Tutorial: catalogue your first simulation¶

This tutorial walks you through cataloguing a simulation in your local SimDB, from checking the CLI to inspecting the ingested result. It assumes SimDB is installed. When you are done, continue with Push your simulation to a server.

Step 1: check the CLI¶

Confirm SimDB is available:

simdb --version

You should see something like simdb, version 0.15.2. Every command has help available with --help, at any level:

simdb --help
simdb simulation --help

The top-level help lists the command groups:

Commands:
  alias       Query remote and local aliases.
  config      Query/update application configuration.
  manifest    Create/check manifest file.
  provenance  Create the PROVENANCE_FILE from the current system.
  remote      Interact with the remote SimDB service.
  simulation  Manage ingested simulations.

sim is an alias for simulation.

Step 2: create a manifest¶

A simulation is described by a manifest: a YAML file listing the data the simulation used and produced, plus metadata about it. Generate a starter template:

simdb manifest create manifest.yaml

Open manifest.yaml and fill it in. A complete example:

manifest_version: 2
alias: iter-baseline-scenario-2024
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
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.

A few things to know (the how-to and reference cover them in full):

• Always use manifest_version: 2.

• The alias is optional but recommended; it must be unique and URL-safe.

• inputs and outputs use file and imas URIs. file paths must be absolute; glob patterns are expanded.

• machine, code, and description are the conventional metadata fields.

Step 3: validate the manifest¶

Before ingesting, check the file is well-formed:

simdb manifest check manifest.yaml

This checks the YAML syntax, the required sections, the URI formats, the metadata structure, and the alias rules. Fix any reported problems.

Step 4: ingest the simulation¶

simdb simulation ingest manifest.yaml

This adds the simulation to your local catalogue, computing a checksum for each referenced file. To override the manifest’s alias at ingest time:

simdb simulation ingest -a my-alias manifest.yaml

Step 5: inspect what you ingested¶

List your local simulations:

simdb simulation list

And show the full detail of one, by alias or UUID:

simdb simulation info iter-baseline-scenario-2024

What you have learned¶

You created a manifest, validated it, ingested a simulation, and inspected it, all locally. Next, share it: Push your simulation to a server.