# Metadata written to sim_telarray output

simtools writes metadata including run information, software version, and model parameters into the
sim_telarray output file. The metadata is written as a set of key-value pairs and consists of
a general set of values plus one set per array element.

To read the metadata from a sim_telarray output file, do e.g.,

```python
import pprint
import simtools.simtel.simtel_io_metadata as simtel_io_metadata

data = simtel_io_metadata.read_sim_telarray_metadata(
    "tests/resources/generated/proton_run000001_za20deg_azm180deg_North_alpha_6.0.2_test.simtel.zst"
)
pprint.pprint(data)
```

Metadata is validated against the registry metaschema
[sim_telarray_meta_parameter.metaschema.yml](https://github.com/gammasim/simtools/blob/main/src/simtools/schemas/sim_telarray_meta_parameter.metaschema.yml)
plus the model-parameter schemas. The registry is used to validate the emitted metadata and to
provide a registry of the metadata keys, their expected scope and value shape.

The complete schema can be exported from the simtools package with

```console
simtools-export-sim-telarray-metadata-schema \
   --output_file sim_telarray_metadata_schema.json
```

To add a new metadata value, update the matching model-parameter schema if it is model-derived,
or add the new generated key to the sim_telarray metadata registry, then run the metadata tests to
verify that the value is written and read correctly.

## Software provenance

Simulation output contains a compact software summary rather than the complete Python environment.
The generated global metadata includes the simtools, CORSIKA, sim_telarray, hessio, stdtools, and
Python versions; the simtools Git revision; relevant CORSIKA build variants; and
`simtools_dependency_manifest_sha256`.

The manifest digest identifies the complete canonical record stored in the container at
`/opt/simtools/provenance/dependency-manifest.json`. Use it to match an output file to the OCI
image and its release metadata. The full manifest is not embedded in every event file.