Container and Facade Migration

July 25, 2026 · View on GitHub

This page maps legacy particle and gas facades to their data-container equivalents. See the migration overview for ownership and support boundaries.

Quick migration

Particle data (before to after)

import numpy as np
import particula as par

# Legacy facade
rep = par.particles.ParticleRepresentation(
    strategy=par.particles.MassBasedMovingBin(),
    activity=par.particles.ActivityIdealMass(),
    surface=par.particles.SurfaceStrategyMass(),
    distribution=np.array([1e-18, 2e-18, 3e-18]),
    density=np.array([1200.0]),
    concentration=np.array([1e5, 1e5, 1e5]),
    charge=np.zeros(3),
    volume=1e-6,
)

# New data container
from particula.particles import ParticleData

data = ParticleData(
    # (n_boxes, n_particles, n_species)
    masses=rep.get_species_mass()[None, ...],
    concentration=rep.get_concentration()[None, ...],
    charge=rep.get_charge()[None, ...],
    density=rep.get_density(),
    volume=np.array([rep.get_volume()]),
)

Gas data (before to after)

import numpy as np
import particula as par

# Legacy facade
species = par.gas.GasSpecies(
    name="Water",
    molar_mass=0.018,
    vapor_pressure_strategy=par.gas.ConstantVaporPressureStrategy(2330.0),
    concentration=1e-6,
)

# New data container
from particula.gas import GasData

gas_data = GasData(
    name=["Water"],
    molar_mass=np.array([0.018]),
    concentration=np.array([[1e-6]]),  # (n_boxes, n_species)
    partitioning=np.array([True]),
)

ParticleRepresentation to ParticleData

Constructor mapping

Legacy input	ParticleData field	Notes
`distribution`	`masses`	Convert to per-species masses.
`density`	`density`	1D array of species densities.
`concentration`	`concentration`	Shape `(n_boxes, n_particles)`.
`charge`	`charge`	Shape `(n_boxes, n_particles)`.
`volume`	`volume`	Shape `(n_boxes,)`.
`strategy`	behavior	Keep strategy separate from data.
`activity`	behavior	Remains in activity strategies.
`surface`	behavior	Remains in surface strategies.

Property and method mapping

Legacy API	ParticleData equivalent	Notes
`get_radius()`	`data.radii`	Computed from mass and density.
`get_mass()`	`data.total_mass`	Total per particle.
`get_species_mass()`	`data.masses`	Per-species masses.
`get_density()`	`data.density`	Density per species.
`get_concentration()`	`data.concentration`	2D array by box.
`get_charge()`	`data.charge`	2D array by box.
`get_volume()`	`data.volume`	Per-box volume.
`get_effective_density()`	`data.effective_density`	Mass-weighted density.
`get_total_concentration()`	`data.concentration.sum(axis=1)`	Per box.

!!! note ParticleData keeps the batch dimension. If you used a single-box facade, index data.concentration[0] or data.radii[0] for the legacy shape.

GasSpecies to GasData

Constructor mapping

Legacy input	GasData field	Notes
`name`	`name`	List of species names.
`molar_mass`	`molar_mass`	1D array of molar masses.
`concentration`	`concentration`	Shape `(n_boxes, n_species)`.
`partitioning`	`partitioning`	1D boolean array.
`vapor_pressure_strategy`	behavior	Remains on the facade.

Property and method mapping

Legacy API	GasData equivalent	Notes
`get_name()`	`data.name`	List of names.
`get_molar_mass()`	`data.molar_mass`	1D array.
`get_concentration()`	`data.concentration[box_index]`	Select a box.
`get_partitioning()`	`data.partitioning`	Boolean mask by species.

!!! note Vapor pressure calculations remain on GasSpecies. Use the facade when strategy-driven behavior is required, and pass GasData where only data is required.

GasData and WarpGasData migration summary

For the canonical transfer boundary and support limits, see Data Containers and GPU Foundations.

Migration-focused rules of thumb:

Keep the leading box axis explicit. Single-box gas arrays still use (1, n_species).
Treat name as caller-owned metadata at the restore boundary. Supplying the original ordered names gives a semantic round trip; omitting name or passing name=None produces placeholders only.
Treat partitioning as a CPU boolean API and a GPU numeric mask.
Treat vapor_pressure as GPU sidecar process state that must be preserved or recomputed outside GasData after restore.

Example CPU-to-GPU-to-CPU handoff:

import numpy as np

from particula.gpu import from_warp_gas_data, to_warp_gas_data

vapor_pressure = np.array([[2330.0, 120.0]])  # (1, n_species)
gpu_gas = to_warp_gas_data(
    gas_data,
    device="cpu",
    vapor_pressure=vapor_pressure,
)
restored = from_warp_gas_data(gpu_gas, name=gas_data.name)

# Preserve ordered names outside WarpGasData and keep any vapor-pressure
# sidecar separately (or recompute it) on the CPU side.

Gradual migration with `.data`

Both legacy facades expose their underlying data containers:

particle_data = rep.data
gas_data = species.data

To wrap data without emitting deprecation logs, use each facade's class method:

rep = par.particles.ParticleRepresentation.from_data(
    data=particle_data,
    strategy=par.particles.MassBasedMovingBin(),
    activity=par.particles.ActivityIdealMass(),
    surface=par.particles.SurfaceStrategyMass(),
    distribution=particle_data.total_mass[0],
)

species = par.gas.GasSpecies.from_data(
    data=gas_data,
    vapor_pressure_strategy=par.gas.ConstantVaporPressureStrategy(2330.0),
)

Conversion helpers

Use conversion helpers when bridging old and new APIs:

from_representation and to_representation for particle data. They are exported from particula.particles.
from_species and to_species for gas data. They are exported from particula.gas.

from particula.gas import from_species
from particula.particles import from_representation

particle_data = from_representation(rep, n_boxes=1)
gas_data = from_species(species, n_boxes=1)