Command-line interface

The aragog console script (registered under [project.scripts] in pyproject.toml) is the standalone entry point. It is a thin wrapper over the Python API: anything the CLI does is also reachable via from aragog.solver import EntropySolver. PROTEUS-coupled runs do not use the CLI; the proteus driver builds Parameters programmatically and calls EntropySolver directly via AragogRunner.

Group flags

aragog --version    # bare aragog version, e.g. 'aragog 26.05.10'
aragog --versions   # multi-line block: aragog + numpy / scipy / jax / scikits.odes / netCDF4

The --versions block is the recommended attachment for any bug report.

Subcommands

Subcommand	Purpose
`aragog new`	Scaffold a new config from a bundled template, in the template's format (TOML or INI).
`aragog list-configs`	Enumerate the bundled `cfg/abe_*.{toml,cfg}` examples.
`aragog validate`	Parse a config and report errors without solving.
`aragog show-config`	Dump the resolved `Parameters` tree as JSON.
`aragog run`	Solve a configured run in full and write a NetCDF snapshot.
`aragog inspect`	Print key diagnostics from a `SolverOutput` NetCDF.
`aragog vnv`	Run a verification-figure script under `tools/verification/figures/`.

Each subcommand is described below.

`aragog new`

aragog new <name> [--from <template>] [--force]

Copies a bundled cfg/abe_*.{toml,cfg} template to the cwd as <name>.toml or <name>.cfg, keeping the template's format. A relative eos_file or init_file in the template that names an existing file is written as an absolute path, so the copy runs from any directory. The bundled data files live in the repository's data/ directory, which is not installed as package data, so this works from a source checkout only. Default template is abe_solid (the canonical solid-phase cooling smoke); use --from abe_mixed (or any other name from aragog list-configs) to pick a different starting point. A <name> ending in .toml or .cfg selects that form of the template; without a suffix, the template's own suffix is appended (.toml when both forms exist). Refuses to overwrite an existing destination unless --force is passed.

aragog new earth_smoke              # writes ./earth_smoke.toml from abe_solid
aragog new earth_mixed --from abe_mixed

`aragog list-configs`

aragog list-configs

Prints each bundled template in src/aragog/cfg/ together with its first-comment-line summary. Reads via importlib.resources, so it works in both editable and wheel installs.

`aragog validate`

aragog validate <config>

Loads the configuration through Parameters.from_file, runs Parameters.__post_init__ (BC normalise, optional EOS file load, ppm-to-mass-fraction conversion for radionuclides), and reports the first parser error. The EOS tables and the solver are not touched. Use this before launching a long CHILI run to catch typos, missing files, IBC=99-style dispatch errors, and the [scalings] strict-rejection.

On success, prints a one-line summary:

OK earth_smoke.toml: core_bc=energy_balance, IBC=2, OBC=1, eos_method=1, IC_method=1, radionuclides=4

On failure, raises a ClickException with configuration error in <path>: <message> and a non-zero exit code.

`aragog show-config`

aragog show-config <config> [--indent N]

Dumps the resolved Parameters dataclass tree (post-__post_init__) as JSON on stdout. Use for diff'ing PROTEUS-extracted configs against hand-crafted ones, for machine-readable extraction with jq, or for archival snapshots of the resolved schema.

aragog show-config earth_smoke.toml | jq .energy.kappah_floor
aragog show-config earth_smoke.toml --indent 0 > resolved.json   # one-line, jq-friendly

The walker uses dataclasses.asdict plus a numpy-array-to-list pass, so energy.tidal_array and any optional mesh.eos_* profile arrays serialise cleanly.

`aragog run`

aragog run <config.toml> --eos-dir <path> [--initial-entropy <S0>] [options]

Solves a configured run in full and writes a NetCDF snapshot. Solver status 0 (success) and 1 (stop at a step-cap event, or, with the floor on (energy.eos_floor_margin > 0), a call that the EOS floor does not let advance; see Solver method tuning) are successful runs, any other status is a failure (SolverOutput.failed). If the integration fails, the command writes the state at the last successful output time (the initial state if the solver fails before the first output) and exits with status 1. A run stopped early by a per-call step cap (energy.phi_step_cap, energy.temperature_step_cap or energy.entropy_step_cap) exits 0, with the snapshot at the stop time. Mirrors the Python recipe in Tutorials: First run: load Parameters, initialise the solver, set the initial-condition state vector, solve, and call SolverOutput.to_netcdf.

--initial-entropy is optional when the config's [initial_condition] block sets surface_temperature > 0 and initial_condition is 1 (linear) or 3 (adiabatic); the CLI then derives $S_0$ by inverting $T(P_\mathrm{surf}, S) = $ surface_temperature against the loaded EOS. The bundled cfg/abe_*.{toml,cfg} configs all set surface_temperature, so they run without the flag. Pass --initial-entropy explicitly to override the derivation.

Options

Option	Type	Description
`--eos-dir PATH`	directory	SPIDER-format P-S EOS tables. Defaults to `$FWL_DATA/spider/lookup-fs` if the env var is set.
`--initial-entropy FLOAT`	J/kg/K	Initial isentropic profile. Optional when the `[initial_condition]` block sets `surface_temperature > 0` and `initial_condition` is 1 (linear) or 3 (adiabatic): the CLI then derives $S_0$ from `T(P_\mathrm{surf}, S) = $`surface_temperature`. Required in all other cases.
`--initial-dsdr-cmb FLOAT`	J/kg/K/m	Initial CMB entropy gradient. Sets the CMB flux when `core_bc` is `"energy_balance"`; `"core_module"` carries the slot without effect (its flux is the boundary-layer law); the other modes ignore it. Default 0.
`--out PATH`	file	NetCDF output path. Defaults to `<config-stem>.nc` in the cwd.
`--log-dir PATH`	directory	Directory for `aragog.log`. Defaults to the cwd.
`--log-level {debug,info,warning,error}`	level	Console log level. Default `info`.
`--set KEY.PATH=VALUE`	repeatable	Override a config field. See below.

`--set` overrides

Repeatable flag that overrides any field in the resolved configuration tree without editing the TOML on disk. Type-coercion order: int → float → bool ('true'/'false') → JSON ([...], {...}, "...") → bare string.

# Tighten tolerances and bump kappah_floor for one run.
aragog run earth_smoke.toml \
    --eos-dir $FWL_DATA/spider/lookup-fs \
    --initial-entropy 2900.0 \
    --set energy.kappah_floor=20.0 \
    --set solver.atol=1e-11

# Drive a tidal-heating array via JSON.
aragog run earth_smoke.toml \
    --eos-dir $FWL_DATA/spider/lookup-fs \
    --initial-entropy 2900.0 \
    --set 'energy.tidal_array=[1e-9, 2e-9, 3e-9]'

Constraints:

--set requires a .toml config (uses tomllib); legacy .cfg INI is rejected with a clear error.
A relative mesh.eos_file or initial_condition.init_file value given with --set resolves against the working directory; the same keys inside the config file resolve against the config file's directory first.
Unknown intermediate sections (e.g. --set atmos.X=...) raise immediately, before any solver construction.
Unknown leaf keys (e.g. --set energy.kapaha_floor=... with the typo) surface as UsageError: after applying --set overrides, the resolved config has unknown / mismatched fields: ....

`aragog inspect`

aragog inspect <file.nc> [--json]

Reads a NetCDF snapshot produced by SolverOutput.to_netcdf (or by aragog run --out) and prints key diagnostics.

Default output is human-readable: scalar lines aligned in two columns with units in the label, scientific notation for very large / small values, plus a S_final / T_basic profile-range block (min / max / finite-count).

snapshot: out.nc
  aragog: 26.05.10
  created: 2026-05-09T00:00:00+00:00
  description: Aragog run from earth_smoke.toml
  cvode_flag_name: SUCCESS
  dimensions: staggered=120, basic=121

  status                               0  solver status (0 success, 1 step-cap stop, other failure)
  cvode_flag                           0  raw CVODE return flag (0 = success, -1 = too much work)
  time                        1.0000e+06  simulation time [yr]
  dt_actual                   1.0000e+06  integration interval [yr]
  T_magma                      3500.0000  surface (magma) temperature [K]
  T_core                       4200.0000  CMB temperature [K]
  tcore_change_max              125.0000  largest per-solve CMB-temperature change [K]
  tcore_change_exceeded                0  CMB-temperature change over limit or non-finite (0/1)
  Phi_global                      0.4200  mass-weighted melt fraction [-]
  E_state                     4.5000e+30  EOS-consistent enthalpy [J]
  E_state_cons                4.4900e+30  frozen-mass enthalpy [J]
  ...

  S_final: min=2.9000e+03, max=3.0000e+03 (120/120 finite)
  T_basic: min=1.5000e+03, max=4.5000e+03 (121/121 finite)

The CVODE diagnostics come from the last integrator return: cvode_flag is the raw SUNDIALS return code (status stays the aragog-level solver status), and cvode_flag_name is the matching symbolic name printed in the header block. The tcore_change_max / tcore_change_exceeded pair reports the largest core-mantle-boundary temperature change measured within the final solve and whether it crossed the configured solver.tcore_change_limit; tcore_change_exceeded is also set when any sampled core temperature in that solve is non-finite, independent of whether a limit is set. cvode_flag and tcore_change_exceeded print as plain integers; the excursion magnitude follows the normal float formatting. Every fresh snapshot carries all four fields: on the default radau path CVODE never runs, so cvode_flag is 0 and cvode_flag_name reads N/A. Only an older snapshot that predates these fields omits them, and inspect then drops the cvode_flag_name header line and skips the absent scalars.

--json emits the same payload as a single JSON document keyed {path, dimensions, attrs, scalars, profiles}, suitable for jq post-processing or CI assertions. cvode_flag, tcore_change_max and tcore_change_exceeded appear under .scalars; cvode_flag_name is a global attribute and appears under .attrs.

aragog inspect out.nc --json | jq .scalars.T_magma

The command is robust to all-NaN profiles (e.g. E_state on the const_properties path) and to older snapshots missing some scalars; absent fields are silently skipped.

`aragog vnv`

aragog vnv [<topic>] [--list]

Runs a verification-figure script under tools/verification/figures/verify_<topic>.py. Bare invocation or --list enumerates the available scripts (radio_decay, permeability, rhs_parity, eos_bilinear_jacobian, flux_decomposition, mass_coord_jacobian, utbl_cardano).

aragog vnv --list
aragog vnv radio_decay

The V&V scripts are not packaged inside the aragog distribution; they live under the source tree and require a checkout. A non-editable pip install aragog install will print a clear "no V&V scripts found" error. A script main() that raises is wrapped in a ClickException so the CLI exits non-zero with a clean message rather than a raw traceback.

Recommended workflows

First run (CLI-only)

aragog new my_first --from abe_solid
aragog validate my_first.toml
aragog run my_first.toml --eos-dir $FWL_DATA/spider/lookup-fs
aragog inspect my_first.nc

The scaffolded abe_solid.toml carries [initial_condition].surface_temperature = 3600, so the CLI derives the initial entropy from the EOS. Add --initial-entropy <S0> to override.

Debugging a stuck PROTEUS-coupled run

# Extract the resolved config that PROTEUS built, save it to disk, then validate.
aragog show-config saved_from_proteus.toml > resolved.json
aragog validate saved_from_proteus.toml

# Try a single override to test a hypothesis without editing the TOML.
aragog run saved_from_proteus.toml \
    --eos-dir <eos> --initial-entropy <S0> \
    --set solver.atol=1e-11 \
    --out probe.nc
aragog inspect probe.nc

Diff'ing two configs

aragog show-config a.toml --indent 2 > a.json
aragog show-config b.toml --indent 2 > b.json
diff a.json b.json

Command-line interface

Group flags

Subcommands

aragog new

aragog list-configs

aragog validate

aragog show-config

aragog run