Sources
FocusedSource2D
Bases: Source
A focused source in 2D.
This source is shaped like an arc and has a circular focus. It is created by taking an arc of a circle and distributing point sources evenly along that arc.
See Circular arc for relevant geometrical calculations.
calculate_waveform_scale(dx)
Calculate the scale factor to apply to waveforms from this source.
The scale is equal to the ratio between the density of grid points along a line and the density of source points along the arc.
Parameters:
Name  Type  Description  Default 

dx 
float

the separation between gridpoints (in meters). Assumed to be the same in both directions. 
required 
Returns:
Type  Description 

float

The scale factor to apply to the waveform. 
FocusedSource3D
Bases: Source
A focused source in 3D.
This source is shaped like a bowl and has a spherical focus. It is created by taking a section of a spherical shell and distributing source points over the surface. Points are distributed according to Fibonacci spirals.
See Spherical cap for relevant geometrical calculations.
calculate_waveform_scale(dx)
Calculate the scale factor to apply to waveforms from this source.
The scale is equal to the ratio between the density of grid points in a plane and the density of source points along the bowl surface.
Parameters:
Name  Type  Description  Default 

dx 
float

the separation between gridpoints (in meters). Assumed to be the same in all 3 directions. 
required 
Returns:
Type  Description 

float

The scale factor to apply to the waveform. 
PhasedArraySource(*, position, direction, num_points, num_elements, pitch, element_width, tilt_angle=0.0, focal_length=np.inf, delay=0.0, element_delays=None)
Bases: Source
A base class for phased array sources.
Parameters:
Name  Type  Description  Default 

position 
list[float]

a float array indicating the coordinates (in meters) of the point at the center of the source, which is the point that bisects the line segment source. 
required 
direction 
list[float]

a float array representing
a vector located at position that is perpendicular to the plane
of the source. Only the orientation of 
required 
num_points 
int

the number of point sources to use when simulating the source. 
required 
num_elements 
int

the number of elements of the phased array. 
required 
pitch 
float

the distance (in meters) between the centers of neighboring elements in the phased array. 
required 
element_width 
float

the width (in meters) of each individual element of the array. 
required 
tilt_angle 
float

the desired tilt angle (in degrees) of the wavefront. The angle is measured between the direction the wavefront travels and the normal to the surface of the transducer, with positive angles resulting in a counterclockwise tilt away from the normal. 
0.0

focal_length 
float

the distance (in meters) from 
np.inf

delay 
float

the delay (in seconds) that the source will wait before emitting. 
0.0

element_delays 
npt.NDArray[np.float_]  None

an 1D array with the delays (in seconds) for each element of the
phased array. Delays from 
None

aperture: float
property
The width (in meters) of the source.
element_delays: npt.NDArray[np.float_]
property
The delay (in seconds) that each element should wait before emitting.
element_positions: npt.NDArray[np.float_]
property
An array with the position of the center of each element of the array.
element_width: float
property
The width (in meters) of each element of the array.
num_elements: int
property
The number of elements in the source array.
pitch: float
property
The pitch
(in meters) of the source.
point_mapping: tuple[slice, ...]
property
A tuple with the slices of source point indexes comprising each element.
point_source_delays: npt.NDArray[np.float_]
property
The delay before emitting (in seconds) for each point source.
The delays are computed at the element level. All source points within an element will have the same delay.
spacing: float
property
The separation (in meters) between elements of the array.
tilt_angle: float
property
The angle (in degrees) that the wave front is tilted.
focal_point()
Get or set the coordinates (in meters) of the focal point of the source.
txdelay(tilt_angle, pitch, speed=1500)
staticmethod
Compute the delay (in seconds) required to tilt the wavefront.
The delays from element n to element n+1 to achieve a wavefront with
tilt_angle
respect to the normal. Positive angles lead to counterclockwise
rotations.
Parameters:
Name  Type  Description  Default 

tilt_angle 
float

angle (in degrees) between the vector normal to the source and the wavefront. 
required 
pitch 
float

the pitch (in meters) of the source. 
required 
speed 
float

the speed of sound (in meters/second) of the material where the source is placed. 
1500

Returns:
Type  Description 

float

The delay (in seconds) between two consecutive elements. 
PhasedArraySource2D
Bases: PhasedArraySource
A phased array source in 2D.
This source is shaped like multiple segments in a line. Each segment can emit
waves independently. It has no focus currently. A focused implementation will be
supported in the future. This source is composed of num_points
point sources.
Distributed evenly in num_elements
.
If the number of points can not be evenly distributed in the number of elements, the remainder number of points from the even division will be discarded.
See Phased array ultras... for detailed explanation.
focal_point: npt.NDArray[np.float_]
property
The coordinates (in meters) of the point where the array focuses.
If the array is unfocused it will return the focal point (inf, inf).
calculate_waveform_scale(dx)
Calculate the scale factor to apply to waveforms from this source.
The scale is equal to the ratio between the density of grid points along a line and the density of source points along the line segment source.
Parameters:
Name  Type  Description  Default 

dx 
float

the separation between gridpoints (in meters). Assumed to be the same in both directions. 
required 
Returns:
Type  Description 

float

The scale factor to apply to the waveform. 
PhasedArraySource3D(*, position, direction, center_line, num_points, num_elements, pitch, height, element_width, tilt_angle=0.0, focal_length=np.inf, delay=0.0, element_delays=None)
Bases: PhasedArraySource
A linear phased array source in 3D.
This source is shaped like multiple rectangular segments in a line. Each segment
can emit waves independently. It has no focus currently. A focused implementation
will be supported in the future. This source is composed of num_points
point
sources distributed evenly in num_elements
.
If the number of points can not be evenly distributed in the number of elements, the remainder number of points from the even division will be discarded.
See Phased array ultras... for detailed explanation.
Parameters:
Name  Type  Description  Default 

position 
list[float]

a float array in 3D indicating the coordinates (in meters) of the point at the center of the source, which is the point that bisects both the height and the aperture of the source. 
required 
direction 
list[float]

a float array in 3D representing a
vector located at position that is perpendicular to the plane of the source.
Only the orientation of 
required 
center_line 
npt.NDArray[np.float_]

A 3D vector which is parallel to the line through the centers of
the elements in the linear array. This vector must be perpendicular to

required 
num_points 
int

the number of point sources to use when simulating the source. If the number of points is not divisible evenly by the number of elements, the number of points would be truncated to a multiple of the maximum even divisor. 
required 
num_elements 
int

the number of elements of the phased array. 
required 
pitch 
float

the distance (in meters) between the centers of neighboring elements in the phased array. 
required 
height 
float

the height (in meters) of the elements of the array. 
required 
element_width 
float

the width (in meters) of each individual element of the array. 
required 
tilt_angle 
float

the desired tilt angle (in degrees) of the wavefront. The angle is measured between the direction the wavefront travels and the normal to the surface of the transducer, with positive angles resulting in a counterclockwise tilt away from the normal. 
0.0

focal_length 
float

the distance (in meters) from 
np.inf

delay 
float

the delay (in seconds) that the source will wait before emitting. 
0.0

element_delays 
npt.NDArray[np.float_]  None

an 1D array with the delays (in seconds) for each element of the
phased array. Delays from 
None

focal_point: npt.NDArray[np.float_]
property
The coordinates (in meters) of the point where the array focuses.
If the array is unfocused it will return the focal point (inf, inf, inf).
height: float
property
The height
(in meters) of the elements of the source.
unit_center_line: npt.NDArray[np.float_]
property
The unit direction of the line crossing the center of the array elements.
calculate_waveform_scale(dx)
Calculate the scale factor to apply to waveforms from this source.
The scale is equal to the ratio between the density of grid points along a plane and the density of source points along the planar source.
Parameters:
Name  Type  Description  Default 

dx 
float

the separation between gridpoints (in meters). Assumed to be the same in both directions. 
required 
Returns:
Type  Description 

float

The scale factor to apply to the waveform. 
PlanarSource2D
Bases: UnfocusedSource
A planar source in 2D.
This source is shaped like a line segment and has no focus. The source is composed
of num_points
point sources evenly distributed along the line segment.
calculate_waveform_scale(dx)
Calculate the scale factor to apply to waveforms from this source.
The scale is equal to the ratio between the density of grid points along a line and the density of source points along the line segment source.
Parameters:
Name  Type  Description  Default 

dx 
float

the separation between gridpoints (in meters). Assumed to be the same in both directions. 
required 
Returns:
Type  Description 

float

The scale factor to apply to the waveform. 
PlanarSource3D
Bases: UnfocusedSource
A planar source in 3D.
This source is shaped like a disk and has no focus. It is created by defining a
disk and distributing num_points
point sources according to Fibonacci spirals.
calculate_waveform_scale(dx)
Calculate the scale factor to apply to waveforms from this source.
The scale is equal to the ratio between the density of grid points along a plane and the density of source points along the disk source.
Parameters:
Name  Type  Description  Default 

dx 
float

the separation between gridpoints (in meters). Assumed to be the same in both directions. 
required 
Returns:
Type  Description 

float

The scale factor to apply to the waveform. 
PointSource(*, position, num_dim=2, delay=0.0)
Bases: Source
Theoretical point source.
Automatically sets aperture
, focal_length
, and direction
, and num_points
.
calculate_waveform_scale(dx)
Calculate the scale factor to apply to waveforms from point source.
The scale is equal to the ratio between the density of source points and the density of grid points (2D: 1 / dx; 3D: 1 / dx2). Because the aperture is technically zero, we approximate the source density as the smallest grid (2D: 1 / dx; 3D: 1 / dx2).
Parameters:
Name  Type  Description  Default 

dx 
float

the separation between gridpoints (in meters). Assumed to be the same in both directions. Unused. 
required 
Returns:
Type  Description 

float

The scale factor to apply to the waveform. 
PointSource2D(*, position, delay=0.0)
PointSource3D(*, position, delay=0.0)
Source(*, position, direction, aperture, focal_length, num_points, delay=0.0)
Bases: abc.ABC
An abstract class that represents a generic Source object.
Sources can be 2D or 3D, which affects the shape of arrays representing coordinates or vectors. Sources are composed of point sources evenly distributed over the appropriate source geometry.
Parameters:
Name  Type  Description  Default 

position 
npt.ArrayLike

a float array indicating the coordinates (in meters) of the point at the center of the source. 
required 
direction 
list[float]

a float array representing a vector located at position and pointing
towards the focal point. Only the orientation of 
required 
aperture 
float

the width (in meters) of the source. 
required 
focal_length 
float

the distance (in meters) from 
required 
num_points 
int

the number of point sources to use when simulating the source. 
required 
delay 
float

the delay (in seconds) that the source will wait before emitting. Defaults to 0.0. 
0.0

aperture: float
property
The width (in meters) of the source.
coordinates: npt.NDArray[np.float_]
property
A 2D array containing the coordinates
(in meters) of the source points.
The length of this array along the first dimension is equal to num_points
.
delay: float
property
The delay
(in seconds) for the source as a whole.
delay
should be nonnegative.
focal_length: float
property
The distance (in meters) from position
to the focal point.
num_points: int
property
The number of point sources used to simulate the source.
point_source_delays: npt.NDArray[np.float_]
property
The delay before emitting (in seconds) for each point source.
position: npt.NDArray[np.float_]
property
A numpy float array indicating the position
(in meters) of the source.
The position of the source is defined as the coordinates of the point at the center of symmetry of the source.
unit_direction: npt.NDArray[np.float_]
property
A normalized vector indicating the orientation of the source.
The vector is located at position
, points towards the focal point, and has
unit length. It points in the same direction as the direction
parameter in
__init__
, except it is normalized.
calculate_waveform_scale(dx)
abstractmethod
Calculate the scale factor to apply to waveforms from this source.
The scale depends on the relative density of source points vs grid points.
This method must be implemented by all concrete Source classes.
Parameters:
Name  Type  Description  Default 

dx 
float

the separation (in meters) between gridpoints. Assumed to be the same in all directions. 
required 
Returns:
Type  Description 

float

The scale factor to apply to the waveform. 
UnfocusedSource(*, position, direction, aperture, num_points, delay=0.0)
Bases: Source
, abc.ABC
An abstract base class for unfocused sources.
Automatically sets focal_length
to np.inf