Getting SLUG

You can get SLUG v3 in three ways: installing from PyPI, using a container, or installing from source. The first two options are the easiest and are recommended for most users, while the third option is the most flexible and is likely to give the best performance on HPC systems.

Installing from PyPI

You can install SLUG v3 from PyPI using pip, by doing:

pip install slugpy

in a terminal. This will install the latest release of both the slugpy Python package and the slug executable, which can be run from the command line. SLUG requires a number of data files that are not included in the PyPI distribution due to their size. To download these, run:

python -m slugpy.download_data

By default the data will be downloaded into the data subdirectory of a per-user directory (e.g., ~/.local/share/slug/data on Linux, or ~/Library/Application Support/slug/data on macOS), or into $SLUG_DIR/data if the environment variable SLUG_DIR is set. Warning: the data files are large (several GB), so make sure you have enough disk space before downloading them. You can download only some of the data by doing:

python -m slugpy.download_data --subdir SUBDIR

where SUBDIR is the name of one subdirectory of the data directory; run the command once for each subdirectory you want. The full list of subdirectories is:

  • filters: photometric filter transmission curves

  • nebular: nebular emission model data

  • spectra: stellar atmosphere model spectra

  • tracks: stellar evolutionary tracks

Prebuilt wheels are available for Linux on x86_64 and aarch64 processors, and for macOS 14 or later on Apple Silicon (arm64), for Python 3.12 through 3.14. On other platforms or Python versions, pip builds SLUG from source, which requires the compiler and libraries listed in Dependencies.

Using a container

SLUG v3 is also distributed as a container image, hosted on the GitHub Container Registry as ghcr.io/markkrumholz/slug3. Each release is tagged with its version number (e.g., ghcr.io/markkrumholz/slug3:3.0.1), and the tag latest always points to the most recent release. The image contains the slug command-line executable, built with support for both OpenMP and MPI parallelism, and the slugpy package, installed in a Python environment whose python and slug are on the default PATH. The image is built for Linux on x86_64 (linux/amd64) processors; it will run on other architectures (e.g., Apple Silicon Macs) only under emulation, which is much slower, so on those platforms installing from PyPI is a better choice.

You can use the image with Docker, by doing:

docker pull ghcr.io/markkrumholz/slug3:latest

or, on HPC systems, which generally do not provide Docker, with Apptainer (formerly called Singularity), which converts the image into a single file, here called slug3.sif:

apptainer pull slug3.sif docker://ghcr.io/markkrumholz/slug3:latest

The large data files SLUG needs are not included in the image. Instead, the image expects to find them in a directory /data inside the container, which you provide by binding (mounting) a directory on the host system there. The data files themselves go in a data/ subdirectory of that directory, and you can download them into it by running the same download script as for PyPI installations inside the container – be warned that the data files are large (several GB), so make sure you have enough disk space to hold them. For example, with Apptainer, to download the data into /path/to/slug-data/data:

apptainer exec --bind /path/to/slug-data:/data slug3.sif python -m slugpy.download_data

The equivalent with Docker is:

docker run --rm -v /path/to/slug-data:/data ghcr.io/markkrumholz/slug3:latest \
    python -m slugpy.download_data

You only need to do this once; every later run of the container just needs the same directory bound to /data again. Similarly, slug writes its output files into its working directory (unless the input deck specifies otherwise), so the directory you run it from must also be visible inside the container, and must be the container’s working directory. Apptainer usually does this automatically, but if your output does not appear, bind it explicitly by adding --bind "$PWD" --pwd "$PWD" to the apptainer exec command. With Docker, do the same with -v "$PWD":"$PWD" -w "$PWD". See Running a SLUG Simulation for how to run simulations with the container.

Installing from source

SLUG v3 is available for download from the GitHub repository at https://github.com/markkrumholz/slug3. To get it, use git to clone the repository by doing:

git clone https://github.com/markkrumholz/slug3.git
cd slug3
git submodule update --init --recursive

In addition to the SLUG source code and its submodules, SLUG requires a number of data files that are not included in the GitHub repository due to their size. These data files can be downloaded using the script data/tools/download_data.py in the repository. For example, to download all of the data files, run:

python data/tools/download_data.py

Warning: the data files are large (several GB), so make sure you have enough disk space before downloading them.

If you prefer to download the data files manually, they can be accessed from the Australian National University Data Commons service.

Once you have downloaded the source code and data files, the next step is to compile SLUG.