Skip to content

Field ownership and transfer policy

This policy preserves the ownership decisions from the container-foundations record. Use native data semantics for representation tags, inventories, independent particle/gas widths, and construction. Use transfers for explicit conversions and execution for supported paths.

Field / group Authoritative owner CPU shape GPU shape Dtype Mutability Round-trip behavior Downstream consumers
ParticleData.masses Owned by ParticleData as the authoritative particle/species mass state (n_boxes, n_particles, n_species) (n_boxes, n_particles, n_species) via WarpParticleData.masses float64 on CPU / wp.float64 on GPU Mutable stored state on both containers Must round-trip without schema drift through to_warp_particle_data() and from_warp_particle_data() Particle property accessors, condensation, coagulation, and resident timestep loops
ParticleData.concentration Owned by ParticleData as authoritative per-box particle concentration/count state (n_boxes, n_particles) (n_boxes, n_particles) via WarpParticleData.concentration float64 / wp.float64 Mutable stored state on both containers Must round-trip without schema change Particle dynamics kernels and any box-batched particle workflow
ParticleData.charge Owned by ParticleData as authoritative particle charge state (n_boxes, n_particles) (n_boxes, n_particles) via WarpParticleData.charge float64 / wp.float64 Mutable stored state on both containers Must round-trip without dtype drift Charged coagulation follow-on work and GPU parity paths that consume particle charge
ParticleData.density Owned by ParticleData and must remain shared-across-boxes material state, not per-box environment state (n_species,) (n_species,) via WarpParticleData.density float64 / wp.float64 Mutable stored state, but shared across boxes Must round-trip as shared 1D species density state Radius, effective-density, and mass-fraction calculations plus GPU particle property calculations
ParticleData.volume Owned by ParticleData as the authoritative per-box simulation-volume carrier (n_boxes,) (n_boxes,) via WarpParticleData.volume float64 / wp.float64 Mutable stored state on both containers Must round-trip without schema change Per-box particle workflows, dilution-style process work, and future environment/process coordination
GasData.name Owned by CPU GasData as authoritative species-name metadata len == n_species Not owned on GPU list[str] Mutable CPU metadata only Does not survive transfer on its own; CPU restore requires caller-supplied ordered species names from external metadata, but the current from_warp_gas_data() implementation validates only name-list length before reconstructing GasData, so ordering must be preserved by the caller rather than inferred or checked during restore CPU-facing reporting, facade compatibility, and any restore path back to GasData
GasData.molar_mass Owned by GasData as authoritative gas species molar-mass state (n_species,) (n_species,) via WarpGasData.molar_mass float64 / wp.float64 Mutable stored state on both containers Must round-trip with the same numeric values inside the documented gas restore boundary (name still requires caller-managed ordered metadata and vapor_pressure still has no CPU field) Gas property calculations, condensation, and GPU gas kernels
GasData.concentration Owned by GasData as authoritative per-box gas concentration state (n_boxes, n_species) (n_boxes, n_species) via WarpGasData.concentration float64 / wp.float64 Mutable stored state on both containers Must round-trip without shape drift Condensation, gas-phase workflows, and future GPU-resident gas updates
GasData.partitioning Owned by GasData as authoritative shared-across-boxes partitioning eligibility state (n_species,) (n_boxes, n_species) via WarpGasData.partitioning bool on CPU / active-device binary wp.int32 on GPU Mutable stored state on both containers CPU transfer expands bool per box; kernels index [box, species]; CPU restore converts back only when every box agrees Condensation partitioning decisions and GPU kernels that require a numeric mask
WarpParticleData numeric mirrors Owned on GPU only as mirrors of authoritative ParticleData fields, not as a separate source of truth Mirrors CPU particle shapes Stored on GPU as declared in WarpParticleData wp.float64 Mutable GPU working state Must restore to the corresponding ParticleData fields without adding or dropping particle schema GPU-resident particle workflows and parity tests
WarpGasData.molar_mass / concentration / partitioning Owned on GPU only as numeric mirrors/helpers of authoritative CPU GasData state (n_species,), (n_boxes, n_species), (n_boxes, n_species) Same declared GPU shapes wp.float64 / wp.float64 / active-device binary wp.int32 Mutable GPU working state CPU partitioning expands per box; kernels index [box, species]; restore recovers bool only when every box agrees GPU condensation and other gas-kernel workflows
WarpGasData.vapor_pressure Owned by no CPU container; treated as GPU-helper/process state rather than authoritative GasData or shipped CPU EnvironmentData state Not owned on CPU containers (n_boxes, n_species) via WarpGasData.vapor_pressure wp.float64 Mutable GPU helper state Must be recomputed from the current authoritative thermodynamic inputs, explicitly provided, or carried as sidecar state; update order must prevent mixed stale/new state, and CPU restore from WarpGasData remains intentionally lossy because from_warp_gas_data() drops it GPU condensation kernels and on-device thermodynamic updates
EnvironmentData.temperature Owned by shipped CPU EnvironmentData, not by ParticleData or GasData (n_boxes,) (n_boxes,) via shipped WarpEnvironmentData float64 on CPU / wp.float64 on GPU Mutable per-box thermodynamic state Round-trips through to_warp_environment_data() / from_warp_environment_data(); resident ownership follows the explicit session lifecycle Parcel/expansion workflows, latent-heat condensation, and other per-box thermodynamic updates
EnvironmentData.pressure Owned by shipped CPU EnvironmentData, not by ParticleData or GasData (n_boxes,) (n_boxes,) via shipped WarpEnvironmentData float64 on CPU / wp.float64 on GPU Mutable per-box thermodynamic state Round-trips through to_warp_environment_data() / from_warp_environment_data(); resident ownership follows the explicit session lifecycle Parcel/expansion workflows, kernel inputs, and per-box forcing profiles
EnvironmentData.saturation_ratio Shipped CPU EnvironmentData helper state; not an independent source of truth separate from current environment and gas state (n_boxes, n_species) (n_boxes, n_species) via shipped WarpEnvironmentData or equivalent GPU environment state float64 on CPU / wp.float64 on GPU Mutable derived/cache state that must be refreshed after invalidating updates Round-trips through to_warp_environment_data() / from_warp_environment_data() and still must be invalidated/recomputed after upstream state changes; process support is governed by the execution guide Latent-heat condensation, parcel expansion, and humidity-coupled follow-on work
Simulation volume ownership Not owned by EnvironmentData; must remain owned by ParticleData.volume (n_boxes,) on ParticleData (n_boxes,) on WarpParticleData float64 / wp.float64 Mutable per-box simulation state under particle container ownership Must continue to round-trip only with particle container conversion helpers Per-box particle state, dilution-style workflows, and timestep orchestration that needs simulation volume

Scientific configuration belongs to processes; physical state belongs to the containers. Single-box storage keeps its leading dimension. Multi-box storage does not imply multi-box CPU strategy execution. Keep fp64 absolute per-species masses unless an approved numerical study supports a representation change; see mass precision.

Source: ownership decision table at repository revision 7b064295037c3c9a137f5dd13c03f4a40da3f11b, originally docs/Features/Roadmap/data-oriented-gpu.md.

Explore this topic: State ownership and transfers