# Installation guide If you only want to open and analyze a database from an existing SODA run, follow [Output analysis](tutorials/analyzer.md#install-the-analyzer-only) 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 {ref}`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 ```{installation-selector} ``` ## Advanced information (linux-support)=
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 {repo}`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 {ref}`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 {repo}`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)=
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](https://docs.nvidia.com/cuda/archive/12.1.0/cuda-installation-guide-linux/index.html) 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](https://docs.nvidia.com/cuda/archive/12.6.3/cuda-installation-guide-linux/index.html) 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 {repo}`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 {repo}`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 {repo}`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 {repo}`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 {repo}`module stack reference `. The {repo}`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//`. 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 --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: ```bash tail -f "$SODA_ROOT/submodules/build/my-build/install.log" ``` The {repo}`full installer guide ` provides manual installation examples and the complete option reference. For failures or interrupted builds, see {repo}`installation sequence and recovery `.