1. Setting up Your Julia Environment

1.1. Overview

In this lecture we will cover how to get up and running with Julia.

While there are alternative ways to access Julia (e.g. if you have a JupyterHub provided by your university), this section assumes you will install it to your local desktop.

It is not strictly required for running the lectures, but we will strongly encourage installing and using Visual Studio Code (VS Code).

As the most popular and best-supported open-source code editor, it provides a large number of useful features and extensions. We will begin to use it as a primary editor in the tools lecture.

1.2. A Note on Jupyter

Like Python and R, and unlike products such as Matlab and Stata, there is a looser connection between Julia as a programming language and Julia as a specific development environment.

While you will eventually use other editors, there are some advantages to starting with the Jupyter environment while learning Julia.

  • The ability to mix formatted text (including mathematical expressions) and code in a single document.

  • Nicely formatted output including tables, figures, animation, video, etc.

  • Conversion tools to generate PDF slides, static HTML, etc.

We’ll discuss the workflow on these features in the next section

Quick installation for experienced users

If you have already installed Jupyter, Julia, and Git and have experience with these tools, you can

  • Get the notebooks’ repositories with git clone https://github.com/quantecon/lecture-julia.notebooks

  • Open a Jupyter notebook within the downloaded notebooks

  • Install the necessary packages in a Julia REPL with using Pkg; Pkg.instantiate()

At that point, you could directly move on to the julia by example lecture.

However, as we strongly recommend becoming familiar with VS Code as a transition towards using more advanced tools and to support better software engineering workflows, so consider walking through the rest of these instructions.

For those with little to no programming experience (e.g. you have never used a loop or “if” statement) see the list of introductory resources.

1.3. Desktop Installation of Julia and Jupyter

In this section, we will describe the installation of Julia and Jupyter on your desktop.

Tip

On Windows, you probably want to install the new open-source Windows Terminal. See here for installation instructions, and select the option to add the explorer context menu if provided.

It provides a much more modern terminal with better font support for Julia, and with better operating system integration. For example, you can right-click on a folder in the File Explorer and choose Open in Microsoft Terminal to start a terminal in that location. Rather than providing a particular shell directly, it hosts those that are available in your setup (e.g., PowerShell, Git Bash, Ubuntu Bash in WSL).

1.3.1. Installing Jupyter

Anaconda provides an easy to install package of jupyter, python, and many data science tools.

If you have not previously installed Conda or Jupyter, then

  1. Download the binary (https://www.anaconda.com/download/) and follow the installation instructions for your platform.

  2. If given the option for your operating system, let Conda add Python to your PATH environment variables.

Note

While Conda is the easiest way to install jupyter, it is not strictly required. With any python you can install with pip install jupyter. Alternatively you can let IJulia install its own version of Conda by following these instructions, or use the direct support for Jupyter notebooks in VS Code - which does no Python installation at all.

1.3.2. Install Julia

After Conda is installed, you can install Julia.

Note

The semi-official installation method for Windows is to use Juliaup, which makes it easier to upgrade and manage concurrent Julia versions. Support on Mac and Linux is prerelease. See here for a list of commands, such as juliaup update to upgrade to the latest available Julia version after installation, or ways to switch to newer Julia versions after they are released.

  1. Download and install Julia following the Juliaup instructions or manually installing from download page, accepting all default options. That is,

    • Easiest method may be executing winget install julia -s msstore in a Windows terminal, or

    • curl -fsSL https://install.julialang.org | sh on a Mac terminal.

    • We recommend installing manually on Linux.

    • If you have previously installed Julia manually, you will need to uninstall previous versions before switching to Juliaup.

  2. Open Julia, by either

    • Navigating to Julia through your menus or desktop icons (Windows, Mac), or

    • Opening a terminal and type julia (Windows; to set this up on macOS, see here; to set this up on Linux, see here).

    You should now be looking at something like this

    ../_images/julia_term_1.png

    This is called the JULIA REPL (Read-Evaluate-Print-Loop), which we discuss more later.

  3. In the Julia REPL, hit ] to enter package mode and then enter:

    add IJulia
    

    This adds packages for the IJulia kernel which links Julia to Jupyter you previously installed with Anaconda (i.e., allows your browser to run Julia code, manage Julia packages, etc.).

  4. You can exit the julia REPL by hitting backspace to exit the package mode, and then

    exit()
    

Note

As entering of the package mode is so common in these notes, we will denote this with a ] IJulia, etc. On Windows and in Jupyter, you can directly copy this into your terminal, whereas on Linux and macOS you may need to manually enter the package mode.

1.4. Setting up Git and VS Code

A primary benefit of using open-source languages such as Julia, Python, and R is that they can enable far better workflows for both collaboration and reproducible research.

Reproducibility will ensure that you, your future self, your collaborators, and eventually the public will be able to run the exact code with the identical environment with which you provided the results - or even roll back to a snapshot in the past where the results may have been different in order to compare.

We will explore these topics in detail in the lectures on source code control and continuous integration and test-driven development, but it is worth installing and beginning to use these tools immediately.

First, we will install Git, which has become the industry standard open-source version-control tool. This lets you download both the files and the entire version history from a server (e.g. on GitHub) to your desktop.

  1. Install Git and accept the default arguments.

    • If you allow Git to add to your path, then you can run it with the git command, but we will frequently use the built-in VS Code features.

  2. (Optional) Install VS Code for your platform and open it

    • On Windows, during install under Select Additional Tasks, choose all options that begin with Add "Open with Code" action. This lets you open VS Code from inside File Explorer folders directly.

    • While optional, we find the experience with VS Code will be much easier and the transition to more advanced tools will be more seamless.

  3. (Optional) Install the VS Code Julia extension

    • After installation of VS Code, you should be able to choose Install on the webpage of any extensions and it will open on your desktop.

    • Otherwise: run VS Code and open the extensions with <Ctrl+Shift+X> or selecting extensions in the left-hand side of the VS Code window. Then search for Julia in the Marketplace.

    ../_images/vscode_intro_0.png
    • No further configuration should be required, but see here if you have issues.

The VS Code and the VS Code Julia extension will help us better manage environments during our initial setup, and will provide a seamless transition to the more advanced tools.

1.4.1. Command Palette on VS Code

A key feature within VS Code is the Command Palette, which can be accessed with <Ctrl+Shift+P> or View > Command Palette... in the menus.

https://code.visualstudio.com/assets/docs/getstarted/userinterface/commands.png

This is so common that in these notes we denote opening the command palette and searching for a command with things like > Julia: Start REPL , etc.

Tip

You can type partial strings for different commands and it helps you to find features of vscode and its extensions. Furthermore, the command palette remembers your most recent and common commands.

Integrated Terminals within VS Code are a convenient because they are local to that project, detect hypertext links, and provide better fonts.

To launch a terminal, use either (1) <Ctrl+`>, (2) >View: Toggle Terminal with the command palette, or (3) View > Terminal in the menus.

Note

Becoming comfortable with VS Code and tools for source code control/software engineering is an essential step towards ensuring reproducibility. An easy way to begin that process is to start using VS Code to edit LaTeX, and practice managing your .tex files in GitHub rather than dropbox or similar alternatives. While not directly connected to Julia, this familiarity will make everything easier - even for proprietary languages such as Stata and Matlab. See here for instructions on this setup process.

1.5. Downloading the Notebooks

Next, let’s install the QuantEcon lecture notes to our machine and run them (for more details on the tools we’ll use, see our lecture on version control).

While the lecture notes can be cloned within VS Code directly, we will use the command-line to begin the introduction to source control tools.

  1. Choose and create if necessary a convenient parent folder where you would like the notebooks directory

    • The workflow will be easiest if you clone the repo to the default location relative to the home folder for your user.

    • For example, on Windows a good choice might be c:\Users\YOURUSERNAME\Documents\GitHub or simply c:\Users\YOURUSERNAME\Documents. On linux and macOS, your home directory ~ or ~/GitHub.

  2. Open a new terminal for your machine and navigate to the parent folder of where you wish to store the notebooks.

    • On Windows: if using the Windows Terminal you can simply right-click on the directory in the File Explorer and choose to “Open in Microsoft Terminal” or, alternatively “Git Bash Here” to use the terminal provided by Git. On macOS, see here for a discussion of different approaches.

  3. Execute the following code in the terminal to download the entire suite of notebooks associated with these lectures.

    git clone https://github.com/quantecon/lecture-julia.notebooks
    

    This will download the repository with the notebooks into the directory lecture-julia.notebooks within your working directory.

  4. Then, cd to that location in your terminal

    cd lecture-julia.notebooks
    
  5. Finally, you can open this directory from your terminal with the following

    code .
    

Which should provide a screen such as

../_images/vscode_intro_1.png

Cloning Directly from VS Code

Alternatively, if you are already a user of Visual Studio Code, you can clone within VS Code by using the > Git: Clone command from the command palette. See the lectures on tools and source code control for more details.

1.6. Installing Packages

After you have the notebooks available, as described in the previous section, we can install the required packages for plotting, benchmarking, and statistics.

For this, we will use the integrated terminal in VS Code.

Recall that you can start this directly from the command palette with <Ctrl+Shift+P> then typing part of the > Julia: Start REPL command.

../_images/vscode_intro_2.png
  1. Start a REPL; it may do an initial compilation of packages in the background, but will then look something like

    ../_images/vscode_intro_3.png
  2. Next type ] to enter the package mode, which should indicate that the local project is activated by changing the cursor to (quantecon-notebooks-julia) pkg>.

  3. Type instantiate to install all of the packages required for these notes.

    ../_images/vscode_intro_4.png

This process will take several minutes to download and compile all of the files used by the lectures.

Attention

If the cursor is instead (@v1.8) pkg> then you may not have started the integrated terminal in the correct location, or you used an external REPL. Assuming that you are in the correct location, if you type activate . in the package mode, the cursor should change to (quantecon-notebooks-julia) pkg> as it activates this project file.

One benefit of using the integrated REPL is that it will set important options for launching Julia (e.g. the number of threads) and activate the local project files (i.e. the Project.toml file in the notebooks directory) automatically. If you use an external REPL, you will need to set these manually. Here you would want to run the REPL with julia --project --threads auto to tell Julia to set the number of threads equal to your local machine’s number of cores, and to activate the existing project. See here for more details.

1.7. Running JupyterLab

You can start Jupyter within any directory by executing the following in a terminal

jupyter lab

This runs a process giving Jupyter permission to access this directory, but not its parents. This is especially convenient to do in VS Code since we have already navigated to this directory:

  1. If the Julia REPL is still open, create a new terminal by clicking on the + button on the terminal pane and create a new terminal appropriate for your operating system. Close the Julia REPL if you wish.

    ../_images/vscode_intro_5.png
    • As before, if the terminal pane is not available, use <Ctrl+`> or >View: Toggle Terminal to see the pane.

    • You can close the Julia REPL if you wish, or create multiple terminals in this interface

  2. Within the new terminal, execute jupyter lab. This should run in the background in this terminal, with output such as

    ../_images/vscode_intro_6.png

The process should launch a webpage on your desktop, which may look like

../_images/jupyterlab_first.png

If it does not start automatically, use the link at the bottom of the output in the terminal (which should show with Follow link (ctrl + click).

Proceed to the next section on Jupyter to explore this interface and start writing code.

1.8. Refreshing the Notebooks after Modification

As you work through the notebooks, you may wish to reset these to the most recent version on the server.

  1. To see this, modify one of the notebooks in Jupyter, and then go back to VS Code, which should now highlight on the left hand side that one or more modified files have been modified.

  2. Choose the highlighted “Source Control” pane, or use <Ctrl+Shift+G>; then it will summarize all of the modified files.

  3. To revert back to the versions you previously downloaded, right click on “Changes” and then choose Discard All Changes:

../_images/vscode_intro_7.png

Additionally, if the notebooks themselves are modified as the lecture notes evolve, you can first discard any changes, and then either use > Git: Pull command or click on the arrow next to “main” on the bottom left of the screen to download the latest versions. Here “main” refers to the main branch of the repo where the latest versions are hosted.

If the Project.toml or Manifest.toml files are modified, then after reverting you will want to redo the instantiation step to ensure you have the correct versions.

We will explore these sorts of features, and how to use them for your own projects, in the source code control lecture.

1.9. Interacting with Julia

Next, we’ll start examining different features of the Julia and Jupyter environments.

While we emphasize a local installation of Jupyter, other alternatives exist.

For example,

  • Some universities may have JupyterHub installations available - which provide a hosted Jupyter environment. However, it would require the hub to have explicit Julia support.

  • VS Code has rapidly progressing support for Jupyter using an existing Jupyter installation.

  • The combination of the new VS Code Jupyter and VS Code Julia extensions supports Jupyter notebooks without even a fragile Conda/python installation

  • Online services such as JuliaHub provide a tailored experience for Julia. Be warned, however, that Colab and others are only designed for Python, and adding Julia requires a great deal of effort.

1.10. Using Jupyter

1.10.1. Getting Started

Note

The easiest way to get started with these notebooks is to follow the cloning instructions earlier.

Launch jupyter lab and navigate to this notebook(i.e. getting_started_julia/getting_started.ipynb )

See here for the previous instructions on launching Jupyter Lab.

Your web browser should open to a page that looks something like this

../_images/starting_nb_julia.png

The page you are looking at is called the “dashboard”.

If you click on “Julia 1.x.x” under “Notebook” you should have the option to start a Julia notebook.

Here’s what your Julia notebook should look like

../_images/nb2_julia.png

The notebook displays an active cell, into which you can type Julia commands.

1.10.2. Notebook Basics

Notice that in the previous figure the cell is surrounded by a blue border.

This means that the cell is selected, and double-clicking will place it in edit mode.

As a result, you can type in Julia code and it will appear in the cell.

When you’re ready to execute these commands, hit Shift-Enter

../_images/nb3_julia.png

1.10.2.2. Switching modes

  • To switch to command mode from edit mode, hit the Esc key.

  • To switch to edit mode from command mode, hit Enter or click in a cell.

The modal behavior of the Jupyter notebook is a little tricky at first but very efficient when you get used to it.

1.10.2.3. Plots

Run the following cell

using Plots
plot(sin, -2π, 2π, label="sin(x)")
../_images/getting_started_1_0.svg

You’ll see something like this (although the style of plot depends on your installation)

../_images/nb4_julia.png

Attention

If this code fails to work because the Plots package is missing, then either you

  1. did not install the packages in the previous lecture

    • You should go back and follow the install the packages instructions, or just call using Pkg; Pkg.instantiate() in a new cell.

  2. downloaded or moved this notebook rather than cloning the notebook repository. In that case, it does not have the associated Project.toml file local to it.

    • Consider cloning the notebook repository instead.

    • If you would prefer not, then you can manually install packages as you need them. For example, in this case you could type ] add Plots into a code cell in the notebook or into your Julia REPL.

1.10.3. Working with the Notebook

Let’s go over some more Jupyter notebook features — enough so that we can press ahead with programming.

1.10.3.1. Tab Completion

Tab completion in Jupyter makes it easy to find Julia commands and functions available.

For example if you type rep and hit the tab key you’ll get a list of all commands that start with rep

../_images/nb5_julia.png

1.10.3.2. Getting Help

To get help on the Julia function such as repeat, enter ? repeat.

Documentation should now appear in the browser

../_images/repeatexample.png

1.10.3.3. Other Content

In addition to executing code, the Jupyter notebook allows you to embed text, equations, figures and even videos in the page.

For example, here we enter a mixture of plain text and LaTeX instead of code

../_images/nb6_julia.png

Next we Esc to enter command mode and then type m to indicate that we are writing Markdown, a mark-up language similar to (but simpler than) LaTeX.

(You can also use your mouse to select Markdown from the Code drop-down box just below the list of menu items)

Now we Shift + Enter to produce this

../_images/nb7_julia.png

1.10.3.4. Inserting Unicode (e.g. Greek letters)

Julia supports the use of unicode characters such as α and β in your code.

Unicode characters can be typed quickly in Jupyter using the tab key.

Try creating a new code cell and typing \alpha, then hitting the tab key on your keyboard.

There are other operators with a mathematical notation. For example, the LinearAlgebra package has a dot function as identical to the latex \cdot.

using LinearAlgebra
x = [1, 2]
y = [3, 4]
@show dot(x, y)
@show x⋅y;
dot(x, y) = 11
x ⋅ y = 11

1.10.3.5. Shell Commands

You can execute shell commands (system commands) in Jupyter by prepending a semicolon.

For example, ; ls will execute the UNIX style shell command ls, which — at least for UNIX style operating systems — lists the contents of the current working directory.

These shell commands are handled by your default system shell and hence are platform specific.

1.10.3.6. Package Operations

You can execute package operations in the notebook by prepending a ].

For example, ] st will give the status of installed packages in the current environment.

Note: Cells where you use ; and ] must not have any other instructions in them (i.e., they should be one-liners).

1.10.4. Sharing Notebooks

Notebook files are just text files structured in JSON and typically end with .ipynb.

A notebook can easily be saved and shared between users — you just need to pass around the ipynb file.

To open an existing ipynb file, import it from the dashboard (the first browser page that opens when you start Jupyter notebook) and run the cells or edit as discussed above.

The Jupyter organization has a site for sharing notebooks called nbviewer which provides a static HTML representations of notebooks.

QuantEcon also hosts the QuantEcon Notes website, where you can upload and share your notebooks with other economists and the QuantEcon community.