the9cat/exp repository overview

⁠Using the EXP Docker images

We provide a premade Docker image for Jupyter notebooks and Jupyter lab that contains EXP. No building necessary. More information about using and running EXP can be found here⁠.

The EXP images on Docker Hub are tagged by a short git commit hash. In addition, the latest build is tagged 24 for the current Ubuntu 24.04-based image on the main branch. Development snapshots tagged devel are built occasionally to test features, so they probably will not reflect the current devel. The Ubuntu 22.04-based builds are old legacy releases (tagged 22) and do not contain new features or recent bug fixes. These will be deleted in the near future.

You will automatically get the latest build the first time you run the expbox script. After that first download, your Docker image will not be automatically updated from the Hub. To retrieve an updated image, run the command

docker pull the9cat/exp:tag

to get the the image with a specific tag value. For example, the command

docker pull the9cat/exp:24

will get the most recent build.

This container is designed to be run on a workstation or laptop, rather than a cluster. Rather than custom build HPC libraries for a particular version of OpenMPI and Cuda, we build the Docker container using a standard Ubuntu image and repository support packages.

⁠Usage

⁠Using the Docker image

This directory contains a Bash script called expbox⁠ that runs a Docker container to either (1) start Jupyter Notebook or Jupyter Lab; or (2) start an interactive terminal session that maybe be used to run exp. Try expbox -h to see the available options. This script will automatically download a prebuilt Docker image from the Docker Hub and start the container. Then you should be up and running.

⁠Tips and hints for running EXP in Docker

• The expbox script with no options will start a Jupyter Notebook in your home directory using the first available open networking port beginning with 8888. You can use the -p <port> option to specify a preferred port. To start the notebook in a different directory, add -d <path_to_directory_here>.
• The container name will be expbox_<port>. You can change the prefix name using the -n <name> option.
• The script attempts to find an unused port. If docker has an old stopped container with an inactive port, this strategy may result in the same assigned name. When this happens, simply remove the container using the docker rm expbox_<port> command and try again.
• The terminal session invoked with -t will give you a shell with user privileges and access to the EXP container. You can use this to run exp or any of the standalone routines that are part of the standard EXP build, such as initial condition generators and analysis routines in the EXP utils directory. For example, you can use the session to start MPI simulations inside the container. This is a good way to experiment with and learn EXP by running the examples in the EXP-examples repository⁠.
• You can use the -l option to start a Jupyter Lab session instead of Notebook.
• The container will be automatically stopped when you Control-C the Jupyter server or exit the terminal session. If you are done with your container, you can remove it by running docker rm -f <container>. List your current containers by running docker ps.
• The container contains the full EXP build including MPI and Python + Jupyter packages needed for pyEXP. Preinstalled Python packages include jupyterlab, matplotlib, numpy, scipy, pandas, mpi4py, h5py, pyYAML, astropy, gala, galpy, agama, k3d and ipyparallel.
• Additional packages can be installed by pip install <package> from a JupyterLab terminal or from a Jupyter cell using the !pip install command.