Skip to main content

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.

Four species across the solar spectrum


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 two-dimensional declared sweep


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_SOURCE is 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)

Source distribution for pymopsmap 0.5.0
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)

Table of built distributions (wheels) for pymopsmap 0.5.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page