From ffc43d2a923d8654b17910bba0f55c94dc91171a Mon Sep 17 00:00:00 2001
From: Herman Sletmoen <hermansletmoen@gmail.com>
Date: Thu, 17 Oct 2024 16:18:57 +0200
Subject: [PATCH] Add description to all systems

---
 src/systems/abstractsystem.jl                  |  1 +
 src/systems/diffeqs/odesystem.jl               | 11 ++++++++---
 src/systems/diffeqs/sdesystem.jl               | 15 ++++++++++-----
 src/systems/discrete_system/discrete_system.jl | 12 +++++++++---
 src/systems/jumps/jumpsystem.jl                |  9 ++++++---
 src/systems/nonlinear/nonlinearsystem.jl       | 12 +++++++++---
 src/systems/optimization/constraints_system.jl | 11 ++++++++---
 src/systems/optimization/optimizationsystem.jl |  9 ++++++---
 src/systems/pde/pdesystem.jl                   |  7 ++++++-
 9 files changed, 63 insertions(+), 24 deletions(-)

diff --git a/src/systems/abstractsystem.jl b/src/systems/abstractsystem.jl
index 117c37a70d..2bc3335b81 100644
--- a/src/systems/abstractsystem.jl
+++ b/src/systems/abstractsystem.jl
@@ -986,6 +986,7 @@ for prop in [:eqs
              :ps
              :tspan
              :name
+             :description
              :var_to_name
              :ctrls
              :defaults
diff --git a/src/systems/diffeqs/odesystem.jl b/src/systems/diffeqs/odesystem.jl
index ec2c5f8157..b59f08878c 100644
--- a/src/systems/diffeqs/odesystem.jl
+++ b/src/systems/diffeqs/odesystem.jl
@@ -79,6 +79,10 @@ struct ODESystem <: AbstractODESystem
     """
     name::Symbol
     """
+    A description of the system.
+    """
+    description::String
+    """
     The internal systems. These are required to have unique names.
     """
     systems::Vector{ODESystem}
@@ -178,7 +182,7 @@ struct ODESystem <: AbstractODESystem
     parent::Any
 
     function ODESystem(tag, deqs, iv, dvs, ps, tspan, var_to_name, ctrls, observed, tgrad,
-            jac, ctrl_jac, Wfact, Wfact_t, name, systems, defaults, guesses,
+            jac, ctrl_jac, Wfact, Wfact_t, name, description, systems, defaults, guesses,
             torn_matching, initializesystem, initialization_eqs, schedule,
             connector_type, preface, cevents,
             devents, parameter_dependencies,
@@ -199,7 +203,7 @@ struct ODESystem <: AbstractODESystem
             check_units(u, deqs)
         end
         new(tag, deqs, iv, dvs, ps, tspan, var_to_name, ctrls, observed, tgrad, jac,
-            ctrl_jac, Wfact, Wfact_t, name, systems, defaults, guesses, torn_matching,
+            ctrl_jac, Wfact, Wfact_t, name, description, systems, defaults, guesses, torn_matching,
             initializesystem, initialization_eqs, schedule, connector_type, preface,
             cevents, devents, parameter_dependencies, metadata,
             gui_metadata, is_dde, tearing_state, substitutions, complete, index_cache,
@@ -213,6 +217,7 @@ function ODESystem(deqs::AbstractVector{<:Equation}, iv, dvs, ps;
         systems = ODESystem[],
         tspan = nothing,
         name = nothing,
+        description = "",
         default_u0 = Dict(),
         default_p = Dict(),
         defaults = _merge(Dict(default_u0), Dict(default_p)),
@@ -290,7 +295,7 @@ function ODESystem(deqs::AbstractVector{<:Equation}, iv, dvs, ps;
     end
     ODESystem(Threads.atomic_add!(SYSTEM_COUNT, UInt(1)),
         deqs, iv′, dvs′, ps′, tspan, var_to_name, ctrl′, observed, tgrad, jac,
-        ctrl_jac, Wfact, Wfact_t, name, systems, defaults, guesses, nothing, initializesystem,
+        ctrl_jac, Wfact, Wfact_t, name, description, systems, defaults, guesses, nothing, initializesystem,
         initialization_eqs, schedule, connector_type, preface, cont_callbacks,
         disc_callbacks, parameter_dependencies,
         metadata, gui_metadata, is_dde, checks = checks)
diff --git a/src/systems/diffeqs/sdesystem.jl b/src/systems/diffeqs/sdesystem.jl
index 0d73aaf313..8343f35e17 100644
--- a/src/systems/diffeqs/sdesystem.jl
+++ b/src/systems/diffeqs/sdesystem.jl
@@ -80,6 +80,10 @@ struct SDESystem <: AbstractODESystem
     """
     name::Symbol
     """
+    A description of the system.
+    """
+    description::String
+    """
     The internal systems. These are required to have unique names.
     """
     systems::Vector{SDESystem}
@@ -142,7 +146,7 @@ struct SDESystem <: AbstractODESystem
     function SDESystem(tag, deqs, neqs, iv, dvs, ps, tspan, var_to_name, ctrls, observed,
             tgrad,
             jac,
-            ctrl_jac, Wfact, Wfact_t, name, systems, defaults, connector_type,
+            ctrl_jac, Wfact, Wfact_t, name, description, systems, defaults, connector_type,
             cevents, devents, parameter_dependencies, metadata = nothing, gui_metadata = nothing,
             complete = false, index_cache = nothing, parent = nothing, is_scalar_noise = false,
             is_dde = false,
@@ -168,7 +172,7 @@ struct SDESystem <: AbstractODESystem
         end
         new(tag, deqs, neqs, iv, dvs, ps, tspan, var_to_name, ctrls, observed, tgrad, jac,
             ctrl_jac,
-            Wfact, Wfact_t, name, systems, defaults, connector_type, cevents, devents,
+            Wfact, Wfact_t, name, description, systems, defaults, connector_type, cevents, devents,
             parameter_dependencies, metadata, gui_metadata, complete, index_cache, parent, is_scalar_noise,
             is_dde, isscheduled)
     end
@@ -183,6 +187,7 @@ function SDESystem(deqs::AbstractVector{<:Equation}, neqs::AbstractArray, iv, dv
         default_p = Dict(),
         defaults = _merge(Dict(default_u0), Dict(default_p)),
         name = nothing,
+        description = "",
         connector_type = nothing,
         checks = true,
         continuous_events = nothing,
@@ -234,7 +239,7 @@ function SDESystem(deqs::AbstractVector{<:Equation}, neqs::AbstractArray, iv, dv
     end
     SDESystem(Threads.atomic_add!(SYSTEM_COUNT, UInt(1)),
         deqs, neqs, iv′, dvs′, ps′, tspan, var_to_name, ctrl′, observed, tgrad, jac,
-        ctrl_jac, Wfact, Wfact_t, name, systems, defaults, connector_type,
+        ctrl_jac, Wfact, Wfact_t, name, description, systems, defaults, connector_type,
         cont_callbacks, disc_callbacks, parameter_dependencies, metadata, gui_metadata,
         complete, index_cache, parent, is_scalar_noise, is_dde; checks = checks)
 end
@@ -349,7 +354,7 @@ function stochastic_integral_transform(sys::SDESystem, correction_factor)
     end
 
     SDESystem(deqs, get_noiseeqs(sys), get_iv(sys), unknowns(sys), parameters(sys),
-        name = name, parameter_dependencies = parameter_dependencies(sys), checks = false)
+        name = name, description = get_description(sys), parameter_dependencies = parameter_dependencies(sys), checks = false)
 end
 
 """
@@ -457,7 +462,7 @@ function Girsanov_transform(sys::SDESystem, u; θ0 = 1.0)
     # return modified SDE System
     SDESystem(deqs, noiseeqs, get_iv(sys), unknown_vars, parameters(sys);
         defaults = Dict(θ => θ0), observed = [weight ~ θ / θ0],
-        name = name, parameter_dependencies = parameter_dependencies(sys),
+        name = name, description = get_description(sys), parameter_dependencies = parameter_dependencies(sys),
         checks = false)
 end
 
diff --git a/src/systems/discrete_system/discrete_system.jl b/src/systems/discrete_system/discrete_system.jl
index b09ecf5c4c..5e7ae46a08 100644
--- a/src/systems/discrete_system/discrete_system.jl
+++ b/src/systems/discrete_system/discrete_system.jl
@@ -42,6 +42,10 @@ struct DiscreteSystem <: AbstractTimeDependentSystem
     """
     name::Symbol
     """
+    A description of the system.
+    """
+    description::String
+    """
     The internal systems. These are required to have unique names.
     """
     systems::Vector{DiscreteSystem}
@@ -95,7 +99,7 @@ struct DiscreteSystem <: AbstractTimeDependentSystem
 
     function DiscreteSystem(tag, discreteEqs, iv, dvs, ps, tspan, var_to_name,
             observed,
-            name,
+            name, description,
             systems, defaults, preface, connector_type, parameter_dependencies = Equation[],
             metadata = nothing, gui_metadata = nothing,
             tearing_state = nothing, substitutions = nothing,
@@ -111,7 +115,7 @@ struct DiscreteSystem <: AbstractTimeDependentSystem
             u = __get_unit_type(dvs, ps, iv)
             check_units(u, discreteEqs)
         end
-        new(tag, discreteEqs, iv, dvs, ps, tspan, var_to_name, observed, name,
+        new(tag, discreteEqs, iv, dvs, ps, tspan, var_to_name, observed, name, description,
             systems,
             defaults,
             preface, connector_type, parameter_dependencies, metadata, gui_metadata,
@@ -128,6 +132,7 @@ function DiscreteSystem(eqs::AbstractVector{<:Equation}, iv, dvs, ps;
         systems = DiscreteSystem[],
         tspan = nothing,
         name = nothing,
+        description = "",
         default_u0 = Dict(),
         default_p = Dict(),
         defaults = _merge(Dict(default_u0), Dict(default_p)),
@@ -164,7 +169,7 @@ function DiscreteSystem(eqs::AbstractVector{<:Equation}, iv, dvs, ps;
         throw(ArgumentError("System names must be unique."))
     end
     DiscreteSystem(Threads.atomic_add!(SYSTEM_COUNT, UInt(1)),
-        eqs, iv′, dvs′, ps′, tspan, var_to_name, observed, name, systems,
+        eqs, iv′, dvs′, ps′, tspan, var_to_name, observed, name, description, systems,
         defaults, preface, connector_type, parameter_dependencies, metadata, gui_metadata, kwargs...)
 end
 
@@ -221,6 +226,7 @@ function flatten(sys::DiscreteSystem, noeqs = false)
             observed = observed(sys),
             defaults = defaults(sys),
             name = nameof(sys),
+            description = get_description(sys),
             checks = false)
     end
 end
diff --git a/src/systems/jumps/jumpsystem.jl b/src/systems/jumps/jumpsystem.jl
index a714d4b364..98253569d2 100644
--- a/src/systems/jumps/jumpsystem.jl
+++ b/src/systems/jumps/jumpsystem.jl
@@ -74,6 +74,8 @@ struct JumpSystem{U <: ArrayPartition} <: AbstractTimeDependentSystem
     observed::Vector{Equation}
     """The name of the system."""
     name::Symbol
+    """A description of the system."""
+    description::String
     """The internal systems. These are required to have unique names."""
     systems::Vector{JumpSystem}
     """
@@ -116,7 +118,7 @@ struct JumpSystem{U <: ArrayPartition} <: AbstractTimeDependentSystem
     index_cache::Union{Nothing, IndexCache}
     isscheduled::Bool
 
-    function JumpSystem{U}(tag, ap::U, iv, unknowns, ps, var_to_name, observed, name,
+    function JumpSystem{U}(tag, ap::U, iv, unknowns, ps, var_to_name, observed, name, description,
             systems,
             defaults, connector_type, devents, parameter_dependencies,
             metadata = nothing, gui_metadata = nothing,
@@ -131,7 +133,7 @@ struct JumpSystem{U <: ArrayPartition} <: AbstractTimeDependentSystem
             u = __get_unit_type(unknowns, ps, iv)
             check_units(u, ap, iv)
         end
-        new{U}(tag, ap, iv, unknowns, ps, var_to_name, observed, name, systems, defaults,
+        new{U}(tag, ap, iv, unknowns, ps, var_to_name, observed, name, description, systems, defaults,
             connector_type, devents, parameter_dependencies, metadata, gui_metadata,
             complete, index_cache, isscheduled)
     end
@@ -147,6 +149,7 @@ function JumpSystem(eqs, iv, unknowns, ps;
         default_p = Dict(),
         defaults = _merge(Dict(default_u0), Dict(default_p)),
         name = nothing,
+        description = "",
         connector_type = nothing,
         checks = true,
         continuous_events = nothing,
@@ -193,7 +196,7 @@ function JumpSystem(eqs, iv, unknowns, ps;
     disc_callbacks = SymbolicDiscreteCallbacks(discrete_events)
     parameter_dependencies, ps = process_parameter_dependencies(parameter_dependencies, ps)
     JumpSystem{typeof(ap)}(Threads.atomic_add!(SYSTEM_COUNT, UInt(1)),
-        ap, value(iv), unknowns, ps, var_to_name, observed, name, systems,
+        ap, value(iv), unknowns, ps, var_to_name, observed, name, description, systems,
         defaults, connector_type, disc_callbacks, parameter_dependencies,
         metadata, gui_metadata, checks = checks)
 end
diff --git a/src/systems/nonlinear/nonlinearsystem.jl b/src/systems/nonlinear/nonlinearsystem.jl
index d9ad826a2c..07c73798f4 100644
--- a/src/systems/nonlinear/nonlinearsystem.jl
+++ b/src/systems/nonlinear/nonlinearsystem.jl
@@ -44,6 +44,10 @@ struct NonlinearSystem <: AbstractTimeIndependentSystem
     """
     name::Symbol
     """
+    A description of the system.
+    """
+    description::String
+    """
     The internal systems. These are required to have unique names.
     """
     systems::Vector{NonlinearSystem}
@@ -91,7 +95,7 @@ struct NonlinearSystem <: AbstractTimeIndependentSystem
     parent::Any
     isscheduled::Bool
 
-    function NonlinearSystem(tag, eqs, unknowns, ps, var_to_name, observed, jac, name,
+    function NonlinearSystem(tag, eqs, unknowns, ps, var_to_name, observed, jac, name, description,
             systems,
             defaults, connector_type, parameter_dependencies = Equation[], metadata = nothing,
             gui_metadata = nothing,
@@ -102,7 +106,7 @@ struct NonlinearSystem <: AbstractTimeIndependentSystem
             u = __get_unit_type(unknowns, ps)
             check_units(u, eqs)
         end
-        new(tag, eqs, unknowns, ps, var_to_name, observed, jac, name, systems, defaults,
+        new(tag, eqs, unknowns, ps, var_to_name, observed, jac, name, description, systems, defaults,
             connector_type, parameter_dependencies, metadata, gui_metadata, tearing_state,
             substitutions, complete, index_cache, parent, isscheduled)
     end
@@ -111,6 +115,7 @@ end
 function NonlinearSystem(eqs, unknowns, ps;
         observed = [],
         name = nothing,
+        description = "",
         default_u0 = Dict(),
         default_p = Dict(),
         defaults = _merge(Dict(default_u0), Dict(default_p)),
@@ -157,7 +162,7 @@ function NonlinearSystem(eqs, unknowns, ps;
     parameter_dependencies, ps = process_parameter_dependencies(
         parameter_dependencies, ps)
     NonlinearSystem(Threads.atomic_add!(SYSTEM_COUNT, UInt(1)),
-        eqs, unknowns, ps, var_to_name, observed, jac, name, systems, defaults,
+        eqs, unknowns, ps, var_to_name, observed, jac, name, description, systems, defaults,
         connector_type, parameter_dependencies, metadata, gui_metadata, checks = checks)
 end
 
@@ -554,6 +559,7 @@ function flatten(sys::NonlinearSystem, noeqs = false)
             observed = observed(sys),
             defaults = defaults(sys),
             name = nameof(sys),
+            description = get_description(sys),
             checks = false)
     end
 end
diff --git a/src/systems/optimization/constraints_system.jl b/src/systems/optimization/constraints_system.jl
index f9176df3a2..054244e005 100644
--- a/src/systems/optimization/constraints_system.jl
+++ b/src/systems/optimization/constraints_system.jl
@@ -45,6 +45,10 @@ struct ConstraintsSystem <: AbstractTimeIndependentSystem
     """
     name::Symbol
     """
+    A description of the system.
+    """
+    description::String
+    """
     The internal systems. These are required to have unique names.
     """
     systems::Vector{ConstraintsSystem}
@@ -79,7 +83,7 @@ struct ConstraintsSystem <: AbstractTimeIndependentSystem
     index_cache::Union{Nothing, IndexCache}
 
     function ConstraintsSystem(tag, constraints, unknowns, ps, var_to_name, observed, jac,
-            name,
+            name, description,
             systems,
             defaults, connector_type, metadata = nothing,
             tearing_state = nothing, substitutions = nothing,
@@ -89,7 +93,7 @@ struct ConstraintsSystem <: AbstractTimeIndependentSystem
             u = __get_unit_type(unknowns, ps)
             check_units(u, constraints)
         end
-        new(tag, constraints, unknowns, ps, var_to_name, observed, jac, name, systems,
+        new(tag, constraints, unknowns, ps, var_to_name, observed, jac, name, description, systems,
             defaults,
             connector_type, metadata, tearing_state, substitutions, complete, index_cache)
     end
@@ -100,6 +104,7 @@ equations(sys::ConstraintsSystem) = constraints(sys) # needed for Base.show
 function ConstraintsSystem(constraints, unknowns, ps;
         observed = [],
         name = nothing,
+        description = "",
         default_u0 = Dict(),
         default_p = Dict(),
         defaults = _merge(Dict(default_u0), Dict(default_p)),
@@ -142,7 +147,7 @@ function ConstraintsSystem(constraints, unknowns, ps;
     isempty(observed) || collect_var_to_name!(var_to_name, (eq.lhs for eq in observed))
 
     ConstraintsSystem(Threads.atomic_add!(SYSTEM_COUNT, UInt(1)),
-        cstr, unknowns, ps, var_to_name, observed, jac, name, systems,
+        cstr, unknowns, ps, var_to_name, observed, jac, name, description, systems,
         defaults,
         connector_type, metadata, checks = checks)
 end
diff --git a/src/systems/optimization/optimizationsystem.jl b/src/systems/optimization/optimizationsystem.jl
index 22488e8bad..1f543dc8d1 100644
--- a/src/systems/optimization/optimizationsystem.jl
+++ b/src/systems/optimization/optimizationsystem.jl
@@ -37,6 +37,8 @@ struct OptimizationSystem <: AbstractOptimizationSystem
     constraints::Vector{Union{Equation, Inequality}}
     """The name of the system."""
     name::Symbol
+    """A description of the system."""
+    description::String
     """The internal systems. These are required to have unique names."""
     systems::Vector{OptimizationSystem}
     """
@@ -67,7 +69,7 @@ struct OptimizationSystem <: AbstractOptimizationSystem
     isscheduled::Bool
 
     function OptimizationSystem(tag, op, unknowns, ps, var_to_name, observed,
-            constraints, name, systems, defaults, metadata = nothing,
+            constraints, name, description, systems, defaults, metadata = nothing,
             gui_metadata = nothing, complete = false, index_cache = nothing, parent = nothing,
             isscheduled = false;
             checks::Union{Bool, Int} = true)
@@ -78,7 +80,7 @@ struct OptimizationSystem <: AbstractOptimizationSystem
             check_units(u, constraints)
         end
         new(tag, op, unknowns, ps, var_to_name, observed,
-            constraints, name, systems, defaults, metadata, gui_metadata, complete,
+            constraints, name, description, systems, defaults, metadata, gui_metadata, complete,
             index_cache, parent, isscheduled)
     end
 end
@@ -92,6 +94,7 @@ function OptimizationSystem(op, unknowns, ps;
         default_p = Dict(),
         defaults = _merge(Dict(default_u0), Dict(default_p)),
         name = nothing,
+        description = "",
         systems = OptimizationSystem[],
         checks = true,
         metadata = nothing,
@@ -125,7 +128,7 @@ function OptimizationSystem(op, unknowns, ps;
         op′, unknowns′, ps′, var_to_name,
         observed,
         constraints,
-        name, systems, defaults, metadata, gui_metadata;
+        name, description, systems, defaults, metadata, gui_metadata;
         checks = checks)
 end
 
diff --git a/src/systems/pde/pdesystem.jl b/src/systems/pde/pdesystem.jl
index 7aa3f29191..eac540e401 100644
--- a/src/systems/pde/pdesystem.jl
+++ b/src/systems/pde/pdesystem.jl
@@ -78,6 +78,10 @@ struct PDESystem <: ModelingToolkit.AbstractMultivariateSystem
     """
     name::Symbol
     """
+    A description of the system.
+    """
+    description::String
+    """
     Metadata for the system, to be used by downstream packages.
     """
     metadata::Any
@@ -96,6 +100,7 @@ struct PDESystem <: ModelingToolkit.AbstractMultivariateSystem
             gui_metadata = nothing,
             eval_module = @__MODULE__,
             checks::Union{Bool, Int} = true,
+            description = "",
             name)
         if checks == true || (checks & CheckUnits) > 0
             u = __get_unit_type(dvs, ivs, ps)
@@ -127,7 +132,7 @@ struct PDESystem <: ModelingToolkit.AbstractMultivariateSystem
         end
 
         new(eqs, bcs, domain, ivs, dvs, ps, defaults, connector_type, systems, analytic,
-            analytic_func, name, metadata, gui_metadata)
+            analytic_func, name, description, metadata, gui_metadata)
     end
 end