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 Julia, Matlab and C++ example snippets below).

TL;DR (try in a Jupyter notebook)

! pip install git+https://github.com/open-atmos/PyPartMC.git
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 & Matlab (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_state = ppmc.GasState()
# ... TODO

example object instantiation in C++

//... TODO

example object instantiation in Julia

using Pkg
Pkg.add("PyCall")

using PyCall
ppmc = pyimport("PyPartMC")
print(ppmc.__version__)
GasState = ppmc.GasState
gas_state = GasState()
#... TODO

example object instantiation in Matlab

Note that since Matlab ships with and prioritizes its own GCC libraries (libgfortran.so, libstdc++.so, libgcc_s.so, libquadmath.so), it is essential to build PyPartMC with the same version of GCC as the one Matlab files are based on.

ppmc = py.importlib.import_module('PyPartMC');
ver = char(py.getattr(ppmc, "__version__"))
system(['ldd ' char(py.getattr(ppmc, "__file__"))]) 
%GasState = ppmc.GasState;
%gas_state = GasState();
% ... TODO (pending resolution of https://github.com/pybind/pybind11/issues/3945)

Jupyter notebooks with examples

... TODO ...

usage in other projects

PyPartMC is also used within the tests of PySDM project ... TODO

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)

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 tests

Credits

PyPartMC:

author: Sylwester Arabas
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