Input And Output Reference

This page is the practical reference for every public input and output surface. Use it after the Feature Reference when you know which workflow you want to run and need the exact files, command-line switches, Python entry points, and artifacts.

Input Families

Input family Used by What to edit
TOML native decks drbx run, drbx inspect Time, runtime precision, mesh, solver settings, model components, species, fields, output, restart
Python example constants scripts under examples/ Constants near the top of the file: grid sizes, timestep, output directory, model flags, plotting toggles
Release-backed artifacts movies, docs galleries, cached user examples Restored by scripts/fetch_example_artifacts.py; do not edit by hand
Developer geometry roots heavy external-geometry regeneration Geometry-specific environment variables
Imported geometry payloads ESSOS/VMEC/VMEC-extender workflows Field-line arrays, VMEC-coordinate maps, compact NetCDF edge-field grids, metadata JSON

Most user examples are self-contained after artifact restoration and do not require external plasma-code installations. Developer geometry-regeneration commands are documented separately and require explicit local inputs.

TOML Decks

The native runtime reads TOML decks. A minimal promoted deck is committed at examples/inputs/restartable_diffusion.toml.

Common top-level sections:

Section Keys and meaning
[time] nout output intervals, timestep physical or normalized interval length
[runtime] precision (float32 or float64) and backend-sensitive runtime options
[runtime.logging] verbosity, verbose, quiet; controls terminal progress and log detail
[mesh] nx, ny, nz, dx, dy, dz, J, metric-like factors or expression-valued spacing
[solver] native solver selectors, step limits, and opt-in research backend switches
[model] active component list and model-family selectors
[species.<name>] species type/equations, charge, mass number, transport coefficients, closure toggles
[fields.<name>] initial field formula or reference, boundary conditions, guard behavior
[output] output directory and write toggles for summary, arrays, restart, and run log
[restart] optional restart input and resume length

Minimal example:

[time]
nout = 3
timestep = 5.0

[runtime]
precision = "float64"

[runtime.logging]
verbosity = "detailed"
verbose = true
quiet = false

[mesh]
nx = 16
ny = 24
nz = 1
dx = { expr = "0.0075 + 0.005*x" }
dy = 0.01
dz = 0.01
J = 1

[solver]
mxstep = 1000

[model]
components = ["h"]

[species.h]
type = ["evolve_density", "evolve_pressure", "anomalous_diffusion"]
AA = 1
charge = 1
anomalous_D = 2.0
thermal_conduction = false

[fields.Nh]
function = { expr = "1 + H(x - 0.25) * H(0.75-x) * exp(-(y-pi)^2)" }
bndry_all = "neumann"

[fields.Ph]
function = { ref = "Nh:function" }
bndry_all = "neumann"

[output]
directory = "output/restartable_diffusion"
write_summary = true
write_arrays = true
write_restart = true
write_log = true

Expressions And References

Expression-valued inputs use { expr = "..." }. Current examples use coordinate names such as x, y, and z, constants such as pi, elementary functions such as exp, and helper functions such as H(...) for a Heaviside-style switch.

Reference-valued fields use { ref = "OtherField:function" } when one field should reuse another field definition.

Boundary Conditions

The public TOML examples use field-level boundary keys such as:

[fields.Nh]
bndry_all = "neumann"

Higher-fidelity recycling, sheath, neutral, and target behavior is usually staged by curated campaigns or Python examples, because those paths need species coupling, target masks, guard-cell sequencing, and source accounting. Their capability tier is written to the run summary and validation report.

CLI Commands

The executable is drbx. Running a TOML path directly is equivalent to drbx run.

Command Purpose Typical inputs Typical outputs
drbx run input.toml Run a native input deck TOML deck, optional restart summary JSON, arrays NPZ, restart NPZ, run log
drbx inspect input.toml Parse and print the resolved plan without advancing TOML deck terminal plan summary

Common commands:

drbx inspect examples/inputs/restartable_diffusion.toml
drbx run examples/inputs/restartable_diffusion.toml --verbose
drbx run examples/inputs/restartable_diffusion.toml \
  --output-dir output/resumed_case \
  --restart-in output/base_case/base_restart.npz \
  --resume-steps 2

Python Entry Points

Use the CLI for ordinary runs. Use the Python API when embedding DRBX in analysis scripts or examples.

from drbx.native import run_input_case

result = run_input_case(
    "examples/inputs/restartable_diffusion.toml",
    case_name="diffusion_driver",
    parity_mode="run",
    verbose=True,
)

print(result.time_points[-1])
print(sorted(result.variables))

Common Python entry points:

API Source Purpose
run_input_case src/drbx/native/deck_runner.py Run a TOML deck and return structured native output
load_run_config src/drbx/runtime/run_config.py Parse runtime configuration
write_run_outputs and output helpers src/drbx/runtime/output.py Write summary, arrays, restart, and run-log artifacts
compute_fci_drb_rhs src/drbx/native/fci_drb_rhs.py Evaluate compact 3D FCI DRB RHS terms
build_*_campaign functions src/drbx/validation Generate validation reports, figures, and publication artifacts

Output Artifacts

When [output] enables every public artifact, the runtime writes:

Artifact Format Contents Typical use
<case>_summary.json JSON scalar metadata, capability tier, runtime configuration, variable summaries, output manifest quick inspection, docs tables, CI checks
<case>_arrays.npz NPZ field arrays and time histories plotting and analysis scripts
<case>_restart.npz NPZ restart payload with fields and metadata resume native runs
<case>_run_log.json JSON ordered runtime events, progress messages, artifact paths, sanitized runtime metadata long-run monitoring and reproducibility
validation report JSON campaign settings, metrics, thresholds, capability tier, literature/reference notes docs and paper figures
validation arrays NPZ campaign arrays used to make plots regeneration and review
validation figures PNG/GIF publication-style plots and movies docs, README, manuscript

The run log is designed for long calculations. It records the ordered event stream, artifact paths, and sanitized runtime metadata for each run.

Where Outputs Go

Most examples write to either output/<case>/ or docs/data/<case>_artifacts/. The first location is for user runs. The second location is used by examples that regenerate documentation figures. Large files in docs/data/ are either ignored by git or restored from the release artifact manifest.

Use these conventions:

Situation Recommended output directory
Trying a tutorial locally output/<case_name>/
Regenerating a documented example figure the script default under docs/data/<case>_artifacts/
Running heavy profiling tmp/profiles/<profile_name>/
Running a heavy geometry-regeneration campaign explicit scratch directory outside the repo or under ignored tmp/

Artifact Restore And No-Bloat Policy

The repository tracks source code, documentation, small fixtures, and small machine-readable reports. Large media are release-hosted.

Restore user-facing media:

python scripts/fetch_example_artifacts.py

Use a shared cache:

export DRBX_ARTIFACT_CACHE_DIR=/path/to/cache
python scripts/fetch_example_artifacts.py

For private-repository users, authenticate with gh auth login --hostname github.com or set GH_TOKEN/GITHUB_TOKEN.

Capability Tiers In Outputs

Every promoted or curated result should be interpreted through its tier:

Tier Meaning
native_exact Strong enough for the main native benchmark surface.
native_operational Native and useful, but still carrying bounded residuals or reduced fidelity.

The tier is written to summaries, run logs, and validation artifacts so docs figures and paper figures do not overstate the solver claim.

For implementation details, use:

Topic Source
CLI parsing and command dispatch src/drbx/cli.py
Runtime state and output writing src/drbx/runtime
Native run orchestration src/drbx/native/deck_runner.py
3D FCI geometry and RHS terms src/drbx/native/fci.py, src/drbx/native/fci_drb_rhs.py
Validation campaigns and plotting src/drbx/validation