Mondaic

salvus.project.components.simulation_component

salvus.project.components.simulation_component salvus project components simulation_component

SalvusProject simulation component.

Functions

get_simulation_input_file()

def get_simulation_input_file(
    simulation_template: simple_config.simulation.Waveform,
    event: Event,
    event_configuration: EventConfiguration,
    project_path: pathlib.Path,
    event_dependent_mesh_masking: typing.Callable | None = None,
    wavefield_compression: WavefieldCompression | None = None,
    extra_output_configuration: dict[str, typing.Any] | None = None,
) -> simple_config.simulation.Waveform: ...

Create Salvus input file for a single event from a template.

Parameters
  • simulation_template simple_config.simulation.Waveform — Template for the simulation containing all non-event-dependent information, such as start/end time or a template for the boundary conditions.
  • event Event — Event object to extract the source(s) and receivers from.
  • event_configuration EventConfiguration — EventConfiguration object.
  • project_path pathlib.Path — Root path to the project.
  • event_dependent_mesh_masking typing.Callable | None — Optional callback function for event- dependent mesh masking. The function signature must take the global mesh and the event as arguments. Boundary conditions will be applied automatically.
  • wavefield_compression WavefieldCompression | None — Options that have an effect on the output of subsequent simulations but must already be known now. Currently allows the specification of some techniques to compress wavefields for the purpose of gradient computations. Must be given for checkpoints to be generated during the forward simulation.
  • extra_output_configuration dict[str, typing.Any] | None — Extra settings for the waveform simulations. Can only be used for settings that do not change the resulting waveforms. python extra_output_configuration={ "volume_data": { "sampling_interval_in_time_steps": 50, "fields": ["displacement"], }, "surface_data": { "sampling_interval_in_time_steps": 20, "fields": ["acceleration", "velocity"], "side_sets": ["x0", "x1"], }, "memory_per_rank_in_MB": 2000.0, }
Returns simple_config.simulation.Waveform

Classes

SimulationComponent

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

Project subclass dealing with all things related to simulations. This explicitly includes meshes as for the project they largely exist for the purpose of simulations.

Parameters
  • project Project — The project to attach the components to.
Methods
cancel()
def cancel(
    self,
    simulation_configuration: str | None = None,
    events: (
        str
        | typing.Sequence[str]
        | Event
        | typing.Sequence[Event]
        | EventCollection
        | None
    ) = None,
    misfit_configuration: str | MisfitConfiguration | None = None,
    wavefield_compression: WavefieldCompression | None = None,
    gradient_parameters: set[str] | None = None,
) -> None: ...

Cancel ongoing or pending simulations. Note that if simulations for several events have been simultaneously submitted using simulations.launch(), all jobs in this job array will be cancelled.

Parameters
  • simulation_configuration str | None — Name of the simulation configuration.
  • events str | typing.Sequence[str] | Event | typing.Sequence[Event] | EventCollection | None — One or more events.
  • misfit_configuration str | MisfitConfiguration | None — Optional misfit configuration to query adjoint simulations
  • wavefield_compression WavefieldCompression | None — Must be given for adjoint simulations.
  • 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.
Returns None
cancel_all()
def cancel_all(self) -> None: ...

Cancel all running simulations.

All currently launched simulations that have not finished yet will be cancelled.

Returns None
clear_simulation_store()
def clear_simulation_store(self) -> None: ...

Remove all items from the simulation store. Try to delete dangling jobs on remote sites.

Returns None
delete_jobs()
def delete_jobs(
    self,
    simulation_configuration: str | SimulationConfiguration,
    events: (
        str
        | typing.Sequence[str]
        | Event
        | typing.Sequence[Event]
        | EventCollection
    ),
    verbosity: int = 0,
) -> None: ...

Manually delete the jobs associated with a simulation configuration and events. By default, this happens automatically, when all remote output is downloaded with query() unless there still exists remote data.

Parameters
  • simulation_configuration str | SimulationConfiguration — The simulation configuration.
  • events str | typing.Sequence[str] | Event | typing.Sequence[Event] | EventCollection — One or more events.
  • verbosity int — Verbosity level.
Returns None
delete_results()
def delete_results(
    self,
    simulation_configuration: str,
    events: (
        str
        | typing.Sequence[str]
        | Event
        | typing.Sequence[Event]
        | EventCollection
    ),
    misfit_configuration: str | None = None,
    wavefield_compression: WavefieldCompression | None = None,
    gradient_parameters: set[str] | None = None,
    verbosity: int = 1,
) -> int: ...

Delete simulation results (waveforms, gradients, …). The function does not delete the configuration, but only simulated data. Those data can be recomputed if necessary.

Parameters
  • simulation_configuration str — The name of the simulation configuration.
  • events str | typing.Sequence[str] | Event | typing.Sequence[Event] | EventCollection — One or more events.
  • misfit_configuration str | None — The name of the misfit configuration for deleting gradients.
  • wavefield_compression WavefieldCompression | None — The wavefield compression settings for deleting gradients.
  • 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.
  • verbosity int — Verbosity level.
Returns int — Cumulative size of all deleted files in bytes.
get_adjoint_input_files()
def get_adjoint_input_files(
    self,
    simulation_configuration: str,
    misfit_configuration: str | MisfitConfiguration,
    wavefield_compression: WavefieldCompression,
    gradient_parameters: set[str] | None,
    events: (
        str
        | typing.Sequence[str]
        | Event
        | typing.Sequence[Event]
        | EventCollection
    ),
    skip_gradient_assembly: bool = False,
    skip_existing_simulations: bool = False,
    verbose: bool = True,
    site_name: str | None = None,
    ranks_per_job: salvus._core.types.int_ | None = None,
) -> tuple[
    list[simple_config.simulation.Waveform], list[Event], dict[str, str]
]: ...

Create Salvus input files for adjoint simulations for one or more events.

This is largely useful for custom workflows - if you want to simulate and remain fully inside SalvusProject, please use the .launch_adjoint() method.

Returns a tuple of the list of input files and the list of events for the input files. If skip_existing_simulations is True that list might be a subset of the input list.

Parameters
  • simulation_configuration str — Name of the simulation configuration for the forward run.
  • misfit_configuration str | MisfitConfiguration — Name of the misfit configuration.
  • wavefield_compression WavefieldCompression — The wavefield compression settings. Used to check compatibility of potentially already existing checkpoints.
  • 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.
  • events str | typing.Sequence[str] | Event | typing.Sequence[Event] | EventCollection — One or more events.
  • skip_gradient_assembly bool — Setting for skipping the pre-assembly after gradient computation. If True, the sensitivity kernels won’t be mapped to nodal fields and scaled with the mass matrix, which will have to be done manually.
  • skip_existing_simulations bool — If True, do not return input files for simulations that already exist as part of the project.
  • verbose bool — Verbosity.
  • site_name str | None — Optionally provide site name to check for remote files.
  • ranks_per_job salvus._core.types.int_ | None — Optionally provide the number of ranks to check for consistent checkpoints.
Returns tuple[list[simple_config.simulation.Waveform], list[Event], dict[str, str]]
get_input_files()
def get_input_files(
    self,
    simulation_configuration: str | _SimulationConfigurationBase,
    events: (
        str
        | typing.Sequence[str]
        | Event
        | typing.Sequence[Event]
        | EventCollection
    ),
    skip_existing_simulations: bool = False,
    derived_job_config: WavefieldCompression | None = None,
    verbose: bool = True,
    site_name: str | None = None,
    ranks_per_job: salvus._core.types.int_ | None = None,
    extra_output_configuration: dict[str, typing.Any] | None = None,
    delete_conflicting_previous_results: bool = False,
    allow_empty_output: bool = False,
) -> tuple[
    list[simple_config.simulation.Waveform], list[Event], dict[str, str]
]: ...

Create Salvus input files for one or more events.

This is largely useful for custom workflows - if you want to simulate and remain fully inside SalvusProject, please use the .launch() method.

Returns a tuple of the list of input files and the list of events for the input files. If skip_existing_simulations is True that list might be a subset of the input list.

Parameters
  • simulation_configuration str | _SimulationConfigurationBase — Name of the simulation configuration.
  • events str | typing.Sequence[str] | Event | typing.Sequence[Event] | EventCollection — One or more events. If not given, it will return a generic input file without any sources or receivers.
  • skip_existing_simulations bool — If True, do not return input files for simulations that already exist as part of the project.
  • derived_job_config WavefieldCompression | None — Options that have an effect on the output of subsequent simulations but must already be known now. Currently allows the specification of some techniques to compress wavefields for the purpose of gradient computations. Must be given for checkpoints to be generated during the forward simulation.
  • verbose bool — Verbosity.
  • site_name str | None — Optionally provide site name to check for remote files.
  • ranks_per_job salvus._core.types.int_ | None — Optionally provide the number of ranks to check for consistent checkpoints.
  • extra_output_configuration dict[str, typing.Any] | None — Extra settings for the waveform simulations. Can only be used for settings that do not change the resulting waveforms. python extra_output_configuration={ "volume_data": { "sampling_interval_in_time_steps": 50, "fields": ["displacement"], }, "surface_data": { "sampling_interval_in_time_steps": 20, "fields": ["acceleration", "velocity"], "side_sets": ["x0", "x1"], }, "memory_per_rank_in_MB": 2000.0, }
  • delete_conflicting_previous_results bool — If skip_existing_simulations is True, simulations with existing results but different extra_output_configurations would cause an error. If this options is set to True, it will delete the potentially conflicting existing results.
  • allow_empty_output bool — By default, this method will raise a ValueError if one attempts to get an input file for an event that would have no output at all. This argument overwrites that which is useful for example for visualization purposes.
Returns tuple[list[simple_config.simulation.Waveform], list[Event], dict[str, str]]
get_mesh()
def get_mesh(
    self,
    simulation_configuration: str,
    event: Event | str | None = None,
    verbosity: int = 1,
    execution_policy: bindings.ExecutionPolicy = salvus._core.lib.salvus_core_python_bindings.ExecutionPolicy,
    skip_validation: bool = True,
    comm: int | None = None,
) -> UnstructuredMesh | DistributedMesh: ...

Load the chosen mesh from disk or create if necessary.

Parameters
  • simulation_configuration str — Simulation for which to get the mesh.
  • event Event | str | None — Optional event to retrieve an event-dependent mesh. If not given, the master mesh is returned.
  • verbosity int — Verbosity level.
  • execution_policy bindings.ExecutionPolicy — Execution policy governing the maximum allowable parallelism of child routines.
  • skip_validation bool — Whether to skip mesh quality control after mesh creation. Will only trigger if the mesh has not been created yet.
  • comm int | None — MPI communicator for distributed mesh loading.
Returns UnstructuredMesh | DistributedMesh
get_mesh_filenames()
def get_mesh_filenames(
    self,
    simulation_configuration: str,
    event: Event | str | None = None,
    verbosity: int = 1,
    execution_policy: bindings.ExecutionPolicy = salvus._core.lib.salvus_core_python_bindings.ExecutionPolicy,
    skip_validation: bool = True,
) -> dict[str, pathlib.Path]: ...

Get mesh and XDMF filenames for a chosen simulation.

This will create the mesh if it does not exist yet, for now in legacy mode (i.e. as an UnstructuredMesh object).

The XDMF file will not exist for the minimal and minimal_fast mesh file modes.

Parameters
  • simulation_configuration str — Simulation for which to create the mesh.
  • event Event | str | None — Not active yet but serves as scaffolding for the future possibility to build event dependent meshes.
  • verbosity int — Verbosity level.
  • execution_policy bindings.ExecutionPolicy — Execution policy governing the maximum allowable parallelism of child routines.
  • skip_validation bool — Whether to skip mesh quality control after mesh creation. Will only trigger if the mesh has not been created yet.
Returns dict[str, pathlib.Path]
get_remote_output_directory()
def get_remote_output_directory(
    self, simulation_configuration: str, event: str | Event
) -> dict[str, typing.Any]: ...

Get the remote output directory for a given simulation. The function does not check if the remote data still exist.

Parameters
  • simulation_configuration str — The name of the simulation configuration.
  • event str | Event — The used event.
Returns dict[str, typing.Any]
get_simulation_output_directories()
def get_simulation_output_directories(
    self,
    simulation_configuration: str | _SimulationConfigurationBase,
    events: (
        str
        | typing.Sequence[str]
        | Event
        | typing.Sequence[Event]
        | EventCollection
    ),
) -> dict[str, pathlib.Path]: ...

Get the output directories for a given simulation and a list of events.

Parameters
  • simulation_configuration str | _SimulationConfigurationBase — The name of the simulation configuration.
  • events str | typing.Sequence[str] | Event | typing.Sequence[Event] | EventCollection — One or several events.
Returns dict[str, pathlib.Path]
get_simulation_output_directory()
def get_simulation_output_directory(
    self,
    simulation_configuration: str | _SimulationConfigurationBase,
    event: str | Event,
) -> pathlib.Path: ...

Get the output directory for a given simulation.

Parameters
  • simulation_configuration str | _SimulationConfigurationBase — The name of the simulation configuration.
  • event str | Event — The used event.
Returns pathlib.Path
get_simulation_template()
def get_simulation_template(
    self,
    simulation_configuration: str | _SimulationConfigurationBase,
    events: (
        str
        | typing.Sequence[str]
        | Event
        | typing.Sequence[Event]
        | EventCollection
        | None
    ) = None,
    extra_output_configuration: dict[str, typing.Any] | None = None,
    apply_waveform_simulation_configuration: bool = True,
    execution_policy: bindings.ExecutionPolicy = salvus._core.lib.salvus_core_python_bindings.ExecutionPolicy,
) -> simple_config.simulation.Waveform: ...

Get the Salvus simulation template for a given setup.

Parameters
  • simulation_configuration str | _SimulationConfigurationBase — Simulation configuration, or name thereof.
  • events str | typing.Sequence[str] | Event | typing.Sequence[Event] | EventCollection | None — Optionally pass a list of event to check for consistency regarding attenuation.
  • extra_output_configuration dict[str, typing.Any] | None — Extra settings for the waveform simulations. Can only be used for settings that do not change the resulting waveforms. python extra_output_configuration={ "volume_data": { "sampling_interval_in_time_steps": 50, "fields": ["displacement"], }, "surface_data": { "sampling_interval_in_time_steps": 20, "fields": ["acceleration", "velocity"], "side_sets": ["x0", "x1"], }, "memory_per_rank_in_MB": 2000.0, }
  • apply_waveform_simulation_configuration bool — Apply the waveform simulation configuration before returning the template. A ValueError will be raised in case the waveform simulation configuration is event-dependent.
  • execution_policy bindings.ExecutionPolicy — Execution policy governing the maximum allowable parallelism of child routines.
Returns simple_config.simulation.Waveform
launch()
def launch(
    self,
    simulation_configuration: str,
    events: (
        str
        | typing.Sequence[str]
        | Event
        | typing.Sequence[Event]
        | EventCollection
    ),
    site_name: str,
    ranks_per_job: salvus._core.types.int_,
    wall_time_in_seconds_per_job: salvus._core.types.float_ | None = None,
    derived_job_config: WavefieldCompression | None = None,
    store_adjoint_checkpoints: bool | None = None,
    verbosity: salvus._core.types.int_ = 2,
    max_block_in_seconds: salvus._core.types.float_ = 0,
    extra_output_configuration: dict[str, typing.Any] | None = None,
    delete_conflicting_previous_results: bool = False,
) -> int: ...

Generate synthetics for one or more events.

Parameters
  • simulation_configuration str — Name of the simulation configuration.
  • events str | typing.Sequence[str] | Event | typing.Sequence[Event] | EventCollection — One or more events.
  • site_name str — Site to use.
  • ranks_per_job salvus._core.types.int_ — Ranks per job.
  • wall_time_in_seconds_per_job salvus._core.types.float_ | None — Wall time per job.
  • derived_job_config WavefieldCompression | None — Options that have an effect on the output of subsequent simulations but must already be known now. Currently allows the specification of some techniques to compress wavefields for the purpose of gradient computations.
  • store_adjoint_checkpoints bool | None — Deprecated. Please use the derived_job_config parameter.
  • verbosity salvus._core.types.int_ — Verbosity.
  • max_block_in_seconds salvus._core.types.float_ — If set, the function will wait for the specified time for the simulations to finish.
  • extra_output_configuration dict[str, typing.Any] | None — Extra settings for the waveform simulations. Can only be used for settings that do not change the resulting waveforms. For volume_data and surface_data, the output cadence can be given either as an explicit sampling_interval_in_time_steps or as an approximate number_of_snapshots. In the latter case the sampling interval is computed automatically from the simulation’s time step and duration so that roughly that many snapshots are written. python extra_output_configuration={ "volume_data": { "sampling_interval_in_time_steps": 50, "fields": ["displacement"], }, "surface_data": { "number_of_snapshots": 200, "fields": ["acceleration", "velocity"], "side_sets": ["x0", "x1"], }, "memory_per_rank_in_MB": 2000.0, }
  • delete_conflicting_previous_results bool — If data for an event but a different extra_output_configuration already exists, an error will be raised. If this option is set to True, it will delete pre-existing conflicting output. Use with caution, as this can delete expensive-to-compute outputs.
Returns int
launch_adjoint()
def launch_adjoint(
    self,
    simulation_configuration: str,
    misfit_configuration: str,
    wavefield_compression: WavefieldCompression,
    gradient_parameters: set[str] | None,
    events: (
        str
        | typing.Sequence[str]
        | Event
        | typing.Sequence[Event]
        | EventCollection
    ),
    site_name: str,
    ranks_per_job: int,
    skip_gradient_assembly: bool = False,
    wall_time_in_seconds_per_job: salvus._core.types.float_ | None = None,
    verbosity: bool = True,
    max_block_in_seconds: int = 0,
) -> int: ...

Launch adjoint simulations for one or more events.

Parameters
  • simulation_configuration str — Name of the simulation configuration for the forward run.
  • misfit_configuration str — Name of the misfit configuration.
  • wavefield_compression WavefieldCompression — The gradient 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.
  • events str | typing.Sequence[str] | Event | typing.Sequence[Event] | EventCollection — One or more events.
  • site_name str — Site to use.
  • ranks_per_job int — Ranks per job.
  • skip_gradient_assembly bool — Setting for skipping the pre-assembly after gradient computation. If True, the sensitivity kernels won’t be mapped to nodal fields and scaled with the mass matrix, which will have to be done manually.
  • wall_time_in_seconds_per_job salvus._core.types.float_ | None — Wall time per job.
  • verbosity bool — Verbosity.
  • max_block_in_seconds int — If set, the function will wait for the specified time for the simulations to finish.
Returns int
list()
def list(self) -> list[str]: ...

Get a list of all simulation configurations.

Returns list[str]
list_events()
def list_events(
    self, simulation_configuration: str, verbosity: int = 1
) -> dict[str, typing.Any]: ...

Return all event names known for this simulation configuration.

Parameters
  • simulation_configuration str — Name of the simulation configuration.
  • verbosity int — Verbosity level.
Returns dict[str, typing.Any]
query()
def query(
    self,
    simulation_configuration: str | None = None,
    events: (
        str
        | typing.Sequence[str]
        | Event
        | typing.Sequence[Event]
        | EventCollection
        | None
    ) = None,
    misfit_configuration: str | MisfitConfiguration | None = None,
    wavefield_compression: WavefieldCompression | None = None,
    gradient_parameters: set[str] | None = None,
    get_all_outputs: bool | None = None,
    block: bool = False,
    ping_interval_in_seconds: salvus._core.types.float_ | None = None,
    raise_on_failed_jobs: bool = True,
    verbosity: int = 1,
) -> bool: ...

Query the status of currently ongoing simulations.

Parameters
  • simulation_configuration str | None — Name of the simulation configuration.
  • events str | typing.Sequence[str] | Event | typing.Sequence[Event] | EventCollection | None — One or more events.
  • misfit_configuration str | MisfitConfiguration | None — Optional misfit configuration to query adjoint simulations
  • wavefield_compression WavefieldCompression | None — Must be given for querying adjoint simulations.
  • 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.
  • get_all_outputs bool | None — Optional flag to skip the download of large output files. If not set, checkpoints will remain on the remote site, while all other outputs are downloaded. If False, the data can manually be downloaded using EventData.download_extra_outputs().
  • block bool — If True, wait for all simulations to finish.
  • ping_interval_in_seconds salvus._core.types.float_ | None — Update interval of the status of the jobs if block=True.
  • raise_on_failed_jobs bool — If True, querying failed or cancelled jobs will raise an error. When set to false, errors for the failed jobs will be retrieved and printed in the in the widget, but no error will be thrown.
  • verbosity int — Verbosity level. Negative values hide the widget.
Returns bool
run()
def run(
    self,
    simulation_configuration: str,
    events: (
        str
        | typing.Sequence[str]
        | Event
        | typing.Sequence[Event]
        | EventCollection
    ),
    site_config: (
        SiteConfig
        | TaskChainSiteConfig
        | dict[str, TaskChainSiteConfig]
        | MPIExecutionConfiguration
    ),
    timer: Timer | None = None,
) -> None: ...

Run simulations for a selection of events, wait for them to finish, and add the results to the project.

This function only returns after all simulations have been completed. For an asynchronous options, use launch() instead.

Parameters
  • simulation_configuration str — Name of the simulation configuration.
  • events str | typing.Sequence[str] | Event | typing.Sequence[Event] | EventCollection — One or more events.
  • site_config SiteConfig | TaskChainSiteConfig | dict[str, TaskChainSiteConfig] | MPIExecutionConfiguration — The site configuration and job submission settings.
  • timer Timer | None — Execution timer.
Returns None

Used in tutorials