Arrays

Handling of transducer arrays, grouping multiple transducer elements.

The main class is the TransducerArray class, but other classes exist to simplify the creation of the transducer positions for common array geometries.

`TransducerArray`	Base class to handle transducer arrays.
`NormalTransducerArray`	Transducer array with a clearly defined normal.
`RectangularArray`	TransducerArray implementation for rectangular arrays.
`SphericalCapArray`	Transducer array implementation for spherical caps.
`DoublesidedArray`	TransducerArray implementation for doublesided arrays.

class levitate.arrays.TransducerArray(positions, normals, transducer=None, medium=None, **kwargs)

Base class to handle transducer arrays.

This class has no notion of the layout. If possible, try to use a more specific implementation instead.

Parameters

positions (numpy.ndarray) – The positions of the transducer elements in the array, shape 3xN.
normals (numpy.ndarray) – The normals of the transducer elements in the array, shape 3xN.
transducer – An object of levitate.transducers.TransducerModel or a subclass. If passed a class it will create a new instance.
**kwargs – All additional keyword arguments will be passed to the a transducer class used when instantiating a new transducer model. Note that this will have no effect on already instantiated transducer models.

Variables

~TransducerArray.num_transducers (int) – The number of transducers used.
~TransducerArray.positions (numpy.ndarray) – As above.
~TransducerArray.normals (numpy.ndarray) – As above.
~TransducerArray.transducer (TransducerModel) – An instance of a specific transducer model implementation.
~TransducerArray.freq (float) – Frequency of the transducer model.
~TransducerArray.omega (float) – Angular frequency of the transducer model.
~TransducerArray.k (float) – Wavenumber in air, corresponding to freq.
~TransducerArray.wavelength (float) – Wavelength in air, corresponding to freq.

class ArrayVisualizer(array, *args, **kwargs)

Visualizations of a trandcuer array.

It is possible to set an item using either just a trace specifier, e.g. “Pressure”, which create the appropriate trace with default arguments. If arguments are required or wanted, set the item to a tuple where the first element is the trace specifier, and subsequent elements are the arguments. If the last element in the tuple is a dictionary, it will be used as keyword arguments for the trace type.

__call__(*complex_transducer_amplitudes, **kwargs): Call self as a function.

class ForceDiagram(*args, scale_to_gravity=True, include_gravity=True, **kwargs)

__call__(*complex_transducer_amplitudes, **kwargs): Call self as a function.

focus_phases(focus)

Focuses the phases to create a focus point.

Parameters: focus (array_like) – Three element array with a location where to focus.
Returns: phases (numpy.ndarray) – Array with the phases for the transducer elements.

signature(position, phases, stype=None)

Calculate the phase signature of the array.

The signature of an array if the phase of the transducer elements when the phase required to focus all elements to a specific point has been removed.

Parameters

position (array_like) – Three element array with a position for where the signature is relative to.
phases (numpy.ndarray) – The phases of which to calculate the signature.

Returns

signature (numpy.ndarray) – The signature wrapped to the interval [-pi, pi].

pressure_derivs(positions, orders=3)

Calculate derivatives of the pressure.

Calculates the spatial derivatives of the pressure from all individual transducers in a Cartesian coordinate system.

Parameters

positions (numpy.ndarray) – The location(s) at which to evaluate the derivatives, shape (3, …). The first dimension must have length 3 and represent the coordinates of the points.
orders (int) – How many orders of derivatives to calculate. Currently three orders are supported.

Returns

derivatives (ndarray) – Array with the calculated derivatives. Has the shape (M, N, …) where M is the number of spatial derivatives, and N is the number of transducers, see num_spatial_derivatives and spatial_derivative_order, and the remaining dimensions are the same as the positions input with the first dimension removed.

spherical_harmonics(positions, orders=0)

Spherical harmonics expansion of transducer sound fields.

The sound fields generated by the individual transducers in the array are expanded in spherical harmonics around the positions specified. The coefficients are calculated using analytical translation of the transducer radiation patterns. This is a simplified calculation which will not account for the local directivity curve, only an overall scaling for each transducer-position combination.

Parameters

positions (numpy.ndarray) – The location(s) at which to evaluate the derivatives, shape (3, …). The first dimension must have length 3 and represent the coordinates of the points.
orders (int, default 0) – The maximum order to expand to.

Returns

spherical_harmonics_coefficients (numpy.ndarray) – Array with the calculated expansion coefficients. The order of the coefficients are described in SphericalHarmonicsIndexer. Has shape (M, N, …) where M=len(SphericalHarmonicsIndexer(orders)), N is the number of transducers in the array, and the remaining dimensions are the same as the positions input with the first dimension removed.

request(requests, position)

Evaluate a set of requests.

This takes a mapping (e.g. dict) of requests, and evaluates them at a given position. This is independent of the current transducer state. If a certain quantity should be calculated with regards to the current transducer state, use a FieldImplementation from the fields module.

Parameters

position (ndarray) – The position where to calculate the requirements needed, shape (3,…).
requests (mapping, e.g. dict) –
A mapping of the desired requests. The keys in the mapping should start with the desired output, and the value indicates some kind of parameter set. Possible requests listed below:

pressure_derivs
A number of spatial derivatives of the pressure. Should contain the maximum order of differentiation, see pressure_derivs.

spherical_harmonics
Spherical harmonics coefficients for an expansion of the pressure. Should contain the maximum order of expansion, see spherical_harmonics.

Returns

evaluated_requests (dict) – A dictionary of the set of calculated data, according to the requests.

class levitate.arrays.NormalTransducerArray(positions, normals, offset=(0, 0, 0), normal=(0, 0, 1), rotation=0, **kwargs)

Transducer array with a clearly defined normal.

This is mostly intended as a base class for other implementations. The advantage is that a simple arrangement can be created assuming a normal along the z-axis, which is then rotated and moved to the desired orientation. The positions and normals of the transducers should be input assuming that the overall normal for the array is along the z-axis. The positions and normals will be rotated around the origin to give the desired overall normal. This rotation will take place along the intersection line of the plane specificed by the desired normal, and the xy-plane. If rotation is desired, the positions are further rotated using the normal as the rotation axis. Finally an offset is applied to the entire array.

Parameters

positions (numpy.ndarray) – The positions of the transducer elements in the array, shape 3xN.
normals (numpy.ndarray) – The normals of the transducer elements in the array, shape 3xN (or 3 elements which will broadcast).
offset (3 element array_like, default (0, 0, 0)) – The location of the center of the array.
normal (3 element array_like, default (0, 0, 1)) – The normal of the overall array.
rotation (float, default 0) – The in-plane rotation of the array around the normal.

signature(position=None, *args, stype=None, **kwargs)

Calculate phase signatures of the array.

The signature of an array if the phase of the transducer elements when the phase required to focus all elements to a specific point has been removed. If stype if set to one of the available signatures: ‘twin’, ‘vortex’, or ‘bottle’, the corresponding signature is returned.

The signatures and the additional keyword parameters for them are:

Current signature (stype=None)

Calculates the current phase signature. See TransducerArray.signature

phases (numpy.ndarray, optional): The phases of which to calculate the signature. Will default to the current phases in the array.

Twin signature (stype='twin')

Calculates the twin trap signature which shifts the phase of half of the elements by pi, splitting the array along a straight line.

angle (float, optional): The angle between the x-axis and the dividing line. Default is to create a line perpendicular to the line from the center of the array to position.

Vortex signature (stype='vortex')

Calculates the vortex trap signature which phase shifts the elements in the array according to their angle in the coordinate plane.

angle (float, optional): Additional angle to rotate the phase signature with.

Bottle signature (stype='bottle')

Calculates the bottle trap signature which phase shifts the elements in the array according to their distance from the center, creating an inner zone and an outer zone of equal area with a relative shift of pi.

radius (float, optional): A custom radius to use for the division of transducers. The default is to use equal area partition based on the rectangular area occupied by each transducer. This gives the same number of transducers in the two groups for square arrays.

Parameters

position (array_like) – Three element array with a location for where the signature is relative to.
stype (None, 'twin', 'bottle', 'vortex'. Default None) – Chooses which type of signature to calculate.

Returns

signature (numpy.ndarray) – The signature wrapped to the interval [-pi, pi].

class levitate.arrays.RectangularArray(shape=16, spread=0.01, **kwargs)

TransducerArray implementation for rectangular arrays.

Defines the locations and normals of elements (transducers) in an array. See NormaltransducerArray for documentation of roration and transslation options.

Parameters

shape (int or (int, int), default 16) – The number of transducer elements. Passing a single int will create a square array.
spread (float, default 10e-3) – The distance between the array elements.

class levitate.arrays.SphericalCapArray(radius, rings, spread=0.01, packing='distance', **kwargs)

Transducer array implementation for spherical caps.

The transducers will be placed on a virtual spherical surface, i.e. on the same distance from a given point in space. Control the overall shape of the array with the radius, rings, and spead parameters. See NormalTransdcerArray for details on the overall placement of the array, e.g. rotations and offsets.

There are many ways to pack transdcuers on a spherical surface. The ‘distance’ method will place the transducers on concentric rings where the distance between each ring is pre-determined. Each ring will have as many transducers as possible for the given ring size. This will typically pack the transducers densely, and the outer dimentions of the array is quite consistent. The ‘count’ method will use a pre-determined number of transducers in each ring, with 6 additional transducers for each successive ring. The inter-ring distance will be set to fit the requested number of transducers. This method will deliver a pre-determined number of transducers, but will not be as dense. If too many rings are requested, the ‘count’ method will fill a half-spere with transducers and then stop. The ‘distance’ method can fill the entire sphere with transducers.

Parameters

radius (float) – The curvature of the spherical cap, i.e. how for away the focus is.
rings (int) – Number of consecutive rings of transducers in the array.
packing (str, default 'distance') – Controlls which packing method is used. One of ‘distance’ or ‘count’, see above.
spread (float, default 10e-3) – Controls the minimum spacing between individual transducers.

class levitate.arrays.DoublesidedArray(array, separation, normal=(0, 0, 1), offset=(0, 0, 0), twist=0, **kwargs)

TransducerArray implementation for doublesided arrays.

Creates a doublesided array based on mirroring a singlesided array. This can easily be used to create standard doublesided arrays by using the same normal for the mirroring as for the original array. If a different normal is used it is possible to create e.g. v-shaped arrays.

The singlesided array is “centered” at the origin, where “center” is defined as the mean coordinate of the elements.

The singlesided array is shifted with half of the separation in the opposite direction of the normal to create the “lower” half.

The “upper” half is created by mirroring the “lower” half in the plane described by the normal.

Both halves are offset with a specified vector.

Note that only the orientation of the initial array matters, not the overall position.

Parameters

array (Instance or (sub)class of TransducerArray.) – The singlesided object used to the creation of the doublesided array. Classes will be instantiated to generate the array, using all input arguments except array, separation, and offset.
separation (float) – The distance between the two halves, along the normal.
offset (array_like, 3 elements) – The placement of the center between the two arrays.
normal (array_like, 3 elements) – The normal of the reflection plane.
twist (float, default 0) – By how much the two halves are rotated compared to each other, in radians.

signature(position=None, *args, stype=None, **kwargs)

Calculate phase signatures of the array.

The signature of an array if the phase of the transducer elements when the phase required to focus all elements to a specific point has been removed. If stype if set to one of the available signatures the corresponding signature is returned. The signatures of the array used when creating the doublesided array are also available.

The signatures and the additional keyword parameters for them are:

Current signature (stype=None)

Calculates the current phase signature. See TransducerArray.signature

phases (numpy.ndarray, optional): The phases of which to calculate the signature. Will default to the current phases in the array.

Doublesided signature (stype='doublesided')

Calculates the doublesided trap signature which shifts the phase of one side of the array half of the elements by pi.

Parameters

position (array_like) – Three element array with a location for where the signature is relative to.
stype (None, 'doublesided', etc. Default None) – Chooses which type of signature to calculate.

Returns

signature (numpy.ndarray) – The signature wrapped to the interval [-pi, pi].