Merge remote-tracking branch 'origin' into add-metadata-getters

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

.github/workflows/Tests.yml

@@ -38,6 +38,7 @@ jobs:
           - Extensions
           - Downstream
           - RegressionI
+          - FMI
     uses: "SciML/.github/.github/workflows/tests.yml@v1"
     with:
       julia-version: "${{ matrix.version }}"

Project.toml

@@ -1,7 +1,7 @@
 name = "ModelingToolkit"
 uuid = "961ee093-0014-501f-94e3-6117800e7a78"
 authors = ["Yingbo Ma <[email protected]>", "Chris Rackauckas <[email protected]> and contributors"]
-version = "9.60.0"
+version = "9.62.0"
 
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
@@ -64,6 +64,7 @@ Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 BifurcationKit = "0f109fa4-8a5d-4b75-95aa-f515264e7665"
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
 DeepDiffs = "ab62b9b5-e342-54a8-a765-a90f495de1a6"
+FMI = "14a09403-18e3-468f-ad8a-74f8dda2d9ac"
 HomotopyContinuation = "f213a82b-91d6-5c5d-acf7-10f1c761b327"
 InfiniteOpt = "20393b10-9daf-11e9-18c9-8db751c92c57"
 LabelledArrays = "2ee39098-c373-598a-b85f-a56591580800"
@@ -72,6 +73,7 @@ LabelledArrays = "2ee39098-c373-598a-b85f-a56591580800"
 MTKBifurcationKitExt = "BifurcationKit"
 MTKChainRulesCoreExt = "ChainRulesCore"
 MTKDeepDiffsExt = "DeepDiffs"
+MTKFMIExt = "FMI"
 MTKHomotopyContinuationExt = "HomotopyContinuation"
 MTKInfiniteOptExt = "InfiniteOpt"
 MTKLabelledArraysExt = "LabelledArrays"
@@ -106,6 +108,7 @@ FindFirstFunctions = "1"
 ForwardDiff = "0.10.3"
 FunctionWrappers = "1.1"
 FunctionWrappersWrappers = "0.1"
+FMI = "0.14"
 Graphs = "1.5.2"
 HomotopyContinuation = "2.11"
 InfiniteOpt = "0.5"
@@ -123,7 +126,7 @@ NonlinearSolve = "4.3"
 OffsetArrays = "1"
 OrderedCollections = "1"
 OrdinaryDiffEq = "6.82.0"
-OrdinaryDiffEqCore = "1.13.0"
+OrdinaryDiffEqCore = "1.15.0"
 OrdinaryDiffEqDefault = "1.2"
 OrdinaryDiffEqNonlinearSolve = "1.3.0"
 PrecompileTools = "1"
@@ -132,7 +135,7 @@ RecursiveArrayTools = "3.26"
 Reexport = "0.2, 1"
 RuntimeGeneratedFunctions = "0.5.9"
 SCCNonlinearSolve = "1.0.0"
-SciMLBase = "2.68.1"
+SciMLBase = "2.72.1"
 SciMLStructures = "1.0"
 Serialization = "1"
 Setfield = "0.7, 0.8, 1"
@@ -142,9 +145,9 @@ SpecialFunctions = "0.7, 0.8, 0.9, 0.10, 1.0, 2"
 StaticArrays = "0.10, 0.11, 0.12, 1.0"
 StochasticDiffEq = "6.72.1"
 StochasticDelayDiffEq = "1.8.1"
-SymbolicIndexingInterface = "0.3.36"
-SymbolicUtils = "3.10"
-Symbolics = "6.22.1"
+SymbolicIndexingInterface = "0.3.37"
+SymbolicUtils = "3.10.1"
+Symbolics = "6.27"
 URIs = "1"
 UnPack = "0.1, 1.0"
 Unitful = "1.1"

docs/pages.jl

@@ -32,6 +32,7 @@ pages = [
         "basics/InputOutput.md",
         "basics/MTKLanguage.md",
         "basics/Validation.md",
+        "basics/Debugging.md",
         "basics/DependencyGraphs.md",
         "basics/Precompilation.md",
         "basics/FAQ.md"],

docs/src/basics/Debugging.md

@@ -0,0 +1,40 @@
+# Debugging
+
+Every (mortal) modeler writes models that contain mistakes or are susceptible to numerical errors in their hunt for the perfect model.
+Debugging such errors is part of the modeling process, and ModelingToolkit includes some functionality that helps with this.
+
+For example, consider an ODE model with "dangerous" functions (here `√`):
+
+```@example debug
+using ModelingToolkit, OrdinaryDiffEq
+using ModelingToolkit: t_nounits as t, D_nounits as D
+
+@variables u1(t) u2(t) u3(t)
+eqs = [D(u1) ~ -√(u1), D(u2) ~ -√(u2), D(u3) ~ -√(u3)]
+defaults = [u1 => 1.0, u2 => 2.0, u3 => 3.0]
+@named sys = ODESystem(eqs, t; defaults)
+sys = structural_simplify(sys)
+```
+
+This problem causes the ODE solver to crash:
+
+```@repl debug
+prob = ODEProblem(sys, [], (0.0, 10.0), []);
+sol = solve(prob, Tsit5());
+```
+
+This suggests *that* something went wrong, but not exactly *what* went wrong and *where* it did.
+In such situations, the `debug_system` function is helpful:
+
+```@repl debug
+dsys = debug_system(sys; functions = [sqrt]);
+dprob = ODEProblem(dsys, [], (0.0, 10.0), []);
+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.
+
+```@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/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)