From 42823247b30fb51dbadde6da46442f53e77fac3b Mon Sep 17 00:00:00 2001 From: tmigot Date: Thu, 22 Oct 2020 02:07:28 +0200 Subject: [PATCH] update doc test --- README.md | 16 ++++++----- docs/src/api.md | 18 +++++++++++- docs/src/index.md | 70 ++++++++++++++++++++++++----------------------- 3 files changed, 62 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 460d1f76..5a1b8423 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,12 @@ When a solver is called on an optimization model, four outcomes may happen: This tool eases the first three items above. It defines a type mutable struct GenericStopping <: AbstractStopping - problem :: Any # an arbitrary instance of a problem - meta :: AbstractStoppingMeta # contains the used parameters - current_state :: AbstractState # the current state + problem :: Any # an arbitrary instance of a problem + meta :: AbstractStoppingMeta # contains the used parameters and stopping status + current_state :: AbstractState # Current information on the problem + main_stp :: Union{AbstractStopping, Nothing} # Stopping of the main problem, or nothing + listofstates :: Union{ListStates, Nothing} # History of states + user_specific_struct :: Any # User-specific structure The [StoppingMeta](https://github.com/vepiteski/Stopping.jl/blob/master/src/Stopping/StoppingMetamod.jl) provides default tolerances, maximum resources, ... as well as (boolean) information on the result. @@ -33,11 +36,10 @@ redefining a State and some functions specific to your problem. We provide some specialization of the GenericStopping for optimization: * [NLPStopping](https://github.com/vepiteski/Stopping.jl/blob/master/src/Stopping/NLPStoppingmod.jl) with [NLPAtX](https://github.com/vepiteski/Stopping.jl/blob/master/src/State/NLPAtXmod.jl) as a specialized State: for non-linear programming (based on [NLPModels](https://github.com/JuliaSmoothOptimizers/NLPModels.jl)); + * [LAStopping](https://github.com/vepiteski/Stopping.jl/blob/master/src/Stopping/LinearAlgebraStopping.jl) with [GenericState](https://github.com/vepiteski/Stopping.jl/blob/master/src/State/GenericStatemod.jl): for linear algebra problems. * [LS_Stopping](https://github.com/vepiteski/Stopping.jl/blob/master/src/Stopping/LineSearchStoppingmod.jl) with [LSAtT](https://github.com/vepiteski/Stopping.jl/blob/master/src/State/LSAtTmod.jl) as a specialized State: for 1d optimization; * more to come... -In these examples, the function `optimality_residual` computes the residual of the optimality conditions is an additional attribute of the types. - ## Functions The tool provides two main functions: @@ -83,13 +85,13 @@ f(x) = 0.5 * x' * Q * x nlp = ADNLPModel(f, ones(5)) ``` -We now initialize the NLPStopping. First create a State. +We now initialize the *NLPStopping*. First create a State. ``` nlp_at_x = NLPAtX(ones(5)) ``` We use [unconstrained_check](https://github.com/vepiteski/Stopping.jl/blob/master/src/Stopping/nlp_admissible_functions.jl) as an optimality function ``` -stop_nlp = NLPStopping(nlp, unconstrained_check, nlp_at_x) +stop_nlp = NLPStopping(nlp, nlp_at_x, optimality_check = unconstrained_check) ``` Note that, since we used a default State, an alternative would have been: ``` diff --git a/docs/src/api.md b/docs/src/api.md index 63b3593c..e011ffee 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -2,6 +2,7 @@ ## Types ```@docs Stopping.GenericState +Stopping.ListStates Stopping.NLPAtX Stopping.LSAtT ``` @@ -10,6 +11,12 @@ Stopping.LSAtT ```@docs Stopping.update! Stopping.reinit! +Stopping.copy, +Stopping.compress_state!, +Stopping.copy_compress_state +Stopping.add_to_list! +Stopping.length +Stopping.print ``` # Stopping @@ -18,6 +25,8 @@ Stopping.reinit! Stopping.GenericStopping Stopping.NLPStopping Stopping.LS_Stopping +Stopping.LAStopping +Stopping.LACounters Stopping.StoppingMeta ``` @@ -32,7 +41,7 @@ Stopping.fill_in! Stopping.status ``` -## Non linear admissibility functions +## Non-linear admissibility functions ```@docs Stopping.KKT Stopping.unconstrained_check @@ -40,6 +49,13 @@ Stopping.unconstrained2nd_check Stopping.optim_check_bounded ``` + +## Linear algebra admissibility functions +```@docs +Stopping.linear_system_check +Stopping.normal_equation_check +``` + ## Line search admissibility functions ```@docs Stopping.armijo diff --git a/docs/src/index.md b/docs/src/index.md index 577b308d..870346b4 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -4,24 +4,26 @@ Documentation for Stopping.jl ## Purpose -Stopping.jl is a set of tools to ease the uniformization of stopping criteria in iterative solvers. +Tools to ease the uniformization of stopping criteria in iterative solvers. When a solver is called on an optimization model, four outcomes may happen: -1. the approximate solution is obtained, the problem is considered solved; -2. the problem is declared unsolvable (unboundedness, infeasibility, etc.); -3. the maximum available resources are not sufficient to compute the solution; -4. some algorithm dependent failure happens. +1. the approximate solution is obtained, the problem is considered solved +2. the problem is declared unsolvable (unboundedness, infeasibility ...) +3. the maximum available resources are not sufficient to compute the solution +4. some algorithm dependent failure happens -This tool eases the first three items above. It defines a type [GenericStopping](https://github.com/Goysa2/Stopping.jl/blob/master/src/Stopping/GenericStoppingmod.jl): +This tool eases the first three items above. It defines a type mutable struct GenericStopping <: AbstractStopping - problem :: Any # an arbitrary instance of a problem - meta :: AbstractStoppingMeta # contains the used parameters - current_state :: AbstractState # the current state - main_stp :: Union{AbstractStopping, Nothing} # Stopping of the main problem, or nothing + problem :: Any # an arbitrary instance of a problem + meta :: AbstractStoppingMeta # contains the used parameters and stopping status + current_state :: AbstractState # Current information on the problem + main_stp :: Union{AbstractStopping, Nothing} # Stopping of the main problem, or nothing + listofstates :: Union{ListStates, Nothing} # History of states + user_specific_struct :: Any # User-specific structure -The [StoppingMeta](https://github.com/Goysa2/Stopping.jl/blob/master/src/Stopping/StoppingMetamod.jl) provides default tolerances, maximum resources, ... as well as (boolean) information on the result. +The [StoppingMeta](https://github.com/vepiteski/Stopping.jl/blob/master/src/Stopping/StoppingMetamod.jl) provides default tolerances, maximum resources, ... as well as (boolean) information on the result. ### Your Stopping your way @@ -30,31 +32,30 @@ Then, depending on the problem structure, you can specialize a new Stopping by redefining a State and some functions specific to your problem. We provide some specialization of the GenericStopping for optimization: - * [NLPStopping](https://github.com/Goysa2/Stopping.jl/blob/master/src/Stopping/NLPStoppingmod.jl) with [NLPAtX](https://github.com/Goysa2/Stopping.jl/blob/master/src/State/NLPAtXmod.jl) as a specialized State for non-linear programming (based on [NLPModels](https://github.com/JuliaSmoothOptimizers/NLPModels.jl)); - * [LS_Stopping](https://github.com/Goysa2/Stopping.jl/blob/master/src/Stopping/LineSearchStoppingmod.jl) with [LSAtT](https://github.com/Goysa2/Stopping.jl/blob/master/src/State/LSAtTmod.jl) as a specialized State for 1d optimization; - * more to come. - -In these examples, the function `optimality_residual` computing the residual of the optimality conditions is an additional attribute of the types. + * [NLPStopping](https://github.com/vepiteski/Stopping.jl/blob/master/src/Stopping/NLPStoppingmod.jl) with [NLPAtX](https://github.com/vepiteski/Stopping.jl/blob/master/src/State/NLPAtXmod.jl) as a specialized State: for non-linear programming (based on [NLPModels](https://github.com/JuliaSmoothOptimizers/NLPModels.jl)); + * [LAStopping](https://github.com/vepiteski/Stopping.jl/blob/master/src/Stopping/LinearAlgebraStopping.jl) with [GenericState](https://github.com/vepiteski/Stopping.jl/blob/master/src/State/GenericStatemod.jl): for linear algebra problems. + * [LS_Stopping](https://github.com/vepiteski/Stopping.jl/blob/master/src/Stopping/LineSearchStoppingmod.jl) with [LSAtT](https://github.com/vepiteski/Stopping.jl/blob/master/src/State/LSAtTmod.jl) as a specialized State: for 1d optimization; + * more to come... ## Functions -An AbstractStopping has two main functions: -* `start!(stp :: AbstractStopping)` initializes the time and the tolerance at the starting point and check whether the initial guess is optimal; -* `stop!(stp :: AbstractStopping)` checks optimality of the current guess as well as a failure of the system (unboundedness for instance) and maximum resources (number of evaluations of functions, elapsed time ...). +The tool provides two main functions: +* `start!(stp :: AbstractStopping)` initializes the time and the tolerance at the starting point and check wether the initial guess is optimal. +* `stop!(stp :: AbstractStopping)` checks optimality of the current guess as well as failure of the system (unboundedness for instance) and maximum resources (number of evaluations of functions, elapsed time ...) -Stopping uses the information furnished by the State to assess the success. Communication between the two can be done through the following functions: -* `update_and_start!(stp :: AbstractStopping; kwargs...)` updates the State with information furnished as kwargs and then call start!. -* `update_and_stop!(stp :: AbstractStopping; kwargs...)` updates the State with information furnished as kwargs and then call stop!. -* `fill_in!(stp :: AbstractStopping, x :: Iterate)` a function that fill in all the State with all the information required to evaluate the Stopping functions correctly. This can reveal useful, for instance, if the user do not trust the information furnished by the algorithm in the State. +Stopping uses the informations furnished by the State to evaluate its functions. Communication between the two can be done through the following functions: +* `update_and_start!(stp :: AbstractStopping; kwargs...)` updates the states with informations furnished as kwargs and then call start!. +* `update_and_stop!(stp :: AbstractStopping; kwargs...)` updates the states with informations furnished as kwargs and then call stop!. +* `fill_in!(stp :: AbstractStopping, x :: Iterate)` a function that fill in all the State with all the informations required to correctly evaluate the stopping functions. This can reveal useful, for instance, if the user do not trust the informations furnished by the algorithm in the State. * `reinit!(stp :: AbstractStopping)` reinitialize the entries of the Stopping to reuse for another call. -Consult the [HowTo tutorial](https://github.com/Goysa2/Stopping.jl/blob/master/test/examples/runhowto.jl) to learn more about the possibilities offered by Stopping. +Consult the [HowTo tutorial](https://github.com/vepiteski/Stopping.jl/blob/master/test/examples/runhowto.jl) to learn more about the possibilities offered by Stopping. -You can also access other examples of algorithms in the [test/examples](https://github.com/Goysa2/Stopping.jl/blob/master/test/examples/) folder, which for instance illustrate the strength of Stopping with subproblems: -* Consult the [OptimSolver tutorial](https://github.com/Goysa2/Stopping.jl/blob/master/test/examples/run-optimsolver.jl) for more on how to use Stopping with nested algorithms. -* Check the [Benchmark tutorial](https://github.com/Goysa2/Stopping.jl/blob/master/test/examples/benchmark.jl) to see how Stopping can combined with [SolverBenchmark.jl](https://juliasmoothoptimizers.github.io/SolverBenchmark.jl/). -* Stopping can be adapted to closed solvers via a buffer function as in [Buffer tutorial](https://github.com/Goysa2/Stopping.jl/blob/master/test/examples/buffer.jl) for an instance with [Ipopt](https://github.com/JuliaOpt/Ipopt.jl) via [NLPModelsIpopt](https://github.com/JuliaSmoothOptimizers/NLPModelsIpopt.jl). +You can also access other examples of algorithms in the [test/examples](https://github.com/vepiteski/Stopping.jl/blob/master/test/examples/) folder, which for instance illustrate the strenght of Stopping with subproblems: +* Consult the [OptimSolver tutorial](https://github.com/vepiteski/Stopping.jl/blob/master/test/examples/run-optimsolver.jl) for more on how to use Stopping with nested algorithms. +* Check the [Benchmark tutorial](https://github.com/vepiteski/Stopping.jl/blob/master/test/examples/benchmark.jl) to see how Stopping can combined with [SolverBenchmark.jl](https://juliasmoothoptimizers.github.io/SolverBenchmark.jl/). +* Stopping can be adapted to closed solvers via a buffer function as in [Buffer tutorial](https://github.com/vepiteski/Stopping.jl/blob/master/test/examples/buffer.jl) for an instance with [Ipopt](https://github.com/JuliaOpt/Ipopt.jl) via [NLPModelsIpopt](https://github.com/JuliaSmoothOptimizers/NLPModelsIpopt.jl). ## How to install Install and test the Stopping package with the Julia package manager: @@ -62,14 +63,15 @@ Install and test the Stopping package with the Julia package manager: pkg> add Stopping pkg> test Stopping ``` -You can also access the most up-to-date version of the Stopping package using: +You can access the most up-to-date version of the Stopping package using: ```julia -pkg> add https://github.com/Goysa2/Stopping.jl +pkg> add https://github.com/vepiteski/Stopping.jl pkg> test Stopping +pkg> status Stopping ``` ## Example -As an example, a naive version of the Newton method is provided [here](https://github.com/Goysa2/Stopping.jl/blob/master/test/examples/newton.jl). First we import the packages: +As an example, a naive version of the Newton method is provided [here](https://github.com/vepiteski/Stopping.jl/blob/master/test/examples/newton.jl). First we import the packages: ``` using LinearAlgebra, NLPModels, Stopping ``` @@ -80,13 +82,13 @@ f(x) = 0.5 * x' * Q * x nlp = ADNLPModel(f, ones(5)) ``` -We now initialize the NLPStopping. First create a State. +We now initialize the *NLPStopping*. First create a State. ``` nlp_at_x = NLPAtX(ones(5)) ``` -We use [unconstrained_check](https://github.com/Goysa2/Stopping.jl/blob/master/src/Stopping/nlp_admissible_functions.jl) as an optimality function +We use [unconstrained_check](https://github.com/vepiteski/Stopping.jl/blob/master/src/Stopping/nlp_admissible_functions.jl) as an optimality function ``` -stop_nlp = NLPStopping(nlp, unconstrained_check, nlp_at_x) +stop_nlp = NLPStopping(nlp, nlp_at_x, optimality_check = unconstrained_check) ``` Note that, since we used a default State, an alternative would have been: ```