Gen Quick Start
This repository contains Jupyter notebooks that contain tutorials on specific features and/or applications of Gen. The notebooks walk you through programs that use Gen. Some notebooks also include exercises that expect you to write code or fill in written responses.
These notebooks assume some familiarity with the Julia programming language.
For reference on Gen see:
The easiest way to run the notebooks is using Docker.
If on Linux, make sure to run the post-installation steps so that you can run the docker commands smoothly without needing sudo access.
If on Mac, run the Docker application, and make sure that you see the Docker whale icon in your menu bar (when you click on the icon it should say "Docker Desktop is running").
Next, clone this Github repository using https and enter that directory:
$ git clone https://github.com/probcomp/gen-quickstart.git $ cd gen-quickstart
Next, build the image using the following command:
$ docker build -t gen:v0 .
Then run the image using:
$ docker run -it --name gen -p 8080:8080 -p 8090:8090 -p 8091:8091 -p 8092:8092 gen:v0
localhost:8080 in your browser and open the 'Gen Quick Start.ipynb' notebook.
All the changes made to the notebooks will be saved in your docker container.
To stop the image, run
To restart the image and resume your work, run:
$ docker start -ia gen
These notebooks have been tested on Ubuntu Linux 16.04 and Mac OS X. To install Gen natively on your machine, please view the commands taken in the Dockerfile, which is based on Ubuntu Linux 16.04. The steps in the Dockerfile can be reproduced on your machine but will require slight variations depending on your local development setup.
Below is a brief documentation of the steps taken in the Dockerfile.
Install global dependencies from Ubuntu APT.
$ apt-get update -qq \ && apt-get install -qq -y \ hdf5-tools \ python3-dev \ python3-tk \ wget \ virtualenv \ zlib1g-dev
Create a Python virtual environment for use with the examples (make sure to create a virtual environment in a writable directory), and insatll the following packages into this environment with
- jupyter: used to run the notebook sever (required)
- matplotlib: used in many of the notebooks for basic plotting (required)
- tensorflow: (recommended)
$ virtualenv -p /usr/bin/python3 /venv $ . /venv/bin/activate && pip install jupyter matplotlib tensorflow
Download and install Julia. Note that we create a soft-link of the
/usr/bin/. You should create a soft link to the executable to any writable directory that is on your PATH.
$ wget https://julialang-s3.julialang.org/bin/linux/x64/1.0/julia-1.0.3-linux-x86_64.tar.gz $ tar -xzv < julia-1.0.3-linux-x86_64.tar.gz $ ln -s /julia-1.0.3/bin/julia /usr/bin/julia
JULIA_PROJECTenvironment variable to
/path/to/gen-quickstart/(i.e. path where this repository was cloned). Make that
JULIA_PROJECTis set correctly on your machine whenever working with Gen or with these examples.
$ export JULIA_PROJECT=/path/to/gen-quickstart
Build and precompile the Julia packages. The main libraries that are being built are PyCall and IJulia. We make sure that
python(version 3 only) and
jupyterare in our PATH and pointing to the right Python environment and Jupyter installation, respectively, by activating the Python virtual environment we created. Since we have activated the virtual environment in the commands below, the
build()command uses the version of Python and Jupyter in the virtual environment. (For more information on how PyCall and IJulia find the right versions of
jupyter, please see the respective documentation of those packages.)
$ . /venv/bin/activate && julia -e 'using Pkg; Pkg.build()' $ . /venv/bin/activate && julia -e 'using Pkg; Pkg.API.precompile()'
Run the Jupyter server! The notebooks should be available in your browser at
localhost:8080. Remember to make sure that your
JULIA_PROJECTis correctly set (step 4) before running this command again.
$ . /venv/bin/activate && jupyter notebook \ --ip='0.0.0.0' \ --port=8080 \ --no-browser \ --NotebookApp.token= \ --allow-root \ --NotebookApp.iopub_data_rate_limit=-1
Running the Notebooks
Start by opening the 'Gen Quick Start.ipynb' notebook, which contains links to the other notebooks in the intended order.