Skip to content

Latest commit

 

History

History
130 lines (81 loc) · 3.86 KB

python-sscha Installation Guide.md

File metadata and controls

130 lines (81 loc) · 3.86 KB

python-sscha Installation Guide

This guide provides step-by-step instructions to compile and install the sscha library. The project uses the Meson build system to compile C and Fortran extensions for Python.

Recommended Installation: Conda / Mamba

The easiest and most reproducible way to install python-sscha is by using a Conda environment. We strongly recommend using micromamba or mamba as they are significantly faster. This method installs all the required compilers, libraries, and Python packages inside an isolated environment, avoiding the need to modify your base system.

Step 1: Create and Activate the Environment

  1. Install Conda/Mamba. If you don't have it, we recommend installing micromamba.

  2. Create the environment. Open your terminal and run the following command. It will create a new environment named sscha with all the necessary dependencies, including CellConstructor.

micromamba create -n sscha python=3.12 gfortran libblas lapack openmpi openmpi-mpicc pkg-config pip numpy scipy spglib=2.2 cellconstructor matplotlib ase

  • Python Version: We use Python 3.12. Newer versions are not yet supported due to a dependency constraint from spglib <= 2.2.

  • pkg-config: This package is essential. Meson requires it to correctly detect the BLAS and LAPACK libraries provided by Conda.

  1. Activate the environment. You must activate the environment before proceeding.
micromamba activate sscha

Step 2: Clone the Repository (if not done)

If you don't have the source code locally, clone it from the repository.

git clone https://github.com/SSCHAcode/python-sscha.git
cd python-sscha

Step 3: Install python-sscha

With the environment active, install the package using pip. pip will automatically use Meson to compile and install the project.

pip install .

The installation is now complete! You can verify it by running the tests or importing the modules in Python.

Advanced Installation: Manual Configuration

This section is for users who cannot use Conda or need to configure the build with specific compilers or options.

Prerequisites

  • A C and Fortran compiler.

  • Python 3.12 and pip.

  • Ninja and Meson: pip install meson ninja.

  • System libraries for BLAS, LAPACK, and MPI.

  • All Python dependencies, including CellConstructor, must be installed in your environment.

Method 1: Using Environment Variables

You can specify compilers by setting the CC (C compiler) and FC (Fortran compiler) environment variables before running pip.

# Example using compilers from a specific toolchain
export CC=/usr/local/bin/gcc-11
export FC=/usr/local/bin/gfortran-11

# Install the project
pip install .

Method 2: Using a Meson Cross File

For a reproducible setup, define your compilers in a file (e.g., native-toolchain.ini).

Example native-toolchain.ini:

[binaries]
c = '/path/to/my/custom/gcc'
fortran = '/path/to/my/custom/gfortran'

Then, install by passing this file to Meson via pip:

pip install . --config-settings=meson-args="--native-file=native-toolchain.ini"

Build Options

You can pass options to Meson to customize the build.

  • Create a debug build:
pip install . --config-settings=meson-args="-Dbuildtype=debug"
  • Enable Intel MKL (requires MKL to be installed and findable by your system):
pip install . --config-settings=meson-args="-Duse_mkl=true"
  • Combine multiple options:
pip install . --config-settings=meson-args="-Dbuildtype=debug,-Duse_mkl=true"

Reconfiguring a Build

If you need to change build options, it is best to perform a clean installation.

# 1. Uninstall the package
pip uninstall python-sscha

# 2. (Optional but recommended) Remove the build directory
rm -rf build/

# 3. Reinstall with the new options
pip install . --config-settings=meson-args="-Dnew_option=value"