diff --git a/src/raphson.jl b/src/raphson.jl index 5c44908f0..8d7720a3f 100644 --- a/src/raphson.jl +++ b/src/raphson.jl @@ -1,8 +1,8 @@ """ ```julia NewtonRaphson(; chunk_size = Val{0}(), autodiff = Val{true}(), - standardtag = Val{true}(), concrete_jac = nothing, - diff_type = Val{:forward}, linsolve = nothing, precs = DEFAULT_PRECS) + standardtag = Val{true}(), concrete_jac = nothing, + diff_type = Val{:forward}, linsolve = nothing, precs = DEFAULT_PRECS) ``` An advanced NewtonRaphson implementation with support for efficient handling of sparse @@ -11,37 +11,37 @@ for large-scale and numerically-difficult nonlinear systems. ### Keyword Arguments -- `chunk_size`: the chunk size used by the internal ForwardDiff.jl automatic differentiation - system. This allows for multiple derivative columns to be computed simultaneously, - improving performance. Defaults to `0`, which is equivalent to using ForwardDiff.jl's - default chunk size mechanism. For more details, see the documentation for - [ForwardDiff.jl](https://juliadiff.org/ForwardDiff.jl/stable/). -- `autodiff`: whether to use forward-mode automatic differentiation for the Jacobian. - Note that this argument is ignored if an analytical Jacobian is passed, as that will be - used instead. Defaults to `Val{true}`, which means ForwardDiff.jl via - SparseDiffTools.jl is used by default. If `Val{false}`, then FiniteDiff.jl is used for - finite differencing. -- `standardtag`: whether to use a standardized tag definition for the purposes of automatic - differentiation. Defaults to true, which thus uses the `NonlinearSolveTag`. If `Val{false}`, - then ForwardDiff's default function naming tag is used, which results in larger stack - traces. -- `concrete_jac`: whether to build a concrete Jacobian. If a Krylov-subspace method is used, - then the Jacobian will not be constructed and instead direct Jacobian-vector products - `J*v` are computed using forward-mode automatic differentiation or finite differencing - tricks (without ever constructing the Jacobian). However, if the Jacobian is still needed, - for example for a preconditioner, `concrete_jac = true` can be passed in order to force - the construction of the Jacobian. -- `diff_type`: the type of finite differencing used if `autodiff = false`. Defaults to - `Val{:forward}` for forward finite differences. For more details on the choices, see the - [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl) documentation. -- `linsolve`: the [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) used for the - linear solves within the Newton method. Defaults to `nothing`, which means it uses the - LinearSolve.jl default algorithm choice. For more information on available algorithm - choices, see the [LinearSolve.jl documentation](https://docs.sciml.ai/LinearSolve/stable/). -- `precs`: the choice of preconditioners for the linear solver. Defaults to using no - preconditioners. For more information on specifying preconditioners for LinearSolve - algorithms, consult the - [LinearSolve.jl documentation](https://docs.sciml.ai/LinearSolve/stable/). + - `chunk_size`: the chunk size used by the internal ForwardDiff.jl automatic differentiation + system. This allows for multiple derivative columns to be computed simultaneously, + improving performance. Defaults to `0`, which is equivalent to using ForwardDiff.jl's + default chunk size mechanism. For more details, see the documentation for + [ForwardDiff.jl](https://juliadiff.org/ForwardDiff.jl/stable/). + - `autodiff`: whether to use forward-mode automatic differentiation for the Jacobian. + Note that this argument is ignored if an analytical Jacobian is passed, as that will be + used instead. Defaults to `Val{true}`, which means ForwardDiff.jl via + SparseDiffTools.jl is used by default. If `Val{false}`, then FiniteDiff.jl is used for + finite differencing. + - `standardtag`: whether to use a standardized tag definition for the purposes of automatic + differentiation. Defaults to true, which thus uses the `NonlinearSolveTag`. If `Val{false}`, + then ForwardDiff's default function naming tag is used, which results in larger stack + traces. + - `concrete_jac`: whether to build a concrete Jacobian. If a Krylov-subspace method is used, + then the Jacobian will not be constructed and instead direct Jacobian-vector products + `J*v` are computed using forward-mode automatic differentiation or finite differencing + tricks (without ever constructing the Jacobian). However, if the Jacobian is still needed, + for example for a preconditioner, `concrete_jac = true` can be passed in order to force + the construction of the Jacobian. + - `diff_type`: the type of finite differencing used if `autodiff = false`. Defaults to + `Val{:forward}` for forward finite differences. For more details on the choices, see the + [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl) documentation. + - `linsolve`: the [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) used for the + linear solves within the Newton method. Defaults to `nothing`, which means it uses the + LinearSolve.jl default algorithm choice. For more information on available algorithm + choices, see the [LinearSolve.jl documentation](https://docs.sciml.ai/LinearSolve/stable/). + - `precs`: the choice of preconditioners for the linear solver. Defaults to using no + preconditioners. For more information on specifying preconditioners for LinearSolve + algorithms, consult the + [LinearSolve.jl documentation](https://docs.sciml.ai/LinearSolve/stable/). !!! note diff --git a/src/trustRegion.jl b/src/trustRegion.jl index 1eeddc1d7..0c19dfaf5 100644 --- a/src/trustRegion.jl +++ b/src/trustRegion.jl @@ -1,16 +1,16 @@ """ ```julia TrustRegion(; chunk_size = Val{0}(), autodiff = Val{true}(), - standardtag = Val{true}(), concrete_jac = nothing, - diff_type = Val{:forward}, linsolve = nothing, precs = DEFAULT_PRECS, - max_trust_radius::Real = 0.0, - initial_trust_radius::Real = 0.0, - step_threshold::Real = 0.1, - shrink_threshold::Real = 0.25, - expand_threshold::Real = 0.75, - shrink_factor::Real = 0.25, - expand_factor::Real = 2.0, - max_shrink_times::Int = 32) + standardtag = Val{true}(), concrete_jac = nothing, + diff_type = Val{:forward}, linsolve = nothing, precs = DEFAULT_PRECS, + max_trust_radius::Real = 0.0, + initial_trust_radius::Real = 0.0, + step_threshold::Real = 0.1, + shrink_threshold::Real = 0.25, + expand_threshold::Real = 0.75, + shrink_factor::Real = 0.25, + expand_factor::Real = 2.0, + max_shrink_times::Int = 32) ``` An advanced TrustRegion implementation with support for efficient handling of sparse @@ -19,61 +19,61 @@ for large-scale and numerically-difficult nonlinear systems. ### Keyword Arguments -- `chunk_size`: the chunk size used by the internal ForwardDiff.jl automatic differentiation - system. This allows for multiple derivative columns to be computed simultaneously, - improving performance. Defaults to `0`, which is equivalent to using ForwardDiff.jl's - default chunk size mechanism. For more details, see the documentation for - [ForwardDiff.jl](https://juliadiff.org/ForwardDiff.jl/stable/). -- `autodiff`: whether to use forward-mode automatic differentiation for the Jacobian. - Note that this argument is ignored if an analytical Jacobian is passed, as that will be - used instead. Defaults to `Val{true}`, which means ForwardDiff.jl via - SparseDiffTools.jl is used by default. If `Val{false}`, then FiniteDiff.jl is used for - finite differencing. -- `standardtag`: whether to use a standardized tag definition for the purposes of automatic - differentiation. Defaults to true, which thus uses the `NonlinearSolveTag`. If `Val{false}`, - then ForwardDiff's default function naming tag is used, which results in larger stack - traces. -- `concrete_jac`: whether to build a concrete Jacobian. If a Krylov-subspace method is used, - then the Jacobian will not be constructed and instead direct Jacobian-vector products - `J*v` are computed using forward-mode automatic differentiation or finite differencing - tricks (without ever constructing the Jacobian). However, if the Jacobian is still needed, - for example for a preconditioner, `concrete_jac = true` can be passed in order to force - the construction of the Jacobian. -- `diff_type`: the type of finite differencing used if `autodiff = false`. Defaults to - `Val{:forward}` for forward finite differences. For more details on the choices, see the - [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl) documentation. -- `linsolve`: the [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) used for the - linear solves within the Newton method. Defaults to `nothing`, which means it uses the - LinearSolve.jl default algorithm choice. For more information on available algorithm - choices, see the [LinearSolve.jl documentation](https://docs.sciml.ai/LinearSolve/stable/). -- `precs`: the choice of preconditioners for the linear solver. Defaults to using no - preconditioners. For more information on specifying preconditioners for LinearSolve - algorithms, consult the - [LinearSolve.jl documentation](https://docs.sciml.ai/LinearSolve/stable/). -- `max_trust_radius`: the maximal trust region radius. - Defaults to `max(norm(fu), maximum(u) - minimum(u))`. -- `initial_trust_radius`: the initial trust region radius. Defaults to - `max_trust_radius / 11`. -- `step_threshold`: the threshold for taking a step. In every iteration, the threshold is - compared with a value `r`, which is the actual reduction in the objective function divided - by the predicted reduction. If `step_threshold > r` the model is not a good approximation, - and the step is rejected. Defaults to `0.1`. For more details, see - [Trust-region methods](https://optimization.mccormick.northwestern.edu/index.php/Trust-region_methods) -- `shrink_threshold`: the threshold for shrinking the trust region radius. In every - iteration, the threshold is compared with a value `r` which is the actual reduction in the - objective function divided by the predicted reduction. If `shrink_threshold > r` the trust - region radius is shrunk by `shrink_factor`. Defaults to `0.25`. For more details, see - [Trust-region methods](https://optimization.mccormick.northwestern.edu/index.php/Trust-region_methods) -- `expand_threshold`: the threshold for expanding the trust region radius. If a step is - taken, i.e `step_threshold < r` (with `r` defined in `shrink_threshold`), a check is also - made to see if `expand_threshold < r`. If that is true, the trust region radius is - expanded by `expand_factor`. Defaults to `0.75`. -- `shrink_factor`: the factor to shrink the trust region radius with if - `shrink_threshold > r` (with `r` defined in `shrink_threshold`). Defaults to `0.25`. -- `expand_factor`: the factor to expand the trust region radius with if - `expand_threshold < r` (with `r` defined in `shrink_threshold`). Defaults to `2.0`. -- `max_shrink_times`: the maximum number of times to shrink the trust region radius in a - row, `max_shrink_times` is exceeded, the algorithm returns. Defaults to `32`. + - `chunk_size`: the chunk size used by the internal ForwardDiff.jl automatic differentiation + system. This allows for multiple derivative columns to be computed simultaneously, + improving performance. Defaults to `0`, which is equivalent to using ForwardDiff.jl's + default chunk size mechanism. For more details, see the documentation for + [ForwardDiff.jl](https://juliadiff.org/ForwardDiff.jl/stable/). + - `autodiff`: whether to use forward-mode automatic differentiation for the Jacobian. + Note that this argument is ignored if an analytical Jacobian is passed, as that will be + used instead. Defaults to `Val{true}`, which means ForwardDiff.jl via + SparseDiffTools.jl is used by default. If `Val{false}`, then FiniteDiff.jl is used for + finite differencing. + - `standardtag`: whether to use a standardized tag definition for the purposes of automatic + differentiation. Defaults to true, which thus uses the `NonlinearSolveTag`. If `Val{false}`, + then ForwardDiff's default function naming tag is used, which results in larger stack + traces. + - `concrete_jac`: whether to build a concrete Jacobian. If a Krylov-subspace method is used, + then the Jacobian will not be constructed and instead direct Jacobian-vector products + `J*v` are computed using forward-mode automatic differentiation or finite differencing + tricks (without ever constructing the Jacobian). However, if the Jacobian is still needed, + for example for a preconditioner, `concrete_jac = true` can be passed in order to force + the construction of the Jacobian. + - `diff_type`: the type of finite differencing used if `autodiff = false`. Defaults to + `Val{:forward}` for forward finite differences. For more details on the choices, see the + [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl) documentation. + - `linsolve`: the [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) used for the + linear solves within the Newton method. Defaults to `nothing`, which means it uses the + LinearSolve.jl default algorithm choice. For more information on available algorithm + choices, see the [LinearSolve.jl documentation](https://docs.sciml.ai/LinearSolve/stable/). + - `precs`: the choice of preconditioners for the linear solver. Defaults to using no + preconditioners. For more information on specifying preconditioners for LinearSolve + algorithms, consult the + [LinearSolve.jl documentation](https://docs.sciml.ai/LinearSolve/stable/). + - `max_trust_radius`: the maximal trust region radius. + Defaults to `max(norm(fu), maximum(u) - minimum(u))`. + - `initial_trust_radius`: the initial trust region radius. Defaults to + `max_trust_radius / 11`. + - `step_threshold`: the threshold for taking a step. In every iteration, the threshold is + compared with a value `r`, which is the actual reduction in the objective function divided + by the predicted reduction. If `step_threshold > r` the model is not a good approximation, + and the step is rejected. Defaults to `0.1`. For more details, see + [Trust-region methods](https://optimization.mccormick.northwestern.edu/index.php/Trust-region_methods) + - `shrink_threshold`: the threshold for shrinking the trust region radius. In every + iteration, the threshold is compared with a value `r` which is the actual reduction in the + objective function divided by the predicted reduction. If `shrink_threshold > r` the trust + region radius is shrunk by `shrink_factor`. Defaults to `0.25`. For more details, see + [Trust-region methods](https://optimization.mccormick.northwestern.edu/index.php/Trust-region_methods) + - `expand_threshold`: the threshold for expanding the trust region radius. If a step is + taken, i.e `step_threshold < r` (with `r` defined in `shrink_threshold`), a check is also + made to see if `expand_threshold < r`. If that is true, the trust region radius is + expanded by `expand_factor`. Defaults to `0.75`. + - `shrink_factor`: the factor to shrink the trust region radius with if + `shrink_threshold > r` (with `r` defined in `shrink_threshold`). Defaults to `0.25`. + - `expand_factor`: the factor to expand the trust region radius with if + `expand_threshold < r` (with `r` defined in `shrink_threshold`). Defaults to `2.0`. + - `max_shrink_times`: the maximum number of times to shrink the trust region radius in a + row, `max_shrink_times` is exceeded, the algorithm returns. Defaults to `32`. !!! note diff --git a/src/utils.jl b/src/utils.jl index 4118b525c..32cac8cd6 100644 --- a/src/utils.jl +++ b/src/utils.jl @@ -20,7 +20,7 @@ alg_autodiff(alg::AbstractNewtonAlgorithm{CS, AD}) where {CS, AD} = AD alg_autodiff(alg) = false """ - value_derivative(f, x) +value_derivative(f, x) Compute `f(x), d/dx f(x)` in the most efficient way. """