Install

Prerequisites

Basics:

• Python >=3.10

• C or Fortran compiler like gcc, gfortran

• Linear algebra packages BLAS and LAPACK

For parallel runs:

• An MPI library like open-mpi, mpich

• OpenMP

Interfaces to physics codes:

• Check the requirements for GVEC.

Virtual environment

In order to not interfere with existing Python packages, it is highly recommended to install Struphy in a virtual environment:

python -m pip install -U virtualenv

Then:

python -m venv struphy_env
source struphy_env/bin/activate
pip install -U pip

Install and compile

base install

pip install -U struphy
struphy compile --status
struphy compile
struphy -h

more Physics

pip install -U struphy[phys]
struphy compile --status
struphy compile
struphy -h

with MPI

pip install -U struphy[mpi]
struphy compile --status
struphy compile
struphy -h

for developers

git clone git@github.com:struphy-hub/struphy.git
cd struphy
pip install -e .[dev,doc]
struphy compile --status
struphy compile
struphy -h

all options

git clone git@github.com:struphy-hub/struphy.git
cd struphy
pip install -e .[all]
struphy compile --status
struphy compile
struphy -h

In case you encounter problems during install visit Trouble shooting.

Sample environments

Some Linux environments on which Struphy is continuously tested are:

Ubuntu

apt install -y software-properties-common
add-apt-repository -y ppa:deadsnakes/ppa
apt update -y
apt install -y python3-pip
apt install -y python3-venv
apt install -y gfortran gcc
apt install -y liblapack-dev libopenmpi-dev
apt install -y libblas-dev openmpi-bin
apt install -y libomp-dev libomp5
apt install -y git
apt install -y pandoc

OpenSuse

zypper refresh
zypper install -y python311 python311-devel
zypper install -y python311-pip python3-virtualenv
zypper install -y gcc-fortran gcc
zypper install -y lapack-devel openmpi-devel
zypper install -y blas-devel openmpi
zypper install -y libgomp1
zypper install -y git
zypper install -y pandoc
zypper install -y vim
zypper install -y make

AlmaLinux

- yum install -y wget yum-utils make openssl-devel bzip2-devel libffi-devel zlib-devel
- yum update -y
- yum clean all
- yum install -y gcc
- yum install -y gfortran
- yum install -y openmpi openmpi-devel
- yum install -y libgomp
- yum install -y git
- yum install -y environment-modules
- yum install -y sqlite-devel
- wget https://www.python.org/ftp/python/3.10.14/Python-3.10.14.tgz
- tar xzf Python-3.10.14.tgz
- cd Python-3.10.14
- ./configure --with-system-ffi --with-computed-gotos --enable-loadable-sqlite-extensions
- make -j ${nproc}
- make altinstall
- cd ..
- export PATH="/usr/lib64/openmpi/bin:$PATH"
- mv /usr/local/lib/libpython3.10.a libpython3.10.a.bak

Fedora-CentOS-RHEL

dnf install -y wget yum-utils make openssl-devel bzip2-devel libffi-devel zlib-devel
dnf update -y
dnf install -y gcc
dnf install -y gfortran
dnf install -y blas-devel lapack-devel
dnf install -y openmpi openmpi-devel
dnf install -y libgomp
dnf install -y git
dnf install -y environment-modules
dnf install -y python3-mpi4py-openmpi
dnf install -y pandoc
dnf install -y sqlite-devel
wget https://www.python.org/ftp/python/3.10.14/Python-3.10.14.tgz
tar xzf Python-3.10.14.tgz
cd Python-3.10.14
./configure --with-system-ffi --with-computed-gotos --enable-loadable-sqlite-extensions
make -j ${nproc}
make altinstall
cd ..
mv /usr/local/lib/libpython3.10.a libpython3.10.a.bak
module load mpi/openmpi-$(arch)

MacOS

brew update
brew install python3
brew install gcc
brew install openblas
brew install lapack
brew install open-mpi
brew install libomp
brew install git
brew install pandoc

On Windows systems we recommend the use of a virtual machine, for instance the multipass.

Trouble shooting

Install problems

• Make sure that you can pip install -U mpi4py.

• mpi4py>=4.1.0 provides binaries for common platforms. In case of “exotic” platforms you might try pip install -U mpi4py --no-binary mpi4py

• In many cases installing apt install openmpi-devel solves a problem with missing headers.

• On Mac OS, you can try to install the command line tools (160 MB) xcode-select --install.

• Struphy is not supported with Conda; however, in case you insist you might try:

  conda install mpich
  conda install gxx_linux-64
  

Compilation problems

• If compilation fails, struphy compile --delete can help to clean up the environment.

• It can happen that during struphy compile you encounter:

  A module that was compiled using NumPy 1.x cannot be run in
  NumPy 2.2.1 as it may crash. To support both 1.x and 2.x
  versions of NumPy, modules must be compiled with NumPy 2.0.
  Some module may need to rebuild instead e.g. with 'pybind11>=2.12'.
  

  At the moment this error is resolved with:

  pip install numpy==1.26.4
  

Argument completion

Struphy provides console argument completion through the package argcomplete. In order to enable it, make sure to have bash or zsh tab comlpetion enabled. After Struphy installation type:

activate-global-python-argcomplete

and follow the instructions. For activation you need to restart your shell, for instance with exec bash.

Docker

You can run Struphy in a docker container, encapsulated from your host machine. The container is launched from an image which you can download and run immediately, irrespective of your architecture and OS.

Struphy’s Github package registry

User install

To use Struphy via docker, perform the following steps:

1. Install Docker Desktop and start it.

Linux

If you do not want to preface the docker command with sudo, you can create a Unix group called docker and add your user to it. If you are uncomfortable with running sudo, you can run docker in “rootless” mode.

MacOS

It is recommended to read the Mac OS permission requirements. (REMARK: older versions of Mac OS may require older docker desktop versions.)

Windows

It is recommended to read the Windows permission requirements

2. Pull one of the availabale images listed above (< 1 GB in size), for instance:

   docker pull ghcr.io/struphy-hub/struphy/ubuntu-with-reqs:latest
   

3. Run the container:

   docker run -it ghcr.io/struphy-hub/struphy/ubuntu-with-reqs:latest
   

The option -i stands for interactive while -t gives you a terminal.

4. Install Struphy.

Important docker commands

• docker images shows the images available on your computer.

• docker run -d -t --name <container_name> IMAGE runs the container in the background (detached).

• docker exec <container_name> COMMAND gives a bash command to a detached container.

• docker stop <container_name> stops the container.

• docker ps -l lists all containers (also exited/stopped).

• docker restart <container_name> restarts the container in detached mode.

• docker attach <container_name> opens a terminal to a detached container.

• Mirror default Struphy output to ~/<dir> on the host machine:

  docker run -it -v ~/<dir>:<install_path>/io/out gitlab-registry.mpcdf.mpg.de/struphy/struphy/release
  

Docker for devs

Docker is well-suited for developers on any kind of platform. In order to interact with Github you need to mirror your private ssh key into the container with the -v option. For a rsa key this is done with:

docker run -it -v ~/.ssh/id_rsa:/root/.ssh/id_rsa ghcr.io/struphy-hub/struphy/ubuntu-with-reqs:latest

On OS other than Linux ~/.ssh/id_rsa must be replaced with the path to the private rsa key.

You can now install Struphy from source (see above). An installation in editable mode (pip install -e .) can only be done within a virtual environment.

In order to develop inside the container, we recommend to use Visual Studio Code. Once installed, you can click on Extensions (red circle below) and install the Dev Containers extension (green box). Now you will be able to edit container files in VScode by clicking on the green symbol in the bottom-left corner (yellow circle). Choose Attach to a running container ... and select the container in which you want to edit. By doing File - Open Folder... you are able to open any folder from the container.

We recommend to install the following VScode extensions inside the container:

• Python extension

• Python Extensions extension

• Jupyter extension

MPCDF computing clusters

Struphy is periodically tested on the MPCDF HPC facilities. Tests are performed with the available MPCDF images. The modules loaded in these tests can be found in Struphy’s .gitlab-ci.yml.

A common installation looks like this

1. Load necessary modules and create a virtual environment:

   module purge
   module load gcc/14 openmpi/5.0 python-waterboa/2024.06 git pandoc graphviz/8
   pip install -U virtualenv
   python3 -m venv <some_name>
   source <some_name>/bin/activate
   python3 -m pip install --upgrade pip
   

2. Install Struphy by not using the binaries of mpi4py (see install methods from above: pypi_install or source_install):

   pip install -U struphy –no-binary mpi4py

3. When using slurm, include the following lines in your BATCH script:

   source <some_name>/bin/activate
   
   OMPI_MCA_mpi_warn_on_fork=0
   export OMPI_MCA_mpi_warn_on_fork