`salvus.flow.executors.mpi.simulations`

Run simulations on MPI distributed meshes.

Functions

`run_adjoint_simulation()`

def run_adjoint_simulation(
    distributed_mesh: DistributedMesh,
    execution_config: MPIExecutionConfiguration,
    simulation: Simulation | None,
    adjoint_source_callback: typing.Callable[[EventData], EventMisfit],
    wavefield_compression: WavefieldCompression | None = None,
    gradient_parameters: set[str] | None = None,
    keep_intermediate_data_on_disk: bool = False,
    diagnostic_output_directory: pathlib.Path | None = None,
    verbosity: int = 1,
    timer: Timer | None = None,
    log_to_logger: bool = True,
) -> tuple[float, Mesh] | None: ...

Run a forward + adjoint simulation on an MPI distributed mesh to compute the gradient for a single event.

Parameters

distributed_mesh DistributedMesh — The distributed mesh to run the simulation on.
execution_config MPIExecutionConfiguration — The MPI execution configuration.
simulation Simulation | None — The simulation to run. If None, this rank will only participate in collective MPI operations without running an actual simulation.
adjoint_source_callback typing.Callable[[EventData], EventMisfit] — A callback function that takes the EventData from the forward simulation and returns an EventMisfit object.
wavefield_compression WavefieldCompression | None — Wavefield compression settings.
gradient_parameters set[str] | None — Model parameters to compute gradients for.
keep_intermediate_data_on_disk bool — If True, do not delete the temporary directories created for the simulation.
diagnostic_output_directory pathlib.Path | None — If set, the input files and mesh for the offending simulation will be moved to that directory.
verbosity int — Controls the amount of progress reporting. <=1: No output at this level. 2+: Log output per rank.
timer Timer | None — Execution timer.
log_to_logger bool — Whether to log timing information to the logger.

Returns tuple[float, Mesh] | None — A tuple of (misfit, gradient) where misfit is a float and gradient is a :class:Mesh, or None if this rank had no simulation to run.

`run_adjoint_simulations_and_sum_gradients()`

def run_adjoint_simulations_and_sum_gradients(
    distributed_mesh: DistributedMesh,
    execution_config: MPIExecutionConfiguration,
    simulations: collections.abc.Sequence[Simulation],
    adjoint_source_callback: typing.Callable[[EventData], EventMisfit],
    wavefield_compression: WavefieldCompression | None = None,
    gradient_parameters: set[str] | None = None,
    keep_intermediate_data_on_disk: bool = False,
    diagnostic_output_directory: pathlib.Path | None = None,
    verbosity: int = 1,
    timer: Timer | None = None,
) -> tuple[list[float], DistributedMesh]: ...

Run multiple forward + adjoint simulations on an MPI distributed mesh and return the total misfit and summed gradient.

Parameters

distributed_mesh DistributedMesh — The distributed mesh to run the simulations on.
execution_config MPIExecutionConfiguration — The MPI execution configuration.
simulations collections.abc.Sequence[Simulation] — The simulations to run.
adjoint_source_callback typing.Callable[[EventData], EventMisfit] — A callback function that takes the EventData from the forward simulation and returns an EventMisfit object containing the adjoint sources. The misfit value will be retrieved from the EventMisfit.misfit_value property.
wavefield_compression WavefieldCompression | None — Wavefield compression settings.
gradient_parameters set[str] | None — Model parameters to compute the gradients for. Must be a subset of the model parameters. If not given, gradients will be computed for all model fields.
keep_intermediate_data_on_disk bool — If True, do not delete the temporary directories created for the simulations.
diagnostic_output_directory pathlib.Path | None — If set, the input files and mesh for the offending simulation will be moved to that directory.
verbosity int — Controls the amount of progress reporting. 0: No progress output. 1: Summary at start and per-rank progress after each simulation. 2+: More detailed output per rank.
timer Timer | None — Execution timer.

Returns tuple[list[float], DistributedMesh] — A tuple of (total_misfit, summed_gradient) where total_misfit is the sum of per-event misfits and summed_gradient is an :class:UnstructuredMesh whose element data is the sum of all per-event gradients (or None if this rank ran no simulations).

`run_simulation()`

def run_simulation(
    distributed_mesh: DistributedMesh,
    execution_config: MPIExecutionConfiguration,
    simulation: Simulation | None,
    keep_intermediate_data_on_disk: bool = False,
    diagnostic_output_directory: pathlib.Path | None = None,
    verbosity: int = 1,
    timer: Timer | None = None,
    log_to_logger: bool = True,
) -> EventData | None: ...

Run a single forward simulation on an MPI distributed mesh.

Parameters

distributed_mesh DistributedMesh — The distributed mesh to run the simulation on.
execution_config MPIExecutionConfiguration — The MPI execution configuration.
simulation Simulation | None — The simulation to run. If None, this rank will only participate in collective MPI operations without running an actual simulation.
keep_intermediate_data_on_disk bool — If True, do not delete the temporary directories created for the simulation. This includes the data specified in the run directory.
diagnostic_output_directory pathlib.Path | None — If set, the input files and mesh for the offending simulation will be moved to that directory.
verbosity int — Controls the amount of progress reporting. <=1: No output at this level. 2+: Log output per rank.
timer Timer | None — Execution timer.
log_to_logger bool — Whether to log timing information to the logger.

Returns EventData | None — EventData from the simulation.

`run_simulations()`

def run_simulations(
    distributed_mesh: DistributedMesh,
    execution_config: MPIExecutionConfiguration,
    simulations: collections.abc.Sequence[Simulation],
    keep_intermediate_data_on_disk: bool = False,
    result_callback_function: typing.Callable[..., EventData] | None = None,
    diagnostic_output_directory: pathlib.Path | None = None,
    verbosity: int = 1,
    timer: Timer | None = None,
) -> list[EventData]: ...

Run multiple simulations on an MPI distributed mesh.

Parameters

distributed_mesh DistributedMesh — The distributed mesh to run the simulations on.
execution_config MPIExecutionConfiguration — The MPI execution configuration.
simulations collections.abc.Sequence[Simulation] — The simulations to run.
keep_intermediate_data_on_disk bool — If True, do not delete the temporary directories created for the simulations.
result_callback_function typing.Callable[..., EventData] | None — Callback function for performing additional processing on the results from each simulation. The callback function should have arguments result, simulation, and timer, with types EventData, Simulation, and Timer respectively. The callback function should return the processed data. Below is an example of such a callback function: python def result_callback_function( result: EventData, simulation: Simulation, timer: Timer | None = None, ) -> EventData: # Perform custom processing on the result here ... return result
diagnostic_output_directory pathlib.Path | None — If set, the input files and mesh for the offending simulation will be moved to that directory.
verbosity int — Controls the amount of progress reporting. 0: No progress output. 1: Summary at start and per-rank progress after each simulation. 2+: More detailed output per rank.
timer Timer | None — Execution timer.

Returns list[EventData]

`run_simulations_and_compute_misfits()`

def run_simulations_and_compute_misfits(
    distributed_mesh: DistributedMesh,
    execution_config: MPIExecutionConfiguration,
    simulations: collections.abc.Sequence[Simulation],
    misfit_callback: typing.Callable[[EventData], EventMisfit],
    keep_intermediate_data_on_disk: bool = False,
    diagnostic_output_directory: pathlib.Path | None = None,
    verbosity: int = 1,
    timer: Timer | None = None,
) -> list[float]: ...

Run multiple forward simulations on an MPI distributed mesh and return only the per-event misfits.

Unlike run_simulations(), the EventData objects are not retained after the misfit has been computed, keeping memory usage low.

Parameters

distributed_mesh DistributedMesh — The distributed mesh to run the simulations on.
execution_config MPIExecutionConfiguration — The MPI execution configuration.
simulations collections.abc.Sequence[Simulation] — The simulations to run.
misfit_callback typing.Callable[[EventData], EventMisfit] — A callback function that takes the EventData from a forward simulation and returns an EventMisfit object. Only the misfit_value property of the returned object is used; the EventData is discarded immediately afterwards. The same callable that is passed as adjoint_source_callback to :func:run_adjoint_simulations_and_sum_gradients can be used here.
keep_intermediate_data_on_disk bool — If True, do not delete the temporary directories created for the simulations.
diagnostic_output_directory pathlib.Path | None — If set, the input files and mesh for the offending simulation will be moved to that directory.
verbosity int — Controls the amount of progress reporting. 0: No progress output. 1: Summary at start and per-rank progress after each simulation. 2+: More detailed output per rank.
timer Timer | None — Execution timer.

Returns list[float] — A list of per-event misfit values (one per simulation in the same order).

`smooth_distributed_mesh()`

def smooth_distributed_mesh(
    distributed_mesh: DistributedMesh,
    execution_config: MPIExecutionConfiguration,
    smoothing_config: (
        ConstantSmoothing | ModelDependentSmoothing | SpaceDependentSmoothing
    ),
    halo_width_in_meters: float,
    in_place: bool = False,
    keep_intermediate_data_on_disk: bool = False,
    verbosity: int = 1,
    timer: Timer | None = None,
) -> DistributedMesh: ...

Smooth a distributed mesh using diffusion simulations.

Parameters

distributed_mesh DistributedMesh — The distributed mesh to smooth.
execution_config MPIExecutionConfiguration — The MPI execution configuration.
smoothing_config ConstantSmoothing | ModelDependentSmoothing | SpaceDependentSmoothing — Smoothing configuration per field.
halo_width_in_meters float — Width of the halo region.
in_place bool — Whether to modify the distributed mesh in place.
keep_intermediate_data_on_disk bool — If True, do not delete the temporary directories created for the simulations.
verbosity int — Controls the amount of progress reporting.
timer Timer | None — Execution timer.

Returns DistributedMesh — The smoothed distributed mesh.

Classes

`Simulation`

class Simulation(builtins.object):
    def __init__(
        self,
        simulation: Waveform,
        event_name: str | None,
        event_block: EventBlock,
        element_selection_function: collections.abc.Callable | None,
        source_time_functions: list[BaseSourceTimeFunction],
    ) -> None: ...

An object representing a single simulation to run.

Parameters

simulation Waveform — The simulation configuration. Sources, receivers, and meshes in it will be ignored.
event_name str | None — The name of the event that will be returned from the simulation. Will be autogenerated, if not given.
event_block EventBlock — The sources and receivers for the simulations.
element_selection_function collections.abc.Callable | None — A function that takes global element IDs and returns the selected ones for this simulation. If None, all elements are selected.
source_time_functions list[BaseSourceTimeFunction] — A list of source time functions. Either a single one, or as many sources as in the event block.