Using Docker container

Quick Start (on your local machine)

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

• Pull librom_env, with Docker Desktop installed and running

  docker pull ghcr.io/llnl/librom/librom_env:latest
  

  • Note: if using an ARM based system, such as Apple M1/M2 chip Macbooks, an ARM image is available using the arm64 tag:

    docker pull ghcr.io/llnl/librom/librom_env:arm64
    

• Clone libROM repository

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

• Launch the Docker container with the cloned repository

  docker run -it --volume ./libROM:/home/test/libROM ghcr.io/llnl/librom/librom_env:latest
  

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

  mkdir build
  cd build
  cmake ~/libROM -DCMAKE_TOOLCHAIN_FILE=${TOOLCHAIN_FILE} -DCMAKE_BUILD_TYPE=${BUILD_TYPE} -DUSE_MFEM=${USE_MFEM} -DMFEM_USE_GSLIB=${MFEM_USE_GSLIB}
  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 ./libROM.
• Any change in /home/test/libROM in the container is instantaneously reflected into the actual directory ./libROM, and vice versa.

Using the Docker container locally with VSCode

To facilitate working with the Docker container in VSCode, you can add a custom terminal that will automatically run the Docker container to your workspace settings. First, create a bash script that will run on terminal start up:

#!/bin/bash
#source ~/.bashrc

# Check if the Docker daemon is running and start it if not.
DOCKER_PS=$(docker ps 2>&1)
if [[ $DOCKER_PS == *"Cannot connect"* ]]; then
  echo "Docker daemon is not running. Starting Docker..."
  open --background -a Docker
  sleep 5 # Wait for Docker to start up
  echo "Docker started."
else
  echo "Docker daemon is running."
fi

# Run Docker container
echo "Opening LibROM container"
HOSTDIR=$(pwd)
docker run -it --volume $HOSTDIR:/home/test/libROM ghcr.io/llnl/librom/librom_env:latest

This script will start Docker if it's not running and then run the LibROM container. Save the script in a file as init_bash.sh in the LibROM main directory and add the following entry to "terminal.integrated.profiles.osx" in your workspace settings.

"librom_bash": {
				"path": "/bin/bash",
				"args": [
					"-l",
					"init_bash.sh"
				],
				"icon": "terminal-bash",
				"label": "LibROM"
			},

Now you should have an option to open the custom terminal in the VSCode terminal dropdown window.

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 librom_env docker://ghcr.io/llnl/librom/librom_env:latest

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

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

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

singularity shell --cleanenv --contain -B ./libROM:/home/test/libROM librom_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 ./libROM:/home/test/libROM,dir1:/home/test/dir1,dir2:/home/test/dir2 librom_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/libROM, /home/test/dir1, /home/test/dir2 (NOT on /home/test itself).

Move to the working directory to start compiling:

cd /home/test/libROM
mkdir build
cmake .. -DCMAKE_TOOLCHAIN_FILE=${TOOLCHAIN_FILE} -DCMAKE_BUILD_TYPE=${BUILD_TYPE} -DUSE_MFEM=${USE_MFEM} -DMFEM_USE_GSLIB=${MFEM_USE_GSLIB}
make -j 4

Some details

• Machine architecture: Linux-x86_64
• From: ubuntu:22.04
• Dependencies:
  • cmake-3.22.1
  • hypre-2.20.0
  • parmetis-4.0.3
  • gslib-1.0.7
  • mfem: latest verified commit on May 02, 2023
  • googletest-v1.12.1: the last release that supports c++11
• Environmental variables preset for libROM cmake:
  • TOOLCHAIN_FILE=/env/dependencies/librom_env.cmake
  • BUILD_TYPE=Optimized
  • USE_MFEM=On
  • MFEM_USE_GSLIB=On
• Miscellaneous packages
  • Debugging tools: valgrind, lldb, gdb
  • Python packages: numpy, scipy, argparse, tables, PyYAML, h5py, pybind11, pytest, mpi4py