Mondaic

salvus.project.components.inversion_component

salvus.project.components.inversion_component salvus project components inversion_component

The inversion component.

Classes

InversionComponent

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

Project subclass handling inverse problems.

Parameters
  • project Project — The project for the component.
Methods
add_events()
def add_events(
    self,
    inverse_problem_configuration: str,
    events: str | typing.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 str | typing.Sequence[str] — Event name or list of event names.
Returns None
add_iteration()
def add_iteration(
    self,
    inverse_problem_configuration: str,
    model: str | None = None,
    events: typing.Sequence[str] | None = None,
    control_group_events: typing.Sequence[str] | None = None,
    misfit_configuration: str | None = None,
    parent_id: int | None = None,
    comm: int | None = None,
    timer: Timer | None = None,
    log_to_logger: bool = False,
) -> 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 str | None — 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 typing.Sequence[str] | None — Iteration-specific event selection.
  • control_group_events typing.Sequence[str] | None — Iteration-specific control group.
  • misfit_configuration str | None — Name of the misfit configuration.
  • parent_id int | None — Id of the parent iteration that this iteration should be derived from.
  • comm int | None — MPI communicator for distributed operations, if applicable.
  • timer Timer | None — Execution timer.
  • log_to_logger bool — Log timings to logger.
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: str | InverseProblemConfiguration,
    iteration_id: int | None = None,
    data_to_remove: str | typing.Sequence[str] = "auxiliary",
    keep_data_from_first_iteration: bool = True,
    keep_data_from_unfinished_iterations: bool = True,
    comm: int | None = None,
) -> 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 str | InverseProblemConfiguration — The inverse problem.
  • iteration_id int | None — Optional iteration ID. If not specified, disposable files from all finished iterations except the initial model will be deleted.
  • data_to_remove str | typing.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.
  • comm int | None — MPI communicator, if any.
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
) -> 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 Iteration
get_iteration_directory()
def get_iteration_directory(
    self,
    inverse_problem_configuration: str | InverseProblemConfiguration,
    iteration_id: int,
) -> pathlib.Path: ...

Get the directory containing all the models of an iteration.

Parameters
  • inverse_problem_configuration str | InverseProblemConfiguration — The inverse problem.
  • iteration_id int — Iteration ID.
Returns pathlib.Path
get_misfits()
def get_misfits(
    self,
    inversions: typing.Sequence[str] | None = None,
    combine_event_misfits: bool = False,
    events: typing.Sequence[str] | None = None,
    misfit_type: typing.Literal[
        "absolute", "relative", "iteration_relative"
    ] = "absolute",
) -> dict[str, npt.NDArray] | dict[str, dict[str, npt.NDArray]]: ...

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 typing.Sequence[str] | None — 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 typing.Sequence[str] | None — An optional sequence of event identifiers. If None, misfits for all events are retrieved.
  • misfit_type typing.Literal['absolute', 'relative', 'iteration_relative'] — Specifies the type of misfit calculation. Can be ‘absolute’, ‘relative’, or ‘iteration_relative’.
Returns dict[str, npt.NDArray] | dict[str, dict[str, npt.NDArray]] — 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: str | InverseProblemConfiguration,
    iteration_id: int,
) -> UnstructuredMesh: ...

Obtain the model of an iteration as unstructured mesh.

Parameters
  • inverse_problem_configuration str | InverseProblemConfiguration — The inverse problem.
  • iteration_id int — Iteration ID.
Returns UnstructuredMesh
get_simulation_name()
def get_simulation_name(
    self,
    inverse_problem_configuration: str | InverseProblemConfiguration,
    iteration_id: int,
) -> str: ...

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

Parameters
  • inverse_problem_configuration str | InverseProblemConfiguration — The inverse problem.
  • iteration_id int — Iteration ID.
Returns str
iterate()
def iterate(
    self,
    inverse_problem_configuration: str | InverseProblemConfiguration,
    timeout_in_seconds: salvus._core.types.float_,
    ping_interval_in_seconds: salvus._core.types.float_ | None = None,
    iteration_ids: str | int | builtins.list[int] = "latest",
    delete_disposable_files: str | builtins.list[str] | None = None,
    timer: Timer | None = None,
    verbosity: int = 1,
    comm: int | None = None,
    log_to_logger: bool = False,
) -> 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 str | InverseProblemConfiguration — The inverse problem.
  • timeout_in_seconds salvus._core.types.float_ — Maximum time spent after which the function returns even if the iteration has not been completed yet.
  • ping_interval_in_seconds salvus._core.types.float_ | None — Ping interval to check for updated on the simulations.
  • iteration_ids str | int | builtins.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 str | builtins.list[str] | None — Optional cleanup stage when finalizing the iteration. Possible choices are all, or any combination of auxiliary, checkpoints, waveforms, and gradients.
  • timer Timer | None — Execution timer.
  • verbosity int — Verbosity level.
  • comm int | None — MPI communicator, if any.
  • log_to_logger bool — Whether to log timing information to the logger.
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: str | InverseProblemConfiguration,
    iteration_ids: str | int | builtins.list[int] = "latest",
    verbosity: int = 2,
    timer: Timer | None = None,
    comm: int | None = None,
    log_to_logger: bool = False,
) -> bool: ...

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 str | InverseProblemConfiguration — The inverse problem.
  • iteration_ids str | int | builtins.list[int] — List of iteration IDs to be processed. If not provided, all running iterations will be considered.
  • verbosity int — Verbosity level.
  • timer Timer | None — Execution timer.
  • comm int | None — MPI communicator, if any.
  • log_to_logger bool — Whether to log timing information to the logger.
Returns bool
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: (
        SiteConfig
        | TaskChainSiteConfig
        | dict[str, SiteConfig | bool | dict[str, TaskChainSiteConfig]]
        | MPIExecutionConfiguration
    ),
    comm: int | None = None,
) -> 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 SiteConfig | TaskChainSiteConfig | dict[str, SiteConfig | bool | dict[str, TaskChainSiteConfig]] | MPIExecutionConfiguration — Either a SiteConfig or a dictionary of SiteConfigs with keys forward, adjoint, and preconditioner. Alternatively it could be a TaskChainSiteConfig object or a dictionary of dictionaries with many task chain configurations on remote sites.
  • comm int | None — MPI communicator, if any.
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: WavefieldCompression,
) -> None: ...

Set or modify the wavefield compression settings for computing gradients.

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

Used in tutorials