Quick Start (on your local machine)

Docker container scaleuprom_env provides a containerized environment with all the prerequisites for scaleupROM. In order to compile and use scaleupROM in the Docker container, follow these steps:

• Pull scaleuprom_env, with Docker Desktop installed and running

docker pull ghcr.io/llnl/scaleuprom/scaleuprom_env:latest

On apple-chip machines, use:

docker pull ghcr.io/llnl/scaleuprom/scaleuprom_env:arm64

• Clone scaleupROM repository

git clone https://github.com/LLNL/scaleupROM.git

• Launch the Docker container with the cloned repository

docker run -it --volume ./scaleupROM:/home/test/scaleupROM ghcr.io/llnl/scaleuprom/scaleuprom_env:latest

• This will lead to a terminal with the cloned repository mounted at ~/scaleupROM. Compile scaleupROM with the pre-set environment variables

mkdir build
cd build
cmake ~/scaleupROM
make -j 4

Some notes about using the Docker container:

• Any change within the container will not be saved, except those happening in the mounted directory ./scaleupROM.
• Any change in /home/test/scaleupROM in the container is instantaneously reflected into the actual directory ./scaleupROM, and vice versa.

Quartz/Singularity

Quartz has singularity available in the default path (no module required). If you want to run a Docker container built elsewhere, you will need to convert it to a Singularity format first. Before starting, we strongly recommend to work in a directory where you have a enough disk quota (lustre1, lustre2, etc). If in the login node, the container might exceed your disk quota and will not work properly.

Here is an example pulling from GitHub Container Registry.

• Login with your github username/personal access token for SingularityCE.

singularity remote login --username your-github-username docker://ghcr.io

• Build the container image file from GitHub Containter Registry. NOTE: make sure to build it at a directory with enough disk quota.

singularity build scaleuprom_env docker://ghcr.io/llnl/scaleuprom/scaleuprom_env:latest

• Clone scaleupROM repository. NOTE: do this also at the same directory with enough disk quota.

git clone https://github.com/LLNL/scaleupROM.git

• Run container shell with the built container file, with the cloned repository mounted at /home/test/scaleupROM

singularity shell --cleanenv --contain -B ./scaleupROM:/home/test/scaleupROM scaleuprom_env

You can also mount multiple directories as your working directory, for example, for a dir1 and dir2 on LC machine,

singularity shell --cleanenv --contain -B ./scaleupROM:/home/test/scaleupROM,dir1:/home/test/dir1,dir2:/home/test/dir2 scaleuprom_env

• On LC machine, there are some differences when you entered into the container terminal.
  • Unlike your local laptop/desktop, the home directory will be your login node by default, not /home/test.
  • Unlike your local laptop/desktop, you will have write permission only in the mounted directories. In the example above, you have write permission only on /home/test/scaleupROM, /home/test/dir1, /home/test/dir2 (NOT on /home/test itself).

Move to the working directory to start compiling:

cd /home/test/scaleupROM
mkdir build
cmake ..
make -j 4

We can also execute a command instead of opening an interactive shell,

singularity exec --cleanenv --contain -B ./scaleupROM:/home/test/scaleupROM scaleuprom_env ./main -i example_options.yml

If ./main is compiled within the container, you can simply use it as above.