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

salvus.project.components.simulation_component

SalvusProject simulation component.

Functions

get_simulation_input_file()

def get_simulation_input_file(
    simulation_template: salvus.flow.simple_config.simulation.waveform.Waveform,
    event: salvus.flow.collections.event.Event,
    event_configuration: salvus.project.configuration.event_configuration.EventConfiguration,
    event_dependent_mesh_masking: Optional[Callable] = None,
    wavefield_compression: Optional[
        salvus.flow.collections.wavefield_compression.WavefieldCompression
    ] = None,
    extra_output_configuration: Optional[Dict[str, Any]] = None,
) -> salvus.flow.simple_config.simulation.waveform.Waveform:
    ...

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

Parameters
  • simulation_template salvus.flow.simple_config.simulation.waveform.Waveform — Template for the simulation containing all non-event-dependent information, such as start/end time or a template for the boundary conditions.
  • event salvus.flow.collections.event.Event — Event object to extract the source(s) and receivers from.
  • event_configuration salvus.project.configuration.event_configuration.EventConfiguration — EventConfiguration object.
  • event_dependent_mesh_masking Optional[Callable] — 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 Optional[salvus.flow.collections.wavefield_compression.WavefieldCompression] — 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 Optional[Dict[str, Any]] — 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 salvus.flow.simple_config.simulation.waveform.Waveform

Classes

SimulationComponent

class SimulationComponent(builtins.object):
    def __init__(self, project: salvus.project.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 salvus.project.project.Project — The project to attach the components to.
Methods
cancel()
def cancel(
    self,
    simulation_configuration: Optional[str] = None,
    events: Optional[
        str,
        Sequence[str],
        salvus.flow.collections.event.Event,
        Sequence[salvus.flow.collections.event.Event],
        salvus.flow.collections.event_collection.EventCollection,
    ] = None,
    misfit_configuration: Optional[
        str,
        salvus.project.configuration.misfit_configuration.MisfitConfiguration,
    ] = None,
    wavefield_compression: Optional[
        salvus.flow.collections.wavefield_compression.WavefieldCompression
    ] = 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 Optional[str] — Name of the simulation configuration.
  • events Optional[str, Sequence[str], salvus.flow.collections.event.Event, Sequence[salvus.flow.collections.event.Event], salvus.flow.collections.event_collection.EventCollection] — One or more events.
  • misfit_configuration Optional[str, salvus.project.configuration.misfit_configuration.MisfitConfiguration] — Optional misfit configuration to query adjoint simulations
  • wavefield_compression Optional[salvus.flow.collections.wavefield_compression.WavefieldCompression] — Must be given for adjoint simulations.
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: Union[
        str,
        salvus.project.configuration.simulation_configuration.SimulationConfiguration,
    ],
    events: Union[
        str,
        Sequence[str],
        salvus.flow.collections.event.Event,
        Sequence[salvus.flow.collections.event.Event],
        salvus.flow.collections.event_collection.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 Union[str, salvus.project.configuration.simulation_configuration.SimulationConfiguration] — The simulation configuration.
  • events Union[str, Sequence[str], salvus.flow.collections.event.Event, Sequence[salvus.flow.collections.event.Event], salvus.flow.collections.event_collection.EventCollection] — One or more events.
  • verbosity int — Verbosity level.
Returns None
delete_results()
def delete_results(
    self,
    simulation_configuration: str,
    events: Union[
        str,
        Sequence[str],
        salvus.flow.collections.event.Event,
        Sequence[salvus.flow.collections.event.Event],
        salvus.flow.collections.event_collection.EventCollection,
    ],
    misfit_configuration: Optional[str] = None,
    wavefield_compression: Optional[
        salvus.flow.collections.wavefield_compression.WavefieldCompression
    ] = 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 Union[str, Sequence[str], salvus.flow.collections.event.Event, Sequence[salvus.flow.collections.event.Event], salvus.flow.collections.event_collection.EventCollection] — One or more events.
  • misfit_configuration Optional[str] — The name of the misfit configuration for deleting gradients.
  • wavefield_compression Optional[salvus.flow.collections.wavefield_compression.WavefieldCompression] — The wavefield compression settings for deleting gradients.
  • 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: Union[
        str,
        salvus.project.configuration.misfit_configuration.MisfitConfiguration,
    ],
    wavefield_compression: salvus.flow.collections.wavefield_compression.WavefieldCompression,
    events: Union[
        str,
        Sequence[str],
        salvus.flow.collections.event.Event,
        Sequence[salvus.flow.collections.event.Event],
        salvus.flow.collections.event_collection.EventCollection,
    ],
    skip_existing_simulations: bool = False,
    verbose: bool = True,
    site_name: Optional[str] = None,
    ranks_per_job: Optional[int] = None,
) -> Tuple[
    List[salvus.flow.simple_config.simulation.waveform.Waveform],
    List[salvus.flow.collections.event.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 Union[str, salvus.project.configuration.misfit_configuration.MisfitConfiguration] — Name of the misfit configuration.
  • wavefield_compression salvus.flow.collections.wavefield_compression.WavefieldCompression — The wavefield compression settings. Used to check compatibility of potentially already existing checkpoints.
  • events Union[str, Sequence[str], salvus.flow.collections.event.Event, Sequence[salvus.flow.collections.event.Event], salvus.flow.collections.event_collection.EventCollection] — One or more events.
  • 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 Optional[str] — Optionally provide site name to check for remote files.
  • ranks_per_job Optional[int] — Optionally provide the number of ranks to check for consistent checkpoints.
Returns Tuple[List[salvus.flow.simple_config.simulation.waveform.Waveform], List[salvus.flow.collections.event.Event], Dict[str, str]]
get_input_files()
def get_input_files(
    self,
    simulation_configuration: Union[
        str,
        salvus.project.configuration.simulation_configuration.SimulationConfiguration,
        salvus.project.configuration.simulation_configuration._UnstructuredMeshFileSimulationConfiguration,
    ],
    events: Union[
        str,
        Sequence[str],
        salvus.flow.collections.event.Event,
        Sequence[salvus.flow.collections.event.Event],
        salvus.flow.collections.event_collection.EventCollection,
    ],
    skip_existing_simulations: bool = False,
    derived_job_config: Optional[
        salvus.flow.collections.wavefield_compression.WavefieldCompression
    ] = None,
    verbose: bool = True,
    site_name: Optional[str] = None,
    ranks_per_job: Optional[int] = None,
    extra_output_configuration: Optional[Dict[str, Any]] = None,
    delete_conflicting_previous_results: bool = False,
    allow_empty_output: bool = False,
) -> Tuple[
    List[salvus.flow.simple_config.simulation.waveform.Waveform],
    List[salvus.flow.collections.event.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 Union[str, salvus.project.configuration.simulation_configuration.SimulationConfiguration, salvus.project.configuration.simulation_configuration._UnstructuredMeshFileSimulationConfiguration] — Name of the simulation configuration.
  • events Union[str, Sequence[str], salvus.flow.collections.event.Event, Sequence[salvus.flow.collections.event.Event], salvus.flow.collections.event_collection.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 Optional[salvus.flow.collections.wavefield_compression.WavefieldCompression] — 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 Optional[str] — Optionally provide site name to check for remote files.
  • ranks_per_job Optional[int] — Optionally provide the number of ranks to check for consistent checkpoints.
  • extra_output_configuration Optional[Dict[str, Any]] — 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[salvus.flow.simple_config.simulation.waveform.Waveform], List[salvus.flow.collections.event.Event], Dict[str, str]]
get_mesh()
def get_mesh(
    self,
    simulation_configuration: str,
    event: Optional[salvus.flow.collections.event.Event, str] = None,
    verbosity: int = 1,
) -> salvus.mesh.unstructured_mesh.UnstructuredMesh:
    ...

Load the chosen mesh from disc or create if necessary.

Parameters
  • simulation_configuration str — Simulation for which to get the mesh.
  • event Optional[salvus.flow.collections.event.Event, str] — Optional event to retrieve an event-dependent mesh. If not given, the master mesh is returned.
  • verbosity int — Verbosity level.
Returns salvus.mesh.unstructured_mesh.UnstructuredMesh
get_mesh_filenames()
def get_mesh_filenames(
    self,
    simulation_configuration: str,
    event: Optional[salvus.flow.collections.event.Event, str] = None,
    verbosity: int = 1,
) -> Dict[str, pathlib.Path]:
    ...

Get mesh and XDMF filenames for a chosen simulation. Will create the mesh if it does not exist yet.

Parameters
  • simulation_configuration str — Simulation for which to create the mesh.
  • event Optional[salvus.flow.collections.event.Event, str] — Not active yet but serves as scaffolding for the future possibility to build event dependent meshes.
  • verbosity int — Verbosity level.
Returns Dict[str, pathlib.Path]
get_remote_output_directory()
def get_remote_output_directory(
    self,
    simulation_configuration: str,
    event: Union[str, salvus.flow.collections.event.Event],
) -> Dict[str, 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 Union[str, salvus.flow.collections.event.Event] — The used event.
Returns Dict[str, Any]
get_simulation_output_directory()
def get_simulation_output_directory(
    self,
    simulation_configuration: Union[
        str,
        salvus.project.configuration.simulation_configuration.SimulationConfiguration,
    ],
    event: Union[str, salvus.flow.collections.event.Event],
) -> pathlib.Path:
    ...

Get the output directory for a given simulation.

Parameters
  • simulation_configuration Union[str, salvus.project.configuration.simulation_configuration.SimulationConfiguration] — The name of the simulation configuration.
  • event Union[str, salvus.flow.collections.event.Event] — The used event.
Returns pathlib.Path
get_simulation_template()
def get_simulation_template(
    self,
    simulation_configuration: Union[
        str,
        salvus.project.configuration.simulation_configuration.SimulationConfiguration,
        salvus.project.configuration.simulation_configuration._UnstructuredMeshFileSimulationConfiguration,
    ],
    events: Optional[
        str,
        Sequence[str],
        salvus.flow.collections.event.Event,
        Sequence[salvus.flow.collections.event.Event],
        salvus.flow.collections.event_collection.EventCollection,
    ] = None,
    extra_output_configuration: Optional[Dict[str, Any]] = None,
    apply_waveform_simulation_configuration: bool = True,
) -> salvus.flow.simple_config.simulation.waveform.Waveform:
    ...

Get the Salvus simulation template for a given setup.

Parameters
  • simulation_configuration Union[str, salvus.project.configuration.simulation_configuration.SimulationConfiguration, salvus.project.configuration.simulation_configuration._UnstructuredMeshFileSimulationConfiguration] — Simulation configuration, or name thereof.
  • events Optional[str, Sequence[str], salvus.flow.collections.event.Event, Sequence[salvus.flow.collections.event.Event], salvus.flow.collections.event_collection.EventCollection] — Optionally pass a list of event to check for consistency regarding attenuation.
  • extra_output_configuration Optional[Dict[str, Any]] — 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.
Returns salvus.flow.simple_config.simulation.waveform.Waveform
launch()
def launch(
    self,
    simulation_configuration: str,
    events: Union[
        str,
        Sequence[str],
        salvus.flow.collections.event.Event,
        Sequence[salvus.flow.collections.event.Event],
        salvus.flow.collections.event_collection.EventCollection,
    ],
    site_name: str,
    ranks_per_job: int,
    wall_time_in_seconds_per_job: Optional[int] = None,
    derived_job_config: Optional[
        salvus.flow.collections.wavefield_compression.WavefieldCompression
    ] = None,
    store_adjoint_checkpoints: Optional[bool] = None,
    verbosity: int = 2,
    max_block_in_seconds: int = 0,
    extra_output_configuration: Optional[Dict[str, Any]] = 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 Union[str, Sequence[str], salvus.flow.collections.event.Event, Sequence[salvus.flow.collections.event.Event], salvus.flow.collections.event_collection.EventCollection] — One or more events.
  • site_name str — Site to use.
  • ranks_per_job int — Ranks per job.
  • wall_time_in_seconds_per_job Optional[int] — Wall time per job.
  • derived_job_config Optional[salvus.flow.collections.wavefield_compression.WavefieldCompression] — 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 Optional[bool] — Deprecated. Please use the derived_job_config parameter.
  • verbosity int — Verbosity.
  • max_block_in_seconds int — If set, the function will wait for the specified time for the simulations to finish.
  • extra_output_configuration Optional[Dict[str, Any]] — 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 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: salvus.flow.collections.wavefield_compression.WavefieldCompression,
    events: Union[
        str,
        Sequence[str],
        salvus.flow.collections.event.Event,
        Sequence[salvus.flow.collections.event.Event],
        salvus.flow.collections.event_collection.EventCollection,
    ],
    site_name: str,
    ranks_per_job: int,
    wall_time_in_seconds_per_job: Optional[int] = 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 salvus.flow.collections.wavefield_compression.WavefieldCompression — The gradient compression settings.
  • events Union[str, Sequence[str], salvus.flow.collections.event.Event, Sequence[salvus.flow.collections.event.Event], salvus.flow.collections.event_collection.EventCollection] — One or more events.
  • site_name str — Site to use.
  • ranks_per_job int — Ranks per job.
  • wall_time_in_seconds_per_job Optional[int] — 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, 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, Any]
query()
def query(
    self,
    simulation_configuration: Optional[str] = None,
    events: Optional[
        str,
        Sequence[str],
        salvus.flow.collections.event.Event,
        Sequence[salvus.flow.collections.event.Event],
        salvus.flow.collections.event_collection.EventCollection,
    ] = None,
    misfit_configuration: Optional[
        str,
        salvus.project.configuration.misfit_configuration.MisfitConfiguration,
    ] = None,
    wavefield_compression: Optional[
        salvus.flow.collections.wavefield_compression.WavefieldCompression
    ] = None,
    get_all_outputs: Optional[bool] = None,
    block: bool = False,
    ping_interval_in_seconds: Optional[
        int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64
    ] = None,
    raise_on_failed_jobs: bool = True,
    verbosity: int = 1,
) -> bool:
    ...

Query the status of currently ongoing simulations.

Parameters
  • simulation_configuration Optional[str] — Name of the simulation configuration.
  • events Optional[str, Sequence[str], salvus.flow.collections.event.Event, Sequence[salvus.flow.collections.event.Event], salvus.flow.collections.event_collection.EventCollection] — One or more events.
  • misfit_configuration Optional[str, salvus.project.configuration.misfit_configuration.MisfitConfiguration] — Optional misfit configuration to query adjoint simulations
  • wavefield_compression Optional[salvus.flow.collections.wavefield_compression.WavefieldCompression] — Must be given for querying adjoint simulations.
  • get_all_outputs Optional[bool] — 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 Optional[int, numpy.int32, numpy.int64, float, numpy.float32, numpy.float64] — 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.
Returns bool