It is possible to add metadata to symbolic variables, the metadata will be displayed when calling help on a variable.
The following information can be added (note, it's possible to extend this to user-defined metadata as well)
Descriptive strings can be attached to variables using the [description = "descriptive string"] syntax:
using ModelingToolkit
using ModelingToolkit: t_nounits as t, D_nounits as D
@variables u [description = "This is my input"]
getdescription(u)
When variables with descriptions are present in systems, they will be printed when the system is shown in the terminal:
@variables u(t) [description = "A short description of u"]
@parameters p [description = "A description of p"]
@named sys = ODESystem([u ~ p], t)
show(stdout, "text/plain", sys) # hide
Calling help on the variable u displays the description, alongside other metadata:
help?> u
A variable of type Symbolics.Num (Num wraps anything in a type that is a subtype of Real)
Metadata
≡≡≡≡≡≡≡≡≡≡
ModelingToolkit.VariableDescription: This is my input
Symbolics.VariableSource: (:variables, :u)
Variables in connectors can have connect metadata which describes the type of connections.
Flow is used for variables that represent physical quantities that "flow" ex:
current in a resistor. These variables sum up to zero in connections.
Stream can be specified for variables that flow bi-directionally.
using ModelingToolkit
using ModelingToolkit: t_nounits as t, D_nounits as D
@variables i(t) [connect = Flow]
@variables k(t) [connect = Stream]
Designate a variable as either an input or an output using the following
using ModelingToolkit
using ModelingToolkit: t_nounits as t, D_nounits as D
@variables u [input = true]
isinput(u)
@variables y [output = true]
isoutput(y)
Bounds are useful when parameters are to be optimized, or to express intervals of uncertainty.
@variables u [bounds = (-1, 1)]
hasbounds(u)
getbounds(u)
Specify an initial guess for custom initial conditions of an ODESystem.
@variables u [guess = 1]
hasguess(u)
getguess(u)
Indicate that an input is not available for control, i.e., it's a disturbance input.
@variables u [input = true, disturbance = true]
isdisturbance(u)
Indicate that a parameter can be automatically tuned by parameter optimization or automatic control tuning apps.
@parameters Kp [tunable = true]
istunable(Kp)
A probability distribution may be associated with a parameter to indicate either uncertainty about its value, or as a prior distribution for Bayesian optimization.
using Distributions
d = Normal(10, 1)
@parameters m [dist = d]
hasdist(m)getdist(m)For systems that contain parameters with metadata like described above, have some additional functions defined for convenience. In the example below, we define a system with tunable parameters and extract bounds vectors
@variables x(t)=0 u(t)=0 [input = true] y(t)=0 [output = true]
@parameters T [tunable = true, bounds = (0, Inf)]
@parameters k [tunable = true, bounds = (0, Inf)]
eqs = [D(x) ~ (-x + k * u) / T # A first-order system with time constant T and gain k
y ~ x]
sys = ODESystem(eqs, t, name = :tunable_first_order)
p = tunable_parameters(sys) # extract all parameters marked as tunable
lb, ub = getbounds(p) # operating on a vector, we get lower and upper bound vectors
b = getbounds(sys) # Operating on the system, we get a dict
See also: ModelingToolkit.dump_variable_metadata, ModelingToolkit.dump_parameters,
ModelingToolkit.dump_unknowns.
Pages = ["Variable_metadata.md"]
Modules = [ModelingToolkit]
Pages = ["variables.jl"]
Private = false
ModelingToolkit.dump_variable_metadata
ModelingToolkit.dump_parameters
ModelingToolkit.dump_unknowns