I/O

save_hdf5(results, path)

Save simulation results to an HDF5 file.

File structure (metadata schema v3; files without schema_version were written by mcising <= 0.23.0 and load through a legacy path; schema 2 files lack the statistics subgroup)::

results.h5
├── metadata/
│   ├── schema_version  (attribute, int)
│   ├── version         (attribute, mcising version that wrote the file)
│   ├── config_json     (attribute, full config as JSON)
│   ├── seed            (attribute) [when a config is recorded]
│   ├── mode            (attribute) [when a config is recorded]
│   ├── algorithm       (attribute) [when a config is recorded]
│   ├── git_commit      (attribute) [when built from a git checkout]
│   └── elapsed_seconds (attribute) [when known]
├── T=2.269/
│   ├── configurations  (n_samples x L x L, int8)
│   ├── energy          (n_samples, float64)
│   ├── magnetization   (n_samples, float64)
│   ├── correlation_function  (n_distances, float64) [optional]
│   ├── correlation_distances (n_distances, float64) [optional]
│   ├── correlation_length    (n_samples // correlation_interval, float64)
│   │                         [optional]
│   └── statistics/     (derived observable estimates, attributes:
│       n_samples, tau_int, and value + ``*_error`` pairs for
│       energy, magnetization, abs_magnetization, specific_heat,
│       susceptibility, binder_cumulant; non-finite values are
│       omitted. Written for external inspection only — loading
│       recomputes statistics from the raw series.)
└── ...

Parameters:

Name	Type	Description	Default
results	SimulationResults	The simulation results to save.	required
path	str or Path	Output file path (should end in .h5 or .hdf5).	required

---

load_hdf5(path)

Load simulation results from an HDF5 file.

Restores the full provenance record (version, seed, mode, algorithm, and the SimulationConfig object) for schema v2 files; legacy files (mcising <= 0.23.0) load with a best-effort config reconstruction.

Parameters:

Name	Type	Description	Default
path	str or Path	Input file path.	required

Returns:

Type	Description
SimulationResults	The loaded simulation results.

Raises:

Type	Description
ConfigurationError	If the file's metadata schema is newer than this mcising supports.

---

save_json_summary(results, path)

Save a JSON summary of simulation results (no large arrays).

Carries the same provenance fields as the HDF5 metadata group (version, schema_version, seed, mode, algorithm, git_commit, config); fields whose value is unknown are omitted rather than written as null.

Parameters:

Name	Type	Description	Default
results	SimulationResults	The simulation results to summarize.	required
path	str or Path	Output file path.	required

---

checkpoint_run(sim, path, *, show_progress=True, resume=False, checkpoint_interval=1)

Run a simulation with periodic HDF5 checkpointing.

After every checkpoint_interval temperatures complete, results are appended to the checkpoint file. If the process is interrupted, already-completed temperatures are preserved.

Checkpoint granularity depends on the execution mode: cooldown saves after each temperature; independent mode computes the batch in parallel and saves every temperature when it returns; parallel tempering is all-or-nothing (the replicas form one coupled ensemble, so a partial ladder cannot be resumed).

Parameters:

Name	Type	Description	Default
sim	Simulation	Configured simulation instance.	required
path	str or Path	HDF5 checkpoint file path.	required
show_progress	bool	Whether to display progress bars.	True
resume	bool	If True and the file exists, skip already-completed temperatures. The stored config must match sim.config (temperatures may differ, so a scan can be extended on resume). Resuming a file written by mcising <= 0.23.0 keeps its original metadata schema: a file records the code that created it.	False
checkpoint_interval	int	Save checkpoint every N completed temperatures. Default is 1 (save after every temperature). Use higher values for speed at the cost of less frequent saves.	1

Returns:

Type	Description
SimulationResults	Complete simulation results (including resumed data).

Raises:

Type	Description
ConfigurationError	When resume=False but path already exists; on resume, when the checkpoint was written with a different config than sim.config (or its config record is unreadable), or when a parallel-tempering ladder is only partially complete.