Installing Salvus on Linux

We recommend the following steps to install Salvus on Linux systems. This page contains a general process -- however some steps have a deeper dive under the advanced topics accessed via the sidebar menu.

1. Where to Install

The first step to install Salvus, regardless of system, is to figure out where every component of it will run. The most common case is to have a full installation locally and additionally install a version of SalvusCompute on a larger workstation or cluster. Details on where to run Salvus for different scenarios can be found on the relevant page.

2. Setting up your Python environment

Salvus runs a great deal of its functionality through Python (SalvusFlow, SalvusMesh, SalvusOpt, all contained within SalvusPy). For it to be able to do that, it needs a compatible version of Python and dependencies. We ensure this compatibility by using conda-based package managers, then installing preset versions of Python and dependent packages.

Installing a package manager

On Linux systems, we recommend to use the Miniforge distribution together with Mamba as package manager. First, install Miniforge from Miniforge's GitHub. After installation, this program can be accessed from your shell by simply running it as:

mamba --version

The default configuration installs a Python executable into something called a "Conda environment". Such an environment is a way to install different version of Python and dependencies without them interfering. Most shells indicate that you are inside an environment by prepending the shell prompt with the environment name. Restarting your shell after a typical Miniforge installation will show you the default activated environment:

(base) > ...

This default environment will not be further used by SalvusPy.

Creating a salvus environment with dependencies

After setting up a way for you to run the command Mamba (or Conda if you opted for a different distribution), you need to download the list of Python dependencies, i.e. the 'specs' or 'specifications', and use this to create a new Conda environment. Conda and Mamba can directly read this file to install the appropriate Python version and external versions packages (of exact versions) required by SalvusPy.

On Linux systems, this file is easily obtained by running the program curl:

curl -O https://mondaic.com/environment-py311.yml

which will download it to the current directory in which you have your shell opened. You can also navigate to the file in your browser to download it to your downloads folder.

What's left is to use the downloaded spec file to create a new Conda environment. To do this, run this in your shell:

# Create a new environment with all required dependencies. 
mamba env create -n salvus -f environment.yml

This creates a new Python environment with the name `salvus`. You are free to change the name of the environment in your command, just ensure you note down for yourself what you name it.

To use this environment for the next steps of the installation process, and to use Salvus at all, make sure to activate this environment in your shell:

# Activate the created environment.
mamba activate salvus

3. Running the Salvus Downloader

The next step is to obtain two sets of files:

• SalvusCompute related binaries. These files include the computational part of Salvus itself, optionally its 64-bits precision variant, and binaries required for parallel execution.
• SalvusPy related distribution files. This simply is the Python API of Salvus rolled up into a distributable wheel.

Since both of these files require to be compiled on a per-platform basis, you need to obtain them specifically for Linux. Selecting the right set of files to download is mostly automated through the Salvus Downloader, with full details available here.

To run this helper program on Linux and obtain the relevant files, run the following:

bash -c "$(curl -sSL https://get.mondaic.com)"

After evaluating the end-user license agreement, ensuring the user has a license, a few system configuration steps are run through. The Salvus downloader is smart enough to select the correct microarchitecture and platform automatically. After this, you can select your release version.

Finally, the installer allows one to select which files exactly are downloaded:

• Salvus: the single precision version of SalvusCompute. This is needed to run Salvus in normal operation.
• SalvusF64: the double precision version of SalvusCompute. This is typically not needed to run Salvus in normal operation, but might be useful for research purposes. It is less performant but more precise.
• SalvusPy: the Salvus Python package. This is needed to run Salvus in normal operation, but typically not needed on remote systems to which simulations are dispatched.
• mpi: the MPI distribution. This is needed to run Salvus in normal operation, but it is not recommended on systems that provide their own, like HPC systems

One can navigate with the keyboard arrows and (de)select files using space.

The last part of this step is to install SalvusPy into the Python environment created before. This is done by running the pip program (available via the Conda environment) on the just-downloaded Python wheel of Salvus. In the following two commands ensure that you update the environment name to match the name you gave and you update the path to the Python wheel to match what you entered:

# Ensure you update the environment name if necessary.
mamba activate salvus
# Ensure you update the download path if necessary.
pip install ~/Salvus/python_packages/salvus-*.whl

4. Setting up your Salvus site

The final step in this process is to set up a computational site for SalvusCompute to run on. A site determines how the computational part of Salvus is run, and what resources it is allocated. The functionality that orchestrates the dispatching of simulations, the allocation of resources and the retrieval of results is collected in SalvusFlow, A detailed explanation on what these sites are can be found on the page on SalvusFlow Configurations

To streamline this process, the command line interface to salvus (aptly named `salvus-cli`) allows one to interactively create a new site from your shell:

# Update the conda environment name if necessary
mamba activate salvus
salvus-cli add-site

The default and maximum ranks relate to the parallelism allowed on your systems. Higher values up to the maximum your system is capable of will typically result in the better performance. We found that the optimal on Linux can be found by running the following:

# Linux command to get CPU details
lscpu | grep -E '^Thread|^Core|^Socket|^CPU\('

Specifically, the optimal on any system is the number of performant physical cores.

5. Start to Learn Salvus

Salvus should be all ready by now so time to learn how to use it. We recommend to start with the getting started tutorial series.