dlib C++ Library - optimization_stop_strategies_abstract.h

    // Copyright (C) 2008  Davis E. King (davis@dlib.net)
    // License: Boost Software License   See LICENSE.txt for the full license.
    #undef DLIB_OPTIMIZATIOn_STOP_STRATEGIES_ABSTRACT_
    #ifdef DLIB_OPTIMIZATIOn_STOP_STRATEGIES_ABSTRACT_

    #include <cmath>
    #include <limits>
    #include "../matrix/matrix_abstract.h"
    #include "../algs.h"

    namespace dlib
    {

    // ----------------------------------------------------------------------------------------

        class objective_delta_stop_strategy
        {
            /*!
                WHAT THIS OBJECT REPRESENTS
                    This object represents a strategy for deciding if an optimization
                    algorithm should terminate.   This particular object looks at the
                    change in the objective function from one iteration to the next and
                    bases its decision on how large this change is.  If the change
                    is below a user given threshold then the search stops.
            !*/

        public:
            explicit objective_delta_stop_strategy (
                double min_delta = 1e-7
            );
            /*!
                requires
                    - min_delta >= 0
                ensures
                    - This stop strategy object will only consider a search to be complete
                      if a change in an objective function from one iteration to the next
                      is less than min_delta.
            !*/

            objective_delta_stop_strategy (
                double min_delta,
                unsigned long max_iter
            );
            /*!
                requires
                    - min_delta >= 0
                    - max_iter > 0
                ensures
                    - This stop strategy object will only consider a search to be complete
                      if a change in an objective function from one iteration to the next
                      is less than min_delta or more than max_iter iterations has been
                      executed.
            !*/

            objective_delta_stop_strategy& be_verbose(
            );
            /*!
                ensures
                    - causes this object to print status messages to standard out
                      every time should_continue_search() is called.
                    - returns *this
            !*/

            template <typename T>
            bool should_continue_search (
                const T& x,
                const double funct_value,
                const T& funct_derivative
            );
            /*!
                requires
                    - this function is only called once per search iteration
                    - for some objective function f():
                        - x == the search point for the current iteration
                        - funct_value == f(x)
                        - funct_derivative == derivative(f)(x)
                ensures
                    - returns true if the point x doest not satisfy the stopping condition and
                      false otherwise.
            !*/

        };

    // ----------------------------------------------------------------------------------------

        class gradient_norm_stop_strategy
        {
            /*!
                WHAT THIS OBJECT REPRESENTS
                    This object represents a strategy for deciding if an optimization
                    algorithm should terminate.   This particular object looks at the
                    norm (i.e. the length) of the current gradient vector and stops
                    if it is smaller than a user given threshold.
            !*/

        public:
            explicit gradient_norm_stop_strategy (
                double min_norm = 1e-7
            );
            /*!
                requires
                    - min_norm >= 0
                ensures
                    - This stop strategy object will only consider a search to be complete
                      if the current gradient norm is less than min_norm
            !*/

            gradient_norm_stop_strategy (
                double min_norm,
                unsigned long max_iter
            );
            /*!
                requires
                    - min_norm >= 0
                    - max_iter > 0
                ensures
                    - This stop strategy object will only consider a search to be complete
                      if the current gradient norm is less than min_norm or more than
                      max_iter iterations has been executed.
            !*/

            gradient_norm_stop_strategy& be_verbose(
            );
            /*!
                ensures
                    - causes this object to print status messages to standard out
                      every time should_continue_search() is called.
                    - returns *this
            !*/

            template <typename T>
            bool should_continue_search (
                const T& x,
                const double funct_value,
                const T& funct_derivative
            );
            /*!
                requires
                    - this function is only called once per search iteration
                    - for some objective function f():
                        - x == the search point for the current iteration
                        - funct_value == f(x)
                        - funct_derivative == derivative(f)(x)
                ensures
                    - returns true if the point x doest not satisfy the stopping condition and
                      false otherwise.
            !*/

        };

    // ----------------------------------------------------------------------------------------

    }

    #endif // DLIB_OPTIMIZATIOn_STOP_STRATEGIES_ABSTRACT_