add variable metadata (#1560)

* add variable metadata

closes #1509

* optional default tunable metadata

Co-authored-by: Fredrik Bagge Carlson <[email protected]>

Author: baggepinnen

docs/make.jl

@@ -30,6 +30,7 @@ makedocs(
         "Basics" => Any[
             "basics/AbstractSystem.md",
             "basics/ContextualVariables.md",
+            "basics/Variable_metadata.md",
             "basics/Composition.md",
             "basics/Validation.md",
             "basics/DependencyGraphs.md",

docs/src/basics/Variable_metadata.md

@@ -0,0 +1,95 @@
+# Symbolic metadata
+It is possible to add metadata to symbolic variables. The following
+information can be added (note, it's possible to extend this to user-defined metadata as well)
+
+## Input or output
+Designate a variable as either an input or an output using the following
+```@example metadata
+using ModelingToolkit
+@variables u [input=true]
+isinput(u)
+```
+```@example metadata
+@variables y [output=true]
+isoutput(y)
+```
+
+## Bounds
+Bounds are useful when parameters are to be optimized, or to express intervals of uncertainty.
+
+```@example metadata
+@variables u [bounds=(-1,1)]
+hasbounds(u)
+```
+```@example metadata
+getbounds(u)
+```
+
+## Mark input as a disturbance 
+Indicate that an input is not available for control, i.e., it's a disturbance input.
+
+```@example metadata
+@variables u [input=true, disturbance=true]
+isdisturbance(u)
+```
+
+## Mark parameter as tunable
+Indicate that a parameter can be automatically tuned by automatic control tuning apps.
+
+```@example metadata
+@parameters Kp [tunable=true]
+istunable(Kp)
+```
+
+## Probability distributions
+A probability distribution may be associated with a parameter to indicate either
+uncertainty about it's value, or as a prior distribution for Bayesian optimization.
+
+```julia
+using Distributions
+d = Normal(10, 1)
+@parameters m [dist=d]
+hasdist(m)
+```
+```julia
+getdist(m)
+```
+
+## Additional functions
+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
+
+```@example metadata
+@parameters t
+Dₜ = Differential(t)
+@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)
+```
+```@example metadata
+p = tunable_parameters(sys) # extract all parameters marked as tunable
+```
+```@example metadata
+lb, ub = getbounds(p) # operating on a vector, we get lower and upper bound vectors
+```
+```@example metadata
+b = getbounds(sys) # Operating on the system, we get a dict
+```
+
+
+## Index
+```@index
+Pages = ["Variable_metadata.md"]
+```
+
+## Docstrings
+```@autodocs
+Modules = [ModelingToolkit]
+Pages = ["variables.jl"]
+Private = false
+```

src/ModelingToolkit.jl

@@ -173,6 +173,7 @@ export NonlinearSystem, OptimizationSystem
 export ControlSystem
 export alias_elimination, flatten
 export connect, @connector, Connection, Flow, Stream, instream
+export isinput, isoutput, getbounds, hasbounds, isdisturbance, istunable, getdist, hasdist, tunable_parameters
 export ode_order_lowering, liouville_transform
 export runge_kutta_discretize
 export PDESystem

src/variables.jl

@@ -94,3 +94,167 @@ ishistory(x) = ishistory(unwrap(x))
 ishistory(x::Symbolic) = getmetadata(x, IsHistory, false)
 hist(x, t) = wrap(hist(unwrap(x), t))
 hist(x::Symbolic, t) = setmetadata(toparam(similarterm(x, operation(x), [unwrap(t)], metadata=metadata(x))), IsHistory, true)
+
+
+## Bounds ======================================================================
+struct VariableBounds end
+Symbolics.option_to_metadata_type(::Val{:bounds}) = VariableBounds
+getbounds(x::Num) = getbounds(Symbolics.unwrap(x))
+
+"""
+    getbounds(x)
+
+Get the bounds associated with symbolc variable `x`.
+Create parameters with bounds like this
+```
+@parameters p [bounds=(-1, 1)]
+```
+"""
+function getbounds(x)
+    p = Symbolics.getparent(x, nothing)
+    p === nothing || (x = p)
+    Symbolics.getmetadata(x, VariableBounds, (-Inf, Inf))
+end
+
+"""
+    hasbounds(x)
+
+Determine whether or not symbolic variable `x` has bounds associated with it.
+See also [`getbounds`](@ref).
+"""
+function hasbounds(x)
+    b = getbounds(x)
+    isfinite(b[1]) && isfinite(b[2])
+end
+
+
+## Disturbance =================================================================
+struct VariableDisturbance end
+Symbolics.option_to_metadata_type(::Val{:disturbance}) = VariableDisturbance
+
+isdisturbance(x::Num) = isdisturbance(Symbolics.unwrap(x))
+
+"""
+    isdisturbance(x)
+
+Determine whether or not symbolic variable `x` is marked as a disturbance input.
+"""
+function isdisturbance(x)
+    p = Symbolics.getparent(x, nothing)
+    p === nothing || (x = p)
+    Symbolics.getmetadata(x, VariableDisturbance, false)
+end
+
+
+## Tunable =====================================================================
+struct VariableTunable end
+Symbolics.option_to_metadata_type(::Val{:tunable}) = VariableTunable
+
+istunable(x::Num, args...) = istunable(Symbolics.unwrap(x), args...)
+
+"""
+    istunable(x, default = false)
+
+Determine whether or not symbolic variable `x` is marked as a tunable for an automatic tuning algorithm.
+
+`default` indicates whether variables without `tunable` metadata are to be considered tunable or not.
+
+Create a tunable parameter by
+```
+@parameters u [tunable=true]
+```
+See also [`tunable_parameters`](@ref), [`getbounds`](@ref)
+"""
+function istunable(x, default=false)
+    p = Symbolics.getparent(x, nothing)
+    p === nothing || (x = p)
+    Symbolics.getmetadata(x, VariableTunable, default)
+end
+
+
+## Dist ========================================================================
+struct VariableDistribution end
+Symbolics.option_to_metadata_type(::Val{:dist}) = VariableDistribution
+getdist(x::Num) = getdist(Symbolics.unwrap(x))
+
+"""
+    getdist(x)
+
+Get the probability distribution associated with symbolc variable `x`. If no distribution
+is associated with `x`, `nothing` is returned.
+Create parameters with associated distributions like this
+```julia
+using Distributions
+d = Normal(0, 1)
+@parameters u [dist=d]
+hasdist(u) # true
+getdist(u) # retrieve distribution
+```
+"""
+function getdist(x)
+    p = Symbolics.getparent(x, nothing)
+    p === nothing || (x = p)
+    Symbolics.getmetadata(x, VariableDistribution, nothing)
+end
+
+"""
+    hasdist(x)
+
+Determine whether or not symbolic variable `x` has a probability distribution associated with it.
+"""
+function hasdist(x)
+    b = getdist(x)
+    b !== nothing
+end
+
+
+## System interface
+
+"""
+    tunable_parameters(sys, p = parameters(sys); default=false)
+
+Get all parameters of `sys` that are marked as `tunable`.
+
+Keyword argument `default` indicates whether variables without `tunable` metadata are to be considered tunable or not.
+
+Create a tunable parameter by
+```
+@parameters u [tunable=true]
+```
+See also [`getbounds`](@ref), [`istunable`](@ref)
+"""
+function tunable_parameters(sys, p = parameters(sys); default=false)
+    filter(x->istunable(x, default), p)
+end
+
+"""
+    getbounds(sys::ModelingToolkit.AbstractSystem)
+
+Returns a dict with pairs `p => (lb, ub)` mapping parameters of `sys` to lower and upper bounds.
+Create parameters with bounds like this
+```
+@parameters p [bounds=(-1, 1)]
+```
+"""
+function getbounds(sys::ModelingToolkit.AbstractSystem)
+    p = parameters(sys)
+    Dict(p .=> getbounds.(p))
+end
+
+"""
+    lb, ub = getbounds(p::AbstractVector)
+
+Return vectors of lower and upper bounds of parameter vector `p`.
+Create parameters with bounds like this
+```
+@parameters p [bounds=(-1, 1)]
+```
+See also [`tunable_parameters`](@ref), [`hasbounds`](@ref)
+"""
+function getbounds(p::AbstractVector)
+    bounds = getbounds.(p)
+    lb = first.(bounds)
+    ub = last.(bounds)
+    (; lb, ub)
+end
+

test/runtests.jl

@@ -30,6 +30,7 @@ using SafeTestsets, Test
 @safetestset "Precompiled Modules Test" begin include("precompile_test.jl") end
 @testset "Distributed Test" begin include("distributed.jl") end
 @safetestset "Variable Utils Test" begin include("variable_utils.jl") end
+@safetestset "Variable Metadata Test" begin include("test_variable_metadata.jl") end
 @safetestset "DAE Jacobians Test" begin include("dae_jacobian.jl") end
 @safetestset "Jacobian Sparsity" begin include("jacobiansparsity.jl") end
 println("Last test requires gcc available in the path!")

test/test_variable_metadata.jl

@@ -0,0 +1,69 @@
+using ModelingToolkit
+
+# Bounds
+@variables u [bounds=(-1,1)]
+@test getbounds(u) == (-1, 1)
+@test hasbounds(u)
+
+@variables y
+@test !hasbounds(y)
+
+
+# Disturbance
+@variables u [disturbance=true]
+@test isdisturbance(u)
+
+@variables y
+@test !isdisturbance(y)
+
+
+# Tunable
+@parameters u [tunable=true]
+@test istunable(u)
+
+@parameters y
+@test !istunable(y)
+
+# Distributions
+struct FakeNormal end
+d = FakeNormal()
+@parameters u [dist=d]
+@test hasdist(u)
+@test getdist(u) == d
+
+@parameters y
+@test !hasdist(y)
+
+## System interface
+@parameters t
+Dₜ = Differential(t)
+@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)]
+@parameters k2
+eqs = [
+    Dₜ(x) ~ (-k2*x + k*u) / T
+    y ~ x
+]
+sys = ODESystem(eqs, t, name=:tunable_first_order)
+
+p = tunable_parameters(sys)
+sp = Set(p)
+@test k ∈ sp
+@test T ∈ sp
+@test k2 ∉ sp
+@test length(p) == 2
+
+lb, ub = getbounds(p)
+@test lb == [0,0]
+@test ub == [Inf, Inf]
+
+b = getbounds(sys)
+@test b[T] == (0, Inf)
+
+p = tunable_parameters(sys, default=true)
+sp = Set(p)
+@test k ∈ sp
+@test T ∈ sp
+@test k2 ∈ sp
+@test length(p) == 3