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

salvus.project.components.inversion_component

Classes

InversionComponent

class InversionComponent(builtins.object):
    def __init__(self, project: salvus.project.project.Project): ...

Project subclass handling inverse problems.

Parameters
  • project salvus.project.project.Project — The project for the component.
Methods
add_events()
def add_events(
    self, inverse_problem_configuration: str, events: Union[str, Sequence[str]]
) -> None: ...

Add events to an inverse problem. The events have to exist in the project already.

Parameters
  • inverse_problem_configuration str — The inverse problem.
  • events Union[str, Sequence[str]] — Event name or list of event names.
Returns None
add_iteration()
def add_iteration(
    self,
    inverse_problem_configuration: str,
    model: Optional[str] = None,
    events: Optional[Sequence[str]] = None,
    control_group_events: Optional[Sequence[str]] = None,
    misfit_configuration: Optional[str] = None,
    parent_id: Optional[int] = None,
) -> bool: ...

Add a new iteration to an inverse problem. All components that are not specified directly are either inherited from the parent iteration (if provided) or from the inverse problem.

Parameters
  • inverse_problem_configuration str — The inverse problem.
  • model Optional[str] — The model of the iteration. If not provided either the final model from the parent iteration or the prior model of the inverse problem is used.
  • events Optional[Sequence[str]] — Iteration-specific event selection.
  • control_group_events Optional[Sequence[str]] — Iteration-specific control group.
  • misfit_configuration Optional[str] — Name of the misfit configuration.
  • parent_id Optional[int] — Id of the parent iteration that this iteration should be derived from.
Returns bool
delete()
def delete(self, inverse_problem_name: str) -> None: ...

Delete an inverse problem. Attention: This will remove all associated models and can lead to significant data loss.

Parameters
  • inverse_problem_name str — The inverse problem to be deleted.
Returns None
delete_disposable_files()
def delete_disposable_files(
    self,
    inverse_problem_configuration: Union[
        str,
        salvus.project.configuration.inverse_problem_configuration.InverseProblemConfiguration,
    ],
    iteration_id: Optional[int] = None,
    data_to_remove: Union[str, Sequence[str]] = "auxiliary",
    keep_data_from_first_iteration: bool = True,
    keep_data_from_unfinished_iterations: bool = True,
) -> None: ...

Delete files such as waveforms, gradients or auxiliary files that are not strictly required to continue the inversion, or can be recomputed if needed.

Parameters
  • inverse_problem_configuration Union[str, salvus.project.configuration.inverse_problem_configuration.InverseProblemConfiguration] — The inverse problem.
  • iteration_id Optional[int] — Optional iteration ID. If not specified, disposable files from all finished iterations except the initial model will be deleted.
  • data_to_remove Union[str, Sequence[str]] — Specify which data to delete. Can be either all for all that can be recomputed, or any combination of auxiliary, waveforms, and gradients. Note that waveforms are cheaper to recompute than gradients and should be deleted second after auxiliary files.
  • keep_data_from_first_iteration bool — Option to also remove data from iterations without a parent id. If True, the files of the initial iteration will be kept.
  • keep_data_from_unfinished_iterations bool — Option to also remove data from unfinished iterations, including the current one. Running this function with False is recommended when finishing an inversion.
Returns None
delete_iteration()
def delete_iteration(
    self, inverse_problem_configuration: str, id: int
) -> None: ...

Delete an iteration.

Parameters
  • inverse_problem_configuration str — The inverse problem.
  • id int — Id of the iteration to be deleted.
Returns None
get_iteration()
def get_iteration(
    self, inverse_problem_configuration: str, iteration_id: int
) -> salvus.opt.iteration.Iteration: ...

Get the iteration object from an inverse problem configuration and index.

Parameters
  • inverse_problem_configuration str — The inverse problem.
  • iteration_id int — Iteration ID.
Returns salvus.opt.iteration.Iteration
get_iteration_directory()
def get_iteration_directory(
    self,
    inverse_problem_configuration: Union[
        str,
        salvus.project.configuration.inverse_problem_configuration.InverseProblemConfiguration,
    ],
    iteration_id: int,
) -> pathlib.Path: ...

Get the directory containing all the models of an iteration.

Parameters
  • inverse_problem_configuration Union[str, salvus.project.configuration.inverse_problem_configuration.InverseProblemConfiguration] — The inverse problem.
  • iteration_id int — Iteration ID.
Returns pathlib.Path
get_misfits()
def get_misfits(
    self,
    inversions: Optional[Sequence[str]] = None,
    combine_event_misfits: bool = False,
    events: Optional[Sequence[str]] = None,
    misfit_type: Union[
        Literal["absolute"], Literal["relative"], Literal["iteration_relative"]
    ] = "absolute",
) -> Union[
    Dict[str, numpy.ndarray[Any, numpy.dtype[+_ScalarType_co]]],
    Dict[str, Dict[str, numpy.ndarray[Any, numpy.dtype[+_ScalarType_co]]]],
]: ...

Retrieves aggregated misfit values for specified inverse problems and events.

This function aggregates misfit values across different events for each inversion problem. The aggregation can be either a sum or a mean, based on the misfit_type. It supports filtering by specific inversions and events.

If combine_event_misfits is True and no events are found for an inversion, and empty list is returned as the misfit array for that inversion. If combine_event_misfits is False, empty dictionaries will be returned per inversion for which no events are found.

Parameters
  • inversions Optional[Sequence[str]] — An optional sequence of inversion problem identifiers. If None, misfits for all inversions are retrieved.
  • combine_event_misfits bool — A flag indicating whether to aggregate misfits across events. If True, misfits for each inversion are combined into a single value per inversion; otherwise, misfits are returned per event per inversion. This will raise a ValueError if used in conjuction with iteration-dependent event selections.
  • events Optional[Sequence[str]] — An optional sequence of event identifiers. If None, misfits for all events are retrieved.
  • misfit_type Union[Literal['absolute'], Literal['relative'], Literal['iteration_relative']] — Specifies the type of misfit calculation. Can be ‘absolute’, ‘relative’, or ‘iteration_relative’.
Returns Union[Dict[str, numpy.ndarray[Any, numpy.dtype[+_ScalarType_co]]], Dict[str, Dict[str, numpy.ndarray[Any, numpy.dtype[+_ScalarType_co]]]]] — A dictionary mapping each inversion problem identifier to its aggregated misfit value(s). If combine_event_misfits is False, the dictionary maps inversion problem identifiers to another dictionary mapping event identifiers to their respective misfit values.
get_model()
def get_model(
    self,
    inverse_problem_configuration: Union[
        str,
        salvus.project.configuration.inverse_problem_configuration.InverseProblemConfiguration,
    ],
    iteration_id: int,
) -> (
    salvus.mesh.data_structures.unstructured_mesh.unstructured_mesh.UnstructuredMesh
): ...

Obtain the model of an iteration as unstructured mesh.

Parameters
  • inverse_problem_configuration Union[str, salvus.project.configuration.inverse_problem_configuration.InverseProblemConfiguration] — The inverse problem.
  • iteration_id int — Iteration ID.
Returns salvus.mesh.data_structures.unstructured_mesh.unstructured_mesh.UnstructuredMesh
get_simulation_name()
def get_simulation_name(
    self,
    inverse_problem_configuration: Union[
        str,
        salvus.project.configuration.inverse_problem_configuration.InverseProblemConfiguration,
    ],
    iteration_id: int,
) -> str: ...

Get the name of the simulation configuration that belongs to an iteration.

Parameters
  • inverse_problem_configuration Union[str, salvus.project.configuration.inverse_problem_configuration.InverseProblemConfiguration] — The inverse problem.
  • iteration_id int — Iteration ID.
Returns str
iterate()
def iterate(
    self,
    inverse_problem_configuration: Union[
        str,
        salvus.project.configuration.inverse_problem_configuration.InverseProblemConfiguration,
    ],
    timeout_in_seconds: Union[
        int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64
    ],
    ping_interval_in_seconds: Optional[
        int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64
    ] = None,
    iteration_ids: Union[str, int, List[int]] = "latest",
    delete_disposable_files: Optional[str, List[str]] = None,
) -> None: ...

Run or continue an iteration until a model update has been computed successfully. The function can be called on any state of the iteration. In particular, if the previous attempt reached the time limit, repeated calls to this function will continue with the iteration where it stopped the last time.

Parameters
  • inverse_problem_configuration Union[str, salvus.project.configuration.inverse_problem_configuration.InverseProblemConfiguration] — The inverse problem.
  • timeout_in_seconds Union[int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64] — Maximum time spent after which the function returns even if the iteration has not been completed yet.
  • ping_interval_in_seconds Optional[int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64] — Ping interval to check for updated on the simulations.
  • iteration_ids Union[str, int, List[int]] — List of iteration IDs to be processed. Alternatively, the key words latest (default, use only the latest iteration) or all (use all running iterations) can be provided.
  • delete_disposable_files Optional[str, List[str]] — Optional cleanup stage when finalizing the iteration. Possible choices are all, or any combination of auxiliary, checkpoints, waveforms, and gradients.
Returns None
list()
def list(self) -> List[str]: ...

Get a list of all inverse problem configurations.

Returns List[str]
resume()
def resume(
    self,
    inverse_problem_configuration: Union[
        str,
        salvus.project.configuration.inverse_problem_configuration.InverseProblemConfiguration,
    ],
    iteration_ids: Union[str, int, List[int]] = "latest",
    verbosity: int = 1,
) -> None: ...

Resume with the inversion. This function steps through the optimization algorithm in sequences and returns whenever a new task that potentially requires longer compute time has been issued.

Repeated calls to this function will advance an iteration until a model update has been successfully computed.

If no iterations are specified, this function will advance all unfinished iterations of the inverse problem.

Parameters
  • inverse_problem_configuration Union[str, salvus.project.configuration.inverse_problem_configuration.InverseProblemConfiguration] — The inverse problem.
  • iteration_ids Union[str, int, List[int]] — List of iteration IDs to be processed. If not provided, all running iterations will be considered.
  • verbosity int — Verbosity level.
Returns None
set_constraints()
def set_constraints(
    self, inverse_problem_configuration: str, constraints: Dict
) -> None: ...

Set or modify the stopping criteria for the inverse problem.

Parameters
  • inverse_problem_configuration str — The inverse problem.
  • constraints Dict — Dictionary of constraints. Currently supported are pointwise lower and/or upper bounds on the inversion parameters.
Returns None
set_job_submission_configuration()
def set_job_submission_configuration(
    self,
    inverse_problem_configuration: str,
    job_submission: Union[
        salvus.flow.executors.executor_utils.SiteConfig,
        Dict[
            str,
            Union[
                salvus.flow.executors.executor_utils.SiteConfig,
                bool,
                Dict[
                    str,
                    salvus.flow.executors.task_chain.task_chain_site_config.TaskChainSiteConfig,
                ],
            ],
        ],
    ],
) -> None: ...

Set or modify the job submission configuration of an inverse problem. for asynchronous tasks.

Parameters
  • inverse_problem_configuration str — The inverse problem.
  • job_submission Union[salvus.flow.executors.executor_utils.SiteConfig, Dict[str, Union[salvus.flow.executors.executor_utils.SiteConfig, bool, Dict[str, salvus.flow.executors.task_chain.task_chain_site_config.TaskChainSiteConfig]]]] — Either a SiteConfig or a dictionary of SiteConfigs with keys forward, adjoint, and preconditioner.
Returns None
set_stopping_criteria()
def set_stopping_criteria(
    self, inverse_problem_configuration: str, criteria: Dict
) -> None: ...

Set or modify the stopping criteria for the inverse problem.

Parameters
  • inverse_problem_configuration str — The inverse problem.
  • criteria Dict — Dictionary of stopping criteria. If any of them is true, no further iterations will be added. Currently supported are max_iterations for the maximum number of iterations per branch and max_iterations_global for the maximum number of iterations in the entire inversion tree.
Returns None
set_wavefield_compression()
def set_wavefield_compression(
    self,
    inverse_problem_configuration: str,
    wavefield_compression: salvus.flow.collections.wavefield_compression.WavefieldCompression,
) -> None: ...

Set or modify the wavefield compression settings for computing gradients.

Parameters
  • inverse_problem_configuration str — The inverse problem.
  • wavefield_compression salvus.flow.collections.wavefield_compression.WavefieldCompression — Wavefield compression settings.
Returns None