GPU resident checkpoints
For public runnable continuation, use prepared checkpoints and resume. The detailed concrete resident schema below remains the underlying continuation authority.
Current controllers create schema-v5 checkpoints with explicit population type
and independent particle-material and gas widths. Schemas v1–v4 reject before
setup or upload; there is no inferred migration. Supported population semantics
are explicit PMF and resolved counts, with independently declared gas width.
Schema-v5 legacy_untagged records and missing population meaning reject before
setup or upload without inferred migration or a schema-version change. PDF
remains unsupported on Warp. Native inspection carriers retain their population
tag; canonical bytes remain restart authority.
Resident communication is a concrete-only closed-map barrier. Communication runs before optional physical volume evolution; both invalidate saturation ratio. Restart creates fresh communication arrays and bindings. Native PMF checkpoints cannot contain particle transport or prescribed volume evolution.
The direct-import-only checkpoint boundary is available from
particula.execution.checkpoint; it is deliberately not exported by
particula.execution or the top-level package. Create a
ResidentCheckpointController for one active ResidentSession, its pinned
GPUResourceRegistry, and its ResidentStepGuard, or use the session’s
checkpoint(registry, guard) and finalize(registry, guard) methods.
checkpoint() is nonterminal and returns a fresh immutable host snapshot.
finalize() is terminal and idempotent only when called again with the exact
bound session, pinned registry, and closed guard. After its first successful
call the session is FINALIZED and later calls with that matching binding return
the cached snapshot without device work; mismatched or invalid bindings are
rejected. Checkpoints are explicit in-memory, same-device recovery only. They
do not serialize to disk, select or migrate a device, synchronize implicitly
during restart, or provide rollback after a device writer has launched.
The snapshot owns immutable canonical bytes for primary arrays and acquired
sidecars, plus detached CPU inspection carriers. Inspection GasData is
intentionally lossy because CPU gas carriers do not contain GPU vapor pressure;
restart uses canonical bytes and restores vapor pressure exactly. Snapshotting
requires approximately one additional host copy of resident payload bytes plus
the detached inspection copies. Restart explicitly requires the compatible
target Device through restart_resident_session(checkpoint, device).
restart_checkpoint is an equivalent concrete-only alias; both require the
same exact compatible device and create fresh session, registry, guard, and
resident-array identities.
Restart compatibility is intentionally exact and fail-closed. It accepts
ResidentCheckpoint records with carrier type "ResidentSession", lifecycle
ACTIVE, complete valid canonical payload descriptors, and an exactly equal
target Device. Schema-v5 checkpoints may contain no communication family or
exactly one complete closed-map GAS or PARTICLES family with matching metadata
and payloads. They always require RNG continuation
metadata, though their published-stream payload collection may be empty when
neither canonical coagulation nor wall-loss resource family is acquired. Their
immutable current uint32 words are restart authority; normal dispatch and
reacquisition neither read them back nor reset them, and only explicit stream
reset derives new words from the root seed for a restored published stream. This
does not prevent normal first acquisition from deriving words for a stream that
was absent from the checkpoint. Finalization terminalizes its source session but
returns an ACTIVE, restartable checkpoint record. Restart creates fresh session,
registry, guard, resident arrays, and communication bindings; it never reuses
source identities or provides fallback. It rejects other versions or carrier
schemas, malformed, incomplete, partial, mixed, or mismatched communication
payloads, non-ACTIVE checkpoint records, and device mismatches; it does not
promise forward or backward compatibility.
Schema-v5 continuation covers the canonical published coagulation
and wall_loss streams; schema-v5 is the current format. Each retained record
includes schema-versioned stable logical-ID, root-seed, and namespace metadata
plus immutable current uint32 words. Those words are the sole continuation
authority, rather than lossy CPU inspection carriers or ordinary resource
payloads. Checkpoint capture is the sole explicit synchronization/readback
boundary for this continuation. Normal scheduling and reacquisition do not
inspect, transfer, synchronize, seed, or reset streams. Before setup, the
checkpoint validates exact bidirectional pairing between acquired coagulation/
wall-loss process families and continuation payloads; continuation-only and
resource-only forms reject. Normal first acquisition initializes a stream only
when its resource family was absent from the checkpoint.
Split-run continuation requires a manual restart into a fresh session with a
frozen configuration and exactly equal supported Device. It excludes CPU,
Warp, CUDA, or other cross-backend replay, cross-device migration; durable
serialization; automatic restart; implicit reseeding, and hidden transfer;
fallback; and rollback after a writer launch.
Normal resident scheduler calls never checkpoint, finalize, or restart. Those operations remain this explicit, concrete-only exact-device boundary; see the GPU-resident deterministic timestep contract for normal-step limits.
For a lazy lifecycle-only walkthrough that does not schedule or launch physics, see the GPU-resident session lifecycle source.
Validate documentation with:
pytest particula/execution/tests/rng_test.py \ particula/execution/tests/rng_invariance_test.py \ particula/execution/tests/checkpoint_test.py -qpytest examples_tests/gpu_resident_session_example_test.py -qnpm --prefix website run buildWarp CPU is the installed-Warp baseline. CUDA evidence is optional and skips cleanly when unavailable.
Explore this topic: Resident execution