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

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 or conda. 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. These images eliminate all manual installation steps and allow direct execution of simtools applications.

Pre-built Images#

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, no_opt)
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 (docker login).

Running a simtools Production Image#

Prerequisite: Configure simulation model database access.

Start an Interactive Container:

docker run --rm -it \
    --env-file .env \
    -v "$(pwd):/workdir/external" \
    ghcr.io/gammasim/simtools-prod-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:

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

Pip Installation#

simtools is available as a Python package from PypPi.

To install, prepare a python environment, e.g.:

mamba create --name simtools-prod python=3.11
mamba activate simtools-prod

Install simtools and its dependencies:

pip install gammasimtools

Conda Installation#

Prepare and install a conda environment with the simtools package:

conda env create -n gammasimtools
conda install gammasimtools --channel conda-forge
conda activate 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, this is why it is recommended to use the Docker environment

For a non-Docker setup, follow the instruction 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 -czf corsika7.7_simtelarray.tar.gz
./build_all prod6-sc qgs2 gsl

The environmental variable $SIMTOOLS_SIMTEL_PATH should point towards the CORSIKA/sim_telarray installation (recommended to include it in the .env file with all other environment variables).

Model Database Access#

Simulation model parameters are stored in database. Many simtools applications depend on access to this database.

Note

Ask one of the developers for the credentials to access the database.

Credentials for database access are passed on to simtools applications using environmental variables stored in a file named .env, see the Environment Variables section below.

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.

# Hostname of the database server
SIMTOOLS_DB_SERVER=<hostname>
# Port on the database server
SIMTOOLS_DB_API_PORT=<integer>
# Username for database
SIMTOOLS_DB_API_USER=<username>
# Password for database
SIMTOOLS_DB_API_PW=<password>
SIMTOOLS_DB_API_AUTHENTICATION_DATABASE='admin'
# Name of the simulation model database
SIMTOOLS_DB_SIMULATION_MODEL='CTAO-Simulation-ModelParameters-v0-7-0'
# Path to the sim_telarray installation
SIMTOOLS_SIMTEL_PATH='/workdir/sim_telarray'
# 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'