make a complete documentation

ChrisRackauckas · ChrisRackauckas · commit eba9d4962c2a · 2022-06-01T06:06:43.000-04:00
diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml
@@ -0,0 +1,25 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+      - 'release-'
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs/ docs/make.jl
diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
 # Integrals.jl
 
 [![Build Status](https://github.com/SciML/Integrals.jl/workflows/CI/badge.svg)](https://github.com/SciML/Integrals.jl/actions?query=workflow%3ACI)
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](http://integrals.sciml.ai/stable/)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](http://integrals.sciml.ai/dev/)
 
 Integrals.jl is an instantiation of the SciML common `IntegralProblem`
 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
 for benchmarking or for library implementations, since libraries which internally
 use a quadrature can easily accept a quadrature method as an argument.
 
+## Tutorials and Documentation
+
+For information on using the package,
+[see the stable documentation](https://integrals.sciml.ai/stable/). Use the
+[in-development documentation](https://integrals.sciml.ai/dev/) for the version of
+the documentation, which contains the unreleased features.
+
 ## Examples
 
 For basic multidimensional quadrature we can construct and solve a `IntegralProblem`:
@@ -41,78 +50,4 @@ the change is a one-argument change:
 ```julia
 using IntegralsCuba
 sol = solve(prob,CubaCuhre(),reltol=1e-3,abstol=1e-3)
-```
-
-## Differentiability
-
-Integrals.jl is a fully differentiable quadrature library. Thus, it adds the
-ability to perform automatic differentiation over any of the libraries that it
-calls. It integrates with ForwardDiff.jl for forward-mode automatic differentiation
-and Zygote.jl for reverse-mode automatic differentiation. For example:
-
-```julia
-using Integrals, ForwardDiff, FiniteDiff, Zygote, Cuba
-f(x,p) = sum(sin.(x .* p))
-lb = ones(2)
-ub = 3ones(2)
-p = [1.5,2.0]
-
-function testf(p)
-    prob = IntegralProblem(f,lb,ub,p)
-    sin(solve(prob,CubaCuhre(),reltol=1e-6,abstol=1e-6)[1])
-end
-dp1 = Zygote.gradient(testf,p)
-dp2 = FiniteDiff.finite_difference_gradient(testf,p)
-dp3 = ForwardDiff.gradient(testf,p)
-dp1[1] ≈ dp2 ≈ dp3
-```
-
-## IntegralProblem
-
-To use this package, you always construct a `IntegralProblem`. This has a
-constructor:
-
-```julia
-IntegralProblem(f,lb,ub,p=NullParameters();
-                  nout=1, batch = 0, kwargs...)
-```
-
-- `f`: Either a function `f(x,p)` for out-of-place or `f(dx,x,p)` for in-place.
-- `lb`: Either a number or vector of lower bounds.
-- `ub`: Either a number or vector of upper bounds.
-- `p`: The parameters associated with the problem.
-- `nout`: The output size of the function `f`. Defaults to `1`, i.e., a scalar
-  integral output.
-- `batch`: The preferred number of points to batch. This allows user-side
-  parallelization of the integrand. If `batch != 0`, then each `x[:,i]` is a
-  different point of the integral to calculate, and the output should be
-  `nout x batchsize`. Note that `batch` is a suggestion for the number of points,
-  and it is not necessarily true that `batch` is the same as `batchsize` in all
-  algorithms.
-
-Additionally, we can supply `iip` like `IntegralProblem{iip}(...)` as true or
-false to declare at compile time whether the integrator function is in-place.
-
-## Algorithms
-
-The following algorithms are available:
-
-- `QuadGKJL`: Uses QuadGK.jl. Requires `nout=1` and `batch=0`.
-- `HCubatureJL`: Uses HCubature.jl. Requires `batch=0`.
-- `VEGAS`: Uses MonteCarloIntegration.jl. Requires `nout=1`.
-- `CubatureJLh`: h-Cubature from Cubature.jl. Requires `using IntegralsCubature`.
-- `CubatureJLp`: p-Cubature from Cubature.jl. Requires `using IntegralsCubature`.
-- `CubaVegas`: Vegas from Cuba.jl. Requires `using IntegralsCuba`.
-- `CubaSUAVE`: SUAVE from Cuba.jl. Requires `using IntegralsCuba`.
-- `CubaDivonne`: Divonne from Cuba.jl. Requires `using IntegralsCuba`.
-- `CubaCuhre`: Cuhre from Cuba.jl. Requires `using IntegralsCuba`.
-
-## Common Solve Keyword Arguments
-
-- `reltol`: Relative tolerance
-- `abstol`: Absolute tolerance
-- `maxiters`: The maximum number of iterations
-
-Additionally, the extra keyword arguments are splatted to the library calls, so
-see the documentation of the integrator library for all of the extra details.
-These extra keyword arguments are not guaranteed to act uniformly.
+```
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,2 @@
+build/
+site/
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -0,0 +1,6 @@
+[deps]
+NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "0.27"
diff --git a/docs/make.jl b/docs/make.jl
@@ -0,0 +1,31 @@
+using Documenter, Integrals
+
+makedocs(
+    sitename="Integrals.jl",
+    authors="Chris Rackauckas",
+    modules=[Integrals,Integrals.SciMLBase],
+    clean=true,doctest=false,
+    format = Documenter.HTML(analytics = "UA-90474609-3",
+                             assets = ["assets/favicon.ico"],
+                             canonical="https://integrals.sciml.ai/stable/"),
+    pages=[
+        "Home" => "index.md",
+        "Tutorials" => Any[
+            "tutorials/numerical_integrals.md",
+            "tutorials/differentiating_integrals.md"
+        ],
+        "Basics" => Any[
+            "basics/IntegralProblem.md",
+            "basics/FAQ.md"
+        ],
+        "Solvers" => Any[
+            "solvers/NonlinearSystemSolvers.md",
+            "solvers/BracketingSolvers.md"
+        ]
+    ]
+)
+
+deploydocs(
+   repo = "github.com/SciML/Integrals.jl.git";
+   push_preview = true
+)
diff --git a/docs/src/assets/favicon.ico b/docs/src/assets/favicon.ico
diff --git a/docs/src/assets/logo.png b/docs/src/assets/logo.png
diff --git a/docs/src/basics/FAQ.md b/docs/src/basics/FAQ.md
@@ -0,0 +1,3 @@
+# Frequently Asked Questions
+
+Ask more questions.
diff --git a/docs/src/basics/IntegralProblem.md b/docs/src/basics/IntegralProblem.md
@@ -0,0 +1,5 @@
+# Integral Problems
+
+```@docs
+IntegralProblem
+```
diff --git a/docs/src/basics/solve.md b/docs/src/basics/solve.md
@@ -0,0 +1,9 @@
+# Common Solver Options (Solve Keyword Arguments)
+
+- `reltol`: Relative tolerance
+- `abstol`: Absolute tolerance
+- `maxiters`: The maximum number of iterations
+
+Additionally, the extra keyword arguments are splatted to the library calls, so
+see the documentation of the integrator library for all of the extra details.
+These extra keyword arguments are not guaranteed to act uniformly.
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -0,0 +1,45 @@
+# NonlinearSolve.jl: High-Performance Unified Nonlinear Solvers
+
+NonlinearSolve.jl is a unified interface for the nonlinear solving packages of
+Julia. It includes its own high-performance nonlinear solvers which include the
+ability to swap out to fast direct and iterative linear solvers, along with the
+ability to use sparse automatic differentiation for Jacobian construction and
+Jacobian-vector products. It interfaces with other packages of the Julia ecosystem
+to make it easy to test alternative solver packages and pass small types to
+control algorithm swapping. It also interfaces with the
+[ModelingToolkit.jl](https://mtk.sciml.ai/dev/) world of symbolic modeling to
+allow for automatically generating high-performance code.
+
+Performance is key: the current methods are made to be highly performant on
+scalar and statically sized small problems, with options for large-scale systems.
+If you run into any performance issues, please file an issue. Note that this
+package is distinct from [SciMLNLSolve.jl](https://github.com/SciML/SciMLNLSolve.jl).
+Consult the [NonlinearSystemSolvers](@ref nonlinearsystemsolvers) page for
+information on how to import solvers from different packages.
+
+## Installation
+
+To install NonlinearSolve.jl, use the Julia package manager:
+
+```julia
+using Pkg
+Pkg.add("NonlinearSolve")
+```
+
+## Contributing
+
+- Please refer to the
+  [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
+  for guidance on PRs, issues, and other matters relating to contributing to ModelingToolkit.
+- There are a few community forums:
+    - the #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/)
+    - [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter
+    - on the Julia Discourse forums (look for the [modelingtoolkit tag](https://discourse.julialang.org/tag/modelingtoolkit)
+    - see also [SciML Community page](https://sciml.ai/community/)
+
+## Roadmap
+
+The current algorithms should support automatic differentiation, though improved
+adjoint overloads are planned to be added in the current update (which will make
+use of the `f(u,p)` form). Future updates will include standard methods for
+larger scale nonlinear solving like Newton-Krylov methods.
diff --git a/docs/src/solvers/IntegralSolvers.md b/docs/src/solvers/IntegralSolvers.md
@@ -0,0 +1,13 @@
+# Integral Solver Algorithms
+
+The following algorithms are available:
+
+- `QuadGKJL`: Uses QuadGK.jl. Requires `nout=1` and `batch=0`.
+- `HCubatureJL`: Uses HCubature.jl. Requires `batch=0`.
+- `VEGAS`: Uses MonteCarloIntegration.jl. Requires `nout=1`.
+- `CubatureJLh`: h-Cubature from Cubature.jl. Requires `using IntegralsCubature`.
+- `CubatureJLp`: p-Cubature from Cubature.jl. Requires `using IntegralsCubature`.
+- `CubaVegas`: Vegas from Cuba.jl. Requires `using IntegralsCuba`.
+- `CubaSUAVE`: SUAVE from Cuba.jl. Requires `using IntegralsCuba`.
+- `CubaDivonne`: Divonne from Cuba.jl. Requires `using IntegralsCuba`.
+- `CubaCuhre`: Cuhre from Cuba.jl. Requires `using IntegralsCuba`.
diff --git a/docs/src/tutorials/differentiating_integrals.md b/docs/src/tutorials/differentiating_integrals.md
@@ -0,0 +1,23 @@
+# Differentiating Integrals
+
+Integrals.jl is a fully differentiable quadrature library. Thus, it adds the
+ability to perform automatic differentiation over any of the libraries that it
+calls. It integrates with ForwardDiff.jl for forward-mode automatic differentiation
+and Zygote.jl for reverse-mode automatic differentiation. For example:
+
+```julia
+using Integrals, ForwardDiff, FiniteDiff, Zygote, Cuba
+f(x,p) = sum(sin.(x .* p))
+lb = ones(2)
+ub = 3ones(2)
+p = [1.5,2.0]
+
+function testf(p)
+    prob = IntegralProblem(f,lb,ub,p)
+    sin(solve(prob,CubaCuhre(),reltol=1e-6,abstol=1e-6)[1])
+end
+dp1 = Zygote.gradient(testf,p)
+dp2 = FiniteDiff.finite_difference_gradient(testf,p)
+dp3 = ForwardDiff.gradient(testf,p)
+dp1[1] ≈ dp2 ≈ dp3
+```
diff --git a/docs/src/tutorials/numerical_integrals.md b/docs/src/tutorials/numerical_integrals.md
@@ -0,0 +1,33 @@
+# Numerically Solving Integrals
+
+For basic multidimensional quadrature we can construct and solve a `IntegralProblem`:
+
+```julia
+using Integrals
+f(x,p) = sum(sin.(x))
+prob = IntegralProblem(f,ones(2),3ones(2))
+sol = solve(prob,HCubatureJL(),reltol=1e-3,abstol=1e-3)
+```
+
+If we would like to parallelize the computation, we can use the batch interface
+to compute multiple points at once. For example, here we do allocation-free
+multithreading with Cubature.jl:
+
+```julia
+using Integrals, Cubature, Base.Threads
+function f(dx,x,p)
+  Threads.@threads for i in 1:size(x,2)
+    dx[i] = sum(sin.(@view(x[:,i])))
+  end
+end
+prob = IntegralProblem(f,ones(2),3ones(2),batch=2)
+sol = solve(prob,CubatureJLh(),reltol=1e-3,abstol=1e-3)
+```
+
+If we would like to compare the results against Cuba.jl's `Cuhre` method, then
+the change is a one-argument change:
+
+```julia
+using IntegralsCuba
+sol = solve(prob,CubaCuhre(),reltol=1e-3,abstol=1e-3)
+```

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Frequently Asked Questions`
	`2`	`+`
	`3`	`+Ask more questions.`