-
Notifications
You must be signed in to change notification settings - Fork 19
Getting started with Julia
Sunny is implemented in the Julia programming language, and using the package will involve some Julia programming.
We recommending starting with juliaup. Download it from the Windows store here, or in the Mac/Unix terminal via the command
curl -fsSL https://install.julialang.org | sh
juliaup will provide the most recent Julia compiler at the time of installation. Later, use juliaup update to get new Julia versions as they are released.
Once juliaup is installed, 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.9.2 (2023-07-05)
_/ |\__'_|_|_|\__'_| | Official https://julialang.org/ release
|__/ |
julia>
This is the Julia REPL, short for read-eval-print-loop. You can run code here, for example
julia> exp(pi * im)
-1.0 - 1.2246467991473532e-16imwhich verifies Euler's identity
There are many resources to learn Julia. Quick references are Learn X in Y minutes, where X=Julia and the Julia Cheat-sheet. For more detail, see the official Julia documentation.
You may be familiar with package managers like pip and anaconda for Python. In Julia this functionality is built-in.
At the Julia REPL, press the key ] to enter the "package" mode:
(@v1.9) pkg>
New packages can be added with the add command. To install Sunny, use:
pkg> add Sunny
Many other packages are available, and can be browsed at JuliaHub. To run the Sunny examples, you will need some additional packages. For example, add GLMakie is necessary to enable 3D graphics. If other packages are missing, the error message should be clear ("Package X not found...").
Julia packages, including Sunny, tend to be updated frequently. To get updates, use:
pkg> update
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 REPL, 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 should be 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 recommend the Julia-VSCode development environment. Julia-VSCode enables a notebook-like experience overlayed on top of a full-featured code-editor. Tips for working with Julia VSCode are provided in a later section.
Jupyter notebooks are another option. Integration is possible via the IJulia package. Install with ] add IJulia and, back at the Julia prompt, launch a notebook with using IJulia; notebook(). The Julia/Jupyter integration seems to break whenever Julia is updated. If you see an error about a 'missing kernel', reinstall the Julia kernel files with ] build IJulia.
A number of example notebooks can be found at the SunnyTutorials repo.
The previous sections are fully sufficient for running and modifying the Sunny examples. Eventually, however, you 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 the REPL 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 REPL, 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. Press Enter to launch a Julia REPL, 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 REPL 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.
The Git version control system makes it possible to fearlessly experiment with code modifications. To get the latest development branch of Sunny, use:
pkg> rm Sunny
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.
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. For Julia development, we recommend the VSCode editor with the Git Lens extension (see below).
To learn more about software development best practices, it may be worthwhile to see the lectures for Tim Holy's short course.