Metadata-Version: 2.4
Name: particula
Version: 0.2.11
Summary: a simple, fast, and powerful particle simulator
Keywords: atmospheric,particles,climate,aerosol,particulate
Author-email: Particula developers <uncscode@users.noreply.github.com>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
License-File: license
Requires-Dist: numpy>=2.0.0
Requires-Dist: scipy>=1.12
Requires-Dist: typing_extensions>=4.0.0
Requires-Dist: particula[dev] ; extra == "all"
Requires-Dist: particula[extra] ; extra == "all"
Requires-Dist: pylint ; extra == "dev"
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: pytest-cov ; extra == "dev"
Requires-Dist: autopep8 ; extra == "dev"
Requires-Dist: jupyterlab ; extra == "dev"
Requires-Dist: build ; extra == "dev"
Requires-Dist: flake8 ; extra == "dev"
Requires-Dist: jupyter-book ; extra == "dev"
Requires-Dist: ghp-import ; extra == "dev"
Requires-Dist: mkdocs ; extra == "dev"
Requires-Dist: mkdocs-material[imaging] ; extra == "dev"
Requires-Dist: mkdocs-jupyter ; extra == "dev"
Requires-Dist: mkdocstrings[python] ; extra == "dev"
Requires-Dist: mkdocs-gen-files ; extra == "dev"
Requires-Dist: mkdocs-literate-nav ; extra == "dev"
Requires-Dist: griffe ; extra == "dev"
Requires-Dist: openai ; extra == "dev"
Requires-Dist: GitPython ; extra == "dev"
Requires-Dist: ruff ; extra == "dev"
Requires-Dist: mypy ; extra == "dev"
Requires-Dist: ipykernel ; extra == "extra"
Requires-Dist: nbclient ; extra == "extra"
Requires-Dist: nbconvert ; extra == "extra"
Requires-Dist: nbformat ; extra == "extra"
Requires-Dist: matplotlib ; extra == "extra"
Requires-Dist: pandas ; extra == "extra"
Requires-Dist: pint ; extra == "extra"
Requires-Dist: thermo ; extra == "extra"
Requires-Dist: tqdm ; extra == "extra"
Project-URL: homepage, https://github.com/uncscode/particula
Project-URL: repository, https://github.com/uncscode/particula
Provides-Extra: all
Provides-Extra: dev
Provides-Extra: extra

# Particula

A simple, fast, and powerful particle simulator for aerosol science.

**Requires:** Python 3.12+

[Documentation](https://uncscode.github.io/particula) | [Examples](https://uncscode.github.io/particula/Examples/) | [PyPI](https://pypi.org/project/particula/)

## Installation

```bash
pip install particula
```

or via conda:

```bash
conda install -c conda-forge particula
```

## Quick Start

```python
import particula as par

# Build an aerosol system
aerosol = (
    par.AerosolBuilder()
    .set_atmosphere(atmosphere)
    .set_particles(particles)
    .build()
)

# Run dynamics (chainable with | operator)
process = par.dynamics.Condensation(strategy) | par.dynamics.Coagulation(strategy)
aerosol = process.execute(aerosol, time_step=10, sub_steps=1000)
```

## Code Structure

```
particula/
├── gas/           # Gas phase: species, vapor pressure, atmosphere
├── particles/     # Particle representations & distributions
├── dynamics/      # Time-dependent processes
│   ├── coagulation/
│   ├── condensation/
│   └── wall_loss/
├── activity/      # Activity coefficients, phase separation
├── equilibria/    # Gas-particle partitioning
└── util/          # Constants, validation, unit conversion
```

## Documentation Guide

| Looking for...            | Go to                                      |
|---------------------------|--------------------------------------------|
| Tutorials & walkthroughs  | [Examples/](https://uncscode.github.io/particula/Examples/) |
| Scientific background     | [Theory/](https://uncscode.github.io/particula/Theory/) |
| API reference             | [Full Docs](https://uncscode.github.io/particula) |
| Contributing              | [contribute/](./docs/contribute/CONTRIBUTING.md) |

### Examples by Topic

- **Aerosol** — Building and inspecting aerosol objects
- **Dynamics** — Coagulation, condensation, wall loss simulations
- **Equilibria** — Gas-particle partitioning calculations
- **Gas Phase** — Vapor pressure, species properties
- **Particle Phase** — Size distributions, optical properties
- **Simulations** — Full end-to-end scientific scenarios

### Featured Examples

- [**Aerosol Tutorial**](./docs/Examples/Aerosol/Aerosol_Tutorial.ipynb) — Learn how to build gas species, atmospheres, particle distributions, and combine them into an `Aerosol` object.

- [**Organic Partitioning & Coagulation**](./docs/Examples/Simulations/Notebooks/Organic_Partitioning_and_Coagulation.ipynb) — Full simulation of secondary organic aerosol (SOA) formation from 10 organic vapors, followed by Brownian coagulation over 10 minutes.

- [**Cloud Chamber Cycles**](./docs/Examples/Simulations/Notebooks/Cloud_Chamber_Cycles.ipynb) — Multi-cycle cloud droplet activation demonstrating κ-Köhler theory across 3 seed compositions (Ammonium Sulfate, Sucrose, Mixed), showing how hygroscopicity affects activation at different supersaturations.

## Features

- **Gas & Particle Phases** — Full thermodynamic modeling with swappable strategies
- **Dynamics** — Coagulation, condensation, wall loss, dilution
- **Flexible Representations** — Discrete bins, continuous PDF, particle-resolved
- **Builder Pattern** — Clean, validated object construction with unit conversion
- **Composable Processes** — Chain runnables with `|` operator

## Citation

If you use Particula in your research, please cite:
> Particula [Computer software]. DOI: [10.5281/zenodo.6634653](https://doi.org/10.5281/zenodo.6634653)

## License

MIT

