Runtime

context

Run context: the configuration and services of one simtools run.

class simtools.runtime.context.Activity(activity_id=<factory>, activity_name=None, user=<factory>, hostname=<factory>)

Identity of one simtools activity.

classmethod from_arguments(args)

Return the activity of parsed arguments (a new ID if none is given).

class simtools.runtime.context.RunContext(model_reader=None, paths=<factory>, software=<factory>, activity=<factory>, args=<factory>, logger=None, run_time=None)

Configuration and services of one simtools run.

Parameters:

model_readerSimulationModelReader or None

Reader of the simulation models.

pathsOutputPaths

Output and model-configuration directories.

softwareSimulationSoftware

Simulation software installations and ray-tracing backend.

activityActivity

Activity identity.

argsMapping

Read-only view of the parsed application arguments.

classmethod from_arguments(args=None, model_reader=None, paths=None)

Return the context of parsed arguments.

Parameters:

argsdict, optional

Parsed arguments; wrapped read-only, not copied.

model_readerSimulationModelReader, optional

Reader of the simulation models.

pathsOutputPaths, optional

Output paths; by default built from output_path in the arguments.

classmethod from_environment()

Return a fresh context built from environment.

classmethod from_spec(spec, model_reader=None)

Rebuild a worker context from to_spec() output.

property ray_tracing_backend

Configured optical ray-tracing backend.

replace(**changes)

Return a copy with the given fields replaced.

to_spec()

Return the JSON-serializable configuration needed to rebuild this context.

class simtools.runtime.context.SimulationSoftware(sim_telarray_root=None, sim_telarray_executable_name=None, corsika_root=None, corsika_interaction_table_root=None, corsika_build_variants=None, corsika_flat_executable=None, he_interaction='epos', le_interaction='urqmd', ray_tracing_backend='sim_telarray')

Configured CORSIKA and sim_telarray installations and the ray-tracing backend.

Fields hold the configured values; the properties validate them and resolve executables.

property corsika_dummy_file

Path to a dummy CORSIKA file required by sim_telarray for ray-tracing simulations.

This file does not need to exist; sim_telarray only requires a file path.

property corsika_exe

Path to the CORSIKA executable (flat atmosphere).

property corsika_interaction_models

Configured high- and low-energy CORSIKA interaction models.

property corsika_interaction_table_path

Path to the CORSIKA interaction table directory.

property corsika_path

Path to the CORSIKA installation directory.

classmethod from_arguments(args=None)

Return the software configuration from arguments, environment and defaults.

Priority order: argument > environment variable > built-in default.

Parameters:

argsMapping, optional

Parsed arguments.

property sim_telarray_exe

Path to the sim_telarray executable.

property sim_telarray_exe_debug_trace

Path to the debug trace version of the sim_telarray executable.

property sim_telarray_path

Path to the sim_telarray installation directory.

dependencies

Simtools dependencies version management.

This modules provides two main functionalities:

• retrieve the versions of simtools dependencies (e.g., model repositories, sim_telarray, CORSIKA)

• provide space for future implementations of version management

simtools.runtime.dependencies.build_dependency_manifest(context=None)

Build a deterministic manifest from the active runtime environment.

Returns:

dict

Discovered dependency manifest.

simtools.runtime.dependencies.canonical_manifest_bytes(manifest)

Serialize a manifest deterministically for hashing.

Parameters:

manifestdict

Dependency manifest.

Returns:

bytes

Canonical UTF-8 JSON representation.

simtools.runtime.dependencies.export_build_info(output_file, run_time=None, context=None)

Export build and version information to a file.

Parameters:

output_filestr

Path to the output file.

run_timelist, optional

Runtime environment command (e.g., Docker).

simtools.runtime.dependencies.get_build_options(run_time=None, context=None)

Return CORSIKA / sim_telarray config and build options.

For CORSIKA / sim_telarray build for simtools version >0.25.0: expects build_opts.yml file in each CORSIKA and sim_telarray directories.

For CORSIKA / sim_telarray build for simtools version <=0.25.0: expects a build_opts.yml file in the sim_telarray directory.

Parameters:

run_timelist, optional

Runtime environment command (e.g., Docker).

Returns:

dict

CORSIKA / sim_telarray build options.

simtools.runtime.dependencies.get_corsika_version(run_time=None, context=None)

Get the version of the CORSIKA package.

Version strings for CORSIKA are of the form “7.7550” (major.minor with 4-digit minor).

Parameters:

run_timelist, optional

Runtime environment command (e.g., Docker).

Returns:

str

Version of the CORSIKA package.

simtools.runtime.dependencies.get_dependency_manifest(run_time=None, context=None)

Return the installed dependency manifest or a discovered fallback.

Parameters:

run_timelist, optional

Runtime command used to read a manifest from a container.

Returns:

dict

Dependency manifest.

Raises:

FileNotFoundError

If an explicitly requested container does not contain a manifest.

ValueError

If the manifest contains invalid JSON.

simtools.runtime.dependencies.get_dependency_manifest_digest(run_time=None, context=None)

Return the SHA-256 digest of the dependency manifest.

simtools.runtime.dependencies.get_dependency_metadata(context=None)

Return compact scalar provenance values for simulation metadata.

simtools.runtime.dependencies.get_dependency_summary(run_time=None, context=None)

Return a compact human-readable dependency summary.

simtools.runtime.dependencies.get_direct_python_dependency_versions()

Return installed versions of direct simtools Python dependencies.

Includes optional dependencies (extras) that are installed.

Returns:

dict

Normalized distribution names mapped to installed versions.

simtools.runtime.dependencies.get_sim_telarray_version(run_time=None, context=None)

Get the version of the sim_telarray package using ‘sim_telarray –version’.

Version strings for sim_telarray are of the form “2024.271.0” (year.day_of_year.patch).

Parameters:

run_timelist, optional

Runtime environment command (e.g., Docker).

Returns:

str

Version of the sim_telarray package.

simtools.runtime.dependencies.get_software_version(software, context=None)

Return the version of the specified software package.

Parameters:

softwarestr

Name of the software package.

Returns:

str

Version of the specified software package.

simtools.runtime.dependencies.get_version_string(run_time=None, include_software_versions=True, context=None)

Print the versions of the dependencies.

Parameters:

run_timelist, optional

Runtime environment command (e.g., Docker).

include_software_versionsbool, optional

If True, query sim_telarray/CORSIKA executables and include their runtime versions. If False, skip executable checks and report these values as None.

Returns:

str

String containing the versions of the dependencies.

simtools.runtime.dependencies.validate_simulation_dependencies(simulation_software, context=None)

Validate external software and data required by a simulation.

Parameters:

simulation_softwarestr

Simulation software selection: sim_telarray, corsika, or corsika_sim_telarray.

Raises:

ValueError

If the selection or CORSIKA interaction-table manifest is invalid, or if a required dependency is unavailable.

simtools.runtime.dependencies.write_dependency_manifest(output_file, context=None)

Write the active dependency manifest and its SHA-256 file.

Parameters:

output_filestr or Path

JSON manifest output path.

simtools.runtime.dependencies.write_development_dependency_manifest(output_file, project_file, build_option_files)

Write provenance for a development image without installing simtools.

Parameters:

output_filestr or Path

JSON manifest output path.

project_filestr or Path

Project file declaring direct Python dependencies.

build_option_filesiterable of str or Path

CORSIKA and sim_telarray build-options files to merge when available.