PyMopsmap
A Python wrapper for MOPSMAP. Compute aerosol optical properties with Mie, T-matrix and DDA single-particle scattering. See Gasteiger and Wiegner (2018), GMD for the model itself.
docs/guide.md is the documentation. What follows is the short tour.
The idea
An aerosol is a description: a size distribution, a refractive index, a shape, how it responds to water. That description does not change when the conditions around it do:
- the air it sits in, through relative humidity,
- the wavelength it is looked at,
- where and when it is.
So the description is the object, and the conditions are the call.
import numpy as np
import pymopsmap as pm
aer = pm.Specie.custom(
pm.Mode(
shape=pm.shapes.Sphere(),
psd=pm.psd.LognormalPSD(
rm=0.12, sigma=1.8, n=1e9, rmin=0.005, rmax=20.0
),
n_real=1.53,
n_imag=0.008,
density_dry=2.6,
kappa=0.2,
),
name="my dust",
)
Eight numbers and a shape. That is the whole aerosol, and nothing in it mentions a wavelength or a humidity.
One aerosol, many conditions
op = aer.compute(wl=np.linspace(0.4, 2.0, 100), rh=[0, 50, 80])
op.sizes # {'rh': 3, 'wl': 100}
op["kext"] # <xarray.DataArray (rh: 3, wl: 100)>
op["ssa"]
The dimensions you asked for come back as the dimensions you named. The answer
is a plain xarray.Dataset, so the whole xarray API applies to it: sel,
interp, mean, to_netcdf, plotting.
A description that varies too
A modal radius you do not know is not a condition, it is part of the
description. So it goes where the radius goes, as a DataArray:
import xarray as xr
aer = pm.Specie.custom(
pm.Mode(
shape=pm.shapes.Sphere(),
psd=pm.psd.LognormalPSD(
rm=xr.DataArray(np.linspace(0.05, 0.4, 8), dims="rm"),
sigma=xr.DataArray(np.linspace(1.4, 2.2, 5), dims="sigma"),
n=1e9, rmin=0.005, rmax=20.0,
),
n_real=1.53, n_imag=0.008, density_dry=2.6, kappa=0.2,
),
name="my dust",
)
aer.swept # {'rm': 8, 'sigma': 5}
op = aer.compute(wl=[0.55], rh=[0, 50, 80])
op.sizes # {'rh': 3, 'rm': 8, 'sigma': 5, 'wl': 1}
Any numeric field of a mode accepts one: the modal radius, the width, the bounds, the refractive index, the aspect ratio of a spheroid. Distinct dimensions multiply, and the call never changes.
A scene
The same thing holds in two or three dimensions, which is what a satellite image or a model output is. A size that varies from pixel to pixel, a humidity that varies from pixel to pixel and from hour to hour:
rm = xr.DataArray(..., dims=("y", "x")) # (12, 16)
rh = xr.DataArray(..., dims=("y", "x", "t")) # (12, 16, 4)
aer = pm.Specie.custom(
pm.Mode(
shape=pm.shapes.Sphere(),
psd=pm.psd.LognormalPSD(rm=rm, sigma=1.8, n=1e9, rmin=0.005, rmax=20),
n_real=1.53, n_imag=0.008, density_dry=2.6, kappa=0.2,
),
name="scene",
)
op = aer.compute(wl=[0.55], rh=rh)
op.sizes # {'y': 12, 'x': 16, 't': 4, 'wl': 1}
768 cells, and MOPSMAP runs 103 times: that is how many distinct pairs of radius and humidity the scene holds. Nothing in the call says so, and nothing has to.
Where to go next
| docs/guide.md | the documentation: the catalogue, saving a species, every output, humidity, mixtures, measured particles, and what the library cannot do |
| docs/validation.md | what agrees with the reference article, to what precision, and what does not |
| docs/api-v2-spec.md | the NetCDF schema a species is written in |
Installation
pip install pymopsmap
The built-in aerosol catalogue (CAMS, OPAC) ships with the package. Two external pieces are not bundled:
| Piece | How to get it |
|---|---|
| MOPSMAP binary | download from mopsmap.net, place at bin/mopsmap/mopsmap |
| Optical dataset | set PYMOPSMAP_DATASET_SOURCE to a local path or HTTP base URL; files are fetched on demand into ~/.cache/pymopsmap/ |
export PYMOPSMAP_DATASET_SOURCE=https://your-server.org/mopsmap_dataset
python -c "import pymopsmap as pm; print(pm.load(pm.CAMS.SULPHATE))"
For development:
git clone https://github.com/walcark/pymopsmap.git
cd pymopsmap
pixi install -e dev
Validation
The wrapper is held to the numbers published in
Gasteiger and Wiegner (2018), the
MOPSMAP article. Tables 3 to 6 of it, 92 values in all, are asserted in
tests/validation/, which also checks the same pipeline against miepython,
an implementation that shares no code with MOPSMAP.
export PYMOPSMAP_DATASET_SOURCE=/path/to/optical_dataset
pixi run -e dev test-validation
Both archives of the optical data set are needed: soot reaches a refractive index of 1.75, past the 1.64 the main one covers.
Nine figures of the article are recomputed by scripts/validation/.
| Figure | What it shows |
|---|---|
| 2 | single particles against size parameter, five shapes |
| 4 | the size sampling and index interpolation error of the data set |
| 5 | the ten OPAC types against relative humidity |
| 6 | phase functions of five dust size bins, spheres against spheroids |
| 7 | the OPAC desert type against the cutoff radius |
| 8 | one size distribution read through three size equivalences |
| 9 | dust scattering against the variability of its imaginary index |
| 10 | the truncation correction of an Aurora 3000 nephelometer |
| 11 | nine volcanic ashes, one mode per measured particle |
docs/validation.md says what agrees, to what precision, and what does not.
Roadmap
- Growable sweeps: a store holds one grid, so widening a request today recomputes it rather than extending what is already there.
- Transparent remote dataset: automatic download of the optical dataset
when
PYMOPSMAP_DATASET_SOURCEis not set, removing the manual setup step. - Tabulated OPAC: the wet state published by GEISA, alongside the kappa flavour that ships today. The GEISA file host was decommissioned during the migration of the database, so the links on its pages no longer resolve.
How the repository is laid out
src/pymopsmap/ the library
species/ Specie, Mode, Mix, the NetCDF schema, the catalogue
shapes.py Sphere, Spheroid, Irregular, and the rest
psd.py LognormalPSD, ModifiedGammaPSD, and the rest
microparams.py one validated point, rendered to MOPSMAP commands
engine/ one point, one MOPSMAP run, and the output rules
sweep.py a parameter space to points, and the xsweep binding
scatlib/ the optical data set: resolve, download, cache
accessors.py the .mopsmap accessor on a result
data/ the species catalogue the wheel ships
tests/
unit/ nothing but the package, MOPSMAP stubbed
integration/ the binary and the data set, end to end
validation/ the published numbers of the reference article
data/ fixtures, not the library's data
scripts/ none of it is imported by the package
build_catalog/ builds src/pymopsmap/data
validation/ redraws the article's figures
demo/ draws the guide, and sweeps a real CAMS scene
docs/
guide.md the documentation
validation.md what agrees with the article, and what does not
api-v2-spec.md the NetCDF schema a species is written in
figures/ committed, and regenerated by scripts/
bin/mopsmap/ the MOPSMAP distribution: binary, source, data, examples
Three levels, and only the first and third are usually in your way.
| Level | Object | Role |
|---|---|---|
| Description | Specie |
the parameter space, from a file or built in Python |
| Point | MicroParameters |
one concrete, validated point of it |
| Combination | Mix |
species weighted into an external mixture |
tests/README.md and scripts/README.md say what each directory needs and
what it proves.
Development
pixi run -e dev test # unit, no data set needed
pixi run -e dev test-integration # the pipeline end to end
pixi run -e dev test-validation # against the published article
pixi run -e dev all # fmt + lint + type-check + test
tests/README.md says what each directory needs and proves, and
scripts/README.md what each script produces.
Metadata
Release files for pymopsmap 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pymopsmap-0.5.0.tar.gz | 3.4 MB | With provenance | Details for pymopsmap-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pymopsmap-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for pymopsmap-0.5.0-py3-none-any.whl |
Total release size: 3.7 MB
Release files / pymopsmap-0.5.0.tar.gz
| Download URL | pymopsmap-0.5.0.tar.gz |
|---|---|
| Size | 3.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b34a8d79a9134909443e7817ddf63b0a9125ee6a61c082b44a12d574cedd203f
|
|
BLAKE2b-256 checksum How to use checksums |
3d83a50947344805782b992c5db990996052d73b19c1d878ec960c18792e50d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / pymopsmap-0.5.0-py3-none-any.whl
| Download URL | pymopsmap-0.5.0-py3-none-any.whl |
|---|---|
| Size | 286.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dbb96769f89b987038bd3bc6d0f5bb40c0b88b013f50fc366528bced04bd52a1
|
|
BLAKE2b-256 checksum How to use checksums |
5df3349e21e038f9de15d0b76636c4e9eb563c30e1c18da686bcaefa0647393f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logSecurity for pymopsmap 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pymopsmap-0.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.