Optional parameters

Model options control the numerical solver, timestep size, and what state is recorded. They can be set in three ways:

  1. As keyword arguments when creating the model:

    model = Model(data_df, sas_specs=..., dt=0.01, n_substeps=5)

  2. In the "options" section of a JSON config file:

{
    "options": {
        "dt": 0.01,
        "n_substeps": 5
    }
}

  1. By assigning a dict after creation:

    model.options = {"n_substeps": 10}

Only the specified options are changed; others retain their current values.

The ModelOptions dataclass can also be used directly:

from mesas import ModelOptions
opts = ModelOptions(dt=0.01, n_substeps=5, num_scheme=2)

Available options

dtfloat, default = 1.0

Timestep size, in appropriate units. The product dt * flux must equal the volume of fluid transferred in one timestep.

verbosebool, default = False

Print solver progress information.

debugbool, default = False

Print detailed debug output from the solver.

warningbool, default = True

Enable/disable solver warnings about numerical issues.

num_schemeint, default = 4

Numerical integration scheme:

  • 1 — Forward Euler (1st order)

  • 2 — Midpoint method (2nd order)

  • 4 — Runge-Kutta 4 (4th order, recommended)

n_substepsint, default = 1

Number of sub-timesteps per full timestep. Increasing this improves numerical accuracy at the cost of longer run times. Sub-step results are aggregated back to the full timestep.

max_ageint, default = len(data_df)

Maximum water age to track (in timesteps). Set to a value smaller than the timeseries length to reduce computation time. Water older than max_age is assigned concentration C_old.

sT_init1-D numpy array, default = zeros

Initial age-ranked storage distribution (density form). Useful for spin-up. If provided, max_age is set to len(sT_init).

influxstr, default = "J"

Name of the column in data_df containing the inflow rate.

record_statebool or str, default = False

Controls which timesteps are recorded in the output arrays:

  • False — record only the final timestep (saves memory)

  • True — record every timestep (required for water/solute balance checks)

  • A string — name of a boolean column in data_df indicating which timesteps to record

jacobianbool, default = False

Not implemented in the v2 solver: setting True raises NotImplementedError. Use numerical jacobians instead (e.g. mesas.me.recursive_split.fit_model with jacobian_mode="numerical").

record_everyint or None, default = None

Record the state at the end of every k-th timestep — a memory-saving alternative to record_state=True.

record_arrays“all” or iterable of str, default = “all”

Which state arrays to record (subset of {"sT", "pQ", "mT", "mQ", "mR", "water_balance", "solute_balance"}). Unselected arrays are never allocated.

record_dtype{“float64”, “float32”}, default = “float64”

Storage dtype for the recorded arrays; "float32" halves memory. Computation is always float64.

record_tostr or None, default = None

Directory in which to store the recorded arrays as disk-backed .npy memory maps instead of RAM. Reloadable later with Model.load_state(). See Extracting results.

validate_inputsbool, default = True

Check input data and SAS parameters for NaN, negative fluxes, and non-positive distribution parameters before running, raising a descriptive error. Set False to skip.

ST_smallest_segmentfloat, default = 0.01

Minimum allowed piecewise segment length along the \(S_T\) axis.

ST_largest_segmentfloat, default = inf

Maximum allowed piecewise segment length along the \(S_T\) axis.