Skip to content

Commit 3442efe

Browse files
ChrisRackauckasChrisRackauckas
committed
Create a real documentation
1 parent 1beb826 commit 3442efe

File tree

10 files changed

+201
-123
lines changed

10 files changed

+201
-123
lines changed

‎.github/workflows/Documentation.yml‎

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

‎README.md‎

Lines changed: 16 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -8,133 +8,26 @@
88
ParameterizedFunctions.jl is a component of the SciML ecosystem which allows
99
for easily defining parameterized ODE models in a simple syntax.
1010

11-
## Basic Usage
11+
## Tutorials and Documentation
1212

13-
### ODE Macros
13+
For information on using the package,
14+
[see the stable documentation](https://parameterizedfunctions.sciml.ai/stable/). Use the
15+
[in-development documentation](https://parameterizedfunctions.sciml.ai/dev/) for the version of
16+
the documentation, which contains the unreleased features.
1417

15-
A helper macro is provided to make it easier to define a `ParameterizedFunction`,
16-
and it will symbolically compute a bunch of extra functions to make the differential
17-
equation solvers run faster. For example, to define the previous `LotkaVolterra`,
18-
you can use the following command:
18+
## Example
1919

20-
```julia
21-
f = @ode_def LotkaVolterra begin
22-
dx = a*x - b*x*y
23-
dy = -c*y + d*x*y
24-
end a b c d
25-
```
26-
27-
or you can define it anonymously:
20+
The following are valid ODE definitions.
2821

2922
```julia
3023
f = @ode_def begin
31-
dx = a*x - b*x*y
32-
dy = -c*y + d*x*y
33-
end a b c d
34-
```
35-
36-
The macro also defines the Jacobian `f'`. This is defined as an in-place Jacobian `f(Val{:jac},t,u,J)`.
37-
This is calculated using SymEngine.jl automatically, so it's no effort on your part.
38-
The symbolic inverse of the Jacobian is also computed, and an in-place function
39-
for this is available as well as `f(Val{:invjac},t,u,iJ)`. If the Jacobians cannot be
40-
computed, a warning is thrown and only the function itself is usable. The functions
41-
`jac_exists(f)` and `invjac_exists(f)` can be used to see whether the Jacobian
42-
and the function for its inverse exist.
43-
44-
#### Extra Options
45-
46-
In most cases the `@ode_def` macro should be sufficient. This is because by default
47-
the macro will simply calculate each function symbolically, and if it can't it
48-
will simply throw a warning and move on. However, in extreme cases the symbolic
49-
calculations may take a long time, in which case it is necessary to turn them
50-
off. To do this, use the `ode_def_opts` function. The `@ode_def` macro simply defines the specifiable options:
51-
52-
```julia
53-
opts = Dict{Symbol,Bool}(
54-
:build_tgrad => true,
55-
:build_jac => true,
56-
:build_expjac => false,
57-
:build_invjac => true,
58-
:build_invW => true,
59-
:build_invW_t => true,
60-
:build_hes => false,
61-
:build_invhes => false,
62-
:build_dpfuncs => true)
63-
```
64-
65-
and calls the function `ode_def_opts(name::Symbol,opts,ex::Expr,params)`. Note that
66-
params is an iterator holding expressions for the parameters.
24+
dy₁ = -k₁*y₁+k₃*y₂*y₃
25+
dy₂ = k₁*y₁-k₂*y₂^2-k₃*y₂*y₃
26+
dy₃ = k₂*y₂^2
27+
end k₁ k₂ k₃
6728

68-
In addition, one can also use their own function inside of the macro. For example:
69-
70-
```julia
71-
f(x,y,d) = erf(x*y/d)
72-
NJ = @ode_def FuncTest begin
73-
dx = a*x - b*x*y
74-
dy = -c*y + f(x,y,d)
75-
end a b c d
76-
```
77-
78-
will do fine. The symbolic derivatives will not work unless you define a derivative
79-
for `f`.
80-
81-
#### Extra Macros
82-
83-
Instead of using `ode_def_opts` directly, one can use one of the following macros
84-
to be more specific about what to not calculate. In increasing order of calculations:
85-
86-
```julia
87-
@ode_def_bare
88-
@ode_def
89-
@ode_def_all
90-
```
91-
92-
### Extra Functions
93-
94-
#### Jacobian Function
95-
96-
The Jacobian overload is provided by overloading in the following manner:
97-
98-
```julia
99-
function (p::LotkaVolterra)(::Type{Val{:jac}},t,u,J)
100-
J[1,1] = p.a - p.b * u[2]
101-
J[1,2] = -(p.b) * u[1]
102-
J[2,1] = 1 * u[2]
103-
J[2,2] = -3 + u[1]
104-
nothing
105-
end
106-
```
107-
108-
#### Inverse Jacobian
109-
110-
The Inverse Jacobian overload is provided by overloading in the following manner:
111-
112-
```julia
113-
function (p::LotkaVolterra)(::Type{Val{:invjac}},t,u,J)
114-
J[1,1] = (1 - (p.b * u[1] * u[2]) / ((p.a - p.b * u[2]) * (-3 + u[1] + (p.b * u[1] * u[2]) / (p.a - p.b * u[2])))) / (p.a - p.b * u[2])
115-
J[1,2] = (p.b * u[1]) / ((p.a - p.b * u[2]) * (-3 + u[1] + (p.b * u[1] * u[2]) / (p.a - p.b * u[2])))
116-
J[2,1] = -(u[2]) / ((p.a - p.b * u[2]) * (-3 + u[1] + (p.b * u[1] * u[2]) / (p.a - p.b * u[2])))
117-
J[2,2] = (-3 + u[1] + (p.b * u[1] * u[2]) / (p.a - p.b * u[2])) ^ -1
118-
nothing
119-
end
120-
```
121-
122-
#### Parameter Jacobian
123-
124-
For solvers which need parameters derivatives, specifying the functions can increase
125-
performance. For our example, we allow the solvers to use the explicit derivatives
126-
in the parameters by:
127-
128-
```julia
129-
function (p::LotkaVolterra)(::Type{Val{:paramjac}},J,u,p,t)
130-
J[1, 1] = u[1] * 1
131-
J[1, 2] = -(u[1]) * u[2]
132-
J[1, 3] = 0 * 1
133-
J[1, 4] = 0 * 1
134-
J[2, 1] = 0 * 1
135-
J[2, 2] = 0 * 1
136-
J[2, 3] = -(u[2])
137-
J[2, 4] = u[1] * u[2]
138-
nothing
139-
end
140-
```
29+
f = @ode_def begin
30+
d🐁 = α*🐁 - β*🐁*🐈
31+
d🐈 = -γ*🐈 + δ*🐁*🐈
32+
end α β γ δ
33+
```

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
build/
2+
site/

‎docs/Project.toml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[deps]
2+
RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
3+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
4+
5+
[compat]
6+
Documenter = "0.27"

‎docs/make.jl‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
using Documenter, ParameterizedFunctions
2+
3+
include("pages.jl")
4+
5+
makedocs(
6+
sitename="ParameterizedFunctions.jl",
7+
authors="Chris Rackauckas",
8+
modules=[ParameterizedFunctions],
9+
clean=true,doctest=false,
10+
format = Documenter.HTML(analytics = "UA-90474609-3",
11+
assets = ["assets/favicon.ico"],
12+
canonical="https://parameterizedfunctions.sciml.ai/stable/"),
13+
pages=pages
14+
)
15+
16+
deploydocs(
17+
repo = "github.com/SciML/ParameterizedFunctions.jl.git";
18+
push_preview = true
19+
)

‎docs/pages.jl‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Put in a separate page so it can be used by SciMLDocs.jl
2+
3+
pages=[
4+
"Home" => "index.md",
5+
"ode_def.md",
6+
]

‎docs/src/index.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# ParameterizedFunctions.jl: Simple High Level ODE Definitions
2+
3+
ParameterizedFunctions.jl is a component of the SciML ecosystem which allows
4+
for easily defining parameterized ODE models in a simple syntax.
5+
6+
## Installation
7+
8+
To install ParameterizedFunctions.jl, use the Julia package manager:
9+
10+
```julia
11+
using Pkg
12+
Pkg.add("ParameterizedFunctions")
13+
```
14+
15+
## Contributing
16+
17+
- Please refer to the
18+
[SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
19+
for guidance on PRs, issues, and other matters relating to contributing to SciML.
20+
- There are a few community forums:
21+
- the #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/)
22+
- [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter
23+
- on the [Julia Discourse forums](https://discourse.julialang.org)
24+
- see also [SciML Community page](https://sciml.ai/community/)

‎docs/src/ode_def.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# The ode_def macro
2+
3+
```@docs
4+
ParameterizedFunctions.@ode_def
5+
ParameterizedFunctions.@ode_def_bare
6+
ParameterizedFunctions.@ode_def_all
7+
```
8+
9+
## Internal API
10+
11+
```@docs
12+
ParameterizedFunctions.ode_def_opts
13+
```

‎src/macros.jl‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,37 @@
1+
"""
2+
```
3+
@ode_def name begin
4+
differential equation
5+
end parameters :: ODEFunction
6+
```
7+
8+
## Definition of the Domain-Specific Language (DSL)
9+
10+
A helper macro is provided to make it easier to define a `ParameterizedFunction`,
11+
and it will symbolically compute a bunch of extra functions to make the differential
12+
equation solvers run faster. For example, to define the previous `LotkaVolterra`,
13+
you can use the following command:
14+
15+
```julia
16+
f = @ode_def LotkaVolterra begin
17+
dx = a*x - b*x*y
18+
dy = -c*y + d*x*y
19+
end a b c d
20+
```
21+
22+
or you can define it anonymously:
23+
24+
```julia
25+
f = @ode_def begin
26+
dx = a*x - b*x*y
27+
dy = -c*y + d*x*y
28+
end a b c d
29+
```
30+
31+
`@ode_def` uses ModelingToolkit.jl internally and returns an `ODEFunction` with the
32+
extra definitions (Jacobian, parameter Jacobian, etc.) defined through the MTK
33+
symbolic tools.
34+
"""
135
macro ode_def(name,ex,params...)
236
opts = Dict{Symbol,Bool}(
337
:build_tgrad => true,
@@ -12,6 +46,16 @@ macro ode_def(name,ex,params...)
1246
ode_def_opts(name,opts,__module__,ex,params...)
1347
end
1448

49+
"""
50+
```
51+
@ode_def_bare name begin
52+
differential equation
53+
end parameters :: ODEFunction
54+
```
55+
56+
Like `@ode_def` but the `opts` options are set so that no symbolic functions are generated.
57+
See the `@ode_def` docstring for more details.
58+
"""
1559
macro ode_def_bare(name,ex,params...)
1660
opts = Dict{Symbol,Bool}(
1761
:build_tgrad => false,
@@ -26,6 +70,16 @@ macro ode_def_bare(name,ex,params...)
2670
ode_def_opts(name,opts,__module__,ex,params...)
2771
end
2872

73+
"""
74+
```
75+
@ode_def_all name begin
76+
differential equation
77+
end parameters :: ODEFunction
78+
```
79+
80+
Like `@ode_def` but the `opts` options are set so that all possible symbolic functions are generated.
81+
See the `@ode_def` docstring for more details.
82+
"""
2983
macro ode_def_all(name,ex,params...)
3084
opts = Dict{Symbol,Bool}(
3185
:build_tgrad => true,

‎src/ode_def_opts.jl‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,42 @@ function findreplace(ex::Expr, dict)
44
end
55
findreplace(ex, dict) = ex
66

7+
"""
8+
```julia
9+
ode_def_opts(name::Symbol,opts::Dict{Symbol,Bool},curmod,ex::Expr,params...;depvar=:t)
10+
```
11+
12+
The core internal. Users should only interact with this through the `@ode_def_*` macros.
13+
14+
Options are self-explanatory by name mapping to `ODEFunction`:
15+
16+
- build_tgrad
17+
- build_jac
18+
- build_expjac
19+
- build_invjac
20+
- build_invW
21+
- build_invW_t
22+
- build_hes
23+
- build_invhes
24+
- build_dpfuncs
25+
26+
`depvar` sets the symbol for the dependent variable.
27+
28+
Example:
29+
30+
```julia
31+
opts = Dict{Symbol,Bool}(
32+
:build_tgrad => true,
33+
:build_jac => true,
34+
:build_expjac => false,
35+
:build_invjac => true,
36+
:build_invW => true,
37+
:build_invW_t => true,
38+
:build_hes => false,
39+
:build_invhes => false,
40+
:build_dpfuncs => true)
41+
```
42+
"""
743
function ode_def_opts(name::Symbol,opts::Dict{Symbol,Bool},curmod,ex::Expr,params...;depvar=:t)
844
# depvar is the dependent variable. Defaults to t
945
# M is the mass matrix in RosW, must be a constant!

0 commit comments

Comments
 (0)