Create a manifest¶

A manifest is the YAML file you ingest to catalogue a simulation. This guide shows how to write a good one. For the complete specification of every field, see the manifest format reference.

Start from a template¶

simdb manifest create manifest.yaml

This writes a starter manifest you can edit.

Set the version and alias¶

Always use version 2, and give the simulation a descriptive, unique, URL-safe alias:

manifest_version: 2
alias: iter-baseline-scenario-2024

Good alias conventions:

a descriptive name such as machine-scenario-date; or
a pulse_number/run_number form such as 100001/1.

The alias is optional in the manifest; you can also set it at ingest time with simdb simulation ingest -a ALIAS. Use simdb alias make-unique if you need a guaranteed-unique name.

List inputs and outputs¶

List every data file the simulation used (inputs) and produced (outputs), as URIs:

inputs:
  - uri: file:///work/sims/run42/input/parameters.txt
  - uri: imas:hdf5?path=/work/imas/input_data
outputs:
  - uri: file:///work/sims/run42/results/output.nc
  - uri: imas:mdsplus?path=/work/imas/simulation_output

Tips:

Use absolute paths for file URIs. Glob patterns such as *.nc are expanded.
For IMAS data, give the correct backend (hdf5 or mdsplus).
Include all relevant inputs (initial conditions, parameters, configuration) and all outputs (results, diagnostics).

Describe it with metadata¶

metadata:
  - machine: ITER
  - code:
      name: JETTO
      version: "2024.1"
  - description: |-
      Baseline H-mode scenario simulation for ITER.
      15 MA plasma current with a Q=10 target.

Conventions:

machine: the device name. Always include it.
code: name and version, for reproducibility.
description: context about the run’s purpose.
Add any other key/value pairs you want to be able to query on. Metadata names may not contain :, =, or #.

Check it¶

Before ingesting, validate the file’s structure:

simdb manifest check manifest.yaml

Then ingest it (see Ingest and manage simulations).