-
Notifications
You must be signed in to change notification settings - Fork 19
Getting started with Julia
The Sunny package is accessed through the Julia programming language.
Download juliaup from the Windows store here, or in the Mac/Unix terminal via the command
curl -fsSL https://install.julialang.org | sh
This will provide the latest Julia compiler at the time of installation. Later, use juliaup update to get new Julia versions as they are released.
Now you can execute the julia command from a terminal (or a Windows start-menu shortcut). It should bring up a prompt like this:
_
_ _ _(_)_ | Documentation: https://docs.julialang.org
(_) | (_) (_) |
_ _ _| |_ __ _ | Type "?" for help, "]?" for Pkg help.
| | | | | | |/ _` | |
| | |_| | | | (_| | | Version 1.10.3 (2024-04-30)
_/ |\__'_|_|_|\__'_| | Official https://julialang.org/ release
|__/ |
julia>
This allows for interactive code evaluation, e.g.,
julia> exp(pi * im)
-1.0 - 1.2246467991473532e-16imwhich verifies Euler's identity
Julia code looks a bit like Matlab, but using Julia feels more like a mixture of Python (flexible) and Fortran/C++ (performant). Concise Julia references are Learn X in Y minutes, where X=Julia and the Julia Cheat-sheet. For more detail, see the official Julia documentation.
It should be possible to install all Sunny dependencies without administrator access. Install juliaup into a custom directory with the -p option. For example, on Mac or Linux, a natural location would be .juliainstall within the user's home directory:
curl -fsSL https://install.julialang.org | sh -s -- -p ~/.juliaupinstall
For VSCode on Windows, choose the "User Installer", which is available from the usual download page.
At some institutions, you may need to set environment variables so that Julia can connect to the internet through a proxy.
Instructions for LANL
From the terminal, set the following environment variables:
export http_proxy=http://proxyout.lanl.gov:8080
export https_proxy=http://proxyout.lanl.gov:8080
Consider adding these to your .bashrc or .zshrc configuration file. In a pinch, one can also set environment variables from within a running Julia process:
ENV["http_proxy"] = "http://proxyout.lanl.gov:8080"
ENV["https_proxy"] = "http://proxyout.lanl.gov:8080"
You may be familiar with package managers like pip and anaconda for Python. In Julia this functionality is built in.
At the Julia prompt, press the key ] to enter the "package" mode:
(@v1.10) pkg>
New packages can be added with the add command. To install Sunny, use:
pkg> add Sunny
To enable 3D graphics, additionally install
pkg> add GLMakie
Many other packages are available, and can be browsed at JuliaHub, but these two are enough to get started.
Julia packages, including Sunny, tend to be updated frequently. To get updates, use:
pkg> update
Updates to Sunny will sometimes introduce breaking changes. To downgrade to any previous Sunny release, you can employ an explicit version number, e.g.,
pkg> add [email protected]
Type help to learn more about package mode. Use the [Backspace] key to return to the julia> prompt.
You're now ready to try the Sunny examples! Alternatively, to learn more about Julia, keep reading.
Julia has built-in help. From the prompt, enter ? to enter the help mode, and then enter a function or type name to get documentation. For example:
help?> exp
search: exp exp2 Expr expm1 exp10 export exponent expanduser ExponentialBackOff ldexp frexp nextpow
exp(x)
Compute the natural base exponential of x, in other words e^x.
...
Public functions of Sunny are similarly documented.
Math symbols can be accessed with Latex-like notation. For example, typing \pi and then pressing Tab will produce π. If you see a unicode symbol that you don't know how to type, you can copy-paste it into the help prompt:
help?> ≈
"≈" can be typed by \approx<tab>
...
Julia allows liberal use of unicode to match math notation. Try this at the terminal:
exp(π * im) ≈ -1Although Julia and Matlab have similar surface syntax, there are important differences between the two languages. One crucial thing to know is that simple "for loops" over scalars are encouraged in Julia, and can be used to generate code with C++ or Fortran-like speed. Vectorized style is supported in Julia, but not necessary. Like Matlab and Fortran (but unlike Python or C++), Julia uses 1-based indexing by default, so my_array[1] is the first element of my_array.
Note that Julia, like Python, passes data by reference. For example:
a = [10, 20] # Create a Julia array of integers
b = a # A new reference to the _same_ data
b[1] = 42 # Modify the data shared by `a` and `b`
@assert a == [42, 20]For advanced Julia/Sunny code development, we strongly recommend the Julia-VSCode development environment. Julia-VSCode enables a notebook-like experience overlayed on top of a full-featured code-editor. For example, one can load a Julia source file (*.jl), evaluate individual lines of code using the command [Shift-Enter], and inspect data structures through a graphic interface.
VSCode also has experimental support for Julia + Jupyter notebooks. Just drag the notebook file onto the VSCode icon.
Another way to load Jupyter notebooks is through the more traditional web interface. Julia can launch this interface via the IJulia package. Install with ] add IJulia and, back at the Julia prompt, launch a notebook with using IJulia; notebook(). This Julia/Jupyter integration is somewhat brittle. If you see an error about a 'missing kernel', reinstall the Julia kernel files with ] build IJulia.
In the main Sunny documentation, there is a notebook download link at the top of each example page, e.g., the FeI₂ tutorial.
The previous sections are fully sufficient for running and modifying the Sunny examples. Later, you may want to write more involved Julia programs, or experiment with changes to Sunny itself. This section describes how to set up Julia for code development.
A very important package for Julia code development is Revise:
pkg> add Revise
Revise allows a running Julia process to dynamically pick up changes to package source code (i.e., update function behaviors) without requiring a restart. This is very convenient for rapid iteration -- one can avoid most of the wait times associated with reloading (and recompiling) packages.
Enable Revise by default in every Julia session by following the instructions here.
Revise works great for redefining function definitions, but has some limitations. In particular, Revise does not support redefining struct datatypes. If a struct is modified, then Julia must be restarted.
VSCode is a powerful text editor, and hosts the official Julia development environment.
Much of the power of VSCode comes from extensions. Download these through the Extensions panel, accessible by clicking the appropriate icon on the left of the VSCode window (alternatively, by selecting the View -> Extensions menu item). Search "julia" to find the Julia extension and click Install. A restart of VSCode may then be required. You'll know the Julia extension is working correctly if you can load a .jl file and see syntax highlighting. The blue status bar at the bottom of the window will also print some Julia information. The first launch of the Julia extension may take a while to complete (for example, the "Indexing packages..." step might take a couple minutes). Once the extension has fully loaded, a lot of powerful features become available. To see how it should look, see the Julia for VSCode landing page. Features include "auto-complete" suggestions while typing, pop-up documentation on mouse-hover, an integrated debugger, a plot panel, and more.
The Command Palette can help to discover VSCode functionality. Access it through the View -> Command Palette... menu item (Shift-Command-P on Mac, or Shift-Ctrl-P on Windows). Here you can type keywords to get a list of command suggestions. For example, entering "julia repl" will suggest the Julia: Start REPL command (read-eval-print loop). Press Enter to launch a Julia process, which will appear at the bottom of the VSCode window. This running Julia process integrates with other Julia-VSCode features in a powerful way.
You can interactively evaluate code in any file .jl using the Shift-Enter (Mac), which maps to Julia: Execute Code in REPL and Move. This command will send the Julia expression under the cursor to the running Julia process for evaluation. The result of evaluation will be displayed "inline" in the text editor using a distinct color. Effectively, one gets the power and interactivity of a Jupyter notebook, but with the convenience of working with ordinary .jl files.
Every window in VSCode represents a standalone process. In most cases, you will probably want to do all work entirely in a single VSCode window. To develop a package, it is useful to load the directory containing all source files into the VSCode window (e.g., using File -> Open ...). You can then navigate the files from within VSCode.
It is frequently useful to launch VSCode from the terminal. On Unix systems, run Shell Command: Install 'code' command in PATH using the Command Palette. On Windows systems, code will be available by default. As expected, this will create a shell command code that can be used to quickly launch VSCode. The usage code <filename> and code <directory> is also supported.
It is convenient to make VSCode the default editor for Julia. On a UNIX system, this is possible by adding the line
export JULIA_EDITOR=codeto the shell startup script (e.g. .bashrc or similar). On a Windows system, it seems the best way to configure this environment variable is to add the line ENV["JULIA_EDITOR"]="code.cmd" to the .julia/config/startup.jl file (note the extra .cmd suffix). The file startup.jl will not exist in a fresh Julia install; you can create it by hand.
Once JULIA_EDITOR has been configured, the @edit macro can be used to load source code. For example, running
julia> @edit sort([3, 2, 1])will open the definition of the sort function in the VSCode editor. The @edit macro is defined in the InteractiveUtils module. Browse around these docs to see what else is availabe.
Julia makes it easy to experiment with changes to any package.
pkg> dev Sunny
This will download (more specifically, git clone) the source code for Sunny into the local directory ~/.julia/dev/Sunny/. If you've installed Revise, modifications to the files here will be immediately picked up by a running Julia process. To go back to the release version of Sunny, use add Sunny.
The Git version control system makes it easy to track changes to a codebase. A full introduction to Git is beyond the scope of this document, but here are some basics. Open a terminal in the ~/.julia/dev/Sunny/ directory and type git status. You should see that the directory is free of changes, i.e., "clean". Try modifying some source file. Now git status will show name of the file that was changed. Type git diff to see the specific changes made. You can revert these changes with the command git checkout <filename>. Other useful commands include git add <filenames> and git commit, which will enter changes into the database (repository) of tracked changes (commits). git log will show a history of commits. The commands git pull and git push will download and upload, respectively, from the "origin" repository (in this case, the one hosted on Github). If you actually try this, you will likely find that git push reports an error stating that you don't have write access to the main Sunny repository. The recommend workflow is to fork Sunny on Github. The forked version can be checked out using pkg> dev <GithubURL>. Changes in a fork can be considered for incorporation into Sunny using a pull request.
Instead of entering Git commands in the terminal, it's usually more convenient to use a graphical user interface. VSCode has nice built-in Git support, and more extensions can be added (the Git Graph extension is nice).
To learn more about software development with Julia, Tim Holy created a nice short course on advanced scientific computing.