Merge pull request #134 from avik-pal/ap/docs

Author: avik-pal

.JuliaFormatter.toml

@@ -1,2 +1,3 @@
 style = "sciml"
 annotate_untyped_fields_with_any = false
+format_markdown = true

LICENSE.md

@@ -19,4 +19,3 @@ The BoundaryValueDiffEq.jl package is licensed under the MIT "Expat" License:
 > LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 > OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 > SOFTWARE.
-> 

README.md

@@ -8,7 +8,7 @@
 [![Package Downloads](https://shields.io/endpoint?url=https://pkgs.genieframework.com/api/v1/badge/BoundaryValueDiffEq)](https://pkgs.genieframework.com?packages=BoundaryValueDiffEq)
 [![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 
-[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor%27s%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
 [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle)
 
 BoundaryValueDiffEq.jl is a component package in the DifferentialEquations ecosystem. It holds the
@@ -45,17 +45,17 @@ For the list of available solvers, please refer to the [DifferentialEquations.jl
 
 Precompilation can be controlled via `Preferences.jl`
 
-- `PrecompileMIRK` -- Precompile the MIRK2 - MIRK6 algorithms (default: `true`).
-- `PrecompileShooting` -- Precompile the single shooting algorithms (default: `true`). This is triggered when `OrdinaryDiffEq` is loaded.
-- `PrecompileMultipleShooting` -- Precompile the multiple shooting algorithms (default: `true`). This is triggered when `OrdinaryDiffEq` is loaded.
-- `PrecompileMIRKNLLS` -- Precompile the MIRK2 - MIRK6 algorithms for under-determined and over-determined BVPs (default: `true` on Julia Version 1.10 and above).
-- `PrecompileShootingNLLS` -- Precompile the single shooting algorithms for under-determined and over-determined BVPs (default: `true` on Julia Version 1.10 and above). This is triggered when `OrdinaryDiffEq` is loaded.
-- `PrecompileMultipleShootingNLLS` -- Precompile the multiple shooting algorithms for under-determined and over-determined BVPs (default: `true` on Julia Version 1.10 and above). This is triggered when `OrdinaryDiffEq` is loaded.
+  - `PrecompileMIRK` -- Precompile the MIRK2 - MIRK6 algorithms (default: `true`).
+  - `PrecompileShooting` -- Precompile the single shooting algorithms (default: `true`). This is triggered when `OrdinaryDiffEq` is loaded.
+  - `PrecompileMultipleShooting` -- Precompile the multiple shooting algorithms (default: `true`). This is triggered when `OrdinaryDiffEq` is loaded.
+  - `PrecompileMIRKNLLS` -- Precompile the MIRK2 - MIRK6 algorithms for under-determined and over-determined BVPs (default: `true` on Julia Version 1.10 and above).
+  - `PrecompileShootingNLLS` -- Precompile the single shooting algorithms for under-determined and over-determined BVPs (default: `true` on Julia Version 1.10 and above). This is triggered when `OrdinaryDiffEq` is loaded.
+  - `PrecompileMultipleShootingNLLS` -- Precompile the multiple shooting algorithms for under-determined and over-determined BVPs (default: `true` on Julia Version 1.10 and above). This is triggered when `OrdinaryDiffEq` is loaded.
 
 To set these preferences before loading the package, do the following (replacing `PrecompileShooting` with the preference you want to set, or pass in multiple pairs to set them together):
 
 ```julia
 using Preferences, UUIDs
 Preferences.set_preferences!(UUID("764a87c0-6b3e-53db-9096-fe964310641d"),
-                             "PrecompileShooting" => false)
+    "PrecompileShooting" => false)
 ```

src/algorithms.jl

@@ -6,6 +6,21 @@ abstract type AbstractMIRK <: BoundaryValueDiffEqAlgorithm end
     Shooting(ode_alg; nlsolve = NewtonRaphson())
 
 Single shooting method, reduces BVP to an initial value problem and solves the IVP.
+
+## Arguments
+
+  - `ode_alg`: ODE algorithm to use for solving the IVP. Any solver which conforms to the
+    SciML `ODEProblem` interface can be used!
+
+## Keyword Arguments
+
+  - `nlsolve`: Internal Nonlinear solver. Any solver which conforms to the SciML
+    `NonlinearProblem` interface can be used.
+
+!!! note
+    For type-stability, you need to specify the chunksize for autodiff. This can be done
+    via `NewtonRaphson(; autodiff = AutoForwardDiff(; chunksize = <chunksize>))`.
+    Alternatively, you can use other ADTypes!
 """
 struct Shooting{O, N} <: BoundaryValueDiffEqAlgorithm
     ode_alg::O
@@ -16,10 +31,45 @@ Shooting(ode_alg; nlsolve = NewtonRaphson()) = Shooting(ode_alg, nlsolve)
 
 """
     MultipleShooting(nshoots::Int, ode_alg; nlsolve = NewtonRaphson(),
-        grid_coarsening = true)
+        grid_coarsening = true, jac_alg = BVPJacobianAlgorithm())
 
 Multiple Shooting method, reduces BVP to an initial value problem and solves the IVP.
 Significantly more stable than Single Shooting.
+
+## Arguments
+
+  - `nshoots`: Number of shooting points.
+  - `ode_alg`: ODE algorithm to use for solving the IVP. Any solver which conforms to the
+    SciML `ODEProblem` interface can be used!
+
+## Keyword Arguments
+
+  - `nlsolve`: Internal Nonlinear solver. Any solver which conforms to the SciML
+    `NonlinearProblem` interface can be used. Note that any autodiff argument for the solver
+    will be ignored and a custom jacobian algorithm will be used.
+  - `jac_alg`: Jacobian Algorithm used for the nonlinear solver. Defaults to
+    `BVPJacobianAlgorithm()`, which automatically decides the best algorithm to use based
+    on the input types and problem type.
+    - For `TwoPointBVProblem`, only `diffmode` is used (defaults to
+      `AutoSparseForwardDiff` if possible else `AutoSparseFiniteDiff`).
+    - For `BVProblem`, `bc_diffmode` and `nonbc_diffmode` are used. For `nonbc_diffmode`
+      defaults to `AutoSparseForwardDiff` if possible else `AutoSparseFiniteDiff`. For
+      `bc_diffmode`, defaults to `AutoForwardDiff` if possible else `AutoFiniteDiff`.
+  - `grid_coarsening`: Coarsening the multiple-shooting grid to generate a stable IVP
+    solution. Possible Choices:
+    - `true`: Halve the grid size, till we reach a grid size of 1.
+    - `false`: Do not coarsen the grid. Solve a Multiple Shooting Problem and finally
+      solve a Single Shooting Problem.
+    - `AbstractVector{<:Int}` or `Ntuple{N, <:Integer}`: Use the provided grid coarsening.
+      For example, if `nshoots = 10` and `grid_coarsening = [5, 2]`, then the grid will be
+      coarsened to `[5, 2]`. Note that `1` should not be present in the grid coarsening.
+    - `Function`: Takes the current number of shooting points and returns the next number
+      of shooting points. For example, if `nshoots = 10` and
+      `grid_coarsening = n -> n ÷ 2`, then the grid will be coarsened to `[5, 2]`.
+
+!!! note
+    For type-stability, the chunksizes for ForwardDiff ADTypes in `BVPJacobianAlgorithm`
+    must be provided.
 """
 @concrete struct MultipleShooting{J <: BVPJacobianAlgorithm}
     ode_alg
@@ -62,6 +112,25 @@ for order in (2, 3, 4, 5, 6)
 
         $($order)th order Monotonic Implicit Runge Kutta method, with Newton Raphson nonlinear solver as default.
 
+        ## Keyword Arguments
+
+          - `nlsolve`: Internal Nonlinear solver. Any solver which conforms to the SciML
+            `NonlinearProblem` interface can be used. Note that any autodiff argument for
+            the solver will be ignored and a custom jacobian algorithm will be used.
+          - `jac_alg`: Jacobian Algorithm used for the nonlinear solver. Defaults to
+            `BVPJacobianAlgorithm()`, which automatically decides the best algorithm to
+            use based on the input types and problem type.
+            - For `TwoPointBVProblem`, only `diffmode` is used (defaults to
+              `AutoSparseForwardDiff` if possible else `AutoSparseFiniteDiff`).
+            - For `BVProblem`, `bc_diffmode` and `nonbc_diffmode` are used. For
+              `nonbc_diffmode` defaults to `AutoSparseForwardDiff` if possible else
+              `AutoSparseFiniteDiff`. For `bc_diffmode`, defaults to `AutoForwardDiff` if
+              possible else `AutoFiniteDiff`.
+
+        !!! note
+            For type-stability, the chunksizes for ForwardDiff ADTypes in
+            `BVPJacobianAlgorithm` must be provided.
+
         ## References
 
         @article{Enright1996RungeKuttaSW,