Add documentation page for debugging

docs/pages.jl

@@ -31,6 +31,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,43 @@
+# 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 `√`):
+```julia
+using ModelingToolkit, OrdinaryDiffEq
+using ModelingToolkit: t_nounits as t, D_nounits as D
+
+@variables u1(t) u2(t) u3(t)
+@named sys = ODESystem([
+    D(u1) ~ -√(u1)
+    D(u2) ~ -√(u2)
+    D(u3) ~ -√(u3)
+], t; defaults = [
+    u1 => 1.0
+    u2 => 2.0
+    u3 => 3.0
+])
+sys = structural_simplify(sys)
+```
+
+This problem causes the ODE solver to crash:
+```julia
+prob = ODEProblem(sys, [], (0.0, 10.0), [])
+sol = solve(prob, Tsit5())
+```
+
+This error message suggests *that* something went wrong, but not exactly *what* went wrong and *where* it did.
+In such situations, the `debug_system` function is helpful:
+```julia
+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
+```