Usage

Aragog is primarily used as a Python library, either directly via EntropySolver or, in coupled simulations, through the PROTEUS framework wrapper. The standalone command-line interface is minimal and intentional: production runs go through the Python API.

Running Aragog from Python

The minimal workflow is load configuration → instantiate solver → set initial entropy → solve → read SolverOutput.

from pathlib import Path
from aragog.solver import EntropySolver

# Build a solver from a TOML configuration file and a directory
# of SPIDER-format pressure-entropy EOS tables.
solver = EntropySolver.from_file(
    filename="src/aragog/cfg/abe_solid.toml",
    eos_dir="data/lookup",
)

solver.initialize()

# When core_bc = "energy_balance", the CMB entropy gradient is part
# of the state vector. If you need to set its initial value explicitly,
# do it BEFORE set_initial_entropy; otherwise the solver derives it
# from S_init via one-sided finite differences.
# solver.set_initial_dSdr_cmb(0.0)

# Set the initial entropy profile at staggered nodes (J/kg/K).
# A scalar S_init produces a uniform isentropic profile.
solver.set_initial_entropy(2900.0)

solver.solve()

# Retrieve a SolverOutput dataclass with profiles, fluxes, and
# scalar diagnostics.
out = solver.get_state()
print(f"Status:           {out.status}")           # 0 success, -1 failure
print(f"T_magma:          {out.T_magma:.0f} K")    # surface temperature
print(f"T_core:           {out.T_core:.0f} K")
print(f"Phi_global:       {out.Phi_global:.4f}")
print(f"F_heat_total:     {out.F_heat_total:.3e} W/m^2")

EntropySolver.from_file is a convenience constructor; in PROTEUS, the wrapper builds Parameters and EntropyEOS programmatically and passes them to the constructor directly.

What SolverOutput contains

get_state() returns a SolverOutput dataclass. The fields are flat NumPy arrays except where noted:

Profiles (staggered nodes, length \(N\)):

Mesh geometry:

Per-component fluxes (basic nodes, length \(N+1\)):

Scalar diagnostics:

Driving Aragog from PROTEUS

When Aragog is invoked as a PROTEUS submodule, the wrapper (proteus.interior_energetics.aragog.AragogRunner) constructs Parameters from the PROTEUS config object and the current helpfile row, instantiates EntropySolver directly, sets the initial entropy from the previous step (or from a Zalmoxis-derived profile on the first iteration), runs solve(), and reads the results from get_state().

PROTEUS handles:

• The mapping of PROTEUS config keys (config.interior_energetics.*, config.interior_struct.*) onto Aragog's Parameters.
• The choice of EOS table directory (output/data/aragog_pt/ for PALEOS-generated tables, or a SPIDER-bundled directory for parity runs).
• The four-column external mesh file (output/data/zalmoxis_output.dat for Zalmoxis-coupled runs, output/data/spider_mesh.dat for spider or dummy structure modes) when eos_method = 2.
• A retry ladder around solve() that calls set_initial_dSdr_cmb() and _atol_sf to recover after a status = -1 failure.

For an end-to-end coupled run, see the PROTEUS documentation.

Resetting and re-running the solver

To run multiple configurations or restart from a saved entropy profile, call reset() and then set_initial_entropy() again:

solver.reset()                 # rebuilds the mesh and BCs from current parameters
# Optional in energy_balance mode (must be called BEFORE set_initial_entropy):
# solver.set_initial_dSdr_cmb(dSdr_cmb_new)
solver.set_initial_entropy(S_new)
solver.solve()
out = solver.get_state()

reset() does not change the parameters; mutate solver.parameters first if a different time window or boundary value is needed.

NetCDF output

Standalone Aragog writes a NetCDF snapshot via SolverOutput.to_netcdf(path) (also exposed as EntropySolver.write_netcdf(path) and as aragog run --out path.nc on the CLI). The PROTEUS wrapper builds its own per-iteration int.nc snapshot from SolverOutput arrays for the PROTEUS analysis pipeline; that path is independent. See Inspecting NetCDF output for the snapshot schema.

Logging

aragog.aragog_file_logger(log_dir=output_dir) configures a console+file logger that writes aragog.log into the supplied directory. The logger is shared between the solver and the EOS layer; the standalone path uses it implicitly.

Command-line interface

Aragog exposes the aragog console entry point with seven subcommands: new, list-configs, validate, show-config, run, inspect, and vnv. The CLI is a thin wrapper over the Python API — anything it does is also reachable from from aragog.solver import EntropySolver — but it covers the recommended standalone-user loop without writing Python:

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

aragog run derives the initial entropy from [initial_condition].surface_temperature when the bundled config provides it (the abe_* templates do); pass --initial-entropy <S0> to override. Repeatable --set <key.path>=<value> flags accept one-shot overrides without editing the TOML. The full subcommand reference, including the --set type-coercion rules, is in Reference: CLI. PROTEUS-coupled runs bypass the CLI and call EntropySolver directly via AragogRunner.