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