Merge pull request #672 from SciML/myb/docs

Update docs

Author: ChrisRackauckas

docs/src/IR.md

@@ -9,10 +9,14 @@ at the top, an `Equation`, normally written as `op1 ~ op2`, defines the
 symbolic equality between two operations.
 
 ### Types
+`Sym`, `Term`, and `FnType` are from `SymbolicUtils.jl`. For more details,
+checkout https://juliasymbolics.github.io/SymbolicUtils.jl/api/. Note that in
+ModelingToolkit, we always use `Sym{Real}`, `Term{Real}`, and
+`FnType{Tuple{Any}, Real}`. To get the arguments of a `Term` use
+`arguments(t::Term)`, and to get the operation of a `Term` use
+`operation(t::Term)`.
 
 ```@docs
-Sym
-Term
 Equation
 ```
 
@@ -28,6 +32,21 @@ By default, the `@variables` and `@parameters` functions return Num-wrapped
 objects so as to allow calling functions which are restricted to `Number` or
 `Real`.
 
+```julia
+julia> @parameters t; @variables x y z(t);
+
+julia> ModelingToolkit.operation(ModelingToolkit.value(x + y))
++ (generic function with 377 methods)
+
+julia> ModelingToolkit.operation(ModelingToolkit.value(z))
+z(::Any)::Real
+
+julia> ModelingToolkit.arguments(ModelingToolkit.value(x + y))
+2-element Vector{Sym{Real}}:
+ x
+ y
+```
+
 ### Function Registration
 
 The ModelingToolkit graph only allowed for registered Julia functions for the
@@ -113,7 +132,11 @@ and easily understandable to all Julia programmers.
 Other additional manipulation functions are given below.
 
 ```@docs
-simplify_constants
 get_variables
-substitute_expr!
+substitute
+tovar
+toparam
+tosymbol
+makesym
+diff2term
 ```

docs/src/tutorials/symbolic_functions.md

@@ -385,11 +385,24 @@ macro-free usage. For example:
 x = Num(Sym{Float64}(:x))
 y = Num(Sym{Float64}(:y))
 x+y^2.0 # isa Num
+
+t = Num(Variable{ModelingToolkit.Parameter{Real}}(:t))  # independent variables are treated as known
+α = Num(Variable{ModelingToolkit.Parameter{Real}}(:α))  # parameters are known
+σ = Num(Variable{ModelingToolkit.FnType{Tuple{Any},Real}}(:σ)) # left uncalled, since it is used as a function
+w = Num(Variable{ModelingToolkit.FnType{Tuple{Any},Real}}(:w)) # unknown, left uncalled
+x = Num(Variable{ModelingToolkit.FnType{Tuple{Any},Real}}(:x))(t)  # unknown, depends on `t`
+y = Num(Variable(:y))   # unknown, no dependents
+z = Num(Variable{ModelingToolkit.FnType{NTuple{3,Any},Real}}(:z))(t, α, x)  # unknown, multiple arguments
+β₁ = Num(Variable(:β, 1)) # with index 1
+β₂ = Num(Variable(:β, 2)) # with index 2
+
+expr = β₁ * x + y^α + σ(3) * (z - t) - β₂ * w(t - 1)
 ```
 
-Does what you'd expect. The reference documentation shows how to
-define any of the quantities in such a way that the names can come
-from runtime values.
+Does what you'd expect. Note that `Variable` is simply a convenient function for
+making variables with indices that always returns `Sym`. The reference
+documentation shows how to define any of the quantities in such a way that the
+names can come from runtime values.
 
 If we need to use this to generate new Julia code, we can simply
 convert the output to an `Expr`:

src/register_function.jl

@@ -1,3 +1,15 @@
+"""
+    @register(expr, Ts = [Num, Symbolic, Real])
+
+Overload approperate methods such that ModelingToolkit can stop tracing into the
+registered function.
+
+# Examples
+```julia
+@register foo(x, y)
+@register goo(x, y::Int) # `y` is not overloaded to take symbolic objects
+```
+"""
 macro register(expr, Ts = [Num, Symbolic, Real])
     @assert expr.head == :call
 

src/utils.jl

@@ -53,9 +53,28 @@ is_derivative(O::Term) = isa(O.op, Differential)
 is_derivative(::Any) = false
 
 """
-get_variables(O)
+    get_variables(O) -> Vector{Union{Sym, Term}}
 
-Returns the variables in the expression
+Returns the variables in the expression. Note that the returned variables are
+not wrapped in the `Num` type.
+
+# Examples
+```julia
+julia> @parameters t
+(t,)
+
+julia> @variables x y z(t)
+(x, y, z(t))
+
+julia> ex = x + y + sin(z)
+(x + y) + sin(z(t))
+
+julia> ModelingToolkit.get_variables(ex)
+3-element Vector{Any}:
+ x
+ y
+ z(t)
+```
 """
 get_variables(e::Num, varlist=nothing) = get_variables(value(e), varlist)
 get_variables!(vars, e, varlist=nothing) = vars
@@ -89,11 +108,26 @@ modified_states!(mstates, e::Equation, statelist=nothing) = get_variables!(mstat
 # variable substitution
 # Piracy but mild
 """
-substitute(expr, s::Pair)
-substitute(expr, s::Dict)
-substitute(expr, s::Vector)
+    substitute(expr, s::Pair)
+    substitute(expr, s::Dict)
+    substitute(expr, s::Vector)
+
+Performs the substitution on `expr` according to rule(s) `s`.
+
+# Examples
+```julia
+julia> @parameters t
+(t,)
+
+julia> @variables x y z(t)
+(x, y, z(t))
+
+julia> ex = x + y + sin(z)
+(x + y) + sin(z(t))
 
-Performs the substitution `Num => val` on the `expr` Num.
+julia> substitute(ex, Dict([x => z, sin(z) => z^2]))
+(z(t) + y) + (z(t) ^ 2)
+```
 """
 substitute(expr::Num, s::Union{Pair, Vector, Dict}; kw...) = Num(substituter(s)(value(expr); kw...))
 # TODO: move this to SymbolicUtils
@@ -150,8 +184,9 @@ toparam(s::Sym{<:Parameter}) = s
 
 """
     tovar(s::Sym) -> Sym{Real}
+    tovar(s::Sym{<:Parameter}) -> Sym{Real}
 
-Maps the variable to a variable (state).
+Maps the variable to a state.
 """
 tovar(s::Sym{<:Parameter}) = Sym{symtype(s)}(s.name)
 tovar(s::Sym) = s
@@ -167,6 +202,15 @@ tosymbol(t::Num; kwargs...) = tosymbol(value(t); kwargs...)
 Convert `x` to a symbol. `states` are the states of a system, and `escape`
 means if the target has escapes like `val"y⦗t⦘"`. If `escape` then it will only
 output `y` instead of `y⦗t⦘`.
+
+# Examples
+```julia
+julia> @parameters t; @variables z(t)
+(z(t),)
+
+julia> ModelingToolkit.tosymbol(z)
+Symbol("z⦗t⦘")
+```
 """
 function tosymbol(t::Term; states=nothing, escape=true)
     if t.op isa Sym
@@ -188,6 +232,21 @@ function tosymbol(t::Term; states=nothing, escape=true)
     error("Cannot convert $t to a symbol")
 end
 
+"""
+    makesym(x::Union{Num,Symbolic}, kwargs...) -> Sym
+
+`makesym` takes the same arguments as [`tosymbol`](@ref), but it converts a
+`Term` in the form of `x(t)` to a `Sym` in the form of `x⦗t⦘`.
+
+# Examples
+```julia
+julia> @parameters t; @variables x(t)
+(x(t),)
+
+julia> ModelingToolkit.makesym(x)
+x⦗t⦘
+```
+"""
 makesym(t::Symbolic; kwargs...) = Sym{symtype(t)}(tosymbol(t; kwargs...))
 makesym(t::Num; kwargs...) = makesym(value(t); kwargs...)
 
@@ -224,7 +283,12 @@ end
     diff2term(x::Term) -> Term
     diff2term(x) -> x
 
-diff2term(D(D(x(t)))) -> xˍtt(t)
+Convert a differential variable to a `Symbol`. Note that it only takes a `Term`
+not a `Num`.
+```julia
+julia> ModelingToolkit.diff2term(ModelingToolkit.value(D(D(x))))
+xˍtt(t)
+```
 """
 function diff2term(O)
     isa(O, Term) || return O