pynetdesign.modelling.utils.get_phase_station_directionality

pynetdesign.modelling.utils.get_phase_station_directionality(station_coords, grid_coords, phases=('P', 'SV', 'SH'), geometry_df=None, force_tangent=False, strict_nan_check=False)

Derive receiver projection coefficients for P, SV and SH polarizations.

The recorded amplitude of a phase is the projection of its arriving polarization onto the direction the receiver is sensitive to. For a phase \(\phi\) the correction applied to the minimum detectable amplitude is

\[C_{\phi} = \frac{1}{\left| \mathbf{d} \cdot \mathbf{e}_{\phi} \right|},\]

where \(\mathbf{e}_{\phi}\) is the arriving polarization and \(\mathbf{d}\) is the local cable tangent for DAS, or the vertical axis for a single-component station. Three-component stations record the full vector and therefore use a coefficient of one.

Parameters:

station_coordsnumpy.ndarray

Array of station coordinates [[xr1, yr1, zr1], [xr2, yr2, zr2], …]

grid_coordsnumpy.ndarray

Array of grid coordinates [[xs1, ys1, zs1], [xs2, ys2, zs2], …]

phasessequence of str, optional, default: ("P", "SV", "SH")

Phases to compute coefficients for. Must be drawn from ‘P’, ‘SV’ and ‘SH’.

geometry_dfpandas.DataFrame, optional

Geometry DataFrame, used to detect a DAS geometry from its gauge length and to read a Components column for station geometries. If None, projection onto the local tangent is used.

force_tangentbool, optional, default: False

Force projection onto the local tangent even when geometry_df describes a station geometry.

strict_nan_checkbool, optional, default: False

Flag to check whether NaN values appear in the result.

Returns:

coefficientsdict

Mapping from phase name to an array of coefficients of shape (n_grid_points, n_stations).

Raises:

ValueError

If a requested phase is not P, SV or SH, if the geometry and station coordinates disagree in length, or if a DAS geometry also carries a Components column.

RuntimeError

If strict_nan_check is True and NaN appears in the result.

Notes

A vanishing projection means the phase cannot be recorded at all, for example SH on a vertical cable, and yields NaN so that the phase is excluded rather than reported as infinitely detectable.

Straight rays between each station and each grid point are assumed, which is exact in a homogeneous medium.