Merge pull request #1688 from SciML/fb/descriptions

add description metadata to variables

Author: YingboMa

docs/src/basics/Variable_metadata.md

@@ -1,6 +1,38 @@
 # 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)
+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)
+
+## 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
+```
+
+Calling help on the variable `u` displays the description, alongside other metadata:
+```julia
+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)
+```
 
 ## Input or output
 Designate a variable as either an input or an output using the following

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

@@ -1,14 +1,12 @@
 struct VariableUnit end
 struct VariableConnectType end
 struct VariableNoiseType end
-struct VariableDescriptionType end
 struct VariableInput end
 struct VariableOutput end
 struct VariableIrreducible end
 Symbolics.option_to_metadata_type(::Val{:unit}) = VariableUnit
 Symbolics.option_to_metadata_type(::Val{:connect}) = VariableConnectType
 Symbolics.option_to_metadata_type(::Val{:noise}) = VariableNoiseType
-Symbolics.option_to_metadata_type(::Val{:description}) = VariableDescriptionType
 Symbolics.option_to_metadata_type(::Val{:input}) = VariableInput
 Symbolics.option_to_metadata_type(::Val{:output}) = VariableOutput
 Symbolics.option_to_metadata_type(::Val{:irreducible}) = VariableIrreducible
@@ -267,3 +265,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)