Quickstart

To get started with SLUG, you can either install it from PyPI, use a container, or build from source. Quickstart directions for each path are below, with full details in Getting SLUG.

Installing from PyPI

1. Install SLUG and its required data by doing:

   pip install slugpy
   python -m slugpy.download_data
   

2. Write a parameter file describing the simulation you want to run. See The SLUG Input Deck for details, and the examples/ directory in the SLUG repository for example parameter files (see Examples).

3. Run SLUG either from the command line or from Python. To run from the command line, do:

   slug path/to/parameter_file.toml
   

   and to run from Python, do:

   import slugpy
   sim_result = slugpy.run_sim("path/to/parameter_file.toml")
   

   See Running a SLUG Simulation for full details on running SLUG from the command line or from Python.

4. If SLUG was run from the command line, use the Python lazy-reader to examine the output:

   import slugpy
   sim_result = slugpy.read("path/to/model_name")
   

   This step is not needed if SLUG was run from Python with HDF5 output (the default), as the Python runner automatically returns a Python lazy-reader pointing to the simulation output in that case (for ASCII output, it returns None instead, and this step doesn’t apply). See slugpy for details on how to use the lazy-reader, and Output Files and Format for full documentation of the contents of the output of a simulation.

Using a Container

1. Install SLUG and its required data by doing:

   # If using Docker:
   docker pull ghcr.io/markkrumholz/slug3:latest
   docker run --rm -v /path/to/slug-data:/data ghcr.io/markkrumholz/slug3:latest \
       python -m slugpy.download_data
   
   # If using Apptainer/Singularity:
   apptainer pull slug3.sif docker://ghcr.io/markkrumholz/slug3:latest
   apptainer exec --bind /path/to/slug-data:/data slug3.sif python -m slugpy.download_data
   

   depending on whether you are using Docker or Apptainer.

2. Write a parameter file describing the simulation you want to run. See The SLUG Input Deck for details, and the examples/ directory in the SLUG repository for example parameter files (see Examples). With Docker, the parameter file must be in or below the directory from which you run the container, since that is the only directory of the host system (other than the data directory) visible inside it.

3. Run SLUG either from the command line or from Python. To run from the command line, do:

   # If using Docker:
   docker run --rm -v /path/to/slug-data:/data -v "$PWD":"$PWD" -w "$PWD" \
       ghcr.io/markkrumholz/slug3:latest slug path/to/parameter_file.toml
   
   # If using Apptainer/Singularity:
   apptainer exec --bind /path/to/slug-data:/data slug3.sif slug path/to/parameter_file.toml
   

   and to run from Python, start up a Python interpreter inside the container by doing:

   # If using Docker:
   docker run --rm -it -v /path/to/slug-data:/data -v "$PWD":"$PWD" -w "$PWD" \
       ghcr.io/markkrumholz/slug3:latest python
   
   # If using Apptainer/Singularity:
   apptainer exec --bind /path/to/slug-data:/data slug3.sif python
   

   and then do:

   import slugpy
   sim_result = slugpy.run_sim("path/to/parameter_file.toml")
   

4. If SLUG was run from the command line, use the Python lazy-reader to examine the output. First start up a Python interpreter inside the container as per the previous step, then do:

   import slugpy
   sim_result = slugpy.read("path/to/model_name")
   

   This step is not needed if SLUG was run from Python with HDF5 output (the default), as the Python runner automatically returns a Python lazy-reader pointing to the simulation output in that case (for ASCII output, it returns None instead, and this step doesn’t apply). See slugpy for details on how to use the lazy-reader, and Output Files and Format for full documentation of the contents of the output of a simulation.

Building from Source

1. Download SLUG and its required data by doing:

   git clone https://github.com/markkrumholz/slug3.git
   cd slug3
   git submodule update --init --recursive
   python data/tools/download_data.py
   

   See Getting SLUG for full details.

2. Compile SLUG by doing:

   cmake -S . -B build -G Ninja
   cmake --build build
   

   from the repository root. See Configuring and Building for full details. (If this doesn’t work, check the list of dependencies and supported compilers in Dependencies.)

3. Run the quick test suite to make sure everything is working:

   cd build
   ctest -L quick
   

   See Tests for the full details on the test suite.

4. Write a parameter file describing the simulation you want to run. See The SLUG Input Deck for details, and the examples/ directory in the repository for example parameter files (see Examples).

5. Run SLUG either from the command line or from Python. To run from the command line, do:

   build/slug path/to/parameter_file.toml
   

   and to run from Python, do:

   import slugpy
   sim_result = slugpy.run_sim("path/to/parameter_file.toml")
   

   See Running a SLUG Simulation for full details on running SLUG from the command line or from Python.

6. If SLUG was run from the command line, use the Python lazy-reader to examine the output:

   import slugpy
   sim_result = slugpy.read("path/to/model_name")
   

   This step is not needed if SLUG was run from Python with HDF5 output (the default), as the Python runner automatically returns a Python lazy-reader pointing to the simulation output in that case (for ASCII output, it returns None instead, and this step doesn’t apply). See slugpy for details on how to use the lazy-reader, and Output Files and Format for full documentation of the contents of the output of a simulation.