pynetdesign.modelling.homo.mag_sensitivity_grid#

pynetdesign.modelling.homo.mag_sensitivity_grid(grid_coords, velocity_df, geometry_df=None, station_coords=None, min_amps_p=None, min_amps_s=None, min_stations_p=None, min_stations_s=None, rad_pattern_p=None, rad_pattern_s=None, rad_patterns=None, f_p=None, f_s=None, f_p_corner=None, f_s_corner=None, wave_mode='PS', fs_mode='auto', fs_level=None, fs_deviation=None, use_station_directionality=False, return_stations=False, strict_nan_check=False, amps_type=None)[source]#

Computes magnitude sensitivity - the minimum moment magnitude (Mw) of a microseismic event which will theoretically produce particle velocity amplitudes (of P and/or S waves) on stations necessary for event detection assuming 3D elastic homogeneous medium with attenuation. It takes into account minimum number of stations on which the event should be detected. By request it is possible to output only minimum moment magnitude for each station.

Parameters:

grid_coordsnumpy.ndarray: Array of grid coordinates [[xs1, ys1, zs1], [xs2, ys2, zs2], …]
velocity_dfpandas.DataFrame: Velocity model DataFrame
geometry_dfpandas.DataFrame, optional: Geometry DataFrame, use if station_coords is None
station_coordsnumpy.ndarray, optional: Array of station coordinates [[xr1, yr1, zr1], [xr2, yr2, zr2], …], use if geometry_df is None
min_amps_pnumpy.ndarray, optional: Minimal measurable displacement amplitudes of on stations [a1, a2, …] for P waves
min_amps_snumpy.ndarray, optional: Minimal measurable displacement amplitudes on stations [a1, a2, …] for S waves
min_stations_pint, optional, default: None (3): Minimum number of stations on which event must be detected with P waves
min_stations_sint, optional, default: None (3): Minimum number of stations on which event must be detected with S waves
rad_pattern_pfloat, optional: Override of the radiation pattern factor for P waves. If None, the root-mean-square value \(\sqrt{4/15} \approx 0.52\) is used.
rad_pattern_sfloat, optional: Override of the radiation pattern factor applied to both S phases. If None, the root-mean-square values \(\sqrt{7/30} \approx 0.48\) for SV and \(\sqrt{1/6} \approx 0.41\) for SH are used. Pass 0.63 to reproduce results computed with the combined S-wave value.
rad_patternsdict, optional: Per-phase overrides of the radiation pattern factor, e.g. {'SV': 0.63}. Takes precedence over rad_pattern_p and rad_pattern_s.
f_pfloat, optional: Frequency of the P wave (Hz)
f_sfloat, optional: Frequency of the S wave (Hz)
f_p_cornerfloat, optional: Corner frequency of the P wave (Hz)
f_s_cornerfloat, optional: Corner frequency of the S wave (Hz)
wave_mode: :obj:`str`, optional, default: ‘PS’: Wave mode to use, can be ‘P’, ‘SV’, ‘SH’, ‘S’ or ‘PS’
fs_modestr, optional, default: ‘auto’: Free surface correction mode, can be ‘auto’, ‘on’ or ‘off’. The correction accounts for the amplification of amplitudes recorded at the daily surface due to the free surface boundary condition, and is applied per station so that geometries mixing surface and downhole receivers are handled correctly. See compute_free_surface_coefficients.
fs_levelfloat, optional, default: None (0.0): Level of the free surface in metres above the reference level.
fs_deviationfloat, optional, default: None (1.0): Permitted deviation from the free surface level in metres.
use_station_directionalitybool, optional, default: False: Force projection of the arriving polarization onto the local tangent defined by the adjacent stations. Projection is applied automatically for DAS geometries and for stations recording a single vertical component, so this is only needed to force tangent projection for a station geometry.
return_stationsbool, optional, default: False: Return magnitude sensitivity for each station, don’t take into account detectability
strict_nan_check: :obj:`bool`, optional, default: False: flag to check if NaN values appear in the result
amps_typestr, optional, default: None: Type of amplitudes, can be ‘displacement’, ‘velocity’, ‘acceleration’, ‘strain rate’, ‘strain’.

Returns:

Mw_min_gridnumpy.ndarray: Array of computed detectable minimum moment magnitudes on the grid, if return_stations = False
Mw_min_stationsnumpy.ndarray: Array of computed minimum moment magnitudes for individual stations, if return_stations = True Mw_min_stations is of shape (2, npairs) where npairs is a number of of source-grid pairs determined from station_coords and grid_coords. First dimension corresponds to P and S waves.

Raises:

ValueError: if both station_coords and geometry_df are not None or None
ValueError: if there is inconsistency in P/S wave parameters
ValueError: if number of minimal measurable amplitudes do not match number of stations
ValueError: if density, wave velocity or attenuation factor is not positive
ValueError: if radiation pattern factor for P or S wave is less or equal to 0 or higher than 1
ValueError: if number of minimal measurable amplitudes does not match number of stations
RuntimeError: if strict_nan_check is True and NaN appears in the result

Notes

This is a refactored vectorized version of the code