Skip to content

Particula Design

Particula purposefully sticks to two complementary coding paradigms so users can pick the style that fits their workflow.

Preference Use case Recommendation
Procedural / notebooks Quick calculations, teaching demos Stick to get_ functions.
OO / large experiments Multiple interacting processes, validation, swapping kernels Use Builders + Strategies.

1. Procedural: Functional core – “verb‑phrased” helpers

Section titled “1. Procedural: Functional core – “verb‑phrased” helpers”

Pattern: Functions

These core functions are in most cases stateless and return a value based on inputs. They have no hidden side effects and are not dependent on any object. They are easy to test and can be replaced with JIT‑compiled versions (Numba/C++) in the future.

They are the building blocks of the simulation engine. They can be used in a procedural style, making them suitable for quick calculations or teaching demos.

get_ – prefix that signals “this function returns a value”.

Example:

import numpy as np
import particula as par
particle_radius = np.array([100e-9, 200e-9])
eddy_dissipation = 0.01 # m²/s³
temperature = 298.15 # K
fluid_density = 1.225 # kg/m³
kernel = par.dynamics.get_turbulent_shear_kernel_st1956_via_system_state(
particle_radius=particle_radius,
turbulent_dissipation=eddy_dissipation,
temperature=temperature,
fluid_density=fluid_density,
)

2. Object‑oriented: – “noun‑phrased” abstractions

Section titled “2. Object‑oriented: – “noun‑phrased” abstractions”

Patterns employed

  • Strategy – e.g. TurbulentShearCoagulationStrategy selects which kernel to call, built of get_ functions. These are the main building blocks of the simulation engine.
  • Builder – e.g. CombineCoagulationStrategyBuilder validates input and assembles strategies.
  • Factory – e.g. ActivityFactory creates an ActivityStrategy instance via an ActivityBuilder. These allow for more complex meta programming of simulation objects.
  • Decorator – e.g. @validate_inputs checks for valid inputs before running the function. These are used to enforce domain specific invariants (positive radius, non‑negative concentration, finite Coulomb potential, …).
  • Mixin – thin, single‑responsibility classes adding orthogonal capabilities (density, charge, surface …).

For a broader overview of design patterns, see Object‑Oriented Patterns.

Example (combining two kernels):

import particula as par
# Step 1: Build your individual strategies
brownian_strategy = ( # using a builder for the Brownian kernel
par.dynamics.BrownianCoagulationBuilder()
.set_distribution_type("discrete")
.build()
)
turbulent_strategy = ( # directly creating the strategy
par.dynamics.TurbulentShearCoagulationStrategy(
distribution_type="discrete",
turbulent_dissipation=0.01, # example value [m^2/s^3]
fluid_density=1.225 # air at sea level [kg/m^3]
)
)
# Step 2: Combine strategies with the builder
builder = par.dynamics.CombineCoagulationStrategyBuilder()
builder.set_strategies([brownian_strategy, turbulent_strategy])
combined_strategy = builder.build()
# Step 3: Use the combined strategy in a coagulation process
coagulation_process = par.dynamics.Coagulation(
coagulation_strategy=combined_strategy
)

Benefits

  • Plug‑and‑play process swapping → perfect for sensitivity studies.
  • Builder validation enforces Agreeing (the A in WARMED).
  • Functions → get_<quantity>[_via_system_state]
  • Classes → <Descriptor><PatternName> (TurbulentShearCoagulationStrategy, ParticleDataBuilder)

These rules make grep‑based discovery trivial and help LLMs auto‑suggest the correct object.

Performance work (Numba/C++) will follow the “replace the function, keep the interface” rule—strategies will automatically inherit the speed‑ups without further changes.