DRBX Documentation¶

DRBX is a JAX-first edge and scrape-off-layer plasma toolkit for drift-reduced Braginskii modeling, Hasegawa-Wakatani drift-wave turbulence, linear stability analysis, differentiable reduced studies, open-field-line SOL and neutral/detachment physics, and reusable 3D stellarator geometry.

The documentation is written for two audiences. New users should be able to install the package, run the examples, and understand what each output file means. Developers and reviewers should be able to trace every advertised feature to source code, validation tests, algorithm notes, and capability boundaries.

Start Here¶

Install from PyPI:

pip install drbx

Or install from a clone:

git clone https://github.com/uwplasma/drbx
cd drbx
pip install -e .

Run the smallest native deck:

drbx inspect examples/inputs/restartable_diffusion.toml
drbx run examples/inputs/restartable_diffusion.toml --verbose

Run the flagship examples (each is a flat, self-documenting script: imports, a PARAMETERS block, explicit setup, a run loop with progress prints, then plotting):

PYTHONPATH=src python examples/tokamak/drift_wave_turbulence.py
PYTHONPATH=src python examples/sol/open_sol_flux_tube.py
PYTHONPATH=src python examples/benchmarks/b6_detachment_rollover.py
PYTHONPATH=src python examples/stellarator/stellarator_turbulence.py

Or start with the narrative walkthroughs in the Tutorials section: turbulence from zero, open SOL / neutrals / detachment, and stellarator FCI turbulence.

Documentation Map¶

Need	Read
Decide what DRBX can run today, with links to examples, source, tests, and outputs	Feature Reference
Learn by doing, with every parameter explained	Tutorials
Install, run the CLI, resume runs, and inspect outputs	Installation, Native Runtime CLI, Input And Output Reference
The governing equations of every shipped model	Models And Equations
The solvers and design decisions behind the code	Solvers And Design, Physics Models, Equation To Code Map
Browse the example scripts	Examples And Artifacts
Understand validation status and figures	Validation Gallery, Fluid 1D MMS Convergence
Work with stellarator, VMEC, imported field-line, and FCI geometry	Stellarator Examples, Connection Length, VMEC Extender Edge Fields, ESSOS Field-Line Import
Understand differentiability, JAX transforms, performance, and profiling	Performance And Differentiability, Autodiff And Scaling Examples, Profiling Runtime
Understand repository size, releases, PyPI, and artifact storage	Release Packaging

What Ships¶

The current release includes:

Feature family	User-facing surface
Native runtime	TOML decks, CLI runs, restart artifacts, structured progress logs, and Python drivers
1D and compact reduced-fluid models	restartable diffusion, manufactured-solution convergence, electrostatic vorticity
Drift-wave turbulence	JAX-native Hasegawa-Wakatani flagship with differentiable inverse design
Linear stability	drift-wave, shear-Alfven, and interchange dispersion solver plus the general Jacobian engine
Open-field-line SOL	open slab flux tube with Bohm sheath targets, two-point steady state, sheath/recycling closure
Neutrals and detachment	hermes-3 AMJUEL atomic rates (packaged), recycling SOL, self-consistent detaching SOL with the SD1D rollover, gradient-based detachment control
3D stellarator workflows	rotating-ellipse and island-divertor geometry, FCI 2-field/4-field/DRB models, closed vs limiter-open turbulence, imported ESSOS coil / VMEC / VMEX geometry
Differentiability	jax.grad through every model — sensitivity, uncertainty, inverse design, detachment control
Parallelism	multi-device shard_map FCI stepping with halo exchange, bit-exact vs single device
Validation	manufactured-solution convergence, geometry and operator campaigns, and publication-ready plots

Claim Boundaries¶

The documentation uses explicit capability labels so examples do not overstate their maturity.

Label	Meaning
native_exact	Native JAX model with exact or roundoff-level agreement on the stated validation target.
native_operational	Native and useful, with bounded documented residuals or reduced fidelity.
self-contained	Runnable from a clean clone after installation.
developer/geometry-input	Regenerates source data from heavier local geometry inputs (e.g. an ESSOS or VMEX checkout).
opt-in research gate	Tested enough for development and evidence collection, but not a stable default claim.

Literature Anchors¶

The model family follows standard edge/SOL reduced-fluid practice: Braginskii collisional closures, drift-reduced ordering, parallel sheath losses, neutral reaction-diffusion sources, and field-line-following geometry operators. Start with Models And Equations and Physics Models for citations, then use Equation To Code Map to inspect the exact source modules and tests.

Topic	Representative links
Collisional transport and reduced Braginskii models	Braginskii 1965, GBS code paper
Flux-coordinate-independent field-line operators	Hariri and Ottaviani 2013, Hariri et al. 2014
SOL detachment (SD1D) and neutral closures	Dudson et al. 2019, Dudson et al. 2024 (hermes-3)
JAX and differentiable scientific computing	JAX documentation
Stellarator geometry and optimization scripting style	SIMSOPT overview, VMEC documentation

Repository And Media Policy¶

The git repository stays lightweight. Source code, examples, documentation, tests, and compressed docs figures/movies (under docs/media/, sized for the rendered docs) are tracked. Heavyweight NPZ payloads and full-resolution legacy campaign media live in GitHub Releases; because this repository is private, release-hosted images do not render inline for readers, so every image embedded in these docs is a committed compressed copy. Release assets can be restored locally with scripts/fetch_example_artifacts.py (authenticate with gh auth login or set GH_TOKEN/GITHUB_TOKEN).