PyPartMC 0.0.18

Python interface to PartMC

PyPartMC (pre-alpha!)

PyPartMC is a Python interface to PartMC, a particle-resolved Monte-Carlo code for atmospheric aerosol simulation. Since PyPartMC is implemented in C++, it also constitutes a C++ API to the PartMC Fortran internals; the Python API can be used from other environments - see, e.g., Julia example below.

TL;DR (try in a Jupyter notebook)

! pip install PyPartMC
import PyPartMC

Features

• works on Linux, macOS and Windows (compatibility assured with CI builds)
• hassle-free installation using pip (prior PartMC installation not needed)
• works out of the box on mybinder.org, Google Colab and alike
• ships with a set of examples maintained in a form of Jupyter notebooks
• Pythonic API (but retaining PartMC jargon) incl. exceptions and GC deallocation of Fortran objects
• code snippets in README depicting how to use PyPartMC from Julia (also executed on CI)
• auto-generated docs on the web
• support for [de]serialization of all exposed structures using JSON
• based on unmodified PartMC code
• does not use or require shell or netCDF Fortran library
• aiming at 100% unit test coverage

Usage examples

example object instantiation in Python

import PyPartMC as ppmc
print(ppmc.__version__)
gas_data = ppmc.GasData(("H2SO4", "HNO3", "HCl", "NH3", "NO", "NO2"))

example object instantiation in Julia

using Pkg
Pkg.add("PyCall")

using PyCall
ppmc = pyimport("PyPartMC")
print(ppmc.__version__)
gas_data = ppmc.GasData(("H2SO4", "HNO3", "HCl", "NH3", "NO", "NO2"))

Jupyter notebooks with examples

See the PyPartMC-examples project.

usage in other projects

PyPartMC is used within the test workflow of the PySDM project.

Implementation outline

• PyPartMC is written in C++, Fortran and uses pybind11 and CMake.
• JSON support is handled with nlohmann::json and pybind11_json
• PartMC and selected parts of SUNDIALS are compiled during pip install and statically linked
• C (SUNDIALS), C++ (pybind11, ...) and Fortran (PartMC) dependencies are linked through git submodules
• a mock of Fortran netCDF API and a mock of PartMC spec file API are used for i/o from/to JSON
• a mock of Fortran MPI API is used for error handling using existing MPI API calls within PartMC

Troubleshooting

Common installation issues

error: [Errno 2] No such file or directory: 'cmake'

Try rerunning after installing CMake (e.g., apt-get install cmake or brew install cmake)

No CMAKE_Fortran_COMPILER could be found.

Try installing a Fortran compiler (e.g., brew reinstall gcc)

warning: no files found matching 'gitmodules/...

Since git clone was done without recursive option, try: git submodule update --init

Notes for developers

How to debug

git clone --recursive git+https://github.com/open-atmos/PyPartMC.git
cd PyPartMC
DEBUG=1 VERBOSE=1 pip --verbose install -e .
gdb python 
(gdb) run -m pytest -s -vv -We -p no:unraisableexception tests

Pre-commit hooks

PyPartMC codebase benefits from Pylint, Black and isort code analysis (which are all part of the CI workflows where we also use pre-commit hooks. The pre-commit hooks can be run locally, and then the resultant changes need to be staged before committing. To set up the hooks locally, install pre-commit via pip install pre-commit and set up the git hooks via pre-commit install (this needs to be done every time you clone the project). To run all pre-commit hooks, run pre-commit run --all-files. The .pre-commit-config.yaml file can be modified in case new hooks are to be added or existing ones need to be altered.

Credits

PyPartMC:

author: PyPartMC developers
funding: US Department of Energy Atmospheric System Research programme
copyright: University of Illinois at Urbana-Champaign
licence: GPL v3

PartMC:

authors: Nicole Riemer, Matthew West, Jeff Curtis et al.
licence: GPL v2 or later