seisflows.plugins.line_search ============================= .. py:module:: seisflows.plugins.line_search Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/seisflows/plugins/line_search/backtrack/index /autoapi/seisflows/plugins/line_search/bracket/index Classes ------- .. autoapisummary:: seisflows.plugins.line_search.Bracket seisflows.plugins.line_search.Backtrack Package Contents ---------------- .. py:class:: Bracket(step_count_max, path=None) [line_search.bracket] The bracketing line search identifies two points between which the minimum misfit lies between. :type step_count_max: int :param step_count_max: maximum number of step counts before changing line search behavior. set by PAR.STEP_COUNT_MAX .. py:attribute:: step_count_max .. py:attribute:: func_vals :value: [] .. py:attribute:: step_lens :value: [] .. py:attribute:: gtg :value: [] .. py:attribute:: gtp :value: [] .. py:attribute:: step_count :value: 0 .. py:attribute:: iteridx :value: [] .. py:method:: __str__() Simply print out all attributes, used for debugging mainly .. py:property:: update_count Independently keeps track of how many model updates we have made .. py:method:: check() Make sure internal parameters are consistent with expectations. This is always expected to pass if the User/workflow uses the main functions to manipulate the line search. But occasionally some manual intervention is required, so the check function makes sure things are okay. .. py:method:: initialize_line_search(func_val, gtg, gtp) Input the initial values of a line search, corresponding to the initial model for this given iteration. Step length is assumed to be 0, because step length is calculated relative to the initial model. .. note:: This is a one-time permanent change to the search history, but can be rolled back manually by the User with `_restart_line_search` (to start over from before `initialize_line_search` :type func_val: float :param func_val: value of the objective function evaluation :type step_len: float :param step_len: length of step for the trial model (alpha) :type gtg: float :param gtg: dot product of gradient with itself :type gtp: float :param gtp: dot product of gradient with search direction .. py:method:: update_search_history(func_val, step_len) After a misfit evaluation for a trial model, line search needs to know how large the step (alpha) was, and the corresponding objective function misfit evaluation value. .. note:: This is a one-time permanent change to the search history, but can be rolled back manually by the User with `_revert_line_search`, to undo the update performed here :type func_val: float :param func_val: value of the objective function evaluation :type step_len: float :param step_len: length of step for the trial model (alpha) .. py:method:: clear_search_history() Clears internal line search history after an optimization restart. This is the 'nuclear' option, because it gets rid of ALL saved information about misfit evaluations from the previous iterations, i.e., this is like starting from scratch. .. py:method:: _restart_line_search() Iff a line search has been initialized and something goes awry, it is often preferable to restart the line search. To do this, we roll back the number of steps we have taken during the line search, and undo variable changes that took place in 'initialize_search'. .. note:: In order to proceed with workflow after running this function you will need to restart the workflow from `initialize_line_search` .. py:method:: _revert_search_history() Occasionally a line search will break mid-search but the User doesn't want to `restart_line_search`, but rather just roll back to the previous step count. This function steps back the search history by a number by one step. Call it multiple times to step back multiple steps Raises an error if there are no more steps to revert. .. py:method:: get_search_history() Get the step lengths and misfit function evaluations for the current line search. Sort the list by the step lengths to get a coherent list, as e.g., in a bracketing line search the actual order of the list does not match the magnitude of step lengths taken. .. note:: In the original SeisFlows the values of the search history were non-intuitive and difficult to understand at a glance. The original values are copied here as they relate to the mathematical formulations and so are still important: i = self.step_count k = len(self.step_lens) x = np.array(self.step_lens[k - i - 1:k]) f = np.array(self.func_vals[k - i - 1:k]) j = count_zeros(self.step_lens) - 1 # update count :rtype: (np.array, np.array, np.array) :return: (step lengths of current line search, misfits of current line search, step count associated with given step length and misfit) .. py:method:: calculate_step_length() Determines step length (alpha) and search status (status) using a bracketing line search. Evaluates Wolfe conditions to determine if a step length is acceptable. .. 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) .. 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)