kwave.utils.mapgen module

compute_linear_transform2D(arc_pos, radius, focus_pos)

Compute a rotation matrix to transform the computed arc points to the orientation specified by the arc and focus positions

Parameters:

• arc_pos (Vector)

• radius (float)

• focus_pos (Vector)

Returns:

The rotation matrix R and an offset b

Return type:

tuple[ndarray, ndarray]

create_pixel_dim(Nx, origin_size, shift)

Create an array of pixel dimensions and a pixel size.

Parameters:

• Nx (int) – The number of pixels in the x-dimension.

• origin_size (float) – The size of the origin in the x-dimension.

• shift (float) – The shift of the pixels in the x-dimension.

Returns:

The pixel dimensions.

Return type:

tuple[ndarray, float]

fit_power_law_params(a0, y, c0, f_min, f_max, plot_fit=False)

Calculate absorption parameters that fit a power law over a given frequency range.

This function calculates the absorption parameters that should be defined in the simulation functions to achieve the desired power law absorption behavior defined by a0 and y. This takes into account the actual absorption behavior exhibited by the fractional Laplacian wave equation.

This fitting is required when using large absorption values or high frequencies, as the fractional Laplacian wave equation solved in kspaceFirstOrderND and kspaceSecondOrder no longer encapsulates absorption of the form a = a0*f^y.

The returned values should be used to define medium.alpha_coeff and medium.alpha_power within the simulation functions. The absorption behavior over the frequency range f_min:f_max will then follow the power law defined by a0 and y.

Parameters:

• a0 (float) – coefficient in the power law absorption equation

• y (float) – exponent in the power law absorption equation

• c0 (float) – speed of sound in the medium

• f_min (float) – minimum frequency in the range to fit the power law

• f_max (float) – maximum frequency in the range to fit the power law

• plot_fit (bool) – whether to plot the fit

Returns:

A tuple of the absorption coefficient and fitted exponent of the power law absorption equation.

Return type:

tuple[float, float]

focused_annulus_oneil(radius, diameter, amplitude, phase, frequency, sound_speed, density, axial_positions)

Compute axial pressure for focused annulus transducer using O’Neil’s solution

focused_annulus_oneil calculates the axial pressure for a focused annular transducer using O’Neil’s solution (O’Neil, H. Theory of focusing radiators. J. Acoust. Soc. Am., 21(5), 516-526, 1949). The annuluar elements are uniformly driven by a continuous wave sinusoid at a given frequency and normal surface velocity.

The solution is evaluated at the positions (along the beam axis) given by axial_position. Where 0 corresponds to the transducer surface.

Note, O’Neil’s formulae are derived under the assumptions of the Rayleigh integral, which are valid when the transducer diameter is large compared to both the transducer height and the acoustic wavelength.

Example

# define transducer parameters radius = 140e-3 # [m] diameter = 120e-3 # [m] velocity = 100e-3 # [m / s] frequency = 1e6 # [Hz] sound_speed = 1500 # [m / s] density = 1000 # [kg / m^3]

# define position vectors axial_position = np.arange(0, 250e-3 + 1e-4, 1e-4) # [m] p_axial = focused_annulus_oneil(radius, diameter, amplitude, phase, frequency, sound_speed, density, axial_position)

Parameters:

• radius (float) – transducer radius of curvature [m]

• diameter (Float[ndarray, 'NumElements 2'] | Float[ndarray, '2 NumElements']) – 2 x num_elements array containing pairs of inner and outer aperture diameter (diameter of opening) [m].

• amplitude (Float[ndarray, 'NumElements']) – array containing the normal surface velocities for each element [m/s]

• phase (Float[ndarray, 'NumElements']) – array containing the phase for each element [rad]

• frequency (int | float | number) – driving frequency [Hz]

• sound_speed (int | float | number) – speed of sound in the propagating medium [m/s]

• density (int | float | number) – density in the propagating medium [kg/m^3]

• axial_positions (Float[ndarray, 'Dim1'] | float | list) – vector of positions along the beam axis where the pressure amplitude is calculated [m]

Returns:

pressure amplitude at the positions specified by axial_position [Pa]

Return type:

p_axial

References

O’Neil, H. (1949). Theory of focusing radiators. J. Acoust. Soc. Am., 21(5), 516-526.

See also focused_bowl_oneil.

focused_bowl_oneil(radius, diameter, velocity, frequency, sound_speed, density, axial_positions=None, lateral_positions=None)

Calculates O’Neil’s solution for the axial and lateral pressure amplitude generated by a focused bowl transducer.

Parameters:

• radius (int | float | number) – The radius of the transducer.

• diameter (int | float | number) – The diameter of the transducer.

• velocity (int | float | number) – The normal surface velocity of the transducer.

• frequency (int | float | number) – The driving frequency of the sinusoid.

• sound_speed (int | float | number) – The sound speed in the medium.

• density (int | float | number) – The density of the medium.

• axial_positions (Float[ndarray, 'Dim1'] | float | list | None) – The positions along the beam axis where the pressure is evaluated (0 corresponds to the transducer surface). Set to [] to return only lateral pressure.

• lateral_positions (Float[ndarray, 'Dim1'] | float | list | None) – The lateral positions through the geometric focus where the pressure is evaluated (0 corresponds to the beam axis). Set to [] to return only axial pressure.

Returns:

pressure amplitude at the positions specified by axial_position [Pa] p_lateral: pressure amplitude at the positions specified by lateral_position [Pa] p_axial_complex: complex pressure amplitude at the positions specified by axial_position [Pa]

Return type:

p_axial

Example

# define transducer parameters radius = 140e-3 # [m] diameter = 120e-3 # [m] velocity = 100e-3 # [m / s] frequency = 1e6 # [Hz] sound_speed = 1500 # [m / s] density = 1000 # [kg / m ^ 3]

# define position vectors axial_position = np.arange(0, 250e-3 + 1e-4, 1e-4) # [m] lateral_position = np.arange(-15e-3, 15e-3 + 1e-4, 1e-4) # [m]

# evaluate pressure p_axial, p_lateral, p_axial_complex = focused_bowl_oneil(radius, diameter,

velocity, frequency, sound_speed, density, axial_position, lateral_position)

References

O’Neil, H. (1949). Theory of focusing radiators. J. Acoust. Soc. Am., 21(5), 516-526.

get_spaced_points(start, stop, n=100, spacing='linear')

Generate a row vector of either logarithmically or linearly spaced points between start and stop.

When spacing is set to ‘linear’, the function is identical to the inbuilt np.linspace function. When spacing is set to ‘log’, the function is similar to the inbuilt np.logspace function, except that start and stop define the start and end numbers, not decades. For logarithmically spaced points, start must be > 0. If n < 2, stop is returned.

Parameters:

• start (float) – start value for the spaced points

• stop (float) – end value for the spaced points

• n (int) – number of points to generate

• spacing (str) – type of spacing to use, either ‘linear’ or ‘log’

Returns:

row vector of spaced points

Return type:

points

Raises:

ValueError – if stop <= start or spacing is not ‘linear’ or ‘log’

make_arc(grid_size, arc_pos, radius, diameter, focus_pos)

Generates an arc shape with a given radius, diameter, and focus position.

Parameters:

• grid_size (Vector) – The size of the grid, given as a 1D array with the number of pixels in each dimension.

• arc_pos (ndarray) – The position of the arc, given as a 1D array with the coordinates in each dimension.

• radius (Real[ndarray, ' '] | number | int | float) – The radius of the arc.

• diameter (Int[ndarray, ' '] | number | int) – The diameter of the arc.

• focus_pos (Vector) – The position of the focus, given as a 1D array with the coordinates in each dimension.

Returns:

A 2D array with the arc shape.

Return type:

np.ndarray

make_ball(grid_size, ball_center, radius, plot_ball=False, binary=False)

Creates a binary map of a filled ball within a 3D grid.

Parameters:

• grid_size (Vector) – size of the 3D grid in [grid points].

• ball_center (Vector) – centre of the ball in [grid points]

• radius (int) – ball radius [grid points].

• plot_ball (bool) – whether to plot the ball using voxelPlot (default = False).

• binary (bool) – whether to return the ball map as a double precision matrix (False) or a logical matrix (True) (default = False).

Returns:

3D binary map of a filled ball.

Return type:

ball

make_bowl(grid_size, bowl_pos, radius, diameter, focus_pos, binary=False, remove_overlap=False)

Generate a matrix representing a bowl-shaped object in 3D space.

This function generates a 3D matrix representing a bowl-shaped object with the specified radius and diameter. The position of the bowl and the focus point can be specified, as well as whether to return a binary matrix or a matrix with continuous values. The optional parameter ‘remove_overlap’ can be used to remove any overlap with the surrounding grid.

Parameters:

• grid_size (Vector) – size of the grid in each dimension

• bowl_pos (Vector) – position of the bowl in the grid

• radius (int | float) – radius of the bowl

• diameter (Real[ndarray, ' '] | number | int | float) – diameter of the bowl

• focus_pos (Vector) – position of the focus point in the grid

• binary (bool) – whether to return a binary matrix

• remove_overlap (bool) – whether to remove overlap with the surrounding grid

Returns:

3D matrix representing the bowl-shaped object

Return type:

matrix

Raises:

ValueError – if any of the input arguments are outside the valid range

make_cart_arc(arc_pos, radius, diameter, focus_pos, num_points, plot_arc=False)

make_cart_arc creates a 2 x num_points array of the Cartesian coordinates of points evenly distributed over an arc. The midpoint of the arc is set by arc_pos. The orientation of the arc is set by focus_pos, which corresponds to any point on the axis of the arc (note, this must not be equal to arc_pos). It is assumed that the arc angle is equal to or less than pi radians. If the radius is set to inf, a line is generated.

Note, the first and last points do not lie on the end-points of the underlying canonical arc, but are offset by half the angular spacing between the points.

Parameters:

• arc_pos (Float[ndarray, '2']) – center of the rear surface (midpoint) of the arc given as a two element vector [bx, by] [m].

• radius (float | int) – radius of curvature of the arc [m].

• diameter (float | int) – diameter of the opening of the arc (length of line connecting arc endpoints) [m].

• focus_pos (Float[ndarray, '2']) – Any point on the beam axis of the arc given as a two element vector [fx, fy] [m].

• num_points (int) – number of points to generate along the arc.

• plot_arc (bool) – boolean flag to plot the arc.

Returns:

2 x num_points array of Cartesian coordinates of points along the arc [m].

Return type:

Float[ndarray, ‘2 NumPoints’]

make_cart_bowl(bowl_pos, radius, diameter, focus_pos, num_points, plot_bowl=False)

Create evenly distributed Cartesian points covering a bowl.

Parameters:

• bowl_pos (ndarray) – Cartesian position of the centre of the rear surface of the bowl given as a three element vector [bx, by, bz] [m].

• radius (float) – Radius of curvature of the bowl [m].

• diameter (float) – Diameter of the opening of the bowl [m].

• focus_pos (ndarray) – Any point on the beam axis of the bowl given as a three element vector [fx, fy, fz] [m].

• num_points (int) – Number of points on the bowl.

• plot_bowl (bool | None) – Boolean controlling whether the Cartesian points are plotted.

Returns:

3 x num_points array of Cartesian coordinates.

Return type:

Float[ndarray, ‘3 NumPoints’]

Examples

bowl = makeCartBowl([0, 0, 0], 1, 2, [0, 0, 1], 100) bowl = makeCartBowl([0, 0, 0], 1, 2, [0, 0, 1], 100, True)

make_cart_circle(radius, num_points, center_pos=Vector([0, 0]), arc_angle=6.283185307179586, plot_circle=False)

Create a set of points in cartesian coordinates defining a circle or arc.

This function creates a set of points in cartesian coordinates defining a circle or arc.

Parameters:

• radius (float) – radius of the circle or arc

• num_points (int) – number of points to generate

• center_pos (Vector) – center position of the circle or arc

• arc_angle (float) – arc angle in radians

• plot_circle (bool) – whether to plot the circle or arc

Returns:

2 x num_points array of cartesian coordinates

Return type:

Float[ndarray, ‘2 NumPoints’]

make_cart_disc(disc_pos, radius, focus_pos, num_points, plot_disc=False, use_spiral=False)

Create evenly distributed Cartesian points covering a disc.

Parameters:

• disc_pos (ndarray) – Cartesian position of the center of the disc given as a two (2D) or three (3D) element tuple [m].

• radius (float) – Radius of the disc [m].

• focus_pos (ndarray) – Any point on the beam axis of the disc given as a three element tuple [fx, fy, fz] [m]. Can be set to None to define a disc in the x-y plane.

• num_points (int) – Number of points on the disc.

• plot_disc (bool) – Boolean controlling whether the Cartesian points are plotted (default = False).

• use_spiral (bool) – Boolean controlling whether the Cartesian points are chosen using a spiral sampling pattern. Concentric sampling is used by default.

Returns:

2 x num_points or 3 x num_points array of Cartesian coordinates.

Return type:

disc

make_cart_rect(rect_pos, Lx, Ly, theta=None, num_points=0, plot_rect=False)

Create evenly distributed Cartesian points covering a rectangle.

Args: rect_pos : List. Cartesian position of the centre of the rectangle. Lx : Float. Height of the rectangle (along the x-coordinate before rotation). Ly : Float. Width of the rectangle (along the y-coordinate before rotation). theta : Float or List (Optional). Specifies the orientation of the rectangle. num_points : int (Optional). Approximate number of points on the rectangle. plot_rect : bool (Optional). Boolean controlling whether the Cartesian points are plotted.

Returns: np.array. 2 x num_points* or 3 x num_points* array of Cartesian coordinates.

Parameters:

• Lx (Real[ndarray, ' '] | number | int | float)

• Ly (Real[ndarray, ' '] | number | int | float)

• theta (Real[ndarray, ' '] | number | int | float | list | Integer[ndarray, '...'] | Float[ndarray, '...'] | None)

• num_points (int)

• plot_rect (bool)

Return type:

Float[ndarray, ‘Dim1 Dim2’] | Float[ndarray, ‘Dim1 Dim2 Dim3’]

make_cart_sphere(radius, num_points, center_pos=Vector([0, 0, 0]), plot_sphere=False)

Cart_sphere creates a set of points in Cartesian coordinates defining a sphere.

Parameters:

• radius (float | int) – the radius of the sphere.

• num_points (int) – the number of points to be generated.

• center_pos (Vector) – the coordinates of the center of the sphere. Defaults to (0, 0, 0).

• plot_sphere (bool) – whether to plot the sphere. Defaults to False.

Returns:

The points on the sphere.

Return type:

Float[ndarray, ‘3 NumPoints’]

make_cart_spherical_segment(bowl_pos, radius, inner_diameter, outer_diameter, focus_pos, num_points, plot_bowl=False, num_points_inner=0)

Create evenly distributed Cartesian points covering a spherical segment.

Parameters:

• bowl_pos (Float[ndarray, '3']) – Cartesian position of the centre of the rear surface of the underlying bowl on which the spherical segment lies given as a three element vector [bx, by, bz] [m].

• radius (float | int) – Radius of curvature of the underlying bowl [m].

• inner_diameter (float | int) – Inner aperture diameter of the spherical segment [m].

• outer_diameter (float | int) – Outer aperture diameter of the spherical segment [m].

• focus_pos (Float[ndarray, '3']) – Any point on the beam axis of the underlying bowl given as a three element vector [fx, fy, fz] [m].

• num_points (int) – Number of points on the spherical segment.

• plot_bowl (bool | None) – Boolean controlling whether the Cartesian points are plotted.

• num_points_inner (int) – If constructing an annular array with contiguous elements (no kerf), the positions of the points will not exactly match makeCartBowl, as each element has no knowledge of the number of points on the internal elements. To force the points to match, specify the total number of points used on all annular segments internal to the current one.

Returns:

3 x num_points array of Cartesian coordinates.

Return type:

numpy.ndarray

make_circle(grid_size, center, radius, arc_angle=None, plot_circle=False)

Create a binary map of a circle within a 2D grid.

This function creates a binary map of a circle (or arc) using the midpoint circle algorithm within a two-dimensional grid. The circle position is denoted by 1’s in the matrix with 0’s elsewhere. A single grid point is taken as the circle centre, so the total diameter will always be an odd number of grid points. The centre of the circle and the radius are not constrained by the grid dimensions, so it is possible to create sections of circles or a blank image if none of the circle intersects the grid.

Parameters:

• grid_size (Vector) – A 2D vector of the grid size in grid points.

• center (Vector) – A 2D vector of the circle centre in grid points.

• radius (Real[ndarray, ' '] | number | int | float) – The radius of the circle.

• arc_angle (float | None) – The angle of the circular arc in degrees. If set to None, a full circle will be created.

• plot_circle (bool) – If set to True, the circle will be plotted using Matplotlib.

Returns:

A binary map of the circle in the 2D grid.

Return type:

Int[ndarray, ‘Dim1 Dim2’]

make_disc(grid_size, center, radius, plot_disc=False)

Create a binary map of a filled disc within a 2D grid.

This function creates a binary map of a filled disc within a two-dimensional grid. The disc position is denoted by 1’s in the matrix with 0’s elsewhere. A single grid point is taken as the disc centre, so the total diameter of the disc will always be an odd number of grid points. If used within a k-Wave grid where dx != dy, the disc will appear oval shaped. If part of the disc overlaps the grid edge, the rest of the disc will wrap to the grid edge on the opposite side.

Parameters:

• grid_size (Vector) – A 2D vector of the grid size in grid points.

• center (Vector) – A 2D vector of the disc centre in grid points.

• radius – The radius of the disc.

• plot_disc – If set to True, the disc will be plotted using Matplotlib.

Returns:

A binary map of the disc in the 2D grid.

Return type:

Bool[ndarray, ‘Dim1 Dim2’]

make_line(grid_size, startpoint, endpoint=None, angle=None, length=None)

Generate a line shape with a given start and end point, angle, or length.

Parameters:

• grid_size (Vector) – The size of the grid in pixels.

• startpoint (tuple[Int[ndarray, ' '] | number | int, Int[ndarray, ' '] | number | int] | Int[ndarray, '2']) – The start point of the line, given as a tuple of x and y coordinates.

• endpoint (tuple[Int[ndarray, ' '] | number | int, Int[ndarray, ' '] | number | int] | Int[ndarray, '2'] | None) – The end point of the line, given as a tuple of x and y coordinates. If not specified, the line is drawn from the start point at a given angle and length.

• angle (Float[ndarray, ' '] | number | float | None) – The angle of the line in radians, measured counterclockwise from the x-axis. If not specified, the line is drawn from the start point to the end point.

• length (Int[ndarray, ' '] | number | int | None) – The length of the line in pixels. If not specified, the line is drawn from the start point to the end point.

Returns:

A 2D array of the same size as the input parameters,

with a value of 1 for pixels that are part of the line and 0 for pixels that are not.

Return type:

line

make_multi_arc(grid_size, arc_pos, radius, diameter, focus_pos)

Generates a multi-arc mask for an image given the size of the grid, the positions and properties of the arcs, and the position of the focus.

Parameters:

• grid_size (Vector) – The size of the grid (assumed to be square).

• arc_pos (ndarray) – An array containing the (x, y) coordinates of the center of each arc.

• radius (int | ndarray) – The radius of each arc. Can be a single value or an array with one value for each arc.

• diameter (int | ndarray) – The diameter of the arcs. Can be a single value or an array with one value for each arc.

• focus_pos (ndarray) – The (x, y) coordinates of the focus.

Returns:

A binary mask of the arcs. arcs_labelled: A labelled mask of the arcs.

Return type:

arcs

Raises:

ValueError – If the shape of arc_pos is not (N, 2), if the number of rows in arc_pos and radius do not match, or if the number of rows in arc_pos and diameter do not match.

make_multi_bowl(grid_size, bowl_pos, radius, diameter, focus_pos, binary=False, remove_overlap=False)

Generates a multi-bowl mask for an image given the size of the grid, the positions of the bowls, the radius of each bowl, the diameter of the bowls, and the position of the focus.

Parameters:

• grid_size (Vector) – The size of the grid (assumed to be square).

• bowl_pos (list[tuple[int, int]]) – A list of tuples containing the (x, y) coordinates of the center of each bowl.

• radius (int) – The radius of each bowl.

• diameter (int) – The diameter of the bowls.

• focus_pos (tuple[int, int]) – The (x, y) coordinates of the focus.

• binary (bool) – Whether to return a binary mask (default: False).

• remove_overlap (bool) – Whether to remove overlap between the bowls (default: False).

Returns:

bowls_labeled:

Return type:

bowls

make_pixel_map(grid_size, shift=None, origin_size='single')

Generates a matrix with values of the distance of each pixel from the center of a grid.

This function generates a matrix populated with values of how far each pixel in a grid is from the center. The center can be a single pixel or a double pixel, and the optional input parameter ‘OriginSize’ controls this. For grids where the dimension size and center pixel size are not both odd or even, the optional input parameter ‘Shift’ can be used to control the location of the center point.

Parameters:

• grid_size (Vector) – A 2D or 3D vector of the grid size in grid points.

• *args – additional optional arguments

Returns:

pixel-radius

Return type:

r

Examples

Single pixel origin size for odd and even (with ‘Shift’ = [1 1] and [0 0], respectively) grid sizes:

x x x x x x x x x x x x 0 x x x x x x 0 x x x x x x x 0 x x x x x

x x x x x x x x

Double pixel origin size for even and odd (with ‘Shift’ = [1 1] and [0 0], respectively) grid sizes:

x x x x x x x x x x x x x x x 0 0 x x x x x x x 0 0 x x x 0 0 x x x 0 0 x x 0 0 x x x x x x x x 0 0 x x x x x x

x x x x x x x x x x

By default, a single pixel centre is used which is shifted towards the final row and column.

make_pixel_map_plane(grid_size, normal, point)

Generates a pixel map of a plane with given normal vector and point.

Parameters:

• grid_size (Vector) – The size of the grid as a NumPy array [Nx, Ny, Nz].

• normal (ndarray) – The normal vector of the plane as a NumPy array [nx, ny, nz].

• point (ndarray) – A point on the plane as a NumPy array [px, py, pz].

Returns:

A 2D array with the distance of each pixel from the given plane.

Return type:

pixel_map

Raises:

ValueError – If the normal vector is zero.

make_pixel_map_point(grid_size, centre_pos)

Generates a map of the distance of each pixel from a given centre position.

Parameters:

• grid_size (Vector) – The size of the grid, given as a 1D array with the number of pixels in each dimension.

• centre_pos (ndarray) – The position of the centre, given as a 1D array with the coordinates in each dimension.

Returns:

A 2D array with the distance of each pixel from the given centre position.

Return type:

np.ndarray

Raises:

ValueError – If grid_size and centre_pos do not have the same number of dimensions.

make_sphere(grid_size, radius, plot_sphere=False, binary=False)

Generates a sphere mask for a 3D grid given the dimensions of the grid, the radius of the sphere,

and optional flags to plot the sphere and/or return a binary mask.

Parameters:

• grid_size (Vector) – The size of the grid (assumed to be cubic).

• radius (float | int) – The radius of the sphere.

• plot_sphere (bool) – Whether to plot the sphere (default: False).

• binary (bool) – Whether to return a binary mask (default: False).

Returns:

The sphere mask as a NumPy array.

Return type:

sphere

make_spherical_section(radius, height, width=None, plot_section=False, binary=False)

Generates a spherical section mask given the radius and height of the section and

optional parameters to specify the width and/or plot and return a binary mask.

Parameters:

• radius (Real[ndarray, ' '] | number | int | float) – The radius of the spherical section.

• height (Real[ndarray, ' '] | number | int | float) – The height of the spherical section.

• width (Real[ndarray, ' '] | number | int | float | None) – The width of the spherical section (default: height).

• plot_section (bool) – Whether to plot the spherical section (default: False).

• binary (bool) – Whether to return a binary mask (default: False).

Returns:

The spherical section mask as a NumPy array. dist_map: The distance map of the spherical section mask as a NumPy array.

Return type:

ss

Raises:

• ValueError – If the width is not an odd number.

• NotImplementedError – Plotting not currently supported.

ndgrid(*args)

power_law_kramers_kronig(w, w0, c0, a0, y)

Compute the variation in sound speed for an attenuating medium using the Kramers-Kronig for power law attenuation.

This function computes the variation in sound speed for an attenuating medium using the Kramers-Kronig formula for power law attenuation, where att = a0 * w^y. The power law parameters must be in Nepers/m, with the frequency in rad/s. The variation is given about the sound speed c0 at a reference frequency w0.

Parameters:

• w (ndarray) – input frequency array [rad/s]

• w0 (float) – reference frequency [rad/s]

• c0 (float) – sound speed at w0 [m/s]

• a0 (float) – power law coefficient [Nepers/((rad/s)^y m)]

• y (float) – power law exponent, where 0 < y < 3

Returns:

Variation of sound speed with w [m/s]

Return type:

ndarray

trim_cart_points(kgrid, points)

trim_cart_points filters a dim x num_points array of Cartesian points so that only those within the bounds of a given kgrid remain. :param kgrid: Object of the kWaveGrid class defining the Cartesian

and k-space grid fields.

Parameters:

points (ndarray) – dim x num_points array of Cartesian coordinates to trim [m].

Returns:

dim x num_points array of Cartesian coordinates that lie within the grid defined by kgrid [m].

water_absorption(f, temp)

Calculates the ultrasonic absorption in distilled water at a given temperature and frequency using a 7 th order polynomial fitted to the data given by Pinkerton (1949).

Parameters:

• f (float) – f frequency value [MHz]

• T – water temperature value [degC]

• temp (float | Float[ndarray, '1'] | Float[ndarray, '2'] | Float[ndarray, '3'])

Returns:

absorption [dB / cm]

Return type:

abs

Examples

>>> abs = waterAbsorption(f, T)

References

[1] J. M. M. Pinkerton (1949) “The Absorption of Ultrasonic Waves in Liquids and its

Relation to Molecular Constitution,”

Proceedings of the Physical Society. Section B, 2, 129-141

water_density(temp)

Calculate the density of air-saturated water with temperature.

This function calculates the density of air-saturated water at a given temperature using the 4th order polynomial given by Jones [1].

Parameters:

temp (int | float | number | ndarray) – water temperature in the range 5 to 40 [degC]

Returns:

density of water [kg/m^3]

Return type:

density

Raises:

ValueError – if temp is not between 5 and 40

References

[1] F. E. Jones and G. L. Harris (1992) “ITS-90 Density of Water Formulation for Volumetric Standards Calibration,” Journal of Research of the National Institute of Standards and Technology, 97(3), 335-340.

water_non_linearity(temp)

Calculates the parameter of nonlinearity B/A at a given temperature using a fourth-order polynomial fitted to the data given by Beyer (1960).

Parameters:

temp (float | Float[ndarray, '1'] | Float[ndarray, '2'] | Float[ndarray, '3']) – water temperature in the range 0 to 100 [degC]

Returns:

parameter of nonlinearity

Return type:

BonA

Examples

>>> BonA = waterNonlinearity(T)

References:

[1] R. T. Beyer (1960) “Parameter of nonlinearity in fluids,” J. Acoust. Soc. Am., 32(6), 719-721.

water_sound_speed(temp)

Calculate the sound speed in distilled water with temperature according to Marczak (1997)

Parameters:

temp (float | Float[ndarray, '1'] | Float[ndarray, '2'] | Float[ndarray, '3']) – The temperature of the water in degrees Celsius.

Returns:

The sound speed in distilled water in m/s.

Return type:

c

Raises:

ValueError – if temp is not between 0 and 95

References

[1] R. Marczak (1997). “The sound velocity in water as a function of temperature”. Journal of Research of the National Institute of Standards and Technology, 102(6), 561-567.