> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prodexlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots

> Frozen copies of a simulation model that anchor reproducibility, comparison, and experiments.

## Overview

A **Snapshot** is a complete, frozen copy of a simulation model at a point in time. Think of it as **"Save As" for a model**: not a diff or a delta, but a self-contained version the engine can simulate on its own, no matter what the live working model looks like later.

Snapshots are how you keep simulation reproducible. Once a Snapshot exists, you can re-run it, hand it to a teammate, or compare it against another configuration in an [Experiment](/product/experiments), so the configuration won't drift while you keep editing the live model.

## What's Inside a Snapshot

A Snapshot **embeds** everything needed to re-run the configuration. Nothing is referenced by name, so there's no risk of a library item changing under it.

| Field            | Contents                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `name`           | The name you gave the snapshot (required)                                                                                            |
| `description`    | Optional description                                                                                                                 |
| `model_registry` | The **full recursive registry**: the model plus its embedded entities, constants, lookup tables, and sub-models, keyed by model slug |
| `schedule`       | The schedule active when the snapshot was captured: **embedded as a full object**, not referenced (null if none was active)          |
| `captured_at`    | Timestamp                                                                                                                            |
| `schema_version` | Internal versioning for migration of stored snapshots                                                                                |

Editing a library item (an entity, constant, lookup table, or schedule) **does not affect existing snapshots**. The snapshot carries its own frozen copies. This is what makes runs against a snapshot reproducible.

Snapshots are stored per model at `factory/models/{model-slug}/snapshots/{slug}.json` — the slug is the filename and the owning model is the parent directory. They are strictly **capture-only artifacts**: direct writes, edits, and renames are rejected at the platform boundary, so there's no way to hand-author or templatize a snapshot file. To "rename" one, re-capture under a new slug.

## Saving a Snapshot

Click the **disk icon** in the Modeler's top bar. The tooltip reads *"Save current work as snapshot."*

The dialog (titled *Create Snapshot*, with a Camera icon) has two fields:

* **Snapshot Name** (required): short, descriptive. Placeholder: *"e.g., Before adding resources"*
* **Description** (optional): explains what's changed since the last save. Placeholder: *"Describe what changes were made..."*

Click **Create Snapshot** to commit. The Snapshot is immediately available everywhere it's needed: the snapshot history picker, and the **Add snapshot** dropdown inside any Experiment.

<Note>
  **Save is gated by validation.** If the working model has validation errors, the Save button is disabled with the tooltip *"Fix model validation errors before saving."* You can't snapshot an invalid model + schedule: capture is refused until the errors are fixed.
</Note>

Snapshots saved from the disk icon are yours. When Dexter iterates on a configuration in chat, the working convention is **versioned slugs rather than overwriting names** — `baseline-200`, `baseline-500` — so each capture stays a distinct, trustworthy point-in-time. Orphaned snapshots from earlier iterations are harmless; they don't need cleanup. If you want Dexter to manage the save points itself, ask it directly (*"save a snapshot of this configuration"*).

<Warning>
  **Don't capture in the same breath as an edit.** A capture issued in the same execution as a model edit reads the *pre-edit* state; the platform now guards this and refuses with *"Snapshot captured stale model state ... and was not written"* rather than writing a mislabeled file. Save first, capture second — and if a snapshot's label ever seems off, inspect the snapshot's contents before trusting it.
</Warning>

## Loading and Removing a Snapshot

The **history icon** next to the disk button opens the snapshot picker (it only renders when at least one snapshot exists for the current model). The tooltip shows the current count (e.g., *"7 snapshots"*). The picker has a search box (*"Search snapshots..."*) that filters live as you type, and rows grouped by recency (*Today*, *Previous 7 Days*, etc.).

* **Click a row** to load that Snapshot onto the canvas. Toast: *"Snapshot loaded successfully."*
* **Hover a row** to reveal a trash icon.

Clicking the trash icon opens a confirmation dialog: *"Delete Snapshot: Are you sure you want to delete '\{name}'? This action cannot be undone."* There's no undo after confirmation.

<Warning>
  **Deleting a snapshot referenced by an experiment corrupts the experiment.** If you delete a snapshot that any active experiment still lists in `selected_snapshots`, every subsequent write into that experiment fails — the whole experiment becomes unwritable, across every one of its subdirectories, and recovery is manual and painful. The rule applies to *any* deletion path, including asking Dexter. **The best prevention isn't a safe-removal sequence — it's not deleting at all**: capture new versions under versioned slugs and let old snapshots sit; orphans are harmless. If you truly must delete, first edit every experiment that references the snapshot to drop its slug from `selected_snapshots`.
</Warning>

## Autosaves

**Loading a snapshot is not destructive.** Before a restore replaces the live working model, ProDex first autosaves the current workspace — and the restore hands back `autosave_*` undo handles pointing at that pre-load state. Autosaves appear in the same picker as named Snapshots, and you can load or delete them like any other.

So the worst case of an accidental load is one extra click: restore the autosave and you're back where you were. There's no manual autosave trigger or configuration — for deliberate save points, capture a named Snapshot.

## Asking Dexter to Manage Snapshots

You can have [Dexter](/product/ai-assistant) save, list, and restore Snapshots from chat without leaving the page you're on. Prompts that work:

* *"Save the current state as a snapshot called `baseline-4-techs` with description `Pre-expansion baseline`."*: creates a new named Snapshot.
* *"Show me the snapshots on this model."*: lists them as a markdown table.
* *"Restore `baseline-4-techs`, but show me the diff first."*: a restore supports a **dry-run** that returns a per-bundle diff of what would change without touching anything — the "peek before applying" workflow.
* *"Delete the snapshot `baseline-4-techs`."*: removes it.

Under the hood these map to the capture/restore verbs (`experiments.capture` / `experiments.restore`, also re-exported as `simulation.capture` / `simulation.restore` for mid-build save points) — capture and restore are the *only* ways snapshots are created or loaded.

**Deleting is discouraged, and Dexter's delete has no confirmation step.** A deletion is a raw file removal — the experiment-corruption hazard above applies in full. Use specific names rather than vague references like *"delete the old one"*, and prefer leaving old snapshots in place over deleting them.

## Snapshots in Experiments

Snapshots are the unit of comparison in [Experiments](/product/experiments). Open the Experiments section, pick an experiment, and the **Snapshots** sidebar lets you add Snapshots from the same model side by side. Hit Run and ProDex simulates each Snapshot and lays the KPIs out for comparison.

Since each Snapshot embeds its own schedule, an experiment row doesn't separately select a schedule: the snapshot already carries the timing it should run against. To compare the same model under two demand profiles, capture two snapshots while each schedule is active and add both to the experiment.

## Snapshots vs. The Live Working Model

The live working model is what you edit on the canvas: every drag, drop, and field change writes to it. Snapshots are frozen copies; they don't change when the working model changes afterward.

Experiments only run against Snapshots, never against the live model directly: that's the guarantee that makes a comparison reproducible. Snapshots aren't branches, though: there's no merge-back operation. If a Snapshot represents a configuration you want as your new baseline, apply those changes to the working model manually.

<Note>
  **Snapshots are scoped to their parent model.** They live under that model's directory and cannot be loaded into a different model — a restore targets the model that owns the snapshot. To migrate a configuration across models, recreate it manually rather than expecting to point an existing snapshot at a new home.
</Note>

## Snapshots and Monte Carlo

A [Monte Carlo](/product/monte-carlo) batch sweeps random seeds against whatever model + schedule configuration is loaded at queue time. Snapshots are the natural way to pin that configuration: load the snapshot you want to evaluate, queue Monte Carlo against it, and every seed runs against the same frozen model. The configuration is captured at queue time, so editing the model afterwards doesn't affect the in-flight batch.

## When to Save a Snapshot

Use Snapshots as deliberate save points, not just rolling backups:

* **Before significant changes.** Restructuring routing, changing capacities, altering processing times: snap first so you have a clean baseline to compare against.
* **When you have a known-good configuration.** A model tuned to match observed floor data deserves a named save; it's your reference point for everything that follows.
* **Before running an experiment.** Experiments compare Snapshots: pin the configurations you want to compare with names you'll recognize weeks later.
* **At natural milestones.** End of a calibration cycle, after incorporating new production data, before a product mix shift.
* **Before sharing results.** Each experiment case's run traces back to the Snapshot it was simulated from — and a Monte Carlo batch queued from a snapshotted configuration ties back the same way — so that's your audit trail. (A plain [run](/product/runs) executes against the live working model, not a snapshot.)

Snapshots are immutable once saved. The same [validation](/reference/validation) limits apply at capture time: invalid models can't be snapshotted.