"Quantitative Economics with Julia":
About this Repository
This is the source repository for Quantitative Economics with Julia. These instructions required for authoring/editing the textbook and notebooks, and are not necessary for typical usage.
See LICENSE.md
for licensing and copyright information.
Release
For information on releasing a new lecture version, see the docs.
Usage
WSL and VSCode if on Windows
- To get "Ubuntu on Windows" and other linux kernels see instructions.
- For the installation, run it in
Powershell
as an administrator - Hint on copy-paste: One way to paste into a a windows (of any sort) is the
<ctrl-c>
text somewhere else and then, while selected in the terminal at the cursor, to<right click>
the mouse (which pastes). - Use WSL2 and see https://docs.microsoft.com/en-us/windows/wsl/wsl2-kernel for manual installation instructions if required.
- For the installation, run it in
- Install VSCode with remote WSL support on windows
- See VS Code Remote Editing
- VS Code Remote WSL
To open the WSL in VS Code
- Click on the "><" icon on the bottom left hand corner, and open the remote folder in your WSL image (e.g.
~/lecture-source-jl
) - Choose "TERMINAL" to open a WSL terminal, and run any of the above jupinx or make commands.
To get git credentials integrated, in a windows terminal (i.e. not in WSL) run
git config --global credential.helper wincred
Then in a WSL terminal (within VS Code or otherwise),
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-wincred.exe"
(See more details in Sharing Credentials )
Prerequisities
-
Start within your home directory in linux or in a WSL terminal
-
Go to your home directory and make sure key dependencies are installed
cd ~
sudo apt update
sudo apt-get upgrade
sudo apt install make gcc unzip
sudo apt-get update
sudo apt-get install libxt6 libxrender1 libgl1-mesa-glx libqt5widgets5
-
Install Conda
- In the Ubuntu terminal, first install python/etc. tools
wget https://repo.anaconda.com/archive/Anaconda3-2020.07-Linux-x86_64.sh bash Anaconda3-2020.07-Linux-x86_64.sh
- Create a directory
.conda
by runningmkdir ~/.conda
if the warning "Unable to register the environment" shows up
-
The installation will take time. You should:
- accept default paths
- accept licensing terms
- IMPORTANT Manually choose
yes
to have it do theconda init
- Delete the installation file
pip install --upgrade --force-reinstall pyzmq rm Anaconda3-2020.07-Linux-x86_64.sh
-
Install Julia
wget -qO- https://julialang-s3.julialang.org/bin/linux/x64/1.5/julia-1.5.1-linux-x86_64.tar.gz | tar -xzv
- Assuming you installed anaconda in your home directory then,
- Within your home directory modify the
.bashrc
(with VS Code, you can edit directly after connecting to WSL) - Add something like the following:
export PATH=~/anaconda3/bin:~/julia-1.5.1/bin:$PATH
Then, from your terminal, run source .bashrc
to load the changes in the current WSL terminal.
- Install Jupinx and deps
conda upgrade conda
conda install dask distributed
pip install jupinx sphinxcontrib.bibtex jupinx guzzle_sphinx_theme
- Clone the repo to your preferred location (note that WSL+vscode+ssh cloning has bugs, so use https).
On Windows, you want to clone to the WSL setup, not onto your windows drive.
git clone https://github.com/QuantEcon/lecture-source-jl
Precompile the packages used by the lectures before building. To do this:
-
(Optional) If you have a major preexisting julia setup, consider deleting
~/.julia
folder to start fresh. -
In a Julia REPL (i.e.
julia
in terminal if your.bashrc
was edited above), run
] add InstantiateFromURL IJulia; precompile
- Start a new REPL
(If you didn't run the package compilation step, then cd lecture-source-jl/source/rst
)
In the REPL, run
] activate .; instantiate; precompile
This will take a long time to run. You can safely ignore build errors for Electron
Building
There are a few different targets, notably:
-
make website
, which will generate Jupyter, execute notebooks, and then turn that into HTML -
make coverage
, which will do steps (1) and (2) above (with otherwise hidden unit tests), and then generate a report about which notebooks fail. -
make preview
, which will do steps (1), (2), and (3) above and then fire up a local HTTP server. -
jupinx -w --files source/rst/getting_started_julia/julia_by_example.rst
, or any other.rst
for a single file
Workflow for Editing with VS Code
Setup A few useful extensions to install (in WSL if on windows):
- https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer
- See https://github.com/ubcecon/tutorials/blob/master/vscode.md for general extensions as well as Julia and Python
- https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext which requires the python extension
- Note that for the RST extension you will need to have python extension installed. When it asks for the python interpreter, choose
DocUtils
rather than sphinx
- Note that for the RST extension you will need to have python extension installed. When it asks for the python interpreter, choose
One Workflow:
- When you open the project, in the julia terminal go
;cd source/rst
and then] activate .
to ensure you are using the package/manifest. - Edit for the content. With the RST extension, you can get a preview (
Ctrl+K Ctrl+R
, or clicking on the preview buton)- It will have plenty of errors since it doesn't apply jupinx, but will help avoid obvious RST issues.
- When ready to edit the code, use
Ctrl+Shift+P
and typeChange Language Mode
to change it to Julia- With this, you can use
Shift+Enter,Ctrl+Enter
orAlt+Enter
depending on your setup, to run one line of the code at a time in the Julia REPL. If you activated the Package in above, it will use the correct versions of those packages.
- With this, you can use
- When you want to see the results, run in the bash script to build the files
jupinx -w --files source/rst/getting_started_julia/fundamental_types.rst
- And finally, you can watch the file with the LiveServer extension. Go to the
_build/webiste/jupyter_html/getting_started_julia/fundamental_types.htm
etc. in the file explorer, and right click to "Open with LiveServer"
Options and Special Cases
Specifying parallel execution (i.e., make coverage parallel=8
) will use 8 cores instead of 1. This leads to a notable speedup in build times. (There are some zmq
errors that sporadically pop up at very high core counts, i.e. above 8.)
You can build only a few notebooks by jupinx -w --files source/rst/<file>.rst
.