Skip to content

Commit eba9d49

Browse files
make a complete documentation
1 parent c0d5167 commit eba9d49

File tree

14 files changed

+205
-75
lines changed

14 files changed

+205
-75
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: 10 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# Integrals.jl
22

33
[![Build Status](https://github.com/SciML/Integrals.jl/workflows/CI/badge.svg)](https://github.com/SciML/Integrals.jl/actions?query=workflow%3ACI)
4+
[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](http://integrals.sciml.ai/stable/)
5+
[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](http://integrals.sciml.ai/dev/)
46

57
Integrals.jl is an instantiation of the SciML common `IntegralProblem`
68
interface for the common quadrature packages of Julia. By using Integrals.jl,
@@ -9,6 +11,13 @@ standardized throughout the various integrator libraries. This can be useful
911
for benchmarking or for library implementations, since libraries which internally
1012
use a quadrature can easily accept a quadrature method as an argument.
1113

14+
## Tutorials and Documentation
15+
16+
For information on using the package,
17+
[see the stable documentation](https://integrals.sciml.ai/stable/). Use the
18+
[in-development documentation](https://integrals.sciml.ai/dev/) for the version of
19+
the documentation, which contains the unreleased features.
20+
1221
## Examples
1322

1423
For basic multidimensional quadrature we can construct and solve a `IntegralProblem`:
@@ -41,78 +50,4 @@ the change is a one-argument change:
4150
```julia
4251
using IntegralsCuba
4352
sol = solve(prob,CubaCuhre(),reltol=1e-3,abstol=1e-3)
44-
```
45-
46-
## Differentiability
47-
48-
Integrals.jl is a fully differentiable quadrature library. Thus, it adds the
49-
ability to perform automatic differentiation over any of the libraries that it
50-
calls. It integrates with ForwardDiff.jl for forward-mode automatic differentiation
51-
and Zygote.jl for reverse-mode automatic differentiation. For example:
52-
53-
```julia
54-
using Integrals, ForwardDiff, FiniteDiff, Zygote, Cuba
55-
f(x,p) = sum(sin.(x .* p))
56-
lb = ones(2)
57-
ub = 3ones(2)
58-
p = [1.5,2.0]
59-
60-
function testf(p)
61-
prob = IntegralProblem(f,lb,ub,p)
62-
sin(solve(prob,CubaCuhre(),reltol=1e-6,abstol=1e-6)[1])
63-
end
64-
dp1 = Zygote.gradient(testf,p)
65-
dp2 = FiniteDiff.finite_difference_gradient(testf,p)
66-
dp3 = ForwardDiff.gradient(testf,p)
67-
dp1[1] dp2 dp3
68-
```
69-
70-
## IntegralProblem
71-
72-
To use this package, you always construct a `IntegralProblem`. This has a
73-
constructor:
74-
75-
```julia
76-
IntegralProblem(f,lb,ub,p=NullParameters();
77-
nout=1, batch = 0, kwargs...)
78-
```
79-
80-
- `f`: Either a function `f(x,p)` for out-of-place or `f(dx,x,p)` for in-place.
81-
- `lb`: Either a number or vector of lower bounds.
82-
- `ub`: Either a number or vector of upper bounds.
83-
- `p`: The parameters associated with the problem.
84-
- `nout`: The output size of the function `f`. Defaults to `1`, i.e., a scalar
85-
integral output.
86-
- `batch`: The preferred number of points to batch. This allows user-side
87-
parallelization of the integrand. If `batch != 0`, then each `x[:,i]` is a
88-
different point of the integral to calculate, and the output should be
89-
`nout x batchsize`. Note that `batch` is a suggestion for the number of points,
90-
and it is not necessarily true that `batch` is the same as `batchsize` in all
91-
algorithms.
92-
93-
Additionally, we can supply `iip` like `IntegralProblem{iip}(...)` as true or
94-
false to declare at compile time whether the integrator function is in-place.
95-
96-
## Algorithms
97-
98-
The following algorithms are available:
99-
100-
- `QuadGKJL`: Uses QuadGK.jl. Requires `nout=1` and `batch=0`.
101-
- `HCubatureJL`: Uses HCubature.jl. Requires `batch=0`.
102-
- `VEGAS`: Uses MonteCarloIntegration.jl. Requires `nout=1`.
103-
- `CubatureJLh`: h-Cubature from Cubature.jl. Requires `using IntegralsCubature`.
104-
- `CubatureJLp`: p-Cubature from Cubature.jl. Requires `using IntegralsCubature`.
105-
- `CubaVegas`: Vegas from Cuba.jl. Requires `using IntegralsCuba`.
106-
- `CubaSUAVE`: SUAVE from Cuba.jl. Requires `using IntegralsCuba`.
107-
- `CubaDivonne`: Divonne from Cuba.jl. Requires `using IntegralsCuba`.
108-
- `CubaCuhre`: Cuhre from Cuba.jl. Requires `using IntegralsCuba`.
109-
110-
## Common Solve Keyword Arguments
111-
112-
- `reltol`: Relative tolerance
113-
- `abstol`: Absolute tolerance
114-
- `maxiters`: The maximum number of iterations
115-
116-
Additionally, the extra keyword arguments are splatted to the library calls, so
117-
see the documentation of the integrator library for all of the extra details.
118-
These extra keyword arguments are not guaranteed to act uniformly.
53+
```

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+
NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
3+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
4+
5+
[compat]
6+
Documenter = "0.27"

docs/make.jl

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
using Documenter, Integrals
2+
3+
makedocs(
4+
sitename="Integrals.jl",
5+
authors="Chris Rackauckas",
6+
modules=[Integrals,Integrals.SciMLBase],
7+
clean=true,doctest=false,
8+
format = Documenter.HTML(analytics = "UA-90474609-3",
9+
assets = ["assets/favicon.ico"],
10+
canonical="https://integrals.sciml.ai/stable/"),
11+
pages=[
12+
"Home" => "index.md",
13+
"Tutorials" => Any[
14+
"tutorials/numerical_integrals.md",
15+
"tutorials/differentiating_integrals.md"
16+
],
17+
"Basics" => Any[
18+
"basics/IntegralProblem.md",
19+
"basics/FAQ.md"
20+
],
21+
"Solvers" => Any[
22+
"solvers/NonlinearSystemSolvers.md",
23+
"solvers/BracketingSolvers.md"
24+
]
25+
]
26+
)
27+
28+
deploydocs(
29+
repo = "github.com/SciML/Integrals.jl.git";
30+
push_preview = true
31+
)

docs/src/assets/favicon.ico

1.36 KB
Binary file not shown.

docs/src/assets/logo.png

26 KB
Loading

docs/src/basics/FAQ.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Frequently Asked Questions
2+
3+
Ask more questions.

docs/src/basics/IntegralProblem.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Integral Problems
2+
3+
```@docs
4+
IntegralProblem
5+
```

docs/src/basics/solve.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Common Solver Options (Solve Keyword Arguments)
2+
3+
- `reltol`: Relative tolerance
4+
- `abstol`: Absolute tolerance
5+
- `maxiters`: The maximum number of iterations
6+
7+
Additionally, the extra keyword arguments are splatted to the library calls, so
8+
see the documentation of the integrator library for all of the extra details.
9+
These extra keyword arguments are not guaranteed to act uniformly.

0 commit comments

Comments
 (0)