Build on Local Machine

This page provides the source-build installation path for SurfATT. This path is recommended when you need maximum control over compiler versions, MPI stack, and optimization flags.

Typical use cases:

Performance tuning on HPC clusters.
Reproducible builds with pinned toolchains.
Debugging and developer workflows.

Requirements

Library	Minimum Version	Recommended Version	Role
CMake	≥ 3.18	≥ 3.25	Build system (required)
C++ compiler	GCC ≥ 13 / Clang ≥ 14	GCC ≥ 14 / Clang ≥ 17	C++17 (required)
Fortran compiler	GFortran ≥ 10	GFortran ≥ 12	Fortran-based routines and toolchain compatibility (required)
MPI	≥ 3.0	Open MPI ≥ 4.0	Parallelism with shared-memory windows (required)
HDF5	≥ 1.10	≥ 1.14	Model I/O (required)
Eigen3	≥ 3.4	≥ 3.4.0	Linear algebra (required)
yaml-cpp	≥ 0.6	≥ 0.8	Parameter file parsing (bundled fallback)
spdlog	≥ 1.5	≥ 1.15	Logging (bundled fallback)

1. Install Dependencies on Local Machine

Conda / Mamba

Use this option for isolated and reproducible environments, especially for laptops, shared servers, and CI workflows. It avoids conflicts with system packages.

Create the environment


conda create -n surfatt -c conda-forge -y

Activate the environment


conda activate surfatt

Install dependencies


conda install -c conda-forge -y cxx-compiler fortran-compiler cmake openmpi hdf5 eigen yaml-cpp spdlog

Ubuntu / Debian

Native Linux setups on Ubuntu or Debian where you want direct access to system compilers and libraries. This is usually the fastest path on local workstations.


sudo apt update
sudo apt install -y \
  build-essential cmake pkg-config git \
  gfortran \
  openmpi-bin libopenmpi-dev \
  libhdf5-dev libeigen3-dev \
  libyaml-cpp-dev libspdlog-dev

RHEL / Fedora / CentOS

Use this on Fedora, AlmaLinux, CentOS Stream, or RHEL-based systems. Package names may vary slightly by distro release, so adjust if a package is unavailable.


sudo dnf install -y \
  gcc gcc-c++ gcc-gfortran make cmake pkgconf-pkg-config git \
  openmpi openmpi-devel \
  hdf5 hdf5-devel eigen3-devel \
  yaml-cpp-devel spdlog-devel

After installation, ensure the MPI environment is properly set up by loading the appropriate module.


# Optional: load MPI environment path if needed
module load mpi

macOS (Homebrew)

Best for Apple Silicon and Intel Macs using Homebrew-managed toolchains. Homebrew gcc includes gfortran, which satisfies the Fortran requirement.


brew update
brew install gcc cmake open-mpi hdf5 eigen yaml-cpp spdlog

2. Clone Source Code

Clone the official repository and enter the project directory. If you are on a shared system, use your own workspace path to avoid permission issues.


git clone https://github.com/TomoATT/SurfATT.git
cd SurfATT

3. Build SurfATT

Create a clean build directory, then configure and compile from there. If dependencies are installed in non-default locations, add the corresponding CMake prefix/path options during configuration.


mkdir -p build && cd build

Then configure and compile:


cmake ..
make -j