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, optionally in an electric field, for testing cross-section sets.

• Processes: elastic, backscatter (resonant charge exchange), excitation, ionization (electron and ion impact), attachment, detachment, charge transfer, dissociation, dissociative attachment and dissociative ionization. Isotropic or forward-peaked (Vahedi–Surendra, Okhrimovskyy) scattering, and equal, uniform or Opal–Peterson–Beaty energy sharing. Fast neutrals and fragments can be tracked as species.
• Neutral gases: drifting Maxwellians with density and temperature profiles, replaceable between steps for gas heating or depletion.
• Cross sections: from text tables, LXCat files (with EFFECTIVE sets converted to elastic) 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). Markers can be merged and split, conserving weight, momentum and energy.
• Validated: a 0D reactor reproduces the closed-form relaxation, growth and decay rates of Maxwell-molecule gases, and the drift velocity and Wannier energy of a swarm in a field. The tests run on NumPy and on a CuPy stand-in, with 100 % combined coverage.

Collisions between charged particles (Coulomb collisions, recombination) are out of scope: the collision partners are always neutral gases.

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.