Merge pull request #4425 from SebastianM-C/smc/nominal_value

Add nominal value metadata

Author: AayushSabharwal

docs/src/API/variables.md

@@ -173,6 +173,33 @@ getbounds
 ModelingToolkit.VariableBounds
 ```
 
+## Nominal Value
+
+A nominal value represents the characteristic magnitude of a variable. This is useful
+for scaling constraints in optimal control problems, preventing ill-conditioning when
+variables have vastly different magnitudes. The default nominal value is `1.0`.
+
+```@repl metadata
+@variables x [nominal = 1000.0];
+hasnominal(x)
+getnominal(x)
+```
+
+Nominal values can also be specified for array variables:
+
+```@repl metadata
+@variables x[1:3] [nominal = [100.0, 200.0, 300.0]];
+getnominal(x)
+getnominal(x[1])
+```
+
+```@docs
+hasnominal
+getnominal
+setnominal
+ModelingToolkit.VariableNominal
+```
+
 ## Guess
 
 Specify an initial guess for variables of a `System`. This is used when building the

lib/ModelingToolkitBase/src/ModelingToolkitBase.jl

@@ -257,7 +257,7 @@ export flatten
 export connect, domain_connect, @connector, Connection, AnalysisPoint, Flow, Stream,
     instream
 export @component, @mtkcompile, @mtkbuild, @mtkcomplete
-export isinput, isoutput, getbounds, hasbounds, getguess, hasguess, isdisturbance,
+export isinput, isoutput, getbounds, hasbounds, getnominal, hasnominal, setnominal, getguess, hasguess, isdisturbance,
     istunable, getdist, hasdist,
     tunable_parameters, isirreducible, getdescription, hasdescription,
     hasunit, getunit, hasconnect, getconnect,

lib/ModelingToolkitBase/src/variables.jl

@@ -465,6 +465,40 @@ function setbounds(x::Num, bounds)
     return setmetadata(x, VariableBounds, (lb, ub))
 end
 
+## Nominal =====================================================================
+struct VariableNominal end
+Symbolics.option_to_metadata_type(::Val{:nominal}) = VariableNominal
+
+"""
+    getnominal(x)
+
+Get the nominal value associated with symbolic variable `x`. Returns `1.0` if no nominal value is set.
+Create variables with a nominal value like this
+
+```
+@variables x [nominal = 4785.0]
+```
+"""
+getnominal(x::Union{Num, Symbolics.Arr}) = getnominal(unwrap(x))
+function getnominal(x::SymbolicT)
+    s = Symbolics.getmetadata_maybe_indexed(x, VariableNominal, nothing)
+    s === nothing ? 1.0 : s
+end
+
+"""
+    hasnominal(x)
+
+Determine whether symbolic variable `x` has a nominal value associated with it.
+See also [`getnominal`](@ref).
+"""
+function hasnominal(x)
+    Symbolics.getmetadata_maybe_indexed(unwrap(x), VariableNominal, nothing) !== nothing
+end
+
+function setnominal(x::Num, val)
+    return setmetadata(x, VariableNominal, val)
+end
+
 ## Disturbance =================================================================
 struct VariableDisturbance end
 Symbolics.option_to_metadata_type(::Val{:disturbance}) = VariableDisturbance
@@ -608,6 +642,26 @@ function getbounds(p::AbstractVector)
     return (; lb, ub)
 end
 
+"""
+    getnominal(sys::ModelingToolkitBase.AbstractSystem, vars = parameters(sys))
+
+Returns a dict with pairs `var => nominal` mapping variables of `sys` to their nominal values.
+Create variables with a nominal value like this
+
+```
+@variables x [nominal = 40.0]
+```
+
+To obtain unknown variable nominal values, call `getnominal(sys, unknowns(sys))`
+"""
+function getnominal(sys::ModelingToolkitBase.AbstractSystem, p = parameters(sys))
+    return Dict(p .=> getnominal.(p))
+end
+
+function getnominal(p::AbstractVector)
+    return getnominal.(p)
+end
+
 ## Description =================================================================
 """
     $TYPEDEF

lib/ModelingToolkitBase/test/test_variable_metadata.jl

@@ -263,3 +263,49 @@ x = ModelingToolkitBase.toparam(x)
 
 @brownians z
 @test ModelingToolkitBase.getvariabletype(z) == ModelingToolkitBase.BROWNIAN
+
+# Nominal
+@variables x [nominal = 100.0]
+@test getnominal(x) == 100.0
+@test hasnominal(x)
+
+@variables y
+@test !hasnominal(y)
+@test getnominal(y) == 1.0
+
+y2 = setnominal(y, 50.0)
+@test getnominal(y2) == 50.0
+@test hasnominal(y2)
+
+@variables z [nominal = 0.001]
+@test getnominal(z) == 0.001
+
+# Vector of variables
+vals = getnominal([x, y, z])
+@test vals == [100.0, 1.0, 0.001]
+
+# Vector variables
+@variables yv[1:3] [nominal = [100.0, 200.0, 300.0]]
+@test hasnominal(yv)
+@test getnominal(yv) == [100.0, 200.0, 300.0]
+for i in 1:3
+    @test hasnominal(yv[i])
+end
+@test getnominal(yv[1]) == 100.0
+@test getnominal(yv[2]) == 200.0
+@test getnominal(yv[3]) == 300.0
+
+@variables wv[1:3]
+@test !hasnominal(wv)
+@test getnominal(wv[1]) == 1.0
+
+# System-level accessor
+@independent_variables t5
+Dₜ5 = Differential(t5)
+@variables x5(t5) [nominal = 100.0] y5(t5) z5(t5) [nominal = 0.001]
+@parameters α5 = 1.5 β5 = 1.0
+eqs5 = [Dₜ5(x5) ~ α5 * x5, Dₜ5(y5) ~ -β5 * y5, Dₜ5(z5) ~ x5 - z5]
+sys5 = System(eqs5, t5, name = :nominal_test)
+nv = getnominal(sys5, unknowns(sys5))
+@test nv isa Dict
+@test length(nv) == length(unknowns(sys5))