Metadata-Version: 2.4
Name: part2pop
Version: 0.1.1
Summary: A modular Python toolkit to build, analyze, and extend aerosol particle populations.
Author: Laura Fierce, Payton Beeler
License: MIT License
        
        Copyright (c) 2025 Battelle Memorial Institute, LLC 
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/pnnl/part2pop
Project-URL: Repository, https://github.com/pnnl/part2pop
Project-URL: Issues, https://github.com/pnnl/part2pop/issues
Keywords: aerosols,atmospheric science,aerosol-radiation,aerosol-cloud,particle populations,CCN,optics,ice nucleation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: netCDF4
Requires-Dist: importlib-resources
Requires-Dist: PyMieScatt
Requires-Dist: pyBCabs
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-cov>=4; extra == "test"
Dynamic: license-file

# part2pop

A modular Python toolkit for scaling particle-level models to predict population-level aerosol effects.

`part2pop` is a lightweight Python library that provides a **standardized representation of aerosol particles and populations**, together with modular builders for species, particle populations, optical properties, freezing properties, and analysis tools.

Its **builder/registry design** makes the system easily extensible: new population types, particle morphologies, freezing parameterizations, or species definitions can be added by placing small modules into the appropriate factory directory—without modifying core code.

The framework enables reproducible process-level investigations, sensitivity studies, and intercomparison analyses across diverse model and observational datasets by providing a consistent interface for aerosol populations derived from models, measurements, or parameterized distributions.

## Features

- **Standardized aerosol representation** via `AerosolSpecies`, `AerosolParticle`, and `ParticlePopulation`
- **Species registry** with density, refractive index, hygroscopicity, and thermodynamic properties
- **Population builders** for monodisperse, lognormal, sampled, and model-derived populations
- **Optical-property builders** supporting homogeneous spheres, core–shell particles, and fractal aggregates
- **Freezing-property builders** for immersion-freezing metrics
- **Analysis utilities** for size distributions, hygroscopic growth, CCN activation, and bulk moments
- **Visualization tools** for size distributions, optical coefficients, and freezing curves

Optional external packages (e.g., PyMieScatt, pyBCabs, netCDF4) are used when available.

## Installation

```bash
pip install part2pop
```

For development:

```bash
git clone https://github.com/pnnl/part2pop.git
cd part2pop
pip install -e .
```

## Quick start

```python
from part2pop.population.builder import build_population

config = {
    "type": "monodisperse",
    "diameter": 0.2e-6,
    "species_masses": {"SO4": 1e-15, "BC": 5e-16},
}

pop = build_population(config)
print(pop)
```

More examples are available in the project repository.

## Contributing

`part2pop` is designed so that **all extensibility happens through factories**.

New population types, optical morphologies, freezing parameterizations, diagnostics, and visualization types can be added by placing small modules in the appropriate factory directories without changing the core API.

Please open an issue or pull request to discuss proposed additions.

## License

See the `LICENSE` file in the repository.
