kwave.utils.signals module

add_noise(signal, snr, mode='rms')

Add Gaussian noise to a signal.

Parameters:

• signal (ndarray) – input signal

• snr (float) – desired signal snr (signal-to-noise ratio) in decibels after adding noise

• mode – ‘rms’ (default) or ‘peak’

Returns:

Signal with augmented with noise. This behaviour differs from the k-Wave MATLAB implementation in that the SNR is nor returned.

calc_max_freq(max_spat_freq, c)

create_cw_signals(t_array, freq, amp, phase, ramp_length=4)

Generate a series of continuous wave (CW) signals based on the 1D or 2D input matrices amp and phase, where each signal is given by:

amp[i, j] .* sin(2 * pi * freq * t_array + phase[i, j]);

To avoid startup transients, a cosine tapered up-ramp is applied to the beginning of the signal. By default, the length of this ramp is four periods of the wave. The up-ramp can be turned off by setting the ramp_length to 0.

Examples

# define sampling parameters f = 5e6 T = 1/f Fs = 100e6 dt = 1/Fs t_array = np.arange(0, 10*T, dt)

# define amplitude and phase amp = get_win(9, ‘Gaussian’) phase = np.arange(0, 2*pi, 9).T

# create signals and plot cw_signal = create_cw_signals(t_array, f, amp, phase)

Parameters:

• t_array (ndarray) – A numpy ndarray representing the time values.

• freq (float) – A float representing the frequency of the signals.

• amp (ndarray) – A numpy ndarray representing the amplitudes of the signals.

• phase (ndarray) – A numpy ndarray representing the phases of the signals.

• ramp_length (int) – An optional integer representing the length of the cosine up-ramp in periods of the wave. Default is 4.

Returns:

A numpy ndarray containing the generated CW signals.

Return type:

ndarray

get_alpha_filter(kgrid, medium, filter_cutoff, taper_ratio=0.5)

get_alpha_filter uses get_win to create a Tukey window via rotation to pass to the medium.alpha_filter. This parameter is used to regularise time reversal image reconstruction when absorption compensation is included.

Parameters:

• kgrid – simulation grid

• medium – simulation medium

• filter_cutoff – Any of the filter_cutoff inputs may be set to ‘max’ to set the cutoff frequency to the maximum frequency supported by the grid

• taper_ratio – The taper_ratio input is used to control the width of the transition region between the passband and stopband. The default value is 0.5, which corresponds to a transition region of 50% of the filter width.

Returns:

alpha_filter

get_wave_number(Nx, dx, dim)

get_win(N, type_, plot_win=False, param=None, rotation=False, symmetric=True, square=False)

A frequency domain windowing function of specified type and dimensions.

Args:

N: Number of samples, [Nx] for 1D, [Nx, Ny] for 2D, [Nx, Ny, Nz] for 3D. type_: Window type. Supported values: ‘Bartlett’, ‘Bartlett-Hanning’, ‘Blackman’, ‘Blackman-Harris’,

‘Blackman-Nuttall’, ‘Cosine’, ‘Flattop’, ‘Gaussian’, ‘HalfBand’, ‘Hamming’, ‘Hanning’, ‘Kaiser’, ‘Lanczos’, ‘Nuttall’, ‘Rectangular’, ‘Triangular’, ‘Tukey’.

plot_win: Boolean to display the window (default = False). param: Control parameter for Tukey, Blackman, Gaussian, and Kaiser windows: taper ratio (Tukey),

alpha (Blackman, Kaiser), standard deviation (Gaussian) (default = 0.5, 0.16, 3 respectively).

rotation: Boolean to create windows via rotation or outer product (default = False). symmetric: Boolean to make the window symmetrical (default = True).

Can also be a vector defining the symmetry in each matrix dimension.

square: Boolean to force the window to be square (default = False).

Returns:

A tuple of (win, cg) where win is the window and cg is the coherent gain of the window.

Parameters:

• N (int | ndarray | tuple[int, int] | tuple[int, int, int] | list[Int[ndarray, ' '] | number | int])

• type_ (str)

• plot_win (bool)

• param (float | None)

• rotation (bool)

• symmetric (bool | Bool[ndarray, 'N'])

• square (bool)

gradient_spect(f, dn, dim=None, deriv_order=1)

gradient_spect calculates the gradient of an n-dimensional input matrix using the Fourier collocation spectral method. The gradient for singleton dimensions is returned as 0.

Parameters:

• f (ndarray) – A numpy ndarray representing the input matrix.

• dn (list[float]) – A list of floats representing the grid spacings in each dimension.

• dim (int | list[int] | None) – An optional integer or list of integers representing the dimensions along which to calculate the gradient.

• deriv_order (int) – An integer representing the order of the derivative to calculate. Default is 1.

Returns:

A numpy ndarray containing the calculated gradient.

Return type:

ndarray

reorder_binary_sensor_data(sensor_data, reorder_index)

Parameters:

• sensor_data (ndarray) – N x K

• reorder_index (ndarray) – N

Returns:

reordered sensor data

reorder_sensor_data(kgrid, sensor, sensor_data)

Reorders the sensor data based on the coordinates of the sensor points.

Parameters:

• kgrid – The k-Wave grid object.

• sensor – The k-Wave sensor object.

• sensor_data (ndarray) – The sensor data to be reordered.

Returns:

np.ndarray of the reordered sensor data.

Raises:

ValueError – If the simulation is not 2D or the sensor is not defined as a binary mask.

Return type:

ndarray

tone_burst(sample_freq, signal_freq, num_cycles, envelope='Gaussian', plot_signal=False, signal_length=0, signal_offset=0)

Create an enveloped single frequency tone burst.

Parameters:

• sample_freq – sampling frequency in Hz

• signal_freq – frequency of the tone burst signal in Hz

• num_cycles – number of sinusoidal oscillations

• envelope –

  Envelope used to taper the tone burst. Valid inputs are: - ‘Gaussian’ (the default) - ‘Rectangular’ - [num_ring_up_cycles, num_ring_down_cycles]

  The last option generates a continuous wave signal with a cosine taper of the specified length at the beginning and end.

• plot – Boolean controlling whether the created tone burst is plotted.

• signal_length – Signal length in number of samples. If longer than the tone burst length, the signal is appended with zeros.

• signal_offset – Signal offset before the tone burst starts in number of samples. If an array is given, a matrix of tone bursts is created where each row corresponds to a tone burst for each value of the ‘SignalOffset’.

Returns:

created tone burst

unmask_sensor_data(kgrid, sensor, sensor_data)

Parameters:

sensor_data (ndarray)

Return type:

ndarray