Snapshots

Snapshots capture the entire state of a running simulation (attributes, timers, scenarios, and protocol settings) so you can restore it later or move it between environments.

The core implements snapshots in spx_core/snapshots/snapshot_manager.py and snapshots.py.

When to use snapshots

• Regression testing: freeze a known-good state before running destructive tests and restore afterward.

• Support diagnostics: capture a user's environment to reproduce issues.

• Warm starts: preload complex rigs with initialized state (e.g., machine is mid-cycle).

YAML & API integration

Snapshots are usually triggered via API (POST /snapshots). YAML controls defaults:

YAML

snapshots:
  directory: /var/spx/snapshots
  auto_on_shutdown: true
  retention: 5

JSON

Fields:

• directory: where to store files (server must have write access).

• auto_on_shutdown: automatically save on orderly shutdown.

• retention: number of snapshots to keep (older files are deleted).

CLI usage

spx snapshots create --name baseline
spx snapshots list
spx snapshots restore --name baseline

The CLI proxies API calls; ensure the server is running and credentials are configured.

What gets stored?

• Attribute values (internal & external).

• Active scenarios and their progress.

• Timer state (current time, step mode).

• Communication adapter overrides.

• Parameter overrides.

• Instance meta_parameters values (when instances are created from templates/meta params).

Sensitive data (credentials, secrets) should be kept out of snapshots; store them in parameters or vault-backed configs.

Import behavior (runtime replace)

When importing with runtime replacement (replace_runtime: true), the server performs additional safety steps:

• Existing runtime children are torn down before rebuilding the system tree (best-effort cleanup for running threads/servers).

• Runtime license/config limits are preserved (for example instance_limit), and imported values are clamped to active runtime limits.

• core_dir, extensions_dir, and runtime directories are preserved when missing in imported data.

UI import dialogs can optionally include or skip run.instances startup directives, so you can import structure without forcing startup state.

Best practices

• Keep snapshot directories on fast storage; large models can produce sizeable files.

• Version snapshots alongside model definitions so they match schema changes.

• Use retention to avoid filling disks.

• Document which tests rely on specific snapshots and refresh them regularly.