4. Installation#

4.1. Which installation method?#

ALAMODE can be installed in several ways, which differ in what they install and in how much has to be compiled. If you are unsure, build with conda: it provides everything that the tutorials use.

Purpose

Method

What is installed

Use alm and anphon from Python scripts or notebooks, without compiling anything

Wheels from PyPI (Python API)

The Python modules only

Follow the tutorials and run the command-line programs on a PC or a workstation

Build with conda

The programs alm and anphon, the tool scripts and, optionally, the Python modules

The same, with the environment kept inside the project directory

Build with pixi

As above

Large production runs on a cluster or a supercomputer

Build with native compilers

As above, with the MPI library of the system and optimized linear-algebra backends

The wheels are installed with pip install "alamode-python[openmpi]" (Python 3.11 or later, Linux and macOS on Apple silicon). They do not contain the command-line programs or the tool scripts, which most of the tutorials use. They run with the Open MPI from PyPI and not with the MPI library of a cluster, so build natively there.

Note

The conda-forge packages alamode and alm are older versions and do not match this documentation. Packages of the current version are in preparation; until they are published, use one of the methods above.

4.2. Requirement#

Mandatory requirements#

All of these libraries can be installed easily with conda or pixi.

In addition to the above requirements, users need to install a first-principles package (such as VASP, QUANTUM-ESPRESSO, OpenMX, or xTAPP) or a force-field package (such as LAMMPS) by themselves to compute harmonic and anharmonic force constants.

Optional requirements#

  • Python (>= 3.9), NumPy, h5py, PyYAML, and Matplotlib (ASE and spglib for some scripts)

  • XcrySDen or VMD

Small Python scripts for visualizing phonon dispersion relations, phonon DOS, etc. are provided; they require the Python packages listed above. Additionally, XcrySDen is necessary to visualize the normal-mode directions and animate the normal modes. VMD may be more convenient for making animations, but any other visualization software that supports the XYZ format can be used instead.

4.4. Install using pixi (project-local, reproducible)#

pixi is a fast package manager for the same conda-forge ecosystem used in the conda instructions above. The main difference from conda is that pixi manages a project-local environment: all packages are installed under .pixi/ inside the source tree, together with a lockfile (pixi.lock) that records the exact version of every dependency. Nothing is installed globally, no conda activate is needed, different checkouts or branches can have independent toolchains, and removing the environment is as simple as deleting the .pixi directory.

Step 1. Install pixi#

Follow the official instructions, for example:

% curl -fsSL https://pixi.sh/install.sh | sh

or, with Homebrew on macOS, brew install pixi. Restart the terminal after the installation so that the pixi command is found.

Step 2. Download source and create the environment#

% git clone -b master https://github.com/alamode-code/alamode.git
% cd alamode
% pixi init --import etc/alamode-environment.yml
% pixi add "python=3.12" pip make

pixi init --import seeds the project manifest (pixi.toml) from the same conda environment file used by the conda instructions and the GitHub Actions workflow, so the toolchain (compilers, OpenMPI, Boost, Eigen, CMake, spglib, HDF5 through h5py, NumPy, SciPy, h5py, and PyYAML) is identical. The pixi add line pins Python and adds pip and make, which are used by the build and by the Python wrapper. Both commands solve the dependencies, install them into .pixi/envs/default, and write pixi.lock.

The manifest is created for the platform the command is run on; it is a local file (ignored by git), so users on other platforms simply generate their own.

Step 3. Build by CMake#

Run the usual CMake commands inside the pixi environment, either from an activated shell:

% pixi shell
% cmake -S . -B _build -DCMAKE_BUILD_TYPE=Release
% cmake --build _build -j
% exit

or by prefixing each command with pixi run:

% pixi run 'cmake -S . -B _build -DCMAKE_BUILD_TYPE=Release'
% pixi run 'cmake --build _build -j'

ALAMODE’s CMake setup automatically searches the active environment prefix (pixi sets $CONDA_PREFIX, exactly like conda), so no -DSPGLIB_ROOT or similar options are necessary. The binaries are created in _build/alm/, _build/anphon/, and _build/tools/ with an rpath pointing at the environment’s library directory, so setting $LD_LIBRARY_PATH is not required when they are launched via pixi shell or pixi run.

Step 4. Build and install the Python wrapper (optional)#

The Python interfaces (Python API), the packages alm and anphon, build in the same environment with a single command:

% pixi run 'cd python && pip install .'

The wrapper’s CMake setup likewise picks up spglib, Boost, Eigen, HDF5, and the MPI library that anphon needs from the environment prefix automatically. To build alm only, add -C cmake.define.ALAMODE_PYTHON_ANPHON=OFF to the pip install command. Verify the installation with:

% pixi run python -c 'import alm, anphon; print(alm.__version__)'

or, after an ALM-only build, with:

% pixi run python -c 'import alm; print(alm.__version__)'

Optional: register pixi tasks#

Frequently used commands can be stored in the manifest as tasks:

% pixi task add configure 'cmake -S . -B _build -DCMAKE_BUILD_TYPE=Release'
% pixi task add build 'cmake --build _build -j'
% pixi task add install-python 'cd python && pip install .'

after which the whole build becomes:

% pixi run configure
% pixi run build
% pixi run install-python

Note

pixi.toml, pixi.lock, and the .pixi/ environment directory are local to your checkout and ignored by git. If you want to share a bit-reproducible environment with collaborators, commit pixi.toml and pixi.lock to your own fork.

Note

On macOS, the conda-forge compilers use the system SDK, so the Xcode Command Line Tools must be installed (xcode-select --install). This applies to the conda route as well.

Note

Recent macOS SDKs (macOS 26 “Tahoe” and newer). If your Xcode Command Line Tools provide a very new macOS SDK, the conda-forge linker (cctools/ld64) bundled in the environment may not yet support it, and cmake .. fails during MPI detection even though mpicc works:

-- Could NOT find MPI_C (missing: MPI_C_WORKS)
-- Could NOT find MPI_CXX (missing: MPI_CXX_WORKS)

This is not actually an MPI problem: FindMPI’s test link fails on base libSystem symbols (_puts, ___stack_chk_fail), so any non-trivial link through the conda compiler would fail – MPI is simply the first library checked. Until conda-forge ships a cctools/ld64 that supports the new SDK, configure with Apple’s system Clang while still linking the conda libraries:

% env -u CC -u CXX -u FC cmake .. \
      -DCMAKE_C_COMPILER=/usr/bin/clang \
      -DCMAKE_CXX_COMPILER=/usr/bin/clang++ \
      -DCMAKE_PREFIX_PATH=$CONDA_PREFIX \
      -DHDF5_ROOT=$CONDA_PREFIX

OpenMP still works this way (Apple Clang uses -Xclang -fopenmp with the conda llvm-openmp runtime). For portable binaries, also set -DCMAKE_OSX_DEPLOYMENT_TARGET=<your minimum> and verify the result with otool -L so that only one copy of libc++ / libomp is loaded.