Exploring EXP using Docker

Note

  • You will need Docker installed to use it!

  • Instructions for installing Docker on MacOS, Linux and Windows systems can be found here.

  • We also suggest learning a bit about Docker, if you have not used it previously. There are many available introductions to Docker, like this one.

As described in the top of the FAQ, our Docker container provides a quick way of trying EXP without compiling the software on your own. To get started, download the expbox and make it executable. Running the script will retrieve the latest EXP docker image, build a docker container, and run Jupyter by default. You now have a fully working EXP installation; proceed to the pyEXP tutorials!

If you would like to try the EXP n-body code, first change to a working directory of your choice that contains the configuration and supporting files. For example, let’s suppose that you’ve copied the files from DiskHalo to your current working directory. You can run this example with the Docker container in two steps:

  1. Run the container with the command: expbox -t -d `pwd`. The -t flag starts an interactive terminal. The -d <dir> flag uses <dir> as the working directory. You can omit this move to any desired working directory in your home tree.

  2. Run the simulation with the command mpirun exp.

A few notes:

  • When the container starts running, you will see standard shell prompt: bash-5.1$. At this point, you can look around the system, browse files, etc. It’s a slimmed down Ubuntu Linux image.

  • EXP in the Docker container is installed in /usr/local/EXP.

  • OpenMPI detects the available number of cores and uses that by default. You can supply the -np X flag to mpirun to explicitly request X processes.

  • Use the -h flag to expbox for a list of additional options. Take a quick look at this README for more details.

  • The containers will continue to exist until you stop or remove them. For example, if you started a container named expbox_8889, you can stop and remove it using docker rm -f expbox_8889. Use docker ps to see your containers.