Skip to content

Standalone usage

This page covers running Aragog directly via its standalone Python API. For driving Aragog from inside PROTEUS, see Coupling Aragog to PROTEUS.

When to use the standalone path

The standalone path is the right choice when you want to:

  • Test or develop the solver itself.
  • Reproduce a published Aragog or SPIDER calculation against a fixed boundary condition.
  • Write your own outer driver that loops over masses, compositions, or initial entropies.
  • Run isolated unit-style verifications without the full PROTEUS stack.

If you want a coupled atmosphere-interior simulation, do not use this path; PROTEUS bypasses Aragog's TOML loader entirely. Read Coupling Aragog to PROTEUS instead.

Minimal example

The standalone path drives Aragog directly via the Python API. The user supplies a TOML configuration file and a directory of pressure-entropy EOS tables; the solver returns a SolverOutput dataclass.

from aragog.solver import EntropySolver

solver = EntropySolver.from_file(
    filename='my_config.toml',
    eos_dir='data/lookup',
)
solver.initialize()
solver.set_initial_entropy(2900.0)
solver.solve()
out = solver.get_state()

The full standalone walkthrough is in Tutorials: First run. The TOML schema is in Configuration.

CLI

The standalone CLI exposes the aragog console entry point with seven subcommands:

  • aragog new scaffolds a new TOML config from a bundled template.
  • aragog list-configs enumerates the bundled cfg/abe_*.{toml,cfg} examples.
  • aragog validate parses a config and reports errors without solving.
  • aragog show-config dumps the resolved Parameters tree as JSON.
  • aragog run solves a configured run end-to-end and writes a NetCDF snapshot. Supports --set <key.path>=<value> overrides without editing the TOML.
  • aragog inspect prints key diagnostics from a SolverOutput NetCDF (or --json for jq-style post-processing).
  • aragog vnv runs a verification-figure script from tools/verification/figures/.

For the full subcommand reference and recommended workflows, see Reference: CLI. PROTEUS-coupled runs do not use the CLI; the proteus driver builds Parameters programmatically and calls EntropySolver directly via AragogRunner.

What is shared with the coupled path

The numerical core is identical. Both the standalone and PROTEUS-integrated paths:

  • Use EntropySolver as the integrator wrapper.
  • Read the same SPIDER-format pressure-entropy EOS tables.
  • Return a SolverOutput dataclass with the same fields.
  • Apply the same boundary-condition logic and the same heat-transport switches.

The split is purely at the configuration boundary: in the standalone path, the user writes the TOML; in the PROTEUS-integrated path, the wrapper builds the equivalent Parameters programmatically.

Do not mix the two paths in one run

Setting both an Aragog-side TOML and a PROTEUS-side [interior_energetics.aragog] block in the same simulation is not supported. PROTEUS bypasses the file-based path entirely; the standalone TOML keys are silently ignored when running under PROTEUS.

Cross-references