Snapshots¶

A snapshot is a complete restore point for a simulation. MoCSI can write one at the end of a run and load one at the start of another, which lets you:

continue a long simulation in stages (e.g. run an equilibration, then keep going),
branch a parameter study from a shared starting state, and
archive the exact configuration a result was produced with — a snapshot stores every .ini value, so it doubles as a record of how the run was set up.

💾

Create Save the full state at the end of a run

▶️

Restart Continue a new run from a saved state

📄

Format What's inside the snapshot file

The configuration keys¶

Snapshots are controlled by four keys in your default.ini (overridable in run.ini). All are inert by default, so snapshots are opt-in:

Key	Default	Meaning
`snapshot_save_file`	`"None"`	Path to write a snapshot to at the end of the run. `"None"` disables saving.
`snapshot`	`"None"`	Path to a snapshot file to load at the start of the run. `"None"` disables loading.
`_snapshot_keep_sim`	`false`	When loading, keep the current `default.ini`/`run.ini` values instead of overwriting them from the snapshot.
`_snapshot_keep_module`	`false`	When loading, keep the current module `.ini` values instead of overwriting them from the snapshot.

See the INI options reference (Snapshot options section) for where these sit among the other keys.

Creating a snapshot¶

Set snapshot_save_file to a path on your system:

snapshot_save_file = "results/my_run_snapshot.csv"

At the end of the run — after the last iteration of the time loop — MoCSI writes a snapshot to that path (creating the file if it does not exist). The snapshot contains:

the full temperature field after the final iteration, and
the contents of every .ini file used by the run: the merged simulation config (default.ini + run.ini) and the .ini of every loaded module.

Note

When MoCSI is built with MPI, the field data is written in parallel via MPI-I/O into a separate binary file, so an MPI run produces two files rather than one. MoCSI derives the field-file name from snapshot_save_file by inserting _fields before the extension (e.g. my_run_snapshot.csv → my_run_snapshot_fields.csv); the file named by snapshot_save_file then holds only the configuration (INIFILEDATA:). Both files are needed to restart — see Snapshot file format.

Restarting from a snapshot¶

Point snapshot at a valid snapshot file:

snapshot = "results/my_run_snapshot.csv"

When this is set, MoCSI loads the file at the start of the run and, before the data is first accessed, overwrites the simulation config, the module configs, and the dependent-variable field (temperature) with the snapshot’s values. It then checks that every module that was active when the snapshot was created is also loaded in the new run, and aborts with an error if one is missing.

Continuing with different settings¶

Often you want to continue from a saved temperature profile but change something — a different time_delta or time_max, or a different module combination (for example, equilibrate first, then start a parameter study from the equilibrated state). Use the two keep flags to stop the snapshot from overwriting the parts you want to change:

snapshot = "results/equilibrated_snapshot.csv"
_snapshot_keep_sim    = true   # use my new default.ini / run.ini values
_snapshot_keep_module = true   # use my new module .ini values

With a flag set to true, MoCSI loads the temperature field from the snapshot but keeps your current configuration for that category — so you simply edit your .ini files as usual and the run continues from the saved profile.

Tip

Set the flags independently. Keep _snapshot_keep_sim = false (take timing/grid from the snapshot) while setting _snapshot_keep_module = true to swap only the physics modules, or vice versa.

Important

The simulation time is part of the field data and is always restored from the snapshot, independently of the keep flags. A resumed run therefore starts at the snapshot’s elapsed time. Snapshots are written at the end of a run, when the elapsed time has reached time_max, so to continue you must set a time_max larger than that value — otherwise the termination criterion is already satisfied and the run stops immediately after loading.

Snapshot file format¶

The on-disk layout depends on whether MoCSI was built with MPI, because the field data is human-readable text in the serial build but binary in the MPI build.

Serial build — a single file¶

A serial snapshot is a single text file with two labelled blocks:

FIELDDATA:
name_of_field,time_in_seconds,field_value_1,field_value_2,...,field_value_n
INIFILEDATA:
SimulationConfig$param_name_1 = value
SimulationConfig$param_name_2 = value
.
.
.
ModuleName_1$param_name_1 = value
.
.
.
ModuleName_k$param_name_l = value

FIELDDATA holds the saved field(s): the field name, the simulation time in seconds, and the per-node values.
INIFILEDATA holds every configuration value, namespaced by source. SimulationConfig$… entries are the merged default.ini + run.ini values; ModuleName$… entries are each module’s .ini values.

MPI build — two files¶

When built with MPI the field data is written in parallel and cannot share a text file with the ASCII configuration, so a snapshot is split into two files:

the file named by snapshot_save_file contains only the INIFILEDATA: block (the ASCII configuration, exactly as above), and
a companion binary field file — named by inserting _fields before the extension (e.g. my_run_snapshot.csv → my_run_snapshot_fields.csv) — holds the field values written via MPI-I/O, followed by a binary footer recording the field type, simulation time, and the byte lengths of the data and footer blocks.

Both files are written to the snapshot location and are both required to restart; keep them together.

Notes:

By default the field data saves only the independent variable of the equation being solved — currently the temperature. This is fixed by the set of field names in SnapshotCreator and is not configurable through an .ini key.
The SimulationConfig block intentionally merges default.ini and run.ini into one section; the snapshot does not split them back out.
The INIFILEDATA: block also records build metadata that is not present in any .ini file: SimulationConfig$build.version (the MoCSI version) and SimulationConfig$build.git (the git revision), injected at runtime. A snapshot therefore documents exactly which MoCSI build produced it.

Where to go next¶

INI options — the full configuration reference (see the Snapshot options section).
User workflow — setting up and launching a run.
Core structure — how snapshots fit into the overall architecture.