Check CUDA condensation against independent equations
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 makesall CPU↔Warp transfers explicit. It first completes an independent foursubstep NumPy calculation, then optionally runs the low-level Warp route. IfWarp is unavailable, or ``PARTICULA_EXAMPLE_FORCE_NO_WARP=1``, it reports thecompleted 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 signedjoules, and is not a third returned value. A failed kernel callmay have partially mutated that detached state; discard it and build freshsources from the immutable fixture before retrying."""
from __future__ import annotations
import importlibimport osfrom dataclasses import dataclassfrom typing import Any, Literal
import numpy as npfrom particula.dynamics.condensation.mass_transfer import ( get_first_order_mass_transport_k, get_mass_transfer_rate_latent_heat,)from particula.gas import GasDatafrom particula.gas.properties.dynamic_viscosity import get_dynamic_viscosityfrom particula.gas.properties.mean_free_path import get_molecule_mean_free_pathfrom particula.gas.properties.pressure_function import get_partial_pressurefrom 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 ParticleDatafrom 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])), )
@dataclassclass OracleInput: """Detached CPU state for the independent oracle."""
particles: ParticleData gas: GasData fixture: ParityFixture
@dataclassclass WarpSource: """Detached CPU state converted only after optional Warp enablement."""
particles: ParticleData gas: GasData vapor_pressure: np.ndarray fixture: ParityFixture
@dataclassclass 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
@dataclassclass 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

Explain agreement at the right level
Section titled “Explain agreement at the right level”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