GPU resident graph capture
For the public runnable workflow, use
PreparedSimulation.capture().
The contract below describes the separate concrete canonical resident scheduler.
Native resident graph capture is concrete, direct-import-only machinery in
particula.execution.graph_capture; it is not a package or top-level API. The
only eligible path is a caller-qualified, non-CPU native Warp CUDA device. CPU
and Warp CPU are neither capture paths, capture evidence, nor fallback or
emulation paths. The maintained qualification walkthrough
owns composition code; this runbook records operations rather than providing a
second runnable recipe. Checkpoint and restart limits are defined by the
GPU resident checkpoint contract.
Ordered setup and capture
Section titled “Ordered setup and capture”Fail closed in this order:
- Resolve native-CUDA capability and probes before CPU fixture construction,
resident imports, CPU upload, or allocation. Only an unavailable capability
or probe outcome is a clean skip: do no setup or capture and do not fall
back. Once
qualify_prepared_resident_graph_capture()is attempted, a qualification rejection raisesValueError; it is not a clean skip. - Construct the exact ACTIVE resident session, pinned resource registry, and closed step guard.
- Register the complete fixed inventory; build exact views, capacities, and
CaptureResourceRequirements; then publish that exact resource set once withGPUResourceRegistry.prepare_capture_resources()before final request construction. - Create and attach the exact final request, signature, lifecycle, and binding.
Explicitly initialize the
coagulationandwall_lossresident streams before preparation and capture. Normal replay never initializes or resets streams; an explicit resident-stream lifecycle operation is the only reset boundary. - Prepare the resident simulation, validate the published resource set,
qualify the exact READY binding, and explicitly capture it to reach
CAPTURED. Qualification is read-only and its rejected
ValueErrorleaves the existing lifecycle available as defined by that lifecycle.
Replay requires an authentic issued record; the exact attached request, session,
registry, and closed guard; an ACTIVE session; qualified CUDA availability; a
CAPTURED lifecycle; an unchanged compatible signature; and the matching duration.
One call is one replay. Before .numpy(), checkpointing, or any other host
observation, call prepared.synchronize() on the retained
PreparedResidentSimulation. This explicitly waits for device work and reports
coagulation work-budget failures, faulting the resident lifecycle on rejection.
A bare warp.synchronize_device(...) only waits; it does not inspect those
application diagnostics. Earlier or later processes in a low-level schedule
are not rolled back when coagulation rejects its own operation.
Structural changes require fresh capture
Section titled “Structural changes require fresh capture”Compatibility is identity based and checks the following first-drift order.
Replacing any listed item fails closed and invalidates replay. Recovery is
ordered: retire the invalidated metadata, renew it to READY, prepare and
qualify the renewed binding, then explicitly capture before replay is possible.
| First-drift group | Representative replacement |
|---|---|
request |
Final resident request object |
session |
ACTIVE resident session |
device |
Session device declaration |
dimensions |
Fixed resident dimensions |
primary_containers |
Particle, gas, or environment container |
primary_arrays |
A particle, gas, or environment array |
resource_views |
Process view, scratch sidecar, or communication view |
graph |
Process graph or graph declarations |
schedule |
Resolved schedule or declarations |
schedule_order |
Ordered schedule-node identifiers |
diagnostics |
Diagnostic operation, registration, or output |
communication |
Communication node, map, buffers, or final volumes |
configurations |
Process configuration, capture requirements, or published set |
rng_resources |
Coagulation or wall-loss RNG sidecar |
Same-object payload updates, active/free-slot changes, and advancing resident RNG words are non-triggers. They remain compatible because the tracked identities have not changed.
Lifecycle and incidents
Section titled “Lifecycle and incidents”| State | Replay | Next action |
|---|---|---|
READY |
No | Prepare, qualify, and explicitly capture. |
CAPTURED |
Yes, after every replay precondition | Replay, or replace an identity to invalidate before retirement. |
INVALIDATED |
No | Retire stale metadata, renew it to READY, then prepare, qualify, and explicitly capture. |
FAULTED |
No | Do not retry; close and create fresh setup as needed. |
RETIRED |
No | Renew the retired binding to READY, then prepare, qualify, and explicitly capture. |
CLOSED |
No | Terminal; create a fresh session and binding. |
Structural drift invalidates capture. A writer-capable capture or replay failure faults state and promises no rollback or retry. A read-only qualification or admission rejection leaves the existing state available as defined by its lifecycle. Lifecycle ownership releases every opaque native handle exactly once; a release failure does not restore provenance or trigger retry, rollback, or recovery. Close graph capture before closing the session; terminal session, close, discard, or finalize changes stale the capture binding.
Retirement, renewal, and restart
Section titled “Retirement, renewal, and restart”Retire stale or invalidated metadata. Renew only a retired binding. Renewal creates READY metadata only: it is neither replay nor recapture. Re-prepare, re-qualify, and explicitly capture after renewal.
Concrete operations
Section titled “Concrete operations”Import these operations directly from particula.execution.graph_capture; none
is a package or top-level export. Resolve capability with
resolve_graph_capture_capability(), then qualify a prepared READY binding
with qualify_prepared_resident_graph_capture(). Capture the qualification with
capture_prepared_resident_graph() and replay its authentic issued record with
replay_captured_resident_graph(). For an invalidated resident binding, call
retire_resident_graph_capture(), then
renew_resident_graph_capture() to produce its fresh READY lifecycle. Use
close_resident_graph_capture() for ordered teardown before closing the
resident session.
Checkpoint restart and terminal closure require a fresh session, resource and array identities, qualification, setup, and capture. Restart restores resident bytes and RNG continuation only; it creates fresh identities and no graph handles.
Boundaries and prohibitions
Section titled “Boundaries and prohibitions”Native handles are opaque, nonserializable, and uncheckpointed. There is no stale reuse, migration, serialization, cross-device replay, CPU or Warp-CPU capture/emulation/fallback, hidden transfer/readback/synchronization, automatic recapture/retry/rollback, resizing, compaction, dynamic shapes, dynamic order, dynamic maps, or portable performance claim.
Reproduction commands
Section titled “Reproduction commands”Run focused assertions before the full-package coverage check. The CUDA-selected row is optional pass-or-clean-skip evidence only; it is never CPU or Warp-CPU substitution.
pytest examples_tests/gpu_resident_graph_capture_docs_test.py -q --no-covpytest particula/execution/tests/graph_capture_test.py -q --no-covpytest particula/execution/tests/captured_full_loop_test.py -q --no-covpytest particula/execution/tests/captured_full_loop_test.py -q \ -m "warp and cuda" --no-covpytest --cov=particula --cov-report=term-missing --cov-fail-under=80npm --prefix website run buildRelevant repository sources are
particula/execution/tests/graph_capture_test.py,
particula/execution/tests/captured_full_loop_test.py, and
examples_tests/gpu_resident_graph_capture_docs_test.py.
Explore this topic: Resident execution