wellbalanced

Global (0D) and 1D fluid models of low-temperature plasmas.

• Global model (GlobalModel): the density of every species, the electron energy and optionally the gas temperature, balanced over the volume of a chamber. Reactions, ions leaving through the walls at the Bohm speed (with an edge-to-centre ratio) and through magnetic cusps (hybrid leak width), neutral wall reactions, gas feed and pumping, and volume sources such as a fast beam. Steady states in seconds, and scans that continue from one steady state to the next.
• 1D fluid model (Fluid1D): drift-diffusion of every species with Scharfetter-Gummel fluxes, the electron energy equation and Poisson’s equation, fully implicit. Ions may carry their momentum equation instead (friction from their mobility), so they reach the Bohm speed at the sheath edge; checked against the closed-form collisionless presheath. Walls, prescribed densities or fluxes at either end, changeable between steps, as the fluid side of a coupling to a particle code.
• 2D axial-azimuthal drift fluid of a magnetron (DriftFluid2D): magnetised electrons with the Hall tensor, inertial ions, neutral depletion and refill, the electron energy and a semi-implicit Poisson solve; the gradient-drift instability and spoke diagnostics (mode number, phase velocity against E x B, cathode modulation, potential hump).
• A global model of the magnetron ionization region (Magnetron, wellbalanced.magnetron): Ar and the sputtered metal, Bohm losses through the target with sputtering and self-sputtering, argon refill and sputter wind, driven by the discharge current and voltage of a pulse or of dc; it reports the argon rarefaction, the metal to argon ratio, the metal share of the ion flux and the self-sputtering share against the current. Yields and geometry are placeholders, not data.
• The neutral gas of a magnetron (GasDynamics, wellbalanced.gasdynamics): argon and the sputtered metal as one compressible gas in 1D or 2D (HLLC, species diffusion, heat conduction), with the sputter wind, the return of neutralized ions, ionization sinks, wall heat exchange and a refill reservoir as inputs a plasma model can update; the rarefaction that spokes depend on. The continuum limit, so Knudsen numbers near 1 need a kinetic check.
• A beam-driven plasma neutralizer (wellbalanced.neutralizer): a fast beam’s charge states on the gas and on the plasma it makes, coupled to a global model of the channel fed by the beam’s stripped and secondary electrons, iterated to a fixed point in seconds. The beam’s sources are functions of its local flux, energy and charge states, with cross sections that may depend on the energy and secondary electrons of the mean energy of their distribution (e.g. Rudd’s, from plasmacoll); the same sources drive a Fluid1D across the channel, whose average over the width reproduces the global model (electron temperature within 0.1%, densities within 3%). The gas along the channel is a GasProfile: Knudsen diffusion from the feed to the open ends, or the profile of a kinetic run such as picnic’s NeutralParticleTransport; every axial slice’s own plasma comes from Neutralizer.local_plasma.
• The inductive RF field of a driver (InductiveField2D, wellbalanced.spatial): the magnetoquasistatic vector potential of coil windings, perfect conductors (backplates, electromagnetic shields) and a prescribed plasma in a 2D Cartesian cut or in r–z, with cold electrons or with the collisional electron viscosity, time-harmonic or (cold) time-dependent; the absorbed power, the coil current for a given power and the RF power transfer efficiency. DriverCoupling closes the loop with a power-dependent plasma (a global model’s or Fluid2D’s) at a set absorbed or generator power. Shapes come from simgeometry (pip install "wellbalanced[spatial]", which also installs patchwork, on PyPI as patchwork-amr). On a tensor grid stretched toward the far boundary, or on refined patches (PatchGrid): a coarse base out to the far boundary and fine patches only over the coil and the skin layer.
• The driver plasma in 2D (Fluid2D, wellbalanced.spatial): a multi-species fluid on the field’s cells, in r–z or in a cut: ion continuity and momentum (inertia, drag on the gas), drift-diffusion electrons with their energy, a quasi-neutral potential with sheath walls (or Poisson’s equation, which on a slab is Fluid1D), heated by the field’s 1/2 Re(J E*) and pushed off the coil by its RF Lorentz force; fluid_plasma iterates field and fluid to a fixed point for DriverCoupling. On a tensor grid or on refined patches: one implicit step of all levels, one flux per leaf face, so particles and energy are conserved to round-off across levels (what patchwork’s refluxing restores).
• The driver’s gas (NeutralFluid2D, wellbalanced.spatial): H and H2 as two Navier–Stokes fluids (density, velocity and temperature each; the model of Zielke et al., PSST 31, 035019, 2022) on the plasma’s cells, with the plasma’s reactions (dissociation, ionization, Franck–Condon heating), collisions with the ions (charge exchange) and kinetic walls: atoms recombining with a probability, ions coming back as gas, a gas inlet and a grid of some transparency. couple_neutrals iterates it with Fluid2D to a common steady state, so the gas thins and heats where the plasma is.
• A 0D RF driver (RFDriver, wellbalanced.driver): the global model of the driver plasma coupled to a transformer model of the coil, giving the coil current and the RF power transfer efficiency against the absorbed power, the frequency and the geometry in seconds, for an optimiser. No shields and no neighbouring drivers: those are the 2D field’s part.
• The data of the kinetic codes: rates come from plasmacoll’s cross sections averaged over a Maxwellian, the data its Monte Carlo collisions use, so a fluid and a kinetic model of the same plasma differ in their physics, not their data.

The name: a well-balanced scheme keeps the steady states of its equations exactly, and steady balances are what this code is for.

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

Example

from plasmacoll import CrossSection
from plasmacoll.constants import ELECTRON_MASS

from wellbalanced import ELECTRON, Chamber, GlobalModel, Reaction, Species

argon, argon_ion = Species.atomic("Ar", 39.948), Species.atomic("Ar+", 39.948, 1)
ionization = Reaction.from_cross_section(
    ("e", "Ar"),
    ("e", "e", "Ar+"),
    CrossSection.constant(2.0e-20, threshold=15.76),
    ELECTRON_MASS,
    electron_energy_loss=15.76,
)
model = GlobalModel(
    species=[ELECTRON, argon, argon_ion],
    reactions=[ionization],
    chamber=Chamber(volume=1.0e-3, wall_area=0.06, h_factor=0.5),
    power=100.0,
    fixed={"Ar": 1.0e20},
)
state = model.steady_state()
print(state.electron_temperature, state.electron_density, state.power)

Install

With uv:

make install    # uv sync --extra dev, plus the pre-commit hooks

Or with pip, in a Python environment (3.10 or newer):

pip install -e .

The test, docs and dev extras install the test runner, the documentation tooling and the linters:

pip install -e ".[dev]"

Profiling

The solves, time steps and runs (GlobalModel.steady_state and evolve, Fluid1D’s Newton solves, the step and run of GasDynamics and DriftFluid2D, Neutralizer.solve, …) carry scope-profiler regions named wellbalanced.<Class>.<method>. They are off by default (a region that is off costs about 0.1 µs per call); an application that profiles itself turns them on with the opt-in tag wellbalanced:

import scope_profiler as sp

sp.setup(enable_tags=["wellbalanced"])  # or session(enable_tags=...)

or, without changing the code, SCOPE_PROFILER_ENABLE_TAGS=wellbalanced or scope-profiler run --enable-tag wellbalanced script.py.

Development

Formatting and linting use ruff, type checking pyright, run by pre-commit and in CI:

make lint     # ruff check, ruff format --check, pyright
make test     # pytest with coverage

Commit messages follow Conventional Commits; see CONTRIBUTING.md.

Build docs

The documentation in docs/ is an Astro + Starlight site: hand-written pages, the notebooks in tutorials/ executed and published as pages, complete Python scripts in examples/ published with their plots, and the API reference generated from the docstrings with starlight-pydocs. 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-examples    # run examples/*.py and publish their plots
make docs-dev         # live preview at http://localhost:4321/wellbalanced/
make docs-build       # the static site in docs/dist

Build the README

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

make readme

Releases

Before merging a release to main, update the version in pyproject.toml, src/wellbalanced/__init__.py and CITATION.cff (including its release date), 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). The one-time PyPI and GitHub configuration is described in the publishing tutorial.