Installing Salvus on Windows (WSL)

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

With Windows 10 and 11, one can run programs on a Windows machine as if it was a Linux machine. This is done by using the Windows Subsystem for Linux (WSL), developed by Microsoft. Salvus works well in it, even offering support for Nvidia GPU acceleration. There is little overhead using WSL compared to using Linux natively, and Salvus doesn't take a large performance hit.

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. Installing the Windows Subsystem for Linux

On Windows 11 it can be installed via the Microsoft store. Alternatively, follow these instructions on either Windows 10 or 11. Please note that you require administrator rights on the machine to enable the Linux subsystem.

If you have no specific preference for systems, we recommend to choose Ubuntu 20.04 LTS from the Microsoft store page as Linux distribution, as that has seen the most extensive testing. Other Linux distributions should in principle work as well.

The WSL enables the direct execution of Linux binaries. So make sure to always install the Linux version of everything (Miniforge, Python, Salvus, ... ) into it.

Where are my files?

Within the virtual Linux system that WSL creates, the original Windows file system is mounted as if it was an external hard drive under the Linux subsystem. For example, you can find the Windows Desktop directory here:

Copy
/mnt/c/Users/WindowsUserName/Desktop

Conversely, the WSL installation should also show the Linux file system in the the Windows Explorer as network mounts. These can be immediately found by entering \\wsl$ in the top navigation bar. Additionally, you can access this path also using your Windows native shell:

Copy
\\wsl$

3. 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 WSL 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 WSL 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.

On Windows (WSL), if you use the browser to download the YAML file, you will need to move it into your WSL environment. The easiest way is to copy the file from your Windows Downloads folder into the WSL file system, as described on this support page from Microsoft.

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

4. 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 WSL. 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 WSL 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

5. 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 WSL can be found by running the following:

# Windows native command to retrieve CPU details
# Run this in PowerShell
Get-CimInstance -ClassName Win32_Processor | Select-Object -Property Name,NumberOfCores,NumberOfLogicalProcessors

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

6. 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.

7. Nvidia GPUs

Salvus greatly benefits from running on Nvidia GPUs which is supported in the WSL as described on this Nvidia page . We recommend to use Windows 11 for this which by far has the easiest set-up process.

8. Troubleshooting

A few common reasons for a Salvus installation not working correctly on WSL are described below.

SSL Connections

TLS/SSL connections (e.g. connections over HTTPS) require a few things to work correctly. If you see an error code referencing any of these terms, there might be some connection issues. A simple way to test if everything works is to run the following from the WSL shell:

Copy
wget https://google.com

which should finish without error. In case you encounter SSH connection problems there are a few likely causes:

• Anti-Virus Software: Anti-virus software running on the Windows host has been reported to block SSL connections in the WSL. Executing the following command in the Windows native powershell will print all active anti virus programs. Try disabling them temporarily and check if Salvus does run successfully afterwards.

Copy
powershell.exe "Get-CimInstance -Namespace root/SecurityCenter2 -ClassName AntivirusProduct" | grep displayName

• Proxy Settings: This can result in very similar errors. Please see this page for details.