Installation

Installing SALSA

SALSA is built off of quite a few different packages and some of these are best to install before installing SALSA. Go to Installing Dependencies for more details on how best to do this.

Stable Version

SALSA has a few dependencies that are best installed

The easiest way to install SALSA is with pip

$ pip install astro-salsa

Note

To install some of the dependencies, the GCC compiler needs to be installed. This is not a problem for most machines but can raise an error for some.

Development Version

For the latest development version, you will first need to clone the SALSA repository, then enter the main directory. You can then install SALSA with pip:

$ git clone https://github.com/biboyd/SALSA.git
$ cd SALSA
$ pip install -e .

If you want to install the additional dependencies needed for locally testing SALSA and building the documentation, instead run:

$ pip install -e .[dev]

This will check that dependencies are installed and should install any that you might be missing. The dev tag will check for the additional packages needed to develop locally (e.g., pytest, sphinx).

Running the Test Suite

SALSA uses pytest for its test suite infrastructure. To run the tests from either the top level SALSA directory or the tests subdirectory, simply execute:

$ pytest

This test suite makes use of yt’s sample datasets. By default this sample data will be downloaded to the directory from which the tests are run. To keep things clean, you may wish to use the provided tests/data/ directory by setting yt’s test_data_dir configuration. For example, you can locally configure test_data_dir within the SALSA directory using:

$ yt config set --local yt test_data_dir ./tests/data/

Currently, the test suite is not written to utilize unit tests but rather it regression tests SALSA’s functionality wholistically.

Installing Dependencies

For the full list of dependencies, see the requirements.txt and/or setup.py files in the SALSA repository. Below is some advice/guides to installing a couple of the trickier packages.

A Note on Conda

Conda is a popular package manager that prefers to install wholly contained environments. This can cause issues with packages like mpi4py or h5py (often needed by yt) that depend on non-Python libraries, as Conda will install its own copy of these libraries. On most HPC systems, these libraries are already provided and are usually optimized to the system itself.

It’s generally discouraged to mix Conda and pip because it can cause issues with dependency resolution, but it is required to install both SALSA and its dependency Trident. Additionally, of you wish to use a Conda environment but want to avoid duplicating non-Python libraries, can often pip install such Python libraries using the existing external dependencies in your system path.

Always make sure you are using the copy of pip associated with your Conda environment:

$ conda activate my-env $ conda install pip $ which pip

Install yt

The yt package offers instructions on how to install it on their website.

Note that if you want to work with a dataset from a particular simulation code, there may be additional dependencies that need to be installed. For example, Enzo datasets require you to install h5py. This in turn depends on having HDF5 <https://www.hdfgroup.org/solutions/hdf5/>.

Install Trident

Trident can be installed via pip:

$ pip install trident

The first time trident runs though, it downloads an ionization table. It is recommended that you run trident right after you pip install. This will also do some tests to make sure trident is running properly.

$ python
>>> import trident; trident.verify()

For more details see Trident’s documentation

Install mpi4py

The mpi4py package enables use of MPI parallelism with Python. SALSA uses this to split up light ray creation and absorber extraction across multiple processors which becomes necessary for large numbers of light rays.

You can install mpi4py can be installed either using pip or Conda. It’s useful to install with pip if you already have an MPI library installed (such as OpenMPI) as it will be built against your existing installation as long as the MPI compiler is in your system path:

$ pip install mpi4py