API Documentation

Structure function calculation package. This package calculates structure functions from ocean velocity data.

fluidsf.bin_data(dd, sf, nbins)

Bins the data based on the separation distances and calculates the bin-averaged structure functions.

Parameters:

  • dd (array-like) – The separation distances to be binned.

  • sf (array-like) – The structure functions that will be bin-averaged.

  • nbins (int) – The number of bins to create.

Returns:

A tuple containing the binned separation distances and the bin-averaged structure functions.

Return type:

tuple

fluidsf.calculate_advection_2d(u, v, x, y, dx=None, dy=None, grid_type='uniform', scalar=None)

Calculate the advection for a velocity field or scalar field. The velocity field will return advection components in the x and y directions. The scalar field will return the scalar advection. Defaults to advection for velocity field. If the velocity advection is skipped or a scalar field is not provided, the relevant dictionary key will return None.

Parameters:

  • u (ndarray) – The u-component of velocity.

  • v (ndarray) – The v-component of velocity.

  • x (ndarray) – The x-coordinates of the grid.

  • y (ndarray) – The y-coordinates of the grid.

  • dx (float or ndarray, optional) – The grid spacing in the x-direction. Defaults to None.

  • dy (float or ndarray, optional) – The grid spacing in the y-direction. Defaults to None.

  • grid_type (str, optional) – The type of grid. Defaults to “uniform”.

  • scalar (ndarray, optional) – Array of scalar values. Defaults to None.

Returns:

A tuple of advection components (x and y) if scalar is not provided, otherwise returns an ndarray of scalar advection.

Return type:

tuple or ndarray

fluidsf.calculate_advection_3d(u, v, w, x, y, z, scalar=None)

Calculate the advection for a velocity field or scalar field. The velocity field will return advection components in the x, y, and z directions. The scalar field will return the scalar advection. Defaults to advection for velocity field. If the velocity advection is skipped or a scalar field is not provided, the relevant dictionary key will return None.

Parameters:

  • u (ndarray) – The u-component of velocity.

  • v (ndarray) – The v-component of velocity.

  • w (ndarray) – The w-component of velocity.

  • x (ndarray) – The x-coordinates of the grid.

  • y (ndarray) – The y-coordinates of the grid.

  • z (ndarray) – The z-coordinates of the grid.

  • scalar (ndarray, optional) – Array of scalar values. Defaults to None.

Returns:

A tuple of advection components (x, y, z) if scalar is not provided, otherwise returns an ndarray of scalar advection.

Return type:

tuple or ndarray

fluidsf.calculate_separation_distances(x, y, x_shift, y_shift, grid_type='uniform')

Calculate the separation distances between two points.

Parameters:

  • x (float) – The x-coordinate of the first point.

  • y (float) – The y-coordinate of the first point.

  • x_shift (float) – The x-coordinate of the second point.

  • y_shift (float) – The y-coordinate of the second point.

  • grid_type (str) – The type of grid used for the coordinates. A uniform grid results in a simple distance calculation, but a latlon grid uses geopy’s great_circle function to estimate the distance in meters. Defaults to “uniform”.

Returns:

A tuple containing the x and y separation distances. Either in meters in the case of a latlon grid or code units for a uniform grid

Return type:

tuple

fluidsf.calculate_separation_distances_3d(x, y, z, x_shift, y_shift, z_shift)

Calculate the separation distances between two points.

Parameters:

  • x (float) – The x-coordinate of the first point.

  • y (float) – The y-coordinate of the first point.

  • z (float) – The z-coordinate of the first point.

  • x_shift (float) – The x-coordinate of the second point.

  • y_shift (float) – The y-coordinate of the second point.

  • z_shift (float) – The z-coordinate of the second point.

Returns:

A tuple containing the x, y, and z separation distances. In code units for a uniform grid.

Return type:

tuple

fluidsf.calculate_sf_maps_2d(u, v, x, y, adv_x, adv_y, shift_in_x, shift_in_y, sf_type, scalar=None, adv_scalar=None)

Calculate structure function, either advective or traditional. Supports velocity-based structure functions and scalar-based structure functions. Can only be used with periodic, evenly-spaced data.

Parameters:

  • u (ndarray) – Array of u velocities.

  • v (ndarray) – Array of v velocities.

  • x (ndarray) – 1D array of x-coordinates.

  • y (ndarray) – 1D array of y-coordinates.

  • adv_x (ndarray) – Array of x-dir advection values.

  • adv_y (ndarray) – Array of y-dir advection values.

  • shift_in_x (int) – Shift amount for x shift.

  • shift_in_y (int) – Shift amount for y shift.

  • sf_type (list) – List of structure function types to calculate. Accepted types are: “ASF_V”, “ASF_S”, “LL”, “TT”, “SS”, “LLL”, “LTT”, “LSS”.

  • scalar (ndarray, optional) – Array of scalar values. Defaults to None.

  • adv_scalar (ndarray, optional) – Array of scalar advection values. Defaults to None.

Returns:

A dictionary containing the advection velocity structure functions and scalar structure functions (if applicable). The dictionary has the following keys:

’SF_advection_velocity_xy’: The advection velocity structure function for separation vectors in the x-y plane. ‘SF_advection_scalar_xy’: The scalar advective structure function for separation vectors in the x-y plane. ‘SF_LL_xy’: The traditional structure function LL for separation vectors in the x-y plane. ‘SF_TT_xy’: The traditional structure function TT for separation vectors in the x-y plane. ‘SF_SS_xy’: The traditional structure function SS for separation vectors in the x-y plane. ‘SF_LLL_xy’: The traditional structure function LLL for separation vectors in the x-y plane.. ‘SF_LTT_xy’: The traditional structure function LTT for separation vectors in the x-y plane. ‘SF_LSS_xy’: The traditional structure function LSS for separation vectors in the x-y plane.

Return type:

dict

fluidsf.calculate_structure_function_1d(u, sep_id, sf_type, v=None, scalar=None, boundary='Periodic')

Calculate traditional structure functions for 1D data. Supports velocity-based structure functions and scalar-based structure functions. Defaults to calculating the third-order longitudinal velocity structure function (‘LLL’) along the data track.

Parameters:

  • u (ndarray) – Array of u velocities.

  • sep_id (ndarray) – Array of separation distances.

  • sf_type (list) – List of traditional structure function types to calculate. Accepted types are: “LL”, “TT”, “SS”, “LLL”, “LTT”, “LSS”. Defaults to “LLL”. If you include “SS” or “LSS”, you must provide a 1D array for scalar.

  • v (ndarray) – Array of v velocities. Defaults to None.

  • scalar (ndarray, optional) – Array of scalar values. Defaults to None.

  • boundary (str, optional) – Boundary condition for shifting arrays. Defaults to “Periodic”. Set to None if no boundary conditions.

Returns:

A dictionary containing the velocity structure functions and scalar structure functions (if applicable). The dictionary has the following keys:

’SF_LL’: The second-order longitudinal velocity structure function. ‘SF_TT’: The second-order transverse velocity structure function. ‘SF_SS’: The second-order scalar structure function. ‘SF_LLL’: The third-order longitudinal velocity structure function. ‘SF_LTT’: The longitudinal-transverse velocity structure function. ‘SF_LSS’: The longitudinal-scalar structure function.

Return type:

dict

fluidsf.calculate_structure_function_2d(u, v, adv_x, adv_y, shift_x, shift_y, sf_type, scalar=None, adv_scalar=None, boundary='periodic-all')

Calculate structure function, either advective or traditional. Supports velocity-based structure functions and scalar-based structure functions.

Parameters:

  • u (ndarray) – Array of u velocities.

  • v (ndarray) – Array of v velocities.

  • adv_x (ndarray) – Array of x-dir advection values.

  • adv_y (ndarray) – Array of y-dir advection values.

  • shift_x (int) – Shift amount for x shift.

  • shift_y (int) – Shift amount for y shift.

  • sf_type (list) – List of structure function types to calculate. Accepted types are: “ASF_V, “ASF_S”, “LL”, “TT”, “SS”, “LLL”, “LTT”, “LSS”. Defaults to “ASF_V”.

  • scalar (ndarray, optional) – Array of scalar values. Defaults to None.

  • adv_scalar (ndarray, optional) – Array of scalar advection values. Defaults to None.

  • boundary (str, optional) – Boundary condition for shifting arrays. Accepted strings are “periodic-x”, “periodic-y”, and “periodic-all”. Defaults to “periodic-all”.

Returns:

A dictionary containing the advection velocity structure functions and scalar structure functions (if applicable). The dictionary has the following keys:

’SF_advection_velocity_x’: The advection velocity structure function in the x direction. ‘SF_advection_velocity_y’: The advection velocity structure function in the y direction. ‘SF_advection_scalar_x’: The scalar structure function in the x direction. ‘SF_advection_scalar_y’: The scalar structure function in the y direction. ‘SF_LL_x’: The traditional structure function LL in the x direction. ‘SF_LL_y’: The traditional structure function LL in the y direction. ‘SF_TT_x’: The traditional structure function TT in the x direction. ‘SF_TT_y’: The traditional structure function TT in the y direction. ‘SF_SS_x’: The traditional structure function SS in the x direction. ‘SF_SS_y’: The traditional structure function SS in the y direction. ‘SF_LLL_x’: The traditional structure function LLL in the x direction. ‘SF_LLL_y’: The traditional structure function LLL in the y direction. ‘SF_LTT_x’: The traditional structure function LTT in the x direction. ‘SF_LTT_y’: The traditional structure function LTT in the y direction. ‘SF_LSS_x’: The traditional structure function LSS in the x direction. ‘SF_LSS_y’: The traditional structure function LSS in the y direction.

Return type:

dict

fluidsf.calculate_structure_function_3d(u, v, w, adv_x, adv_y, adv_z, shift_x, shift_y, shift_z, sf_type, scalar=None, adv_scalar=None, boundary='periodic-all')

Calculate structure function, either advective or traditional. Supports velocity-based structure functions and scalar-based structure functions.

Parameters:

  • u (ndarray) – Array of u velocities.

  • v (ndarray) – Array of v velocities.

  • w (ndarray) – Array of w velocities.

  • adv_x (ndarray) – Array of x-dir advection values.

  • adv_y (ndarray) – Array of y-dir advection values.

  • adv_z (ndarray) – Array of z-dir advection values.

  • shift_x (int) – Shift amount for x shift.

  • shift_y (int) – Shift amount for y shift.

  • shift_z (int) – Shift amount for z shift.

  • sf_type (list) – List of structure function types to calculate. Accepted types are: “ASF_V, “ASF_S”, “LL”, “TT”, “SS”, “LLL”, “LTT”, “LSS”. Defaults to “ASF_V”.

  • scalar (ndarray, optional) – Array of scalar values. Defaults to None.

  • adv_scalar (ndarray, optional) – Array of scalar advection values. Defaults to None.

  • boundary (str, optional) – Boundary condition for shifting arrays. Accepted strings are “periodic-x”, “periodic-y”, “periodic-z” and “periodic-all”. Defaults to “periodic-all”.

Returns:

A dictionary containing the velocity-based advective structure functions and scalar structure functions (if applicable). The dictionary has the following keys:

’SF_velocity_x’: The velocity-based advective structure function in the x direction. ‘SF_velocity_y’: The velocity-based advective structure function in the y direction. ‘SF_velocity_z’: The velocity-based advective structure function in the z direction. ‘SF_scalar_x’: The scalar-based advective structure function in the x direction. ‘SF_scalar_y’: The scalar-based advective structure function in the y direction. ‘SF_scalar_z’: The scalar-based advective structure function in the z direction. ‘SF_LL_x’: The traditional structure function LL in the x direction. ‘SF_LL_y’: The traditional structure function LL in the y direction. ‘SF_LL_z’: The traditional structure function LL in the z direction. ‘SF_TT_x’: The traditional structure function TT in the x direction. ‘SF_TT_y’: The traditional structure function TT in the y direction. ‘SF_TT_z’: The traditional structure function TT in the z direction. ‘SF_SS_x’: The traditional structure function SS in the x direction. ‘SF_SS_y’: The traditional structure function SS in the y direction. ‘SF_SS_z’: The traditional structure function SS in the z direction. ‘SF_LLL_x’: The traditional structure function LLL in the x direction. ‘SF_LLL_y’: The traditional structure function LLL in the y direction. ‘SF_LLL_z’: The traditional structure function LLL in the z direction. ‘SF_LTT_x’: The traditional structure function LTT in the x direction. ‘SF_LTT_y’: The traditional structure function LTT in the y direction. ‘SF_LTT_z’: The traditional structure function LTT in the z direction. ‘SF_LSS_x’: The traditional structure function LSS in the x direction. ‘SF_LSS_y’: The traditional structure function LSS in the y direction. ‘SF_LSS_z’: The traditional structure function LSS in the z direction.

Return type:

dict

fluidsf.generate_sf_maps_2d(u, v, x, y, sf_type=['ASF_V'], scalar=None, dx=None, dy=None, grid_type='uniform')

Full method for generating 2D maps of structure functions for 2D data, either advective or traditional structure functions. Supports velocity-based and scalar-based structure functions. Defaults to calculating the velocity-based advective structure functions for the x and y directions. Can only be used with evenly-spaced and periodic data.

Parameters:

  • u (ndarray) – 2D array of u velocity components.

  • v (ndarray) – 2D array of v velocity components.

  • x (ndarray) – 1D array of x-coordinates.

  • y (ndarray) – 1D array of y-coordinates.

  • sf_type (list) – List of structure function types to calculate. Accepted types are: “ASF_V”, “ASF_S”, “LL”, “TT”, “SS”, “LLL”, “LTT”, “LSS”. Defaults to [“ASF_V”].

  • scalar (ndarray, optional) – 2D array of scalar values. Defaults to None.

  • dx (float, optional) – Grid spacing in the x-direction. Defaults to None.

  • dy (float, optional) – Grid spacing in the y-direction. Defaults to None.

  • grid_type (str, optional) – Type of grid, can only be “uniform” for these maps.

Returns:

Dictionary containing the requested structure functions and separation distances for the x- and y-directions.

Return type:

dict

fluidsf.generate_structure_functions_1d(u, x, sf_type=['LLL'], v=None, y=None, scalar=None, dx=None, boundary='Periodic', grid_type='uniform', nbins=None)

Full method for generating traditional structure functions for 1D data. Supports velocity-based and scalar-based structure functions. Defaults to calculating the third-order velocity structure function (‘LLL’) along the data track.

Parameters:

  • u (ndarray) – 1D array of u velocity components.

  • x (ndarray) – 1D array of coordinates. If you have lat-lon data, set x to 1D array of latitudes.

  • sf_type (list) – List of structure function types to calculate. Accepted types are: “LL”, “TT”, “SS”, “LLL”, “LTT”, “LSS”. Defaults to “LLL”. If you include “SS” or “LSS”, you must provide a 1D array for scalar.

  • v (ndarray) – 1D array of v velocity components. Defaults to None.

  • y (ndarray, optional) – 1D array of coordinates orthogonal to x. Defaults to None. If you have lat-lon data, set y to 1D array of longitudes.

  • scalar (ndarray, optional) – 1D array of scalar values. Defaults to None.

  • dx (float, optional) – Grid spacing along the data track. Defaults to None.

  • boundary (str, optional) – Boundary condition of the data. Defaults to “Periodic”. Set to None if no boundary conditions.

  • grid_type (str, optional) – Type of grid, either “uniform” or “latlon”. Defaults to “uniform”.

  • nbins (int, optional) – Number of bins for binning the data. Defaults to None, i.e. does not bin data.

Returns:

Dictionary containing the requested structure functions and separation distances along the data track.

Return type:

dict

fluidsf.generate_structure_functions_2d(u, v, x, y, sf_type=['ASF_V'], scalar=None, dx=None, dy=None, boundary='periodic-all', grid_type='uniform', nbins=None)

Full method for generating structure functions for 2D data, either advective or traditional structure functions. Supports velocity-based and scalar-based structure functions. Defaults to calculating the velocity-based advective structure functions for the x and y directions.

Parameters:

  • u (ndarray) – 2D array of u velocity components.

  • v (ndarray) – 2D array of v velocity components.

  • x (ndarray) – 1D array of x-coordinates.

  • y (ndarray) – 1D array of y-coordinates.

  • sf_type (list) – List of structure function types to calculate. Accepted types are: “ASF_V, “ASF_S”, “LL”, “TT”, “SS”, “LLL”, “LTT”, “LSS”. Defaults to “ASF_V”.

  • scalar (ndarray, optional) – 2D array of scalar values. Defaults to None.

  • dx (float, optional) – Grid spacing in the x-direction. Defaults to None.

  • dy (float, optional) – Grid spacing in the y-direction. Defaults to None.

  • boundary (str, optional) – Boundary condition of the data. Accepted strings are “periodic-x”, “periodic-y”, and “periodic-all”. Defaults to “periodic-all”.

  • grid_type (str, optional) – Type of grid, either “uniform” or “latlon”. Defaults to “uniform”.

  • nbins (int, optional) – Number of bins for binning the data. Defaults to None, i.e. does not bin data.

Returns:

Dictionary containing the requested structure functions and separation distances for the x- and y-direction.

Return type:

dict

fluidsf.generate_structure_functions_3d(u, v, w, x, y, z, sf_type=['ASF_V'], scalar=None, boundary='periodic-all', nbins=None)

Full method for generating structure functions for uniform and even 3D data, either advective or traditional structure functions. Supports velocity-based and scalar-based structure functions. Defaults to calculating the velocity-based advective structure functions for the x, y, and z directions.

Parameters:

  • u (ndarray) – 3D array of u velocity components.

  • v (ndarray) – 3D array of v velocity components.

  • w (ndarray) – 3D array of w velocity components.

  • x (ndarray) – 1D array of x-coordinates.

  • y (ndarray) – 1D array of y-coordinates.

  • z (ndarray) – 1D array of z-coordinates.

  • sf_type (list) – List of structure function types to calculate. Accepted types are: “ASF_V”, “ASF_S”, “LL”, “TT”, “SS”, “LLL”, “LTT”, “LSS”. Defaults to [“ASF_V”].

  • scalar (ndarray, optional) – 3D array of scalar values. Defaults to None.

  • boundary (str, optional) – Boundary condition of the data. Accepted strings are “periodic-x”, “periodic-y”, “periodic-z”, and “periodic-all”. Defaults to “periodic-all”.

  • nbins (int, optional) – Number of bins in the structure function. Defaults to None, i.e. does not bin the data.

Returns:

Dictionary containing the requested structure functions and separation distances for the x, y, and z directions.

Return type:

dict

fluidsf.shift_array_1d(input_array, shift_by=1, boundary='Periodic')

Shifts 1D array by an integer amount and returns the shifted array. Either wraps the array or shifts and pads with NaNs.

Parameters:

  • input_array (array_like) – 1-dimensional array to be shifted.

  • shift_by (int, optional) – Shift amount for array. For periodic data should be less than len(input_array)/2 and less than len(input_array) for other boundary conditions. Defaults to 1.

  • boundary (str, optional) – Boundary condition for input array. Periodic boundary conditions will wrap the array, otherwise the array will be padded with NaNs. Defaults to “Periodic”.

Returns:

1D array shifted by requested integer amount

Return type:

shifted_array

fluidsf.shift_array_2d(input_array, shift_x=1, shift_y=1, boundary='periodic-all')

Shifts 2D array in x and y by the specified integer amounts and returns the shifted arrays. Either wraps the array or shifts and pads with NaNs.

Parameters:

  • input_array (array_like) – 2-dimensional array to be shifted.

  • shift_x (int, optional) – Shift amount in x direction. For periodic data should be less than half the row length and less than the row length for other boundary conditions. Defaults to 1.

  • shift_y (int, optional) – Shift amount in y direction. For periodic data should be less than half the column length and less than the column length for other boundary conditions. Defaults to 1.

  • boundary (str, optional) – Boundary condition for input array. Periodic boundary conditions will wrap the array, otherwise the array will be padded with NaNs. Accepted strings are “periodic-x”, “periodic-y”, and “periodic-all”. Defaults to “periodic-all”.

Returns:

  • shifted_x_array – 2D array shifted in x by the specified integer amount

  • shifted_y_array – 2D array shifted in y by the specified integer amount

fluidsf.shift_array_3d(input_array, shift_x=1, shift_y=1, shift_z=1, boundary=None)

Shifts 3D array in x/y/z by the specified integer amounts and returns the shifted arrays. Either wraps the array or shifts and pads with NaNs.

Parameters:

  • input_array (array_like) – 3-dimensional array to be shifted.

  • shift_x (int, optional) – Shift amount in x direction. For periodic data should be less than half the row length and less than the row length for other boundary conditions. Defaults to 1.

  • shift_y (int, optional) – Shift amount in y direction. For periodic data should be less than half the column length and less than the column length for other boundary conditions. Defaults to 1.

  • shift_z (int, optional) – Shift amount in z direction. For periodic data should be less than half the depth length and less than the depth length for other boundary conditions. Defaults to 1.

  • boundary (list, optional) – List of boundary conditions for input array. Periodic boundary conditions will wrap the array, otherwise the array will be padded with NaNs. Accepted strings are “periodic-x”, “periodic-y”, “periodic-z”, and “periodic-all”. Defaults to “periodic-all”.

Returns:

  • shifted_x_array – 3D array shifted in x by the specified integer amount

  • shiftedy_array – 3D array shifted in y by the specified integer amount

  • shifted_z_array – 3D array shifted in z by the specified integer amount

fluidsf.shift_array_xy(input_array, x_shift=0, y_shift=0)

Wrap 2D array in x and y by the specified integer amounts and returns the shifted arrays. Only works with 2D, doubly-periodic data on an even grid.

Parameters:

  • input_array (array_like) – 2-dimensional array to be shifted.

  • shift_x (int, optional) – Shift amount for x shift.

  • shift_y (int, optional) – Shift amount for y shift.

Returns:

2D array shifted in the x-y directions by the specified integer amount

Return type:

shifted_xy_array