Field Wrappers

Class list

Public API

These are the only classes and functions regarded as part of the public API, but they will only be used directly when implementing new algorithm types.

class levitate.fields._wrappers.FieldImplementation(array)

Base class for FieldImplementations.

The attributes listed below are part of the API and should be implemented in subclasses.

Parameters

array (TransducerArray) – The array object to use for calculations.

Variables

~FieldImplementation.values_require (dict) – Each key in this dictionary specifies a requirement for the values method. The wrapper classes will manage calling the method with the specified arguments.
~FieldImplementation.jacobians_require (dict) – Each key in this dictionary specifies a requirement for the jacobians method. The wrapper classes will manage calling the method with the specified arguments.

values(): Method to calculate the value(s) for the field.

jacobians(): Method to calculate the jacobians for the field. This method is optional if the implementation is not used as a cost function in optimizations.

Parameters: array (TransducerArray) – The object modeling the array.

class requirement(*args, **kwargs)

Parse a set of requirements.

FieldImplementation objects should define requirements for values and jacobians. This class parses the requirements and checks that the request can be met upon call. The requirements are stored as a non-mutable custom dictionary. Requirements can be added to each other to find the combined requirements.

Keyword Arguments

complex_transducer_amplitudes – The field requires the actual complex transducer amplitudes directly. This is a fallback requirement when it is not possible to implement the field with the other requirements, and no performance optimization is possible.
pressure_derivs_summed – The number of orders of Cartesian spatial derivatives of the total sound pressure field. Currently implemented to third order derivatives. See levitate._indexing.pressure_derivs_order and levitate._indexing.num_pressure_derivs for a description of the structure.
pressure_derivs_summed – Like pressure_derivs_summed, but for individual transducers.
spherical_harmonics_summed – A spherical harmonics decomposition of the total sound pressure field, up to and including the order specified. where remaining dimensions are determined by the positions.
spherical_harmonics_individual – Like spherical_harmonics_summed, but for individual transducers.

Raises

NotImplementedError – If one or more of the requested keys is not implemented.

Basic Types

class levitate.fields._wrappers.Field(field, **kwargs)

Primary class for single point, single field.

This is a wrapper class for FieldImplementation to simplify the manipulation and evaluation of the implemented fields. Normally it is not necessary to manually create the wrapper, since it should be done automagically. Many properties are inherited from the underlying field implementation, e.g. ndim, array, values, jacobians.

Parameters: field (FieldImplementation) – The implemented field to use for calculations.

__call__(complex_transducer_amplitudes, position)

Evaluate the field implementation.

Parameters

compelx_transducer_amplitudes (complex numpy.ndarray) – Complex representation of the transducer phases and amplitudes of the array used to create the field.
position (array-like) – The position(s) where to evaluate the field. The first dimension needs to have 3 elements.

Returns

values (ndarray) – The values of the implemented field used to create the wrapper.

class levitate.fields._wrappers.FieldPoint(field, position, **kwargs)

Position-bound class for single point, single field.

See Field for more precise description.

Parameters

field (FieldImplementation) – The implemented field to use for calculations.
position (numpy.ndarray) – The position to bind to.

__call__(complex_transducer_amplitudes)

Evaluate the field implementation.

Parameters: compelx_transducer_amplitudes (complex numpy.ndarray) – Complex representation of the transducer phases and amplitudes of the array used to create the field.
Returns: values (ndarray) – The values of the implemented field used to create the wrapper.

Magnitude Squared Types

MultiFields

class levitate.fields._wrappers.MultiField(*fields, **kwargs)

Class for multiple fields, single position calculations.

This class collects multiple Field objects for simultaneous evaluation at the same position(s). Since the fields can use the same spatial structures this is more efficient than to evaluate all the fields one by one.

Parameters: *fields (Field) – Any number of Field objects.

__call__(complex_transducer_amplitudes, position)

Evaluate all fields.

Parameters

complex_transducer_amplitudes (complex numpy.ndarray) – Complex representation of the transducer phases and amplitudes of the array used to create the field.
position (array-like) – The position(s) where to evaluate the fields. The first dimension needs to have 3 elements.

Returns

values (list) – A list of the return values from the individual fields. Depending on the number of dimensions of the fields, the arrays in the list might not have compatible shapes.

class levitate.fields._wrappers.MultiFieldPoint(*fields, **kwargs)

Class for multiple field, single fixed position calculations.

This class collects multiple FieldPoint bound to the same position(s) for simultaneous evaluation. Since the fields can use the same spatial structures this is more efficient than to evaluate all the fields one by one.

Parameters: *fields (FieldPoint) – Any number of FieldPoint objects.

Warning

If the class is initialized with fields bound to different points, some of the fields are simply discarded.

__call__(complex_transducer_amplitudes)

Evaluate all fields.

Parameters: compelx_transducer_amplitudes (complex numpy.ndarray) – Complex representation of the transducer phases and amplitudes of the array used to create the field.
Returns: values (list) – A list of the return values from the individual fields. Depending on the number of dimensions of the fields, the arrays in the list might not have compatible shapes.

MultiPoints

Private Classes

These classes are not considered part of the public API, and should not appear other than as superclasses.

class levitate.fields._wrappers.FieldBase(*, transforms=None)

Base class for all field type objects.

This wraps a few common procedures for fields, primarily dealing with preparation and evaluation of requirements for fields implementations. The fields support some numeric manipulations to simplify the creation of variants of the basic types. Not all types of fields support all operations, and the order of operation can matter in some cases. If unsure if the arithmetics return the desired outcome, print the resulting object to inspect the new structure.

Note

This class should not be instantiated directly.

class levitate.fields._wrappers.FieldImplementationMeta(clsname, bases, attrs)

Metaclass to wrap FieldImplementation objects in Field objects.

API-wise it is nice to call the implementation classes when requesting a field. Since the behavior of the objects should change depending on if they are added etc, it would be very difficult to keep track of both the current state and the actual field in the same top level object. This class will upon object creation instantiate the called class, but also instantiate and return a Field-type object.

__call__(*cls_args, **cls_kwargs)

Instantiate an Field-type object, using the cls as the base field implementation.

The actual Field-type will be chosen based on which optional parameters are passed. If no parameters are passed (default) a Field object is returned. If weight is passed a CostField object is returned. If position is passed a FieldPoint object is returned. If both weight and position is passed a CostFieldPoint object is returned.

Parameters

cls (class) – The FieldImplementation class to use for calculations.
*cls_args – Args passed to the cls.
**cls_kwargs – Keyword arguments passed to cls.