Skip to content

Configuration Reference

This page lists every settable field in the TOML configuration file. Fields that accept a sub-table are described in their own section below.

All fields are optional — each has a default value. The minimum useful config only needs [chemistry].

Top-level (StellarConfig)

StellarConfig pydantic-model

Bases: BaseModel

Top-level configuration for stellar evolution

Fields:

Validators:

  • validate_all

lane_emden cached property 

lane_emden: LaneEmdenGrid

The Lane-Emden grid for this config, built once on first access.

Pure function of model.mass, chemistry.mu and the grid overrides, so it is (re)built lazily after override()/reload rather than eagerly during validation. massunit is excluded from the grid kwargs (it is a post-grid scaling applied when emitting cards).

override 

override(**sections) -> StellarConfig

Return a new, fully re-validated config with section fields changed.

Intended for a "load a template, then tweak it" workflow::

cfg = load_config("template.toml")
cfg = cfg.override(
    model={"mass": 5.0, "metallicity": 0.001},
    chemistry={"preset": "sollo09"},
)

Each keyword names a config section (model, chemistry, grid, parameters, plot) and maps to a dict of field overrides that are shallow-merged over the existing values. Scalar top-level fields (e.g. output_dir) may be passed directly.

The whole validation pipeline re-runs on the merged data, so the Lane-Emden grid is rebuilt and the composition re-scaled. The original config is left untouched; a new instance is returned.

Notes
  • preset and custom are mutually exclusive: supplying one clears the other.
  • Changing preset/custom/name resets burngen (unless you override it explicitly) so it is regenerated for the new composition.

to_toml 

to_toml(path: str | Path | None = None) -> str

Serialise this config back to TOML, round-tripping load_config.

Only input-level fields are emitted (e.g. mass, preset, scale_to_Z, initial_Y, parameter overrides). Derived values -- the resolved composition, the computed plot parameters, the Lane-Emden grid -- are not written; they are reproduced when the file is reloaded.

Parameters

path: If given, the TOML is also written to this path.

Returns

str The TOML document text.

[model] — Star model

ModelConfig pydantic-model

Bases: BaseModel

Basic (higher) star configuration.

Example: ``` [model] mass: 4 metallicity: 0.014 rotation: 0.9 force_hstat: true

Fields:

Validators:

  • validate_mass → mass

mass pydantic-field 

mass: float = 1.0

Initial mass in Msun

metallicity pydantic-field 

metallicity: float = 0.02

Metal fraction Z

rotation pydantic-field 

rotation: float = 0.0

Rotation rate parameter. >1e6: we use value directly. 0 < val < 1e6: scale with max rotation. val<0: use Z=0 fits.

rotation_version pydantic-field 

rotation_version: int = 2

Algorithm to determine spin. 1: Heger 1998, 2: Woosley & Heger 2012

force_hstat pydantic-field 

force_hstat: bool = False

Whether to force the initial configuration into hydrostatic equilibrium. Can lead to noise.

[chemistry] — Composition and network

ChemistryConfig pydantic-model

Bases: BaseModel

Chemistry (network and materials) config

Example: 

[chemistry]
preset = 'as09' # asplund+09
scale_to_Z = true
coprocess = true

Fields:

Validators:

preset pydantic-field 

preset: Optional[str] = None

Name of preset composition (exclusive with custom). Requires $KEPLER_DATA to be set.

custom pydantic-field 

custom: Optional[dict[str, float]] = None

Custom ion abundances (exclusive with preset)

scale_to_Z pydantic-field 

scale_to_Z: bool = True

Whether to scale the composition to the given metallicity. Setting with a preset will scale all mass fractions to this metallicity

initial_Y pydantic-field 

initial_Y: Optional[float] = None

Optional target initial helium mass fraction Y. When set, the composition is scaled to this Y by drawing from (or adding to) hydrogen while preserving metals, instead of using the raw preset value. Independent of and applied after scale_to_Z.

num pydantic-field 

num: Literal[1] = 1

Network number

isenet pydantic-field 

isenet: bool = True

Whether to enable ISE/NSE networks (#2 and #3)

coprocess pydantic-field 

coprocess: bool = False

Whether to enable BURN coprocessing (mapburn only). Default OFF because use_burn is generally on.

use_burn pydantic-field 

use_burn: bool = True

Whether to use BURN as the main network (lburn).

burngen pydantic-field 

burngen: Optional[str] = None

BURN generator filepath. Automatically set to name of preset if preset is used.

adaptive pydantic-field 

adaptive: bool = True

Whether to use adaptive BURN network (adapnb).

network_z_max pydantic-field 

network_z_max: int = 86

Maximum mass number of elements to be allowed in the network.

[grid] — Lane-Emden grid overrides

GridConfig pydantic-model

Bases: BaseModel

Grid setup overrides to Lane Emden solver

Fields:

  • massunit (float)
  • cutoff (Optional[float])
  • ngrid (Optional[int])
  • rho_c (Optional[float])
  • n (Optional[float])
  • Omega (Optional[float])

massunit pydantic-field 

massunit: float = 1.0

Mass unit used on grid

cutoff pydantic-field 

cutoff: Optional[float] = None

density cutoff

ngrid pydantic-field 

ngrid: Optional[int] = None

number of initial grid points.

rho_c pydantic-field 

rho_c: Optional[float] = None

central density

n pydantic-field 

n: Optional[float] = None

polytrope index

[parameters] — Runtime parameter overrides

ParameterConfig pydantic-model

Bases: BaseModel

Controls for Kepler's adjustable runtime parameters.

Example 

[parameters]
dtmax: 3e12 # 10^5yrs in seconds
iwinsize: 10240750 # XXXX by YYYY
tnmin: 1e4  # minimum temperature for which rezoning is considered
dnmin: 1e-4 # minimum density for which rezoning is considered

Config:

  • extra: allow

Fields:

  • parameters (dict[str, float | int | str])

[plot] — Plotting settings

PlotConfig pydantic-model

Bases: BaseModel

Mongo plotting configuration.

Example: ``` [plot] window_width: 1024 window_height: 720 plot1: plot2:

Fields:

window_width pydantic-field 

window_width: int = 1024

XWindow height

window_height pydantic-field 

window_height: int = 720

XWindow width

interval pydantic-field 

interval: int = 1

Plotting interval in seconds

xaxis pydantic-field 

xaxis: int = 3

xaxis type (irtype).

plot1 pydantic-field 

plot1: PlotMode = 'abundances'

Plot mode 1

plot2 pydantic-field 

plot2: Optional[PlotMode] = None

Plot mode 2

plot3 pydantic-field 

plot3: Optional[PlotMode] = None

Plot mode 3

plot4 pydantic-field 

plot4: Optional[PlotMode] = None

Plot mode 4

isotopes pydantic-field 

isotopes: Optional[list[str]]

isotopes to plot when using isotope plot