Record, save and restart a simulation
Use this workflow to retain a physical-time history and continue a supported
calculation from its accepted state. Start with the
first CPU experiment for executable native state and
physics setup. These concrete particula.execution imports describe development
0.3.1; they do not change existing runnable calls or select physical assumptions
for you. Choose tolerances using the
numerical-method guide.
Select an execution owner
Section titled “Select an execution owner”| Owner | Advance and observe | Exact restart profile |
|---|---|---|
CPUSimulation |
run_until; native CPU runnable cycles |
Known native processes, CPU RNG, auxiliary fields and diagnostics |
CondensationODE |
run_until; CPU RK23, ROS2 or ROS3 accepted steps |
Scaled state, controller and supported forcing table |
GPUCondensationODE |
run_until; Warp CPU or CUDA RK23/ROS3 |
Same explicit device, scaled device state and controller |
GPUCoupledSimulation |
Fixed complete event cycles, optional resident CUDA adaptation, explicit snapshots | Canonical event/RNG state plus condensation configuration, controls, execution profile and ordering |
SplitSimulation |
run_until; complete sequential or Strang cycles |
Nested built-in condensation/dilution flows and their controls |
PreparedSimulation |
run_prepared; unchanged fixed step grid |
Existing qualified prepared configuration and canonical resident checkpoint |
The CPU owner uses native NumPy execution without launching Warp. Adaptive condensation supports the physical profiles in the numerical-method guide; it does not add adaptive stochastic coagulation or latent-heat integration. Prepared execution retains its existing supported stochastic and latent-heat profiles. Custom deterministic split callbacks may run but cannot be saved as exact restart configurations. Unknown CPU processes are rejected. Registered GPU extensions require the caller’s matching registry when resuming; an archive never supplies executable adapters.
Record selected variables at physical times
Section titled “Record selected variables at physical times”Given a configured simulation, request absolute times in seconds:
from particula.execution.recording import Recorder, run_until
history = Recorder( ("number_density", "particle_mass_density", "gas_concentration"), max_records=1000, max_bytes=16 * 1024 * 1024,)run_until(simulation, 10.0, output_times=[0.0, 2.0, 5.0], recorder=history)arrays = history.arrays()assert arrays["time"][-1] == 10.0The final time is always an output target. The initial time is recorded only when requested. Times must be finite, nonnegative and strictly increasing; requests older than the current accepted time are skipped when continuing. Reuse the same recorder across calls to omit an equal-time joining row. A new recorder starts a separate history. Layout or species changes require a new recorder; matching array widths alone do not establish matching species.
run_until bounds steps at each requested time, without interpolation. Only
accepted complete steps or split cycles are visible, never RK stages, rejected
trials or Strang half cycles. Shortened steps can change a numerical or
stochastic trajectory. Exact continuation and passive-observer invariance
require the same future step/output schedule; compare different schedules
against an independent accuracy target or stochastic uncertainty.
| Variable | Unit | Axes after time |
|---|---|---|
number_density |
m⁻³ | box |
particle_mass_density |
kg m⁻³ | box, material |
gas_concentration |
kg m⁻³ | box, gas |
temperature, pressure |
K, Pa | box |
volume |
m³ | box |
particle_masses |
kg per particle | box, slot, material |
particle_concentration |
native population measure | box, slot |
particle_charge |
elementary charges | box, slot |
Volume is always retained. Slot variables are opt-in: resolved concentration is represented count, discrete concentration is number density, and a PDF is dN/dr. Metadata retains dimensions, units, gas order and molar masses, partitioning, material densities and population interpretation. Rows and returned arrays are detached. The byte limit bounds retained numerical data, including times; Python overhead and serialization copies require extra memory. A capacity failure leaves accepted physics intact and appends no partial row.
Save analysis output
Section titled “Save analysis output”save_analysis(history, path, ...) saves on demand. To save after each requested
observation, wrap the recorder in AnalysisWriter and pass it to run_until:
from particula.execution.analysis_io import AnalysisWriter, load_analysis
writer = AnalysisWriter( history, "growth.analysis", configuration={"case": "my explicitly configured growth experiment"}, numerical_settings={"output_times_s": [10.0, 15.0, 20.0]}, source_identity={"study": "growth-study", "input_revision": "case-1"},)run_until(simulation, 20.0, output_times=[10.0, 15.0], recorder=writer)result = load_analysis("growth.analysis")assert result.arrays["time"][-1] == 20.0Replace the illustrative provenance with the actual physical parameters,
process ordering, species maps, tolerances, source revision and input identities.
These dictionaries must contain finite JSON data; the writer cannot infer your
scientific assumptions. Package version and scientific array metadata are added
automatically. compressed=False selects uncompressed numeric payloads.
The versioned single-file ZIP/JSON/NPY format is intended for bounded histories. It retains numeric arrays without pickle, checks hashes, duplicate members, array headers and size budgets, and does not execute file-named code. It is not a chunked database for unlimited particle trajectories. Analysis and restart schemas are distinct: a history cannot masquerade as an exact checkpoint.
A save writes and flushes a temporary file before atomic replacement. If writing
fails, the previous complete file remains and the new in-memory row is retained.
After resolving the storage problem, call writer.flush() to retry without
advancing physics or duplicating that row. File failure does not roll physics
back. Use separate output paths for separate studies and keep the recorder under
one caller’s control while recording or saving.
Apply a reproducible environmental history
Section titled “Apply a reproducible environmental history”For CPU or GPU adaptive condensation, pass an immutable table as forcing=:
from particula.execution.forcing import EnvironmentForcing
forcing = EnvironmentForcing( times=[0.0, 5.0, 10.0], temperature=[298.15, 303.15, 298.15], # K pressure=101325.0, # Pa mode="step",)Times start at zero and increase strictly. Temperature and pressure accept a
scalar, one value per time, or a time-by-box matrix. A single column broadcasts
across boxes. Values must be positive and finite. mode="linear" interpolates
between rows; mode="step" holds the current row. The last row is held forever.
The table is copied into immutable data and is included in supported checkpoints.
Adaptive integration stops at every knot even when no output was requested
there. Endpoint stages finishing the previous segment use that segment’s
left-hand environment; an accepted snapshot at the knot shows the new,
right-continuous environment. This prevents an RK endpoint stage from sampling
the next step’s discontinuity. Built-in condensation_flow(..., forcing=forcing)
also makes the outer split cycle stop at knots. Refine the outer step separately
when checking splitting accuracy.
A pure callable forcing remains available for adaptive execution and evaluates
at absolute stage times. It must not consume RNG or mutate external state.
Its discontinuity boundaries and one-sided values remain the caller’s
responsibility, and it has no supported exact disk identity. Prepared GPU
forcing instead uses its existing explicit environment-update interface;
run_prepared does not install this adaptive table automatically.
Restart accepted CPU or adaptive GPU state
Section titled “Restart accepted CPU or adaptive GPU state”For an adaptive CPU simulation and its matching strategy:
from particula.execution.cpu_restart import ( checkpoint_condensation, load_cpu_checkpoint, resume_condensation, save_cpu_checkpoint,)
save_cpu_checkpoint(checkpoint_condensation(simulation), "growth.restart")resumed = resume_condensation(load_cpu_checkpoint("growth.restart"), strategy)assert resumed.time == simulation.timeCPUSimulation instead supplies simulation.checkpoint() and resumes with
CPUSimulation.resume(load_cpu_checkpoint(path), process). It retains the
accepted native state, process configuration, time/cycle count, timestep,
CPU RNG, supported extension fields and additive ledgers, and latent-energy
diagnostics. State and RNG from a failed current cycle are discarded together.
For SplitSimulation, use checkpoint_split(simulation) and
resume_split(load_cpu_checkpoint(path), group) from
particula.execution.split_restart, with the same CPU save function. The
caller-supplied group must match names, nesting, ordering, physics and controls.
The checkpoint is at a complete cycle; component controllers already restart
at each cycle, so there is no hidden half-step controller to recover.
For a GPU adaptive owner, use the distinct functions in
particula.execution.gpu_restart:
from particula.execution.gpu_restart import ( checkpoint_gpu_condensation, load_gpu_checkpoint, resume_gpu_condensation, save_gpu_checkpoint,)
save_gpu_checkpoint(checkpoint_gpu_condensation(gpu), "gpu-growth.restart")gpu_resumed = resume_gpu_condensation( load_gpu_checkpoint("gpu-growth.restart"), strategy, device="cuda:0",)assert gpu_resumed.time == gpu.timeAdaptive records retain exact scaled coordinates and tolerances, accepted time, next proposed step, last error, work counters and forcing. Scratch stages are recreated. GPU capture of a checkpoint explicitly downloads state; loading its data alone does not allocate a device owner. Resuming uploads to the explicitly selected, exactly compatible saved device, including CUDA UUID identity. There is no cross-device continuation or hidden fallback.
Adaptive GPU checkpoint records use schema 5. This includes material-coupled ROS3, the expanded thermodynamic profile, and exact restoration of unchanged physical coordinates during unscaling. Coupled records use schema 3, which retains the selected resident or transferred execution policy and the fixed parallel reservoir-reduction order. Earlier adaptive GPU records are rejected rather than resumed with different numerical semantics. This version is distinct from the prepared resident checkpoint and the outer archive format. Retain the earlier checkout to continue an older run.
CPU disk restart requires matching package and NumPy versions. GPU restart also requires matching Warp and the existing device/configuration contract. Unsupported schemas, changed physics, unknown records and incompatible devices reject; there is no guessed migration of old records. Loaders decode known data records; resume performs owner-specific configuration and state validation before use. These strict compatibility checks do not replace retaining the exact code and inputs of a research study, especially with a modified development checkout.
Observe and restart prepared GPU runs
Section titled “Observe and restart prepared GPU runs”Given a supported process and native aerosol, explicitly choose downloads:
from particula.execution.checkpoint_io import load_checkpoint, save_checkpointfrom particula.execution.prepared_recording import PreparedObserver, run_prepared
prepared_history = Recorder()with process.prepare(aerosol, device="cuda:0", time_step=0.1) as prepared: observer = PreparedObserver( prepared, prepared_history, download="diagnostics", ) run_prepared( prepared, 1.0, output_times=[0.0, 0.5], observer=observer, ) save_checkpoint(prepared.checkpoint(), "prepared.restart")
with process.resume(load_checkpoint("prepared.restart"), device="cuda:0") as continued: observer = PreparedObserver( continued, prepared_history, download="diagnostics", ) run_prepared( continued, 2.0, output_times=[1.0, 1.5], observer=observer, )assert prepared_history.arrays()["time"][-1] == 2.0Every output and final time must lie on the original fixed grid. Validation rejects off-grid requests before stepping; it never changes the timestep to reach an observation. Labels are computed from initial time plus integer step count times timestep, with floating-point roundoff admission. Older requests are skipped and equal-time joins do not download or append a duplicate observation.
Constructing PreparedObserver downloads one full snapshot to bind species and
layout metadata. download="diagnostics" then transfers existing per-box/species
reductions and environmental values, without full slot arrays. Requesting slot
variables requires download="snapshot", which downloads the full native state
at each output. initial_snapshot_downloads and observation_downloads count
calls, not bytes. Adaptive GPU run_until always takes a full snapshot at each
new requested observation. Account for these transfers in workload timings.
A prepared observer may also wrap an AnalysisWriter. All host observation,
compression and serialization occur outside active CUDA capture. Qualified
captured replay can run between observations; no automatic capture, recapture
or CPU emulation is introduced. Restart retains canonical resident bytes,
managed RNG streams, required auxiliary fields and process continuation data;
CPU inspection carriers are not the restart authority. Registered extensions
require a matching explicitly supplied registry. See
prepared execution and
resident checkpoints for their lifecycle and
configuration restrictions.
Preserve study outputs separately from published documentation bundles. The first CPU experiment demonstrates plotting and an exact future-state check after restart; its publication retains compact plot data rather than full particle states.
Explore this topic: CPU workflows · GPU workflows