seisflows.plugins.line_search

Submodules

Classes

`Bracket`	[line_search.bracket] The bracketing line search identifies two points
`Backtrack`	[line_search.backtrack] Backtracking line search assumes the

Package Contents

class seisflows.plugins.line_search.Bracket(step_count_max, path=None)

[line_search.bracket] The bracketing line search identifies two points between which the minimum misfit lies between.

Parameters:: step_count_max (int) – maximum number of step counts before changing line search behavior. set by PAR.STEP_COUNT_MAX

step_count_max

func_vals = []

step_lens = []

gtg = []

gtp = []

step_count = 0

iteridx = []

__str__(): Simply print out all attributes, used for debugging mainly

property update_count: Independently keeps track of how many model updates we have made

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.

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

Parameters:

func_val (float) – value of the objective function evaluation
step_len (float) – length of step for the trial model (alpha)
gtg (float) – dot product of gradient with itself
gtp (float) – dot product of gradient with search direction

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

Parameters:

func_val (float) – value of the objective function evaluation
step_len (float) – length of step for the trial model (alpha)

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.

_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

_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.

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

Return type:: (np.array, np.array, np.array)
Returns:: (step lengths of current line search, misfits of current line search, step count associated with given step length and misfit)

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.

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

class seisflows.plugins.line_search.Backtrack

Bases: 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

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

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