Merge pull request #1333 from baggepinnen/devdocs

Add some documentation of the internals

Author: ChrisRackauckas

docs/src/internals.md

@@ -16,3 +16,18 @@ plotting their output, these relationships are stored and are then used to
 generate the `observed` equation found in the `SciMLFunction` interface, so that
 `sol[x]` lazily reconstructs the observed variable when necessary. In this sense,
 there is an equivalence between observables and the variable elimination system.
+
+The procedure for variable elimination inside [`structural_simplify`](@ref) is
+1. [`ModelingToolkit.initialize_system_structure`](@ref).
+2. [`ModelingToolkit.alias_elimination`](@ref). This step moves equations into `observed(sys)`.
+3. [`ModelingToolkit.dae_index_lowering`](@ref) by means of [`pantelides!`](@ref) (if the system is an [`ODESystem`](@ref)).
+4. [`ModelingToolkit.tearing`](@ref).
+
+## Preparing a system for simulation
+Before a simulation or optimization can be performed, the symbolic equations stored in an [`AbstractSystem`](@ref) must be converted into executable code. This step is typically occurs after the simplification explained above, and is performed when an instance of a [`AbsSciMLBase.SciMLProblem`](@ref), such as a [`ODEProblem`](@ref), is constructed.
+The call chain typically looks like this, with the function names in the case of an `ODESystem` indicated in parenthesis
+1. Problem constructor ([`ODEProblem`](@ref))
+2. Build an `DEFunction` ([`process_DEProblem`](@ref) -> [`ODEFunction`](@ref)
+3. Write actual executable code ([`generate_function`](@ref))
+
+Apart from [`generate_function`](@ref), which generates the dynamics function, `ODEFunction` also builds functions for observed equations (`build_explicit_observed_function`) and jacobians (`generate_jacobian`) etc. These are all stored in the `ODEFunction`.

docs/src/mtkitize_tutorials/modelingtoolkitize_index_reduction.md

@@ -29,7 +29,7 @@ p = [9.8, 1]
 tspan = (0, 10.0)
 pendulum_prob = ODEProblem(pendulum_fun!, u0, tspan, p)
 traced_sys = modelingtoolkitize(pendulum_prob)
-pendulum_sys = structural_simplify(dae_index_lowering(traced_sys))
+pendulum_sys = structural_simplify(traced_sys)
 prob = ODAEProblem(pendulum_sys, Pair[], tspan)
 sol = solve(prob, Tsit5(),abstol=1e-8,reltol=1e-8)
 plot(sol, vars=states(traced_sys))

src/structural_transformation/codegen.jl

@@ -346,6 +346,19 @@ struct ODAEProblem{iip}
 end
 
 ODAEProblem(args...; kw...) = ODAEProblem{true}(args...; kw...)
+
+"""
+    ODAEProblem{iip}(sys, u0map, tspan, parammap = DiffEqBase.NullParameters(); kw...)
+
+This constructor acts similar to the one for [`ODEProblem`](@ref) with the following changes:
+`ODESystem`s can sometimes be further reduced if `structural_simplify` has
+already been applied to them. This is done this constructor.
+In these cases, the constructor uses the knowledge of the strongly connected
+components calculated during the process of simplification as the basis for
+building pre-simplified nonlinear systems in the implicit solving.
+In summary: these problems are structurally modified, but could be
+more efficient and more stable. Note, the returned object is still of type [`ODEProblem`](@ref).
+"""
 function ODAEProblem{iip}(
                           sys,
                           u0map,

src/structural_transformation/pantelides.jl

@@ -141,10 +141,11 @@ function pantelides!(sys::ODESystem; maxiters = 8000)
 end
 
 """
-    dae_index_lowering(sys::ODESystem) -> ODESystem
+    dae_index_lowering(sys::ODESystem; kwargs...) -> ODESystem
 
 Perform the Pantelides algorithm to transform a higher index DAE to an index 1
-DAE.
+DAE. `kwargs` are forwarded to [`pantelides!`](@ref). End users are encouraged to call [`structural_simplify`](@ref)
+instead, which calls this function internally.
 """
 function dae_index_lowering(sys::ODESystem; kwargs...)
     s = get_structure(sys)

src/structural_transformation/tearing.jl

@@ -1,7 +1,8 @@
 """
     tear_graph(sys) -> sys
 
-Tear the bipartite graph in a system.
+Tear the bipartite graph in a system. End users are encouraged to call [`structural_simplify`](@ref)
+instead, which calls this function internally.
 """
 function tear_graph(sys)
     find_solvables!(sys)
@@ -220,6 +221,7 @@ end
     tearing(sys; simplify=false)
 
 Tear the nonlinear equations in system. When `simplify=true`, we simplify the
-new residual residual equations after tearing.
+new residual residual equations after tearing. End users are encouraged to call [`structural_simplify`](@ref)
+instead, which calls this function internally.
 """
 tearing(sys; simplify=false) = tearing_reassemble(tear_graph(algebraic_equations_scc(sys)); simplify=simplify)