Merge pull request #125 from jlumpe/docs

Start on API documentation

Author: ChrisRackauckas

Project.toml

@@ -6,6 +6,7 @@ version = "0.3.0"
 [deps]
 DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e"
 DiffRules = "b552c78f-8df3-52c6-915a-8e097449b14b"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
 NaNMath = "77ba4419-2d1f-58cd-9bb1-8ffee604a2e3"

docs/.gitignore

@@ -0,0 +1,2 @@
+build/
+site/

docs/make.jl

@@ -0,0 +1,11 @@
+using Documenter, ModelingToolkit, DiffEqBase
+
+
+makedocs(
+    sitename="ModelingToolkit.jl",
+    modules=[ModelingToolkit],
+    pages=[
+        "Home" => "index.md",
+        "api.md",
+    ]
+)

docs/src/api.md

@@ -0,0 +1,55 @@
+# API
+
+
+## Intermediate representation
+
+### Types
+
+```@docs
+Expression
+Variable
+ModelingToolkit.Constant
+Operation
+Equation
+Differential
+```
+
+### Functions
+
+```@docs
+Base.get(c::ModelingToolkit.Constant)
+Base.:~(::Expression, ::Expression)
+expand_derivatives
+ModelingToolkit.derivative
+```
+
+### Macros
+
+```@docs
+@parameters
+@variables
+@derivatives
+@register
+```
+
+## Systems
+
+### Types
+
+```@docs
+ModelingToolkit.AbstractSystem
+ODESystem
+NonlinearSystem
+```
+
+### Functions
+
+```@docs
+independent_variables
+dependent_variables
+parameters
+calculate_jacobian
+generate_jacobian
+generate_function
+DiffEqBase.ODEFunction(sys::ODESystem, dvs, ps; version::FunctionVersion = ArrayFunction)
+```

docs/src/index.md

@@ -0,0 +1,12 @@
+# ModelingToolkit.jl Documentation
+
+
+ModelingToolkit.jl is an intermediate representation (IR) of computational graphs
+for scientific computing problems. Its purpose is to be a common target for
+modeling DSLs in order to allow for a common platform for model inspection and
+transformation. It uses a tagged variable IR in order to allow specification of
+complex models and allow for transformations of models. It has ways to plug into
+its function registration and derivative system so that way it can interact
+nicely with user-defined routines. Together, this is an abstract form of a
+scientific model that is easy for humans to generate but also easy for programs
+to manipulate.

src/ModelingToolkit.jl

@@ -12,20 +12,70 @@ using StaticArrays, LinearAlgebra
 using MacroTools
 import MacroTools: splitdef, combinedef
 
+using DocStringExtensions
+
+"""
+$(TYPEDEF)
+
+Base type for a symbolic expression.
+"""
 abstract type Expression <: Number end
+
+"""
+$(TYPEDEF)
+
+TODO
+"""
 abstract type AbstractSystem end
 
 Base.promote_rule(::Type{<:Number},::Type{<:Expression}) = Expression
 Base.zero(::Type{<:Expression}) = Constant(0)
 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
-function dependent_variables   end
-function parameters            end
+
+"""
+$(TYPEDSIGNATURES)
+
+Get the set of dependent variables for the given system.
+"""
+function dependent_variables end
+
+"""
+$(TYPEDSIGNATURES)
+
+Get the set of parameters variables for the given system.
+"""
+function parameters end
 
 @enum FunctionVersion ArrayFunction=1 SArrayFunction=2
 

src/differentials.jl

@@ -1,7 +1,30 @@
 export Differential, expand_derivatives, @derivatives
 
 
+"""
+$(TYPEDEF)
+
+Represents a differential operator.
+
+# Fields
+$(FIELDS)
+
+# Examples
+
+```jldoctest
+julia> using ModelingToolkit
+
+julia> @variables x y;
+
+julia> D = Differential(x)
+(D'~x())
+
+julia> D(y)  # Differentiate y wrt. x
+(D'~x())(y())
+```
+"""
 struct Differential <: Function
+    """The variable or expression to differentiate with respect to."""
     x::Expression
 end
 (D::Differential)(x) = Operation(D, Expression[x])
@@ -11,6 +34,11 @@ Base.convert(::Type{Expr}, D::Differential) = D
 
 Base.:(==)(D1::Differential, D2::Differential) = isequal(D1.x, D2.x)
 
+"""
+$(SIGNATURES)
+
+TODO
+"""
 function expand_derivatives(O::Operation)
     @. O.args = expand_derivatives(O.args)
 
@@ -32,6 +60,40 @@ end
 expand_derivatives(x) = x
 
 # Don't specialize on the function here
+"""
+$(SIGNATURES)
+
+Calculate the derivative of the op `O` with respect to its argument with index
+`idx`.
+
+# Examples
+
+```jldoctest label1
+julia> using ModelingToolkit
+
+julia> @variables x y;
+
+julia> ModelingToolkit.derivative(sin(x), 1)
+cos(x())
+```
+
+Note that the function does not recurse into the operation's arguments, i.e. the
+chain rule is not applied:
+
+```jldoctest label1
+julia> myop = sin(x) * y^2
+sin(x()) * y() ^ 2
+
+julia> typeof(myop.op)  # Op is multiplication function
+typeof(*)
+
+julia> ModelingToolkit.derivative(myop, 1)  # wrt. sin(x)
+y() ^ 2
+
+julia> ModelingToolkit.derivative(myop, 2)  # wrt. y^2
+sin(x())
+```
+"""
 derivative(O::Operation, idx) = derivative(O.op, (O.args...,), Val(idx))
 
 # Pre-defined derivatives
@@ -76,10 +138,33 @@ function _differential_macro(x)
     ex
 end
 
+"""
+$(SIGNATURES)
+
+Define one or more differentials.
+
+# Examples
+
+```jldoctest
+julia> using ModelingToolkit
+
+julia> @variables x y z;
+
+julia> @derivatives Dx'~x Dy'~y  # Create differentials wrt. x and y
+((D'~x()), (D'~y()))
+
+julia> Dx(z)  # Differentiate z wrt. x
+(D'~x())(z())
+
+julia> Dy(z)  # Differentiate z wrt. y
+(D'~y())(z())
+```
+"""
 macro derivatives(x...)
     esc(_differential_macro(x))
 end
 
+
 function calculate_jacobian(eqs, dvs)
     Expression[Differential(dv)(eq) for eq ∈ eqs, dv ∈ dvs]
 end

src/equations.jl

@@ -1,12 +1,42 @@
 export Equation
 
 
+"""
+$(TYPEDEF)
+
+An equality relationship between two expressions.
+
+# Fields
+$(FIELDS)
+"""
 struct Equation
+    """The expression on the left hand side of the equation."""
     lhs::Expression
+    """The expression on the right hand side of the equation."""
     rhs::Expression
 end
 Base.:(==)(a::Equation, b::Equation) = isequal((a.lhs, a.rhs), (b.lhs, b.rhs))
 
+"""
+$(TYPEDSIGNATURES)
+
+Create an [`Equation`](@ref) out of two [`Expression`](@ref) instances, or an
+`Expression` and a `Number`.
+
+# Examples
+
+```jldoctest
+julia> using ModelingToolkit
+
+julia> @variables x y;
+
+julia> x ~ y
+Equation(x(), y())
+
+julia> x - y ~ 0
+Equation(x() - y(), ModelingToolkit.Constant(0))
+```
+"""
 Base.:~(lhs::Expression, rhs::Expression) = Equation(lhs, rhs)
 Base.:~(lhs::Expression, rhs::Number    ) = Equation(lhs, rhs)
 Base.:~(lhs::Number    , rhs::Expression) = Equation(lhs, rhs)

src/function_registration.jl

@@ -1,4 +1,9 @@
 # Register functions and handle literals
+"""
+$(SIGNATURES)
+
+TODO
+"""
 macro register(sig)
     splitsig = splitdef(:($sig = nothing))
     name = splitsig[:name]

src/operations.jl

@@ -1,5 +1,47 @@
+"""
+$(TYPEDEF)
+
+An expression representing the application of a function to symbolic arguments.
+
+# Fields
+$(FIELDS)
+
+# Examples
+
+Operations can be built by application of most built-in mathematical functions
+to other [`Expression`](@ref) instances:
+
+```jldoctest
+julia> using ModelingToolkit
+
+julia> @variables x y;
+
+julia> op1 = sin(x)
+sin(x())
+
+julia> typeof(op1.op)
+typeof(sin)
+
+julia> op1.args
+1-element Array{Expression,1}:
+ x()
+
+julia> op2 = x + y
+x() + y()
+
+julia> typeof(op2.op)
+typeof(+)
+
+julia> op2.args
+2-element Array{Expression,1}:
+ x()
+ y()
+```
+"""
 struct Operation <: Expression
+    """The function to be applied."""
     op::Function
+    """The arguments the function is applied to."""
     args::Vector{Expression}
 end