API

beampower.beampower.beamform(waveform_features, time_delays, weights_phases, weights_sources, device='cpu', reduce='max', mode='direct', out_of_bounds='strict', num_threads=None)[source]

Compute the beamformed network response.

This routine computes and returns the whole network response over the entire duration of waveform_features. Thus, if the input source grid is large, the output might be considerably memory-consuming. Therefore, this routine is more appropriate for small scale studies such as the rupture imaging of an earthquake.

Parameters:

  • waveform_features ((n_stations, n_channels, n_samples) numpy.ndarray, float) – Any characterization function computed from the continuous seismograms.

  • time_delays ((n_sources, n_stations, n_phases) numpy.ndarray, int) – Moveouts, in samples, from each of the n_sources theoretical sources to each of the n_stations seismic stations and for the n_phases back-projected seismic phases.

  • weights_phases ((n_stations, n_channels, n_phases) numpy.ndarray, float) – Weight given to each station and channel for a given phase. For example, horizontal components might be given a small or zero weight for the P-wave stacking.

  • weights_sources ((n_sources, n_stations) numpy.ndarray, float) – Source-receiver-specific weights. For example, based on the source-receiver distance.

  • device (string, default to 'cpu') – Either ‘cpu’ or ‘gpu’, depending on the available hardware and user’s preferences.

  • reduce (string, default to 'max') – Reduction operation applied to the beamformed network response. If reduce is ‘max’, return the maximum network response of the grid at each time step, as well as the source indexes. If reduce is ‘none’, None or ‘None’, return the full beamformed network response.

  • mode (string, default to 'direct') – Either ‘direct’ (default) or ‘differential’. If ‘direct’, the time delays are the (relative) source-receiver propagation times. If ‘differential’, the time delays are the inter-station differential propagation times. The latter requires waveform_features to be based on inter-station cross-correlations.

  • out_of_bounds (string, default to 'strict') –

    Either ‘strict’ (default) or ‘flexible’.

    • ’strict’: A beam is computed if and only if the moveouts point to a valid sample (that is, within the bounds of the data stream) for every channel used in the beam.

    • ’flexible’: A beam is computed as long as the moveouts point to a valid sample for at least one channel. This option is particularly useful for real time applications where an event might have been recorded at the closest stations but not yet at the more distant ones.

  • num_threads (int or None) – Number of threads for CPU parallelization. If None, uses one thread per available (visible) CPU.

Returns:

  • beam ((n_sources, n_samples) or (n_samples,) numpy.ndarray, float) – Full network response (n_sources, n_samples) or maximum network response (n_samples,). See reduce.

  • beam_argmax ((n_samples,) numpy.ndarray, int, optional) – If reduce is ‘max’, return the maximum network response source indexes.

beampower.beampower.prestack_traces(waveform_features, weights_phases, num_threads=None, device='cpu')[source]

Prestack the detection traces ahead of the beamforming.

Channel-wise stacking for each target seismic phase can be done once and for all at the beginning of the computation.

Parameters:

  • waveform_features ((n_stations, n_channels, n_stations) numpy.ndarray, float) – Any characterization function computed from the continuous seismograms.

  • weights_phases ((n_stations, n_channels, n_phases) numpy.ndarray, float) – Weight given to each station and channel for a given phase. For example, horizontal components might be given a small or zero weight for the P-wave stacking.

  • device (string, default to 'cpu') – Either ‘cpu’ or ‘gpu’, depending on the available hardware and user’s preferences.

  • num_threads (int or None) – Number of threads for CPU parallelization. If None, uses one thread per available (visible) CPU.

Returns:

prestacked_traces – Channel-wise stacked detection traces, optimally formatted for the C CUDA-C routines.

Return type:

(n_stations, n_samples, n_phases) numpy.ndarray, float