mtzgroup/terachem repository overview

⁠Quick Reference

• Maintained by: Colton Hicks and the Martinez Group⁠
• Where to get help: the Docker Community Forums⁠, the Docker Community Slack⁠, or Stack Overflow⁠
• Where to file issues:: https://github.com/mtzgroup/terachem/issues⁠
• Supported architectures: x86_64

⁠Dockerfile links

Images are tagging using the following syntax: mtzgroup/terachem:{version}-{cuda_compilation_version}-{sm_x}-{sm_y}... where version is the version of TeraChem, {cuda_compilation_version} is the version of CUDA used to compile TeraChem, and each {sm_x} field is filled with the corresponding NVIDIA architecture⁠.

• Dockerfile Link⁠

⁠What is TeraChem?

TeraChem is a GPU accelerated package for Quantum Chemistry. Our focus is speed and we achieve this through redesign of modern algorithms for stream processors like the CUDA enabled GPU architectures from NVIDIA.

⁠How to use this image

⁠Basic Configuration

In order to run GPU accelerated docker images you must have the nvidia-container-runtime installed. You can follow the instructions here⁠ to install it.

The TeraChem image writes all scratch data to /scratch inside the container. In order to avoid writing to the container's writable layer (which is slow, increases the size of the container, and means the data is not available outside of the container's lifecycle), you should mount a volume or bind mount to the container's /scratch directory. I'll show you how to do this below. For more information about ways to store your data see Docker's documentation on managing data in Docker⁠ and deeper dives on bind mounts⁠ and volumes⁠. A volume would be the preferred data storage mechanism for most use cases.

This image does not contain a licence. This means you will be limited to TeraChem's unlicensed usage limits by default. For unrestricted TeraChem usage mount a licence to /terachem/license.key.

⁠Server Mode

docker run -d --rm -v terachem-scratch:/scratch -v /path/to/license.key:/terachem/license.key -p 11111:11111 --gpus all --name terachem mtzgroup/terachem:1.9-2021.02-dev-arch-sm_37-sm_52-sm_61-sm_70

Breaking down this command:

• docker run -d runs the container in daemon mode (in the background). You can switch this for -it if you'd like to have the container's outputs connected to your terminal
• --rm this tells docker to delete the container after it exits
• -v terachem-scratch:/scratch this tells docker to create (if it doesn't already exist) and mount a volume called terachem-scratch to the container's /scratch directory. All data created by this container will be available inside this volume even after the container is deleted. You can see volumes on your machine by running docker volume ls.
• -v /path/to/license.key:/terachem/license.key this optional command mounts a TeraChem licence for unrestricted use
• -p 11111:11111 maps port 11111 inside the container to 11111 on your host system. The server will be available on your host system at 127.0.0.1:11111
• --gpus all this critical command tells docker to use the nvidia-container-runtime which can access GPUs. See here⁠ for more details.
• --name terachem give the container the name terachem. If you want to see logs from your container run docker logs terachem -f.
• mtzgroup/terachem:{tag_you_want} this tells docker to which image to run. Since the command terachem -s 11111 is the default CMD for the image, this command will run be default.

⁠Command Line Mode

See "Server Mode" above for more details about what each option in these commands below mean.

To interact with the container on your terminal:

docker run -it --rm -v terachem-scratch:/scratch -v /path/to/license.key:/terachem/license.key --gpus all --name terachem mtzgroup/terachem:1.9-2021.02-dev-arch-sm_37-sm_52-sm_61-sm_70 bash

From inside the container you can run terachem and interact with the environment as you would on a typical server.

To run a job in the background write your tc.in and geom.xyz files to a directory (or better yet a volume!) that you will mount to the docker image, then run:

docker run -d --rm -v path/to/input/files:/scratch -v /path/to/license.key:/terachem/license.key --gpus all --user $(id -u):$(id -g) --name terachem mtzgroup/terachem:1.9-2021.02-dev-arch-sm_37-sm_52-sm_61-sm_70 terachem path/to/tc.in

Note that /path/to/input/files is the path on your local machine to your inputs files and that /path/to/tc.in is the path inside your docker container which will be relative to /scratch. For example, if your tc.in and geom.xyz files were in your local directory like this: path/to/input/files/job1/tc.in then if you used the code above your command would be terachem /job1/tc.in since path/to/input/files is mounted to /scratch.

This will kick off a TeraChem job with the container running in the background (-d) and will write all files to the directory where your tc.in and geom.xyz file are written. If you have mounted your host filesystem (bind mount) as I have done above instead of a volume to your docker container, note that docker runs as root so files written to your filesystem will be owned by root (one great reason to go with a docker volume instead!). However, if you add the --user $(id -u):$(id -g) optioned noted above docker will write to your filesystem as your user rather than root. For more details see this brief tutorial⁠.

A final (basic) way you may want to use this container is:

docker run -it --rm --gpus all -u $uid:$gid -v .:/scratch mtzgroup/terachem:1.9-2023.09-dev-1.4-jammy-cuda-11.8.0-sm52-sm61-sm70-sm80-sm89 bash

This will mount the current working directory on your host machine (possibly containing tc.in and geom.xyz files) into /scratch (the default working directory in the container), and make all file read/writes happen with your default user, rather than root. This is probably the easiest command to use to try out the container and have it write output files back to your local system.