doc improvements

Author: ChrisRackauckas

docs/src/systems/AbstractSystem.md

@@ -41,6 +41,21 @@ which cobble together the generation functionality for a system, for example
 `ODEFunction` can be used to generate a DifferentialEquations-based `ODEFunction`
 with compiled version of the ODE itself, the Jacobian, the mass matrix, etc.
 
+Below are the possible calculation and generation functions:
+
+```@docs
+calculate_tgrad
+calculate_grad
+calculate_jacobian
+calculate_factorized_W
+calculate_hessian
+generate_jacobian
+generate_grad
+generate_tgrad
+generate_factorized_W
+generate_hessian
+```
+
 ## Problem Constructors
 
 At the end, the system types have `DEProblem` constructors, like `ODEProblem`,

docs/src/systems/NonlinearSystem.md

@@ -14,9 +14,9 @@ NonlinearSystem
 
 ## Transformations
 
-## Function Calculation and Generation
+## Applicable Calculation and Generation Functions
 
-```@docs
+```julia
 calculate_jacobian
 generate_jacobian
 ```

docs/src/systems/ODESystem.md

@@ -19,20 +19,20 @@ ODESystem
 ode_order_lowering
 ```
 
-## Function Calculation and Generation
+## Applicable Calculation and Generation Functions
 
-```@docs
+```julia
 calculate_jacobian
 calculate_tgrad
 calculate_factorized_W
 generate_jacobian
 generate_tgrad
 generate_factorized_W
-ODEFunction
 ```
 
 ## Problem Constructors
 
 ```@docs
+ODEFunction
 ODEProblem
 ```

docs/src/systems/OptimizationSystem.md

@@ -14,9 +14,9 @@ OptimizationSystem
 
 ## Transformations
 
-## Function Calculation and Generation
+## Applicable Calculation and Generation Functions
 
-```@docs
+```julia
 calculate_grad
 calculate_hes
 generate_grad

docs/src/systems/SDESystem.md

@@ -15,20 +15,20 @@ SDESystem
 
 ## Transformations
 
-## Function Calculation and Generation
+## Applicable Calculation and Generation Functions
 
-```@docs
-calculate_jacobian(sys::ModelingToolkit.AbstractODESystem)
-calculate_tgrad(sys::ModelingToolkit.AbstractODESystem)
-calculate_factorized_W(sys::ModelingToolkit.AbstractODESystem, simplify)
+```julia
+calculate_jacobian
+calculate_tgrad
+calculate_factorized_W
 generate_jacobian
 generate_tgrad
 generate_factorized_W
-SDEFunction
 ```
 
 ## Problem Constructors
 
 ```@docs
+SDEFunction
 SDEProblem
 ```

src/ModelingToolkit.jl

@@ -35,30 +35,6 @@ Base.one(::Type{<:Expression}) = Constant(1)
 """
 $(TYPEDSIGNATURES)
 
-Calculate the jacobian matrix of a system.
-
-Returns a matrix of [`Expression`](@ref) instances. The result from the first
-call will be cached in the system object.
-"""
-function calculate_jacobian end
-
-"""
-$(TYPEDSIGNATURES)
-
-Generate a function to calculate the Jacobian of the system.
-"""
-function generate_jacobian end
-
-"""
-$(TYPEDSIGNATURES)
-
-Generate a function to evaluate the system's equations.
-"""
-function generate_function end
-
-"""
-$(TYPEDSIGNATURES)
-
 Get the set of independent variables for the given system.
 """
 function independent_variables end

src/simplify.jl

@@ -9,6 +9,13 @@ function simplify_constants(O::Operation, shorten_tree)
     end
 end
 simplify_constants(x, shorten_tree) = x
+
+"""
+simplify_constants(x::Operation)
+
+Simplifies the constants within an expression, for example removing equations
+multiplied by a zero and summing constant values.
+"""
 simplify_constants(x) = simplify_constants(x, true)
 
 Base.isone(x::Operation) = x.op == one || x.op == Constant && isone(x.args)

src/systems/abstractsystem.jl

@@ -1,3 +1,100 @@
+"""
+calculate_tgrad(sys::AbstractSystem)
+
+Calculate the time gradient of a system.
+
+Returns a vector of [`Expression`](@ref) instances. The result from the first
+call will be cached in the system object.
+"""
+function calculate_tgrad end
+
+"""
+calculate_grad(sys::AbstractSystem)
+
+Calculate the gradient of a scalar system.
+
+Returns a vector of [`Expression`](@ref) instances. The result from the first
+call will be cached in the system object.
+"""
+function calculate_grad end
+
+"""
+calculate_jacobian(sys::AbstractSystem)
+
+Calculate the jacobian matrix of a system.
+
+Returns a matrix of [`Expression`](@ref) instances. The result from the first
+call will be cached in the system object.
+"""
+function calculate_jacobian end
+
+"""
+calculate_factorized_W(sys::AbstractSystem)
+
+Calculate the factorized W-matrix of a system.
+
+Returns a matrix of [`Expression`](@ref) instances. The result from the first
+call will be cached in the system object.
+"""
+function calculate_factorized_W end
+
+"""
+calculate_hessian(sys::AbstractSystem)
+
+Calculate the hessian matrix of a scalar system.
+
+Returns a matrix of [`Expression`](@ref) instances. The result from the first
+call will be cached in the system object.
+"""
+function calculate_hessian end
+
+"""
+generate_tgrad(sys::AbstractSystem, dvs = states(sys), ps = parameters(sys), expression = Val{true}; kwargs...)
+
+Generates a function for the time gradient of a system. Extra arguments control
+the arguments to the internal [`build_function`](@ref) call.
+"""
+function generate_tgrad end
+
+"""
+generate_grad(sys::AbstractSystem, dvs = states(sys), ps = parameters(sys), expression = Val{true}; kwargs...)
+
+Generates a function for the gradient of a system. Extra arguments control
+the arguments to the internal [`build_function`](@ref) call.
+"""
+function generate_grad end
+
+"""
+generate_jacobian(sys::AbstractSystem, dvs = states(sys), ps = parameters(sys), expression = Val{true}; sparse = false, kwargs...)
+
+Generates a function for the jacobian matrix matrix of a system. Extra arguments control
+the arguments to the internal [`build_function`](@ref) call.
+"""
+function generate_jacobian end
+
+"""
+generate_factorized_W(sys::AbstractSystem, dvs = states(sys), ps = parameters(sys), expression = Val{true}; sparse = false, kwargs...)
+
+Generates a function for the factorized W-matrix matrix of a system. Extra arguments control
+the arguments to the internal [`build_function`](@ref) call.
+"""
+function generate_factorized_W end
+
+"""
+generate_hessian(sys::AbstractSystem, dvs = states(sys), ps = parameters(sys), expression = Val{true}; sparse = false, kwargs...)
+
+Generates a function for the hessian matrix matrix of a system. Extra arguments control
+the arguments to the internal [`build_function`](@ref) call.
+"""
+function generate_hessian end
+
+"""
+generate_function(sys::AbstractSystem, dvs = states(sys), ps = parameters(sys), expression = Val{true}; kwargs...)
+
+Generate a function to evaluate the system's equations.
+"""
+function generate_function end
+
 function Base.getproperty(sys::AbstractSystem, name::Symbol)
     if name ∈ fieldnames(typeof(sys))
         return getfield(sys,name)

src/systems/diffeqs/sdesystem.jl

@@ -151,7 +151,7 @@ function rename(sys::SDESystem,name)
 end
 
 """
-$(TYPEDEF)
+$(SIGNATURES)
 
 Generates an SDEProblem from an SDESystem and allows for automatically
 symbolically calculating numerical enhancements.

src/utils.jl

@@ -81,6 +81,11 @@ end
 is_singleton(e) = false
 is_singleton(e::Operation) = e.op isa Variable
 
+"""
+get_variables(O::Operation)
+
+Returns the variables in the Operation
+"""
 get_variables(e::Constant, vars = Operation[]) = vars
 function get_variables(e::Operation, vars = Operation[])
     if is_singleton(e)
@@ -92,6 +97,11 @@ function get_variables(e::Operation, vars = Operation[])
 end
 
 # variable substitution
+"""
+substitute_expr!(expr::Operation, s::Pair{Operation, Operation})
+
+Performs the substitution `Operation => Operation` on the `expr` Operation.
+"""
 substitute_expr!(expr::Constant, s::Pair{Operation, Operation}) = nothing
 function substitute_expr!(expr::Operation, s::Pair{Operation, Operation})
     if !is_singleton(expr)