Merge remote-tracking branch 'origin' into implicit_discrete_system

merge master

Author: vyudu

.github/workflows/Downstream.yml

@@ -37,7 +37,6 @@ jobs:
           - {user: SciML, repo: MethodOfLines.jl, group: Interface}
           - {user: SciML, repo: MethodOfLines.jl, group: 2D_Diffusion}
           - {user: SciML, repo: MethodOfLines.jl, group: DAE}
-          - {user: ai4energy, repo: Ai4EComponentLib.jl, group: Downstream}
     steps:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v1

Project.toml

@@ -146,8 +146,8 @@ StaticArrays = "0.10, 0.11, 0.12, 1.0"
 StochasticDiffEq = "6.72.1"
 StochasticDelayDiffEq = "1.8.1"
 SymbolicIndexingInterface = "0.3.37"
-SymbolicUtils = "3.10.1"
-Symbolics = "6.25"
+SymbolicUtils = "3.14"
+Symbolics = "6.29"
 URIs = "1"
 UnPack = "0.1, 1.0"
 Unitful = "1.1"

docs/pages.jl

@@ -41,7 +41,8 @@ pages = [
         "systems/JumpSystem.md",
         "systems/NonlinearSystem.md",
         "systems/OptimizationSystem.md",
-        "systems/PDESystem.md"],
+        "systems/PDESystem.md",
+        "systems/DiscreteSystem.md"],
     "comparison.md",
     "internals.md"
 ]

docs/src/basics/Debugging.md

@@ -35,6 +35,39 @@ dsol = solve(dprob, Tsit5());
 Now we see that it crashed because `u1` decreased so much that it became negative and outside the domain of the `√` function.
 We could have figured that out ourselves, but it is not always so obvious for more complex models.
 
+Suppose we also want to validate that `u1 + u2 >= 2.0`. We can do this via the assertions functionality.
+
+```@example debug
+@mtkbuild sys = ODESystem(eqs, t; defaults, assertions = [(u1 + u2 >= 2.0) => "Oh no!"])
+```
+
+The assertions must be an iterable of pairs, where the first element is the symbolic condition and
+the second is a message to be logged when the condition fails. All assertions are added to the
+generated code and will cause the solver to reject steps that fail the assertions. For systems such
+as the above where the assertion is guaranteed to eventually fail, the solver will likely exit
+with a `dtmin` failure..
+
+```@example debug
+prob = ODEProblem(sys, [], (0.0, 10.0))
+sol = solve(prob, Tsit5())
+```
+
+We can use `debug_system` to log the failing assertions in each call to the RHS function.
+
+```@repl debug
+dsys = debug_system(sys; functions = []);
+dprob = ODEProblem(dsys, [], (0.0, 10.0));
+dsol = solve(dprob, Tsit5());
+```
+
+Note the logs containing the failed assertion and corresponding message. To temporarily disable
+logging in a system returned from `debug_system`, use `ModelingToolkit.ASSERTION_LOG_VARIABLE`.
+
+```@repl debug
+dprob[ModelingToolkit.ASSERTION_LOG_VARIABLE] = false;
+solve(drob, Tsit5());
+```
+
 ```@docs
 debug_system
 ```

docs/src/basics/MTKLanguage.md

@@ -23,6 +23,7 @@ equations.
 
 `@mtkmodel` definition contains begin blocks of
 
+  - `@description`: for describing the whole system with a human-readable string
   - `@components`: for listing sub-components of the system
   - `@constants`: for declaring constants
   - `@defaults`: for passing `defaults` to ODESystem
@@ -42,20 +43,23 @@ using ModelingToolkit
 using ModelingToolkit: t
 
 @mtkmodel ModelA begin
+    @description "A component with parameters `k` and `k_array`."
     @parameters begin
         k
         k_array[1:2]
     end
 end
 
 @mtkmodel ModelB begin
+    @description "A component with parameters `p1` and `p2`."
     @parameters begin
         p1 = 1.0, [description = "Parameter of ModelB"]
         p2 = 1.0, [description = "Parameter of ModelB"]
     end
 end
 
 @mtkmodel ModelC begin
+    @description "A bigger system that contains many more things."
     @icon "https://github.com/SciML/SciMLDocs/blob/main/docs/src/assets/logo.png"
     @constants begin
         c::Int = 1, [description = "Example constant."]
@@ -91,6 +95,10 @@ end
 end
 ```
 
+#### `@description`
+
+A documenting `String` that summarizes and explains what the model is.
+
 #### `@icon`
 
 An icon can be embedded in 3 ways:

docs/src/basics/Variable_metadata.md

@@ -54,6 +54,11 @@ using ModelingToolkit: t_nounits as t, D_nounits as D
 
 @variables i(t) [connect = Flow]
 @variables k(t) [connect = Stream]
+hasconnect(i)
+```
+
+```@example connect
+getconnect(k)
 ```
 
 ## Input or output
@@ -177,8 +182,45 @@ A variable can be marked `irreducible` to prevent it from being moved to an
 `observed` state. This forces the variable to be computed during solving so that
 it can be accessed in [callbacks](@ref events)
 
-```julia
-@variable important_value [irreducible = true]
+```@example metadata
+@variables important_value [irreducible = true]
+isirreducible(important_value)
+```
+
+## State Priority
+
+When a model is structurally simplified, the algorithm will try to ensure that the variables with higher state priority become states of the system. A variable's state priority is a number set using the `state_priority` metadata.
+
+```@example metadata
+@variables important_dof [state_priority = 10] unimportant_dof [state_priority = -2]
+state_priority(important_dof)
+```
+
+## Units
+
+Units for variables can be designated using symbolic metadata. For more information, please see the [model validation and units](@ref units) section of the docs. Note that `getunit` is not equivalent to `get_unit` - the former is a metadata getter for individual variables (and is provided so the same interface function for `unit` exists like other metadata), while the latter is used to handle more general symbolic expressions.
+
+```@example metadata
+@variables speed [unit = u"m/s"]
+hasunit(speed)
+```
+
+```@example metadata
+getunit(speed)
+```
+
+## Miscellaneous metadata
+
+User-defined metadata can be added using the `misc` metadata. This can be queried
+using the `hasmisc` and `getmisc` functions.
+
+```@example metadata
+@variables u [misc = :conserved_parameter] y [misc = [2, 4, 6]]
+hasmisc(u)
+```
+
+```@example metadata
+getmisc(y)
 ```
 
 ## Additional functions

docs/src/systems/DiscreteSystem.md

@@ -0,0 +1,28 @@
+# DiscreteSystem
+
+## System Constructors
+
+```@docs
+DiscreteSystem
+```
+
+## Composition and Accessor Functions
+
+  - `get_eqs(sys)` or `equations(sys)`: The equations that define the discrete system.
+  - `get_unknowns(sys)` or `unknowns(sys)`: The set of unknowns in the discrete system.
+  - `get_ps(sys)` or `parameters(sys)`: The parameters of the discrete system.
+  - `get_iv(sys)`: The independent variable of the discrete system
+  - `discrete_events(sys)`: The set of discrete events in the discrete system.
+
+## Transformations
+
+```@docs; canonical=false
+structural_simplify
+```
+
+## Problem Constructors
+
+```@docs; canonical=false
+DiscreteProblem(sys::DiscreteSystem, u0map, tspan)
+DiscreteFunction(sys::DiscreteSystem, args...)
+```

docs/src/tutorials/acausal_components.md

@@ -84,6 +84,7 @@ end
 end
 
 @mtkmodel RCModel begin
+    @description "A circuit with a constant voltage source, resistor and capacitor connected in series."
     @components begin
         resistor = Resistor(R = 1.0)
         capacitor = Capacitor(C = 1.0)
@@ -251,6 +252,7 @@ make all of our parameter values 1.0. As `resistor`, `capacitor`, `source` lists
 
 ```@example acausal
 @mtkmodel RCModel begin
+    @description "A circuit with a constant voltage source, resistor and capacitor connected in series."
     @components begin
         resistor = Resistor(R = 1.0)
         capacitor = Capacitor(C = 1.0)

docs/src/tutorials/initialization.md

@@ -14,8 +14,10 @@ principles of initialization of DAE systems. Take a DAE written in semi-explicit
 form:
 
 ```math
-x' = f(x,y,t)\\
-0 = g(x,y,t)
+\begin{aligned}
+    x^\prime &= f(x,y,t) \\
+    0 &= g(x,y,t)
+\end{aligned}
 ```
 
 where ``x`` are the differential variables and ``y`` are the algebraic variables.

src/ModelingToolkit.jl

@@ -151,6 +151,7 @@ include("systems/connectors.jl")
 include("systems/analysis_points.jl")
 include("systems/imperative_affect.jl")
 include("systems/callbacks.jl")
+include("systems/codegen_utils.jl")
 include("systems/problem_utils.jl")
 
 include("systems/nonlinear/nonlinearsystem.jl")
@@ -249,7 +250,9 @@ export initial_state, transition, activeState, entry, ticksInState, timeInState
 export @component, @mtkmodel, @mtkbuild
 export isinput, isoutput, getbounds, hasbounds, getguess, hasguess, isdisturbance,
        istunable, getdist, hasdist,
-       tunable_parameters, isirreducible, getdescription, hasdescription
+       tunable_parameters, isirreducible, getdescription, hasdescription,
+       hasunit, getunit, hasconnect, getconnect,
+       hasmisc, getmisc, state_priority
 export ode_order_lowering, dae_order_lowering, liouville_transform
 export PDESystem
 export Differential, expand_derivatives, @derivatives