# 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.

<div class="step-flow">
  <a class="step-card" href="#creating-a-snapshot">
    <span class="step-icon">💾</span>
    <div class="step-body">
      <b>Create</b>
      <span>Save the full state at the end of a run</span>
    </div>
  </a>
  <a class="step-card" href="#restarting-from-a-snapshot">
    <span class="step-icon">▶️</span>
    <div class="step-body">
      <b>Restart</b>
      <span>Continue a new run from a saved state</span>
    </div>
  </a>
  <a class="step-card" href="#snapshot-file-format">
    <span class="step-icon">📄</span>
    <div class="step-body">
      <b>Format</b>
      <span>What's inside the snapshot file</span>
    </div>
  </a>
</div>

## 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](ini_options.md) (*Snapshot options* section) for where these sit among the other keys.

## Creating a snapshot

Set `snapshot_save_file` to a path on your system:

```ini
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](#snapshot-file-format).
:::

## Restarting from a snapshot

Point `snapshot` at a valid snapshot file:

```ini
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:

```ini
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](ini_options.md) — the full configuration reference (see the *Snapshot options* section).
- [User workflow](user_workflow.md) — setting up and launching a run.
- [Core structure](../mocsi_overview/core_structure.md) — how snapshots fit into the overall architecture.