seisflows.plugins.line_search.backtrack
=======================================

.. py:module:: seisflows.plugins.line_search.backtrack

.. autoapi-nested-parse::

   Backtracking line search class plugin to be used with an L-BFGS optimization

   https://en.wikipedia.org/wiki/Backtracking_line_search



Classes
-------

.. autoapisummary::

   seisflows.plugins.line_search.backtrack.Backtrack


Module Contents
---------------

.. py:class:: Backtrack

   Bases: :py:obj:`seisflows.plugins.line_search.bracket.Bracket`


   [line_search.backtrack] Backtracking line search assumes the
   gradient is well scaled from the L-BFGS optimization algorithm, such
   that a unit step length (1) will provide a decrease in misfit. If
   misfit does not decrease, the backtracking step count follows a
   parabolic backtrack from 1 -> 0 in search of a decreased misfit. If the
   backtracked value becomes too small the backtracking line search defaults to
   a Bracketing line search.

   Variables Descriptions:
       x: list of step lenths from current line search
       f: correpsonding list of function values
       m: number of step lengths in current line search
       n: number of model updates in optimization problem
       gtg: dot product of gradient with itself
       gtp: dot product of gradient and search direction

   Status codes
       status == 1   : PASS, line search finished
       status == 0   : TRY/RETRY, attempt line search w/ new step length
       status == -1  : FAIL, line search exceeds internal criteria


   .. py:method:: calculate_step_length()

      Determines step length and search status. Defaults to 'Bracket'ing
      line search during the first evaluation (waiting for the L-BFGS to scale
      properly).

      .. note::
          Search history variable descriptions:
          x: list of step lenths from current line search
          f: correpsonding list of function values
          m: number of step lengths in current line search
          n: number of model updates in optimization problem
          gtg: dot product of gradient with itself
          gtp: dot product of gradient and search direction

      .. note:
          Available status returns are:
          'TRY': try/re-try the line search as conditions have not been met
          'PASS': line search was successful, you can terminate the search
          'FAIL': line search has failed for one or more reasons.

      :rtype: tuple (float, str)
      :return: (alpha==calculated step length,
          status==how to treat the next step count evaluation)