2  Install and Build OPALX

Run the ready-made CPU image with Docker, or follow the source-build instructions below for a custom CPU or GPU build.

2.1 Run with Docker

The public image ghcr.io/opalx-project/opalx:cpu contains OPALX and its runtime dependencies, including MPI. You do not need compilers or a local MPI installation. It uses the CPU/OpenMP backend; GPU images are not provided. Docker automatically selects the Linux x86-64 (amd64) or ARM64 image for your machine, including Intel and Apple silicon Macs.

2.1.1 Set up Docker on a Mac

  1. Install Docker Desktop for Mac, choosing the Apple silicon or Intel download to match your Mac.
  2. Open Docker Desktop and wait until it is running.
  3. In Terminal, check Docker and download the OPALX image:
docker run --rm hello-world
docker pull ghcr.io/opalx-project/opalx:cpu
docker run --rm ghcr.io/opalx-project/opalx:cpu --help

The public image can be pulled without a GitHub account or docker login. Docker Desktop runs the Linux container on macOS. Allocate enough memory and CPUs in Docker Desktop for your simulation.

Check that the image matches your Mac:

docker run --rm --entrypoint uname ghcr.io/opalx-project/opalx:cpu -m

Expect aarch64 on Apple silicon and x86_64 on Intel. If an Apple silicon Mac reports x86_64, check whether DOCKER_DEFAULT_PLATFORM is set to linux/amd64; this selects an Intel image that runs under slower emulation. Unset that variable with unset DOCKER_DEFAULT_PLATFORM, then pull the image again to select the native architecture.

2.1.2 Run a first example

With Docker running, clone the regression inputs into a working directory of your choice and run the small drift example. This step also requires Git (check with git --version). On a Mac, xcode-select --install installs the Command Line Tools, including Git, if needed.

git clone --depth=1 https://github.com/OPALX-project/regression-tests-x.git
cd regression-tests-x/RegressionTests/Drift-1-fromfile

docker run --rm \
  --user "$(id -u):$(id -g)" \
  -e OMP_NUM_THREADS=1 \
  -v "$PWD:/data" \
  ghcr.io/opalx-project/opalx:cpu Drift-1-fromfile.in --info 2

The checkout contains both Drift-1-fromfile.in and its required particle distribution, distr-gauss.txt. The run writes results, including Drift-1-fromfile.stat, beside the input. Check that OPALX exits successfully and the statistics file is present. This is a first-run check; it does not automatically compare numerical results with the regression references. See Run a First Simulation for more about the example and its outputs.

2.1.3 Run your own simulation

In Terminal, change to the directory containing your input file, replacing /path/to/simulation and case.in with your own directory and filename:

cd /path/to/simulation

docker run --rm \
  --user "$(id -u):$(id -g)" \
  -e OMP_NUM_THREADS=4 \
  -v "$PWD:/data" \
  ghcr.io/opalx-project/opalx:cpu case.in --info 2

The mounted directory is /data inside the container and is its working directory. Output files appear beside your input and belong to your macOS user. Distribution files, field maps, and other referenced files must be inside this directory or its subdirectories; use paths relative to the input working directory. --rm removes the container after it exits and keeps the files written into the mounted directory.

This command uses one MPI rank and four OpenMP threads. Adjust OMP_NUM_THREADS to the CPUs available to Docker.

For multiple MPI ranks, set OPALX_NP and increase shared memory, for example:

docker run --rm \
  --user "$(id -u):$(id -g)" \
  -e OPALX_NP=2 -e OMP_NUM_THREADS=2 \
  --shm-size=1g \
  -v "$PWD:/data" \
  ghcr.io/opalx-project/opalx:cpu case.in --info 2

This requests two ranks with two threads each. Choose shared memory and total memory to suit the case. Random particle generation draws samples per thread, so changing the thread count can change the particle sample.

2.1.4 Image versions

The cpu and latest tags follow successful builds of master; they are moving development versions, rather than the OPALX 1.0.0 release used in the source-build instructions below. Run docker pull again to obtain an update. Record the image digest printed by docker pull for reproducible runs, and use ghcr.io/opalx-project/opalx@sha256:<digest> in place of the tagged image to select that exact image. Replace <digest> with the recorded hash.

Images published by the updated Docker build workflow set org.opencontainers.image.version to the OPALX version instead of inheriting Ubuntu’s 24.04. Older images retain their existing labels. A development image and a release image can both report 1.0.0; the version label alone does not identify a release. Use the tag and revision to distinguish them, and the digest to select an exact image.

Check the executable’s version and Git revision with:

docker run --rm ghcr.io/opalx-project/opalx:cpu --version-full --info 5

The Docker README describes commit and release tags, local image builds, and the development container.

2.1.5 Docker development environment

The development image supplies GCC, gfortran, Open MPI and CMake. Build it from a current source checkout containing docker/:

git clone --branch master https://github.com/OPALX-project/OPALX.git opalx-development
cd opalx-development
docker build -f docker/Dockerfile --target dev -t opalx-dev .
docker/dev-shell.sh

The source stays on the host and is mounted at /work. Inside the container:

cmake -S /work -B /work/build_openmp \
  -DCMAKE_BUILD_TYPE=Release \
  -DPLATFORMS=OPENMP \
  -DOPALX_ENABLE_UNIT_TESTS=ON
cmake --build /work/build_openmp -j 4
ctest --test-dir /work/build_openmp --output-on-failure

Run CMake inside the container so cached paths refer to its filesystem. Dependency downloads during configuration require network access. Source and build files persist in the mounted directory. The shell uses the host user and group IDs.

OPALX_WORK selects a different host directory to mount at /work; adjust source/build paths if mounting a parent directory. OPALX_DEV_IMAGE selects a different development-image name. The locally built development image initially contains the toolchain; the published cpu image contains the ready-to-run executable. The release-tag checkout in the source-build section below predates docker/; use the separate current checkout above.

2.2 Source-build prerequisites

OPALX uses CMake and Kokkos to select the execution backend. The following toolchain is recommended for current development and production builds:

Dependency Recommended version Notes
GCC 13 Use the same host compiler throughout the dependency stack.
Fortran compiler e.g. gfortran from GCC 13 Required to build the fetched BLAS/LAPACK dependency.
OpenMPI 4 or 5 Either major version is suitable; use the MPI wrappers from the selected installation.
CUDA 12.9 Required only for NVIDIA GPU builds. Match the architecture setting to the target GPU.
CMake 3.24 or newer OPALX currently declares CMake 3.24 as its minimum version.
Git Recent release Used to clone OPALX and fetched dependencies.

These are recommended versions, not a promise that every other combination is unsupported. Accelerator builds need the matching CUDA or HIP toolchain. Other core dependencies are obtained by the build unless installed-dependency options are selected.

On a module-based system, a typical environment is:

module load gcc/13
module load openmpi/5  # openmpi/4 is also supported
module load cuda/12.9  # CUDA builds only

Module names vary between clusters. After loading them, check that gcc, mpicxx, and nvcc resolve to the intended installations before configuring the build.

2.3 Clone the source

git clone --branch OPALX-1.0.0 --depth 1 https://github.com/OPALX-project/OPALX.git
cd OPALX

This checks out the OPALX 1.0.0 release, whose Git tag is OPALX-1.0.0, in detached-HEAD state. All build commands below use this checkout. To confirm the selected release, run:

git describe --tags --exact-match
# Expected: OPALX-1.0.0

For ongoing development, clone the default branch separately rather than reusing a release build directory.

2.4 Configure a CPU build

For a portable single-threaded backend:

cmake -S . -B build_serial \
  -DCMAKE_BUILD_TYPE=Release \
  -DPLATFORMS=SERIAL
cmake --build build_serial -j 8

For OpenMP, use a separate build directory:

cmake -S . -B build_openmp \
  -DCMAKE_BUILD_TYPE=Release \
  -DPLATFORMS=OPENMP
cmake --build build_openmp -j 8

2.5 Configure a GPU build

An NVIDIA A100 build uses the CUDA backend and Ampere architecture:

cmake -S . -B build_cuda \
  -DCMAKE_BUILD_TYPE=Release \
  -DPLATFORMS=CUDA \
  -DARCH=AMPERE80
cmake --build build_cuda -j 8

Select the architecture that matches the target GPU. HIP builds use -DPLATFORMS=HIP and the corresponding AMD architecture.

2.6 Enable tests

To build and run the unit tests for the serial backend:

cmake -S . -B build_serial \
  -DCMAKE_BUILD_TYPE=Release \
  -DPLATFORMS=SERIAL \
  -DOPALX_ENABLE_UNIT_TESTS=ON
cmake --build build_serial -j 8
ctest --test-dir build_serial --output-on-failure

For a small end-to-end check of the executable, run the regression input in Run a First Simulation. Unit tests and simulation regression checks serve different purposes.

See Build, Test, and CI for the full developer workflow and Configuration Reference for the maintained build options.