Worked Examples

This page collects a few representative NEOPAX workflows using the example input files already shipped in the repository. The goal is not to document every option in each file, but to show the normal ways users interact with the code: transport evolution, ambipolar root finding, flux evaluation, and source evaluation.

Transport Example

Example input files:

  • examples/Solve_Transport_Equations/Solve_Transport_equations_noHe_theta.toml

  • examples/Solve_Transport_Equations/Solve_Transport_equations_noHe_radau.toml

  • examples/Solve_Transport_Equations/Solve_Transport_equations_noHe_diffrax_kvaerno.toml

These examples evolve 1D transport equations for the active profile state using different time-integration backends.

CLI usage:

NEOPAX examples/Solve_Transport_Equations/Solve_Transport_equations_noHe_theta.toml

Module usage:

python -m NEOPAX examples/Solve_Transport_Equations/Solve_Transport_equations_noHe_radau.toml

Direct Python API:

import NEOPAX

result = NEOPAX.run(
    "examples/Solve_Transport_Equations/Solve_Transport_equations_noHe_radau.toml",
    backend="radau",
)

final_state = result.final_state
time_grid = result.time_grid

Useful overrides during development:

  • --backend theta_newton

  • --dt 1e-4

  • --t-final 5.0

  • --output-dir ./outputs/my_transport_run

  • --set turbulence.debug_heat_flux_scale=0.5

Lagged-Response Benchmark Example

To compare the shared transport rhs_mode values on the expensive NTX paths, use:

  • examples/benchmarks/benchmark_transport_rhs_modes.py

This script:

  • defaults to flux_model = "ntx_exact_lij_runtime"

  • can also benchmark ntx_database or keep the flux model already present in the base TOML

  • disables plots/HDF5 output to reduce benchmark noise

  • compares black_box against lagged_response by default

  • works with radau, theta, or theta_newton

Example:

python examples/benchmarks/benchmark_transport_rhs_modes.py --backend radau

or:

python examples/benchmarks/benchmark_transport_rhs_modes.py --backend theta_newton

To benchmark the NTX energy-convolution database route instead of the exact runtime Lij path:

python examples/benchmarks/benchmark_transport_rhs_modes.py --flux-model ntx_database

The script defaults to the no-helium Radau transport example as its base input file, but can rewire the neoclassical model internally so it benchmarks either the runtime NTX exact-Lij path or the file-backed NTX database route.

Ambipolarity Example

Example input file:

  • examples/Solve_Ambipolarity/ambiplarity_benchmark.toml

This mode scans radial electric field values and identifies ambipolar roots, including the entropy-based root selection logic when multiple roots are present.

CLI usage:

NEOPAX examples/Solve_Ambipolarity/ambiplarity_benchmark.toml

Direct Python API:

import NEOPAX

result = NEOPAX.run("examples/Solve_Ambipolarity/ambiplarity_benchmark.toml")

roots = result.raw_result.get("roots_3")
best_root = result.raw_result.get("best_root")

Typical reasons to use this mode:

  • inspect ambipolar root structure before transport evolution

  • initialize E_r from an ambipolar branch

  • benchmark root-finding settings and neoclassical databases

Fluxes Example

Example input file:

  • examples/examples/Calculate_Fluxes/calculate_flux_w7x.toml

This mode evaluates the currently configured flux model on the input state and optionally writes plots and HDF5 output.

CLI usage:

NEOPAX examples/examples/Calculate_Fluxes/calculate_flux_w7x.toml

CLI usage with an override:

NEOPAX examples/examples/Calculate_Fluxes/calculate_flux_w7x.toml --set fluxes.fluxes_write_hdf5=true

Direct Python API:

import NEOPAX

result = NEOPAX.run("examples/examples/Calculate_Fluxes/calculate_flux_w7x.toml")
fluxes = result.raw_result

This mode is especially useful for:

  • validating neoclassical, turbulent, or classical flux models in isolation

  • comparing file-driven fluxes against database-driven models

  • generating reference flux profiles for debugging transport runs

Sources Example

The sources mode evaluates configured source models without running the full transport solve. If you already have a normal transport input file, the simplest way to explore sources-only behavior is to override the mode at runtime.

CLI usage:

NEOPAX examples/Solve_Transport_Equations/Solve_Transport_equations_noHe_theta.toml --mode sources

Direct Python API:

import NEOPAX

result = NEOPAX.run(
    "examples/Solve_Transport_Equations/Solve_Transport_equations_noHe_theta.toml",
    mode="sources",
)

sources = result.raw_result

This is useful for:

  • checking source magnitudes and signs before transport runs

  • isolating heating, radiation, and exchange terms

  • validating source parameter changes independently from transport stiffness

Runtime NTX Direct-API Example

For the ntx_scan_runtime neoclassical model, a useful direct-Python pattern is to preload the static VMEC/Boozer-derived channel data once and then build the runtime scan model around it.

Example file:

  • examples/custom_models/ntx_runtime_scan_direct_api_example.py

This example is useful when:

  • Python, rather than a pure TOML workflow, is controlling repeated model setup

  • you want a cleaner split between static geometry-derived data and scan inputs

  • you want to keep the direct-API path friendlier for future autodiff-oriented work

Choosing A Usage Path

For the same example file, NEOPAX supports three complementary ways of running:

  • Console script: fastest for command-line use and batch scripts

  • python -m NEOPAX: useful when you want the module path explicitly

  • Direct API: best for notebooks, programmatic workflows, parameter scans, and future autodiff-oriented use

In practice:

  • use the CLI when the TOML file is the main source of truth

  • use NEOPAX.run(...) when Python should remain in control of the workflow

  • use NEOPAX.prepare_config(...) plus NEOPAX.run_config(...) when you want an explicit configuration object before execution

See Also