Merge pull request #3658 from AayushSabharwal/as/docs

docs: overhaul documentation for v10

Author: AayushSabharwal

Project.toml

@@ -51,6 +51,7 @@ Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 RuntimeGeneratedFunctions = "7e49a35a-f44a-4d26-94aa-eba1b4ca6b47"
 SCCNonlinearSolve = "9dfe8606-65a1-4bb3-9748-cb89d1561431"
 SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
+SciMLPublic = "431bcebd-1456-4ced-9d72-93c2757fff0b"
 SciMLStructures = "53ae85a6-f571-4167-b2af-e1d143709226"
 Serialization = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
 Setfield = "efcf1570-3423-57d1-acb7-fd33fddbac46"
@@ -145,6 +146,7 @@ Reexport = "0.2, 1"
 RuntimeGeneratedFunctions = "0.5.9"
 SCCNonlinearSolve = "1.0.0"
 SciMLBase = "2.91.1"
+SciMLPublic = "1.0.0"
 SciMLStructures = "1.7"
 Serialization = "1"
 Setfield = "0.7, 0.8, 1"
@@ -156,7 +158,7 @@ StochasticDelayDiffEq = "1.10"
 StochasticDiffEq = "6.72.1"
 SymbolicIndexingInterface = "0.3.39"
 SymbolicUtils = "3.26.1"
-Symbolics = "6.37"
+Symbolics = "6.40"
 URIs = "1"
 UnPack = "0.1, 1.0"
 Unitful = "1.1"

demo.jl

@@ -0,0 +1,107 @@
+macro mtkcompile(ex...)
+    quote
+        @mtkbuild $(ex...)
+    end
+end
+
+function mtkcompile(args...; kwargs...)
+    structural_simplify(args...; kwargs...)
+end
+
+#################################
+
+using ModelingToolkit, OrdinaryDiffEq, StochasticDiffEq
+using ModelingToolkit: t_nounits as t, D_nounits as D
+
+## ODEs
+
+@parameters g
+@variables x(t) y(t) λ(t)
+eqs = [D(D(x)) ~ λ * x
+       D(D(y)) ~ λ * y - g
+       x^2 + y^2 ~ 1]
+@mtkbuild pend = System(eqs, t)
+prob = ODEProblem(pend, [x => -1, y => 0], (0.0, 10.0), [g => 1], guesses = [λ => 1])
+
+sol = solve(prob, FBDF())
+
+## SDEs and unified `System`
+
+@variables x(t) y(t) z(t)
+@parameters σ ρ β
+@brownian a
+
+eqs = [
+    D(x) ~ σ * (y - x) + 0.1x * a,
+    D(y) ~ x * (ρ - z) - y + 0.1y * a,
+    D(z) ~ x * y - β * z + 0.1z * a
+]
+
+@mtkbuild sys1 = System(eqs, t)
+
+eqs = [
+    D(x) ~ σ * (y - x),
+    D(y) ~ x * (ρ - z) - y,
+    D(z) ~ x * y - β * z
+]
+
+noiseeqs = [0.1*x;
+            0.1*y;
+            0.1*z;;]
+
+@mtkbuild sys2 = SDESystem(eqs, noiseeqs, t)
+
+u0 = [
+    x => 1.0,
+    y => 0.0,
+    z => 0.0]
+
+p = [σ => 28.0,
+    ρ => 10.0,
+    β => 8 / 3]
+
+sdeprob = SDEProblem(sys1, u0, (0.0, 10.0), p)
+sdesol = solve(sdeprob, ImplicitEM())
+
+odeprob = ODEProblem(sys1, u0, (0.0, 10.0), p) # error!
+odeprob = ODEProblem(sys1, u0, (0.0, 10.0), p; check_compatibility = false)
+
+@variables x y z
+@parameters σ ρ β
+
+# Define a nonlinear system
+eqs = [0 ~ σ * (y - x),
+    y ~ x * (ρ - z),
+    β * z ~ x * y]
+@mtkbuild sys = System(eqs)
+
+## ImplicitDiscrete Affects
+
+@parameters g
+@variables x(t) y(t) λ(t)
+eqs = [D(D(x)) ~ λ * x
+       D(D(y)) ~ λ * y - g
+       x^2 + y^2 ~ 1]
+c_evt = [t ~ 5.0] => [x ~ Pre(x) + 0.1]
+@mtkbuild pend = System(eqs, t, continuous_events = c_evt)
+prob = ODEProblem(pend, [x => -1, y => 0], (0.0, 10.0), [g => 1], guesses = [λ => 1])
+
+sol = solve(prob, FBDF())
+
+## `@named` and `ParentScope`
+
+function SysA(; name, var1)
+    @variables x(t)
+    return System([D(x) ~ var1], t; name)
+end
+function SysB(; name, var1)
+    @variables x(t)
+    @named subsys = SysA(; var1)
+    return System([D(x) ~ x], t; systems = [subsys], name)
+end
+function SysC(; name)
+    @variables x(t)
+    @named subsys = SysB(; var1 = x)
+    return System([D(x) ~ x], t; systems = [subsys], name)
+end
+@mtkbuild sys = SysC()

docs/Project.toml

@@ -17,6 +17,7 @@ ModelingToolkitStandardLibrary = "16a59e39-deab-5bd0-87e4-056b12336739"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
 Optim = "429524aa-4258-5aef-a3af-852621145aeb"
 Optimization = "7f7a1694-90dd-40f0-9382-eb1efda571ba"
+OptimizationBase = "bca83a33-5cc9-4baa-983d-23429ab6bcbb"
 OptimizationOptimJL = "36348300-93cb-4f02-beb5-3c3902f8871e"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
@@ -29,6 +30,10 @@ SymbolicUtils = "d1185830-fcd6-423d-90d6-eec64667417b"
 Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 
+[sources]
+ModelingToolkitStandardLibrary = {rev = "mtk-v10", url = "https://github.com/SciML/ModelingToolkitStandardLibrary.jl/"}
+OptimizationBase = {rev = "as/mtk-v10", url = "https://github.com/AayushSabharwal/OptimizationBase.jl"}
+
 [compat]
 Attractors = "1.24"
 BenchmarkTools = "1.3"

docs/pages.jl

@@ -27,9 +27,13 @@ pages = [
         "Advanced Examples" => Any["examples/tearing_parallelism.md",
             "examples/sparse_jacobians.md",
             "examples/perturbation.md"]],
-    "Basics" => Any["basics/AbstractSystem.md",
-        "basics/ContextualVariables.md",
-        "basics/Variable_metadata.md",
+    "API" => Any["API/System.md",
+        "API/variables.md",
+        "API/model_building.md",
+        "API/problems.md",
+        "API/codegen.md",
+        "API/PDESystem.md"],
+    "Basics" => Any[
         "basics/Composition.md",
         "basics/Events.md",
         "basics/Linearization.md",
@@ -40,14 +44,6 @@ pages = [
         "basics/DependencyGraphs.md",
         "basics/Precompilation.md",
         "basics/FAQ.md"],
-    "System Types" => Any["systems/ODESystem.md",
-        "systems/SDESystem.md",
-        "systems/JumpSystem.md",
-        "systems/NonlinearSystem.md",
-        "systems/OptimizationSystem.md",
-        "systems/PDESystem.md",
-        "systems/DiscreteSystem.md",
-        "systems/ImplicitDiscreteSystem.md"],
     "comparison.md",
     "internals.md"
 ]

docs/src/systems/PDESystem.md renamed to docs/src/API/PDESystem.md

@@ -0,0 +1,174 @@
+# [The `System` type](@id System_type)
+
+ModelingToolkit.jl uses `System` to symbolically represent all types of numerical problems.
+Users create `System`s representing the problem they want to solve and `mtkcompile` transforms
+them into a format ModelingToolkit.jl can generate code for (alongside performing other
+optimizations).
+
+```@docs
+System
+```
+
+## Utility constructors
+
+Several utility constructors also exist to easily construct alternative system formulations.
+
+```@docs
+NonlinearSystem
+SDESystem
+JumpSystem
+OptimizationSystem
+```
+
+## Accessor functions
+
+Several accessor functions exist to query systems for the information they contain. In general,
+for every field `x` there exists a `has_x` function which checks if the system contains the
+field and a `get_x` function for obtaining the value in the field. Note that fields of a system
+cannot be accessed via `getproperty` - that is reserved for accessing variables, subsystems
+or analysis points of the hierarchical system.
+
+```@docs
+ModelingToolkit.has_eqs
+ModelingToolkit.get_eqs
+equations
+equations_toplevel
+full_equations
+ModelingToolkit.has_noise_eqs
+ModelingToolkit.get_noise_eqs
+ModelingToolkit.has_jumps
+ModelingToolkit.get_jumps
+jumps
+ModelingToolkit.has_constraints
+ModelingToolkit.get_constraints
+constraints
+ModelingToolkit.has_costs
+ModelingToolkit.get_costs
+costs
+ModelingToolkit.has_consolidate
+ModelingToolkit.get_consolidate
+ModelingToolkit.has_unknowns
+ModelingToolkit.get_unknowns
+unknowns
+unknowns_toplevel
+ModelingToolkit.has_ps
+ModelingToolkit.get_ps
+parameters
+parameters_toplevel
+tunable_parameters
+ModelingToolkit.has_brownians
+ModelingToolkit.get_brownians
+brownians
+ModelingToolkit.has_iv
+ModelingToolkit.get_iv
+ModelingToolkit.has_observed
+ModelingToolkit.get_observed
+observed
+observables
+ModelingToolkit.has_name
+ModelingToolkit.get_name
+nameof
+ModelingToolkit.has_description
+ModelingToolkit.get_description
+ModelingToolkit.description
+ModelingToolkit.has_defaults
+ModelingToolkit.get_defaults
+defaults
+ModelingToolkit.has_guesses
+ModelingToolkit.get_guesses
+guesses
+ModelingToolkit.has_initialization_eqs
+ModelingToolkit.get_initialization_eqs
+initialization_equations
+ModelingToolkit.has_continuous_events
+ModelingToolkit.get_continuous_events
+continuous_events
+continuous_events_toplevel
+ModelingToolkit.has_discrete_events
+ModelingToolkit.get_discrete_events
+discrete_events_toplevel
+ModelingToolkit.has_assertions
+ModelingToolkit.get_assertions
+assertions
+ModelingToolkit.has_metadata
+ModelingToolkit.get_metadata
+SymbolicUtils.getmetadata(::ModelingToolkit.AbstractSystem, ::DataType, ::Any)
+SymbolicUtils.setmetadata(::ModelingToolkit.AbstractSystem, ::DataType, ::Any)
+ModelingToolkit.has_is_dde
+ModelingToolkit.get_is_dde
+ModelingToolkit.is_dde
+ModelingToolkit.has_tstops
+ModelingToolkit.get_tstops
+ModelingToolkit.symbolic_tstops
+ModelingToolkit.has_tearing_state
+ModelingToolkit.get_tearing_state
+ModelingToolkit.does_namespacing
+toggle_namespacing
+ModelingToolkit.iscomplete
+ModelingToolkit.has_preface
+ModelingToolkit.get_preface
+ModelingToolkit.preface
+ModelingToolkit.has_parent
+ModelingToolkit.get_parent
+ModelingToolkit.has_initializesystem
+ModelingToolkit.get_initializesystem
+ModelingToolkit.is_initializesystem
+```
+
+## `getproperty` syntax
+
+ModelingToolkit allows obtaining in a system using `getproperty`. For a system `sys` with a
+subcomponent `inner` containing variable `var`, `sys.inner.var` will obtain the appropriately
+namespaced version of `var`. Note that this can also be used to access subsystems (`sys.inner`)
+or analysis points.
+
+!!! note
+    
+    By default, top-level systems not marked as `complete` will apply their namespace. Systems
+    marked as `complete` will not do this namespacing. This namespacing behavior can be toggled
+    independently of whether the system is completed using [`toggle_namespacing`](@ref) and the
+    current namespacing behavior can be queried via [`ModelingToolkit.does_namespacing`](@ref).
+
+```@docs
+Base.getproperty(::ModelingToolkit.AbstractSystem, ::Symbol)
+```
+
+## Functions for querying system equations
+
+```@docs
+has_diff_eqs
+has_alg_eqs
+get_diff_eqs
+get_alg_eqs
+has_diff_equations
+has_alg_equations
+diff_equations
+alg_equations
+is_alg_equation
+is_diff_equation
+```
+
+## String parsing
+
+ModelingToolkit can parse system variables from strings.
+
+```@docs
+ModelingToolkit.parse_variable
+```
+
+## Dumping system data
+
+```@docs
+ModelingToolkit.dump_unknowns
+ModelingToolkit.dump_parameters
+```
+
+```@docs; canonical = false
+ModelingToolkit.dump_variable_metadata
+```
+
+## Debugging utilities
+
+```@docs
+debug_system
+```