Slowness grid

Slowness grid#

Slowness grids and plane-wave time delays for beamforming.

This module defines the SlownessGrid — a two-dimensional grid parameterised by apparent slowness magnitude and azimuth (or equivalently by the Cartesian slowness components \(u_x\), \(u_y\)) — and the PlaneWaveDelays subclass that pre-computes the time delay of a plane wave at each station for every grid point.

Contrary to GeographicalGrid, which lives in three-dimensional geographical space (longitude, latitude, depth), a SlownessGrid lives in two-dimensional horizontal slowness space. It is the natural input for plane-wave beamforming, whereas TravelTimes is the natural input for matched-field processing.

Classes#

  • SlownessGrid — regular 2-D grid in slowness–azimuth space.

  • PlaneWaveDelays — pre-computed inter-station time delays for every slowness grid point.

class covseisnet.slowness.SlownessGrid(slowness_max: float, n_slowness: int, n_azimuth: int, fill_value: float = nan)[source]#

Bases: ndarray

Regular two-dimensional grid in apparent-slowness space.

The grid covers the apparent slowness magnitude \(s \in [s_{\min}, s_{\max}]\) and the propagation azimuth \(\theta \in [0°, 360°)\) measured clockwise from north. At each grid point \((s, \theta)\) we can store any scalar quantity (e.g. beamformed power).

Internally the grid is stored as a 2-D NumPy array of shape (n_slowness, n_azimuth). The corresponding axis values are available as slowness and azimuth.

The Cartesian slowness components are

\[u_x = s \sin\theta, \qquad u_y = s \cos\theta\]

and are available via the ux and uy properties.

Parameters:

  • slowness_max (float) -- Maximum apparent slowness in s/km.

  • n_slowness (int) -- Number of slowness samples (including zero).

  • n_azimuth (int) -- Number of azimuth samples over \([0°, 360°)\).

  • fill_value (float, optional) -- Initial fill value for the grid array. Default is numpy.nan.

Example

import covseisnet as csn

grid = csn.slowness.SlownessGrid(
    slowness_max=0.5, n_slowness=30, n_azimuth=72
)
print(grid)
Parameters:

  • slowness_max (float) -- Maximum apparent slowness in s/km.

  • n_slowness (int) -- Number of slowness samples (from 0 to slowness_max).

  • n_azimuth (int) -- Number of azimuth samples uniformly distributed over \([0°, 360°)\).

  • fill_value (float, optional) -- Value used to initialise the grid. Default is numpy.nan.

property ux: ndarray#

East Cartesian slowness \(u_x = s \sin\theta\) (s/km).

property uy: ndarray#

North Cartesian slowness \(u_y = s \cos\theta\) (s/km).

property mesh: tuple[ndarray, ndarray]#

Meshgrid (slowness, azimuth) of shape (n_slowness, n_azimuth).

maximum_coordinates() → tuple[float, float][source]#

Slowness and azimuth at the grid maximum.

Returns:

slowness, azimuth (float) -- Apparent slowness in s/km and azimuth in degrees at the point of maximum value.

class covseisnet.slowness.PlaneWaveDelays(stats: list[Stats], slowness_max: float, n_slowness: int, n_azimuth: int)[source]#

Bases: SlownessGrid

Time delays of a plane wave at each station over the slowness grid.

For a plane wave with Cartesian slowness components \((u_x, u_y) = s(\sin\theta, \cos\theta)\) the delay at station \(i\) located at flat-Earth coordinates \((x_i, y_i)\) is

\[\tau_i(u_x, u_y) = u_x\, x_i + u_y\, y_i\]

This object stores the full delay tensor of shape (n_stations, n_slowness, n_azimuth) as the delays attribute. The underlying SlownessGrid data array is unused (filled with NaN) and serves only as a container for the grid metadata.

Station coordinates are computed with station_local_coordinates().

Parameters:

  • stats (list of Stats) -- Stats objects of the network stations. Each must have a coordinates attribute with longitude and latitude keys.

  • slowness_max (float) -- Maximum apparent slowness in s/km.

  • n_slowness (int) -- Number of slowness samples (from 0 to slowness_max).

  • n_azimuth (int) -- Number of azimuth samples over \([0°, 360°)\).

delays#

Delay tensor of shape (n_stations, n_slowness, n_azimuth) in seconds.

Type:

numpy.ndarray

stats#

The input stats list.

Type:

list of Stats

Example

Compute the delays for a 5-station array and print the shape:

>>> import covseisnet as csn
>>> stream = csn.read("docs/source/data/undervolc.mseed")
>>> stream.assign_coordinates("docs/source/data/undervolc.xml")
>>> stats = [tr.stats for tr in stream]
>>> from covseisnet.slowness import PlaneWaveDelays
>>> delays = PlaneWaveDelays(stats, slowness_max=0.5, n_slowness=50, n_azimuth=72)
>>> print(delays.delays.shape)
(15, 50, 72)
Parameters:

  • stats (list of Stats) -- Stats objects of the network stations.

  • slowness_max (float) -- Maximum apparent slowness in s/km.

  • n_slowness (int) -- Number of slowness samples.

  • n_azimuth (int) -- Number of azimuth samples.