`aragog.config`

The aragog.config package provides the modern attrs-based configuration classes and the Config facade used by the PROTEUS wrapper. Each subclass corresponds to one TOML section; the facade composes them into a legacy Parameters object that the solver consumes internally.

Name	Role
`Config`	Top-level facade. Static constructors `from_toml(path)`, `from_dict(data)`, and `from_file(*paths)` return a legacy `Parameters` ready for `EntropySolver`.
`BoundaryConfig`	Surface and core boundary settings: `outer_boundary_condition`, `inner_boundary_condition`, emissivity, `core_bc` mode (`quasi_steady` default, `energy_balance`, `gradient`, `bower2018`), UTBL toggle.
`EnergyConfig`	Physics toggles (conduction, convection, gravitational separation, mixing, radionuclides, tidal), eddy-diffusivity ratio, tidal-array buffer.
`InitialConditionConfig`	IC type (linear, user-defined, adiabatic), surface and basal temperatures, init-file path.
`MeshConfig`	Mesh geometry, EOS method (Adams-Williamson or user-defined), surface density, gravity, bulk modulus, mass-coordinate flag, surface pressure.
`MixedPhaseConfig`	Mushy-zone parameters: latent heat, rheological transition, smoothing widths, solidus/liquidus paths, `cp_blend` strategy.
`PhaseConfig`	Single-phase (solid or liquid) properties: density, heat capacity, conductivity, expansivity, viscosity, optional entropy lookup. Each property accepts a float or a path-string lookup.
`RadionuclideConfig`	One radioisotope: name, reference time, abundance, concentration, heat production, half-life. Provides `get_heating(time)` (W/kg).
`SolverConfig`	ODE driver settings: `start_time`, `end_time`, `atol`, `rtol`, surface-T step cap.

For the TOML field syntax expected on disk, see How-to: configuration. The facade returns a Parameters dataclass tree from the legacy aragog.parser module; that is the object EntropySolver actually consumes internally. The attrs Config classes documented here are the public construction surface.

Facade

`Config`

Top-level Aragog configuration.

Facade that constructs a Parameters object from attrs-based sub-configs or from TOML/dict input. Solver consumes the Parameters instance directly.

Parameters:

Name	Type	Description	Default
`solver`	`dict`	ODE solver parameters.	required
`boundary_conditions`	`dict`	Boundary condition parameters.	required
`mesh`	`dict`	Mesh parameters.	required
`energy`	`dict`	Energy source toggles.	required
`initial_condition`	`dict`	Initial condition parameters.	required
`phase_liquid`	`dict`	Liquid phase properties.	required
`phase_solid`	`dict`	Solid phase properties.	required
`phase_mixed`	`dict`	Mixed phase parameters.	required
`radionuclide_`		Radionuclide sections (any key starting with 'radionuclide_').	required

`from_dict(data)` `staticmethod`

Construct a Parameters object from a nested dictionary.

This is the primary construction path used by the PROTEUS wrapper.

Parameters:

Name	Type	Description	Default
`data`	`dict`	Nested dictionary with section names as keys.	required

Returns:

Type	Description
`Parameters`	Legacy Parameters object, ready for Solver.

Source code in src/aragog/config/__init__.py

@staticmethod
def from_dict(data: dict[str, Any]) -> 'Parameters':
    """Construct a Parameters object from a nested dictionary.

    This is the primary construction path used by the PROTEUS wrapper.

    Parameters
    ----------
    data : dict
        Nested dictionary with section names as keys.

    Returns
    -------
    Parameters
        Legacy Parameters object, ready for Solver.
    """
    from aragog.parser import (
        Parameters,
        _BoundaryConditionsParameters,
        _EnergyParameters,
        _InitialConditionParameters,
        _MeshParameters,
        _PhaseMixedParameters,
        _PhaseParameters,
        _Radionuclide,
        _SolverParameters,
    )

    # Case-insensitive scalings reject: keep parity with
    # parser.from_file, which lowercases the section name before
    # comparison. Keys differ in case if the dict was built from a
    # TOML by a parser that preserves case.
    if any(str(k).lower() == 'scalings' for k in data):
        raise ValueError(
            "Configuration contains a 'scalings' section, which is no "
            'longer accepted. Aragog applies its internal '
            'nondimensionalisation around the integrator only; remove '
            "the 'scalings' block from the input dict / TOML."
        )

    solver = _SolverParameters(**data['solver'])
    boundary_conditions = _BoundaryConditionsParameters(**data['boundary_conditions'])
    mesh = _MeshParameters(**data['mesh'])
    energy = _EnergyParameters(**data['energy'])
    initial_condition = _InitialConditionParameters(**data.get('initial_condition', {}))
    phase_liquid = _PhaseParameters(**data['phase_liquid'])
    phase_solid = _PhaseParameters(**data['phase_solid'])
    phase_mixed = _PhaseMixedParameters(**data['phase_mixed'])

    radionuclides: list[_Radionuclide] = []
    for key, val in data.items():
        if key.startswith('radionuclide_'):
            radionuclides.append(_Radionuclide(**val))

    return Parameters(
        boundary_conditions=boundary_conditions,
        energy=energy,
        initial_condition=initial_condition,
        mesh=mesh,
        phase_solid=phase_solid,
        phase_liquid=phase_liquid,
        phase_mixed=phase_mixed,
        radionuclides=radionuclides,
        solver=solver,
    )

`from_file(*filenames)` `staticmethod`

Load from a file, auto-detecting format (TOML or INI).

Parameters:

Name	Type	Description	Default
`filenames`	`str`	One or more file paths.	`()`

Returns:

Type	Description
`Parameters`

Source code in src/aragog/config/__init__.py

@staticmethod
def from_file(*filenames: str) -> 'Parameters':
    """Load from a file, auto-detecting format (TOML or INI).

    Parameters
    ----------
    filenames : str
        One or more file paths.

    Returns
    -------
    Parameters
    """
    from pathlib import Path

    from aragog.parser import Parameters

    paths = [Path(f) for f in filenames]

    if any(p.suffix == '.toml' for p in paths):
        toml_path = next(p for p in paths if p.suffix == '.toml')
        return Config.from_toml(str(toml_path))

    # Fall back to legacy INI parser
    return Parameters.from_file(*filenames)

`from_toml(filename)` `staticmethod`

Load configuration from a TOML file and return a Parameters object.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Path to the TOML file.	required

Returns:

Type	Description
`Parameters`	Legacy Parameters object, ready for Solver.

Source code in src/aragog/config/__init__.py

@staticmethod
def from_toml(filename: str) -> 'Parameters':
    """Load configuration from a TOML file and return a Parameters object.

    Parameters
    ----------
    filename : str
        Path to the TOML file.

    Returns
    -------
    Parameters
        Legacy Parameters object, ready for Solver.
    """
    from pathlib import Path

    with Path(filename).open('rb') as f:
        data = tomllib.load(f)

    return Config.from_dict(data)

Boundary conditions

`BoundaryConfig`

Boundary condition parameters.

Parameters:

Name	Type	Description	Default
`outer_boundary_condition`	`int`	1: Grey-body, 2: Zahnle, 3: Atmodeller, 4: Prescribed flux, 5: Prescribed T	required
`outer_boundary_value`	`float`	Value for outer BC (flux in W/m^2 or T in K, depending on type).	required
`inner_boundary_condition`	`int`	1: Core cooling, 2: Prescribed flux, 3: Prescribed T	required
`inner_boundary_value`	`float`	Value for inner BC.	required
`emissivity`	`float`	Surface emissivity for grey-body BC.	required
`equilibrium_temperature`	`float`	Equilibrium temperature for grey-body BC [K].	required
`core_heat_capacity`	`float`	Core heat capacity [J/(kg K)].	required
`tfac_core_avg`	`float`	Core adiabat correction factor (Bower+2018).	required
`param_utbl`	`bool`	Enable upper thermal boundary layer parameterization.	required
`param_utbl_const`	`float`	UTBL constant.	required

Energy sources

`EnergyConfig`

Physics toggle flags, heating parameters, and solver knobs.

Defaults are aligned with the PROTEUS production path (SUNDIALS CVODE + JAX analytic Jacobian + tanh phase smoothing with the bottom-up gravitational-separation gate enabled and a phase-dependent eddy-diffusivity floor of 10 m^2/s).

Parameters:

Name	Type	Description	Default
`conduction`	`bool`		required
`convection`	`bool`		required
`gravitational_separation`	`bool`		required
`mixing`	`bool`		required
`radionuclides`	`bool`		required
`tidal`	`bool`		required
`eddy_diffusivity_chemical`	`float`	Ratio kappa_c / kappa_h for chemical eddy diffusivity.	required
`eddy_diffusivity_thermal`	`float`	Multiplier on the raw thermal eddy diffusivity \(\kappa_h\) before the floor is applied. The SPIDER convention also permits negative values, in which case the diffusivity is pinned to `\|eddy_diffusivity_thermal\|`. Default 1.0 passes the MLT-derived value through unchanged.	required
`kappah_floor`	`float`	Phase-dependent eddy-diffusivity floor [m^2/s]. Clamps the eddy diffusivity from below by `floor * f(phi)` where `f` falls from 1 (liquid) to 0 (solid) across the rheological transition. Default 10.0 matches PROTEUS production; set 0.0 for textbook MLT.	required
`bottom_up_grav_sep`	`bool`	SPIDER-analogue bottom-up gate for the gravitational mass-flux: only allow melt/solid separation across an interface when the staggered cell below is non-pure. Default True; off only for regression tests against the pre-fix CMB drain at first crystallisation.	required
`phase_smoothing`	`str`	Phase-boundary smoothing scheme for J_grav and J_mix: `'tanh'` (SPIDER parity, production default) or `'cubic_hermite'` (parameter-free fallback for residual EOS-mismatch cases).	required
`solver_method`	`str`	ODE backend: `'cvode'` (SUNDIALS via scikits.odes, production default), `'radau'` (scipy implicit Runge-Kutta), or `'bdf'` (scipy BDF). When scikits.odes is not installed the solver falls back to scipy Radau and emits a warning.	required
`use_jax_jacobian`	`bool`	When True and `solver_method='cvode'`, the integrator uses a JAX-derived analytic Jacobian (`jax.jacrev`) instead of CVODE's finite-difference Jacobian. Requires JAX and the `aragog.jax` module. Default True matches PROTEUS production; silently falls back to FD if no JAX factory was registered before `solve()`.	required
`phi_step_cap`	`float`	Per-call mass-weighted `\|ΔΦ_global\|` cap (SUNDIALS root function). When > 0 and at least one staggered cell sits in or near the mushy band at `solve()` entry, CVODE returns at the exact time where the change first reaches this value. Default 0.0 (disabled); 0.05 is typical for production evolution of 1 M_E PALEOS-2phase mantles.	required
`tidal_array`	`ndarray`	Tidal heating per unit mass [W/kg] at each layer.	required

Initial condition

`InitialConditionConfig`

Initial condition parameters.

Parameters:

Name	Type	Description	Default
`initial_condition`	`int`	1: Linear profile, 2: User-defined from file, 3: Adiabatic profile.	required
`surface_temperature`	`float`	Surface temperature [K].	required
`basal_temperature`	`float`	Basal temperature [K].	required
`init_file`	`str`	Path to user-defined temperature file (for IC type 2).	required

Mesh

`MeshConfig`

Mesh and static pressure profile parameters.

Parameters:

Name	Type	Description	Default
`outer_radius`	`float`	Outer radius of the mantle shell (planet radius minus atmosphere depth, in practice the same as `planet.radius`) [m].	required
`inner_radius`	`float`	Inner radius of the mantle shell, i.e. the core-mantle boundary (CMB) radius [m].	required
`number_of_nodes`	`int`	Number of basic mesh nodes.	required
`mixing_length_profile`	`str`	'constant' or 'nearest_boundary'.	required
`mixing_length_constant_fraction`	`float`	Fraction of the mantle thickness to use as the mixing length when `mixing_length_profile = 'constant'`. Default 0.25. Ignored for 'nearest_boundary'.	required
`core_density`	`float`	Core density [kg/m^3].	required
`eos_method`	`int`	1: Adams-Williamson, 2: User-defined.	required
`surface_density`	`float`	Surface-mantle density anchor [kg/m^3]. Used only by the analytic Adams-Williamson EOS (`eos_method = 1`) as the constant `rho_top` in `rho(P) = rho_top * exp(P/K_S)`. NOT the runtime material density (which is pressure-entropy dependent and comes from the P-S property tables). Default 4078.95095544 matches the SPIDER `-adams_williamson_rhos` value used in PROTEUS production runs. Ignored when `eos_method = 2`.	required
`gravitational_acceleration`	`float`	Gravitational acceleration [m/s^2].	required
`adiabatic_bulk_modulus`	`float`	Adiabatic bulk modulus [Pa].	required
`surface_pressure`	`float`	Surface pressure [Pa].	required
`mass_coordinates`	`bool`	Use uniform spacing in mass-coordinate space instead of radius. Gives larger cells at the surface (lower density) and matches SPIDER's mesh. Default True matches the PROTEUS production path.	required
`eos_file`	`str`	Path to user-defined EOS file.	required

Phases (single and mixed)

`PhaseConfig`

Single-phase (solid or liquid) material properties.

Each property can be a float (constant value) or a str (path to a lookup table file).

Parameters:

Name	Type	Description	Default
`density`	`float or str`	Density [kg/m^3] or path to lookup.	required
`heat_capacity`	`float or str`	Heat capacity [J/(kg K)] or path to lookup.	required
`melt_fraction`	`float`	Melt fraction (0 for solid, 1 for liquid).	required
`thermal_conductivity`	`float or str`	Thermal conductivity [W/(m K)] or path to lookup.	required
`thermal_expansivity`	`float or str`	Thermal expansivity [1/K] or path to lookup.	required
`viscosity`	`float or str`	Dynamic viscosity [Pa s] or path to lookup.	required
`entropy`	`float or str`	Entropy [J/(kg K)] or path to lookup. Empty string means unused.	required

`MixedPhaseConfig`

Mixed-phase (mushy zone) parameters.

Parameters:

Name	Type	Description	Default
`latent_heat_of_fusion`	`float`	Latent heat [J/kg].	required
`rheological_transition_melt_fraction`	`float`	Melt fraction at rheological transition.	required
`rheological_transition_width`	`float`	Width of the tanh smoothing around the transition.	required
`solidus`	`str`	Path to solidus lookup file.	required
`liquidus`	`str`	Path to liquidus lookup file.	required
`phase`	`str`	Active phase mode: 'solid', 'liquid', 'mixed', or 'composite'.	required
`phase_transition_width`	`float`	Width of smoothing at phase boundaries.	required
`grain_size`	`float`	Grain size [m] for permeability calculations.	required
`cp_blend`	`str`	Mushy-zone Cp blending mode: `'latent'` (SPIDER-parity, latent-heat-augmented) or `'linear'` (linear blend of pure-phase Cp without the latent term). Default `'latent'`.	required
`matprop_smooth_width`	`float`	Half-width of the tanh used to smooth phase-dependent material properties around the rheological transition. Default 0.0 reproduces SPIDER's convention of no smoothing on the property side; 0.01 is the typical JAX setting.	required
`const_properties`	`bool`	Replace the EOS-tabulated \((\rho, c_p, \alpha, k)\) and \(\log_{10}\eta\) with the seven constant-property values below. Mirrors SPIDER's `-use_const_properties`. Default False (use the EOS tables).	required
`const_rho`	`float`	Constant density [kg/m^3] when `const_properties` is True.	required
`const_Cp`	`float`	Constant heat capacity [J/(kg K)] when `const_properties` is True.	required
`const_alpha`	`float`	Constant thermal expansivity [1/K] when `const_properties` is True.	required
`const_cond`	`float`	Constant thermal conductivity [W/(m K)] when `const_properties` is True.	required
`const_log10visc`	`float`	Constant \(\log_{10}\) dynamic viscosity [log10(Pa s)] when `const_properties` is True.	required
`const_T_ref`	`float`	Reference temperature [K] for the constant-properties EOS, used to anchor \(T(P, S)\) on the analytic isentrope.	required
`const_S_ref`	`float`	Reference entropy [J/(kg K)] for the constant-properties EOS, paired with `const_T_ref`.	required

Radionuclides

`RadionuclideConfig`

Single radionuclide heating source.

Parameters:

Name	Type	Description	Default
`name`	`str`	Isotope name (e.g., 'K40', 'U238').	required
`t0_years`	`float`	Reference time for initial abundance [years].	required
`abundance`	`float`	Isotopic abundance ratio (e.g., 40K/K).	required
`concentration`	`float`	Elemental concentration [ppm].	required
`heat_production`	`float`	Specific heat production [W/kg].	required
`half_life_years`	`float`	Half-life [years].	required

`get_heating(time)`

Compute radiogenic heating at a given time.

Parameters:

Name	Type	Description	Default
`time`	`float or ndarray`	Time [years].	required

Returns:

Type	Description
`float or ndarray`	Heat production [W/kg].

Source code in src/aragog/config/radionuclides.py

def get_heating(self, time: npt.NDArray | float) -> npt.NDArray | float:
    """Compute radiogenic heating at a given time.

    Parameters
    ----------
    time : float or ndarray
        Time [years].

    Returns
    -------
    float or ndarray
        Heat production [W/kg].
    """
    arg = np.log(2) * (self.t0_years - time) / self.half_life_years
    return self.heat_production * self.abundance * self.concentration * np.exp(arg)

Solver driver

`SolverConfig`

ODE solver parameters.

Parameters:

Name	Type	Description	Default
`start_time`	`float`	Start time [years].	required
`end_time`	`float`	End time [years].	required
`atol`	`float`	Absolute tolerance for BDF solver.	required
`rtol`	`float`	Relative tolerance for BDF solver.	required
`tsurf_poststep_change`	`float`	Maximum surface temperature change per step [K].	required

aragog.config

Facade

Config

from_dict(data) staticmethod

from_file(*filenames) staticmethod

from_toml(filename) staticmethod

Boundary conditions

BoundaryConfig

Energy sources

EnergyConfig

Initial condition

InitialConditionConfig

Mesh

MeshConfig

Phases (single and mixed)

PhaseConfig

MixedPhaseConfig

Radionuclides

RadionuclideConfig

get_heating(time)

Solver driver

SolverConfig

`aragog.config`

`Config`

`from_dict(data)` `staticmethod`

`from_file(*filenames)` `staticmethod`

`from_toml(filename)` `staticmethod`

`BoundaryConfig`

`EnergyConfig`

`InitialConditionConfig`

`MeshConfig`

`PhaseConfig`

`MixedPhaseConfig`

`RadionuclideConfig`

`get_heating(time)`

`SolverConfig`