MTKParams(Model::Function; kwargs...)
MTKParams(sys::System;     kwargs...)

A mutable, hierarchical parameter container for a ModelingToolkit System. Each field mirrors a parameter or sub-system of the underlying model and can be read or mutated with normal getproperty/setproperty! syntax (e.g. pars.resistor.R = 2). Bounds attached to parameters via @parameters X, [bounds=(lo, hi)] are enforced on assignment.

The system must NOT be structurally simplified — construct it with @named (@mtkcompile/@mtkbuild will throw). Initial values come from ModelingToolkit.initial_conditions(sys). Any keyword arguments are applied as parameter overrides after construction.

Use pdict (or model => pars) to convert a MTKParams into the parameter map expected by ODEProblem/SciMLBase.remake, and cache + update! for fast in-place updates.

The printed tree display shows nothing/missing leaf values by default; call hide_missing!/show_missing! to toggle this for the whole tree.

Examples

pars = MTKParams(RCModel)
pars.resistor.R = 2.0

pars = MTKParams(ConstantVoltage; V = 20)

@mtkparams name = Model(; sub = ChildComponent(p = 1), kw = value, ...)
@mtkparams const name = Model(; ...)
@mtkparams Model(; ...)                                   # bare-call form

Convenience macro that rewrites Model(...) into MTKParams(Model; ...), recursively transforming nested component constructor calls into nested MTKParams calls. Wrapping an assignment lets the catalog name appear in front of the macro so the declaration reads top-to-bottom; const is also supported. The bare-call form (name = @mtkparams Model(...)) still works.

Example

@mtkparams seat_pars = MassSpringDamper(
    body   = Mass(m = 100),
    spring = Spring(k = 1000),
    damper = Damper(d = 1),
)

expands (roughly) to

seat_pars = MTKParams(MassSpringDamper;
    body   = MTKParams(Mass;   m = 100),
    spring = MTKParams(Spring; k = 1000),
    damper = MTKParams(Damper; d = 1),
)

pdict(model::System, pars::MTKParams) -> Dict

Build a Dict{symbolic_parameter, value} keyed by the symbolic parameters of model. This is the form accepted by update! and the cache-aware SciMLBase.remake(prob, setters, param_dict) method.

For the flat Vector{Pair} form expected by ODEProblem and the standard SciMLBase.remake(prob; p = ...), write model => pars instead.

Pair(model::System, pars::MTKParams) -> Vector{Pair}

Flatten pars against model into a Vector{Pair} of symbolic_parameter => value entries (recursively walking sub-systems). This is the form accepted by ODEProblem and SciMLBase.remake(prob; p = ...). Equivalent to writing model => pars.

Fields of pars that don't have a matching property on model produce a warning and are skipped.

cache(model::System, x::MTKParams; parent = model) -> Vector{ParameterHookWrapper}

Pre-build a vector of SymbolicIndexingInterface setter functions, one per parameter field reachable from x (recursing into sub-systems). Pass the result, together with a parameter map from pdict, to update! or SciMLBase.remake to mutate an ODEProblem without rebuilding the setters on each call.

parent is the top-level system used when constructing each setp setter; it only differs from model when cache recurses into a sub-system.

resolve(val, param_dict::PDict)

Reduce a pdict value to the concrete value a setter can write.

A parameter's value is not always concrete: it can be a symbolic expression of other parameters in the same map. Dyad's code generator propagates a parent parameter into a sub-component by recording the child's initial condition as the parent's symbolic variable (source₊medium_data => medium_data), and defaults may be expressions of those (source₊medium₊p_crit => critical_pressure_Pa(source₊medium_data)). Such chains can be several levels deep.

SciMLBase.remake(prob; p = ...) resolves these itself, but the cache setters write straight into the parameter buffer, so they have to be resolved here first — otherwise the raw symbolic reaches the buffer and fails to convert to the parameter's type. Concrete values (the common case) skip substitution entirely.

update!(prob::ODEProblem,
        setters::Vector{ParameterHookWrapper},
        param_dict::Dict) -> prob

Mutate prob in place by applying every setter in setters whose target parameter appears in param_dict. setters is produced by cache and param_dict by pdict. Values that are symbolic expressions of other parameters in param_dict are resolved first (see resolve). Entries with missing values are skipped (the underlying setters do not accept missing). Returns prob.

transfer(pars::MTKParams, prob::ODEProblem) -> new_pars::MTKParams

Return a copy of pars with every parameter it exposes updated to the value currently held by prob (read via prob.ps). pars itself is left unmodified.

This generalizes patterns like

pars.seat.spring.initial_stretch = prob.ps[sys.seat.spring.initial_stretch]

to every parameter pars exposes, which is useful for pulling values that were solved for during ODEProblem initialization (e.g. Dyad's p = missing, [guess=...] initialization parameters) back into a MTKParams object.

The model is recovered from prob.f.sys. If a parameter pars exposes cannot be read from prob.ps (not present on the model, or the value comes back missing), it is skipped with a warning and new_pars keeps pars' original value for that field.

compare(pars1::MTKParams, pars2::MTKParams) -> MTKParamsDiff

Compare two MTKParams trees and return an MTKParamsDiff listing every parameter path where the two disagree (by isequal), along with the value on each side. Recurses into sub-systems; the path shown for each row is the dotted name (e.g. "seat.spring.initial_stretch").

pars1 and pars2 need not expose exactly the same parameters (e.g. built from different model variants): the union of both trees' paths is walked, and a path present on only one side shows up as a diff row with the other side marked Absent.

If there are no differences, the returned MTKParamsDiff displays as "No differences.".

MTKParamsDiff(rows::Vector{MTKParamsDiffRow})

Result of compare: the parameter paths where two MTKParams trees differ. Displays as a table (path, pars1 value, pars2 value); if rows is empty, displays as "No differences.".

show_missing!(p::MTKParams)

Turn on display of nothing/missing leaf values when printing p (the default). Applies to the whole MTKParams tree p belongs to, since display options are shared across it — see hide_missing!.

hide_missing!(p::MTKParams)

Turn off display of nothing/missing leaf values when printing p. Applies to the whole MTKParams tree p belongs to, since display options are shared across it — see show_missing!.

save_parameters(x::MTKParams, filepath::String)

Write x to filepath as a hierarchical TOML file. missing values are stored as the string "missing" so they round-trip through load_parameters.

load_parameters(filepath::String, model::Function) -> MTKParams

Construct a fresh MTKParams(model) and apply the values stored in the TOML file at filepath (typically written by save_parameters).

load_parameters(filepath::String, sys::System) -> MTKParams

Construct a fresh MTKParams(sys) and apply the values stored in the TOML file at filepath (typically written by save_parameters).

load_parameters(filepath::String, x::MTKParams) -> MTKParams

Apply the values stored in the TOML file at filepath (typically written by save_parameters) to the x::MTKParams parameter object.

parameters_to_string(x::MTKParams) -> String

Return the TOML representation of x as a String. Same format as save_parameters writes, but without touching the filesystem.

string_to_parameters(contents::String, x::MTKParams) -> MTKParams

Apply parameter values parsed from the TOML string contents to the existing MTKParams instance x, mutating it in place. Returns x.

get_parent(p::MTKParams) -> System

Return the underlying (un-simplified) System that backs p. Use this instead of p.parent, since getproperty on a MTKParams looks up parameters by name.

get_defs(p::MTKParams) -> Dict

Return the internal symbolic_parameter => value dictionary holding the current overrides for p. Mutating the returned dict mutates p.