plasmacoll

Null-collision Monte Carlo collisions (MCC) of charged particles with neutral gases, on NumPy or CuPy arrays. It is the collision step of a particle-in-cell code, or with ZeroDReactor a homogeneous reactor for testing cross-section sets.

• Processes: elastic, backscatter (resonant charge exchange), excitation, ionization, attachment, detachment and charge transfer, against Maxwellian neutral gases that are uniform or have a density profile.
• Cross sections: from text tables, LXCat files or functions. Also Maxwell molecules for benchmarks, and population-weighted mixtures of level-resolved tables, e.g. H₂(v) dissociative attachment.
• Plain arrays: markers are positions, velocities and weights. Any particle container with those plugs in, and cunumpy runs the same code on CPU (NumPy) or GPU (CuPy).
• Validated: a 0D reactor reproduces the closed-form relaxation, growth and decay rates of Maxwell-molecule gases. The tests run on NumPy and on a CuPy stand-in, with 100 % combined coverage.

Documentation: https://max-models.github.io/plasmacoll/

Install

pip install plasmacoll

Example

import plasmacoll
from plasmacoll.constants import ATOMIC_MASS, ELECTRON_MASS, ev_to_kelvin

argon_mass = 39.95 * ATOMIC_MASS
argon_gas = plasmacoll.NeutralBackground(
    "Ar", density=1e21, temperature=300.0, mass=argon_mass
)

elastic_xs = plasmacoll.CrossSection.constant(1e-19)
ionization_xs = plasmacoll.CrossSection.constant(3e-20, threshold=15.76)
elastic = plasmacoll.CollisionProcess("elastic", "Ar", elastic_xs, energy_frame="lab")
ionization = plasmacoll.CollisionProcess(
    "ionization",
    "Ar",
    ionization_xs,
    energy_frame="lab",
    products={"electron": "e", "ion": "Ar+"},
)

mcc = plasmacoll.MonteCarloCollisions(
    species_masses={"e": ELECTRON_MASS, "Ar+": argon_mass},
    backgrounds=[argon_gas],
    processes={"e": [elastic, ionization]},
    seed=1,
)

temperature = ev_to_kelvin(10.0)
electrons = plasmacoll.ParticleArrays.maxwellian(
    100_000, ELECTRON_MASS, temperature, seed=2
)
reactor = plasmacoll.ZeroDReactor(mcc, {"e": electrons}, volume=1e-6)
history = reactor.run(dt=1e-11, num_steps=500, every=10)
print(history.density["Ar+"][-1], history.collisions["ionization:Ar"][-1])

In a particle-in-cell code, call mcc.collide(species, positions, velocities, weights, dt) on arrays, or mcc.collide_species({...}, dt) on your own particle containers. See Use in a particle-in-cell code.

plasmacoll does not ship cross-section data. Load tables from LXCat or the literature with plasmacoll.read_lxcat and CrossSection.from_table.

Development

With uv:

make install    # uv sync --extra dev, plus the pre-commit hooks
make test       # pytest with coverage on NumPy
make test-cupy  # the same tests on cunumpy's stand-in for CuPy (no GPU needed)
make coverage   # both runs combined, must be 100 %
make lint       # ruff check, ruff format --check, pyright, ty

Commit messages follow Conventional Commits.

Build docs

The documentation in docs/ is an Astro + Starlight site: hand-written guides, the notebooks in tutorials/ executed and published as pages, and the API reference generated from the docstrings. It needs Node 22 or newer.

make docs-install     # npm packages and the Python docs extra
make docs-notebooks   # execute tutorials/*.ipynb and convert them to pages
make docs-dev         # live preview at http://localhost:4321/plasmacoll/
make docs-build       # the static site in docs/dist

README.md is rendered from README.qmd with Quarto: make readme.

Releases

Before merging a release to main, update the version in pyproject.toml and src/plasmacoll/__init__.py, and add the release notes to CHANGELOG.md. The push to main creates a GitHub release with a vX.Y.Z tag and publishes the package to PyPI with trusted publishing (OIDC). See the publishing guide.