Getting Started#

Using simtools requires installing and accessing its main components: the simtools package, the simulation software CORSIKA and sim_telarray, and the simulation-model repository.

For development-related information, see Getting Started as a Developer.

Installation#

simtools can be installed using one of the following methods:

  • Using a container image with all software pre-installed (recommended)

  • Via pip. Requires manual compilation and installation of CORSIKA and sim_telarray. See the section below for details.

Container Images#

OCI-compatible container images are available for simtools users and support both application and development use cases. Any runtime such as Docker, Podman, or Apptainer can be used. Apptainer users should pull the OCI image with a docker:// reference. These images eliminate all manual installation steps and allow direct execution of simtools applications.

The most important types of images are listed below; for a complete overview, see the Container Images documentation.

  • Simtools Production images (simtools-prod): Include CORSIKA, sim_telarray, and simtools applications. Variants are available with:

    • Different CORSIKA/sim_telarray versions

    • Compile options (e.g., prod5, prod6)

    • CPU optimizations (e.g., avx2, avx512, generic)

  • Simtools Development images (simtools-dev): Include all dependencies for simtools development, as well as CORSIKA and sim_telarray, but do not contain simtools itself.

Pre-built images are hosted on the simtools package registry. Authentication may be required; follow GitHub’s guide to configure access for your selected runtime.

Important

Container images do not include the interaction tables required by CORSIKA. Follow the instructions in the CORSIKA documentation to download and install the interaction tables.

Running a simtools Production Image#

Prerequisite: Configure access to a local checkout or Git repository containing the simulation models.

Start an Interactive Container:

podman run --rm -it \
    --env-file .env \
    -v "$(pwd):/workdir/external" \
    ghcr.io/gammasim/simtools-240205-corsika-77500-bernlohr-1.67-prod6-baseline-qgs2-no_opt:latest \
    bash

Any simtools application can be run inside the container.

Run a simtools application:

podman run --rm -it \
    --env-file .env \
    -v "$(pwd):/workdir/external" \
    ghcr.io/gammasim/simtools-240205-corsika-77500-bernlohr-1.67-prod6-baseline-qgs2-no_opt:latest \
    simtools-convert-geo-coordinates-of-array-elements \
    --array_element_positions_file ./simtools/tests/resources/telescope_positions-North-utm.ecsv \
    --export ground \
    --output_path /workdir/external/

Start an Interactive Apptainer Container:

apptainer pull simtools-prod.sif \
  docker://ghcr.io/gammasim/simtools-prod:v0.27.0-v78010-v2025-11-30-rc-generic

apptainer shell \
  --env-file .env \
  --bind "$(pwd):/workdir/external" \
  simtools-prod.sif

Run a simtools application with Apptainer:

apptainer exec \
  --env-file .env \
  --bind "$(pwd):/workdir/external" \
  simtools-prod.sif \
  simtools-convert-geo-coordinates-of-array-elements \
  --array_element_positions_file ./simtools/tests/resources/telescope_positions-North-utm.ecsv \
  --export ground \
  --output_path /workdir/external/

Use the same OCI tag with Apptainer that you would use with Docker or Podman. Replace the generic tag with avx2, avx512f, or sse4 when using a corresponding optimized x86_64 image.

Pip Installation#

simtools is available as a Python package from PyPI.

To install, prepare a Python environment and install simtools and its dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install gammasimtools

Installation of CORSIKA and sim_telarray#

CORSIKA and sim_telarray are external tools to simtools and are required dependencies for many applications. The installation requires some preparation; therefore, it is recommended to use the Docker environment.

For a non-Docker setup, follow the instructions provided by the CORSIKA/sim_telarray authors for installation. CTAO users can download both packages from the sim_telarray web page (CTAO password applies) and install the package with:

tar -xzf corsika7.7_simtelarray.tar.gz
./build_all prod6-sc qgs2 gsl

The following environment variables must be set for simtools applications to find the CORSIKA/sim_telarray installation:

  • $SIMTOOLS_SIM_TELARRAY_PATH: Path to the sim_telarray installation (e.g., /workdir/sim_telarray in the container environment)

  • $SIMTOOLS_CORSIKA_PATH: Path to the CORSIKA installation (e.g., /workdir/corsika in the container environment)

  • $SIMTOOLS_CORSIKA_INTERACTION_TABLE_PATH: Path to the CORSIKA interaction tables (e.g., /workdir/corsika-interaction-tables in the container environment)

Simulation-model repository#

Simulation-model parameters and referenced files are read from a local checkout or a local normal, bare, or mirror Git repository. Applications that use model parameters accept --simulation_models_path, --simulation_models_git_path, and --simulation_models_git_revision.

Environment Variables#

The environment variables listed below are used by simtools applications and defined by the user in a .env file to be placed in the working directory. Copy the template file .env_template to a new file named .env and update it accordingly. The pinned model-repository revision and the default simtools-tests resource version are maintained in dependency_versions.yml.

# Path to a checked-out simulation-model repository
SIMTOOLS_SIMULATION_MODELS_PATH='/workdir/simulation-models'
# Or use a local Git repository and revision
SIMTOOLS_SIMULATION_MODELS_GIT_PATH='/workdir/simulation-models.git'
SIMTOOLS_SIMULATION_MODELS_GIT_REVISION='HEAD'
# Path to the sim_telarray installation
SIMTOOLS_SIM_TELARRAY_PATH='/workdir/sim_telarray'
# Path to the CORSIKA installation
SIMTOOLS_CORSIKA_PATH='/workdir/corsika'
# Path to the CORSIKA interaction tables
SIMTOOLS_CORSIKA_INTERACTION_TABLE_PATH='/workdir/corsika-interaction-tables'
# User name of the user running the application
SIMTOOLS_USER_NAME='Max Mustermann'
# ORCID of the user running the application
SIMTOOLS_USER_ORCID='0000-1234-5678-0000'

Note

Any simtools application command-line argument can be set as an environment variable, see the application configuration section.