Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Docker setup for OpenFermion and select plugins

This Docker image contains OpenFermion and its available plugins for Cirq, Psi4, and PySCF. Check out Docker's website for a description of what a container image is and why it can be so useful. The Docker-based installation is extremely robust and runs on any operating system, so it is an ideal solution for anyone having difficulty installing OpenFermion (or any of its plugins) using the standard procedure.

What's included?

Setting up Docker for the first time

You first need to install Docker. Once Docker is setup, one can navigate to the folder containing the Dockerfile for building the OpenFermion image (docker/dockerfile) and run

docker build -t openfermion_docker .

where "openfermion_docker" is just an arbitrary name for our docker image. Building the Dockerfile starts from a base image of Ubuntu and then installs OpenFermion, its plugins, and the necessary applications needed for running these programs. This is a fairly involved setup and will take some time (perhaps up to thiry minutes depending on the computer). Once installation has completed, run the image with

docker run -it openfermion_docker

With this command the terminal enters a new environment which emulates Ubuntu with OpenFermion and accessories installed. To transfer files from somewhere on the disk to the Docker container, first run docker ps in a seperate terminal from the one running Docker. This returns a list of running containers, e.g.:

+CONTAINER ID        IMAGE               COMMAND             CREATED
+STATUS              PORTS               NAMES
+3cc87ed4205b        5a67a4d66d05        "/bin/bash"         2 hours ago
+Up 2 hours                              competent_feynman

In this example, the container name is "competent_feynman" (the name is random and generated automatically). Using this name, one can then copy files into the active Docker session from other terminal using:

docker cp [path to file on disk] [container name]:[path in container]

An alternative way of loading files onto the Docker container is through remote repos such as GitHub. Git is installed in the Docker image. After docker run, one could run "git clone ..." etc to pull files remotely into the Docker container.

Running Jupyter notebook with Docker backend

To run Jupyter notebooks (such as our demos) in a browser with a Docker container running as a backend, first check the ip address of the virtual machine by running

docker-machine ip default

where "default" can be replaced by the name of whichever virtual machine whose ip address you want to check. Assuming the Docker image for OpenFermion is built and called openfermion_docker, run the container with an additional -p flag:

docker run -it -p 8888:8888 openfermion_docker

Here the numbers 8888 simply specifies the port number through which the Docker container communicates with the browser. If for some reason this port is not available, any other number in 8000-9000 will do. When the terminal enters the Docker container, run a Jupyter notebook with:

jupyter-notebook --allow-root --no-browser --port 8888 --ip=

where 8888 is the port number used previously for setting up the container. The message returned to the terminal should end with a statement that says something like:

Copy/paste this URL into your browser when you connect for the first time,
to login with a token:

Note the token string 8f70c035fb9b0dbbf160d996f7f341fecf94c9aedc7cfaf7. Open a browser and type in the address line

        [virtual machine ip]:8888

where [virtual machine ip] is extracted from docker-machine ip and 8888 is the port number (or any other port number that one specifies previously). A webpage asking for token string should appear. Use the token string obtained from before to enter Jupyter notebook. If logged in successfully, you should be able to freely navigate through the entire Docker image and launch any Jupyter notebook in the image.