Merge pull request #631 from SciML/sm/docs

Doc updates for 4.x

Author: ChrisRackauckas

docs/src/IR.md

@@ -1,32 +1,39 @@
 # ModelingToolkit IR
 
-ModelingToolkit IR, which falls under the `Expression` abstract type, mirrors
-the Julia AST but allows for easy mathematical manipulation by itself following
-mathematical semantics. The base of the IR is the `Variable` type, which defines
-a symbolic variable. These variables are combined using `Operation`s, which are
-registered functions applied to the various variables. These `Operation`s then
-perform automatic tracing, so normal mathematical functions applied to an `Operation`
-generate a new `Operation`. For example, `op1 = x+y` is one `Operation` and
-`op2 = 2z` is another, and so `op1*op2` is another `Operation`. Then, at the top,
-an `Equation`, normally written as `op1 ~ op2`, defines the symbolic equality
-between two operations.
+ModelingToolkit IR mirrors the Julia AST but allows for easy mathematical
+manipulation by itself following mathematical semantics. The base of the IR is
+the `Sym` type, which defines a symbolic variable. Registered (mathematical)
+functions on `Sym`s (or `Term`s) return `Term`s.  For example, `op1 = x+y` is
+one `Term` and `op2 = 2z` is another, and so `op1*op2` is another `Term`. Then,
+at the top, an `Equation`, normally written as `op1 ~ op2`, defines the
+symbolic equality between two operations.
 
 ### Types
 
 ```@docs
-Expression
-Variable
-ModelingToolkit.Constant
-Operation
+Sym
+Term
 Equation
 ```
 
+### A note about functions restricted to `Number`s
+
+`Sym` and `Term` objects are NOT subtypes of `Number`. ModelingToolkit provides
+a simple wrapper type called `Num` which is a subtype of `Real`. `Num` wraps
+either a Sym or a Term or any other object, defines the same set of operations
+as symbolic expressions and forwards those to the values it wraps. You can use
+`ModelingToolkit.value` function to unwrap a `Num`.
+
+By default, the `@variables` and `@parameters` functions return Num-wrapped
+objects so as to allow calling functions which are restricted to `Number` or
+`Real`.
+
 ### Function Registration
 
 The ModelingToolkit graph only allowed for registered Julia functions for the
 operations. All other functions are automatically traced down to registered
 functions. By default, ModelingToolkit.jl pre-registers the common functions
-utilized in the AD package ruleset [DiffRules.jl](https://github.com/JuliaDiff/DiffRules.jl)
+utilized in [SymbolicUtils.jl](https://github.com/JuliaSymbolics/SymbolicUtils.jl)
 and pre-defines their derivatives. However, the user can utilize the `@register`
 macro to add their function to allowed functions of the computation graph.
 
@@ -36,7 +43,7 @@ macro to add their function to allowed functions of the computation graph.
 
 ### Derivatives and Differentials
 
-A `Differential(op)` is a partial derivative with respect to the operation `op`,
+A `Differential(op)` is a partial derivative with respect to `op`,
 which can then be applied to some other operations. For example, `D=Differential(t)`
 is what would commonly be referred to as `d/dt`, which can then be applied to
 other operations using its function call, so `D(x+y)` is `d(x+y)/dt`.
@@ -50,18 +57,18 @@ of the differentials down to basic one-variable expressions.
 ModelingToolkit.derivative
 Differential
 expand_derivatives
+ModelingToolkit.jacobian
+ModelingToolkit.gradient
+ModelingToolkit.hessian
 ```
 
-Note that the generation of sparse matrices simply follows from the Julia semantics
-imbued on the IR, so `sparse(jac)` changes a dense Jacobian to a sparse Jacobian
-matrix.
+For jacobians which are sparse, use the `sparsejacobian` function.
+For hessians which are sparse, use the `sparsehessian` function.
 
 ### Adding Derivatives
 
 There is a large amount of derivatives pre-defined by
-[DiffRules.jl](https://github.com/JuliaDiff/DiffRules.jl). Note that `Expression`
-types are defined as `<:Real`, and thus any functions which allow the use of real
-numbers can automatically be traced by the derivative mechanism. Thus, for example:
+[DiffRules.jl](https://github.com/JuliaDiff/DiffRules.jl).
 
 ```julia
 f(x,y,z) = x^2 + sin(x+y) - z
@@ -84,7 +91,7 @@ ModelingToolkit.derivative(::typeof(my_function), args::NTuple{N,Any}, ::Val{i})
 
 where `i` means that it's the derivative with respect to the `i`th argument. `args` is the
 array of arguments, so, for example, if your function is `f(x,t)`, then `args = [x,t]`.
-You should return an `Operation` for the derivative of your function.
+You should return an `Term` for the derivative of your function.
 
 For example, `sin(t)`'s derivative (by `t`) is given by the following:
 
@@ -94,14 +101,14 @@ ModelingToolkit.derivative(::typeof(sin), args::NTuple{1,Any}, ::Val{1}) = cos(a
 
 ### IR Manipulation
 
-ModelingToolkit.jl provides functionality for easily manipulating `Expression`
-types. Most of the functionality comes by the `Expression` type obeying the
-standard mathematical semantics. For example, if one has `A` a matrix of
-`Expression`, then `A^2` calculates the `Expression`s for the squared matrix.
-In that sense, it is encouraged that one uses standard Julia for performing a
-lot of the manipulation on the IR, as, for example, calculating the sparse form
-of the matrix via `sparse(A)` is valid, legible, and easily understandable
-to all Julia programmers.
+ModelingToolkit.jl provides functionality for easily manipulating expressions.
+Most of the functionality comes by the expression objects obeying the standard
+mathematical semantics. For example, if one has `A` a matrix of symbolic
+expressions wrapped in `Num`, then `A^2` calculates the expressions for the
+squared matrix.  In that sense, it is encouraged that one uses standard Julia
+for performing a lot of the manipulation on the IR, as, for example,
+calculating the sparse form of the matrix via `sparse(A)` is valid, legible,
+and easily understandable to all Julia programmers.
 
 Other additional manipulation functions are given below.
 

docs/src/build_function.md

@@ -1,11 +1,11 @@
 # Function Building and Compilation (build_function)
 
-At any time, callable functions can be generated from ModelingToolkit IR by using
-`convert(Expr,x)`. This performs some cleaning to return an expression without
-extraneous pieces that commonly matches expressions one would write in functions
-like those for differential equation solvers and optimization libraries. These
-functions can be automatically parallelize and specialize on Julia types like
-static arrays and sparse matrices.
+At any time, callable functions can be generated from ModelingToolkit IR by
+using `ModelingToolkit.toexpr`. This performs some cleaning to return an
+expression without extraneous pieces that commonly matches expressions one
+would write in functions like those for differential equation solvers and
+optimization libraries. These functions can be automatically parallelize and
+specialize on Julia types like static arrays and sparse matrices.
 
 The core compilation process of ModelingToolkit IR is `build_function`.
 `build_function` takes an operation or an `AbstractArray` of operations and

docs/src/highlevel.md

@@ -11,7 +11,7 @@ methods.
 @parameters
 @variables
 @derivatives
-Base.:~(::Expression, ::Expression)
+Base.:~(::Num, ::Num)
 modelingtoolkitize
 ```
 
@@ -42,7 +42,7 @@ latexify(ex)
 ```
 
 will produce LaTeX output from ModelingToolkit models and expressions.
-This works on basics like `Operation` all the way to higher primitives
+This works on basics like `Term` all the way to higher primitives
 like `ODESystem` and `ReactionSystem`.
 
 ## The Auto-Detecting System Constructors
@@ -78,7 +78,7 @@ du
 ```
 
 ```julia
-3-element Array{Operation,1}:
+3-element Array{Num,1}:
                  10.0 * (u₂(t) - u₁(t))
          u₁(t) * (28.0 - u₃(t)) - u₂(t)
 u₁(t) * u₂(t) - 2.6666666666666665 * u₃(t)
@@ -97,7 +97,7 @@ du
 ```
 
 ```julia
-3-element Array{Operation,1}:
+3-element Array{Num,1}:
                 10.0 * (y(t) - x(t))
          x(t) * (28.0 - z(t)) - y(t)
 x(t) * y(t) - 2.6666666666666665 * z(t)
@@ -106,7 +106,7 @@ x(t) * y(t) - 2.6666666666666665 * z(t)
 ## Intermediate Calculations
 
 The system building functions can handle intermediate calculations by simply
-defining and using an `Operation` of `Variable`s. For example:
+defining and using an `Term` of `Sym`s. For example:
 
 ```julia
 @variables x y z

docs/src/index.md

@@ -23,7 +23,7 @@ ModelingToolkit has 3 layers:
    At the system level, there are *transformations* which take one system to
    another, and *targets* which output code for numerical solvers.
 3. The IR level, also referred to as the direct level. At this level, one
-   directly acts on arrays of `Equation`, `Operation`, and `Variable` types to
+   directly acts on arrays of `Equation`s, and symbolic expressions to
    generate functions.
 
 Each level above is built on the level below, giving more context to allow for

docs/src/tutorials/auto_parallel.md

@@ -1,6 +1,6 @@
 # Automated Sparse Parallelism of ODEs via Tracing
 
-Because the ModelingToolkit `Expression` types obey Julia semantics, one can
+Because the ModelingToolkit expressions obey Julia semantics, one can
 directly transform existing Julia functions into ModelingToolkit symbolic
 representations of the function by simply inputting the symbolic values into
 the function and using what is returned. For example, let's take [the following

docs/src/tutorials/converting_to_C.md

@@ -25,7 +25,7 @@ lotka_volterra!(du, u, p, t)
 which gives:
 
 ```julia
-du = Operation[p₁ * u₁ - (p₂ * u₁) * u₂, -p₃ * u₂ + (p₄ * u₁) * u₂]
+du = Num[p₁ * u₁ - (p₂ * u₁) * u₂, -p₃ * u₂ + (p₄ * u₁) * u₂]
 ```
 
 Now we build the equations we want to solve:

docs/src/tutorials/ode_modeling.md

@@ -69,8 +69,8 @@ eqs = [D(x) ~ σ*(y-x),
        D(z) ~ x*y - β*z]
 ```
 
-Each operation builds an `Operation` type, and thus `eqs` is an array of
-`Operation` and `Variable`s. This holds a tree of the full system that can be
+Each operation builds an `Term` type, and thus `eqs` is an array of
+`Term` and `Sym`s (possibly wrapped in Num). This holds a tree of the full system that can be
 analyzed by other programs. We can turn this into a `ODESystem` via:
 
 ```julia

docs/src/tutorials/symbolic_functions.md

@@ -8,14 +8,14 @@ The way to define symbolic variables is via the `@variables` macro:
 ```
 
 After defining variables as symbolic, symbolic expressions, which we
-call an `Operation`, can be generated by utilizing Julia expressions.
+call a `Term`, can be generated by utilizing Julia expressions.
 For example:
 
 ```julia
 z = x^2 + y
 ```
 
-Here, `z` is the `Operation` for "square `x` and add `y`". To
+Here, `z` is the `Term` for "square `x` and add `y`". To
 make an array of symbolic expressions, simply make an array of
 symbolic expressions:
 
@@ -24,12 +24,14 @@ A = [x^2+y 0 2x
      0     0 2y
      y^2+x 0 0]
 
-3×3 Array{Expression,2}:
-  x ^ 2 + y  Constant(0)           2x
-Constant(0)  Constant(0)           2y
-  y ^ 2 + x  Constant(0)  Constant(0)
+3×3 Array{Num,2}:
+  x ^ 2 + y  0  2x
+  0  0  2y
+  y ^ 2 + x  0  0
 ```
 
+Note that by default, `@variables` returns `Sym` or `Term` objects wrapped in `Num` in order to make them behave like subtypes of `Real`. Any operation on these `Num` objects will return a new `Num` object, wrapping the result of computing symbolically on the underlying values.
+
 To better view the results, we can use [Latexify.jl](https://github.com/korsbo/Latexify.jl).
 ModelingToolkit.jl comes with Latexify recipes so it works automatically:
 
@@ -42,9 +44,9 @@ latexify(A)
 \begin{equation}
 \left[
 \begin{array}{ccc}
-x ^ 2 + y & ModelingToolkit.Constant(0) & 2x \\
-ModelingToolkit.Constant(0) & ModelingToolkit.Constant(0) & 2y \\
-y ^ 2 + x & ModelingToolkit.Constant(0) & ModelingToolkit.Constant(0) \\
+(x ^ 2) + y & 0 & 2 * x \\
+0 & 0 & 2 * y \\
+(y ^ 2) + x & 0 & 0 \\
 \end{array}
 \right]
 \end{equation}
@@ -57,11 +59,11 @@ want to create the sparse version of `A` we would just call `sparse`:
 using SparseArrays
 spA = sparse(A)
 
-3×3 SparseMatrixCSC{Expression,Int64} with 4 stored entries:
-  [1, 1]  =  x ^ 2 + y
-  [3, 1]  =  y ^ 2 + x
-  [1, 3]  =  2x
-  [2, 3]  =  2y
+3×3 SparseMatrixCSC{Num,Int64} with 4 stored entries:
+  [1, 1]  =  (x ^ 2) + y
+  [3, 1]  =  (y ^ 2) + x
+  [1, 3]  =  2 * x
+  [2, 3]  =  2 * y
 ```
 
 We can thus use normal Julia functions as generators for sparse
@@ -73,7 +75,7 @@ function f(u)
 end
 f([x,y,z]) # Recall that z = x^2 + y
 
-3-element Array{Operation,1}:
+3-element Array{Num,1}:
  x - (x ^ 2 + y)
        x ^ 2 - y
  (x ^ 2 + y) + y
@@ -85,7 +87,7 @@ Or we can build array variables and use these to trace:
 @variables u[1:3]
 f(u)
 
-3-element Array{Operation,1}:
+3-element Array{Num,1}:
      u₁ - u₃
  u₁ ^ 2 - u₂
      u₃ + u₂
@@ -178,7 +180,7 @@ a function via a sparse matrix. For example:
 N = 8
 A = sparse(Tridiagonal([x^i for i in 1:N-1],[x^i * y^(8-i) for i in 1:N], [y^i for i in 1:N-1]))
 
-8×8 SparseMatrixCSC{Operation,Int64} with 22 stored entries:
+8×8 SparseMatrixCSC{Num,Int64} with 22 stored entries:
   [1, 1]  =  x ^ 1 * y ^ 7
   [2, 1]  =  x ^ 1
   [1, 2]  =  y ^ 1
@@ -314,7 +316,7 @@ like:
 ```julia
 ModelingToolkit.jacobian([x+x*y,x^2+y],[x,y])
 
-2×2 Array{Expression,2}:
+2×2 Array{Num,2}:
  1 + y            x
     2x  Constant(1)
 ```
@@ -338,7 +340,7 @@ This can be applied to arrays by using Julia's broadcast mechanism:
 B = simplify.([t^2+t+t^2  2t+4t
            x+y+y+2t   x^2 - x^2 + y^2])
 
-2×2 Array{Operation,2}:
+2×2 Array{Num,2}:
   2 * t ^ 2 + t     6t
 x + 2 * (t + y)  y ^ 2
 ```
@@ -348,7 +350,7 @@ We can then use `substitute` to change values of an expression around:
 ```julia
 simplify.(substitute.(B,[x=>y^2]))
 
-2×2 Array{Operation,2}:
+2×2 Array{Num,2}:
        2 * t ^ 2 + t     6t
  y ^ 2 + 2 * (t + y)  y ^ 2
 ```
@@ -380,8 +382,8 @@ the user's code. For these cases, ModelingToolkit.jl allows for fully
 macro-free usage. For example:
 
 ```julia
-x = Variable{Float64}(:x)()
-y = Variable{Float64}(:y)()
+x = Sym{Float64}(:x)()
+y = Sym{Float64}(:y)()
 x+y^2.0
 ```
 
@@ -396,23 +398,17 @@ convert the output to an `Expr`:
 Expr(x+y^2)
 ```
 
-## Variables as Operations
-
-`Operation` is the type name the ModelingToolkit.jl gives to symbolic
-expressions. In ModelingToolkit.jl, essentially everything is an
-`Operation`. Notice that when we defined our variables above, they
-were represented as an `Operation` as well, which means that variables
-alone are an operation that can then be composed to make bigger
-operations.
+## `Sym`s and callable `Sym`s
 
-But since variables are functions, we can represent their dependencies
-as well. For example:
+In the definition
 
 ```julia
 @variables t x(t) y(t)
 ```
 
-defines `t` as a dependent variable while `x(t)` and `y(t)` are
+`t` is of type `Sym{Real}` but the name `x` refers to an object that represents the `Term` `x(t)`. The operation of this expression is itself the object `Sym{FnType{Tuple{Real}, Real}}(:x)`. The type `Sym{FnType{...}}` represents a callable object. In this case specifically it's a function that takes 1 Real argument (noted by `Tuple{Real}`) and returns a `Real` result. You can call such a callable `Sym` with either a number or a symbolic expression of a permissible type.
+
+this expression also defines `t` as a dependent variable while `x(t)` and `y(t)` are
 independent variables. This is accounted for in differentiation:
 
 ```julia