This is the source repository for Quantitative Economics with Julia. These instructions required for authorig/editing the textbook and notebooks, and are not necessary for typical usage.
See LICENSE.md
for licensing and copyright information.
- The latest
quantecon/jupinx
Docker image (see the Containerization section), or:
-
Start within your home directory, using WSL if on Windows. If you're running from the shell, make sure you
run as administrator
. -
Go to your home directory and make sure key dependencies are installed
cd
sudo apt update
sudo apt install make gcc unzip
sudo apt-get update
sudo apt-get install libxt6 libxrender1 libgl1-mesa-glx libqt5widgets5
- Install Conda
wget https://repo.anaconda.com/archive/Anaconda3-2019.07-Linux-x86_64.sh
bash Anaconda3-2019.07-Linux-x86_64.sh
Choose yes
to: "Do you wish the installer to initialize Anaconda3 by running conda init?"
- Install Julia
wget -qO- https://julialang-s3.julialang.org/bin/linux/x64/1.2/julia-1.2.0-linux-x86_64.tar.gz | tar -xzv
- Assuming you installed anaconda in your home directory then,
- Within your home directory,
edit .bashrc
. This opens Vim. Go to the bottom of the file, and typei
to enter insert mode. - Add something like the following:
export PATH=~/anaconda3/bin:~/julia-1.2.0/bin:$PATH
Hit <Esc>
to exit insert mode, and then type :x
to save and exit.
Then, from your terminal, run source .bashrc
to load the changes in the current WSL terminal.
- Install Jupinx and deps
conda upgrade conda
pip install jupinx
pip install sphinxcontrib.bibtex
conda install dask distributed
- Clone the repo to your preferred location (note that WSL+vscode+ssh cloning has bugs, so use https)
git clone https://github.com/QuantEcon/lecture-source-jl
It's recommended that you install and precompile the packages used by the lectures before building. To do this:
-
(Optional) Delete your
~/.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
To accelerate your builds with PackageCompiler
cd lecture-source-jl/util
Then
julia packagecompile.jl
Finally, go to the source/rst
to continue
cd ../source/rst
This will have side-effects for your Julia system (i.e., it will "bake in" a version of Plots.jl) You can re-run the script again whenever the upstream quantecon-notebooks-julia
TOML changes, and reinstall Julia with step 3. to get back to the old sysimg.
Finally, go to the source/rst
to continue
cd ../source/rst
- 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
You may see a lot of warnings during this step if you chose to use PackageCompiler acceleration above. They can be safely ignored.
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
See VS Code Remote Editing and VS Code Remote WSL
In a windows terminal run
git config --global credential.helper wincred
In a WSL terminal,
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 )
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.
- Consider adding a RST Extension
- Consider adding the Live Server extension for viewing the html from
_build/website/jupyter_html
files
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
.
Alternately, you can use the quantecon/jupinx
docker image, which has all these dependencies baked in.
The advantage of a containerized setup is that you can use a siloed, "pre-baked" setup environment to build the lectures.
-
Install Docker.
-
Run
docker pull quantecon/jupinx
. -
In a terminal, cd to this repository, and run
docker run --name quantecon-docker -it -d -v "$(pwd)":/home/jovyan/work quantecon/jupinx
from inside the directory (Linux/macOS). It should spit out a container ID string then exit. Try${PWD}
on Windows, but your mileage may vary.⚠️ In order to guarantee reproducibility, you should either be mounting a fresh clone of this repository, or sanitize things by runninggit clean -xdff
(remove uncommitted/untracked files) andgit reset --hard
(reset to the last git state.) Otherwise, local variance in the mounted files may impact your results. -
In the same terminal (i.e., not inside the container), run
docker exec quantecon-docker bash -c "cd work && make jupyter".
Change it tojupyter-tests
if you want it to output/execute the test blocks. -
Grab a coffee. The Julia side executes in serial, so it takes about an hour (modulo your processor speed.)
-
After it's done, in a terminal run
docker stop quantecon-docker
anddocker rm quantecon-docker
. This will garbage-collect the container, and free the namequantecon-docker
for your next run. If you're having trouble, rundocker rm -f quantecon-docker
to force removal.