This API reference is not for the latest stable Salvus version.

`salvus.opt.methods.trustregion`

Trust-region optimization methods

Classes

`TrustRegion`

class TrustRegion(salvus.flow.utils.serialization_helpers.SerializationMixin):
    def __init__(
        self,
        initial_trust_region_radius: Optional[
            int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64
        ] = None,
        initial_trust_region_linf: Optional[
            int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64
        ] = None,
        max_lbfgs_history: Union[int, numpy.int32, numpy.int64] = 10,
        max_lbfgs_radius: Optional[
            int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64
        ] = None,
        min_model_update_norm: Union[
            int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64
        ] = 0.0,
        convergence_criteria: Dict = {},
        use_event_dependent_gradients: Union[
            bool, Literal["auto-detect"]
        ] = True,
        use_preconditioner: Optional[bool] = True,
        tr_eta_1: Union[
            int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64
        ] = 0.001,
        tr_eta_2: Union[
            int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64
        ] = 0.5,
        tr_gamma_1: Union[
            int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64
        ] = 0.5,
        tr_gamma_2: Union[
            int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64
        ] = 0.9,
        tr_sigma: Union[
            int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64
        ] = 2.0,
    ): ...

Base class of trust region methods.

The following rules apply for updating the trust region radius:

In the first iteration, the initial trust region radius is computed such that the suggested model update satisfies the provided bound on its norm. Here, initial_trust_region_linf is applied pointwise for all model parameters, while initial_trust_region_radius measures distance in the model norm. If both parameters are provided, the more restrictive condition is used.
In subsequent iterations, the trust region radius is adaptively adjusted. This is based on the following criteria, where $\rho$ is the ratio of actual and predicted reduction, $\Delta_{tr}$ denotes the current trust region radius, and $\|\mathbf{m}\|$ is the norm of the model update:

if $\rho < \eta_1$ (poor prediction of the quadratic model): $\Delta_{tr}^{new} = \min(\sigma^{-1}\Delta_{tr}, \|\mathbf{m}\|)$
else if $\rho > \eta_2$ and $\|\mathbf{m}\| \geq \gamma_2 \Delta_{tr}$ (good prediction and model update sufficiently close to trust-region bound): $\Delta_{tr}^{new} = \sigma\Delta_{tr}$
else if $\|\mathbf{m}\| < \gamma_1 \Delta_{tr}$ (small update): $\Delta_{tr}^{new} = \max(\sigma^{-1}\Delta_{tr}, \sigma\|\mathbf{m}\|)$

Parameters

initial_trust_region_radius Optional[int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64] — Initial trust region radius (distance in model norm).
initial_trust_region_linf Optional[int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64] — Initial trust region radius (distance in L-infty norm).
max_lbfgs_history Union[int, numpy.int32, numpy.int64] — Maximum history of L-BFGS approximation.
max_lbfgs_radius Optional[int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64] — Maximum radius (in model space norm) of models considered in L-BFGS approximation.
min_model_update_norm Union[int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64] — Threshold on the norm of the model update.
convergence_criteria Dict — Dictionary of covergence criteria. This can also be provided later on.
use_event_dependent_gradients Union[bool, Literal['auto-detect']] — Flag to indicate whether the event-dependent gradients should be computed independently or whether it is sufficient to directly obtain the summed gradient accumulated from all events. Can be set to “auto-detect”, which means that the InverseProblemConfiguration object will check if the forward simulation used event-dependent mesh masking and set the flag accordingly. Defaults to True.
use_preconditioner Optional[bool] — Flag to skip preconditioner.
tr_eta_1 Union[int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64] — Steering parameter for adjusting the trust region; see formulas above.
tr_eta_2 Union[int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64] — Steering parameter for adjusting the trust region; see formulas above.
tr_gamma_1 Union[int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64] — Steering parameter for adjusting the trust region; see formulas above.
tr_gamma_2 Union[int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64] — Steering parameter for adjusting the trust region; see formulas above.
tr_sigma Union[int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64] — Steering parameter for adjusting the trust region; see formulas above.

Methods

`from_json()`

def from_json(d: Dict) -> Any: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters

d Dict — Dictionary containing its init parameters and a few other things.

Returns Any

`iterate()`

def iterate(
    self,
    it: salvus.opt.iteration.Iteration,
    task_manager: Dict[str, Callable],
    it_history: Optional[Dict[int, salvus.opt.iteration.Iteration]] = {},
) -> None: ...

Run or continue a full iteration.

Parameters

it salvus.opt.iteration.Iteration — The current iteration.
task_manager Dict[str, Callable] — Dictionary of custom callback functions to process the tasks (e.g. for computing misfits) issued during the inversion.
it_history Optional[Dict[int, salvus.opt.iteration.Iteration]] — Dictionary with the iteration history.

Returns None

`resume()`

def resume(
    self,
    it: salvus.opt.iteration.Iteration,
    it_history: Optional[Dict[int, salvus.opt.iteration.Iteration]] = {},
) -> None: ...

Resume an iteration. This function continues to compute a model update until the next compute intensive task (e.g. querying misfits) is reached. The iteration data will be updated internally.

The function will raise an error if there are unfinished tasks.

Parameters

it salvus.opt.iteration.Iteration — Current iteration.
it_history Optional[Dict[int, salvus.opt.iteration.Iteration]] — Dictionary with the iteration history.

Returns None

`solve()`

def solve(
    self,
    current_iteration: salvus.opt.iteration.Iteration,
    task_manager: Dict[str, Callable],
    max_iterations: int,
    it_history: Dict[int, salvus.opt.iteration.Iteration] = {},
    convergence_criteria: Dict = {},
) -> salvus.opt.iteration.Iteration: ...

Run or continue an inversion until a maximum number of iterations is reached.

Parameters

current_iteration salvus.opt.iteration.Iteration — The current iteration.
task_manager Dict[str, Callable] — Dictionary of custom callback functions to process the tasks (e.g. for computing misfits) issued during the inversion.
max_iterations int — Maximum number of iterations to be computed.
it_history Dict[int, salvus.opt.iteration.Iteration] — Dictionary with the iteration history.
convergence_criteria Dict — Dictionary of covergence criteria. This can also be provided later on.

Returns salvus.opt.iteration.Iteration

`to_json()`

def to_json(self, external_file_hash: Optional[str] = None) -> Dict: ...

Serialize the object to dictionary that can be written to JSON.

Parameters

external_file_hash Optional[str] — Hash of any external files associated with this object. Can be passed here in which case it will be stored in a centralized location in the JSON file.

Returns Dict