/*! @page pag_install Installation
\section sec_install Installation

\subsection sec_general General Remarks

The central repository for development and PSI-internal projects is at https://gitea.psi.ch/pearl/pmsco,
the public repository at https://gitea.psi.ch/pearl-public/pmsco.
For their own developments, users should clone the repository.
Changes to common code should be submitted via pull requests.
Scientific projects should be maintained in a separate directory tree, cf. @ref sec_project.

The program code of PMSCO and its external programs is written in Python, C++ and Fortran.
The code will run in any recent Linux environment on a workstation or in a virtual machine.
For optimization jobs with parallel execution, a workstation with at least 4 processor cores
or cluster with 20-50 available processor cores is recommended.
The program requires about 2 GB of RAM per process.

The recommended IDE is [PyCharm (community edition)](https://www.jetbrains.com/pycharm).
[Spyder](https://docs.spyder-ide.org/index.html) is a good alternative with a focus on scientific data.
The documentation in [Doxygen](https://www.doxygen.nl/index.html) format is part of the source code.
The Doxygen compiler can generate documentation in HTML.

@attention Due to rapidly evolving computing environments
some of the installation instructions on this page may be outdated or incompatible with certain environments.


\subsection sec_requirements Requirements

Please note that in some environments (particularly shared high-performance machines)
it may be important to choose specific compiler and library versions that are tailored to the hardware platform.
In order to maintain backward compatibility with older installations,
code that requires new versions of compilers and libraries should be introduced carefully.

The following basic tools and libraries are required:

- GCC (C, C++, Fortran) >= 4.8
- BLAS
- LAPACK
- OpenMPI >= 1.10
- Git

Most of these requirements are available from the Linux distribution.
For the Python environment,
the [uv](https://docs.astral.sh/uv/) package and environment manager is recommended.
It can be installed by non-privileged users.
Other package managers like pip and conda may work as well but are not described here.

The following tools are required to compile the documentation.
They are not needed in calculations.

- doxygen
- doxypypy
- graphviz
- Java runtime environment (JRE)
- [plantUML](https://plantuml.com)

\subsection sec_install_instructions Instructions

Installation instructions are given for Ubuntu 24.04.
On managed HPC clusters use the compilers and libraries recommended by the administrator
(often provided by a module system).

\subsubsection sec_install_ubuntu Installation on Ubuntu

The following instructions install the necessary dependencies on Ubuntu, Debian or related distributions.

@code{.sh}
sudo apt update

sudo apt install \
binutils \
build-essential \
doxygen \
g++ \
gcc \
gfortran \
git \
graphviz \
libblas-dev \
liblapack-dev \
libopenmpi-dev \
nano \
openmpi-bin \
openmpi-common \
python3 \
python3-venv \
sqlite3 \
wget
@endcode

In addition, download and install [uv](https://docs.astral.sh/uv/).
PSI users should configure uv to use PSI's PyPI package cache (cf. documentation on the intranet).


\subsubsection sec_install_extra Additional Applications

For working with the code and data, some other applications are recommended.
The PyCharm IDE can be installed from the Ubuntu software center.
The following commands install other useful helper applications:

@code{.sh}
sudo apt install \
avogadro \
gitg \
meld
@endcode

To compile the documentation install the following tools.
The basic documentation is in HTML format and can be opened in any internet browser.

@code{.sh}
sudo apt install \
doxygen \
graphviz \
default-jre

wget -O plantuml.jar https://sourceforge.net/projects/plantuml/files/plantuml.jar/download
sudo mkdir /opt/plantuml/
sudo mv plantuml.jar /opt/plantuml/
echo "export PLANTUML_JAR_PATH=/opt/plantuml/plantuml.jar" | sudo tee /etc/profile.d/pmsco-env.sh
@endcode


\subsection sec_distro Download PMSCO Source Code

Clone or download the code from one of these repository addresses:

| Repository | Access |
| --- | --- |
| https://gitea.psi.ch/pearl/pmsco | PSI internal  |
| https://gitea.psi.ch/pearl-public/pmsco-public | Public |

@code{.sh}
cd ~
git clone {repo-address see above} pmsco
cd pmsco
git checkout master
@endcode

These instructions download the base package of PMSCO.
The public repository does not contain external programs (EDAC, PHAGEN, LOESS).
You need to obtain the source code for these programs from their respective owners,
copy them to the respective subprojects directories and
apply the patches included in the PMSCO distribution.
Please respect the respective license terms and acknowledge the use of the codes.


\subsection sec_install_environment Set up the Python Environment

The following instructions are for the [uv](https://docs.astral.sh/uv/) package manager.
For other package managers, the pyproject.toml and requirements.txt files list the necessary dependencies.

\subsubsection sec_install_uv Virtual Environment with uv

By default, uv creates the virtual environment automatically in a `.venv` folder inside the source directory tree.
In this case, no explicit setup is necessary, and pmsco can be called by:

~~~~~~{.sh}
uv run pmsco -h
~~~~~~

On some platforms, however, it may be necessary to separate the environment from the code,
e.g. because of limited storage space or quota in the home directory.
In this case, create the environment as follows:

~~~~~~{.sh}
cd ~
mkdir envs
cd envs
uv venv --clear my_pmsco_env
~~~~~~

The `--clear` option resets an existing environment to empty.
To activate this environment, call this command once in every terminal:

~~~~~~{.sh}
source ~/envs/my_pmsco_env/bin/activate
~~~~~~


\subsubsection sec_normal_install Installing PMSCO

to install PMSCO and all dependencies into the active environment,
run the following commands in the top-level PMSCO directory (where `pyproject.toml` is located).
The commands compile the Fortran and C++ code of the calculation programs using the
[Meson build system](https://mesonbuild.com/meson-python/index.html)
and install the binaries and Python code in the site-packages folder of the active Python environment.

~~~~~~{.sh}
uv sync --active
~~~~~~

To use the default `.venv` environment, omit the `--active` option (also in the uv commands shown further below).
Now, run the unit tests to check the installation:

~~~~~~{.sh}
uv run --active nosetests
~~~~~~

And check the help page:

~~~~~~{.sh}
uv run --active pmsco -h
~~~~~~

In the explicit environment, these commands can alternatively be called directly:

~~~~~~{.sh}
nosetests
pmsco -h
~~~~~~

The PMSCO packages are now accessible in Python import statements.
Verify it by opening a Python shell and entering:

~~~~~~{.py}
import pmsco.project
dir(pmsco.project)
~~~~~~

Note: By default, uv installs the Python code in editable mode.
Changes in the PMSCO source tree are visible as soon as you start a new Python interpreter.
This does not apply to the subpackages, however.
After modifying the subpackages, you need to clear and re-sync the environment.


\subsection sec_test Test project

Run the twoatom project to check that everything is installed correctly:

~~~~~~{.py}
cd ~
mkdir -p work/twoatom
cd work/twoatom
nice python -m pmsco -r {path-to-pmsco}/projects/twoatom/twoatom-hemi.json
~~~~~~

You should get a number of result files whose names start with `twoatom0001` in `~/work/twoatom/`,
including a hologram plot of the modulation function.

To learn more about running PMSCO, see @ref pag_run.

\subsection sec_install_projects Installing Namespace Packages

Instructions on how to set up your own projects as namespace packages are given in section \ref sec_project.
To install them into the pmsco namespace, call uv with the `--inexact` option.
Without `--inexact`, uv would remove the previously installed packages (including PMSCO).

~~~~~~{.sh}
uv sync --active --inexact
~~~~~~


\subsection sec_install_singularity Installation in a Singularity container

Singularity containers are currently unmaintained.

The PMSCO source includes an install script for the [Singularity](https://sylabs.io/singularity/) container system
under `extras/singularity`.
To get started with Singularity,
download it from [sylabs.io](https://www.sylabs.io/singularity/) and install it according to their instructions.
On Windows, Singularity can be installed in a virtual machine using the [Vagrant](https://www.vagrantup.com/)
script included under `extras/vagrant`.

After installing Singularity,
check out PMSCO as explained in the @ref sec_compile section:

@code{.sh}
cd ~
mkdir containers
cd containers
git clone git@gitea.psi.ch:pearl-public/pmsco-public.git pmsco
cd pmsco
git checkout master
git checkout -b my_branch
@endcode

Then, either copy a pre-built container into `~/containers`,
or build one from the definition file included under extras/singularity.
You may need to customize the definition file to match the host OS
or to install compatible OpenMPI libraries,
cf. [Singularity user guide](https://sylabs.io/guides/3.7/user-guide/mpi.html).

@code{.sh}
cd ~/containers
sudo singularity build pmsco.sif ~/containers/pmsco/extras/singularity/singularity_python3
@endcode

To work with PMSCO, start an interactive shell in the container and switch to the pmsco environment.
Note that the PMSCO code is outside the container and can be edited with the usual tools.

@code{.sh}
cd ~/containers
singularity shell pmsco.sif
. /opt/miniconda/etc/profile.d/conda.sh
conda activate pmsco
cd ~/containers/pmsco
meson setup build
meson compile -C build
meson install -C build
meson test -C build
@endcode

Or call PMSCO from outside:

@code{.sh}
cd ~/containers
mkdir output
cd output
singularity run -e ../pmsco.sif python -m pmsco -r path/to/your-runfile
@endcode

For parallel processing, prepend `mpirun -np X` to the singularity command as needed.
Note that this requires compatible OpenMPI versions on the host and container to avoid runtime errors.

*/
