Skip to content

particula.dynamics.ions.coagulation

Prepared collision laws for explicit ions and charged aerosols.

Attributes

NameDescription
NEGATIVE_ION_MASSNo description.
POSITIVE_ION_MASSNo description.

Classes

NameDescription
AtmosphericCoagulationCombine charged aerosol coagulation, ion attachment and recombination.

NEGATIVE_ION_MASSattributemodule attribute#

NEGATIVE_ION_MASS = 90 * ATOMIC_MASS_UNIT

POSITIVE_ION_MASSattributemodule attribute#

POSITIVE_ION_MASS = 150 * ATOMIC_MASS_UNIT

AtmosphericCoagulationclassdataclass#

class AtmosphericCoagulation(positive_species: int, negative_species: int, charged_model: str = 'hard_sphere', omitted: str = 'reject', recombination: float = 1.7e-12, attachment_model: str = 'lf2013', positive_mobility: float = 0.00014, negative_mobility: float = 0.00019, ion_radius: float = 2.5e-10)

Bases: RunnableABC

Combine charged aerosol coagulation, ion attachment and recombination.

Prepared Warp execution only, for unit represented particles. Aerosol pairs use charged_model; default ion-aerosol rates use conductive-air LF2013 tables at 298.15 K and 101325 Pa, with 150 u positive and 90 u negative ions. Opposite free ions recombine; same-sign ions do not cluster. Neutral ion-only products are inert until an explicit IonNeutralCleanup. Reserved material lanes must contain only ion mass.

Parameters

NameTypeDefaultDescription
positive_speciesintrequiredPositive-ion material index.
negative_speciesintrequiredNegative-ion material index.
charged_modelstr'hard_sphere'Existing charged Brownian model name.
omittedstr'reject'reject (default), lower or upper for repulsive attachment rates omitted below the published 1e-15 m^3/s cutoff. Bounds are sensitivity assumptions, not extrapolated fit values.
recombinationfloat1.7e-12Explicit opposite-ion recombination coefficient [m^3/s], held constant with T/P; not predicted by the attachment model.
attachment_modelstr'lf2013'lf2013 or opt-in mobility Coulomb transport approximation, supporting variable T/P. No image forces or hydration.
positive_mobilityfloat0.00014Illustrative positive-ion mobility at 298.15 K, 101325 Pa [m^2/(V s)]; supply a measured value for a specific ion.
negative_mobilityfloat0.00019Corresponding negative-ion reference mobility.
ion_radiusfloat2.5e-10Ion contact radius [m], independent of mobility transport.

attachment_modelattributeclass attributeinstance attribute#

attachment_model: str = 'lf2013'

charged_modelattributeclass attributeinstance attribute#

charged_model: str = 'hard_sphere'

ion_radiusattributeclass attributeinstance attribute#

ion_radius: float = 2.5e-10

negative_mobilityattributeclass attributeinstance attribute#

negative_mobility: float = 0.00019

negative_speciesattributeinstance attribute#

negative_species: int

omittedattributeclass attributeinstance attribute#

omitted: str = 'reject'

positive_mobilityattributeclass attributeinstance attribute#

positive_mobility: float = 0.00014

positive_speciesattributeinstance attribute#

positive_species: int

recombinationattributeclass attributeinstance attribute#

recombination: float = 1.7e-12

__init__method#

def __init__(positive_species: int, negative_species: int, charged_model: str = 'hard_sphere', omitted: str = 'reject', recombination: float = 1.7e-12, attachment_model: str = 'lf2013', positive_mobility: float = 0.00014, negative_mobility: float = 0.00019, ion_radius: float = 2.5e-10) -> None

_validate_batchmethod#

def _validate_batch(aerosol)

Reject unsupported model and physical state before GPU upload.

executemethod#

def execute(*args, **kwargs)

Reject native CPU execution without mutating the aerosol.

Inherited from particula.runnable.RunnableABC

__or__method#

def __or__(other: RunnableABC) -> RunnableSequence

Chain this Runnable with another using the ’|’ operator.

This method enables an easy way to sequence processes, so they can be executed in a defined order.

Parameters

NameTypeDescription
otherRunnableABCAnother Runnable to append after this one.

Returns

RunnableSequence
A sequence containing both processes.

Examples

Chaining two processes
combined_process = process1 | process2
final_aerosol = combined_process.execute(aerosol, time_step=1.0)

_advance_boxmethod#

def _advance_box(aerosol, time_step)

Dispatch one staged interval through the native extension seam.

_box_workermethod#

def _box_worker(box, boxes, transaction)

Create isolated hook state for a single box.

_execute_boxmethod#

def _execute_box(aerosol, time_step, sub_steps=1)

Execute the single-box numerical building block.

_is_stochasticmethod#

def _is_stochastic(aerosol)

Report whether this process requires independent box streams.

_prepare_commitmethod#

def _prepare_commit(workers, uses_context)

Prepare a non-failing diagnostics publisher before numeric writes.

_rate_boxmethod#

def _rate_box(aerosol)

Evaluate the single-box numerical building block.

_writer_fieldsmethod#

def _writer_fields(aerosol)

Declare numeric destinations for transactional publication.

preparemethod#

def prepare(aerosol: Aerosol, *, time_step: float, backend: Backend | None = None, device: str = 'cuda:0', root_seed: int = 0, logical_box_ids=None, process_registry=None, coagulation_work_config=None, time: float = 0.0) -> PreparedSimulation

Upload native state once and prepare supported resident GPU physics.

Parameters

NameTypeDefaultDescription
aerosolAerosolrequiredInitial native particle, gas and environment state.
time_stepfloatrequiredFixed duration of each complete process cycle [s].
backendBackend | NoneNoneBackend.WARP by default; CPU execution uses execute().
devicestr'cuda:0'Explicit Warp device, default CUDA device zero.
root_seedint0Root seed for persistent independent process/box streams.
logical_box_idsNoneOptional stable identities in physical box order.
process_registryNoneExact-type custom GPU adapter registrations.
coagulation_work_configNoneOptional coagulation resource budgets.
timefloat0.0Absolute initial simulation time [s].

Returns

PreparedSimulation
An owned PreparedSimulation. Use its context manager or close().
PreparedSimulation
snapshot() returns detached CPU state for analysis and plotting.

Raises

ValueError
If process physics or state cannot be represented.
RuntimeError
If the requested runtime/device is unavailable.

ratemethod#

def rate(aerosol: Aerosol) -> Any

Evaluate detached box hooks and retain a leading box axis.

resumemethod#

def resume(checkpoint: SimulationCheckpoint, *, backend: Backend | None = None, device: str | None = None, process_registry=None) -> PreparedSimulation

Resume exact saved state using the same process configuration.

Parameters

NameTypeDefaultDescription
checkpointSimulationCheckpointrequiredSimulationCheckpoint from a prepared owner.
backendBackend | NoneNoneBackend.WARP by default.
devicestr | NoneNoneExact checkpoint device by default; migration rejects.
process_registryNoneCompatible caller-supplied GPU implementations.

Returns

PreparedSimulation
A new owner preserving state, RNG words, timestep and counters.
PreparedSimulation
Capture is explicit again; native graph handles are never restored.

Raises

ValueError
If configuration, order, schema or device differs, or current population cannot be admitted (e.g. unequal Brownian counts after a later process injected new particles).