From 51e4865599fd17ae78d624016b564e7867128347 Mon Sep 17 00:00:00 2001 From: Tangi Migot Date: Fri, 22 Mar 2024 16:47:38 +0100 Subject: [PATCH] extract docstring (#263) --- src/JSOSolvers.jl | 17 +++++++++++++++++ src/fomo.jl | 17 +++-------------- src/lbfgs.jl | 15 +-------------- src/tron.jl | 17 ++--------------- src/tronls.jl | 17 ++--------------- src/trunk.jl | 15 +-------------- src/trunkls.jl | 15 +-------------- 7 files changed, 27 insertions(+), 86 deletions(-) diff --git a/src/JSOSolvers.jl b/src/JSOSolvers.jl index a6596ac0..9cc4703c 100644 --- a/src/JSOSolvers.jl +++ b/src/JSOSolvers.jl @@ -9,6 +9,23 @@ using Krylov, LinearOperators, NLPModels, NLPModelsModifiers, SolverCore, Solver import SolverCore.solve! export solve! +const Callback_docstring = " +The callback is called at each iteration. +The expected signature of the callback is `callback(nlp, solver, stats)`, and its output is ignored. +Changing any of the input arguments will affect the subsequent iterations. +In particular, setting `stats.status = :user` will stop the algorithm. +All relevant information should be available in `nlp` and `solver`. +Notably, you can access, and modify, the following: +- `solver.x`: current iterate; +- `solver.gx`: current gradient; +- `stats`: structure holding the output of the algorithm (`GenericExecutionStats`), which contains, among other things: + - `stats.dual_feas`: norm of the residual, for instance, the norm of the gradient for unconstrained problems; + - `stats.iter`: current iteration counter; + - `stats.objective`: current objective function value; + - `stats.status`: current status of the algorithm. Should be `:unknown` unless the algorithm attained a stopping criterion. Changing this to anything will stop the algorithm, but you should use `:user` to properly indicate the intention. + - `stats.elapsed_time`: elapsed time in seconds. +" + # Unconstrained solvers include("lbfgs.jl") include("trunk.jl") diff --git a/src/fomo.jl b/src/fomo.jl index bcf3b047..831d07e8 100644 --- a/src/fomo.jl +++ b/src/fomo.jl @@ -58,6 +58,8 @@ The value returned is a `GenericExecutionStats`, see `SolverCore.jl`. # Callback +$(Callback_docstring) + The callback is called at each iteration. The expected signature of the callback is `callback(nlp, solver, stats)`, and its output is ignored. Changing any of the input arguments will affect the subsequent iterations. @@ -170,20 +172,7 @@ The value returned is a `GenericExecutionStats`, see `SolverCore.jl`. # Callback -The callback is called at each iteration. -The expected signature of the callback is `callback(nlp, solver, stats)`, and its output is ignored. -Changing any of the input arguments will affect the subsequent iterations. -In particular, setting `stats.status = :user || stats.stats = :unknown` will stop the algorithm. -All relevant information should be available in `nlp` and `solver`. -Notably, you can access, and modify, the following: -- `solver.x`: current iterate; -- `solver.gx`: current gradient; -- `stats`: structure holding the output of the algorithm (`GenericExecutionStats`), which contains, among other things: - - `stats.dual_feas`: norm of current gradient; - - `stats.iter`: current iteration counter; - - `stats.objective`: current objective function value; - - `stats.status`: current status of the algorithm. Should be `:unknown` unless the algorithm has attained a stopping criterion. Changing this to anything will stop the algorithm, but you should use `:user` to properly indicate the intention. - - `stats.elapsed_time`: elapsed time in seconds. +$(Callback_docstring) # Examples diff --git a/src/lbfgs.jl b/src/lbfgs.jl index bbaef6a9..bcef8850 100644 --- a/src/lbfgs.jl +++ b/src/lbfgs.jl @@ -29,20 +29,7 @@ The keyword arguments may include The returned value is a `GenericExecutionStats`, see `SolverCore.jl`. # Callback -The callback is called at each iteration. -The expected signature of the callback is `callback(nlp, solver, stats)`, and its output is ignored. -Changing any of the input arguments will affect the subsequent iterations. -In particular, setting `stats.status = :user` will stop the algorithm. -All relevant information should be available in `nlp` and `solver`. -Notably, you can access, and modify, the following: -- `solver.x`: current iterate; -- `solver.gx`: current gradient; -- `stats`: structure holding the output of the algorithm (`GenericExecutionStats`), which contains, among other things: - - `stats.dual_feas`: norm of current gradient; - - `stats.iter`: current iteration counter; - - `stats.objective`: current objective function value; - - `stats.status`: current status of the algorithm. Should be `:unknown` unless the algorithm has found a stopping criteria. Changing this to anything will stop the algorithm, but you should use `:user` to properly indicate the intention. - - `stats.elapsed_time`: elapsed time in seconds. +$(Callback_docstring) # Examples ```jldoctest diff --git a/src/tron.jl b/src/tron.jl index f5248722..52cf300b 100644 --- a/src/tron.jl +++ b/src/tron.jl @@ -31,7 +31,7 @@ The keyword arguments may include - `use_only_objgrad::Bool = false`: If `true`, the algorithm uses only the function `objgrad` instead of `obj` and `grad`. - `cgtol::T = T(0.1)`: subproblem tolerance. - `atol::T = √eps(T)`: absolute tolerance. -- `rtol::T = √eps(T)`: relative tolerance, the algorithm stops when ‖∇f(xᵏ)‖ ≤ atol + rtol * ‖∇f(x⁰)‖. +- `rtol::T = √eps(T)`: relative tolerance, the algorithm stops when ‖x - Proj(x - ∇f(xᵏ))‖ ≤ atol + rtol * ‖∇f(x⁰)‖. Proj denotes here the projection over the bounds. - `verbose::Int = 0`: if > 0, display iteration details every `verbose` iteration. - `subsolver_verbose::Int = 0`: if > 0, display iteration information every `subsolver_verbose` iteration of the subsolver. @@ -41,20 +41,7 @@ The keyword arguments of `TronSolver` are passed to the [`TRONTrustRegion`](http The value returned is a `GenericExecutionStats`, see `SolverCore.jl`. # Callback -The callback is called at each iteration. -The expected signature of the callback is `callback(nlp, solver, stats)`, and its output is ignored. -Changing any of the input arguments will affect the subsequent iterations. -In particular, setting `stats.status = :user` will stop the algorithm. -All relevant information should be available in `nlp` and `solver`. -Notably, you can access, and modify, the following: -- `solver.x`: current iterate; -- `solver.gx`: current gradient; -- `stats`: structure holding the output of the algorithm (`GenericExecutionStats`), which contains, among other things: - - `stats.dual_feas`: norm of current gradient; - - `stats.iter`: current iteration counter; - - `stats.objective`: current objective function value; - - `stats.status`: current status of the algorithm. Should be `:unknown` unless the algorithm has attained a stopping criterion. Changing this to anything will stop the algorithm, but you should use `:user` to properly indicate the intention. - - `stats.elapsed_time`: elapsed time in seconds. +$(Callback_docstring) # References TRON is described in diff --git a/src/tronls.jl b/src/tronls.jl index 12e7ed03..60f9e98b 100644 --- a/src/tronls.jl +++ b/src/tronls.jl @@ -30,7 +30,7 @@ The keyword arguments may include - `max_cgiter::Int = 50`: subproblem iteration limit. - `cgtol::T = T(0.1)`: subproblem tolerance. - `atol::T = √eps(T)`: absolute tolerance. -- `rtol::T = √eps(T)`: relative tolerance, the algorithm stops when ‖∇f(xᵏ)‖ ≤ atol + rtol * ‖∇f(x⁰)‖. +- `rtol::T = √eps(T)`: relative tolerance, the algorithm stops when ‖x - Proj(x - ∇f(xᵏ))‖ ≤ atol + rtol * ‖∇f(x⁰)‖. Proj denotes here the projection over the bounds. - `Fatol::T = √eps(T)`: absolute tolerance on the residual. - `Frtol::T = eps(T)`: relative tolerance on the residual, the algorithm stops when ‖F(xᵏ)‖ ≤ Fatol + Frtol * ‖F(x⁰)‖. - `verbose::Int = 0`: if > 0, display iteration details every `verbose` iteration. @@ -42,20 +42,7 @@ The keyword arguments of `TronSolverNLS` are passed to the [`TRONTrustRegion`](h The value returned is a `GenericExecutionStats`, see `SolverCore.jl`. # Callback -The callback is called at each iteration. -The expected signature of the callback is `callback(nlp, solver, stats)`, and its output is ignored. -Changing any of the input arguments will affect the subsequent iterations. -In particular, setting `stats.status = :user` will stop the algorithm. -All relevant information should be available in `nlp` and `solver`. -Notably, you can access, and modify, the following: -- `solver.x`: current iterate; -- `solver.gx`: current gradient; -- `stats`: structure holding the output of the algorithm (`GenericExecutionStats`), which contains, among other things: - - `stats.dual_feas`: norm of current gradient; - - `stats.iter`: current iteration counter; - - `stats.objective`: current objective function value; - - `stats.status`: current status of the algorithm. Should be `:unknown` unless the algorithm attained a stopping criterion. Changing this to anything will stop the algorithm, but you should use `:user` to properly indicate the intention. - - `stats.elapsed_time`: elapsed time in seconds. +$(Callback_docstring) # References This is an adaptation for bound-constrained nonlinear least-squares problems of the TRON method described in diff --git a/src/trunk.jl b/src/trunk.jl index c0b7ef02..f1e4e268 100644 --- a/src/trunk.jl +++ b/src/trunk.jl @@ -32,20 +32,7 @@ The keyword arguments may include The returned value is a `GenericExecutionStats`, see `SolverCore.jl`. # Callback -The callback is called at each iteration. -The expected signature of the callback is `callback(nlp, solver, stats)`, and its output is ignored. -Changing any of the input arguments will affect the subsequent iterations. -In particular, setting `stats.status = :user` will stop the algorithm. -All relevant information should be available in `nlp` and `solver`. -Notably, you can access, and modify, the following: -- `solver.x`: current iterate; -- `solver.gx`: current gradient; -- `stats`: structure holding the output of the algorithm (`GenericExecutionStats`), which contains, among other things: - - `stats.dual_feas`: norm of current gradient; - - `stats.iter`: current iteration counter; - - `stats.objective`: current objective function value; - - `stats.status`: current status of the algorithm. Should be `:unknown` unless the algorithm attained a stopping criterion. Changing this to anything will stop the algorithm, but you should use `:user` to properly indicate the intention. - - `stats.elapsed_time`: elapsed time in seconds. +$(Callback_docstring) # References This implementation follows the description given in diff --git a/src/trunkls.jl b/src/trunkls.jl index cd0bc2db..dace877a 100644 --- a/src/trunkls.jl +++ b/src/trunkls.jl @@ -40,20 +40,7 @@ See `JSOSolvers.trunkls_allowed_subsolvers` for a list of available `KrylovSolve The value returned is a `GenericExecutionStats`, see `SolverCore.jl`. # Callback -The callback is called at each iteration. -The expected signature of the callback is `callback(nlp, solver, stats)`, and its output is ignored. -Changing any of the input arguments will affect the subsequent iterations. -In particular, setting `stats.status = :user` will stop the algorithm. -All relevant information should be available in `nlp` and `solver`. -Notably, you can access, and modify, the following: -- `solver.x`: current iterate; -- `solver.gx`: current gradient; -- `stats`: structure holding the output of the algorithm (`GenericExecutionStats`), which contains, among other things: - - `stats.dual_feas`: norm of current gradient; - - `stats.iter`: current iteration counter; - - `stats.objective`: current objective function value; - - `stats.status`: current status of the algorithm. Should be `:unknown` unless the algorithm attained a stopping criterion. Changing this to anything will stop the algorithm, but you should use `:user` to properly indicate the intention. - - `stats.elapsed_time`: elapsed time in seconds. +$(Callback_docstring) # References This implementation follows the description given in