Skip to content

Commit eba9d49

Browse files
ChrisRackauckasChrisRackauckas
committed
make a complete documentation
1 parent c0d5167 commit eba9d49

14 files changed

+205
-75
lines changed

‎.github/workflows/Documentation.yml

+25
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

+10-75
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

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
build/
2+
site/

‎docs/Project.toml

+6
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

+31
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

+3
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

+5
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

+9
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.

‎docs/src/index.md

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# NonlinearSolve.jl: High-Performance Unified Nonlinear Solvers
2+
3+
NonlinearSolve.jl is a unified interface for the nonlinear solving packages of
4+
Julia. It includes its own high-performance nonlinear solvers which include the
5+
ability to swap out to fast direct and iterative linear solvers, along with the
6+
ability to use sparse automatic differentiation for Jacobian construction and
7+
Jacobian-vector products. It interfaces with other packages of the Julia ecosystem
8+
to make it easy to test alternative solver packages and pass small types to
9+
control algorithm swapping. It also interfaces with the
10+
[ModelingToolkit.jl](https://mtk.sciml.ai/dev/) world of symbolic modeling to
11+
allow for automatically generating high-performance code.
12+
13+
Performance is key: the current methods are made to be highly performant on
14+
scalar and statically sized small problems, with options for large-scale systems.
15+
If you run into any performance issues, please file an issue. Note that this
16+
package is distinct from [SciMLNLSolve.jl](https://github.com/SciML/SciMLNLSolve.jl).
17+
Consult the [NonlinearSystemSolvers](@ref nonlinearsystemsolvers) page for
18+
information on how to import solvers from different packages.
19+
20+
## Installation
21+
22+
To install NonlinearSolve.jl, use the Julia package manager:
23+
24+
```julia
25+
using Pkg
26+
Pkg.add("NonlinearSolve")
27+
```
28+
29+
## Contributing
30+
31+
- Please refer to the
32+
[SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
33+
for guidance on PRs, issues, and other matters relating to contributing to ModelingToolkit.
34+
- There are a few community forums:
35+
- the #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/)
36+
- [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter
37+
- on the Julia Discourse forums (look for the [modelingtoolkit tag](https://discourse.julialang.org/tag/modelingtoolkit)
38+
- see also [SciML Community page](https://sciml.ai/community/)
39+
40+
## Roadmap
41+
42+
The current algorithms should support automatic differentiation, though improved
43+
adjoint overloads are planned to be added in the current update (which will make
44+
use of the `f(u,p)` form). Future updates will include standard methods for
45+
larger scale nonlinear solving like Newton-Krylov methods.

‎docs/src/solvers/IntegralSolvers.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Integral Solver Algorithms
2+
3+
The following algorithms are available:
4+
5+
- `QuadGKJL`: Uses QuadGK.jl. Requires `nout=1` and `batch=0`.
6+
- `HCubatureJL`: Uses HCubature.jl. Requires `batch=0`.
7+
- `VEGAS`: Uses MonteCarloIntegration.jl. Requires `nout=1`.
8+
- `CubatureJLh`: h-Cubature from Cubature.jl. Requires `using IntegralsCubature`.
9+
- `CubatureJLp`: p-Cubature from Cubature.jl. Requires `using IntegralsCubature`.
10+
- `CubaVegas`: Vegas from Cuba.jl. Requires `using IntegralsCuba`.
11+
- `CubaSUAVE`: SUAVE from Cuba.jl. Requires `using IntegralsCuba`.
12+
- `CubaDivonne`: Divonne from Cuba.jl. Requires `using IntegralsCuba`.
13+
- `CubaCuhre`: Cuhre from Cuba.jl. Requires `using IntegralsCuba`.

‎docs/src/tutorials/differentiating_integrals.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Differentiating Integrals
2+
3+
Integrals.jl is a fully differentiable quadrature library. Thus, it adds the
4+
ability to perform automatic differentiation over any of the libraries that it
5+
calls. It integrates with ForwardDiff.jl for forward-mode automatic differentiation
6+
and Zygote.jl for reverse-mode automatic differentiation. For example:
7+
8+
```julia
9+
using Integrals, ForwardDiff, FiniteDiff, Zygote, Cuba
10+
f(x,p) = sum(sin.(x .* p))
11+
lb = ones(2)
12+
ub = 3ones(2)
13+
p = [1.5,2.0]
14+
15+
function testf(p)
16+
prob = IntegralProblem(f,lb,ub,p)
17+
sin(solve(prob,CubaCuhre(),reltol=1e-6,abstol=1e-6)[1])
18+
end
19+
dp1 = Zygote.gradient(testf,p)
20+
dp2 = FiniteDiff.finite_difference_gradient(testf,p)
21+
dp3 = ForwardDiff.gradient(testf,p)
22+
dp1[1] ≈ dp2 ≈ dp3
23+
```

‎docs/src/tutorials/numerical_integrals.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Numerically Solving Integrals
2+
3+
For basic multidimensional quadrature we can construct and solve a `IntegralProblem`:
4+
5+
```julia
6+
using Integrals
7+
f(x,p) = sum(sin.(x))
8+
prob = IntegralProblem(f,ones(2),3ones(2))
9+
sol = solve(prob,HCubatureJL(),reltol=1e-3,abstol=1e-3)
10+
```
11+
12+
If we would like to parallelize the computation, we can use the batch interface
13+
to compute multiple points at once. For example, here we do allocation-free
14+
multithreading with Cubature.jl:
15+
16+
```julia
17+
using Integrals, Cubature, Base.Threads
18+
function f(dx,x,p)
19+
Threads.@threads for i in 1:size(x,2)
20+
dx[i] = sum(sin.(@view(x[:,i])))
21+
end
22+
end
23+
prob = IntegralProblem(f,ones(2),3ones(2),batch=2)
24+
sol = solve(prob,CubatureJLh(),reltol=1e-3,abstol=1e-3)
25+
```
26+
27+
If we would like to compare the results against Cuba.jl's `Cuhre` method, then
28+
the change is a one-argument change:
29+
30+
```julia
31+
using IntegralsCuba
32+
sol = solve(prob,CubaCuhre(),reltol=1e-3,abstol=1e-3)
33+
```

0 commit comments

Comments
 (0)