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 pmap (or model => pars) to convert a MTKParams into the parameter map expected by ODEProblem/SciMLBase.remake, and cache + update! for fast in-place updates.

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),
)

pmap(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 pmap, 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.

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 pmap. Entries with missing values are skipped (the underlying setters do not accept missing). Returns prob.

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.