Skip to content

Commit 29cd4b0

Browse files
ChrisRackauckasclaude
ChrisRackauckas
and
claude
committed
Add solver API documentation
This commit adds comprehensive documentation for the DelayDiffEq.jl solver API, similar to the documentation structure in OrdinaryDiffEq.jl. The documentation includes: - A new docs/ directory with Documenter.jl setup - Solver API reference page explaining MethodOfSteps algorithm - Algorithm selection guide for different problem types - Performance tips and usage examples - GitHub Actions workflow for automatic documentation building The documentation follows the same structure and style as OrdinaryDiffEq.jl to maintain consistency across the SciML ecosystem. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 6374a61 commit 29cd4b0

File tree

6 files changed

+241
-0
lines changed

6 files changed

+241
-0
lines changed

‎.github/workflows/Documentation.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
tags: '*'
8+
pull_request:
9+
10+
jobs:
11+
build:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
- uses: julia-actions/setup-julia@latest
16+
with:
17+
version: '1'
18+
- name: Install dependencies
19+
run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
20+
- name: Build and deploy
21+
env:
22+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
23+
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
24+
run: julia --project=docs/ docs/make.jl

‎docs/Project.toml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[deps]
2+
DelayDiffEq = "bcd4f6db-9728-5f36-b5f7-82caef46ccdb"
3+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
4+
OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
5+
Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
6+
7+
[compat]
8+
Documenter = "1"

‎docs/make.jl‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
using Documenter, DelayDiffEq
2+
3+
cp("./docs/Manifest.toml", "./docs/src/assets/Manifest.toml", force = true)
4+
cp("./docs/Project.toml", "./docs/src/assets/Project.toml", force = true)
5+
6+
include("pages.jl")
7+
8+
makedocs(
9+
sitename = "DelayDiffEq.jl",
10+
authors = "Chris Rackauckas et al.",
11+
clean = true,
12+
doctest = false,
13+
modules = [DelayDiffEq],
14+
warnonly = [:docs_block, :missing_docs, :eval_block],
15+
format = Documenter.HTML(
16+
analytics = "UA-90474609-3",
17+
canonical = "https://delaydiffeq.sciml.ai/stable/"
18+
),
19+
pages = pages
20+
)
21+
22+
deploydocs(
23+
repo = "github.com/SciML/DelayDiffEq.jl";
24+
push_preview = true
25+
)

‎docs/pages.jl‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
pages = [
2+
"DelayDiffEq.jl: DDE solvers" => "index.md",
3+
"Solver API" => "solvers/api.md"
4+
]

‎docs/src/index.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# DelayDiffEq.jl: Delay Differential Equation Solvers
2+
3+
DelayDiffEq.jl is a component package of the DifferentialEquations.jl ecosystem for solving delay differential equations (DDEs). It provides the core algorithms and method of steps implementations for solving DDEs with both constant and state-dependent delays.
4+
5+
## Features
6+
7+
- Method of steps algorithms with automatic step size control
8+
- Support for both constant and state-dependent delays
9+
- Compatible with all ODE solvers from OrdinaryDiffEq.jl
10+
- Automatic discontinuity tracking for accurate solutions
11+
- Full compatibility with the DifferentialEquations.jl common interface
12+
13+
## Installation
14+
15+
To install DelayDiffEq.jl, use the Julia package manager:
16+
17+
```julia
18+
using Pkg
19+
Pkg.add("DelayDiffEq")
20+
```
21+
22+
## Quick Example
23+
24+
```julia
25+
using DelayDiffEq, Plots
26+
27+
# Define a DDE with constant delay
28+
function bc_model(du,u,h,p,t)
29+
du[1] = 1.1/(1 + sqrt(10)*(h(p, t-20)[1])^(5/4)) - 10*u[1]/(1 + 40*u[2])
30+
du[2] = 100*u[1]/(1 + 40*u[2]) - 2.43*u[2]
31+
end
32+
33+
h(p, t) = ones(2)
34+
tspan = (0.0,100.0)
35+
u0 = [1.05767027/3, 1.030713491/3]
36+
37+
prob = DDEProblem(bc_model,u0,h,tspan; constant_lags=[20.0])
38+
sol = solve(prob,MethodOfSteps(Tsit5()))
39+
plot(sol)
40+
```
41+
42+
## Getting Started
43+
44+
For more examples and tutorials, see the [DifferentialEquations.jl DDE tutorial](https://docs.sciml.ai/DiffEqDocs/stable/tutorials/dde_example/).
45+
46+
For the list of available algorithms and their properties, see the [Solver API](@ref) documentation.

‎docs/src/solvers/api.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
```@meta
2+
CollapsedDocStrings = true
3+
```
4+
5+
# Solver API
6+
7+
DelayDiffEq.jl provides delay differential equation solvers through the method of steps approach. The core algorithm wraps ODE solvers from OrdinaryDiffEq.jl to handle the delays.
8+
9+
## Method of Steps Algorithm
10+
11+
The primary algorithm for solving delay differential equations in DelayDiffEq.jl is `MethodOfSteps`, which implements the method of steps approach for solving DDEs.
12+
13+
```@docs
14+
MethodOfSteps
15+
```
16+
17+
### Algorithm Properties
18+
19+
- **Adaptive**: Inherits adaptivity from the underlying ODE solver
20+
- **Order**: Depends on the chosen ODE algorithm
21+
- **Dense Output**: Available when the underlying ODE solver supports it
22+
- **State-Dependent Delays**: Supported through fixed-point iteration
23+
24+
## Usage
25+
26+
### Basic Usage
27+
28+
```julia
29+
using DelayDiffEq, OrdinaryDiffEq
30+
31+
# Use with any ODE solver from OrdinaryDiffEq.jl
32+
alg = MethodOfSteps(Tsit5())
33+
sol = solve(prob, alg)
34+
```
35+
36+
### Constrained vs Unconstrained
37+
38+
By default, `MethodOfSteps` is unconstrained, meaning it can take steps larger than the minimal delay using fixed-point iteration:
39+
40+
```julia
41+
# Unconstrained (default) - can take larger steps
42+
alg = MethodOfSteps(Tsit5())
43+
44+
# Constrained - steps limited to minimal delay
45+
alg = MethodOfSteps(Tsit5(); constrained = true)
46+
```
47+
48+
### Custom Fixed-Point Solver
49+
50+
For unconstrained problems, you can specify the fixed-point iteration method:
51+
52+
```julia
53+
# Use custom fixed-point solver
54+
alg = MethodOfSteps(Tsit5(); fpsolve = NLFunctional(; max_iter = 100))
55+
```
56+
57+
## Recommended Algorithms
58+
59+
The choice of underlying ODE algorithm depends on your problem characteristics:
60+
61+
### Non-Stiff Problems
62+
63+
For non-stiff delay differential equations:
64+
65+
- **`MethodOfSteps(Tsit5())`**: Good general purpose solver (5th order)
66+
- **`MethodOfSteps(BS3())`**: For lower accuracy requirements (3rd order)
67+
- **`MethodOfSteps(Vern6())`**: For high accuracy requirements (6th order)
68+
- **`MethodOfSteps(Vern9())`**: For very high accuracy requirements (9th order)
69+
70+
### Stiff Problems
71+
72+
For stiff delay differential equations:
73+
74+
- **`MethodOfSteps(Rosenbrock23())`**: Good for mildly stiff problems
75+
- **`MethodOfSteps(Rodas4())`**: General purpose stiff solver
76+
- **`MethodOfSteps(Rodas5())`**: High accuracy stiff solver
77+
- **`MethodOfSteps(KenCarp4())`**: Good stability properties
78+
79+
### Low Storage Requirements
80+
81+
For problems with memory constraints:
82+
83+
- **`MethodOfSteps(SSPRK104())`**: Strong stability preserving, low storage
84+
- **`MethodOfSteps(OwrenZen3())`**: 3rd order low storage
85+
- **`MethodOfSteps(OwrenZen5())`**: 5th order low storage
86+
87+
## Algorithm Selection Guide
88+
89+
### Step 1: Determine Stiffness
90+
91+
First, determine if your DDE is stiff. Signs of stiffness include:
92+
- Explicit methods require very small time steps
93+
- The solution has multiple time scales
94+
- There are rapid transients followed by slow dynamics
95+
96+
### Step 2: Choose Tolerance
97+
98+
- **High tolerance (>1e-2)**: Use lower order methods
99+
- **Medium tolerance (1e-8 to 1e-2)**: Use standard 4-5 order methods
100+
- **Low tolerance (<1e-8)**: Use high order methods
101+
102+
### Step 3: Consider Problem Structure
103+
104+
- **Discontinuous forcing**: Use low order methods or constrained stepping
105+
- **State-dependent delays**: May benefit from constrained stepping
106+
- **Conservation properties needed**: Consider symplectic integrators
107+
108+
### Example Selection
109+
110+
```julia
111+
# Non-stiff problem with medium accuracy
112+
alg = MethodOfSteps(Tsit5())
113+
114+
# Stiff problem with medium accuracy
115+
alg = MethodOfSteps(Rodas4())
116+
117+
# High accuracy non-stiff problem
118+
alg = MethodOfSteps(Vern9())
119+
120+
# Problem with frequent discontinuities
121+
alg = MethodOfSteps(BS3(); constrained = true)
122+
```
123+
124+
## Performance Tips
125+
126+
1. **Use constrained stepping** when delays are much smaller than the timescale of the solution
127+
2. **Choose higher order methods** for smooth problems with stringent accuracy requirements
128+
3. **Use lower order methods** when the solution has many discontinuities
129+
4. **Monitor the number of fixed-point iterations** for unconstrained problems with state-dependent delays
130+
131+
## See Also
132+
133+
- [OrdinaryDiffEq.jl Solver Documentation](https://docs.sciml.ai/OrdinaryDiffEq/stable/) for details on the underlying ODE solvers
134+
- [DifferentialEquations.jl DDE Tutorial](https://docs.sciml.ai/DiffEqDocs/stable/tutorials/dde_example/) for comprehensive examples

0 commit comments

Comments
 (0)