Installation guide¶

If you only want to open and analyze a database from an existing SODA run, follow Output analysis to set up the standalone analyzer. A full SODA installation is not needed.

This guide covers Linux workstations and HPC clusters. Ubuntu 24.04 LTS is our reference development environment. See Linux support for other environments.

If your choices cannot share a build, you will need multiple independent installations. The guide provides separate steps for each one.

Generate your installation guide¶

The interactive selector needs JavaScript. Open the Installer reference under Advanced information below for a link to the full guide and manual installation examples.

1. What will you run?

Choose one or more workflows. Each workflow can use several potentials or calculators.

APE: Automatic process exploration (Lai et al., 2025).
EZGA (Lombardi et al., 2026).
NEBScape (Jung et al., 2026).
AKMC: Adaptive kinetic Monte Carlo (Xu and Henkelman, 2008).

2. Where will it run?

Choose the hardware you will use. EAM and GAP recipes use CPUs, including on machines that also have GPUs.

3. What do you plan to use with each workflow?

Check all potentials or calculators you plan to use with each workflow. Compatible choices share an installation; different recipes receive separate build instructions. Each run selects its calculator in its configuration.

EAM (Daw et al., 1993).
GAP (Bartók et al., 2010).
MACE (Batatia et al., 2022).
Fairchem (Shuaibi et al., FAIRChem software).

See Citing SODA for full references and citations for the specific model or parameter set you use.

4. Name your installations

Choose names you will recognize later, such as my-mace-build. The commands use each name as --prefix and create matching folders in venv/, submodules/build/, and build/. Use a different name for each installation, with up to 80 letters, numbers, dots, underscores or hyphens; start with a letter or number.

Compilation settings

Build the C++ test targets I have already loaded my cluster modules Parallel build jobs

How many parts of the software to compile at the same time during installation. This does not change how many CPUs or GPUs your simulations use. Keep this within the number of CPUs your site allows for installation.

Advanced information¶

Linux support: tested environment and installer coverage

Use this reference to choose an installation route and distinguish the tested development environment from configurations that still need validation.

Environment	Current installation route and validation scope
Ubuntu 24.04 LTS on x86_64	Our tested workstation development reference. This does not establish that every calculator, GPU, or driver combination has been tested.
Other Ubuntu releases and Ubuntu-derived distributions	`install.ubuntu` accepts Ubuntu and distributions identifying Ubuntu in `ID_LIKE`, including Linux Mint. They must pass the prerequisite checks and need separate build and runtime validation.
Other Linux distributions	`install.hpc` accepts a prepared Linux toolchain without a distribution/version restriction. It also works on workstations; a module system is optional. Prepare dependencies through your distribution or site, then follow the manual installer guide.
Other CPU architectures	The Ubuntu entry point and pinned PyTorch recipes require x86_64. Other architectures need separate recipe validation; passing OS detection is insufficient.
Native Windows or macOS	These installation scripts require Linux.

The shared prerequisites are matching GCC/G++/GFortran 12+ and MPI, CMake 3.28–3.x, Python 3.10–3.12 with development headers, and compatible HDF5, BLAS/LAPACK, and OpenMP libraries. GPU recipes additionally require a compatible device, driver, CUDA/ROCm toolkit, and PyTorch stack. With CUDA 12.1, the current generalized installers specifically require GCC/G++/GFortran 12; see Dependency versions.

The selector’s workstation package commands are for Ubuntu and its derivatives. Other distributions need their own package setup; these commands do not provide automatic distribution-specific package installation.

The installation validation guide explains the difference between prerequisite checks, a completed build, and a successful simulation. The Ubuntu 22.04/24.04 CI matrix checks CPU prerequisites; it does not establish full application or GPU compatibility.

Dependency versions: package pins, toolchain choices, and validation

Use this reference to assess a different compiler or GPU toolkit. The generated guide lists exact Python package pins; the toolkit paths and module commands are suggested system settings, not an exact toolkit pin or a validated full stack.

For the current native NVIDIA MACE recipe, PyTorch is pinned to 2.4.0+cu121. With CUDA 12.1, both generalized installers require GCC/G++/GFortran 12. They use the selected SODA C++ compiler as CUDA’s host compiler: the installer requires GCC 12 or newer, CUDA 12.1 accepts GCC no newer than 12, and the installer also requires the Fortran and C++ compiler major versions to match.

This is a constraint of the current installer, not a requirement that MACE always use GCC 12. The backup Ubuntu script selects GCC/G++ 11 specifically for LAMMPS-MACE while allowing a newer compiler for SODA. The generalized installers do not yet support that separate compiler selection or the backup’s SODA_HOST_CC / SODA_HOST_CXX overrides.

CUDA / host compiler	What this combination establishes
CUDA 12.1 / GCC, G++, GFortran 12, with matching MPI	The compiler combination required by the current generalized installers for CUDA 12.1. Matches the pinned PyTorch wheel’s CUDA version; full build and runtime validation are still needed.
CUDA 12.6 / GCC, G++, GFortran 13, with matching MPI	The Ubuntu guide’s candidate, based on NVIDIA’s Ubuntu 24.04/GCC 13 support. Its CUDA minor version differs from PyTorch’s; the full MACE combination is unvalidated.
CUDA 12.1 / separate GCC/G++ 11 for LAMMPS-MACE	Used by the backup Ubuntu script and recorded in the older local build. This separate compiler setup is currently unavailable in the generalized installers.

CUDA 12.1’s supported environments do not include Ubuntu 24.04 or GCC 13. Changing only the compiler therefore does not establish OS support. CUDA 12.6’s support table includes Ubuntu 24.04/GCC 13, but does not validate our PyTorch/LAMMPS combination.

The installer accepts the pinned PyTorch build’s toolkit version or a newer minor within the same major, and reports any minor-version difference. A matching version is not itself a runtime test. For native MACE, LAMMPS uses the LibTorch libraries from the installation’s PyTorch package and Torch’s C++ ABI flags. Its Kokkos wrapper uses the detected toolkit; modules.rc restores that toolkit and the host compiler. Use the same environment when preparing the MACE model.

Fairchem has its own newer PyTorch/CUDA/ROCm pins. The Viper-based MACE example also combines different minor versions (ROCm 6.3 toolkit and a rocm6.1 wheel). These combinations require validation on the intended hardware. See the GPU dependency reference for the full matching requirements.

Ubuntu setup: custom tools and libraries

Use this reference when you need to replace the default Ubuntu tools or reuse an existing library installation.

Tool selection: compilers, CMake and Python default to /usr/bin. New installations try available stable Open MPI versions from newest to oldest, selecting one that passes compilation and a short two-process local communication test. Explicit MPICC, MPICXX or MPIEXEC settings disable automatic fallback. Resuming the same prefix retains its recorded MPI choice; changing MPI requires a new prefix. The generated modules.rc restores the selected launcher and libraries. These MPI probes also run for workstation --check-only and --dry-run, so local MPI execution must be permitted. Explicit CC, CXX, FC, and CMAKE override their defaults. --python selects both the installer and virtual environment’s Python and takes precedence over SODA_INSTALL_PYTHON.
Reusing CUDA 12.1: changing CUDA_HOME alone leaves Ubuntu 24.04’s default GCC 13 selected, which CUDA 12.1 rejects. Select GCC/G++/GFortran 12 together in ubuntu.env, and keep the MPI wrappers aligned. The GPU dependency reference contains the explicit override example.
Custom libraries: set HDF5_ROOT and H5CC in ubuntu.env to use an existing HDF5 installation for both SODA and h5py. Intel MKL is optional; the default recipe uses Ubuntu’s BLAS/LAPACK libraries.
Earlier Ubuntu instructions: the original positional commands remain in install_backup.ubuntu. The current installer uses Ubuntu’s HDF5 instead of downloading HDF5 2.1.1. It also uses one compiler toolchain instead of the backup’s separate GCC/G++ 11 selection for LAMMPS-MACE.

See the Ubuntu installer reference for the full defaults and override examples.

HPC module stack: compatibility checks and their limits

Use this reference to assess an alternative site toolchain or understand what the prerequisite check establishes.

Supported compilers: the generalized installer checks for a matching GNU C/C++/Fortran toolchain and Open MPI or MPICH-compatible wrappers. It does not include recipes for vendor compilers such as Intel or NVIDIA HPC compilers.
What is checked: temporary programs are compiled and linked with MPI, HDF5, LAPACK, OpenMP, and Python. GPU builds also compile a CUDA or ROCm source file. The report identifies the toolkit and pinned PyTorch GPU build, including minor-version differences. It does not install PyTorch or test its LibTorch link with LAMMPS; that happens during dependency installation.
What still needs a runtime check: these probes do not launch MPI ranks or execute GPU kernels. Passing them does not establish driver compatibility, GPU execution, or communication between compute nodes.

For a comparison of the Raven and Viper module sets, see the module stack reference. The prerequisites and limits also cover package mirrors, existing dependency sources, and network requirements.

Installer reference: logs, recovery, and manual use

Use this reference to diagnose an installation or adjust how the installer runs.

Logs: full command output and progress records are saved as install.log and install-state.json in submodules/build/<name>/. Add --verbose to an installer command to stream its output to the terminal as well. A status message every 30 seconds confirms that the current command is still running; it is not a completion estimate.
Repeating stages: --no-resume repeats the requested stages in a compatible installation. Changing the dependency target, toolchain, or an incompatible installer recipe requires a new --prefix; changing SODA’s compilation settings does not. --no-resume does not bypass dependency compatibility checks.
Inspecting commands: add --dry-run to an installer command to check prerequisites and print the planned commands without installing dependencies. The supplied environment file is still sourced and compilation probes still run.
Rebuilding: install.hpc --prefix <name> --stage build (or install.ubuntu) restores the saved target, environment, build type, and test setting. Repeating the original options is unnecessary. Build-only runs can reuse dependencies after installer-file changes when the target, toolchain, versions, and source pins still match; dependency installation retains the strict recipe check.
Developer builds: generated guides use Release for running simulations. Change --build-type to debug or relwithdebinfo on the build-stage command to reconfigure the same installation. Add --with-tests to enable test targets, or --without-tests to disable them. Missing cpptrace/Catch2/pytest tools are prepared in this stage; the scientific dependencies are reused. Compilation settings are reused for named build-only runs; other invocations default to Release without tests. Native dependencies stay in Release mode. Use separate names when you need to retain both SODA binaries simultaneously.

To follow the log from another shell, set SODA_ROOT to your checkout and replace my-build with your installation name:

tail -f "$SODA_ROOT/submodules/build/my-build/install.log"

The full installer guide provides manual installation examples and the complete option reference. For failures or interrupted builds, see installation sequence and recovery.

Installation guide¶

Generate your installation guide¶

Your installation guide

Advanced information¶