Add docstrings for all of the problem types

Project.toml

@@ -12,6 +12,7 @@ DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 IteratorInterfaceExtensions = "82899510-4779-5014-852e-03e436cf321d"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
+Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
 RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"

src/SciMLBase.jl

@@ -7,6 +7,7 @@ using LinearAlgebra
 using Statistics
 using Distributed
 using StaticArrays
+using Markdown
 
 import Logging, ArrayInterface
 import IteratorInterfaceExtensions

src/problems/bvp_problems.jl

@@ -3,8 +3,73 @@ $(TYPEDEF)
 """
 struct StandardBVProblem end
 
-"""
+@doc doc"""
 $(TYPEDEF)
+
+Defines an BVP problem.
+Documentation Page: https://diffeq.sciml.ai/stable/types/bvp_types/
+
+## Mathematical Specification of a BVP Problem
+
+To define a BVP Problem, you simply need to give the function ``f`` and the initial
+condition ``u₀`` which define an ODE:
+
+```math
+\frac{du}{dt} = f(u,p,t)
+```
+
+along with an implicit function `bc!` which defines the residual equation, where
+
+```math
+bc(u,p,t) = 0
+```
+
+is the manifold on which the solution must live. A common form for this is the
+two-point `BVProblem` where the manifold defines the solution at two points:
+
+```math
+u(t_0) = a
+u(t_f) = b
+```
+
+## Problem Type
+
+### Constructors
+
+```julia
+TwoPointBVProblem{isinplace}(f,bc!,u0,tspan,p=NullParameters();kwargs...)
+BVProblem{isinplace}(f,bc!,u0,tspan,p=NullParameters();kwargs...)
+```
+
+For any BVP problem type, `bc!` is the inplace function:
+
+```julia
+bc!(residual, u, p, t)
+```
+
+where `residual` computed from the current `u`. `u` is an array of solution values
+where `u[i]` is at time `t[i]`, while `p` are the parameters. For a `TwoPointBVProblem`,
+`t = tspan`. For the more general `BVProblem`, `u` can be all of the internal
+time points, and for shooting type methods `u=sol` the ODE solution.
+Note that all features of the `ODESolution` are present in this form.
+In both cases, the size of the residual matches the size of the initial condition.
+
+Parameters are optional, and if not given then a `NullParameters()` singleton
+will be used which will throw nice errors if you try to index non-existent
+parameters. Any extra keyword arguments are passed on to the solvers. For example,
+if you set a `callback` in the problem, then that `callback` will be added in
+every solve call.
+
+### Fields
+
+* `f`: The function for the ODE.
+* `bc`: The boundary condition function.
+* `u0`: The initial condition. Either the initial condition for the ODE as an
+  initial value problem, or a `Vector` of values for ``u(t_i)`` for collocation
+  methods
+* `tspan`: The timespan for the problem.
+* `p`: The parameters for the problem. Defaults to `NullParameters`
+* `kwargs`: The keyword arguments passed onto the solves.
 """
 struct BVProblem{uType,tType,isinplace,P,F,bF,PT,K} <: AbstractBVProblem{uType,tType,isinplace}
     f::F

src/problems/dae_problems.jl

@@ -1,6 +1,70 @@
-# f(t,u,du,res) = 0
-"""
+@doc doc"""
 $(TYPEDEF)
+
+Defines an implicit ordinary differential equation (ODE) or 
+differential-algebraic equation (DAE) problem.
+Documentation Page: https://diffeq.sciml.ai/stable/types/dae_types/
+
+## Mathematical Specification of an DAE Problem
+
+To define a DAE Problem, you simply need to give the function ``f`` and the initial
+condition ``u₀`` which define an ODE:
+
+```math
+0 = f(du,u,p,t)
+```
+
+`f` should be specified as `f(du,u,p,t)` (or in-place as `f(resid,du,u,p,t)`).
+Note that we are not limited to numbers or vectors for `u₀`; one is allowed to
+provide `u₀` as arbitrary matrices / higher dimension tensors as well.
+
+## Problem Type
+
+### Constructors
+
+- `DAEProblem(f::DAEFunction,du0,u0,tspan,p=NullParameters();kwargs...)`
+- `DAEProblem{isinplace}(f,du0,u0,tspan,p=NullParameters();kwargs...)` :
+  Defines the DAE with the specified functions.
+  `isinplace` optionally sets whether the function is inplace or not. This is
+  determined automatically, but not inferred.
+
+Parameters are optional, and if not given then a `NullParameters()` singleton
+will be used which will throw nice errors if you try to index non-existent
+parameters. Any extra keyword arguments are passed on to the solvers. For example,
+if you set a `callback` in the problem, then that `callback` will be added in
+every solve call.
+
+For specifying Jacobians and mass matrices, see the
+[DiffEqFunctions](@ref performance_overloads)
+page.
+
+### Fields
+
+* `f`: The function in the ODE.
+* `du0`: The initial condition for the derivative.
+* `u0`: The initial condition.
+* `tspan`: The timespan for the problem.
+* `differential_vars`: A logical array which declares which variables are the
+  differential (non algebraic) vars (i.e. `du'` is in the equations for this
+  variable). Defaults to nothing. Some solvers may require this be set if an
+  initial condition needs to be determined.
+* `p`: The parameters for the problem. Defaults to `NullParameters`
+* `kwargs`: The keyword arguments passed onto the solves.
+
+## Example Problems
+
+Examples problems can be found in [DiffEqProblemLibrary.jl](https://github.com/JuliaDiffEq/DiffEqProblemLibrary.jl/blob/master/src/dae_premade_problems.jl).
+
+To use a sample problem, such as `prob_dae_resrob`, you can do something like:
+
+```julia
+#] add DiffEqProblemLibrary
+using DiffEqProblemLibrary.DAEProblemLibrary
+# load problems
+DAEProblemLibrary.importdaeproblems()
+prob = DAEProblemLibrary.prob_dae_resrob
+sol = solve(prob,IDA())
+```
 """
 struct DAEProblem{uType,duType,tType,isinplace,P,F,K,D} <: AbstractDAEProblem{uType,duType,tType,isinplace}
   f::F

src/problems/dde_problems.jl

@@ -3,8 +3,201 @@ $(TYPEDEF)
 """
 struct StandardDDEProblem end
 
-"""
+@doc doc"""
 $(TYPEDEF)
+
+Defines a delay differential equation (DDE) problem.
+Documentation Page: https://diffeq.sciml.ai/stable/types/dde_types/
+
+## Mathematical Specification of a DDE Problem
+
+To define a DDE Problem, you simply need to give the function ``f``, the initial
+condition ``u_0`` at time point ``t_0``, and the history function ``h``
+which together define a DDE:
+
+```math
+\frac{du}{dt} = f(u,h,p,t) \qquad (t \geq t_0)
+```
+```math
+u(t_0) = u_0,
+```
+```math
+u(t) = h(t) \qquad (t < t_0).
+```
+
+``f`` should be specified as `f(u, h, p, t)` (or in-place as `f(du, u, h, p, t)`),
+``u_0`` should be an AbstractArray (or number) whose geometry matches the
+desired geometry of `u`, and ``h`` should be specified as described below. The
+history function `h` is accessed for all delayed values. Note that we are not
+limited to numbers or vectors for ``u_0``; one is allowed to provide ``u_0``
+as arbitrary matrices / higher dimension tensors as well.
+
+## Functional Forms of the History Function
+
+The history function `h` can be called in the following ways:
+
+- `h(p, t)`: out-of-place calculation
+- `h(out, p, t)`: in-place calculation
+- `h(p, t, deriv::Type{Val{i}})`: out-of-place calculation of the `i`th derivative
+- `h(out, p, t, deriv::Type{Val{i}})`: in-place calculation of the `i`th derivative
+- `h(args...; idxs)`: calculation of `h(args...)` for indices `idxs`
+
+Note that a dispatch for the supplied history function of matching form is required
+for whichever function forms are used in the user derivative function `f`.
+
+## Declaring Lags
+
+Lags are declared separately from their use. One can use any lag by simply using
+the interpolant of `h` at that point. However, one should use caution in order
+to achieve the best accuracy. When lags are declared, the solvers can more
+efficiently be more accurate and thus this is recommended.
+
+## Neutral and Retarded Delay Differential Equations
+
+Note that the history function specification can be used to specify general
+retarded arguments, i.e. `h(p,α(u,t))`. Neutral delay differential equations
+can be specified by using the `deriv` value in the history interpolation.
+For example, `h(p,t-τ, Val{1})` returns the first derivative of the history
+values at time `t-τ`.
+
+Note that algebraic equations can be specified by using a singular mass matrix.
+
+## Problem Type
+
+### Constructors
+
+```
+DDEProblem(f[, u0], h, tspan[, p]; <keyword arguments>)
+DDEProblem{isinplace}(f[, u0], h, tspan[, p]; <keyword arguments>)
+```
+
+Parameter `isinplace` optionally sets whether the function is inplace or not.
+This is determined automatically, but not inferred.
+
+Parameters are optional, and if not given then a `NullParameters()` singleton
+will be used which will throw nice errors if you try to index non-existent
+parameters. Any extra keyword arguments are passed on to the solvers. For example,
+if you set a `callback` in the problem, then that `callback` will be added in
+every solve call.
+
+For specifying Jacobians and mass matrices, see the [DiffEqFunctions](@ref performance_overloads) page.
+
+### Arguments
+
+* `f`: The function in the DDE.
+* `u0`: The initial condition. Defaults to the value `h(p, first(tspan))` of the history function evaluated at the initial time point.
+* `h`: The history function for the DDE before `t0`.
+* `tspan`: The timespan for the problem.
+* `p`: The parameters with which function `f` is called. Defaults to `NullParameters`.
+* `constant_lags`: A collection of constant lags used by the history function `h`. Defaults to `()`.
+* `dependent_lags` A tuple of functions `(u, p, t) -> lag` for the state-dependent lags
+  used by the history function `h`. Defaults to `()`.
+* `neutral`: If the DDE is neutral, i.e., if delays appear in derivative terms.
+* `order_discontinuity_t0`: The order of the discontinuity at the initial time point. Defaults to `0` if an initial condition `u0` is provided. Otherwise it is forced to be greater or equal than `1`.
+* `kwargs`: The keyword arguments passed onto the solves.
+
+## Dynamical Delay Differential Equations
+
+Much like [Dynamical ODEs](@ref dynamical_prob), a Dynamical DDE is a Partitioned DDE
+of the form:
+
+```math
+\frac{dv}{dt} = f_1(u,t,h) \\
+\frac{du}{dt} = f_2(v,h) \\
+```
+
+### Constructors
+
+```
+DynamicalDDEProblem(f1, f2[, v0, u0], h, tspan[, p]; <keyword arguments>)
+DynamicalDDEProblem{isinplace}(f1, f2[, v0, u0], h, tspan[, p]; <keyword arguments>)
+```
+Parameter `isinplace` optionally sets whether the function is inplace or not.
+This is determined automatically, but not inferred.
+
+### Arguments
+
+* `f`: The function in the DDE.
+* `v0` and `u0`: The initial condition. Defaults to the values `h(p, first(tspan))...` of the history function evaluated at the initial time point.
+* `h`: The history function for the DDE before `t0`. Must return an object with the indices 1 and 2, with the values of `v` and `u` respectively.
+* `tspan`: The timespan for the problem.
+* `p`: The parameters with which function `f` is called. Defaults to `NullParameters`.
+* `constant_lags`: A collection of constant lags used by the history function `h`. Defaults to `()`.
+* `dependent_lags` A tuple of functions `(v, u, p, t) -> lag` for the state-dependent lags
+  used by the history function `h`. Defaults to `()`.
+* `neutral`: If the DDE is neutral, i.e., if delays appear in derivative terms.
+* `order_discontinuity_t0`: The order of the discontinuity at the initial time point. Defaults to `0` if an initial condition `u0` is provided. Otherwise it is forced to be greater or equal than `1`.
+* `kwargs`: The keyword arguments passed onto the solves.
+
+The for dynamical and second order DDEs, the history function will return an object with
+the indicies 1 and 2 defined, where `h(p, t_prev)[1]` is the value of ``f_2(v, u, h, p,
+t_{\mathrm{prev}})`` and `h(p, t_prev)[2]` is the value of ``f_1(v, u, h, p, t_{\mathrm{prev}})``
+(this is for consistency with the ordering of the intitial conditions in the constructor).
+The supplied history function must also return such a 2-index object, which can be accomplished
+with a tuple `(v,u)` or vector `[v,u]`.
+
+## 2nd Order Delay Differential Equations
+
+To define a 2nd Order DDE Problem, you simply need to give the function ``f``
+and the initial condition ``u_0`` which define an DDE:
+
+```math
+u'' = f(u',u,h,p,t)
+```
+
+`f` should be specified as `f(du,u,p,t)` (or in-place as `f(ddu,du,u,p,t)`), and `u₀`
+should be an AbstractArray (or number) whose geometry matches the desired
+geometry of `u`. Note that we are not limited to numbers or vectors for `u₀`;
+one is allowed to provide `u₀` as arbitrary matrices / higher dimension tensors
+as well.
+
+From this form, a dynamical ODE:
+
+```math
+v' = f(v,u,h,p,t) \\
+u' = v \\
+```
+
+### Constructors
+
+```
+SecondOrderDDEProblem(f, [, du0, u0], h, tspan[, p]; <keyword arguments>)
+SecondOrderDDEProblem{isinplace}(f, [, du0, u0], h, tspan[, p]; <keyword arguments>)
+```
+
+Parameter `isinplace` optionally sets whether the function is inplace or not.
+This is determined automatically, but not inferred.
+
+### Arguments
+
+* `f`: The function in the DDE.
+* `du0` and `u0`: The initial condition. Defaults to the values `h(p, first(tspan))...` of the history function evaluated at the initial time point.
+* `h`: The history function for the DDE before `t0`. Must return an object with the indices 1 and 2, with the values of `v` and `u` respectively.
+* `tspan`: The timespan for the problem.
+* `p`: The parameters with which function `f` is called. Defaults to `NullParameters`.
+* `constant_lags`: A collection of constant lags used by the history function `h`. Defaults to `()`.
+* `dependent_lags` A tuple of functions `(v, u, p, t) -> lag` for the state-dependent lags
+  used by the history function `h`. Defaults to `()`.
+* `neutral`: If the DDE is neutral, i.e., if delays appear in derivative terms.
+* `order_discontinuity_t0`: The order of the discontinuity at the initial time point. Defaults to `0` if an initial condition `u0` is provided. Otherwise it is forced to be greater or equal than `1`.
+* `kwargs`: The keyword arguments passed onto the solves.
+
+As above, the history function will return an object with indices 1 and 2, with the values of `du` and `u` respectively. The supplied history function must also match this return type, e.g. by returning a 2-element tuple or vector.
+
+## Example Problems
+
+Example problems can be found in [DiffEqProblemLibrary.jl](https://github.com/JuliaDiffEq/DiffEqProblemLibrary.jl/tree/master/src/dde).
+
+To use a sample problem, such as `prob_ode_linear`, you can do something like:
+
+```julia
+#] add DiffEqProblemLibrary
+using DiffEqProblemLibrary.ODEProblemLibrary
+# load problems
+ODEProblemLibrary.importodeproblems()
+prob = ODEProblemLibrary.prob_ode_linear
+sol = solve(prob)
+```
 """
 struct DDEProblem{uType,tType,lType,lType2,isinplace,P,F,H,K,PT} <:
                           AbstractDDEProblem{uType,tType,lType,isinplace}