Bases

Base functions used in spherical coordinates.

This module contains classes used to calculate and organize the required base functions for the Helmholtz equation in spherical coordinates. Theese can be used to reuse the calculation of base functions for repeated evaluation of some expansion coefficients at specific points in space.

`LegendrePolynomials`	Order only Legendre polynomials.
`AssociatedLegendrePolynomials`	Associated Legendre polynomials with both order and mode.
`RegularRadialBase`	Regular radial base, for interior problems.
`SingularRadialBase`	Singular radial base, for exterior problems.
`DualRadialBase`	Dual radial base, for interior and problems.
`SphericalHarmonics`	Spherical harmonics.
`RegularBase`	Regular multipole base, for interior problems.
`SingularBase`	Singular multipole base, for exterior problems.
`DualBase`	Dual multipole base, for interior and exterior problems.

class shetar.bases.LegendrePolynomials(order, position=None, colatitude=None, x=None, defer_evaluation=False)

Order only Legendre polynomials.

Parameters

order (int) – The highest order included for the base.
position (None, optional) – Position specifier, see coordinates for more info.
colatitude (None, optional) – Colatitude of a spatial position. Will be used as cos(colatitude) as the input to the base function.
x (None, optional) – Arbitrary input directly to the base function.
defer_evaluation (bool, optional) – Do not calculate the values upon initialization of the object.

class shetar.bases.AssociatedLegendrePolynomials(order, position=None, colatitude=None, x=None, defer_evaluation=False)

Associated Legendre polynomials with both order and mode.

Note that this is using an orthonormal definition of the basis functions, i.e. not the one traditionally found in textbooks.

See LegendrePolynomials for details on parameters.

class shetar.bases.RadialBaseClass(order, position=None, radius=None, wavenumber=None, defer_evaluation=False)

Parent class for all radial bases.

This class should not be instantiated, only inherited from.

Parameters

order (int) – The highest order included for the base.
position (None, optional) – Position specifier, see coordinates for more info.
radius (None, optional) – Radius where the base is evaluated, in meters.
wavenumber (None, optional) – Wavenumber where the base is evaluated, in rad/m.
defer_evaluation (bool, optional) – Do not calculate the values upon initialization of the object.

class shetar.bases.RegularRadialBase(order, position=None, radius=None, wavenumber=None, defer_evaluation=False)

Regular radial base, for interior problems.

This is also known as the spherical Bessel function. See RadialBaseClass for details on the parameters.

class shetar.bases.SingularRadialBase(order, position=None, radius=None, wavenumber=None, defer_evaluation=False)

Singular radial base, for exterior problems.

This is also known as the spherical Hankel function. See RadialBaseClass for details on the parameters.

class shetar.bases.DualRadialBase(order, position=None, radius=None, wavenumber=None, defer_evaluation=False)

Dual radial base, for interior and problems.

This calculates both the regular and singular radial base functions. See RadialBaseClass for details on the parameters.

class shetar.bases.SphericalHarmonics(order, position=None, colatitude=None, azimuth=None, defer_evaluation=False, *args, **kwargs)

Spherical harmonics.

This evaluate the (surface) spherical harmonics. The values are with the same phase and scaling conventions as e.g. scipy.

Parameters

order (int) – The highest order included for the base.
position (None, optional) – Position specifier, see coordinates for more info.
colatitude (None, optional) – Colatitude angle where to evaluate the spherical harmonics, in [0, π].
azimuth (None, optional) – Azimuth angle where to evaluate the spherical harmonics, in radians.
defer_evaluation (bool, optional) – Do not calculate the values upon initialization of the object.

class shetar.bases.MultipoleBase(order, position=None, wavenumber=None, radius=None, colatitude=None, azimuth=None, defer_evaluation=False)

Parent class for all multipole bases.

This class should not be instantiated, only inherited from.

Parameters

order (int) – The highest order included for the base.
position (None, optional) – Position specifier, see coordinates for more info.
wavenumber (None, optional) – Wavenumber where the base is evaluated, in rad/m.
radius (None, optional) – Radius where the base is evaluated, in meters.
colatitude (None, optional) – Colatitude angle where to evaluate the spherical harmonics, in [0, π].
azimuth (None, optional) – Azimuth angle where to evaluate the spherical harmonics, in radians.
defer_evaluation (bool, optional) – Do not calculate the values upon initialization of the object.

class shetar.bases.RegularBase(order, position=None, wavenumber=None, radius=None, colatitude=None, azimuth=None, defer_evaluation=False)

Regular multipole base, for interior problems.

See MultipoleBase for details on the parameters.

class shetar.bases.SingularBase(order, position=None, wavenumber=None, radius=None, colatitude=None, azimuth=None, defer_evaluation=False)

Singular multipole base, for exterior problems.

See MultipoleBase for details on the parameters.

class shetar.bases.DualBase(*args, **kwargs)

Dual multipole base, for interior and exterior problems.

This calculates both the singular and regular multipole bases. See MultipoleBase for details on the parameters.

Expansions

Organization of the various expansions coefficients.

This provides convenience classes for storing expansion coefficients with the cirrect indexing conventions for the package. There’s also a few functions which can create some commonly used expansions, e.g. monopoles or plane waves. The classes with an explicit domain also has methods to conveniently evaluate the expansion at some positions in space, or to apply certain transforms.

`Expansion`	Basic expansion without notion of domain.
`SphericalSurfaceExpansion`	Holds spherical harmonics expansions.
`InteriorExpansion`	Holds interior expansions.
`ExteriorExpansion`	Holds exterior expansions.
`plane_wave`	Create an expansion of a plane wave.
`monopole`	Create a monopole source expansion.
`circular_ring`	Create a circular ring source expansion.

class shetar.expansions.Expansion(order=None, data=None, wavenumber=None, shape=None)

Basic expansion without notion of domain.

This can be used as a plain holder for the coefficients which has both order and mode, e.g. spherical harmonics expansion coefficients. Instances of this class has no inherent notion of what is the correct base to use, so it cannot create them automatically.

Parameters

order (int) – The highest order included in the expansion. If instantiated with raw data, no order is required for the instantiated since it is calculated from the shape of the data. If data if not given, order is required and an all-zero expansion is created. If both data and order are given, the have to agree on the order.
data (array_like) – Raw data for expansion coefficients. Has to have the correct indexing conventions with the coefficient axis last.
wavenumber (None, optional) – Optional wavenumber of the expansion. This has to be broadcastable with the spatial shape of the data.
shape (None, optional) – Spatial shape for all-zero expansions. If both data and shape are given, the have to agree on the spatial shape.

class shetar.expansions.SphericalSurfaceExpansion(order=None, data=None, wavenumber=None, shape=None)

Holds spherical harmonics expansions.

Expansion corresponding to SphericalHarmonics basis functions. These are defined on the surface of a sphere, and can be used to expand arbitrary functions.

See Expansion for parameters and more methods.

class shetar.expansions.InteriorExpansion(order=None, data=None, wavenumber=None, shape=None)

Holds interior expansions.

Expansion corresponding to RegularBase basis functions. These expansions are well defined when all sources are outside the region of evaluation. This means that the evaluation radius is smaller than the distance to the closest source, e.g. an incident sound field.

See Expansion for parameters and more methods.

class shetar.expansions.ExteriorExpansion(order=None, data=None, wavenumber=None, shape=None)

Holds exterior expansions.

Expansion corresponding to SingularBase basis functions. These expansions are well defined when all sources are contained within the region closer to the origin than the evaluation domain. This means that the evaluation radius has to be larger than the distance to the closest source, e.g. a source at the origin.

See Expansion for parameters and more methods.

shetar.expansions.plane_wave(order, strength=1, colatitude=None, azimuth=None, wavenumber=None, wavevector=None)

Create an expansion of a plane wave.

A plane wave has the field

\[q \exp{(i \vec k \cdot \vec r)}\]

where \(\vec r\) is the position in the field, and \(\vec k\) is the wavevector.

The propagation direction of the plane wave can be specified using either a wavevector, or by colatitude, azimuth, and wavenumber.

Parameters

order (int) – The highest order included in the expansion.
strength (numerical, default 1) – The strength of the source, \(q\) in the above definition.
colatitude (None, optional) – Colatitude propagation angle of the wave.
azimuth (None, optional) – Azimuth propagation direction of the wave.
wavenumber (None, optional) – Wavenumber of the propagating wave, \(k\) in the above definition.
wavevector (None, optional) – Wavevector, i.e. both wavenumber and propagation direction for the wave. This will override the separate parameters if given.

Returns

InteriorExpansion – The expansion of a plane wave is always an interior sound field.

shetar.expansions.monopole(strength=1, order=0, wavenumber=1, position=None, domain='exterior')

Create a monopole source expansion.

A monopole has the field

\[\frac{q}{4 \pi r} \exp{(ikr)}\]

where \(r\) is the distance between the source and the evaluation position.

Parameters

strength (numerical, default 1) – Strength or the source, \(q\) in the above definition.
order (int, default 0) – This can be used to return higher orders than needed for untranslated expansions, or to controll the output order of the translation.
wavenumber (numerical, default 1) – The wavenumber of the source, \(k\) in the above definition.
position (None, optional) – Position specifier for translation, see coordinates for more info. If given, the expansion will represent a monopole at this position.
domain (str, optional) – Domain of translated expansions. Depending on where the resulting expansion should be evaluated, the target domain should be specified. If domain='exterior' (default), an exterior expansion will be returned, i.e. an expansion which is valid further away from the origin than the source location. Thus, the expansion should be evaluated using the singular bases, and in the exterior domain. If domain='interior', an interior expansion will be returned, i.e. an expansion which is valid closer to from the origin than the source location. Thus, the expansion should be evaluated using the regular bases, and in the interior domain. A monopole at the origin (position=None) is always an exterior expansion.

Returns

ExteriorExpansion or InteriorExpansion – See the domain documentation.

shetar.expansions.circular_ring(order, radius, strength=1, colatitude=None, azimuth=None, wavenumber=None, wavevector=None, position=None, domain='exterior', source_order=None)

Create a circular ring source expansion.

The returns the expansion coefficients corresponding to a circular ring. In the far-field, this has the directivity

\[\frac{q}{4\pi} J_0(ka\sin\theta) \exp{ikr}\]

where \(J_0\) is the zeroth order Bessel function, \(r\) is the distance from the source, and \(\theta\) is the angle between the position vector and the source normal.

Parameters

order (int) – The output order for the source.
radius (float) – The effective radius of the source, \(a\) in the above definition.
strength (numerical, default 1) – Strength of the source, \(q\) in the above definition.
colatitude (None, optional) – Colatitude angle of the normal of the source.
azimuth (None, optional) – Azimuth angle of the normal of the source.
wavenumber (float, optional) – Wavenumber if the sound field, \(k\) in the above definition.
wavevector (None, optional) – Wavevector, i.e. both wavenumber and propagation direction for the wave. This will override the separate parameters if given.
position (None, optional) – Position specifier for translation, see coordinates for more info. If given, the expansion will represent a source at this position.
domain (str, optional) – Domain of translated expansions. Depending on where the resulting expansion should be evaluated, the target domain should be specified. If domain='exterior' (default), an exterior expansion will be returned, i.e. an expansion which is valid further away from the origin than the source location. Thus, the expansion should be evaluated using the singular bases, and in the exterior domain. If domain='interior', an interior expansion will be returned, i.e. an expansion which is valid closer to from the origin than the source location. Thus, the expansion should be evaluated using the regular bases, and in the interior domain. A monopole at the origin (position=None) is always an exterior expansion.
source_order (int, optional) – Only used for translated expansions. The source order argument can be used in combination with the position argument to use a different expansion order for the initial source expansion before the translation is applied.

Returns

ExteriorExpansion or InteriorExpansion – See the domain documentation.

Transforms

Spatial transforms for expansions.

Spatial transforms are operations that work on expansions to express the same field but with a different coordinate system. The can be used in two ways: 1) To find expansion coefficients of a physical field after undergoing some physical transform, e.g. by moving a source. 2) To find the expansion coefficients of the same physical field but in a different mathematical coordinate system, e.g. as measured at a different point in space. These wto operations are closely linked, and are often the inverse of each other. This means that the expansion coefficients of an “input” expansion after undergoing a movement of the field by \(\vec x\) are the same as the expansion coefficients of the same “input” field expanded at a new origin \(-\vec x\). The default operation here is that of translating the field, e.g. a field created by a source at [1, 2, 3] translated by [4, 5, 6] will have the same expansion coefficients at the field from the source placed at [5, 7, 9].

The transforms are handled with a number of classes listed below. Rotations are either just a colatitude rotation, or a full rotation of the field. Translations are implemented along the z-axis only, for lower computational cost. General translations are handled as a sequence of rotation->coaxial translation->rotation. For full controll of an arbitrary transform, use the rotation and coaxial transslation classes instead of the translation classes.

A translation can be done either within a domain, or from the exterior domain to the interior domain. Take care to use the correct class to preserve the validity of the input expansion at the desired evaluation domain for the output expansion. There is often larger errors in the translations near the boundary of the region of validity. Take extra care if this region is of interest.

`ColatitudeRotation`	Organizes rotations for colatitude directions.
`Rotation`	Organizes arbitrary rotations.
`CoaxialTranslation`	Patent class for coaxial translations.
`InteriorCoaxialTranslation`	Handles translations in the interior domain.
`ExteriorCoaxialTranslation`	Handles translations in the exterior domain.
`ExteriorInteriorCoaxialTranslation`	Handles translations in the between domains.
`Translation`	Parent class for translations.
`InteriorTranslation`	Handles translations in the interior domain.
`ExteriorTranslation`	Handles translations in the exterior domain.
`ExteriorInteriorTranslation`	Handles translations in the between domains.

class shetar.transforms.ColatitudeRotation(order, position=None, colatitude=None, defer_evaluation=False)

Organizes rotations for colatitude directions.

Parameters

order (int) – The highest order for the rotation. Rotations are performed at constant order, so the order of the input expansion and the output expansion are kept the same.
position (optional) – Position specifier for the rotation, see shetar.coordinates.Rotation.
colatitude (float, optional) – Angle in radians by which to rotate.
defer_evaluation (bool, optional) – Do not calculate the values upon initialization of the object.

class shetar.transforms.Rotation(order, position=None, colatitude=None, azimuth=None, secondary_azimuth=None, new_z_axis=None, old_z_axis=None, defer_evaluation=False)

Organizes arbitrary rotations.

This handles rotations with both a colatitude and two azimuth parts. For details on how the two azimuth angles interplay with the colatitude angle, refer to the examples.

See ColatitudeRotation and shetar.coordinates.Rotation for details on the parameters.

class shetar.transforms.CoaxialTranslation(orders, position=None, radius=None, wavenumber=None, defer_evaluation=False)

Patent class for coaxial translations.

This class should not be instantiated, only inherited from.

Parameters

orders (int or (int, int)) – The orders between which the translation takes place. If given as a single value, it is used for both orders. If given as two values, a mixed order translation is evaluated.
position – Position specifier, see shetar.coordinates.Translation.
radius (float) – Distance to translate, see shetar.coordinates.Translation.
wavenumber (float) – The wavenumber that the translation operates at.
defer_evaluation (bool, optional) – Do not calculate the values upon initialization of the object.

class shetar.transforms.InteriorCoaxialTranslation(orders, position=None, radius=None, wavenumber=None, defer_evaluation=False)

Handles translations in the interior domain.

This applies translations from an interior translation to an interior translation.

See CoaxialTranslation and shetar.coordinates.Translation for details on parameters.

class shetar.transforms.ExteriorCoaxialTranslation(orders, position=None, radius=None, wavenumber=None, defer_evaluation=False)

Handles translations in the exterior domain.

This applies translations from an exterior translation to an exterior translation.

See CoaxialTranslation and shetar.coordinates.Translation for details on parameters.

class shetar.transforms.ExteriorInteriorCoaxialTranslation(orders, position=None, radius=None, wavenumber=None, defer_evaluation=False)

Handles translations in the between domains.

This applies translations from an exterior translation to an interior translation.

See CoaxialTranslation and shetar.coordinates.Translation for details on parameters.

class shetar.transforms.Translation(orders, position=None, wavenumber=None, radius=None, colatitude=None, azimuth=None, defer_evaluation=False)

Parent class for translations.

This class should not be instantiated, only inherited from.

See shetar.coordinates.Translation and CoaxialTranslation for details on parameters.

class shetar.transforms.InteriorTranslation(orders, position=None, wavenumber=None, radius=None, colatitude=None, azimuth=None, defer_evaluation=False)

Handles translations in the interior domain.

This applies translations from an interior translation to an interior translation.

See CoaxialTranslation and shetar.coordinates.Translation for details on parameters.

class shetar.transforms.ExteriorTranslation(orders, position=None, wavenumber=None, radius=None, colatitude=None, azimuth=None, defer_evaluation=False)

Handles translations in the exterior domain.

This applies translations from an exterior translation to an exterior translation.

See CoaxialTranslation and shetar.coordinates.Translation for details on parameters.

class shetar.transforms.ExteriorInteriorTranslation(orders, position=None, wavenumber=None, radius=None, colatitude=None, azimuth=None, defer_evaluation=False)

Handles translations in the between domains.

This applies translations from an exterior translation to an interior translation.

See CoaxialTranslation and shetar.coordinates.Translation for details on parameters.