Activity System
Strategy-based activity calculations for aerosol thermodynamics using ideal, kappa-Kohler, and BAT models.
Overview
Section titled “Overview”The activity system provides a unified interface for computing chemical activity in aerosol particles. Activity determines how species partition between gas and particle phases, controls water uptake and hygroscopic growth, and drives phase equilibria in organic-water mixtures.
This feature is built around user-facing APIs exposed via particula.particles:
ActivityIdealMolar,ActivityIdealMass- Ideal activity strategies based on Raoult’s LawActivityKappaParameter- Kappa hygroscopic parameter model for water activityActivityNonIdealBinary- BAT model for non-ideal organic-water mixturesActivityIdealMolarBuilder,ActivityIdealMassBuilder, etc. - Validated, unit-aware buildersActivityFactory- Factory for selecting strategies by name
Integration with equilibria calculations is provided through particula.equilibria:
LiquidVaporPartitioningStrategy- Liquid-vapor equilibrium using activityEquilibria- Runnable wrapper for equilibria strategies
Key Benefits
Section titled “Key Benefits”- Consistent dynamics workflow: Use the same strategy-based API as condensation, coagulation, and wall loss
- Multiple activity models: Choose from ideal, kappa-Kohler, or BAT (non-ideal) models based on your system
- Builder/factory validation: Configure activity using unit-aware builders with automatic conversion and validation
- Equilibria integration: Combine activity strategies with liquid-vapor partitioning for thermodynamic equilibrium
- Extensible design: Add new activity models by subclassing
ActivityStrategy
Who It’s For
Section titled “Who It’s For”This feature is designed for:
- Aerosol modelers: Computing water activity for hygroscopic growth and cloud droplet activation
- Chamber experiment analysts: Modeling organic aerosol partitioning with realistic thermodynamics
- Model developers: Implementing custom activity models while reusing particula’s infrastructure
- Researchers: Comparing ideal vs. non-ideal activity effects on aerosol behavior
Capabilities
Section titled “Capabilities”Unified activity API in particula.particles
Section titled “Unified activity API in particula.particles”Activity strategies are exposed alongside other particle components:
import particula as par
# Strategy classespar.particles.ActivityIdealMolarpar.particles.ActivityIdealMasspar.particles.ActivityKappaParameterpar.particles.ActivityNonIdealBinary
# Builder classespar.particles.ActivityIdealMolarBuilderpar.particles.ActivityIdealMassBuilderpar.particles.ActivityKappaParameterBuilderpar.particles.ActivityNonIdealBinaryBuilder
# Factory classpar.particles.ActivityFactoryAll activity strategies share a common interface:
- Call
activity(mass_concentration)to compute activity from mass concentrations - Call
partial_pressure(pure_vapor_pressure, mass_concentration)to compute partial pressures
Available strategies
Section titled “Available strategies”| Strategy | Description | Use Case |
|---|---|---|
ActivityIdealMolar |
Raoult’s Law based on mole fractions | Simple mixtures, dilute solutions |
ActivityIdealMass |
Ideal activity based on mass fractions | Mass-based calculations |
ActivityKappaParameter |
Kappa hygroscopic parameter model | Hygroscopic growth, CCN activation |
ActivityNonIdealBinary |
BAT model for non-ideal mixtures | Organic-water aerosol thermodynamics |
Ideal activity strategies
Section titled “Ideal activity strategies”For systems where activity coefficients are approximately 1, use the ideal strategies:
import numpy as npimport particula as par
# Ideal molar activity (Raoult's Law)strategy = par.particles.ActivityIdealMolar( molar_mass=np.array([18.015e-3, 200.0e-3]), # kg/mol: water, organic)
# Mass concentrations (kg/m^3)mass = np.array([0.5e-9, 0.5e-9])
# Compute activity (returns mole fractions for ideal mixing)activity = strategy.activity(mass_concentration=mass)Kappa parameter activity
Section titled “Kappa parameter activity”For hygroscopic aerosols, the kappa parameter provides a single-parameter representation of water activity:
import numpy as npimport particula as par
# Kappa parameter strategystrategy = par.particles.ActivityKappaParameter( kappa=np.array([0.0, 0.61]), # water, ammonium sulfate density=np.array([1000.0, 1770.0]), # kg/m^3 molar_mass=np.array([18.015e-3, 132.14e-3]), # kg/mol water_index=0,)
# Compute water activity at given compositionmass = np.array([0.7e-9, 0.3e-9]) # 70% water, 30% saltactivity = strategy.activity(mass_concentration=mass)# activity[0] gives water activityNon-ideal activity (BAT model)
Section titled “Non-ideal activity (BAT model)”For organic-water mixtures with significant non-ideality, use the BAT model:
import particula as par
# Build non-ideal activity strategystrategy = ( par.particles.ActivityNonIdealBinaryBuilder() .set_molar_mass(200.0e-3, "kg/mol") .set_oxygen2carbon(0.5) .set_density(1200.0, "kg/m^3") .build())
# Compute activitymass = np.array([0.5e-9, 0.5e-9]) # water, organicactivity = strategy.activity(mass_concentration=mass)Builder usage patterns
Section titled “Builder usage patterns”Builders provide validated configuration with automatic unit conversion:
import numpy as npimport particula as par
# Molar activity with unit conversionmolar_activity = ( par.particles.ActivityIdealMolarBuilder() .set_molar_mass(np.array([18.015, 200.0]), "g/mol") # converts to kg/mol .build())
# Kappa activity with all parameterskappa_activity = ( par.particles.ActivityKappaParameterBuilder() .set_kappa(np.array([0.0, 0.61])) .set_density(np.array([1.0, 1.77]), "g/cm^3") # converts to kg/m^3 .set_molar_mass(np.array([18.015, 132.14]), "g/mol") .set_water_index(0) .build())Factory usage for dynamic selection
Section titled “Factory usage for dynamic selection”The factory enables runtime strategy selection by name:
import numpy as npimport particula as par
factory = par.particles.ActivityFactory()
# Select ideal molar strategyideal = factory.get_strategy( strategy_type="molar_ideal", parameters={ "molar_mass": np.array([18.015e-3, 200.0e-3]), "molar_mass_units": "kg/mol", },)
# Select kappa strategykappa = factory.get_strategy( strategy_type="kappa", parameters={ "kappa": np.array([0.0, 0.3]), "density": np.array([1000.0, 1500.0]), "density_units": "kg/m^3", "molar_mass": np.array([18.015, 342.29]), "molar_mass_units": "g/mol", "water_index": 0, },)Integration with equilibria
Section titled “Integration with equilibria”Activity strategies integrate with liquid-vapor partitioning calculations. This equilibrium interface uses matching µg/m³ concentration inputs and g/mol molar masses; activity strategies above use kg/mol. Water supplied by the prescribed humidity reservoir is separate from the organic species balance:
import numpy as npimport particula as par
# Create partitioning strategypartitioning = par.equilibria.LiquidVaporPartitioningStrategy( water_activity=0.75, # 75% RH)
# Solve for equilibriumresult = partitioning.solve( c_star_j_dry=np.array([1e-6, 1e-4, 1e-2]), # ug/m³, matching organic inventory units concentration_organic_matter=np.array([1.0, 5.0, 10.0]), # ug/m^3 molar_mass=np.array([200.0, 200.0, 200.0]), # g/mol oxygen2carbon=np.array([0.2, 0.3, 0.5]), density=np.array([1200.0, 1200.0, 1200.0]), # kg/m^3)
# Access resultsprint(f"Partition coefficients: {result.partition_coefficients}")print(f"Alpha phase water: {result.alpha_phase.water_concentration}")Run the Python snippets in page order so imports and example arrays are
available to the later workflow snippets. These functional calculations do
not construct or mutate an Aerosol.
Getting Started
Section titled “Getting Started”Quick start: ideal activity calculation
Section titled “Quick start: ideal activity calculation”import numpy as npimport particula as par
# 1. Create activity strategystrategy = par.particles.ActivityIdealMolar( molar_mass=np.array([18.015e-3, 200.0e-3]), # kg/mol)
# 2. Define mass concentrationsmass = np.array([0.5e-9, 0.5e-9]) # kg/m^3
# 3. Compute activityactivity = strategy.activity(mass_concentration=mass)print(f"Activity: {activity}")
# 4. Compute partial pressurespure_pressure = np.array([3169.0, 1e-3]) # Papartial_p = strategy.partial_pressure( pure_vapor_pressure=pure_pressure, mass_concentration=mass,)print(f"Partial pressures: {partial_p}")Prerequisites
Section titled “Prerequisites”particulaversion 0.2.6 or later installed- Basic familiarity with NumPy arrays
- Understanding of aerosol thermodynamics (helpful but not required)
Typical Workflows
Section titled “Typical Workflows”1. Choose an activity model
Section titled “1. Choose an activity model”Select the appropriate strategy based on your system:
- Simple mixtures: Use
ActivityIdealMolarorActivityIdealMass - Hygroscopic aerosols: Use
ActivityKappaParameterwith known kappa values - Organic-water mixtures: Use
ActivityNonIdealBinary(BAT model)
2. Configure with a builder
Section titled “2. Configure with a builder”Use builders for validated configuration:
strategy = ( par.particles.ActivityNonIdealBinaryBuilder() .set_molar_mass(200.0, "g/mol") .set_oxygen2carbon(0.4) .set_density(1.2, "g/cm^3") .build())3. Compute activity or partial pressure
Section titled “3. Compute activity or partial pressure”Call the strategy methods with mass concentration arrays:
activity = strategy.activity(mass_concentration=mass)partial_p = strategy.partial_pressure(pure_pressure, mass_concentration=mass)4. Integrate with equilibria
Section titled “4. Integrate with equilibria”Combine with partitioning strategies for full thermodynamic calculations:
partitioning = par.equilibria.LiquidVaporPartitioningStrategy( water_activity=0.75,)result = partitioning.solve( c_star_j_dry=np.array([1e-6, 1e-4, 1e-2]), # ug/m³ concentration_organic_matter=np.array([1.0, 5.0, 10.0]), # ug/m³ molar_mass=np.array([200.0, 200.0, 200.0]), # g/mol oxygen2carbon=np.array([0.2, 0.3, 0.5]), density=np.array([1200.0, 1200.0, 1200.0]), # kg/m³)Use Cases
Section titled “Use Cases”Use case 1: Hygroscopic growth calculation
Section titled “Use case 1: Hygroscopic growth calculation”Scenario: Calculate water activity for ammonium sulfate aerosol at different water contents.
Solution: Use ActivityKappaParameter with known kappa values and compute activity across a range of compositions.
Use case 2: Organic aerosol partitioning
Section titled “Use case 2: Organic aerosol partitioning”Scenario: Model gas-particle partitioning of organic compounds using realistic non-ideal thermodynamics.
Solution: Use ActivityNonIdealBinary with BAT model parameters, then integrate with LiquidVaporPartitioningStrategy for equilibrium calculations.
Use case 3: Comparing activity models
Section titled “Use case 3: Comparing activity models”Scenario: Evaluate the effect of non-ideal activity on partitioning predictions.
Solution: Create both ideal and non-ideal strategies, compute activity at the same compositions, and compare results.
Configuration
Section titled “Configuration”Strategy Parameters
Section titled “Strategy Parameters”| Strategy | Parameter | Description | Units |
|---|---|---|---|
ActivityIdealMolar |
molar_mass |
Species molar masses | kg/mol |
ActivityIdealMass |
(none) | No parameters required | - |
ActivityKappaParameter |
kappa |
Hygroscopic parameters | dimensionless |
density |
Species densities | kg/m^3 | |
molar_mass |
Species molar masses | kg/mol | |
water_index |
Index of water species | int | |
ActivityNonIdealBinary |
molar_mass |
Organic molar mass | kg/mol |
oxygen2carbon |
O:C ratio | dimensionless | |
density |
Organic density | kg/m^3 |
Factory Strategy Types
Section titled “Factory Strategy Types”| Type Name | Strategy Class |
|---|---|
"ideal_mass" |
ActivityIdealMass |
"ideal_molar" |
ActivityIdealMolar |
"kappa" |
ActivityKappaParameter |
"non_ideal_binary" |
ActivityNonIdealBinary |
Best Practices
Section titled “Best Practices”- Match model to system: Use ideal strategies for simple mixtures, kappa for inorganic hygroscopic aerosols, and BAT for organic-water systems
- Use builder validation: Set parameters through builders to ensure unit conversion and validity checks
- Check finite, nonnegative activities: Non-ideal activity can exceed one; do not clip it to a mole-fraction bound.
- Consider temperature effects: The BAT model includes temperature-dependent parameters; ensure consistency
- Validate with experiments: Compare model predictions against measured hygroscopic growth or partitioning data
- Use consistent units: Mass concentrations are expected in kg/m^3; use builders for automatic conversion
Limitations
Section titled “Limitations”- Binary organic-water only:
ActivityNonIdealBinaryassumes a binary organic-water system; multi-organic mixtures use mean properties - No solid-liquid equilibria: Current strategies handle liquid-vapor systems only
- Temperature range: BAT model parameters are optimized for ambient temperatures (250-310 K)
- Kappa model assumptions: Assumes volume additivity and spherical particles
Related Documentation
Section titled “Related Documentation”- Theory: Activity Theory - Mathematical foundations
- Theory: Equilibria Theory - Partitioning equations
- Examples: Activity Examples - Working code examples
- Tutorial: Activity Tutorial - Interactive notebook
Which activity model should I use?
Section titled “Which activity model should I use?”- For dilute aqueous solutions:
ActivityIdealMolar(Raoult’s Law) - For hygroscopic inorganics:
ActivityKappaParameterwith measured kappa values - For organic aerosols:
ActivityNonIdealBinary(BAT model)
How do I get activity coefficients?
Section titled “How do I get activity coefficients?”Activity = activity coefficient x mole fraction. For ideal strategies, the activity coefficient is 1. For non-ideal strategies, you can compute activity coefficients by dividing activity by mole fraction.
Can I use custom activity models?
Section titled “Can I use custom activity models?”Yes. Subclass ActivityStrategy from particula.particles.activity_strategies and implement the activity() and partial_pressure() methods.
How does activity connect to equilibria?
Section titled “How does activity connect to equilibria?”Activity determines the effective concentration that drives phase equilibrium. The LiquidVaporPartitioningStrategy uses BAT model activity internally to compute gas-particle partitioning.
See Also
Section titled “See Also”Explore this topic: Chemical activity