update doc test

SolverStoppingJulia · Oct 22, 2020 · 4282324 · 4282324
1 parent 28e5f18
commit 4282324
Show file tree

Hide file tree

Showing 3 changed files with 62 additions and 42 deletions.
diff --git 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
@@ -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,14 +41,21 @@ Stopping.fill_in!
 Stopping.status
 ```
 
-## Non linear admissibility functions
+## Non-linear admissibility functions
 ```@docs
 Stopping.KKT
 Stopping.unconstrained_check
 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
@@ -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,46 +32,46 @@ 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:
 ```julia
 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:
 ```