Boiling Flow Utilities

Boiling Flow Utilities#

Functions#

Functions:

ft2(data[, scale])

Use FFT-shifts to take the 2-D FFT of data.

ift2(data[, scale])

Use FFT-shifts to take the inverse 2-D FFT of data.

remove_ttp(input_data)

Remove the tip, tilt, and piston (TTP) components from a phase screen or time-series of phase screens.

parabolic_interpolation_2d(x_vals, y_vals, ...)

Fit a 2-D parabola to a 3x3 grid of values centered at the maximum of a discrete 2-D array.

parabolic_interpolation_1d(input_vals, ...)

Fit a 1-D parabola to a three values centered at the maximum of a discrete array.

extract_largest_square(input_data[, mask])

Extracts the largest even-length square sub-array from an input 3-D array according to a mask.

img_to_vec(image_data, mask)

Converts from a 2-D array (an "image") to a row vector in raster order, using a boolean array called a "mask" that indicates the pixels in the image which should be included in the vector.

structure_function_2d(data_values[, mask, ...])

Estimate a generalized quasi-homogeneous Kolmogorov spatial structure function of an input time-series of 2-D data.
boiling_flow._utils.extract_largest_square(input_data, mask=None)[source]#

Extracts the largest even-length square sub-array from an input 3-D array according to a mask.

Parameters:

  • input_data (ndarray) – numpy 3-D array of shape (num_time_steps, M, N) containing the input data values

  • mask (ndarray, optional) – [Default=None] numpy boolean 2-D array of shape (M, N) indicating which values at each time-step of ‘input_data’ to allow in the square.

    • If set to None, all values are allowed.

Returns:

*square_data (ndarray)* – numpy 3-D array of shape (num_time_steps, K, K) containing the largest even-length square (length K) that can be extracted from an input 3-D array.

boiling_flow._utils.ft2(data, scale=1.0)[source]#

Use FFT-shifts to take the 2-D FFT of data. Adapted from [1].

Parameters:

  • data (ndarray) – numpy 2-D or 3-D array of shape (N, N) or (num_time_steps, N, N) containing the data to take the Fourier transform of

  • scale (float, optional) – [Default = 1] scale of the FFT

Returns:

scaled_fourier_transform (ndarray) – numpy 2-D or 3-D array of shape (N, N) or (num_time_steps, N, N) containing the FFT of the data

boiling_flow._utils.ift2(data, scale=1.0)[source]#

Use FFT-shifts to take the inverse 2-D FFT of data. Adapted from [1].

Parameters:

  • data (ndarray) – numpy 2-D or 3-D array of shape (N, N) or (num_time_steps, N, N) containing the data to take the inverse Fourier transform of

  • scale (float, optional) – [Default = 1] scale of the inverse FFT

Returns:

scaled_inverse_fourier_transform (ndarray) – numpy 2-D or 3-D array of shape (N, N) or (num_time_steps, N, N) containing the inverse FFT of the data

boiling_flow._utils.img_to_vec(image_data, mask)[source]#

Converts from a 2-D array (an “image”) to a row vector in raster order, using a boolean array called a “mask” that indicates the pixels in the image which should be included in the vector. The function can convert either a single image to a single vector or a 3-D array (containing a sequence of images) to a sequence of rows vectors (i.e., to the rows of a 2-D array).

Parameters:

  • image_data (ndarray) – numpy 2-D or 3-D array containing the image pixel values.

    • If image_data is 2-D, a single image is converted to a single vector. In this case, the input must have

      shape (image height, image width).

    • If image_data is 3-D, a sequence of images is converted to a sequence of row vectors. In this case, the

      input must have shape (number of images, image height, image width).

  • mask (ndarray) – numpy 2-D boolean array of shape (image height, image width) indicating which 2-D data indices to include in the output vector(s).

Returns:

output_vec (ndarray) – numpy 1-D or 2-D array with the (flattened) image pixel values. If “image_data” is 2-D, only a single 1-D array is returned. If “image_data” is 3-D, a 2-D array of shape (number of images, image dimensionality) is returned.

boiling_flow._utils.parabolic_interpolation_1d(input_vals, function_values)[source]#

Fit a 1-D parabola to a three values centered at the maximum of a discrete array.

Parameters:

  • input_vals (ndarray) – numpy 1-D array of shape (3,) containing the function inputs, centered at maximal index

  • function_values (ndarray) – numpy 1-D array of shape (3,) containing the function values centered at the maximum value.

Returns:

  • maximal_input (float) – interpolated input at the maximum value

  • max_val (float) – interpolated maximum value

boiling_flow._utils.parabolic_interpolation_2d(x_vals, y_vals, function_values)[source]#

Fit a 2-D parabola to a 3x3 grid of values centered at the maximum of a discrete 2-D array.

Parameters:

  • x_vals (ndarray) – numpy 1-D array of shape (3,) containing x-values centered at maximal x-index

  • y_vals (ndarray) – numpy 1-D array of shape (3,) containing y-values centered at maximal y-index

  • function_values (ndarray) – numpy 2-D array of shape (3, 3) containing the function values centered at the maximum value.

Returns:

  • x_max (float) – interpolated x-coordinate of the maximum value

  • y_max (float) – interpolated y-coordinate of the maximum value

  • max_val (float) – interpolated maximum value

boiling_flow._utils.remove_ttp(input_data)[source]#

Remove the tip, tilt, and piston (TTP) components from a phase screen or time-series of phase screens.

Parameters:

input_data (ndarray, float) – numpy 2-D or 3-D array of shape (N, N) or (num_time_steps, N, N) containing the phase screen(s)

Returns:

phase_screen_ttp_removed (ndarray) – numpy 2-D or 3-D array of shape (N, N) or (num_time_steps, N, N) containing the TTP-removed phase screen(s)

boiling_flow._utils.structure_function_2d(data_values, mask=None, compute_square_root=False)[source]#

Estimate a generalized quasi-homogeneous Kolmogorov spatial structure function of an input time-series of 2-D data. The spatial structure function values are the (estimated) mean-squared differences of the input array “data” values at pairs of 2-D spatial locations. While the standard structure function computes these values as a function just the of relative separation (or the pixel distance between two spatial locations), the anisotrpic structure function depends on two variables: the relative separation and the angle of the difference between the two spatial locations.

Parameters:

  • data_values (ndarray) – numpy 3-D array of shape (number of images, image height, image width) containing the data from which we would like to calculate turbulence structure function values.

  • mask (ndarray, optional) – [Default=None] numpy 2-D boolean array of shape (image height, image width) indicating which 2-D data indices correspond to valid pixel values.

    • If set to None, the function infers the mask based on which data values are “nan.”

  • compute_square_root (bool, optional) – [Default=False] choice of whether to compute (and return) the square root of the structure function values (instead of the structure function values themselves)

Returns:

  • structure_function_inputs (ndarray) – numpy 2-D array of shape (number of inputs, 2) containing each (relative separation, angle) input to the structure function.

  • structure_function (ndarray) – numpy 1-D array of shape (number of inputs,) containing the estimated structure function values (in the same order as the first output).

Disclaimer: Approved for public release; distribution is unlimited. Public Affairs release approval # AFRL-2025-5580.