Add a bunch more documentation stuff

Finishes #806

Author: ChrisRackauckas

docs/make.jl

@@ -22,14 +22,16 @@ makedocs(
         ],
         "ModelingToolkitize Tutorials" => Any[
             "mtkitize_tutorials/modelingtoolkitize.md",
-            "mtkitize_tutorials/modelingtoolkitize_index_reduction.md"
+            "mtkitize_tutorials/modelingtoolkitize_index_reduction.md",
+            #"mtkitize_tutorials/sparse_jacobians",
         ],
         "Basics" => Any[
             "basics/AbstractSystem.md",
             "basics/ContextualVariables.md",
             "basics/Composition.md",
             "basics/Validation.md",
-            "basics/DependencyGraphs.md"
+            "basics/DependencyGraphs.md",
+            "basics/FAQ.md"
         ],
         "System Types" => Any[
             "systems/ODESystem.md",

docs/src/basics/AbstractSystem.md

@@ -71,6 +71,12 @@ another `AbstractSystem`. These are passes, like optimizations (e.g., Block-Lowe
 Triangle transformations), or changes to the representation, which allow for
 alternative numerical methods to be utilized on the model (e.g., DAE index reduction).
 
+## Analyses
+
+Analyses are functions on a system which return information about the corresponding
+properties, like whether its parameters are structurally identifiable, or whether
+it's linear.
+
 ## Function Calculation and Generation
 
 The calculation and generation functions allow for calculating additional
@@ -112,3 +118,21 @@ array would normally be provided, such as `u0` the initial condition of an
 `ODEProblem`, it is instead replaced with a variable map, i.e., an array of
 pairs `var=>value`, which allows the user to designate the values without having
 to know the order that ModelingToolkit is internally using.
+
+For the value maps, the parameters are allowed to be functions of each other,
+and value maps of states can be functions of the parameters, i.e. you can do:
+
+```
+u0 = [
+  lorenz1.x => 2.0
+  lorenz2.x => lorenz1.x * lorenz1.p
+]
+```
+
+## Default Value Handling
+
+The `AbstractSystem` types allow for specifying default values, for example
+`default_p` inside of them. At problem construction time, these values are merged
+into the value maps, where for any repeats the value maps override the default.
+In addition, defaults of a higher level in the system override the defaults of
+a lower level in the system. 

docs/src/basics/FAQ.md

@@ -0,0 +1,23 @@
+# Frequently Asked Questions
+
+## Getting the index for a symbol
+
+Since **ordering of symbols is not guaranteed after symbolic transformations**,
+one should normally refer to values by their name. For example, `sol[lorenz.x]`
+from the solution. But what if you need to get the index? The following helper
+function will do the trick:
+
+```julia
+indexof(sym,syms) = findfirst(isequal(sym),syms)
+indexof(σ,parameters(sys))
+```
+
+## Transforming value maps to arrays
+
+ModelingToolkit.jl allows (and recommends) input maps like `[x => 2.0, y => 3.0]`
+because symbol ordering is not guaranteed. However, what if you want to get the
+lowered array? You can use the internal function `varmap_to_vars`. For example:
+
+```julia
+pnew = varmap_to_vars([β=>3.0, c=>10.0, γ=>2.0],parameters(sys))
+```

docs/src/mtkitize_tutorials/modelingtoolkitize.md

@@ -1,4 +1,4 @@
-# Symbolic Extensions to ODEProblem via Modelingtoolkitize
+# Automatically Accelerating ODEProblem Code
 
 For some `DEProblem` types, automatic tracing functionality is already included
 via the `modelingtoolkitize` function. Take, for example, the Robertson ODE

docs/src/mtkitize_tutorials/modelingtoolkitize_index_reduction.md

@@ -1,4 +1,4 @@
-# Automated Index Reduction of DAEs via ModelingToolkitize
+# Automated Index Reduction of DAEs
 
 In many cases one may accidentally write down a DAE that is not easily solvable
 by numerical methods. In this tutorial we will walk through an example of a

docs/src/mtkitize_tutorials/sparse_jacobians.md

@@ -0,0 +1,78 @@
+# Automated Sparse Analytical Jacobians
+
+In many cases where you have large stiff differential equations, getting a
+sparse Jacobian can be essential for performance. In this tutorial we will show
+how to use `modelingtoolkitize` to regenerate an `ODEProblem` code with
+the analytical solution to the sparse Jacobian, along with the sparsity
+pattern required by DifferentialEquations.jl's solvers to specialize the solving
+process.
+
+First let's start out with an implementation of the 2-dimensional Brusselator
+partial differential equation discretized using finite differences:
+
+```julia
+using DifferentialEquations, ModelingToolkit
+
+const N = 32
+const xyd_brusselator = range(0,stop=1,length=N)
+brusselator_f(x, y, t) = (((x-0.3)^2 + (y-0.6)^2) <= 0.1^2) * (t >= 1.1) * 5.
+limit(a, N) = a == N+1 ? 1 : a == 0 ? N : a
+function brusselator_2d_loop(du, u, p, t)
+  A, B, alpha, dx = p
+  alpha = alpha/dx^2
+  @inbounds for I in CartesianIndices((N, N))
+    i, j = Tuple(I)
+    x, y = xyd_brusselator[I[1]], xyd_brusselator[I[2]]
+    ip1, im1, jp1, jm1 = limit(i+1, N), limit(i-1, N), limit(j+1, N), limit(j-1, N)
+    du[i,j,1] = alpha*(u[im1,j,1] + u[ip1,j,1] + u[i,jp1,1] + u[i,jm1,1] - 4u[i,j,1]) +
+                B + u[i,j,1]^2*u[i,j,2] - (A + 1)*u[i,j,1] + brusselator_f(x, y, t)
+    du[i,j,2] = alpha*(u[im1,j,2] + u[ip1,j,2] + u[i,jp1,2] + u[i,jm1,2] - 4u[i,j,2]) +
+                A*u[i,j,1] - u[i,j,1]^2*u[i,j,2]
+    end
+end
+p = (3.4, 1., 10., step(xyd_brusselator))
+
+function init_brusselator_2d(xyd)
+  N = length(xyd)
+  u = zeros(N, N, 2)
+  for I in CartesianIndices((N, N))
+    x = xyd[I[1]]
+    y = xyd[I[2]]
+    u[I,1] = 22*(y*(1-y))^(3/2)
+    u[I,2] = 27*(x*(1-x))^(3/2)
+  end
+  u
+end
+u0 = init_brusselator_2d(xyd_brusselator)
+prob = ODEProblem(brusselator_2d_loop,u0,(0.,11.5),p)
+```
+
+Now let's use `modelingtoolkitize` to generate the symbolic version:
+
+```julia
+sys = modelingtoolkitize(prob_ode_brusselator_2d)
+```
+
+Now we regenerate the problem using `jac=true` for the analytical Jacobian
+and `sparse=true` to make it sparse:
+
+```julia
+sparseprob = ODEProblem(sys,Pair[],(0.,11.5),jac=true,sparse=true)
+```
+
+Hard? No! How much did that help?
+
+```julia
+using BenchmarkTools
+@btime solve(prob,save_everystep=false) # 51.714 s (7317 allocations: 70.12 MiB)
+@btime solve(sparseprob,save_everystep=false) # 2.880 s (55533 allocations: 885.09 MiB)
+```
+
+Notice though that the analytical solution to the Jacobian can be quite expensive.
+Thus in some cases we may only want to get the sparsity pattern. In this case,
+we can simply do:
+
+```julia
+sparsepatternprob = ODEProblem(sys,Pair[],(0.,11.5),sparse=true)
+@btime solve(sparsepatternprob,save_everystep=false) # 2.880 s (55533 allocations: 885.09 MiB)
+```

docs/src/systems/ControlSystem.md

@@ -19,3 +19,5 @@ ControlSystem
 ModelingToolkit.runge_kutta_discretize
 structural_simplify
 ```
+
+## Analyses

docs/src/systems/JumpSystem.md

@@ -19,6 +19,8 @@ JumpSystem
 structural_simplify
 ```
 
+## Analyses
+
 ## Problem Constructors
 
 ```@docs

docs/src/systems/NonlinearSystem.md

@@ -20,6 +20,12 @@ alias_elimination
 tearing
 ```
 
+## Analyses
+
+```@docs
+ModelingToolkit.islinear
+```
+
 ## Applicable Calculation and Generation Functions
 
 ```julia

docs/src/systems/ODESystem.md

@@ -24,6 +24,13 @@ alias_elimination
 tearing
 ```
 
+## Analyses
+
+```@docs
+ModelingToolkit.islinear
+ModelingToolkit.isautonomous
+```
+
 ## Applicable Calculation and Generation Functions
 
 ```julia