kwave.utils.math module

Rx(theta)[source]

Create a rotation matrix for rotation about the x-axis.

Parameters:

theta (float) – Rotation angle in degrees

Returns:

3x3 rotation matrix

Return type:

ndarray

Ry(theta)[source]

Create a rotation matrix for rotation about the y-axis.

Parameters:

theta (float) – Rotation angle in degrees

Returns:

3x3 rotation matrix

Return type:

ndarray

Rz(theta)[source]

Create a rotation matrix for rotation about the z-axis.

Parameters:

theta (float) – Rotation angle in degrees

Returns:

3x3 rotation matrix

Return type:

ndarray

compute_linear_transform(pos1, pos2, offset=None)[source]

Compute linear transformation between two 3D points.

This function computes the linear transformation that maps a vector pointing from pos1 to pos2 into the canonical direction [0, 0, -1].

Parameters:

  • pos1 – Starting position (3D point)

  • pos2 – Ending position (3D point)

  • offset – Offset vector (3D point)

Returns:

  • 3x3 rotation matrix

Return type:

Tuple containing

compute_rotation_between_vectors(start_pos, end_pos)[source]

Compute rotation matrix between two 3D points.

Parameters:

  • start_pos (ndarray) – Starting position vector

  • end_pos (ndarray) – Ending position vector

Returns:

  • 3x3 rotation matrix

  • Normalized direction vector

Return type:

Tuple containing

cosd(angle_in_degrees)[source]

Compute cosine of angle in degrees.

find_closest(A, a)[source]

Returns the value and index of the item in A that is closest to the value a.

This function finds the value and index of the item in the input array A that is closest to the given value a. For vectors, the value and index correspond to the closest element in A. For matrices, value and index are row vectors corresponding to the closest element from each column. For N-D arrays, the function finds the closest value along the first matrix dimension (singleton dimensions are removed before the search). If there is more than one element with the closest value, the index of the first one is returned.

Parameters:

  • A (ndarray) – The array to search.

  • a (float | int) – The value to find.

Returns:

A tuple containing the value and index of the closest element in A to a.

Return type:

Tuple[float | int, Tuple[int, …]]

fourier_shift(data, shift, shift_dim=None)[source]

Wrapper for phase_shift_interpolate. See its documentation for details.

Parameters:

  • data (ndarray)

  • shift (float)

  • shift_dim (int | None)

Return type:

ndarray

gaussian(x, magnitude=None, mean=0, variance=1)[source]

Returns a Gaussian distribution f(x) with the specified magnitude, mean, and variance. If these values are not specified, the magnitude is normalised and values of variance = 1 and mean = 0 are used. For example running:

import matplotlib.pyplot as plt x = np.arange(-3, 0.05, 3) plt.plot(x, gaussian(x))

will plot a normalised Gaussian distribution.

Note, the full width at half maximum of the resulting distribution can be calculated by FWHM = 2 * sqrt(2 * log(2) * variance).

Parameters:

  • x (int | float | ndarray) – The input values.

  • magnitude (int | float | None) – Bell height. Defaults to normalised.

  • mean (float | None) – Mean or expected value. Defaults to 0.

  • variance (float | None) – Variance, or bell width. Defaults to 1.

Returns:

A Gaussian distribution.

Return type:

int | float | ndarray

get_affine_matrix(translation, rotation, seq='xyz')[source]
Parameters:

  • translation (Vector)

  • rotation (float | List[float])

  • seq (str)

Return type:

ndarray

largest_prime_factor(n)[source]

Finds the largest prime factor of a positive integer.

Parameters:

n (int) – The positive integer to be factored.

Returns:

The largest prime factor of n.

Return type:

int

make_affine(translation, rotation, seq='xyz')[source]

Create an affine transformation matrix combining rotation and translation. Uses scipy.spatial.transform.Rotation internally.

Parameters:

  • translation (Vector) – [dx, dy] or [dx, dy, dz]

  • rotation (float | List[float]) – Single angle (degrees) for 2D or list of angles for 3D

  • seq (str) – Rotation sequence for 3D (default: ‘xyz’)

Returns:

3x3 (2D) or 4x4 (3D) affine transformation matrix

Return type:

ndarray

Examples

# 2D transform (rotation around z-axis) T1 = make_affine([1, 2], 45)

# 3D transform with xyz Euler angles T2 = make_affine([1, 2, 3], [45, 30, 60])

# 3D transform with custom sequence T3 = make_affine([1, 2, 3], [45, 30], ‘xy’)

next_pow2(n)[source]

Calculate the next power of 2 that is greater than or equal to n.

This function takes a positive integer n and returns the smallest power of 2 that is greater than or equal to n.

Parameters:

n (int) – The number to find the next power of 2 for.

Returns:

The smallest power of 2 that is greater than or equal to n.

Return type:

int

phase_shift_interpolate(data, shift, shift_dim=None)[source]

Interpolates array data using phase shifts in the Fourier domain.

This function resamples the input data along the specified dimension using a regular grid that is offset by the non-dimensional distance shift. The resampling is performed using a Fourier interpolant.

This can be used to shift the acoustic particle velocity recorded by the first-order simulation functions to the regular (non-staggered) temporal grid by setting shift to 1/2.

Example

# Move velocity data from staggered to regular grid points v_regular = phase_shift_interpolate(v_staggered, shift=0.5)

Parameters:

  • data (ndarray) – The input array to be interpolated.

  • shift (float) – Non-dimensional shift amount, where: 0 = no shift 1/2 = shift for staggered grid 1 = full grid point

  • shift_dim (int | None) – The dimension along which to apply the phase shift. Default is highest non-singleton dimension.

Returns:

The interpolated array after applying the phase shift.

Return type:

ndarray

primefactors(n)[source]

Finds the prime factors of a given integer.

Parameters:

n (int) – The integer to factor.

Returns:

A list of prime factors of n.

Return type:

List[int]

round_even(x)[source]

Rounds to the nearest even integer.

Parameters:

x – Input value

Returns:

Nearest even integer.

round_odd(x)[source]

Rounds to the nearest odd integer.

Parameters:

x – Input value

Returns:

Nearest odd integer.

rwh_primes(n)[source]

Generates a list of prime numbers less than a given integer.

Parameters:

n (int) – The upper bound for the list of primes.

Returns:

A list of prime numbers less than n.

Return type:

List[int]

sinc(x)[source]

Calculates the sinc function of a given value or array of values.

Parameters:

x (int | float | ndarray) – The value or array of values for which to calculate the sinc function.

Returns:

The sinc function of x.

Return type:

int | float | ndarray

sind(angle_in_degrees)[source]

Compute sine of angle in degrees.