Building Atomistica Python Interface

October 3, 2025 ยท View on GitHub

The following instructions explain how to compile, use and test the Python interface to Atomistica.

Requirements

  • Python 3.8 or greater (Python 3.12+ recommended)
  • NumPy >= 1.21.0 (NumPy 2.x supported)
  • Meson >= 1.1.0
  • meson-python >= 0.15.0
  • A Fortran compiler (gfortran or ifort)
  • A C compiler
  • A C++ compiler
  • LAPACK library

Quick Start

1. Install build dependencies

Using pip:

pip install meson-python meson ninja numpy ase

Or using uv (recommended):

uv pip install meson-python meson ninja numpy ase

2. Build the package

To build a wheel:

python -m build --no-isolation -w

To build and install in development mode:

pip install -e . --no-build-isolation

3. Install the built wheel

pip install dist/atomistica-*.whl

4. Test the installation

Import Atomistica to verify it works:

python -c "import atomistica; print('Successfully imported atomistica')"

5. Run the test suite

cd tests
python run_tests.py

Each test can also be run directly for more diagnostic output:

python bulk_properties.py
python forces_and_virial.py
python rebo2_molecules.py

Build System Details

Atomistica now uses the Meson build system (via meson-python) instead of the deprecated numpy.distutils. The build configuration is defined in:

  • pyproject.toml - Python package metadata and build backend configuration
  • meson.build - Meson build configuration
  • build_helpers/generate_factories.py - Factory code generation script

Compiler Configuration

The build system will automatically detect your compilers. If you need to specify particular compilers, you can set environment variables:

For GNU compilers:

export CC=gcc
export CXX=g++
export FC=gfortran

For Intel compilers:

export CC=icc
export CXX=icpc
export FC=ifort

LAPACK Library

The build system automatically detects LAPACK using pkg-config. If LAPACK is not found automatically, you may need to install it or specify its location:

On Ubuntu/Debian:

sudo apt-get install liblapack-dev

On macOS with Homebrew:

brew install lapack

On Fedora/RHEL:

sudo dnf install lapack-devel

Troubleshooting

Build fails with "command not found: meson"

Install Meson and ninja:

pip install meson ninja

Import error: "symbol not found"

This typically indicates a linking issue. Make sure all dependencies (LAPACK, compiler runtime libraries) are properly installed and accessible.

NumPy compatibility issues

Atomistica supports both NumPy 1.x and 2.x through a compatibility layer. If you encounter NumPy-related errors, try upgrading to NumPy 2.x:

pip install 'numpy>=2.0'

Migration from numpy.distutils

If you previously built Atomistica with setup.py, note that:

  • setup.cfg is no longer used for compiler configuration
  • The build system now uses pyproject.toml and meson.build
  • You no longer need to run python setup.py clean between builds
  • OpenMP and other compiler flags are automatically configured by Meson

Development Workflow

For active development, use the provided rebuild scripts to quickly rebuild and reinstall after making changes:

Using standard pip:

./rebuild.sh

Using uv:

./rebuild-uv.sh

These scripts will:

  1. Build a new wheel
  2. Force-reinstall it
  3. Provide a test command to verify the installation

Note on editable installs: Meson's editable install mode (pip install -e .) can have caching issues. We recommend using the wheel rebuild workflow for development instead.

Advanced Build Options

To pass additional Fortran flags:

FFLAGS="-fopenmp" pip install -e . --no-build-isolation

To enable verbose build output:

python -m build --no-isolation -w -v

For development, you can use meson directly:

meson setup builddir
meson compile -C builddir