dsm

Main module of dsmpy. Contains the classes for core dsmpy objects and the methods for serial and parallel computation of synthetic seismograms using the Fortran DSM.

Compute functions

compute

dsmpy.dsm.compute(pydsm_input, write_to_file=False, mode=0)

Compute spectra using DSM.

Parameters

  • dsm_input (PyDSMInput) – inputs for DSM.

  • mode (int) – computation mode. 0: both, 1: P-SV, 2: SH.

  • write_to_file (bool) – write spetrum files to disk

  • specified in dsm_input.output. (as) –

Returns

object containing spectra and

stations/source information.

Return type

PyDSMOutput

Note

SH and P-SV spectra are summed by default. Using only P-SV or SH results in non-physical waves and should be avoided. See Kawai et al. (2006) for details.

Examples

>>> catalog = dsmpy.utils.cmtcatalog.read_catalog()
>>> event = Event.event_from_catalog(
...     catalog, '200707211534A')
>>> stations = [
...     Station(
...         name='FCC', network='CN',
...         latitude=58.7592, longitude=-94.0884),
...     ]
>>> model = SeismicModel.prem()
>>> input = PyDSMInput.input_from_arrays(
...     event, stations,
...     model, tlen=1638.4, nspc=256,
...     sampling_hz=20)
>>> output = compute(input, mode=0)
>>> output.plot()
>>> plt.show()

compute_dataset_parallel

dsmpy.dsm.compute_dataset_parallel(dataset, seismic_model, tlen, nspc, sampling_hz, mode=0, write_to_file=False, verbose=0, log=None)

Compute spectra using DSM with data parallelization for a given seismic model.

This method scales to large dataset and many CPU cores, since the dataset is split (scattered) between many cores.

Parameters

  • dataset (Dataset) – dataset of events & stations.

  • mode (int) – computation mode. 0: both, 1: P-SV, 2: SH.

  • write_to_file (bool) – write output in Kibrary format (default is False).

Returns

list of PyDSMOutput objects with one

entry for each event in dataset.

Return type

list of PyDSMOutput

Examples

>>> dataset = Dataset.dataset_from_sac(
...     sac_files, headonly=False)
>>> model = SeismicModel.prem()
>>> outputs = compute_dataset_parallel(
...     dataset, model, tlen=1638.4, nspc=256,
...     sampling_hz=20, mode=0)
>>> outputs[0].plot()
>>> plt.show()

compute_models_parallel

dsmpy.dsm.compute_models_parallel(dataset, models, tlen, nspc, sampling_hz, mode=0, write_to_file=False, verbose=0)

Compute synthetics for a list of models in parallel.

At the moment, we must have len(models) % n_cores == 0. If this is not satisfied, the list of models will be padded to the closest larger integer that satisfies this relation.

Warning: When the dataset contains a large number of records, and for a large number of seismic models, the memory usage for this method can get large as it scales as len(models) * dataset.nr.

Parameters

  • dataset (Dataset) – dataset.

  • models (list of SeismicModel) – the models

  • tlen (float) – duration of the synthetics (in seconds) (better to be 2**n/10)

  • nspc (int) – number of frequency points in the synthetics (better to be 2**n)

  • sampling_hz (int) –

  • mode (int) – computation mode. 0: both, 1: P-SV, 2: SH (default is 0).

  • write_to_file (bool) – write output in Kibrary format (default is False).

  • verbose (int) – debugging parameter (default is 0).

Returns

Shape is (n_models, n_events).

Return type

list of list of PyDSMOutput

Examples

>>> dataset = Dataset.dataset_from_sac(
...     sac_files)
>>> models = [SeismicModel.prem(), SeismicModel.ak135()]
>>> outputs = compute_models_parallel(
...     dataset, models, tlen=1638.4, nspc=256,
...     sampling_hz=20, mode=0)
>>> fig, ax = plt.subplots(1)
>>> outputs[0][0].plot_component(
...     component=Component.T, ax=ax, label='prem')
>>> outputs[1][0].plot_component(
...     component=Component.T, ax=ax, label='ak135')
>>> plt.show()

compute_parallel

dsmpy.dsm.compute_parallel(pydsm_input, mode=0, write_to_file=False, verbose=0)

Compute spectra using DSM with data parallelization.

DSMInput

class dsmpy.dsm.DSMInput(re, ratc, ratl, tlen, nspc, omegai, imin, imax, nzone, vrmin, vrmax, rho, vpv, vph, vsv, vsh, eta, qmu, qkappa, r0, eqlat, eqlon, mt, nr, theta, phi, lat, lon, output, file_mode=1)

Input parameters used by the Fortran DSM.

Parameters

  • re (float) –

  • ratc (float) –

  • ratl (float) –

  • tlen (float) – duration of the synthetics (in seconds) (must be 2**n/10)

  • nspc (int) – number of frequency points in the synthetics (must be 2**n)

  • omegai (float) –

  • imin (int) –

  • imax (int) –

  • nzone (int) –

  • vrmin (ndarray) –

  • vrmax (ndarray) –

  • rho (ndarray) –

  • vpv (ndarray) –

  • vph (ndarray) –

  • vsv (ndarray) –

  • vsh (ndarray) –

  • eta (ndarray) –

  • qmu (ndarray) –

  • qkappa (ndarray) –

  • r0 (float) –

  • eqlat (float) –

  • eqlon (float) –

  • mt (ndarray) –

  • nr (int) –

  • theta (ndarray) –

  • phi (ndarray) –

  • lat (float) –

  • lon (float) –

  • output (ndarray) –

  • file_mode (int) –

classmethod input_from_arrays(event, stations, seismic_model, tlen, nspc)

Build a DSMInput from user-friendly arguments.

Parameters

  • event (Event) – earthquake information.

  • stations (list of Station) – seismic stations.

  • seismic_model (SeismicModel) – Earth structure model (e.g. PREM).

  • tlen (float) – duration of the synthetics (in seconds) (better to be 2**n/10)

  • nspc (int) – number of frequency points in the synthetics (better to be 2**n)

Returns

DSMInput object

Return type

DSMInput

classmethod input_from_file(parameter_file, file_mode=1)

Build a DSMInput object from a DSM input file.

Parameters

  • parameter_file (str) – path of a DSM input file

  • mode (int) – 1: P-SV, 2: SH

Returns

DSMInput

PyDSMInputFile

class dsmpy.dsm.PyDSMInputFile(input_file)

Input file for dsmpy.

Parameters

input_file (str) – path of dsmpy input file

PyDSMInput

class dsmpy.dsm.PyDSMInput(dsm_input, sampling_hz=None, file_mode=1)

Input parameters for dsmpy compute methods.

Parameters

  • dsm_input (DSMInput) – input parameters for Fortran DSM.

  • sampling_hz (int) – sampling frequency for time-domain waveforms.

  • mode (int) – 1: P-SV, 2: SH. (default is 1).

classmethod input_from_arrays(event, stations, seismic_model, tlen, nspc, sampling_hz)

Build a PyDSMInput from user-friendly arguments.

Parameters

  • event (Event) – earthquake information.

  • stations (list of Station) – seismic stations.

  • seismic_model (SeismicModel) – Earth structure model (e.g. PREM).

  • tlen (float) – duration of the synthetics (in seconds) (better to be 2**n/10)

  • nspc (int) – number of frequency points in the synthetics (better to be 2**n)

  • sampling_hz (float) – sampling frequency for time-domain synthetics.

Returns

PyDSMInput object.

Return type

PyDSMInput

classmethod input_from_file(parameter_file, sampling_hz=None, source_time_function=None, file_mode=1)

Build a PyDSMInput object from a DSM input file.

Parameters

  • parameter_file (str) – path of a DSM input file.

  • sampling_hz (float) – sampling frequency

  • time-domain waveforms. (for) –

  • source_time_function (SourceTimeFunction) –

  • object. (SourceTimeFunction) –

  • file_mode (int) – 1: P-SV, 2: SH.

Returns

PyDSMInput object

PyDSMOutput

class dsmpy.dsm.PyDSMOutput(spcs, stations, event, sampling_hz, tlen, nspc, omegai=0.0014053864092981234, model_id=None)

Output from dsmpy compute methods.

Parameters

  • spcs (ndarray) – seismic spectra computed with DSM. Shape is (3, nr, nspc+1).

  • stations (ndarray of Station) – stations. Shape is (nr,)

  • event (Event) – seismic event (the source).

  • sampling_hz (int) – sampling frequency for time-domain waveforms

  • tlen (float) – duration of the synthetics (in seconds) (better to be 2**n/10)

  • nspc (int) – number of frequency points in the synthetics (better to be 2**n)

  • omegai (float) – numerical damping using in DSM. Default is default_params[‘omegai’]. Better to leave it at its default value.

  • model_id (str) – seismic model identifier (e.g., ‘PREM’, ‘mod1’). (default is None).

filter(freq, freq2=0.0, type='lowpass', zerophase=False)

Filter time-domain waveforms using obspy.signal.filter.

Parameters

  • freq (float) – filter frequency

  • freq2 (float) – filter maximum frequency (for bandpass filters only)

  • type (str) – type of filter (‘lowpass’, ‘bandpass’).

  • zerophase (bool) – use zero-phase filter (default is False).

free()

Free memory for the large fields self.us and self.ts.

Can be used after processing the time-domain waveform in cases where a large number of waveforms are used, which can quickly requires a lot of memory.

Examples: >>> output.to_time_domain() >>> # do some operations on output.us >>> output.free()

get_nr()

Returns the number of receivers (stations).

get_traces()

Return list of obspy.Trace.

Returns

traces

Return type

list ot obspy.Trace

get_us_shape() -> (<class 'int'>, <class 'int'>, <class 'int'>)

Return the shape of self.us (without doing FFT).

static load(path)

Read file into self using pickle.load().

Parameters

path (str) – name of the file that contains self.

Returns

the loaded PyDSMOutput object.

Return type

PyDSMOutput

plot_component(component, windows=None, ax=None, align_zero=False, **kwargs)

Plot waveforms for one seismic component.

Parameters

component (Component) – seismic component.

Returns

matplotlib figure object. Axes: matplotlib Axes object.

Return type

figure

plot_spc(color='black', axes=None, distance_min=0.0, distance_max=inf, label=None, normalize='self')

Plot a frequency-domain (spectra) record section.

Parameters

  • axes (matplotlib.axes) – ax on which to plot

  • distance_min (float) – minimum epicentral distance (deg)

  • distance_max (float) – maximum epicentral distance (deg)

  • label (str) – label for model name

  • normalize (str) – ‘self’ for self-normalization

  • 'none' to see amplitude decay with distance (or) –

Returns

matplotlib figure object. Axes: matplotlib Axes object.

Return type

figure

save(path)

Save self using pickle.dump().

Parameters

path (str) – name of the output file.

set_source_time_function(source_time_function)

Set the source time function for convolution.

Parameters

source_time_function (SourceTimeFunction) – source time function object.

to_time_domain(source_time_function=None)

Compute time domain waveforms from spetcra.

Parameters

source_time_function (SourceTimeFunction) – source time function object (default is None).

window_spcs(windows, window_width)

Window the spectra in the frequency domain using gaussian windows to isolate portions of time-domain waveforms.

Parameters

  • windows (list of Window) – windows.

  • window_width (float) – duration (in seconds).

Returns

windowed PyDSMOutput object.

Return type

PyDSMOutput

write(root_path, format)

Write to file using obspy.io.write.

Parameters

  • root_path (str) – path of root folder in which to write.

  • format (str) – output files format (‘sac’).