seisflows.optimize.NLCG
=======================

.. py:module:: seisflows.optimize.NLCG

.. autoapi-nested-parse::

   Nonlinear conjugate gradient method for optimization



Classes
-------

.. autoapisummary::

   seisflows.optimize.NLCG.NLCG


Functions
---------

.. autoapisummary::

   seisflows.optimize.NLCG.check_conjugacy
   seisflows.optimize.NLCG.check_descent


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

.. py:class:: NLCG(nlcg_max=np.inf, nlcg_thresh=np.inf, calc_beta='pollak_ribere', **kwargs)

   Bases: :py:obj:`seisflows.optimize.gradient.Gradient`


   NLCG Optimization
   -----------------
   Nonlinear conjugate gradient method

   Parameters
   ----------
   :type nlcg_max: int
   :param nlcg_max: NLCG periodic restart interval, should be between 1
       and infinity
   :type nlcg_thresh: NLCG conjugacy restart threshold, should be
       between 1 and infinity
   :type calc_beta: str
   :param calc_beta: method to calculate the parameter 'beta' in the
       NLCG algorithm. Available: 'pollak_ribere', 'fletcher_reeves'

   Paths
   -----
   ***


   .. py:attribute:: __doc__
      :value: Multiline-String

      .. raw:: html

         <details><summary>Show Value</summary>

      .. code-block:: python

         """
             Gradient Optimization [Optimize Base]
             -------------------------------------
             Defines foundational structure for Optimization module. Applies a 
             gradient/steepest descent optimization algorithm.
         
             Parameters
             ----------
             :type line_search_method: str
             :param line_search_method: chosen line_search algorithm. Currently available
                 are 'bracket' and 'backtrack'. See seisflows.plugins.line_search
                 for all available options
             :type preconditioner: str
             :param preconditioner: algorithm for preconditioning gradients. Currently
                 available: 'diagonal'. Requires `path_preconditioner` to point to a
                 set of files that define the preconditioner, formatted the same as the
                 input model
             :type step_count_max: int
             :param step_count_max: maximum number of trial steps to perform during
                 the line search before a change in line search behavior is
                 considered, or a line search is considered to have failed.
             :type step_len_init: float
             :param step_len_init: initial line search step length guess, provided
                 as a fraction of current model parameters.
             :type step_len_max: float
             :param step_len_max: optional, maximum allowable step length during the line
                 search. Set as a fraction of the current model parameters
             :type step_len_min: float
             :param step_len_min: optional, minimum allowable step length during the line
                 search. Set as a fraction of the current model parameters
         
             Paths
             -----
             :type path_preconditioner: str
             :param path_preconditioner: optional path to a set of preconditioner files
                 formatted the same as the input model (or output model of solver).
                 Required to exist and contain files if `preconditioner`==True
             ***
             
         Nonlinear conjugate gradient method for optimization
         """

      .. raw:: html

         </details>




   .. py:attribute:: NLCG_max


   .. py:attribute:: NLCG_thresh


   .. py:attribute:: calc_beta
      :value: 'pollak_ribere'



   .. py:attribute:: _NLCG_iter
      :value: 0



   .. py:attribute:: _calc_beta


   .. py:method:: checkpoint()

      Overwrite default checkpointing to store internal L-BFGS Attributes



   .. py:method:: compute_direction()

      Compute search direction using the Nonlinear Conjugate Gradient method
      The potential outcomes when computing direction with NLCG

      1. First iteration of an NLCG optimization, search direction is
          the inverse gradient
      2. NLCG internal iteration ticks over the maximum allowable number of
          iterations, force a restart condition, search direction is the
          inverse gradient
      3. New NLCG search direction does not have conjugacy with previous
          search direction, force restart, inverse gradient search direction
      4. New NLCG search direction is not a descent direction,
          force restart, inverse gradient search direction
      5. New NLCG search direction has conjugacy and is a descent direction
          and is set as the new search direction.

      :rtype: seisflows.tools.specfem.Model
      :return: search direction as a Model instance



   .. py:method:: restart()

      Overwrite the Base restart class and include a restart of the NLCG



   .. py:method:: _fletcher_reeves(g_new, g_old)

      One method for calculating beta in the NLCG Algorithm from
      Fletcher & Reeves, 1964

      :type g_new: np.array
      :param g_new: new search direction
      :type g_old: np.array
      :param g_old: old search direction
      :rtype: float
      :return: beta, the scale factor to apply to the old search direction to
          determine the new search direction



   .. py:method:: _pollak_ribere(g_new, g_old)

      One method for calculating beta in the NLCG Algorithm from
      Polak & Ribiere, 1969

      :type g_new: np.array
      :param g_new: new search direction
      :type g_old: np.array
      :param g_old: old search direction
      :rtype: float
      :return: beta, the scale factor to apply to the old search direction to
          determine the new search direction



.. py:function:: check_conjugacy(g_new, g_old)

   Check for conjugacy between two vectors

   :type g_new: np.array
   :param g_new: new search direction
   :type g_old: np.array
   :param g_old: old search direction
   :rtype: float
   :return: an element that proves conjugacy


.. py:function:: check_descent(p_new, g_new)

   Ensure that the search direction is descending

   :type p_new: np.array
   :param p_new: search direction
   :type g_new: np.array
   :param g_new: gradient direction
   :rtype: float
   :return: the angle between search direction and gradient direction, should
       be negative to ensure descent