Version:

This documentation is not for the latest stable Salvus version.

This tutorial is presented as Python code running inside a Jupyter Notebook, the recommended way to use Salvus. To run it yourself you can copy/type each individual cell or directly download the full notebook, including all required files.

Continental-scale Simulations

In this tutorial we'll set up, from scratch, a 3-D spherical domain for the region surrounding Australia. This domain will include a 3-D crustal and mantle model, taken from AusREM, as well as 3-D surface and Moho topography. After our model and simulations are set up, we'll fire them off to a remote site (if available) in order to run simulations accurate to a minimum period of 40 seconds. We'll then gather the data from the remote site and apply some basic processing functions to some observed, as well as our synthetic, data. All right -- let's get started!

Copy
# This notebook will use this variable to determine which
# remote site to run on.
import os
import pathlib
import time

from salvus import namespace as sn
SALVUS_FLOW_SITE_NAME = os.environ.get("SITE_NAME", "local")
PROJECT_DIR = "project"

We start by initializeing a small domain centered on Australia, and download real data via ObsPy for a few stations from the IU global network. These are high quality stations which will be perfect for a comparison to our synthetic data.

If the project already exist on disk, the cell below allows us to simply load the project.

# Define a spherical chunk domain.
lat_c, lon_c = -27.5, 135
lat_e, lon_e = 25.5, 42.0
d = sn.domain.dim3.SphericalChunkDomain(
    lat_center=lat_c,
    lat_extent=lat_e,
    lon_center=lon_c,
    lon_extent=lon_e,
    radius_in_meter=6371e3,
)

# Uncomment the following line to start from scratch
# !rm -rf proj
if pathlib.Path(PROJECT_DIR).exists():
    print("Opening existing project.")
    p = sn.Project(path=PROJECT_DIR)
else:
    print("Creating new project.")
    p = sn.Project.from_domain(path=PROJECT_DIR, domain=d)
Creating new project.
# Add an event
e = sn.Event(
    sources=sn.simple_config.source.seismology.parse(
        "./event.txt", dimensions=3
    ),
    receivers=[],
)

if e.event_name not in p.events.list():
    p += e

    p.actions.seismology.download_data_for_event(
        data_name="raw_recording",
        event=p.events.list()[0],
        add_receivers_to_project_event=True,
        receiver_fields=["velocity"],
        seconds_before_event=300.0,
        seconds_after_event=1800.0,
        network="IU",
        download_providers=["IRIS"],
    )
[2020-09-17 13:12:22,509] - obspy.clients.fdsn.mass_downloader - INFO: Initializing FDSN client(s) for IRIS.
[2020-09-17 13:12:23,012] - obspy.clients.fdsn.mass_downloader - INFO: Successfully initialized 1 client(s): IRIS.
[2020-09-17 13:12:23,026] - obspy.clients.fdsn.mass_downloader - INFO: Total acquired or preexisting stations: 0
[2020-09-17 13:12:23,028] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Requesting reliable availability.
[2020-09-17 13:12:25,853] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Successfully requested availability (2.83 seconds)
[2020-09-17 13:12:25,888] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Found 7 stations (19 channels).
[2020-09-17 13:12:25,890] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Will attempt to download data from 7 stations.
[2020-09-17 13:12:25,892] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Status for 19 time intervals/channels before downloading: NEEDS_DOWNLOADING
[2020-09-17 13:12:28,454] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Successfully downloaded 19 channels (of 19)
[2020-09-17 13:12:28,456] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Launching basic QC checks...
[2020-09-17 13:12:28,487] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Downloaded 1.1 MB [452.52 KB/sec] of data, 0.0 MB of which were discarded afterwards.
[2020-09-17 13:12:28,488] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Status for 19 time intervals/channels after downloading: DOWNLOADED
[2020-09-17 13:12:28,982] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Successfully downloaded '/tmp/salvus_flow_internal_tmp_root/tempdir__2009171312026503edb3b39d__299/stations/IU.HNR.xml'.
[2020-09-17 13:12:28,983] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Successfully downloaded '/tmp/salvus_flow_internal_tmp_root/tempdir__2009171312026503edb3b39d__299/stations/IU.MBWA.xml'.
[2020-09-17 13:12:28,985] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Successfully downloaded '/tmp/salvus_flow_internal_tmp_root/tempdir__2009171312026503edb3b39d__299/stations/IU.CTAO.xml'.
[2020-09-17 13:12:29,289] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Successfully downloaded '/tmp/salvus_flow_internal_tmp_root/tempdir__2009171312026503edb3b39d__299/stations/IU.RAO.xml'.
[2020-09-17 13:12:29,293] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Successfully downloaded '/tmp/salvus_flow_internal_tmp_root/tempdir__2009171312026503edb3b39d__299/stations/IU.PMG.xml'.
[2020-09-17 13:12:29,295] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Successfully downloaded '/tmp/salvus_flow_internal_tmp_root/tempdir__2009171312026503edb3b39d__299/stations/IU.NWAO.xml'.
[2020-09-17 13:12:29,598] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Successfully downloaded '/tmp/salvus_flow_internal_tmp_root/tempdir__2009171312026503edb3b39d__299/stations/IU.SNZO.xml'.
[2020-09-17 13:12:29,614] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Downloaded 7 station files [0.3 MB] in 1.1 seconds [286.18 KB/sec].
[2020-09-17 13:12:29,614] - obspy.clients.fdsn.mass_downloader - INFO: ============================== Final report
[2020-09-17 13:12:29,615] - obspy.clients.fdsn.mass_downloader - INFO: 0 MiniSEED files [0.0 MB] already existed.
[2020-09-17 13:12:29,615] - obspy.clients.fdsn.mass_downloader - INFO: 0 StationXML files [0.0 MB] already existed.
[2020-09-17 13:12:29,616] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Acquired 19 MiniSEED files [1.1 MB].
[2020-09-17 13:12:29,616] - obspy.clients.fdsn.mass_downloader - INFO: Client 'IRIS' - Acquired 7 StationXML files [0.3 MB].
[2020-09-17 13:12:29,617] - obspy.clients.fdsn.mass_downloader - INFO: Downloaded 1.4 MB in total.

In previous tutorials we outlined the difference between background and volumetric models, and until now have only considered background models. Here we'll foray into the use of volumetric models as well, and we'll specifically choose a different model for both the crust and the mantle. In the tutorial folder you should see two NetCDF (.nc) files entitled ausrem_crust.nc and ausrem_mantle.nc. The name of these models are relatively self descriptive: they are modified version of the AusREM (Australian Seismological Reference Model) crust and mantle models respectively. The format that they are stored in is governed by the CF conventions, which is a commonly used format for storing geoscientific data.

Since we're focussed here on Australia we'll shift back to AusREM for now. In a seismological context, we can restrict the interpolation of models to specific regions, such as the crust or mantle. Also, in many cases we want to apply a taper to the volumetric models so that they will smoothly blend into the background model. To accomplish this, the seismological model API allows us to optionally specify a taper_in_degrees parameter. Ok, now let's add the crustal model to the project...

p += sn.model.volume.seismology.CrustalModel(
    name="ausrem_crust", data="./data/ausrem_crust.nc", taper_in_degrees=5.0
)

...and now the mantle model...

p += sn.model.volume.seismology.MantleModel(
    name="ausrem_mantle", data="./data/ausrem_mantle.nc", taper_in_degrees=5.0
)

...and now finally let's create a complete model configuration using anisotropic PREM as a background model.

mc = sn.ModelConfiguration(
    background_model="prem_ani_one_crust",
    volume_models=["ausrem_crust", "ausrem_mantle"],
)

Adding surface and Moho topography

Surface and Moho topography can be added in a similar fashion to those on Cartesian domains.

These files contain filtered versions of global surface and moho topography.

p += sn.topography.spherical.SurfaceTopography(
    name="topo_surface",
    data="./data/topography_wgs84_filtered_512.nc",
    use_symlink=True,
)
p += sn.topography.spherical.MohoTopography(
    name="topo_moho",
    data="./data/moho_topography_wgs84_filtered.nc",
    use_symlink=True,
)
tc = sn.topography.TopographyConfiguration(
    topography_models=["topo_surface", "topo_moho"]
)

To finalize our simulation configuration, we first prepare an event configuration to define the time and frequency axes. We'll simulate half an hour of synthetic waveforms, and take as our source time function a Gaussian in moment-rate. In this case we'll set a very short half-duration in seconds to get an almost white spectrum in our synthetic data. We'll use this to motivate the processing functions we later apply.

# end_time_in_seconds should be 1800.0 s!
# We only truncated the time interval for the CI.

ec = sn.EventConfiguration(
    wavelet=sn.simple_config.stf.GaussianRate(half_duration_in_seconds=1.5000),
    waveform_simulation_configuration=sn.WaveformSimulationConfiguration(
        end_time_in_seconds=10.0
    ),
)

As always, we need to also set up some absorbing boundary parameters here. At this point it is fair to ask the question: how do I choose a reference velocity in a domain with a 3-D velocity model, and what even is the reference frequency if my spectrum is white? The answer to both of these questions is that, as always, the performance of the absorbing boundaries is a tunable parameter. In the case of a white spectrum a good rule is to set the reference frequency to the dominant frequency in your observed data.

ab = sn.AbsorbingBoundaryParameters(
    reference_velocity=6000.0,
    number_of_wavelengths=3.5,
    reference_frequency=1 / 40.0,
)

We've now got everything we need to set up our simulation configuration object, as we do in the next cell below. Here we'll generate a simulation mesh which ensures that we have at least 1 element per wavelength using a minimum period of 40 seconds, and the using anisotropic PREM as a size function.

# Combine everything into a complete configuration.
p += sn.SimulationConfiguration(
    tensor_order=1,
    name="40seconds",
    elements_per_wavelength=1.0,
    min_period_in_seconds=40,
    max_depth_in_meters=1000e3,
    model_configuration=mc,
    topography_configuration=tc,
    event_configuration=ec,
    absorbing_boundaries=ab,
)

We can, as is true with the other domains, visualize our new simulation configuration...

p.viz.nb.simulation_setup("40seconds", events=p.events.list())
[2020-09-17 13:12:30,215] INFO - salvus.project.meshing: Creating mesh. Hang on.
Interpolating model: ausrem_crust.
Interpolating model: ausrem_mantle.
/miniconda/envs/salvus/lib/python3.7/_collections_abc.py:702: MatplotlibDeprecationWarning: The global colormaps dictionary is no longer considered public API.
  return len(self._mapping)
/miniconda/envs/salvus/lib/python3.7/_collections_abc.py:720: MatplotlibDeprecationWarning: The global colormaps dictionary is no longer considered public API.
  yield from self._mapping
When run interactively in a Jupyter Notebook, this output cell contains a widget. Click the button below to load a preview of it. Please note that most interactive functionality does not work without a running Python kernel.
<salvus.flow.simple_config.simulation.Waveform object at 0x7f3c4b0c4310>

... and then go ahead and run our simulation. The time taken to complete will vary significantly depending on the options you've chosen above. For instance, adding both Moho and surface topography decreases the time step by quite a bit due to the relatively small elements in the oceanic crust.

p.simulations.launch(
    ranks_per_job=4,
    site_name=SALVUS_FLOW_SITE_NAME,
    events=p.events.list()[0],
    wall_time_in_seconds_per_job=3600,
    simulation_configuration="40seconds",
)

while not p.simulations.query():
    time.sleep(10.0)
[2020-09-17 13:12:34,276] INFO - salvus.project.components.simulation_component: Submitting job ...
Uploading 1 files...

🚀  Submitted [email protected]local
[2020-09-17 13:12:34,646] INFO - salvus.project.components.simulation_component: Status of running jobs (might be slightly out of date).
[2020-09-17 13:12:34,648] INFO - salvus.project.components.simulation_component: job_2009171312376846_12a0e5ec37:
[2020-09-17 13:12:34,648] INFO - salvus.project.components.simulation_component:     event_SOUTHEAST_OF_LOYALTY_ISLANDS_Mag_5.59_2010-08-03-22-30: pending
[2020-09-17 13:12:44,756] INFO - salvus.project.components.simulation_component: Status of running jobs (might be slightly out of date).
[2020-09-17 13:12:44,757] INFO - salvus.project.components.simulation_component: job_2009171312376846_12a0e5ec37:
[2020-09-17 13:12:44,757] INFO - salvus.project.components.simulation_component:     event_SOUTHEAST_OF_LOYALTY_ISLANDS_Mag_5.59_2010-08-03-22-30: running
[2020-09-17 13:12:54,827] INFO - salvus.project.components.simulation_component: Status of running jobs (might be slightly out of date).
[2020-09-17 13:12:54,828] INFO - salvus.project.components.simulation_component: job_2009171312376846_12a0e5ec37:
[2020-09-17 13:12:54,828] INFO - salvus.project.components.simulation_component:     event_SOUTHEAST_OF_LOYALTY_ISLANDS_Mag_5.59_2010-08-03-22-30: running `Computing forward wavefield`: 26% done
[2020-09-17 13:13:04,883] INFO - salvus.project.components.simulation_component: Status of running jobs (might be slightly out of date).
[2020-09-17 13:13:04,883] INFO - salvus.project.components.simulation_component: job_2009171312376846_12a0e5ec37:
[2020-09-17 13:13:04,884] INFO - salvus.project.components.simulation_component:     event_SOUTHEAST_OF_LOYALTY_ISLANDS_Mag_5.59_2010-08-03-22-30: running `Computing forward wavefield`: 54% done
[2020-09-17 13:13:14,949] INFO - salvus.project.components.simulation_component: Status of running jobs (might be slightly out of date).
[2020-09-17 13:13:14,950] INFO - salvus.project.components.simulation_component: job_2009171312376846_12a0e5ec37:
[2020-09-17 13:13:14,950] INFO - salvus.project.components.simulation_component:     event_SOUTHEAST_OF_LOYALTY_ISLANDS_Mag_5.59_2010-08-03-22-30: running `Computing forward wavefield`: 81% done
[2020-09-17 13:13:25,066] INFO - salvus.project.components.simulation_component: Retrieving output for 1 simulation(s) from site.

It is usually necessary to process files to be able to compare data to synthetics.

# Import helper function generating suitable processing functions.
from salvus.project.tools.processing.seismology import (
    get_bandpass_filter_processing_function,
    get_remove_response_and_bandpass_filter_processing_function,
)
p += sn.processing.seismology.SeismologyProcessingConfiguration(
    name="observed_40_seconds",
    data_source_name="EXTERNAL_DATA:raw_recording",
    processing_function=get_remove_response_and_bandpass_filter_processing_function(
        min_frequency_in_hertz=1.0 / 100.0,
        max_frequency_in_hertz=1.0 / 40.0,
        highpass_corners=4,
        lowpass_corners=4,
    ),
)
p += sn.processing.seismology.SeismologyProcessingConfiguration(
    name="synthetic_40_seconds",
    data_source_name="40seconds",
    processing_function=get_bandpass_filter_processing_function(
        min_frequency_in_hertz=1.0 / 100.0,
        max_frequency_in_hertz=1.0 / 40.0,
        highpass_corners=4,
        lowpass_corners=4,
    ),
)
p.viz.nb.waveforms(
    [
        "PROCESSED_DATA:observed_40_seconds",
        "PROCESSED_DATA:synthetic_40_seconds",
    ],
    receiver_field="velocity",
)
When run interactively in a Jupyter Notebook, this output cell contains a widget. Click the button below to load a preview of it. Please note that most interactive functionality does not work without a running Python kernel.

The .nc files we used in this tutorial are in fact the same convention that is used by the IRIS Earth Model Catalogue (EMC). This means that many of the models stored in the EMC can be downloaded and used directly in Salvus! Unfortunately, there is no standard parameter set stored in the EMC, and we've found that not all the files actually conform to the required convention. Nevertheless, with some minimal processing, you can have the public library of 3-D Earth models at your disposal to run simulations through. The picture below show a successful attempt at including 3 distinct 3-D Earth models (crust, mantle, cascadia) for a region along the US west coast.

http://ds.iris.edu/ds/products/emc/

# # Adding the downloaded file as a mantle model.
# p += sn.model.volume.seismology.MantleModel(
#     name="SEMUM", data="./SEMUM_kmps.nc"
# )
# # Combine into a model configuration.
# mc1 = sn.model.ModelConfiguration(
#     background_model="prem_iso_one_crust", volume_models=["SEMUM"]
# )
# # Combine everything into a complete configuration.
# p += sn.SimulationConfiguration(
#     tensor_order=1,
#     name="40seconds_semum",
#     elements_per_wavelength=1.0,
#     min_period_in_seconds=40,
#     max_depth_in_meters=1000e3,
#     model_configuration=mc1,
#     topography_configuration=tc,
#     event_configuration=ec,
#     absorbing_boundaries=ab,
# )
# # Visualize the setup.
# p.viz.nb.simulation_setup("40seconds_semum", events=p.events.list())
# # Can also open it in Paraview.
# m = p.simulation.get_mesh_filenames("40seconds_semum")["xdmf_filename"]

# # Uncomment the following line on Mac OS
# # !open {m}
PAGE CONTENTS