add description metadata to variables

Author: baggepinnen

docs/src/basics/Variable_metadata.md

@@ -2,6 +2,23 @@
 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)
 
+## Variable descriptions
+Descriptive strings can be attached to variables using the `[description = "descriptive string"]` syntax:
+```@example metadata
+using ModelingToolkit
+@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:
+```@example metadata
+@parameters t
+@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
+```
+
 ## Input or output
 Designate a variable as either an input or an output using the following
 ```@example metadata

src/ModelingToolkit.jl

@@ -173,7 +173,7 @@ export NonlinearSystem, OptimizationSystem
 export alias_elimination, flatten
 export connect, @connector, Connection, Flow, Stream, instream
 export isinput, isoutput, getbounds, hasbounds, isdisturbance, istunable, getdist, hasdist,
-       tunable_parameters, isirreducible
+       tunable_parameters, isirreducible, getdescription, hasdescription
 export ode_order_lowering, dae_order_lowering, liouville_transform
 export PDESystem
 export Differential, expand_derivatives, @derivatives

src/systems/abstractsystem.jl

@@ -752,6 +752,10 @@ function Base.show(io::IO, mime::MIME"text/plain", sys::AbstractSystem)
                                :displaysize => (1, displaysize(io)[2])), val)
                 print(io, "]")
             end
+            description = getdescription(s)
+            if description !== nothing && description != ""
+                print(io, ": ", description)
+            end
         end
     end
     limited && print(io, "\n⋮")
@@ -774,6 +778,10 @@ function Base.show(io::IO, mime::MIME"text/plain", sys::AbstractSystem)
                                :displaysize => (1, displaysize(io)[2])), val)
                 print(io, "]")
             end
+            description = getdescription(s)
+            if description !== nothing && description != ""
+                print(io, ": ", description)
+            end
         end
     end
     limited && print(io, "\n⋮")

src/variables.jl

@@ -267,3 +267,24 @@ function getbounds(p::AbstractVector)
     ub = last.(bounds)
     (; lb, ub)
 end
+
+## Description =================================================================
+struct VariableDescription end
+Symbolics.option_to_metadata_type(::Val{:description}) = VariableDescription
+
+getdescription(x::Num) = getdescription(Symbolics.unwrap(x))
+
+"""
+    getdescription(x)
+
+Return any description attached to variables `x`. If no description is attached, an empty string is returned.
+"""
+function getdescription(x)
+    p = Symbolics.getparent(x, nothing)
+    p === nothing || (x = p)
+    Symbolics.getmetadata(x, VariableDescription, "")
+end
+
+function hasdescription(x)
+    getdescription(x) != ""
+end

test/test_variable_metadata.jl

@@ -66,3 +66,19 @@ sp = Set(p)
 @test T ∈ sp
 @test k2 ∈ sp
 @test length(p) == 3
+
+## Descriptions
+@variables u [description = "This is my input"]
+@test getdescription(u) == "This is my input"
+@test hasdescription(u)
+
+@variables u
+@test getdescription(u) == ""
+@test !hasdescription(u)
+
+@parameters t
+@variables u(t) [description = "A short description of u"]
+@parameters p [description = "A description of p"]
+@named sys = ODESystem([u ~ p], t)
+
+@test_nowarn show(stdout, "text/plain", sys)