.. _install: Install ======= .. _require: 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 .. _sample_envs: Sample environments ------------------- Some Linux/MacOS environments on which Struphy is continuously tested are: .. tab-set:: .. tab-item:: Ubuntu .. code-block:: 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 apt install -y libosmesa6 libosmesa6-dev libegl-mesa0 .. tab-item:: OpenSuse .. code-block:: 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 .. tab-item:: AlmaLinux .. code-block:: - 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 .. tab-item:: Fedora-CentOS-RHEL .. code-block:: 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) .. tab-item:: MacOS .. code-block:: brew update brew install python3 brew install gcc brew install openblas brew install lapack brew install open-mpi brew install pkgconf brew install libomp brew install git brew install pandoc brew install hdf5 brew install netcdf-fortran brew install cmake export "FC=$(which gfortran)" # for gvec export "CC=$(which gcc)" >> # for gvec export "CXX=$(which g++)" >> # for gvec On **Windows systems** we recommend the use of a virtual machine, for instance the :ref:`multipass`. **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_modes: Install and compile ------------------- .. tab-set:: .. tab-item:: base install .. code-block:: pip install -U struphy struphy compile struphy -h .. tab-item:: more Physics .. code-block:: pip install -U struphy[phys] struphy compile struphy -h .. tab-item:: with MPI .. code-block:: pip install -U struphy[mpi] struphy compile struphy -h .. tab-item:: for developers .. code-block:: git clone --recurse-submodules https://github.com/struphy-hub/struphy.git cd struphy pip install -e .[dev] struphy compile struphy -h .. tab-item:: all options .. code-block:: git clone --recurse-submodules https://github.com/struphy-hub/struphy.git cd struphy pip install -e .[all] struphy compile struphy -h In case you encounter problems during install visit :ref:`trouble_shoot`. .. _trouble_shoot: 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 .. _args: 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_install: 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. .. _user_install: User install ^^^^^^^^^^^^ To use Struphy via docker, perform the following steps: 1. `Install Docker Desktop `_ and start it. .. tab-set:: .. tab-item:: 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 `_. .. tab-item:: MacOS It is recommended to read the `Mac OS permission requirements `_. (REMARK: older versions of Mac OS may require `older docker desktop versions `_.) .. tab-item:: Windows It is recommended to read the `Windows permission requirements `_ 2. Pull one of the availabale images, for instance:: docker pull spossann/ubuntu-for-struphy:main 3. Run the container:: docker run -it --rm spossann/ubuntu-for-struphy:main 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 IMAGE`` runs the container in the background (detached). * ``docker exec COMMAND`` gives a bash command to a detached container. * ``docker stop `` stops the container. * ``docker ps -l`` lists all containers (also exited/stopped). * ``docker restart `` restarts the container in detached mode. * ``docker attach `` opens a terminal to a detached container. .. _docker_devs: 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 .. image:: ../pics/vscode_docker_red.png IPP computing clusters ---------------------- Information about the computing clusters at the `Max Planck Institute for Plasma Physics `_ can be found in the `IPP computing cluster Wiki `_. TOK cluster installation ^^^^^^^^^^^^^^^^^^^^^^^^ 1. Load necessary modules:: module purge module load gcc/14 python-waterboa/2025.06 openmpi/5.0 mpi4py/4.1.1 2. Create and source virtual environment:: python3 -m venv struphy-env source struphy-env/bin/activate 3. Install the latest release of Struphy (with mpi):: pip install -U struphy[mpi] struphy compile Or, if you want the source code (with tests, examples and tutorials), install from the current ``devel`` branch:: git clone --recurse-submodules https://github.com/struphy-hub/struphy.git cd struphy pip install .[mpi] struphy compile 4. When using SLURM, make sure to activate the virtual environment in your BATCH script:: source struphy-env/bin/activate MPCDF cluster installation ^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Load necessary modules:: module purge module load gcc/14 python-waterboa/2025.06 openmpi/5.0 mpi4py/4.1.1 2. Create and source virtual environment:: python3 -m venv struphy-env source struphy-env/bin/activate 3. Install Struphy by not using the binaries of `mpi4py` (see install methods from above: :ref:`pypi_install` or :ref:`source_install`): pip install -U struphy --no-binary mpi4py 4. When using SLURM, make sure to activate the virtual environment in your BATCH script:: source struphy-env/bin/activate OMPI_MCA_mpi_warn_on_fork=0 export OMPI_MCA_mpi_warn_on_fork