@@ -4,26 +4,49 @@ abstract type AbstractShooting <: AbstractBoundaryValueDiffEqAlgorithm end
44"""
55 Shooting(ode_alg; kwargs...)
66 Shooting(ode_alg, nlsolve; kwargs...)
7- Shooting(; ode_alg = nothing, nlsolve = nothing, optimize = nothing, jac_alg = nothing)
7+ Shooting(; ode_alg = nothing, nlsolve = nothing, optimize = nothing, jac_alg = nothing) -> Shooting
88
9- Single shooting method, reduces BVP to an initial value problem and solves the IVP.
9+ Configures the single-shooting algorithm for a boundary value problem. Single shooting
10+ integrates one initial value problem and solves for the initial condition that satisfies the
11+ boundary conditions.
1012
1113## Arguments
1214
13- - `ode_alg`: ODE algorithm to use for solving the IVP. Any solver which conforms to the
14- SciML `ODEProblem` interface can be used! (Defaults to `nothing` which will use
15- poly-algorithm if `DifferentialEquations.jl` is loaded else this must be supplied)
16- - `nlsolve`: Internal Nonlinear solver. Any solver which conforms to the SciML
17- `NonlinearProblem` interface can be used. Note that any autodiff argument for the solver
18- will be ignored and a custom jacobian algorithm will be used.
19- - `optimize`: Internal Optimization solver. Any solver which conforms to the SciML
20- `OptimizationProblem` interface can be used. Note that any autodiff argument for the solver
21- will be ignored and a custom jacobian algorithm will be used.
22- - `jac_alg`: Jacobian Algorithm used for the Nonlinear Solver. If this is not set, we
23- check if `nlsolve.ad` exists and is not nothing. If it is, we use that to construct
24- the jacobian. If not, we try to use the best algorithm based on the input types
25- and problem type. If `BVPJacobianAlgorithm` is provided, only `diffmode` is used
26- (defaults to `AutoForwardDiff` if possible else `AutoFiniteDiff`).
15+ - `ode_alg`: algorithm used to solve the internal `SciMLBase.ODEProblem`. Pass this as the
16+ first positional argument or keyword argument. `nothing` selects a loaded polyalgorithm;
17+ otherwise an ODE algorithm must be supplied.
18+ - `nlsolve`: nonlinear-solver algorithm for the shooting residual. Its autodiff setting is
19+ superseded by `jac_alg` when a Jacobian algorithm is materialized.
20+
21+ ## Keywords
22+
23+ - `ode_alg = nothing`: ODE algorithm, as described above.
24+ - `nlsolve = nothing`: nonlinear-solver algorithm, as described above.
25+ - `optimize = nothing`: optimization-solver algorithm used when the selected BVP solve path
26+ formulates the residual as an optimization problem.
27+ - `jac_alg = nothing`: `BVPJacobianAlgorithm` configuration. When omitted, the constructor
28+ derives it from `nlsolve` and the problem during solve initialization. For single shooting,
29+ only its `diffmode` setting is used; the default is `AutoForwardDiff` when applicable and
30+ otherwise `AutoFiniteDiff`.
31+
32+ ## Fields
33+
34+ - `ode_alg`: configured ODE algorithm or `nothing`.
35+ - `nlsolve`: configured nonlinear-solver algorithm or `nothing`.
36+ - `optimize`: configured optimization-solver algorithm or `nothing`.
37+ - `jac_alg::BVPJacobianAlgorithm`: materialized Jacobian-algorithm configuration.
38+
39+ ## Returns
40+
41+ - `Shooting`: an algorithm object accepted by `SciMLBase.solve` for a boundary value problem.
42+
43+ ## Examples
44+
45+ ```julia
46+ using BoundaryValueDiffEqShooting, OrdinaryDiffEqTsit5
47+
48+ alg = Shooting(Tsit5())
49+ ```
2750"""
2851@concrete struct Shooting{J <: BVPJacobianAlgorithm } <: AbstractShooting
2952 ode_alg
4669
4770"""
4871 MultipleShooting(; nshoots::Int, ode_alg = nothing, nlsolve = nothing,
49- optimize = nothing, grid_coarsening = true, jac_alg = nothing)
72+ optimize = nothing, grid_coarsening = true, jac_alg = nothing) -> MultipleShooting
5073 MultipleShooting(nshoots::Int; kwargs...)
5174 MultipleShooting(nshoots::Int, ode_alg; kwargs...)
5275 MultipleShooting(nshoots::Int, ode_alg, nlsolve; kwargs...)
5376
54- Multiple Shooting method, reduces BVP to an initial value problem and solves the IVP.
55- Significantly more stable than Single Shooting.
77+ Configures the multiple-shooting algorithm for a boundary value problem. Multiple shooting
78+ integrates an IVP on `nshoots` subintervals and solves for their matching initial conditions;
79+ it is generally more stable than [`Shooting`](@ref).
5680
5781## Arguments
5882
59- - `nshoots`: Number of shooting points.
83+ - `nshoots::Int`: number of shooting subintervals.
84+ - `ode_alg`: algorithm used to solve each internal `SciMLBase.ODEProblem`. Pass this as the
85+ second positional argument or keyword argument. `nothing` selects a loaded polyalgorithm;
86+ otherwise an ODE algorithm must be supplied.
87+ - `nlsolve`: nonlinear-solver algorithm for the multiple-shooting residual.
6088
61- - `ode_alg`: ODE algorithm to use for solving the IVP. Any solver which conforms to the
62- SciML `ODEProblem` interface can be used! (Defaults to `nothing` which will use
63- poly-algorithm if `DifferentialEquations.jl` is loaded else this must be supplied)
64- - `nlsolve`: Internal Nonlinear solver. Any solver which conforms to the SciML
65- `NonlinearProblem` interface can be used.
66- - `optimize`: Internal Optimization solver. Any solver which conforms to the SciML
67- `OptimizationProblem` interface can be used.
68- - `jac_alg`: Jacobian Algorithm used for the nonlinear solver. Defaults to
69- `BVPJacobianAlgorithm()`, which automatically decides the best algorithm to use based
70- on the input types and problem type.
89+ ## Keywords
90+
91+ - `ode_alg = nothing`: ODE algorithm, as described above.
92+ - `nlsolve = nothing`: nonlinear-solver algorithm, as described above.
93+ - `optimize = nothing`: optimization-solver algorithm used when the selected BVP solve path
94+ formulates the residual as an optimization problem.
95+ - `jac_alg = nothing`: `BVPJacobianAlgorithm` configuration. When omitted, the constructor
96+ derives it from `nlsolve` and the problem during solve initialization.
7197
7298 + For `TwoPointBVProblem`, only `diffmode` is used (defaults to
7399 `AutoSparse(AutoForwardDiff())` if possible else `AutoSparse(AutoFiniteDiff())`).
74100 + For `BVProblem`, `bc_diffmode` and `nonbc_diffmode` are used. For `nonbc_diffmode`
75101 we default to `AutoSparse(AutoForwardDiff())` if possible else
76102 `AutoSparse(AutoFiniteDiff())`. For `bc_diffmode`, we default to `AutoForwardDiff`
77103 if possible else `AutoFiniteDiff`.
78- - `grid_coarsening`: Coarsening the multiple-shooting grid to generate a stable IVP
79- solution. Possible Choices :
104+ - `grid_coarsening = true `: coarsens the multiple-shooting grid while generating a stable
105+ IVP solution. Supported values are :
80106
81107 + `true`: Halve the grid size, till we reach a grid size of 1.
82108 + `false`: Do not coarsen the grid. Solve a Multiple Shooting Problem and finally
@@ -87,6 +113,28 @@ Significantly more stable than Single Shooting.
87113 + `Function`: Takes the current number of shooting points and returns the next number
88114 of shooting points. For example, if `nshoots = 10` and
89115 `grid_coarsening = n -> n ÷ 2`, then the grid will be coarsened to `[5, 2]`.
116+
117+ ## Fields
118+
119+ - `ode_alg`: configured ODE algorithm or `nothing`.
120+ - `nlsolve`: configured nonlinear-solver algorithm or `nothing`.
121+ - `optimize`: configured optimization-solver algorithm or `nothing`.
122+ - `jac_alg::BVPJacobianAlgorithm`: materialized Jacobian-algorithm configuration.
123+ - `nshoots::Int`: configured number of shooting subintervals.
124+ - `grid_coarsening`: configured grid-coarsening strategy.
125+
126+ ## Returns
127+
128+ - `MultipleShooting`: an algorithm object accepted by `SciMLBase.solve` for a boundary value
129+ problem.
130+
131+ ## Examples
132+
133+ ```julia
134+ using BoundaryValueDiffEqShooting, OrdinaryDiffEqTsit5
135+
136+ alg = MultipleShooting(8, Tsit5(); grid_coarsening = true)
137+ ```
90138"""
91139@concrete struct MultipleShooting{J <: BVPJacobianAlgorithm } <: AbstractShooting
92140 ode_alg
0 commit comments