Reading, synthesis and caching#

Most dynamic readers share geometry, sampling, filtering and time-window arguments. Their tensor layouts and native time origins differ. Read each function’s Notes before combining results.

With only_seismograms=False, the dynamic seek_* functions return seven values. first_p and first_s remain None unless shift=True; nearest-grid metadata can differ from the geometry used for interpolation. EDCMP readers return static arrays and normalize the mechanism magnitude.

read_syn#

pygrnwang.read_syn.read_syn(method, path_green, event_depth_km, receiver_depth_km, az_deg, dist_km, focal_mechanism, srate, output_type='disp', rotate=True, before_p=None, pad_zeros=False, shift=False, only_seismograms=True, model_name='ak135fc', green_info=None, interpolate_type=0, freq_band=None, butter_order=4, zero_phase=False)[source]#

Read dynamic synthetic waveforms through an explicit backend selector.

Parameters:

method (str) – One of qseis2025, qssp2020, spgrn2020 or spgrn2012; QSEIS06 and EDCMP have separate readers.
path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
az_deg (float) – Source-to-receiver azimuth in degrees clockwise from north.
dist_km (float) – Epicentral distance in km; query within the stored distance grid.
focal_mechanism (array_like) – Either [strike, dip, rake] in degrees; [M0, strike, dip, rake]; six NED components [Mnn, Mne, Mnd, Mee, Med, Mdd]; or [M0, six components]. Three angles imply unit moment; seven entries normalize the six-component shape to M0. Moments are in N m.
srate (float) – Positive output sampling rate in Hz.
output_type (str, optional) – Requested observable; supported values and units are listed in Notes. Default: ‘disp’.
rotate (bool, optional) – Rotate vector output to east, north, up when True; False retains radial, transverse, up. Tensor layouts are specified in Notes. Default: True.
before_p (float or None, optional) – Seconds before the library P onset at the new first sample. None preserves the native window. Default: None.
pad_zeros (bool, optional) – Shift to source-origin time using zero padding. Use separately from before_p. Default: False.
shift (bool, optional) – Correct the time axis using P/S arrivals recomputed for the requested geometry and model. Default: False.
only_seismograms (bool, optional) – Return just the waveform array when True; False returns the array and six metadata fields. Default: True.
model_name (str, optional) – TauP built-in model name or path to a custom model. Use a model consistent with the Green library. Default: ‘ak135fc’.
green_info (dict or None, optional) – Preloaded green_lib_info.json mapping; None loads it from path_green. Default: None.
interpolate_type (int, optional) – 0 selects nearest neighbor; 1 interpolates source depth, receiver depth and distance. Returned grid metadata remains nearest neighbor. Default: 0.
freq_band (sequence of float or None, optional) – Two cutoff frequencies [low, high] in Hz. None disables filtering in readers; a missing corner selects lowpass or highpass. Default: None.
butter_order (int, optional) – Butterworth filter order. Default: 4.
zero_phase (bool, optional) – True applies forward/backward filtering; False uses causal filtering. Default: False.

Returns:

seismograms (numpy.ndarray) – Shape (C, N): C=3 for vectors, 6 for tensors or 1 for scalar outputs, with physical units and component conventions of the selected backend.
metadata (tuple, conditional) – With only_seismograms=False returns the seven-tuple (seismograms, tpts_table, first_p, first_s, grn_dep_source, grn_dep_receiver, grn_dist). Arrival times are seconds after origin; first_p/first_s are None unless shift=True. Grid coordinates are nearest stored nodes in km.

Raises:

ValueError – method is unsupported or a selected reader rejects its parameters.
OSError – The selected reader cannot access required library files.
KeyError – Metadata does not describe the selected backend.

Notes

Dispatches unchanged keyword arguments to the selected seek function. Vector rotate=True means east, north, up; native tensor layouts and time origins differ by backend. Consult seek_qseis2025, seek_qssp2020, seek_spgrn2020 or seek_spgrn2012 for supported observables, units and tpts_table availability. No automatic backend detection, grid conversion or physical normalization is performed.

read_qseis2025#

pygrnwang.read_qseis2025.seek_qseis2025(path_green, event_depth_km, receiver_depth_km, az_deg, dist_km, focal_mechanism, srate, output_type='disp', rotate=True, before_p=None, pad_zeros=False, shift=False, only_seismograms=True, model_name='ak135fc', green_info=None, interpolate_type=0, freq_band=None, butter_order=4, zero_phase=False)[source]#

Synthesize qseis2025 waveforms from a precomputed Green library.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
az_deg (float) – Source-to-receiver azimuth in degrees clockwise from north.
dist_km (float) – Epicentral distance in km; query within the stored distance grid.
focal_mechanism (array_like) – Either [strike, dip, rake] in degrees; [M0, strike, dip, rake]; six NED components [Mnn, Mne, Mnd, Mee, Med, Mdd]; or [M0, six components]. Three angles imply unit moment; seven entries normalize the six-component shape to M0. Moments are in N m.
srate (float) – Positive output sampling rate in Hz.
output_type (str, optional) – Requested observable; supported values and units are listed in Notes. Default: ‘disp’.
rotate (bool, optional) – Rotate vector output to east, north, up when True; False retains radial, transverse, up. Tensor layouts are specified in Notes. Default: True.
before_p (float or None, optional) – Seconds before the library P onset at the new first sample. None preserves the native window. Default: None.
pad_zeros (bool, optional) – Shift to source-origin time using zero padding. Use separately from before_p. Default: False.
shift (bool, optional) – Correct the time axis using P/S arrivals recomputed for the requested geometry and model. Default: False.
only_seismograms (bool, optional) – Return just the waveform array when True; False returns the array and six metadata fields. Default: True.
model_name (str, optional) – TauP built-in model name or path to a custom model. Use a model consistent with the Green library. Default: ‘ak135fc’.
green_info (dict or None, optional) – Preloaded green_lib_info.json mapping; None loads it from path_green. Default: None.
interpolate_type (int, optional) – 0 selects nearest neighbor; 1 interpolates source depth, receiver depth and distance. Returned grid metadata remains nearest neighbor. Default: 0.
freq_band (sequence of float or None, optional) – Two cutoff frequencies [low, high] in Hz. None disables filtering in readers; a missing corner selects lowpass or highpass. Default: None.
butter_order (int, optional) – Butterworth filter order. Default: 4.
zero_phase (bool, optional) – True applies forward/backward filtering; False uses causal filtering. Default: False.

Returns:

seismograms (numpy.ndarray) – Shape (C, N): components by resampled time samples. C is 3 for vectors, 6 for tensors and 1 for scalar outputs.
metadata (tuple, conditional) – If only_seismograms=False, returns the seven-tuple (seismograms, tpts_table, first_p, first_s, grn_dep_source, grn_dep_receiver, grn_dist). The last three fields describe the nearest stored node in km, including when waveforms are interpolated. first_p and first_s are None unless shift=True; calculated arrivals are in seconds relative to source origin and may be NaN if absent. tpts_table is None when before_p is None and shift/pad_zeros are False; otherwise it contains p_onset and s_onset in seconds.

Raises:

OSError – Metadata, selected observables or travel-time files are missing.
ValueError – Incompatible time-window options or invalid filter/output parameters.
KeyError – Library metadata lacks keys required by this backend.

Notes

Vector rows with rotate=True are east, north, up (ENU), not NED. With rotate=False they are radial, transverse, up; positive transverse points counterclockwise from radial when viewed from above. Moments retain the scale supplied to check_convert_fm. See the qseis2025 tutorial and scientific conventions for the native time origin. Supported outputs: disp (m), velo (m/s), acce (m/s2), volume, strain (dimensionless), strain_rate (1/s), stress (Pa), stress_rate (Pa/s), rota (rad), rota_rate (rad/s). Six tensor rows after rotation are [ee, en, eu, nn, nu, uu]. Before rotation they are [tt, rt, -zt, rr, -zr, zz] in terms of synthesized native components, not [rr, rt, ru, tt, tu, uu]. Wavelet types 1 and 0 (a custom moment-rate STF) store rate kernels, which are integrated for non-rate quantities; type 2 kernels are differentiated for rates.

read_qseis06#

Deprecated backend: QSEIS06. Use the QSEIS2025 reader with a newly built QSEIS2025 library for new calculations; revalidate parameter choices and results.

pygrnwang.read_qseis06.seek_qseis06(path_green, event_depth_km, receiver_depth_km, az_deg, dist_km, focal_mechanism, srate, output_type='disp', rotate=True, before_p=None, pad_zeros=False, shift=False, only_seismograms=True, model_name='ak135fc', green_info=None, freq_band=None, butter_order=4, zero_phase=False)[source]#

Synthesize qseis06 waveforms from a precomputed Green library.

Warning

QSEIS06 is deprecated. Use QSEIS2025 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
az_deg (float) – Source-to-receiver azimuth in degrees clockwise from north.
dist_km (float) – Epicentral distance in km; query within the stored distance grid.
focal_mechanism (array_like) – Either [strike, dip, rake] in degrees; [M0, strike, dip, rake]; six NED components [Mnn, Mne, Mnd, Mee, Med, Mdd]; or [M0, six components]. Three angles imply unit moment; seven entries normalize the six-component shape to M0. Moments are in N m.
srate (float) – Positive output sampling rate in Hz.
output_type (str, optional) – Requested observable; supported values and units are listed in Notes. Default: ‘disp’.
rotate (bool, optional) – Rotate vector output to east, north, up when True; False retains radial, transverse, up. Tensor layouts are specified in Notes. Default: True.
before_p (float or None, optional) – Seconds before the library P onset at the new first sample. None preserves the native window. Default: None.
pad_zeros (bool, optional) – Shift to source-origin time using zero padding. Use separately from before_p. Default: False.
shift (bool, optional) – Correct the time axis using P/S arrivals recomputed for the requested geometry and model. Default: False.
only_seismograms (bool, optional) – Return just the waveform array when True; False returns the array and six metadata fields. Default: True.
model_name (str, optional) – TauP built-in model name or path to a custom model. Use a model consistent with the Green library. Default: ‘ak135fc’.
green_info (dict or None, optional) – Preloaded green_lib_info.json mapping; None loads it from path_green. Default: None.
freq_band (sequence of float or None, optional) – Two cutoff frequencies [low, high] in Hz. None disables filtering in readers; a missing corner selects lowpass or highpass. Default: None.
butter_order (int, optional) – Butterworth filter order. Default: 4.
zero_phase (bool, optional) – True applies forward/backward filtering; False uses causal filtering. Default: False.

Returns:

seismograms (numpy.ndarray) – Shape (C, N): components by resampled time samples. C is 3 for vectors, 6 for tensors and 1 for scalar outputs.
metadata (tuple, conditional) – If only_seismograms=False, returns the seven-tuple (seismograms, tpts_table, first_p, first_s, grn_dep_source, grn_dep_receiver, grn_dist). The last three fields describe the nearest stored node in km, including when waveforms are interpolated. first_p and first_s are None unless shift=True; calculated arrivals are in seconds relative to source origin and may be NaN if absent. tpts_table is None when before_p is None and shift/pad_zeros are False; otherwise it contains p_onset and s_onset in seconds.

Raises:

OSError – Metadata, selected observables or travel-time files are missing.
ValueError – Incompatible time-window options or invalid filter/output parameters.
KeyError – Library metadata lacks keys required by this backend.

Notes

Vector rows with rotate=True are east, north, up (ENU), not NED. With rotate=False they are radial, transverse, up; positive transverse points counterclockwise from radial when viewed from above. Moments retain the scale supplied to check_convert_fm. See the qseis06 tutorial and scientific conventions for the native time origin. Supported outputs: disp (m), velo (m/s), acce (m/s2); C=3. Wavelet types 1 and 0 (a custom moment-rate STF) store velocity kernels: displacement integrates them and acceleration differentiates them. Type 2 stores displacement kernels.

read_qseis06_diff#

Deprecated backend: QSEIS06. Its strain-rate and stress-rate readers are deprecated; use QSEIS2025 direct tensor outputs with a newly built and validated library for new calculations. The generic convert_strain2stress utility below is not deprecated.

This is an advanced historical workflow. It requires a dedicated perturbation library with ASCII files retained. The docstrings record current binary-reader and azimuth-rotation limitations; verify these conventions for your application. The QSEIS2025 tutorial demonstrates directly computed strain and stress.

pygrnwang.read_qseis06_diff.seek_qseis06_strain_rate_diff(path_green, event_depth_km, receiver_depth_km, az_deg, dist_km, focal_mechanism, srate, before_p=None, pad_zeros=False, shift=False, only_seismograms=True, model_name='ak135fc', green_info=None)[source]#

Calculate strain rate by finite differencing a QSEIS06 perturbation library.

Warning

QSEIS06 is deprecated. Use QSEIS2025 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
az_deg (float) – Source-to-receiver azimuth in degrees clockwise from north.
dist_km (float) – Epicentral distance in km; query within the stored distance grid.
focal_mechanism (array_like) – Either [strike, dip, rake] in degrees; [M0, strike, dip, rake]; six NED components [Mnn, Mne, Mnd, Mee, Med, Mdd]; or [M0, six components]. Three angles imply unit moment; seven entries normalize the six-component shape to M0. Moments are in N m.
srate (float) – Positive output sampling rate in Hz.
before_p (float or None, optional) – Seconds before the library P onset at the new first sample. None preserves the native window. Default: None.
pad_zeros (bool, optional) – Shift to source-origin time using zero padding. Use separately from before_p. Default: False.
shift (bool, optional) – Correct the time axis using P/S arrivals recomputed for the requested geometry and model. Default: False.
only_seismograms (bool, optional) – Return just the waveform array when True; False returns the array and six metadata fields. Default: True.
model_name (str, optional) – TauP built-in model name or path to a custom model. Use a model consistent with the Green library. Default: ‘ak135fc’.
green_info (dict or None, optional) – Preloaded green_lib_info.json mapping; None loads it from path_green. Default: None.

Returns:

series (numpy.ndarray) – Shape (6, N), in the condensed tensor layout described in Notes, as strain rate.
metadata (tuple, conditional) – With only_seismograms=False returns (series, tpts_table, first_p, first_s, grn_dep_source, grn_dep_receiver, grn_dist). Arrival seconds are relative to source origin; first_p/first_s are None unless shift=True. Grid depth and distance values are km.

Raises:

OSError – A perturbation waveform or travel-time table is missing.
KeyError – A normal waveform library was supplied instead of a finite-difference library.
ValueError – Time alignment or resampling parameters are invalid.

Notes

Requires pre_process_qseis06_strain_rate and all depth/radial perturbation jobs, not a normal QSEIS06 waveform library. The finite-difference metadata uses dist_range/delta_dist and stores k_dr, dz and diff_accu_order. Avoid zero distance and depth perturbations above the surface. The six pre-rotation rows are [e_tt, e_rt, -e_tz, e_rr, -e_rz, e_zz]; the historical reader applies rotate_symmetric_tensor_series with -az_deg, whereas QSEIS2025 uses +az_deg. Verify the azimuth/sign mapping independently before treating these rows as geographic ENU. Strain rate is 1/s and stress rate is Pa/s for moments in N m. See the QSEIS06 tutorial; QSEIS2025 can compute these observables directly.

This advanced historical workflow currently requires retained ASCII outputs: its binary detector looks for grn_tz.npy, and the binary call omits the required sampling_num argument. Keep convert_pd2bin=False and remove_pd=False when executing perturbation jobs. Numerical equivalence with QSEIS2025 is not implied.

pygrnwang.read_qseis06_diff.seek_qseis06_stress_rate_diff(path_green, event_depth_km, receiver_depth_km, az_deg, dist_km, focal_mechanism, srate, before_p=None, pad_zeros=False, shift=False, only_seismograms=True, model_name='ak135fc', green_info=None)[source]#

Calculate stress rate by finite differencing a QSEIS06 perturbation library.

Warning

QSEIS06 is deprecated. Use QSEIS2025 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
az_deg (float) – Source-to-receiver azimuth in degrees clockwise from north.
dist_km (float) – Epicentral distance in km; query within the stored distance grid.
focal_mechanism (array_like) – Either [strike, dip, rake] in degrees; [M0, strike, dip, rake]; six NED components [Mnn, Mne, Mnd, Mee, Med, Mdd]; or [M0, six components]. Three angles imply unit moment; seven entries normalize the six-component shape to M0. Moments are in N m.
srate (float) – Positive output sampling rate in Hz.
before_p (float or None, optional) – Seconds before the library P onset at the new first sample. None preserves the native window. Default: None.
pad_zeros (bool, optional) – Shift to source-origin time using zero padding. Use separately from before_p. Default: False.
shift (bool, optional) – Correct the time axis using P/S arrivals recomputed for the requested geometry and model. Default: False.
only_seismograms (bool, optional) – Return just the waveform array when True; False returns the array and six metadata fields. Default: True.
model_name (str, optional) – TauP built-in model name or path to a custom model. Use a model consistent with the Green library. Default: ‘ak135fc’.
green_info (dict or None, optional) – Preloaded green_lib_info.json mapping; None loads it from path_green. Default: None.

Returns:

series (numpy.ndarray) – Shape (6, N), in the condensed tensor layout described in Notes, as stress rate.
metadata (tuple, conditional) – With only_seismograms=False returns (series, tpts_table, first_p, first_s, grn_dep_source, grn_dep_receiver, grn_dist). Arrival seconds are relative to source origin; first_p/first_s are None unless shift=True. Grid depth and distance values are km.

Raises:

OSError – A perturbation waveform or travel-time table is missing.
KeyError – A normal waveform library was supplied instead of a finite-difference library.
ValueError – Time alignment or resampling parameters are invalid.

Notes

Requires pre_process_qseis06_strain_rate and all depth/radial perturbation jobs, not a normal QSEIS06 waveform library. The finite-difference metadata uses dist_range/delta_dist and stores k_dr, dz and diff_accu_order. Avoid zero distance and depth perturbations above the surface. The six pre-rotation rows are [e_tt, e_rt, -e_tz, e_rr, -e_rz, e_zz]; the historical reader applies rotate_symmetric_tensor_series with -az_deg, whereas QSEIS2025 uses +az_deg. Verify the azimuth/sign mapping independently before treating these rows as geographic ENU. Strain rate is 1/s and stress rate is Pa/s for moments in N m. See the QSEIS06 tutorial; QSEIS2025 can compute these observables directly.

This advanced historical workflow currently requires retained ASCII outputs: its binary detector looks for grn_tz.npy, and the binary call omits the required sampling_num argument. Keep convert_pd2bin=False and remove_pd=False when executing perturbation jobs. Numerical equivalence with QSEIS2025 is not implied.

pygrnwang.read_qseis06_diff.convert_strain2stress(strain, lam, mu)[source]#

Apply isotropic Hooke law to a tensor strain or strain-rate series.

Parameters:

strain (numpy.ndarray) – Tensor strain or strain-rate series with shape (6, N) in [ee, en, eu, nn, nu, uu] order.
lam (float) – First Lame parameter in Pa for the homogeneous half-space.
mu (float) – Shear modulus in Pa for the homogeneous half-space.

Returns:

stress (numpy.ndarray) – Shape (6, N), same ordering as input; Pa for strain input or Pa/s for strain-rate input when lam and mu are in Pa.

Notes

Off-diagonal terms are physical tensor strain, not doubled engineering strain.

read_spgrn2012#

Deprecated backend: SPGRN2012. Use the SPGRN2020 reader with a newly built SPGRN2020 library for new calculations; revalidate parameter choices, time alignment and results.

pygrnwang.read_spgrn2012.seek_spgrn2012(path_green, event_depth_km, receiver_depth_km, az_deg, dist_km, focal_mechanism, srate, output_type='disp', rotate=True, before_p=None, pad_zeros=False, shift=False, only_seismograms=True, model_name='ak135fc', green_info=None, interpolate_type=0, freq_band=None, butter_order=4, zero_phase=False)[source]#

Synthesize spgrn2012 waveforms from a precomputed Green library.

Warning

SPGRN2012 is deprecated. Use SPGRN2020 for new calculations. Rebuild the Green library with the replacement backend and revalidate numerical settings, source and time conventions, and results; existing libraries and parameter choices are not guaranteed to be interchangeable.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
az_deg (float) – Source-to-receiver azimuth in degrees clockwise from north.
dist_km (float) – Epicentral distance in km; query within the stored distance grid.
focal_mechanism (array_like) – Either [strike, dip, rake] in degrees; [M0, strike, dip, rake]; six NED components [Mnn, Mne, Mnd, Mee, Med, Mdd]; or [M0, six components]. Three angles imply unit moment; seven entries normalize the six-component shape to M0. Moments are in N m.
srate (float) – Positive output sampling rate in Hz.
output_type (str, optional) – Requested observable; supported values and units are listed in Notes. Default: ‘disp’.
rotate (bool, optional) – Rotate vector output to east, north, up when True; False retains radial, transverse, up. Tensor layouts are specified in Notes. Default: True.
before_p (float or None, optional) – Seconds before the library P onset at the new first sample. None preserves the native window. Default: None.
pad_zeros (bool, optional) – Shift to source-origin time using zero padding. Use separately from before_p. Default: False.
shift (bool, optional) – Correct the time axis using P/S arrivals recomputed for the requested geometry and model. Default: False.
only_seismograms (bool, optional) – Return just the waveform array when True; False returns the array and six metadata fields. Default: True.
model_name (str, optional) – TauP built-in model name or path to a custom model. Use a model consistent with the Green library. Default: ‘ak135fc’.
green_info (dict or None, optional) – Preloaded green_lib_info.json mapping; None loads it from path_green. Default: None.
interpolate_type (int, optional) – 0 selects nearest neighbor; 1 interpolates source depth, receiver depth and distance. Returned grid metadata remains nearest neighbor. Default: 0.
freq_band (sequence of float or None, optional) – Two cutoff frequencies [low, high] in Hz. None disables filtering in readers; a missing corner selects lowpass or highpass. Default: None.
butter_order (int, optional) – Butterworth filter order. Default: 4.
zero_phase (bool, optional) – True applies forward/backward filtering; False uses causal filtering. Default: False.

Returns:

seismograms (numpy.ndarray) – Shape (C, N): components by resampled time samples. C is 3 for vectors, 6 for tensors and 1 for scalar outputs.
metadata (tuple, conditional) – If only_seismograms=False, returns the seven-tuple (seismograms, tpts_table, first_p, first_s, grn_dep_source, grn_dep_receiver, grn_dist). The last three fields describe the nearest stored node in km, including when waveforms are interpolated. first_p and first_s are None unless shift=True; calculated arrivals are in seconds relative to source origin and may be NaN if absent. tpts_table is None when before_p is None and shift/pad_zeros are False; otherwise it contains p_onset and s_onset in seconds.

Raises:

OSError – Metadata, selected observables or travel-time files are missing.
ValueError – Incompatible time-window options or invalid filter/output parameters.
KeyError – Library metadata lacks keys required by this backend.

Notes

Vector rows with rotate=True are east, north, up (ENU), not NED. With rotate=False they are radial, transverse, up; positive transverse points counterclockwise from radial when viewed from above. Moments retain the scale supplied to check_convert_fm. See the spgrn2012 tutorial and scientific conventions for the native time origin. Supported outputs: disp (m), velo (m/s), acce (m/s2); C=3. Displacement integrates native velocity kernels and acceleration differentiates them.

read_spgrn2020#

pygrnwang.read_spgrn2020.seek_spgrn2020(path_green, event_depth_km, receiver_depth_km, az_deg, dist_km, focal_mechanism, srate, output_type='disp', rotate=True, before_p=None, pad_zeros=False, shift=False, only_seismograms=True, model_name='ak135fc', green_info=None, interpolate_type=0, freq_band=None, butter_order=4, zero_phase=False)[source]#

Synthesize spgrn2020 waveforms from a precomputed Green library.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
az_deg (float) – Source-to-receiver azimuth in degrees clockwise from north.
dist_km (float) – Epicentral distance in km; query within the stored distance grid.
focal_mechanism (array_like) – Either [strike, dip, rake] in degrees; [M0, strike, dip, rake]; six NED components [Mnn, Mne, Mnd, Mee, Med, Mdd]; or [M0, six components]. Three angles imply unit moment; seven entries normalize the six-component shape to M0. Moments are in N m.
srate (float) – Positive output sampling rate in Hz.
output_type (str, optional) – Requested observable; supported values and units are listed in Notes. Default: ‘disp’.
rotate (bool, optional) – Rotate vector output to east, north, up when True; False retains radial, transverse, up. Tensor layouts are specified in Notes. Default: True.
before_p (float or None, optional) – Seconds before the library P onset at the new first sample. None preserves the native window. Default: None.
pad_zeros (bool, optional) – Shift to source-origin time using zero padding. Use separately from before_p. Default: False.
shift (bool, optional) – Correct the time axis using P/S arrivals recomputed for the requested geometry and model. Default: False.
only_seismograms (bool, optional) – Return just the waveform array when True; False returns the array and six metadata fields. Default: True.
model_name (str, optional) – TauP built-in model name or path to a custom model. Use a model consistent with the Green library. Default: ‘ak135fc’.
green_info (dict or None, optional) – Preloaded green_lib_info.json mapping; None loads it from path_green. Default: None.
interpolate_type (int, optional) – 0 selects nearest neighbor; 1 interpolates source depth, receiver depth and distance. Returned grid metadata remains nearest neighbor. Default: 0.
freq_band (sequence of float or None, optional) – Two cutoff frequencies [low, high] in Hz. None disables filtering in readers; a missing corner selects lowpass or highpass. Default: None.
butter_order (int, optional) – Butterworth filter order. Default: 4.
zero_phase (bool, optional) – True applies forward/backward filtering; False uses causal filtering. Default: False.

Returns:

seismograms (numpy.ndarray) – Shape (C, N): components by resampled time samples. C is 3 for vectors, 6 for tensors and 1 for scalar outputs.
metadata (tuple, conditional) – If only_seismograms=False, returns the seven-tuple (seismograms, tpts_table, first_p, first_s, grn_dep_source, grn_dep_receiver, grn_dist). The last three fields describe the nearest stored node in km, including when waveforms are interpolated. first_p and first_s are None unless shift=True; calculated arrivals are in seconds relative to source origin and may be NaN if absent. tpts_table is always loaded and contains P/S onset, takeoff and slowness fields.

Raises:

OSError – Metadata, selected observables or travel-time files are missing.
ValueError – Incompatible time-window options or invalid filter/output parameters.
KeyError – Library metadata lacks keys required by this backend.

Notes

Vector rows with rotate=True are east, north, up (ENU), not NED. With rotate=False they are radial, transverse, up; positive transverse points counterclockwise from radial when viewed from above. Moments retain the scale supplied to check_convert_fm. See the spgrn2020 tutorial and scientific conventions for the native time origin. Supported outputs: disp (m), velo (m/s), acce (m/s2); C=3. Displacement integrates native velocity kernels and acceleration differentiates them.

class pygrnwang.read_spgrn2020.GridGFCache(path_green, green_info, max_blocks=None)[source]#

Cache raw SPGRN2020 grid blocks and travel-time tables in one process.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
green_info (dict or None) – Preloaded green_lib_info.json mapping; None loads it from path_green.
max_blocks (int or None, optional) – Maximum raw blocks held with least-recently-used eviction; None retains all. Each block contains 10 * samples_num float32 values. Travel-time tables are retained separately. Default: None.

Returns:

cache (GridGFCache) – Empty cache; disk reads occur on demand.

Raises:

OSError – Required library files are missing or cannot be read.

Notes

See the SPGRN2020 tutorial and cache guide. Source and receiver grids must belong to the same library. Cached arrays may be returned directly: treat them as read-only. The cache is not automatically invalidated when files change.

GridGFCache.get_block(depth_node, rec_node, dist_idx)[source]#

Get one exact stored grid block and update its LRU position.

Parameters:

depth_node (float) – Exact source depth node in km.
rec_node (float) – Exact receiver depth node in km.
dist_idx (int) – Zero-based index into the library distance list.

Returns:

data (numpy.ndarray) – Raw basis Green functions with shape (10, N), in native sampling.

Raises:

OSError – Required library files are missing or cannot be read.

Notes

See the SPGRN2020 tutorial and cache guide. Source and receiver grids must belong to the same library. The returned float32 array has 10 elementary traces, each with green_info[“samples_num”] samples.

GridGFCache.time_series(event_depth_km, receiver_depth_km, dist_km, n_cols=None)[source]#

Interpolate cached basis waveforms in source depth, receiver depth and distance.

Parameters:

event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
dist_km (float) – Epicentral distance in km; query within the stored distance grid.
n_cols (int or None, optional) – Keep at most the first n_cols native samples before interpolating; None uses the full block. Default: None.

Returns:

data (numpy.ndarray) – Raw basis Green functions with shape (10, N), in native sampling.

Raises:

OSError – Required library files are missing or cannot be read.

Notes

See the SPGRN2020 tutorial and cache guide. Source and receiver grids must belong to the same library. Trilinear interpolation clamps coordinates outside the grid; n_cols truncates each input block before combining.

GridGFCache.tpts_table(event_depth_km, receiver_depth_km, dist_km)[source]#

Read nearest-node SPGRN P/S arrival metadata from cached tables.

Parameters:

event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
dist_km (float) – Epicentral distance in km; query within the stored distance grid.

Returns:

tpts_table (dict) – p_onset, p_takeoff, p_slowness and corresponding s_ keys: arrival seconds, takeoff degrees and backend slowness in s/m. Metadata uses nearest nodes.

Raises:

OSError – Required library files are missing or cannot be read.

Notes

See the SPGRN2020 tutorial and cache guide. Source and receiver grids must belong to the same library.

pygrnwang.read_spgrn2020.synthesize_from_cache(cache, event_depth_km, receiver_depth_km, az_deg, dist_km, focal_mechanisms, srate, output_type='disp', rotate=True, before_p=None, pad_zeros=False, shift=False, freq_band=None, butter_order=4, zero_phase=False, n_keep=None, model_name='ak135fc')[source]#

Synthesize multiple mechanisms from one SPGRN2020 cache.

Parameters:

cache (GridGFCache) – Reusable cache for one SPGRN2020 library.
event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
az_deg (float) – Source-to-receiver azimuth in degrees clockwise from north.
dist_km (float) – Epicentral distance in km; query within the stored distance grid.
focal_mechanisms (sequence of array_like) – Nonempty sequence of mechanisms accepted by check_convert_fm.
srate (float) – Positive output sampling rate in Hz.
output_type (str, optional) – Requested observable; supported values and units are listed in Notes. Default: ‘disp’.
rotate (bool, optional) – Rotate vector output to east, north, up when True; False retains radial, transverse, up. Tensor layouts are specified in Notes. Default: True.
before_p (float or None, optional) – Seconds before the library P onset at the new first sample. None preserves the native window. Default: None.
pad_zeros (bool, optional) – Shift to source-origin time using zero padding. Use separately from before_p. Default: False.
shift (bool, optional) – Correct the time axis using P/S arrivals recomputed for the requested geometry and model. Default: False.
freq_band (sequence of float or None, optional) – Two cutoff frequencies [low, high] in Hz. None disables filtering in readers; a missing corner selects lowpass or highpass. Default: None.
butter_order (int, optional) – Butterworth filter order. Default: 4.
zero_phase (bool, optional) – True applies forward/backward filtering; False uses causal filtering. Default: False.
n_keep (int or None, optional) – Keep at most this many output samples; None returns the full available window. Default: None.
model_name (str, optional) – TauP built-in model name or path to a custom model. Use a model consistent with the Green library. Default: ‘ak135fc’.

Returns:

seis_stack (numpy.ndarray) – Shape (number_of_mechanisms, 3, N), with ENU rows if rotate=True or radial, transverse, up otherwise. N is limited by n_keep and available data.
tpts_table (dict) – Nearest stored P/S arrival metadata; this is not a list per mechanism.

Raises:

OSError – Required library files are missing or cannot be read.
ValueError – No mechanisms are supplied, time options conflict, or filter parameters are invalid.

Notes

See the SPGRN2020 tutorial and cache guide. Source and receiver grids must belong to the same library. Supports disp (m), velo (m/s) and acce (m/s2). Uses trilinear interpolation and the same time/filter conventions as seek_spgrn2020. Empty mechanism sequences are not accepted.

read_qssp2020#

pygrnwang.read_qssp2020.seek_qssp2020(path_green, event_depth_km, receiver_depth_km, az_deg, dist_km, focal_mechanism, srate, output_type='disp', rotate=True, before_p=None, pad_zeros=False, shift=False, only_seismograms=True, model_name='ak135fc', green_info=None, interpolate_type=0, freq_band=None, butter_order=4, zero_phase=False)[source]#

Synthesize qssp2020 waveforms from a precomputed Green library.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
az_deg (float) – Source-to-receiver azimuth in degrees clockwise from north.
dist_km (float) – Epicentral distance in km; query within the stored distance grid.
focal_mechanism (array_like) – Either [strike, dip, rake] in degrees; [M0, strike, dip, rake]; six NED components [Mnn, Mne, Mnd, Mee, Med, Mdd]; or [M0, six components]. Three angles imply unit moment; seven entries normalize the six-component shape to M0. Moments are in N m.
srate (float) – Positive output sampling rate in Hz.
output_type (str, optional) – Requested observable; supported values and units are listed in Notes. Default: ‘disp’.
rotate (bool, optional) – Rotate vector output to east, north, up when True; False retains radial, transverse, up. Tensor layouts are specified in Notes. Default: True.
before_p (float or None, optional) – Seconds before the library P onset at the new first sample. None preserves the native window. Default: None.
pad_zeros (bool, optional) – Shift to source-origin time using zero padding. Use separately from before_p. Default: False.
shift (bool, optional) – Correct the time axis using P/S arrivals recomputed for the requested geometry and model. Default: False.
only_seismograms (bool, optional) – Return just the waveform array when True; False returns the array and six metadata fields. Default: True.
model_name (str, optional) – TauP built-in model name or path to a custom model. Use a model consistent with the Green library. Default: ‘ak135fc’.
green_info (dict or None, optional) – Preloaded green_lib_info.json mapping; None loads it from path_green. Default: None.
interpolate_type (int, optional) – 0 selects nearest neighbor; 1 interpolates source depth, receiver depth and distance. Returned grid metadata remains nearest neighbor. Default: 0.
freq_band (sequence of float or None, optional) – Two cutoff frequencies [low, high] in Hz. None disables filtering in readers; a missing corner selects lowpass or highpass. Default: None.
butter_order (int, optional) – Butterworth filter order. Default: 4.
zero_phase (bool, optional) – True applies forward/backward filtering; False uses causal filtering. Default: False.

Returns:

seismograms (numpy.ndarray) – Shape (C, N): components by resampled time samples. C is 3 for vectors, 6 for tensors and 1 for scalar outputs.
metadata (tuple, conditional) – If only_seismograms=False, returns the seven-tuple (seismograms, tpts_table, first_p, first_s, grn_dep_source, grn_dep_receiver, grn_dist). The last three fields describe the nearest stored node in km, including when waveforms are interpolated. first_p and first_s are None unless shift=True; calculated arrivals are in seconds relative to source origin and may be NaN if absent. tpts_table is None when before_p is None and shift/pad_zeros are False; otherwise it contains p_onset and s_onset in seconds.

Raises:

OSError – Metadata, selected observables or travel-time files are missing.
ValueError – Incompatible time-window options or invalid filter/output parameters.
KeyError – Library metadata lacks keys required by this backend.

Notes

Vector rows with rotate=True are east, north, up (ENU), not NED. With rotate=False they are radial, transverse, up; positive transverse points counterclockwise from radial when viewed from above. Moments retain the scale supplied to check_convert_fm. See the qssp2020 tutorial and scientific conventions for the native time origin. Supported outputs: disp (m), velo (m/s), acce (m/s2), strain, strain_rate (1/s), stress (Pa), stress_rate (Pa/s), rota (rad), rota_rate (rad/s), gravitation (m/s2), gravimeter (m/s2). Tensor rows are [ee, en, eu, nn, nu, uu] after rotation; with rotate=False they remain the backend local ENU ordering for a receiver north of the source. Request only observables enabled during preprocessing.

read_by_qssp#

pygrnwang.read_by_qssp.read_by_qssp(path_green, event_lat, event_lon, event_depth_km, receiver_lat, receiver_lon, receiver_depth_km, focal_mechanism, srate, read_name='hash', output_type='disp', green_info=None, check_finished=False)[source]#

Synthesize a receiver from QSSP spectra using the historical direct runner.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
event_lat (float) – Source latitude used for the output-name hash only; actual source coordinates are fixed at (0, 0).
event_lon (float) – Source longitude used for the output-name hash only; actual source coordinates are fixed at (0, 0).
event_depth_km (float) – Requested source depth in km, positive down.
receiver_lat (float) – Receiver latitude in degrees.
receiver_lon (float) – Receiver longitude in degrees.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
focal_mechanism (array_like) – Either [strike, dip, rake] in degrees; [M0, strike, dip, rake]; six NED components [Mnn, Mne, Mnd, Mee, Med, Mdd]; or [M0, six components]. Three angles imply unit moment; seven entries normalize the six-component shape to M0. Moments are in N m.
srate (float) – Positive output sampling rate in Hz.
read_name (str, optional) – Output subdirectory name; hash derives it from query parameters. Default: ‘hash’.
output_type (str, optional) – Requested observable; supported values and units are listed in Notes. Default: ‘disp’.
green_info (dict or None, optional) – Preloaded green_lib_info.json mapping; None loads it from path_green. Default: None.
check_finished (bool, optional) – Reuse outputs marked finished. Markers do not verify that inputs are unchanged. Default: False.

Returns:

seismograms (numpy.ndarray)

Raises:

OSError – Required inputs or outputs cannot be accessed.
ValueError – Parameters do not describe a supported grid or observable.

Notes

Current implementation limits: the generated native source is fixed at latitude/longitude (0, 0); event_lat/event_lon affect only the directory hash. Supply receiver coordinates relative to that actual source. The default hash omits the focal mechanism and output selections, so check_finished=True can reuse incompatible results after a mechanism change. The runner also expects the executable in the environment Scripts/bin directory. Prefer seek_qssp2020 for the standard precomputed-library workflow.

read_edcmp#

pygrnwang.read_edcmp.seek_edcmp2(path_green, event_depth_km, receiver_depth_km, az_deg, dist_km, focal_mechanism, rotate=True, check_convert_pure_dp=True, output_type='disp', times_mu=False, area_km_sq=None, model_name='ak135fc', green_info=None)[source]#

Read static EDCMP deformation at the nearest stored geometry.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
az_deg (float) – Source-to-receiver azimuth in degrees clockwise from north.
dist_km (float) – Epicentral distance in km; query within the stored distance grid.
focal_mechanism (array_like) – Either [strike, dip, rake] in degrees; [M0, strike, dip, rake]; six NED components [Mnn, Mne, Mnd, Mee, Med, Mdd]; or [M0, six components]. Three angles imply unit moment; seven entries normalize the six-component shape to M0. Moments are in N m.
rotate (bool, optional) – Rotate vector output to east, north, up when True; False retains radial, transverse, up. Tensor layouts are specified in Notes. Default: True.
check_convert_pure_dp (bool, optional) – Project to the double-couple mechanism extracted by mt2plane. Both branches normalize scalar moment to one; False does not preserve input moment magnitude. Default: True.
output_type (str, optional) – Requested observable; supported values and units are listed in Notes. Default: ‘disp’.
times_mu (bool, optional) – True retains raw rigidity-scaled Green values; False divides by source-node shear modulus from model_name. Default: False.
area_km_sq (float or None, optional) – Multiply the result by this area in km2 converted to m2. Does not automatically supply the missing rigidity or slip factor. Default: None.
model_name (str, optional) – TauP built-in model name or path to a custom model. Use a model consistent with the Green library. Default: ‘ak135fc’.
green_info (dict or None, optional) – Preloaded green_lib_info.json mapping; None loads it from path_green. Default: None.

Returns:

deformation (numpy.ndarray) – Shape (C,): C=3 for disp, 6 for strain/stress, 2 for tilt.

Raises:

OSError – Library or material-model files cannot be read.
ValueError – Output type is unsupported, a mechanism has zero scalar moment, or arrays have incompatible shapes.

Notes

Supported output_type values: disp, strain, stress, tilt. With rotate=True vector rows are east, north, up, tensor rows are [ee, en, eu, nn, nu, uu], and tilt rows are east, north. With rotate=False vectors are radial, transverse, up and tensors are [rr, rt, ru, tt, tu, uu]. All mechanisms are normalized to unit scalar moment. With times_mu=False and no area/slip factor, output is per N m: displacement m/(N m), strain 1/(N m), stress Pa/(N m), tilt rad/(N m). Multiply by the desired seismic moment to obtain physical values. Alternatively times_mu=True with area in km2 and slip in m supplies the mu*A*slip scaling; the single-query function requires applying slip externally. Area alone with times_mu=False does not restore rigidity. Material lookup accepts built-in ak135fc or a four-column no-Q ND path; it is independent of the model metadata. Use the same elastic structure as the library. See the EDGRN/EDCMP tutorial.

pygrnwang.read_edcmp.seek_edcmp2_bulk(path_green, event_depth_km_arr, receiver_depth_km_arr, az_deg_arr, dist_km_arr, focal_mechanism_arr, rotate=True, check_convert_pure_dp=True, output_type='disp', times_mu=False, area_km_sq_arr=None, slip_m_arr=None, model_name='ak135fc', green_info=None)[source]#

Read static EDCMP deformation for a batch of query geometries.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
event_depth_km_arr (array_like) – Source depths in km, shape (N,).
receiver_depth_km_arr (array_like) – Receiver depths in km, shape (N,).
az_deg_arr (array_like) – Source-to-receiver clockwise azimuths from north in degrees, shape (N,).
dist_km_arr (array_like) – Epicentral distances in km, shape (N,).
focal_mechanism_arr (array_like) – N mechanisms, shape (N, 3), (N, 4), (N, 6) or (N, 7), using check_convert_fm conventions; magnitude is normalized away.
rotate (bool, optional) – Rotate vector output to east, north, up when True; False retains radial, transverse, up. Tensor layouts are specified in Notes. Default: True.
check_convert_pure_dp (bool, optional) – Project to the double-couple mechanism extracted by mt2plane. Both branches normalize scalar moment to one; False does not preserve input moment magnitude. Default: True.
output_type (str, optional) – Requested observable; supported values and units are listed in Notes. Default: ‘disp’.
times_mu (bool, optional) – True retains raw rigidity-scaled Green values; False divides by source-node shear modulus from model_name. Default: False.
area_km_sq_arr (array_like or None, optional) – Subfault areas in km2, shape (N,), multiplied after conversion to m2. Default: None.
slip_m_arr (array_like or None, optional) – Subfault slips in m, shape (N,), multiplied into output rows. Default: None.
model_name (str, optional) – TauP built-in model name or path to a custom model. Use a model consistent with the Green library. Default: ‘ak135fc’.
green_info (dict or None, optional) – Preloaded green_lib_info.json mapping; None loads it from path_green. Default: None.

Returns:

deformation (numpy.ndarray) – Shape (N, C), one row per query; C=3 for disp, 6 for strain/stress, 2 for tilt.

Raises:

OSError – Library or material-model files cannot be read.
ValueError – Output type is unsupported, a mechanism has zero scalar moment, or arrays have incompatible shapes.

Notes

Supported output_type values: disp, strain, stress, tilt. With rotate=True vector rows are east, north, up, tensor rows are [ee, en, eu, nn, nu, uu], and tilt rows are east, north. With rotate=False vectors are radial, transverse, up and tensors are [rr, rt, ru, tt, tu, uu]. All mechanisms are normalized to unit scalar moment. With times_mu=False and no area/slip factor, output is per N m: displacement m/(N m), strain 1/(N m), stress Pa/(N m), tilt rad/(N m). Multiply by the desired seismic moment to obtain physical values. Alternatively times_mu=True with area in km2 and slip in m supplies the mu*A*slip scaling; the single-query function requires applying slip externally. Area alone with times_mu=False does not restore rigidity. Material lookup accepts built-in ak135fc or a four-column no-Q ND path; it is independent of the model metadata. Use the same elastic structure as the library. See the EDGRN/EDCMP tutorial. Run convert_pd2bin_edcmp2_all first. The batch reader requires root-level edcmp2_<output_type>.bin files.

read_green_info_spgrn#

pygrnwang.read_green_info_spgrn.read_green_info_spgrn(path_greenfunc, green_depth)[source]#

Read native SPGRN time sampling and distance nodes.

Parameters:

path_greenfunc (str) – SPGRN source/receiver depth folder containing GreenInfo and P/S table files.
green_depth (float) – Exact source depth in km used in the GreenInfo filename.

Returns:

info (dict) – time_window and sampling_interval in seconds, integer samples_num, and dist_list in km.

Raises:

OSError – The GreenInfo file cannot be read.
ValueError – The file does not follow the expected backend format.

Return type:

dict

read_tpts_table#

pygrnwang.read_tpts_table.read_tpts_table(path_greenfunc, dist_in_km, green_info)[source]#

Read nearest-distance native SPGRN first-arrival metadata.

Parameters:

path_greenfunc (str) – SPGRN source/receiver depth folder containing GreenInfo and P/S table files.
dist_in_km (float) – Epicentral distance in km; selects the nearest entry in dist_list.
green_info (dict or None) – Preloaded green_lib_info.json mapping; None loads it from path_green.

Returns:

table (dict) – p_onset, p_takeoff, p_slowness and matching s_ fields: arrival seconds, takeoff degrees, and backend slowness in s/m.

Raises:

OSError – A required P/S table cannot be read.

Return type:

dict

Notes

This reads Fortran-record SPGRN tables; it is distinct from utils.read_tpts_table, which reads the flat TauP binary tables.

utils#

pygrnwang.utils.read_tpts_table(path_green, event_depth_km, receiver_depth_km, ind)[source]#

Read one pair of flat float32 TauP arrival-table entries.

Parameters:

path_green (str) – Absolute library root containing green_lib_info.json and backend subdirectories.
event_depth_km (float) – Requested source depth in km, positive down.
receiver_depth_km (float) – Requested receiver depth in km, positive down.
ind (int) – Zero-based index into the stored distance sequence.

Returns:

first_p, first_s (float)

Raises:

OSError – Required inputs or outputs cannot be accessed.
ValueError – Parameters do not describe a supported grid or observable.

Notes