Transducers

Handling of individual transducers and their directivities.

This module contains classes describing how individual transducer elements radiate sound, e.g. waveforms and directivities. This is also where the various spatial properties, e.g. derivatives, are implemented. Most calculations in this module are fully vectorized, so the models can calculate sound fields for any number of source positions and receiver positions at once.

`TransducerModel`	Base class for ultrasonic single frequency transducers.
`PointSource`	Point source transducers.
`PlaneWaveTransducer`	Class representing planar waves.
`CircularPiston`	Circular piston transducer model.
`CircularRing`	Circular ring transducer model.
`TransducerReflector`	Class for transducers with planar reflectors.

class levitate.transducers.TransducerModel(freq=40000.0, p0=6, medium=Air(dynamic_viscosity=1.85e-05, rho=1.204082071218662, c=343.23714360505863), physical_size=0.01)

Base class for ultrasonic single frequency transducers.

Parameters

freq (float, default 40 kHz) – The resonant frequency of the transducer.
p0 (float, default 6 Pa) – The sound pressure created at maximum amplitude at 1m distance, in Pa. Note: This is not an rms value!
medium (Material) – The medium in which the array is operating.
physical_size (float, default 10e-3) – The physical dimentions of the transducer. Mainly used for visualization and some geometrical assumptions.

Variables

~TransducerModel.k (float) – Wavenumber in the medium.
~TransducerModel.wavelength (float) – Wavelength in the medium.
~TransducerModel.omega (float) – Angular frequency.
~TransducerModel.freq (float) – Wave frequency.

pressure(source_positions, source_normals, receiver_positions, **kwargs)

Calculate the complex sound pressure from the transducer.

Parameters

source_positions (numpy.ndarray) – The location of the transducer, as a (3, …) shape array.
source_normals (numpy.ndarray) – The look direction of the transducer, as a (3, …) shape array.
receiver_positions (numpy.ndarray) – The location(s) at which to evaluate the radiation, shape (3, …). The first dimension must have length 3 and represent the coordinates of the points.

Returns

out (numpy.ndarray) – The pressure at the locations, shape source_positions.shape[1:] + receiver_positions.shape[1:].

pressure_derivs(source_positions, source_normals, receiver_positions, orders=3, **kwargs)

Calculate the spatial derivatives of the greens function.

Calculates Cartesian spatial derivatives of the pressure Green’s function. Should be implemented by concrete subclasses.

Parameters

source_positions (numpy.ndarray) – The location of the transducer, as a (3, …) shape array.
source_normals (numpy.ndarray) – The look direction of the transducer, as a (3, …) shape array.
receiver_positions (numpy.ndarray) – The location(s) at which to evaluate the radiation, 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 (numpy.ndarray) – Array with the calculated derivatives. Has the shape (M,) + source_positions.shape[1:] + receiver_positions.shape[1:]. where M is the number of spatial derivatives, see num_spatial_derivatives and spatial_derivative_order.

class levitate.transducers.PointSource(freq=40000.0, p0=6, medium=Air(dynamic_viscosity=1.85e-05, rho=1.204082071218662, c=343.23714360505863), physical_size=0.01)

Point source transducers.

A point source is in this context defines as a spherically spreading wave, optionally with a directivity. On its own this class defines a monopole, but subclasses are free to change the directivity to other shapes.

The spherical spreading is defined as

\[G(r) = {e^{ikr} \over r}\]

where \(r\) is the distance from the source, and \(k\) is the wavenumber of the wave.

directivity(source_positions, source_normals, receiver_positions)

Evaluate transducer directivity.

Subclasses will preferably implement this to create new directivity models. Default implementation is omnidirectional sources.

Parameters

source_positions (numpy.ndarray) – The location of the transducer, as a (3, …) shape array.
source_normals (numpy.ndarray) – The look direction of the transducer, as a (3, …) shape array.
receiver_positions (numpy.ndarray) – The location(s) at which to evaluate the radiation, shape (3, …). The first dimension must have length 3 and represent the coordinates of the points.

Returns

out (numpy.ndarray) – The amplitude (and phase) of the directivity, shape source_positions.shape[1:] + receiver_positions.shape[1:].

pressure_derivs(source_positions, source_normals, receiver_positions, orders=3, **kwargs)

Calculate the spatial derivatives of the greens function.

This is the combination of the derivative of the spherical spreading, and the derivatives of the directivity, including source strength.

Parameters

source_positions (numpy.ndarray) – The location of the transducer, as a (3, …) shape array.
source_normals (numpy.ndarray) – The look direction of the transducer, as a (3, …) shape array.
receiver_positions (numpy.ndarray) – The location(s) at which to evaluate the radiation, 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 (numpy.ndarray) – Array with the calculated derivatives. Has the (M,) + source_positions.shape[1:] + receiver_positions.shape[1:]. where M is the number of spatial derivatives, see num_spatial_derivatives and spatial_derivative_order.

wavefront_derivatives(source_positions, receiver_positions, orders=3)

Calculate the spatial derivatives of the spherical spreading.

Parameters

source_positions (numpy.ndarray) – The location of the transducer, as a (3, …) shape array.
receiver_positions (numpy.ndarray) – The location(s) at which to evaluate the radiation, 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,) + source_positions.shape[1:] + receiver_positions.shape[1:]. where M is the number of spatial derivatives, see num_spatial_derivatives and spatial_derivative_order.

directivity_derivatives(source_positions, source_normals, receiver_positions, orders=3)

Calculate the spatial derivatives of the directivity.

The default implementation uses finite difference stencils to evaluate the derivatives. In principle this means that customized directivity models does not need to implement their own derivatives, but can do so for speed and precision benefits.

Parameters

source_positions (numpy.ndarray) – The location of the transducer, as a (3, …) shape array.
source_normals (numpy.ndarray) – The look direction of the transducer, as a (3, …) shape array.
receiver_positions (numpy.ndarray) – The location(s) at which to evaluate the radiation, 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 (numpy.ndarray) – Array with the calculated derivatives. Has the shape (M,) + source_positions.shape[1:] + receiver_positions.shape[1:]. where M is the number of spatial derivatives, see num_spatial_derivatives and spatial_derivative_order.

spherical_harmonics(source_positions, source_normals, receiver_positions, orders=0, **kwargs)

Expand sound field in spherical harmonics.

Performs a spherical harmonics expansion of the sound field created from the transducer model. The expansion is centered at the receiver position(s), and calculated by translating spherical wavefronts from the source position(s).

Parameters

source_positions (numpy.ndarray) – The location of the transducer, as a (3, …) shape array.
source_normals (numpy.ndarray) – The look direction of the transducer, as a (3, …) shape array.
receiver_positions (numpy.ndarray) – The location(s) at which to evaluate the radiation, shape (3, …). The first dimension must have length 3 and represent the coordinates of the points.
orders (int) – How many orders of spherical harmonics coefficients to calculate.

Returns

coefficients (numpy.ndarray) – Array with the calculated expansion coefficients. Has the shape (M,) + source_positions.shape[1:] + receiver_positions.shape[1:], where M=len(SphericalHarmonicsIndexer(orders)), see SphericalHarmonicsIndexer for details on the structure of the coefficients.

class levitate.transducers.TransducerReflector(transducer, plane_intersect=(0, 0, 0), plane_normal=(0, 0, 1), reflection_coefficient=1, *args, **kwargs)

Class for transducers with planar reflectors.

This class can be used to add reflectors to all transducer models. This uses the image source method, so only infinite planar reflectors are possible.

Parameters

transducer (TrnsducerModel instance or (sub)class) – The base transducer to reflect. If passed a class it will be instantiated with the remaining arguments not used by the reflector.
plane_intersect (array_like, default (0, 0, 0)) – A point which the reflection plane intersects.
plane_normal (array_like, default (0,0,1)) – 3 element vector with the plane normal.
reflection_coefficient (complex float, default 1) – Reflection coefficient to tune the magnitude and phase of the reflection.

Returns

transducer – The transducer model with reflections.

pressure_derivs(source_positions, source_normals, receiver_positions, *args, **kwargs)

Calculate the spatial derivatives of the greens function.

Parameters

source_positions (numpy.ndarray) – The location of the transducer, as a (3, …) shape array.
source_normals (numpy.ndarray) – The look direction of the transducer, as a (3, …) shape array.
receiver_positions (numpy.ndarray) – The location(s) at which to evaluate the radiation, 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 (numpy.ndarray) – Array with the calculated derivatives. Has the shape (M,) + source_positions.shape[1:] + receiver_positions.shape[1:]. where M is the number of spatial derivatives, see num_spatial_derivatives and spatial_derivative_order.

spherical_harmonics(source_positions, source_normals, receiver_positions, *args, **kwargs)

Evaluate the spherical harmonics expansion at a point.

Mirrors the sources in the reflection plane and calculates the superposition of the expansions from the combined sources. For the full documentation of the parameters and output format, see the documentation of the spherical harmonics method of the underlying transducer model.

class levitate.transducers.PlaneWaveTransducer(freq=40000.0, p0=6, medium=Air(dynamic_viscosity=1.85e-05, rho=1.204082071218662, c=343.23714360505863), physical_size=0.01)

Class representing planar waves.

This is not representing a physical transducer per se, but a traveling plane wave.

pressure_derivs(source_positions, source_normals, receiver_positions, orders=3, **kwargs)

Calculate the spatial derivatives of the greens function.

Parameters

source_positions (numpy.ndarray) – The location of the transducer, as a (3, …) shape array.
source_normals (numpy.ndarray) – The look direction of the transducer, as a (3, …) shape array.
receiver_positions (numpy.ndarray) – The location(s) at which to evaluate the radiation, 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 (numpy.ndarray) – Array with the calculated derivatives. Has the shape ((M,) + source_positions.shape[1:] + receiver_positions.shape[1:]. where M is the number of spatial derivatives, see num_spatial_derivatives and spatial_derivative_order.

class levitate.transducers.CircularPiston(effective_radius, *args, **kwargs)

Circular piston transducer model.

Implementation of the circular piston directivity \(D(\theta) = 2 {J_1(ka\sin\theta) \over ka\sin\theta}\).

Parameters

effective_radius (float) – The radius \(a\) in the above.
**kwargs – See TransducerModel

Note

This class has no implementation of analytic jacobians yet, and is much slower to use than other models.

directivity(source_positions, source_normals, receiver_positions)

Evaluate transducer directivity.

Returns \(D(\theta) = 2 J_1(ka\sin\theta) / (ka\sin\theta)\) where \(a\) is the effective_radius of the transducer, \(k\) is the wavenumber of the transducer (k), \(\theta\) is the angle between the transducer normal and the vector from the transducer to the receiving point, and and \(J_1\) is the first order Bessel function.

Parameters

source_positions (numpy.ndarray) – The location of the transducer, as a (3, …) shape array.
source_normals (numpy.ndarray) – The look direction of the transducer, as a (3, …) shape array.
receiver_positions (numpy.ndarray) – The location(s) at which to evaluate the radiation, shape (3, …). The first dimension must have length 3 and represent the coordinates of the points.

Returns

out (numpy.ndarray) – The amplitude (and phase) of the directivity, shape source_positions.shape[1:] + receiver_positions.shape[1:].

class levitate.transducers.CircularRing(effective_radius, *args, **kwargs)

Circular ring transducer model.

Implementation of the circular ring directivity \(D(\theta) = J_0(ka\sin\theta)\).

Parameters

effective_radius (float) – The radius \(a\) in the above.
**kwargs – See TransducerModel

directivity(source_positions, source_normals, receiver_positions)

Evaluate transducer directivity.

Returns \(D(\theta) = J_0(ka\sin\theta)\) where \(a\) is the effective_radius of the transducer, \(k\) is the wavenumber of the transducer (k), \(\theta\) is the angle between the transducer normal and the vector from the transducer to the receiving point, and \(J_0\) is the zeroth order Bessel function.

Parameters

source_positions (numpy.ndarray) – The location of the transducer, as a (3, …) shape array.
source_normals (numpy.ndarray) – The look direction of the transducer, as a (3, …) shape array.
receiver_positions (numpy.ndarray) – The location(s) at which to evaluate the radiation, shape (3, …). The first dimension must have length 3 and represent the coordinates of the points.

Returns

out (numpy.ndarray) – The amplitude (and phase) of the directivity, shape source_positions.shape[1:] + receiver_positions.shape[1:].

directivity_derivatives(source_positions, source_normals, receiver_positions, orders=3)

Calculate the spatial derivatives of the directivity.

Explicit implementation of the derivatives of the directivity, based on analytical differentiation.

Parameters

source_positions (numpy.ndarray) – The location of the transducer, as a (3, …) shape array.
source_normals (numpy.ndarray) – The look direction of the transducer, as a (3, …) shape array.
receiver_positions (numpy.ndarray) – The location(s) at which to evaluate the radiation, 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 (numpy.ndarray) – Array with the calculated derivatives. Has the shape (M,) + source_positions.shape[1:] + receiver_positions.shape[1:]. where M is the number of spatial derivatives, see num_spatial_derivatives and spatial_derivative_order.