Feature Reference¶
This page is the high-level map from user goals to examples, inputs, outputs, source code, validation tests, and release-backed media. It is intended to be the first page to read after installation when deciding what DRBX can run today and which scripts or modules to inspect.
Large movies, figures, and NPZ payloads are not tracked in git. They are linked from GitHub Releases and can be restored locally with:
python scripts/fetch_example_artifacts.py
Visual Overview¶
Representative outputs (regenerated by the linked examples):
Capability Map¶
| Capability | User entry point | Main inputs | Main outputs | Implementation | Validation and tests |
|---|---|---|---|---|---|
| TOML runtime and CLI | drbx run, examples/restartable_diffusion_tutorial.py |
TOML deck with [time], [runtime], [mesh], [solver], [model], [species.*], [fields.*], [output], [restart] |
summary JSON, arrays NPZ, restart NPZ, run-log JSON | src/drbx/cli.py, src/drbx/native/deck_runner.py, src/drbx/runtime/output.py |
tests/test_cli_run.py, tests/test_restartable_diffusion_tutorial.py |
| Restartable diffusion and MMS | scripts/run_fluid_1d_mms_convergence.py, Fluid 1D MMS |
analytic manufactured fields, grid levels, diffusion/transport coefficients | convergence JSON/NPZ/PNG, observed-order table | src/drbx/native/fluid_1d.py, src/drbx/validation/fluid_1d_mms_convergence.py |
tests/test_native_fluid_1d.py, tests/test_mms_convergence.py |
| Electrostatic vorticity | drbx run |
compact grid, vorticity initial field, electrostatic potential closure | vorticity and potential history arrays | src/drbx/native/vorticity.py |
tests/test_native_vorticity.py |
| Structured elliptic solver (solvax) | Physics Models, Performance And Differentiability | metric weights, periodic/bounded axes, right-hand side | inverted potential field, differentiable through the solve | solvax.elliptic, src/drbx/native/vorticity.py |
tests/test_native_vorticity.py |
| Differentiability, UQ, and inverse design | examples/autodiff_diffusion_sensitivity.py, examples/autodiff_diffusion_uncertainty.py, examples/autodiff_diffusion_inverse_design.py |
differentiable scalar objectives, covariance, design parameters | sensitivity plots, covariance pushforward plots, optimization traces | src/drbx/validation/autodiff_diffusion.py, src/drbx/validation/autodiff_diffusion_uncertainty.py |
tests/test_validation_autodiff_diffusion.py, tests/test_validation_autodiff_diffusion_uncertainty.py |
| Hasegawa-Wakatani turbulence and inverse design | examples/tokamak/drift_wave_turbulence.py, examples/tokamak/drift_wave_inverse_design.py, Tutorial |
grid size, adiabaticity, gradient drive, hyperviscosity, RK4 step | vorticity GIF, energy/flux histories, sensitivity and recovery JSON | src/drbx/native/hasegawa_wakatani.py |
tests/test_hasegawa_wakatani.py |
| Open SOL flux tube, neutrals, detachment | examples/sol/open_sol_flux_tube.py, examples/sol/recycling_sol.py, examples/benchmarks/b6_detachment_rollover.py, Tutorial |
connection length, source strength, recycling fraction, upstream density/power scans | two-point profiles, detachment-onset and rollover figures, JSON summaries | src/drbx/native/sol_flux_tube.py, src/drbx/native/neutrals/ |
tests/test_open_field_line_sol.py, tests/test_native_recycling_sol.py, tests/test_native_detachment_sol.py |
| Stellarator turbulence, closed vs limiter-open | examples/stellarator/stellarator_turbulence.py, Tutorial |
rotating-ellipse shape, limiter radius, 4-field parameters, phi-solver tolerances | closed/open GIF movies, particle-content and limiter-flux summary | src/drbx/native/fci_4_field_rhs.py, src/drbx/native/stellarator_turbulence.py |
tests/test_stellarator_turbulence.py |
| Linear dispersion and the linearized-DRB engine | examples/benchmarks/linear_dispersion.py, examples/benchmarks/linear_drb_survey.py |
wavenumbers, adiabaticity, Alfven speed, curvature drive | dispersion-vs-analytic figures, regime survey | src/drbx/linear/ |
tests/test_linear_dispersion.py |
| VMEX equilibrium import | examples/geometry-3D/vmex/closed_field_lines.py, examples/geometry-3D/vmex/closed_open_field_lines.py |
wout_*.nc equilibrium, DRBX_VMEX_ROOT checkout |
surface-field maps, traced field lines, iota verification, LCFS overlays | src/drbx/geometry/vmex_import.py |
traced iota vs wout iotaf (~1e-6) inside the examples |
| Synthetic stellarator FCI and reduced SOL | examples/geometry-3D/stellarator-fci/nonlinear_turbulence.py, Stellarator Examples |
analytic non-axisymmetric geometry constants, FCI maps, reduced turbulence settings | geometry plots, linear mode, nonlinear GIF, profile analysis | src/drbx/geometry/stellarator.py, src/drbx/native/fci.py, src/drbx/native/fci_drb_rhs.py, src/drbx/validation/stellarator_sol_showcase.py |
tests/test_geometry_fci_maps.py, tests/test_validation_stellarator_fci_campaigns.py |
| Imported coil, VMEC, and hybrid geometry | ESSOS Imported FCI Validation | imported field-line arrays, VMEC map coordinates, endpoint masks, connection-length reports | FCI/source/refinement reports, Poincare figures, movie QA artifacts | src/drbx/geometry/essos_import.py, src/drbx/validation/essos_imported_fci_campaign.py, src/drbx/validation/essos_imported_drb_movie_campaign.py |
tests/test_essos_fieldline_import.py, tests/test_validation_stellarator_fci_campaigns.py |
| VMEC-extender field-grid import | examples/geometry-3D/vmec-extender/imported_field.py, VMEC Extender Edge Fields |
compact NetCDF field grids with physical phi, cylindrical field components, metadata |
imported-field report, FCI maps, compact SOL smoke package | src/drbx/geometry/vmec_extender_import.py, src/drbx/validation/vmec_extender_edge_field_campaign.py |
tests/test_vmec_extender_import.py, tests/test_validation_vmec_extender_edge_field_campaign.py |
| Performance and scaling | examples/strong_scaling_diffusion.py |
fixed workload, batch size, CPU/GPU selector, profiler output directory | scaling plot, RSS/profile JSON, JAX trace/profile summaries | src/drbx/runtime/performance.py |
tests/test_runtime_performance.py |
| Release and artifact management | Release Packaging | release artifact bundle, GitHub token, optional cache directory | restored docs media, wheel/sdist, footprint audit | scripts/fetch_example_artifacts.py, scripts/audit_repository_footprint.py |
Release Packaging |
Runbook By User Goal¶
| Goal | Commands | Expected artifacts |
|---|---|---|
| Install and run a compact native case | pip install drbx; drbx inspect examples/inputs/restartable_diffusion.toml; drbx run examples/inputs/restartable_diffusion.toml --verbose |
output/.../*_summary.json, *_arrays.npz, *_restart.npz, *_run_log.json |
| Restore figures and movies without bloating git | python scripts/fetch_example_artifacts.py |
docs/data/** PNG/GIF/NPZ media restored from the release bundle |
| Regenerate the public restart tutorial | PYTHONPATH=src python examples/restartable_diffusion_tutorial.py |
density snapshots, density surface, restart-consistency plot, run logs |
| Demonstrate differentiability | run the three examples/autodiff_diffusion_*.py scripts and examples/autodiff/differentiation_methods.py |
sensitivity, uncertainty, inverse-design, and method-cost figures plus JSON/NPZ reports |
| Make a turbulence movie | run examples/tokamak/drift_wave_turbulence.py or examples/stellarator/stellarator_turbulence.py |
vorticity/density GIFs, growth and transport histories |
| Run the SOL/detachment ladder | run examples/sol/open_sol_flux_tube.py, examples/sol/recycling_sol.py, examples/benchmarks/b6_detachment_rollover.py |
two-point profiles, detachment-onset scan, rollover figure |
| Run compact stellarator turbulence | run geometry_plotting.py, linear_mode.py, vorticity_bracket.py, nonlinear_turbulence.py, and turbulent_profile_analysis.py |
geometry maps, nonlinear GIF/poster, radial fluctuation and transport-proxy plots |
| Audit imported coil/VMEC/hybrid geometry | run direct_coil_open_sol.py, vmec_closed_field.py, or hybrid_open_sol.py in dry-run mode |
machine-readable workflow summaries and promotion-boundary ledgers |
| Run validation campaigns for docs/paper figures | run selected scripts under examples/benchmarks/ and examples/geometry-3D/ |
JSON/NPZ/PNG validation packages used by the documentation gallery |
| Run release checks | python scripts/run_fast_research_checks.py; pytest -q -m "not slow"; mkdocs build --strict --clean |
local pass/fail evidence for docs, tests, and build surfaces |
Input Surfaces¶
DRBX has three public input styles:
| Input style | Used by | Details |
|---|---|---|
| TOML decks | drbx run, run_input_case |
See Input And Output Reference for [time], [runtime], [mesh], [model], [species.*], [fields.*], [output], and [restart]. |
| Python example constants | most scripts in examples/ |
Scripts follow the SIMSOPT-style pattern: edit constants near the top, run the file, inspect the output directory. |
| Release-backed artifacts | movies, galleries, cached example media | Restored by scripts/fetch_example_artifacts.py; avoids large tracked media and keeps clone size small. |
Output Surfaces¶
| Output | Format | Purpose |
|---|---|---|
| Summary report | JSON | scalar metadata, capability tier, runtime configuration, variable summaries |
| Arrays | NPZ | field histories and derived arrays for plotting and analysis |
| Restart payload | NPZ | resume native runs without starting from the initial condition |
| Run log | JSON | ordered runtime events, progress, timing, sanitized paths, artifact provenance |
| Validation package | JSON/NPZ/PNG/GIF | publication-grade figures and machine-readable metrics |
| Movie package | GIF/PNG/NPZ/JSON | dynamics movie, poster, snapshots, diagnostics, visual-QA metadata |
| Release artifact bundle | ZIP | large generated media stored outside git history |
Source-Code Reading Path¶
For users who want to understand or modify the implementation, read in this order:
- Native runtime CLI and
src/drbx/cli.py. - Input And Output Reference and
src/drbx/runtime/output.py. - Physics Models and Equation To Code Map.
- Code Structure, especially the FCI and geometry sections.
- Validation Gallery.
- Performance And Differentiability before changing solver backends or claiming speedups.
Claim Boundaries¶
The docs use conservative labels because the code mixes stable release surfaces with active research lanes:
| Label | Meaning |
|---|---|
native_exact |
native JAX model with exact or roundoff-level agreement on its validation target |
native_operational |
native and useful, with bounded documented residuals |
self-contained |
clean-clone runnable after installing DRBX and, when needed, restoring release artifacts |
developer/geometry-input |
regenerates source data from heavier local geometry inputs |
opt-in research gate |
tested enough for development and evidence collection, but not a stable default claim |
When a page advertises a movie or figure, the corresponding example command, artifact path, source module, and validation status should be traceable through this page, Examples And Artifact Map, or Validation Gallery.