Skip to content

Check CUDA condensation against independent equations

Download Python script

Check CUDA condensation against independent equations

Section titled “Check CUDA condensation against independent equations”

Would a perfectly conserved mass budget detect an incorrect transfer rate? Not by itself. This walkthrough gives you three separate diagnostics and an independent implementation of the specified update. Start with the direct condensation workflow, then follow proposal, availability limiting, and gas update in that order.

The two boxes use 298.15 and 305.15 K and a total interval of 0.08 s, split into four 0.02 s updates. Both gases have an illustrative constant pure vapor pressure of 0.01 Pa. The labels Water and Organic identify material lanes, not calibrated vapor-pressure models for those temperatures.

Two boxes have different temperatures, particle compositions and gas inventories. Water uptake and organic evaporation occur in the same call. An independent NumPy calculation evaluates four equal substeps before the CUDA calculation begins. Separate checks cover transfer, conservation and signed latent energy; passing one does not imply that the others pass.

Reproduce the CUDA figures with python gpu_condensation_parity_walkthrough.py --cuda. The unflagged command retains the portable Warp CPU regression.

Python · section 1
"""Compare an independent NumPy oracle with direct Warp condensation.
This direct-kernel-only walkthrough defaults to Warp's CPU device and makes
all CPU↔Warp transfers explicit. It first completes an independent four
substep NumPy calculation, then optionally runs the low-level Warp route. If
Warp is unavailable, or ``PARTICULA_EXAMPLE_FORCE_NO_WARP=1``, it reports the
completed oracle and does not import a kernel or allocate device state.
Run ``python docs/examples/gpu/direct/gpu_condensation_parity_walkthrough.py`` or
``pytest examples_tests/gpu_condensation_parity_walkthrough_test.py -q
-Werror``. Warp outputs are mutable caller-owned state. ``energy_transfer``
is caller-owned ``(n_boxes, n_species)`` storage, mutated in place with signed
joules, and is not a third returned value. A failed kernel call
may have partially mutated that detached state; discard it and build fresh
sources from the immutable fixture before retrying.
"""
from __future__ import annotations
import importlib
import os
from dataclasses import dataclass
from typing import Any, Literal
import numpy as np
from particula.dynamics.condensation.mass_transfer import (
get_first_order_mass_transport_k,
get_mass_transfer_rate_latent_heat,
)
from particula.gas import GasData
from particula.gas.properties.dynamic_viscosity import get_dynamic_viscosity
from particula.gas.properties.mean_free_path import get_molecule_mean_free_path
from particula.gas.properties.pressure_function import get_partial_pressure
from particula.gas.properties.thermal_conductivity import (
get_thermal_conductivity,
)
from particula.gpu import (
WARP_AVAILABLE,
from_warp_gas_data,
from_warp_particle_data,
to_warp_gas_data,
to_warp_particle_data,
)
from particula.particles import ParticleData
from particula.particles.properties.aerodynamic_mobility_module import (
get_aerodynamic_mobility,
)
from particula.particles.properties.diffusion_coefficient import (
get_diffusion_coefficient,
)
from particula.particles.properties.kelvin_effect_module import (
get_kelvin_radius,
get_kelvin_term,
)
from particula.particles.properties.knudsen_number_module import (
get_knudsen_number,
)
from particula.particles.properties.slip_correction_module import (
get_cunningham_slip_correction,
)
from particula.particles.properties.vapor_correction_module import (
get_vapor_transition_correction,
)
from particula.util import constants
_FORCE_NO_WARP_ENV = "PARTICULA_EXAMPLE_FORCE_NO_WARP"
_TIME_STEP = 0.08
def _readonly(values: np.ndarray) -> np.ndarray:
"""Return an immutable float64 template."""
result = np.asarray(values, dtype=np.float64)
result.setflags(write=False)
return result
def _readonly_bool(values: np.ndarray) -> np.ndarray:
"""Return an immutable Boolean template."""
result = np.asarray(values, dtype=bool)
result.setflags(write=False)
return result
def _warp_array(wp: Any, values: np.ndarray, dtype: Any, device: str) -> Any:
"""Create an explicit same-device Warp array from detached host values."""
return wp.array(values, dtype=dtype, device=device)
@dataclass(frozen=True)
class ParityFixture:
"""Store immutable two-box/two-particle/two-species fp64 templates.
Particle mass arrays use ``(box, particle, species)`` and gas arrays use
``(box, species)``. Species order is shared by masses, gas names, and all
species sidecars. ``concentration`` is a number-density template in m⁻³;
builders multiply it by represented volume to store native resolved counts.
"""
temperature: np.ndarray
pressure: np.ndarray
masses: np.ndarray
concentration: np.ndarray
charge: np.ndarray
density: np.ndarray
volume: np.ndarray
names: tuple[str, str]
molar_mass: np.ndarray
gas_concentration: np.ndarray
partitioning: np.ndarray
thermodynamic_modes: np.ndarray
thermodynamic_parameters: np.ndarray
surface_tension: np.ndarray
mass_accommodation: np.ndarray
diffusion_coefficient_vapor: np.ndarray
latent_heat: np.ndarray
def build_fixture() -> ParityFixture:
"""Build immutable templates with simultaneous uptake and evaporation.
Returns:
Immutable two-box, two-particle, two-species fp64 example fixture.
"""
modes = np.array([0, 0], dtype=np.int32)
modes.setflags(write=False)
return ParityFixture(
temperature=_readonly(np.array([298.15, 305.15])),
pressure=_readonly(np.array([101325.0, 98000.0])),
masses=_readonly(
np.array(
[
[[1.0e-18, 2.0e-18], [2.0e-18, 1.0e-18]],
[[1.5e-18, 1.0e-18], [2.5e-18, 2.0e-18]],
]
)
),
concentration=_readonly(np.array([[2.0e6, 1.0e6], [1.5e6, 2.5e6]])),
charge=_readonly(np.zeros((2, 2))),
density=_readonly(np.array([1000.0, 1100.0])),
volume=_readonly(np.array([1.0e-6, 1.2e-6])),
names=("Water", "Organic"),
molar_mass=_readonly(np.array([0.018015, 0.150])),
gas_concentration=_readonly(
np.array([[2.0e-6, 5.0e-8], [1.5e-6, 8.0e-8]])
),
partitioning=_readonly_bool(np.array([True, True])),
thermodynamic_modes=modes,
thermodynamic_parameters=_readonly(
np.array([[0.01, 0.0, 0.0, 0.0], [0.01, 0.0, 0.0, 0.0]])
),
surface_tension=_readonly(np.array([0.072, 0.035])),
mass_accommodation=_readonly(np.array([1.0, 0.8])),
diffusion_coefficient_vapor=_readonly(np.array([2.1e-5, 8.0e-6])),
latent_heat=_readonly(np.array([2.26e6, 4.0e5])),
)
@dataclass
class OracleInput:
"""Detached CPU state for the independent oracle."""
particles: ParticleData
gas: GasData
fixture: ParityFixture
@dataclass
class WarpSource:
"""Detached CPU state converted only after optional Warp enablement."""
particles: ParticleData
gas: GasData
vapor_pressure: np.ndarray
fixture: ParityFixture
@dataclass
class OracleResult:
"""Record independent final state and direct-kernel-compatible diagnostics."""
masses: np.ndarray
gas_concentration: np.ndarray
total_mass_transfer: np.ndarray
raw_proposal: np.ndarray
energy_transfer: np.ndarray
substeps: tuple["OracleSubstep", ...]
@dataclass(frozen=True)
class OracleSubstep:
"""Record one independent fixed substep for walkthrough diagnostics."""
time_step: float
gas_concentration_before: np.ndarray
raw_proposal: np.ndarray
finalized_transfer: np.ndarray
@dataclass(frozen=True)
class AcceptanceResult:
"""Record one categorized acceptance outcome and diagnostic.
The categories independently report physics parity, inventory
conservation, and signed energy bookkeeping.
"""
category: Literal["physics", "conservation", "energy"]
status: Literal["passed", "failed", "unavailable"]
diagnostic: str
@dataclass
class ExampleRun:
"""Return the oracle, optional Warp observations, and acceptance results.
``acceptance`` always contains physics, conservation, and energy results.
They are marked unavailable when the optional Warp route does not run.
"""
output: list[str]
oracle: OracleResult
particle_data: ParticleData | None = None
gas_data: GasData | None = None
raw_proposal: np.ndarray | None = None
total_mass_transfer: np.ndarray | None = None
energy_transfer: np.ndarray | None = None
vapor_pressure: np.ndarray | None = None
acceptance: tuple[AcceptanceResult, ...] = ()
scratch_buffers: Any | None = None
def _validate_float_fields(
float_shapes: dict[str, tuple[np.ndarray, tuple[int, ...]]],
) -> None:
"""Validate floating-point array shapes and values."""
for name, (values, shape) in float_shapes.items():
if values.shape != shape or values.dtype != np.float64:
message = f"{name} must be float64 with shape {shape}."
raise ValueError(message)
if not np.all(np.isfinite(values)):
raise ValueError(f"{name} must contain only finite values.")
def _validate_signed_fields(
fixture: ParityFixture,
field_names: tuple[str, ...],
strictly_positive: bool,
description: str,
) -> None:
"""Validate a shared lower bound for named fixture fields."""
for name in field_names:
values = getattr(fixture, name)
invalid_values = values <= 0.0 if strictly_positive else values < 0.0
if np.any(invalid_values):
raise ValueError(f"{name} must contain only {description} values.")
def _validate_fixture(fixture: ParityFixture) -> None:
"""Validate canonical example dimensions before detached construction."""
float_shapes = {
"temperature": (fixture.temperature, (2,)),
"pressure": (fixture.pressure, (2,)),
"masses": (fixture.masses, (2, 2, 2)),
"concentration": (fixture.concentration, (2, 2)),
"charge": (fixture.charge, (2, 2)),
"density": (fixture.density, (2,)),
"volume": (fixture.volume, (2,)),
"molar_mass": (fixture.molar_mass, (2,)),
"gas_concentration": (fixture.gas_concentration, (2, 2)),
"thermodynamic_parameters": (
fixture.thermodynamic_parameters,
(2, 4),
),
"surface_tension": (fixture.surface_tension, (2,)),
"mass_accommodation": (fixture.mass_accommodation, (2,)),
"diffusion_coefficient_vapor": (
fixture.diffusion_coefficient_vapor,
(2,),
),
"latent_heat": (fixture.latent_heat, (2,)),
}
_validate_float_fields(float_shapes)
positive_fields = (
"temperature",
"pressure",
"density",
"volume",
"molar_mass",
)
nonnegative_fields = (
"masses",
"concentration",
"gas_concentration",
"surface_tension",
"mass_accommodation",
"diffusion_coefficient_vapor",
"latent_heat",
)
_validate_signed_fields(fixture, positive_fields, True, "positive")
_validate_signed_fields(fixture, nonnegative_fields, False, "nonnegative")
if fixture.partitioning.shape != (2,) or fixture.partitioning.dtype != bool:
raise ValueError("partitioning must be Boolean with shape (2,).")
if (
fixture.thermodynamic_modes.shape != (2,)
or fixture.thermodynamic_modes.dtype != np.int32
):
raise ValueError("thermodynamic_modes must be int32 with shape (2,).")
if np.any(fixture.thermodynamic_modes != 0):
raise ValueError(
"thermodynamic_modes must use constant mode (0) for this oracle."
)
if len(fixture.names) != 2:
raise ValueError("names must contain the two species-aligned labels.")
def _particle_data(fixture: ParityFixture) -> ParticleData:
"""Build non-aliasing particle data with species-aligned mass columns."""
return ParticleData(
masses=fixture.masses.copy(),
concentration=fixture.concentration * fixture.volume[:, None],
charge=fixture.charge.copy(),
density=fixture.density.copy(),
volume=fixture.volume.copy(),
distribution_type="particle_resolved",
)
def build_oracle_input(fixture: ParityFixture | None = None) -> OracleInput:
"""Build detached oracle inputs without aliasing immutable templates.
Args:
fixture: Optional validated immutable template. A canonical template is
built when omitted.
Returns:
Detached CPU particle and gas state for the independent oracle.
"""
fixture = build_fixture() if fixture is None else fixture
_validate_fixture(fixture)
return OracleInput(
particles=_particle_data(fixture),
gas=GasData(
name=list(fixture.names),
molar_mass=fixture.molar_mass.copy(),
concentration=fixture.gas_concentration.copy(),
partitioning=fixture.partitioning.copy(),
),
fixture=fixture,
)
def _copy_oracle_input(source: OracleInput) -> OracleInput:
"""Copy caller-owned oracle state for private mutation during execution."""
return OracleInput(
particles=ParticleData(
masses=source.particles.masses.copy(),
concentration=source.particles.concentration.copy(),
charge=source.particles.charge.copy(),
density=source.particles.density.copy(),
volume=source.particles.volume.copy(),
distribution_type=source.particles.distribution_type,
),
gas=GasData(
name=list(source.gas.name),
molar_mass=source.gas.molar_mass.copy(),
concentration=source.gas.concentration.copy(),
partitioning=source.gas.partitioning.copy(),
),
fixture=source.fixture,
)
def build_warp_source(fixture: ParityFixture | None = None) -> WarpSource:
"""Build separately detached conversion inputs and derived pressure storage.
Args:
fixture: Optional validated immutable template. A canonical template is
built when omitted.
Returns:
Detached CPU conversion source and zeroed derived vapor-pressure storage.
"""
fixture = build_fixture() if fixture is None else fixture
_validate_fixture(fixture)
return WarpSource(
particles=_particle_data(fixture),
gas=GasData(
name=list(fixture.names),
molar_mass=fixture.molar_mass.copy(),
concentration=fixture.gas_concentration.copy(),
partitioning=fixture.partitioning.copy(),
),
vapor_pressure=np.zeros((2, 2), dtype=np.float64),
fixture=fixture,
)
def _proposal(state: OracleInput) -> np.ndarray: # noqa: C901
"""Compute one predecessor-state raw transfer proposal using public helpers."""
fixture = state.fixture
masses = state.particles.masses
proposal = np.zeros_like(masses)
vapor_pressure = np.broadcast_to(
fixture.thermodynamic_parameters[:, 0], (2, 2)
)
for box in range(2):
temperature = fixture.temperature[box]
viscosity = get_dynamic_viscosity(
temperature,
constants.REF_VISCOSITY_AIR_STP,
constants.REF_TEMPERATURE_STP,
)
mean_free_path = get_molecule_mean_free_path(
constants.MOLECULAR_WEIGHT_AIR,
temperature,
fixture.pressure[box],
viscosity,
)
for particle in range(2):
if state.particles.concentration[box, particle] == 0.0:
continue
particle_masses = masses[box, particle]
total_volume = np.sum(particle_masses / fixture.density)
if total_volume <= 0.0:
continue
radius = (3.0 * total_volume / (4.0 * np.pi)) ** (1.0 / 3.0)
density = np.sum(particle_masses) / total_volume
knudsen = get_knudsen_number(mean_free_path, radius)
slip = get_cunningham_slip_correction(knudsen)
mobility = get_aerodynamic_mobility(radius, slip, viscosity)
particle_diffusion = get_diffusion_coefficient(
temperature, mobility, constants.BOLTZMANN_CONSTANT
)
for species in range(2):
vapor_mean_free_path = get_molecule_mean_free_path(
fixture.molar_mass[species],
temperature,
fixture.pressure[box],
viscosity,
)
transition = get_vapor_transition_correction(
vapor_mean_free_path / radius,
fixture.mass_accommodation[species],
)
vapor_diffusion = fixture.diffusion_coefficient_vapor[species]
if vapor_diffusion <= 0.0:
vapor_diffusion = particle_diffusion
transport = get_first_order_mass_transport_k(
radius, transition, vapor_diffusion
)
kelvin_radius = get_kelvin_radius(
fixture.surface_tension[species],
density,
state.gas.molar_mass[species],
temperature,
)
surface_pressure = vapor_pressure[
box, species
] * get_kelvin_term(radius, kelvin_radius)
delta_pressure = (
get_partial_pressure(
state.gas.concentration[box, species],
state.gas.molar_mass[species],
temperature,
)
- surface_pressure
)
proposal[box, particle, species] = (
get_mass_transfer_rate_latent_heat(
delta_pressure,
transport,
temperature,
state.gas.molar_mass[species],
fixture.latent_heat[species],
get_thermal_conductivity(temperature),
surface_pressure,
vapor_diffusion,
)
* (_TIME_STEP / 4.0)
)
proposal[:, :, ~fixture.partitioning] = 0.0
return proposal
def _finalize_transfer(state: OracleInput, proposal: np.ndarray) -> np.ndarray:
"""Apply inventory finalization bounds and ordered concentration-weighted
inventory limiting.
"""
bounded = np.maximum(proposal, -state.particles.masses)
applied = bounded.copy()
for box in range(2):
for species in range(2):
demand = 0.0
release = 0.0
for particle in range(2):
weighted = (
bounded[box, particle, species]
* state.particles.concentration[box, particle]
/ state.particles.volume[box]
)
if weighted > 0.0:
demand += weighted
else:
release -= weighted
scale = (
np.clip(
(state.gas.concentration[box, species] + release) / demand,
0.0,
1.0,
)
if demand > 0.0
else 1.0
)
applied[box, :, species] = np.where(
bounded[box, :, species] > 0.0,
bounded[box, :, species] * scale,
bounded[box, :, species],
)
return applied
def run_oracle(source: OracleInput | None = None) -> OracleResult:
"""Run exactly four independent fixed substeps before any Warp action.
Args:
source: Optional detached CPU state. A canonical detached source is
built when omitted. Supplied state is copied before mutation.
Returns:
Final independent state, coupled transfer diagnostics, signed-joule
energy diagnostic, and immutable per-substep observations.
"""
state = (
build_oracle_input() if source is None else _copy_oracle_input(source)
)
total = np.zeros_like(state.particles.masses)
raw_proposal = np.zeros_like(total)
substeps: list[OracleSubstep] = []
for _ in range(4):
gas_before = state.gas.concentration.copy()
raw_proposal = _proposal(state)
applied = _finalize_transfer(state, raw_proposal)
substeps.append(
OracleSubstep(
time_step=_TIME_STEP / 4.0,
gas_concentration_before=gas_before,
raw_proposal=raw_proposal.copy(),
finalized_transfer=applied.copy(),
)
)
state.particles.masses += applied
state.gas.concentration -= (
np.sum(applied * state.particles.concentration[:, :, None], axis=1)
/ state.particles.volume[:, None]
)
np.maximum(state.gas.concentration, 0.0, out=state.gas.concentration)
total += applied
energy = (
np.sum(total * state.particles.concentration[:, :, None], axis=1)
* state.fixture.latent_heat[None, :]
)
return OracleResult(
masses=state.particles.masses.copy(),
gas_concentration=state.gas.concentration.copy(),
total_mass_transfer=total,
raw_proposal=raw_proposal,
energy_transfer=energy,
substeps=tuple(substeps),
)
def _acceptance_result(
category: Literal["physics", "conservation", "energy"],
evaluate: Any,
) -> AcceptanceResult:
"""Evaluate one criterion and retain any assertion diagnostic.
Args:
category: Label for the acceptance criterion.
evaluate: Zero-argument assertion-based criterion evaluator.
Returns:
Passed or failed result with a diagnostic string.
"""
try:
evaluate()
except AssertionError as error:
return AcceptanceResult(category, "failed", str(error))
return AcceptanceResult(category, "passed", "criteria satisfied")
def evaluate_acceptance(
fixture: ParityFixture,
oracle: OracleResult,
observed_masses: np.ndarray,
observed_gas_concentration: np.ndarray,
observed_total_mass_transfer: np.ndarray,
observed_energy_transfer: np.ndarray,
observed_vapor_pressure: np.ndarray,
) -> tuple[AcceptanceResult, ...]:
"""Evaluate independent physics, conservation, and energy criteria.
Every criterion is evaluated even when an earlier criterion fails.
Args:
fixture: Immutable initial state and physical parameters.
oracle: Independent NumPy final state and transfer diagnostic.
observed_masses: Synchronized Warp final particle masses in kg.
observed_gas_concentration: Synchronized Warp final gas concentrations.
observed_total_mass_transfer: Synchronized finalized particle transfers
in kg.
observed_energy_transfer: Synchronized signed energy sidecar in J.
observed_vapor_pressure: Synchronized derived vapor pressure in Pa.
Returns:
Physics, conservation, and energy results in that order.
"""
expected_vapor_pressure = np.broadcast_to(
fixture.thermodynamic_parameters[:, 0], (2, 2)
)
def evaluate_physics() -> None:
np.testing.assert_allclose(
observed_masses, oracle.masses, rtol=2e-10, atol=1e-30
)
np.testing.assert_allclose(
observed_gas_concentration,
oracle.gas_concentration,
rtol=2e-10,
atol=1e-30,
)
np.testing.assert_allclose(
observed_total_mass_transfer,
oracle.total_mass_transfer,
rtol=2e-10,
atol=1e-30,
)
np.testing.assert_array_equal(
observed_vapor_pressure, expected_vapor_pressure
)
def evaluate_conservation() -> None:
particle_inventory_change = np.sum(
(observed_masses - fixture.masses)
* fixture.concentration[:, :, None],
axis=1,
)
gas_change = observed_gas_concentration - fixture.gas_concentration
drift = particle_inventory_change + gas_change
conservation_scale = np.maximum(
np.abs(fixture.gas_concentration),
np.abs(observed_gas_concentration),
)
np.testing.assert_allclose(
drift + conservation_scale,
conservation_scale,
rtol=1e-12,
atol=1e-30,
)
def evaluate_energy() -> None:
expected_energy = (
np.sum(
observed_total_mass_transfer
* fixture.concentration[:, :, None]
* fixture.volume[:, None, None],
axis=1,
)
* fixture.latent_heat[None, :]
)
np.testing.assert_allclose(
observed_energy_transfer, expected_energy, rtol=1e-12, atol=1e-18
)
return (
_acceptance_result("physics", evaluate_physics),
_acceptance_result("conservation", evaluate_conservation),
_acceptance_result("energy", evaluate_energy),
)
def _format_acceptance(result: AcceptanceResult) -> str:
"""Format one machine-testable acceptance block for script output.
Args:
result: Categorized acceptance result to display.
Returns:
One labeled, human-readable output line.
"""
return f"{result.category}: {result.status} - {result.diagnostic}"
def _warp_enabled() -> bool:
"""Return whether optional Warp execution is available and not disabled."""
return WARP_AVAILABLE and os.getenv(_FORCE_NO_WARP_ENV) != "1"
def _load_gpu_runtime() -> tuple[Any, Any, Any, Any]:
"""Lazily import Warp and concrete direct-kernel-only runtime modules."""
wp = importlib.import_module("warp")
kernels = importlib.import_module("particula.gpu.kernels")
condensation = importlib.import_module("particula.gpu.kernels.condensation")
thermodynamics = importlib.import_module(
"particula.gpu.kernels.thermodynamics"
)
return (
wp,
kernels.condensation_step_gpu,
condensation.CondensationScratchBuffers,
thermodynamics.ThermodynamicsConfig,
)
def _prepare_species_binding(particles: Any, gas: Any, names: list[str]) -> Any:
"""Explicitly upload the two material-lane mappings after state transfer."""
from particula.dynamics.condensation.species_mapping import (
CondensationSpeciesMap,
)
from particula.gpu.species_mapping import prepare_condensation_species_map
return prepare_condensation_species_map(
particles,
gas,
gas_names=names,
species_map=CondensationSpeciesMap(tuple(names), ((0, 0), (1, 1))),
)
def run_example(device: str = "cpu") -> ExampleRun:
"""Complete the oracle then optionally execute and synchronize Warp state.
Enabled-route errors intentionally propagate. The detached source and its
sidecars must be discarded after failure because opaque kernel mutation is
not atomic; the completed oracle remains an independent clean result.
Args:
device: Warp device for the optional direct-kernel route. Defaults to
Warp's CPU device.
Returns:
Completed oracle and, when Warp is enabled, synchronized mutable
caller-owned outputs. ``energy_transfer`` has shape
``(n_boxes, n_species)``, records signed joules in place, and is not a
third value returned by the direct kernel step.
"""
fixture = build_fixture()
oracle = run_oracle(build_oracle_input(fixture))
output = ["Independent NumPy oracle completed (four fixed substeps)."]
if not _warp_enabled():
output.append("oracle completed; no kernel ran")
categories: tuple[Literal["physics", "conservation", "energy"], ...] = (
"physics",
"conservation",
"energy",
)
acceptance = tuple(
AcceptanceResult(category, "unavailable", "no-Warp observations")
for category in categories
)
output.extend(_format_acceptance(result) for result in acceptance)
return ExampleRun(output=output, oracle=oracle, acceptance=acceptance)
wp, step, scratch_type, thermodynamics_type = _load_gpu_runtime()
source = build_warp_source(fixture)
names = list(source.gas.name)
particles = to_warp_particle_data(source.particles, device=device)
gas = to_warp_gas_data(
source.gas, device=device, vapor_pressure=source.vapor_pressure
)
species_binding = _prepare_species_binding(particles, gas, names)
transfer_shape, box_shape, gas_shape = (2, 2, 2), (2,), (2, 2)
scratch = scratch_type(
work_mass_transfer=wp.zeros(
transfer_shape, dtype=wp.float64, device=device
),
total_mass_transfer=wp.zeros(
transfer_shape, dtype=wp.float64, device=device
),
dynamic_viscosity=wp.zeros(box_shape, dtype=wp.float64, device=device),
mean_free_path=wp.zeros(box_shape, dtype=wp.float64, device=device),
positive_mass_transfer_demand=wp.zeros(
gas_shape, dtype=wp.float64, device=device
),
negative_mass_transfer_release=wp.zeros(
gas_shape, dtype=wp.float64, device=device
),
positive_mass_transfer_scale=wp.zeros(
gas_shape, dtype=wp.float64, device=device
),
)
thermodynamics = thermodynamics_type(
modes=_warp_array(wp, fixture.thermodynamic_modes, wp.int32, device),
parameters=_warp_array(
wp, fixture.thermodynamic_parameters, wp.float64, device
),
molar_mass_reference=_warp_array(
wp, fixture.molar_mass, wp.float64, device
),
)
energy = wp.zeros(gas_shape, dtype=wp.float64, device=device)
_, total = step(
particles,
gas,
temperature=_warp_array(wp, fixture.temperature, wp.float64, device),
pressure=_warp_array(wp, fixture.pressure, wp.float64, device),
time_step=_TIME_STEP,
surface_tension=_warp_array(
wp, fixture.surface_tension, wp.float64, device
),
mass_accommodation=_warp_array(
wp, fixture.mass_accommodation, wp.float64, device
),
diffusion_coefficient_vapor=_warp_array(
wp, fixture.diffusion_coefficient_vapor, wp.float64, device
),
thermodynamics=thermodynamics,
species_binding=species_binding,
scratch_buffers=scratch,
latent_heat=_warp_array(wp, fixture.latent_heat, wp.float64, device),
energy_transfer=energy,
)
assert total is scratch.total_mass_transfer
wp.synchronize_device(device)
restored_particles = from_warp_particle_data(particles)
wp.synchronize_device(device)
restored_gas = from_warp_gas_data(gas, name=names)
wp.synchronize_device(device)
observed_vapor_pressure = gas.vapor_pressure.numpy().copy()
wp.synchronize_device(device)
raw = scratch.work_mass_transfer.numpy().copy()
wp.synchronize_device(device)
applied = total.numpy().copy()
wp.synchronize_device(device)
observed_energy = energy.numpy().copy()
acceptance = evaluate_acceptance(
fixture,
oracle,
restored_particles.masses,
restored_gas.concentration,
applied,
observed_energy,
observed_vapor_pressure,
)
output.append("Synchronized Warp direct-kernel observations completed.")
output.extend(_format_acceptance(result) for result in acceptance)
return ExampleRun(
output=output,
oracle=oracle,
particle_data=restored_particles,
gas_data=restored_gas,
raw_proposal=raw,
total_mass_transfer=applied,
energy_transfer=observed_energy,
vapor_pressure=observed_vapor_pressure,
acceptance=acceptance,
scratch_buffers=scratch,
)

Compare signed mass transfer and latent energy

Section titled “Compare signed mass transfer and latent energy”

Positive transfer means condensation; negative transfer means evaporation. Energy is an extensive quantity in joules and includes represented counts. The small fixture tests the calculation, not GPU throughput.

Python · section 2
def run_publication():
"""Require successful CUDA acceptance before rendering the comparison."""
import matplotlib.pyplot as plt
import warp as wp
if not _warp_enabled() or not wp.is_cuda_available():
raise RuntimeError("This publication run requires CUDA")
result = run_example(device="cuda:0")
if any(item.status != "passed" for item in result.acceptance):
raise AssertionError("CUDA condensation acceptance failed")
fig, axes = plt.subplots(1, 2, figsize=(10, 3.8), constrained_layout=True)
labels = [
f"B{b + 1} P{p + 1} {s}"
for b in range(2)
for p in range(2)
for s in ("water", "organic")
]
x = np.arange(8)
axes[0].bar(
x - 0.18,
result.oracle.total_mass_transfer.ravel() * 1e21,
width=0.36,
label="Independent NumPy",
)
axes[0].bar(
x + 0.18,
result.total_mass_transfer.ravel() * 1e21,
width=0.36,
label="CUDA",
)
axes[0].set(
ylabel="Signed mass transfer (ag)", xticks=x, xticklabels=labels
)
axes[0].tick_params(axis="x", rotation=65)
axes[0].axhline(0, color="0.5", linewidth=0.8)
axes[0].legend()
x = np.arange(4)
axes[1].plot(
x,
result.oracle.energy_transfer.ravel() * 1e12,
"o",
label="Independent NumPy",
)
axes[1].plot(
x,
result.energy_transfer.ravel() * 1e12,
"x",
markersize=9,
label="CUDA",
)
axes[1].set(
ylabel="Signed latent energy (pJ)",
xticks=x,
xticklabels=["B1 water", "B1 organic", "B2 water", "B2 organic"],
)
axes[1].tick_params(axis="x", rotation=35)
axes[1].axhline(0, color="0.5", linewidth=0.8)
axes[1].legend()
fig.suptitle(
"Independent condensation check · " + wp.get_device("cuda:0").name
)
print("\n".join(result.output))
plt.show()
return result
def main() -> int:
"""Run the walkthrough, print results, and return its process status."""
result = run_example()
for line in result.output:
print(line)
return int(any(item.status == "failed" for item in result.acceptance))
if __name__ == "__main__":
import sys
if "--cuda" in sys.argv[1:]:
run_publication()
else:
raise SystemExit(main())
Explicit cuda invocation
result = run_publication()
Warp 1.11.1 initialized:
   CUDA Toolkit 12.9, Driver 13.4
   Devices:
     "cpu"      : "CPU"
     "cuda:0"   : "NVIDIA GeForce RTX 5060" (8 GiB, sm_120, mempool enabled)
   Kernel cache:
     ~/.cache/warp/1.11.1
Module particula.gpu.kernels.condensation 14a649a load on device 'cuda:0' took 0.60 ms  (cached)
Module particula.gpu.kernels.environment e11375e load on device 'cuda:0' took 0.39 ms  (cached)
Module particula.gpu.kernels.condensation 2c7d291 load on device 'cuda:0' took 0.32 ms  (cached)
Module particula.gpu.kernels._condensation_native 34375de load on device 'cuda:0' took 0.43 ms  (cached)
Module particula.gpu.kernels.condensation c7ee7df load on device 'cuda:0' took 0.36 ms  (cached)
Module particula.gpu.kernels.condensation f9b041d load on device 'cuda:0' took 1.98 ms  (cached)
Module particula.gpu.kernels.thermodynamics 10b2126 load on device 'cuda:0' took 0.34 ms  (cached)
Module particula.gpu.kernels.condensation e17dab7 load on device 'cuda:0' took 1.32 ms  (cached)
Module particula.gpu.kernels.condensation 1f07a94 load on device 'cuda:0' took 2.07 ms  (cached)
Module particula.gpu.kernels._condensation_native 9623455 load on device 'cuda:0' took 0.44 ms  (cached)
Module particula.gpu.kernels.condensation bfcd77e load on device 'cuda:0' took 1.49 ms  (cached)
Module particula.gpu.kernels._condensation_native 76403ad load on device 'cuda:0' took 0.47 ms  (cached)
Module particula.gpu.kernels.condensation bdb6652 load on device 'cuda:0' took 1.80 ms  (cached)
Module particula.gpu.kernels._condensation_native c295a4d load on device 'cuda:0' took 0.42 ms  (cached)
Module particula.gpu.kernels._condensation_native a80ebff load on device 'cuda:0' took 0.45 ms  (cached)
Module particula.gpu.kernels.condensation 274e9e6 load on device 'cuda:0' took 2.47 ms  (cached)
Module particula.gpu.kernels.condensation 02112ca load on device 'cuda:0' took 1.94 ms  (cached)
Module particula.gpu.kernels.condensation 072e845 load on device 'cuda:0' took 1.08 ms  (cached)
Module particula.gpu.kernels._condensation_native 6dc00df load on device 'cuda:0' took 0.65 ms  (cached)
Module particula.gpu.kernels._condensation_native bc27112 load on device 'cuda:0' took 0.67 ms  (cached)
Independent NumPy oracle completed (four fixed substeps).
Synchronized Warp direct-kernel observations completed.
physics: passed - criteria satisfied
conservation: passed - criteria satisfied
energy: passed - criteria satisfied
Check CUDA condensation against independent equations: saved scientific figure
Check CUDA condensation against independent equations · saved execution output

Matching signed bars checks the transfer calculation; matching energy markers checks count-weighted transfer times latent heat. The conservation check tests material exchange with gas separately. The category called physics in the printed report means agreement with this implemented oracle, not experimental validation. The oracle uses shared scalar property functions but independently organizes the proposal, bounds, and four-substep update; it is not an independent validation of those shared property laws.

The prescribed temperatures do not evolve with the energy diagnostic. For a thermally coupled study, add an explicit heat budget and an independent limiting solution. For a transfer study, vary gas availability and timestep while retaining species-wise checks, so that clipping and integration errors cannot hide behind a conserved total. See latent-heat condensation for the meaning of the heat-resistance correction.

Explore this topic: Direct kernels