Creation

You have the intention of running a certain experiment with a specific set of input parameters, or input files, or anything. So we create the simulation with all the instructions it needs. Bundling all of this in a single place ensures reproducability. This most likely includes:

• A dictionary of parameters
• A script that produces the result for this simulation
• A set of instructions on how to run the script

To create a new simulation, use add:

sim = coll.add(
    name="my-simulation",
    parameters={
        "param1": 73,
        "bar": [2, 3, 4, 5],
    },
)

Relevant files

Then, copy relevant files (or entire directories) into the simulation directory.

sim.copy_files(["path/to/script.py", "img1.png", "path/to/some/directory"])

Run script

As a next step we can create a run script for the simulation. This is an auto-generated bash script with the purpose of providing a single access point to produce the results for this simulation.

create_run_script takes up to 3 arguments:

• commands: an iterable of bash commands to run in sequence.
• euler: a boolean flag. If set to true, then a slurm submission script is written instead of a pure bash script.
• sbatch_kwargs: a dictionary of slurm job arguments.

sim.create_run_script(
    commands=["source .venv/bin/activate", "python3 script.py"], euler=False
)

Which will create the following file…

#!/bin/bash

export SIMULATION_DIR=/absolute/path/to/collection/data/getting-started/my-simulation
export SIMULATION_ID=315628DE80:my-simulation

source .venv/bin/activate
python3 script.py

Notice that the script exports two variables; SIMULATION_DIR and SIMULATION_ID. These should be used in your executable script script.py to infer the simulation on which to execute the script.

Collection

Initialize the collection as seen above, preferably using its ID. coll.df returns a pandas DataFrame of the collection.

coll = Collection.fromUID["315628DE80"]
coll.df

Filter simulations based on parameters using the built-in filtering interface:

filtered = coll.filter(
    coll.k["param1"] > 50,
    coll.k["bar"] <= 4,
)
filtered.df

See the Collection guide for full filtering syntax.

Simulation

To get a Simulation object, use brackets (it will autocomplete in notebooks).

sim = coll["my-simulation"]
sim

my-simulation

initialized

Not submitted

time stamp: 2026-04-11 12:48:13.635137

Files

⭗ my-simulation
├── run.sh
└── data.h5

0 directories, 2 files

Parameters

Parameter	Value
bar	[2 3 4 5]
param1	73

Key properties of a Simulation object:

Reading results

The sim.data property returns the default Series:

sim.data.values          # array of time values
sim.data.get_field_names()   # list of stored fields

# Read a field across all steps
pressure = sim.data["pressure"][:]    # shape: (n_steps, *field_shape)

# Read global/scalar data as a DataFrame
sim.data.globals.df

See Writing data and Reading data for complete guides.