pynetdesign.modelling.utils.compute_free_surface_coefficients

pynetdesign.modelling.utils.compute_free_surface_coefficients(station_coords, grid_coords, station_coords_on_surface=None, fs_mode='auto', fs_level=0.0, fs_deviation=1.0)

Compute free surface amplification coefficients for each station and grid point.

A receiver recording at the free surface sees an amplitude approximately twice that of the incident wave, which is the exact amplification for normal or near-normal incidence. The coefficient is applied per station, so that a geometry combining surface receivers with receivers at depth is treated correctly.

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], …]

station_coords_on_surfacenumpy.ndarray, optional

Per-station indicator of whether the station is on the free surface, as a 1D array of the same length as the number of stations, with values in [0, 1]. Values between 0 and 1 act as a weighting factor between no amplification and full amplification. If None, the indicator is derived from the station depths.

fs_modestr, optional, default: 'auto'

Free surface correction mode, can be 'auto', 'on' or 'off'. If 'on', the correction is applied to stations close to the free surface irrespective of station_coords_on_surface. If 'off', the correction is never applied. If 'auto', station_coords_on_surface is used when available, otherwise stations are considered to be on the free surface when their Z coordinate deviates from the free surface level by no more than fs_deviation.

fs_levelfloat, optional, default: 0.0

Level of the free surface in metres above the reference level.

fs_deviationfloat, optional, default: 1.0

Permitted deviation from the free surface level in metres, must be non-negative.

Returns:

fs_coef_pnumpy.ndarray

Free surface coefficients for P waves, of shape (n_grid_points, n_stations)

fs_coef_snumpy.ndarray

Free surface coefficients for S waves, of shape (n_grid_points, n_stations)

Raises:

ValueError

If fs_level is not a scalar, fs_deviation is negative, station_coords_on_surface has the wrong shape or values outside [0, 1], or fs_mode is not one of the supported modes.

Notes

The free surface level is negated internally to match the convention that Z increases downwards.