Utilities¶
Various utility functions.

class
sfs.util.
DelayedSignal
¶ Create new instance of DelayedSignal(data, samplerate, time)

data
¶ Alias for field number 0

samplerate
¶ Alias for field number 1

time
¶ Alias for field number 2


class
sfs.util.
XyzComponents
(components)¶ Triple (or pair) of components: x, y, and optionally z.
Instances of this class can be used to store coordinate grids (either regular grids like in
xyz_grid()
or arbitrary point clouds) or vector fields (e.g. particle velocity).This class is a subclass of
numpy.ndarray
. It is onedimensional (like a plainlist
) and has a length of 3 (or 2, if no zcomponent is available). It usesdtype=object
in order to be able to store othernumpy.ndarray
s of arbitrary shapes but also scalars, if needed. Because it is a NumPy array subclass, it can be used in operations with scalars and “normal” NumPy arrays, as long as they have a compatible shape. Like any NumPy array, instances of this class are iterable and can be used, e.g., in forloops and tuple unpacking. If slicing or broadcasting leads to an incompatible shape, a plainnumpy.ndarray
withdtype=object
is returned.To make sure the components are NumPy arrays themselves, use
as_xyz_components()
.Parameters: components ((3,) or (2,) array_like) – The values to be used as X, Y and Z data. Z is optional. 
apply
(func, *args, **kwargs)¶ Apply a function to each component.
The function func will be called once for each component, passing the current component as first argument. All further arguments are passed after that. The results are returned as a new
XyzComponents
object.

x
¶ xcomponent.

y
¶ ycomponent.

z
¶ zcomponent (optional).


sfs.util.
as_delayed_signal
(arg, **kwargs)¶ Make sure that the given argument can be used as a signal.
Parameters:  arg (sequence of 1 array_like followed by 1 or 2 scalars) – The first element is converted to a NumPy array, the second element is used as the sampling rate (in Hertz) and the optional third element is used as the starting time of the signal (in seconds). Default starting time is 0.
 **kwargs – All keyword arguments are forwarded to
numpy.asarray()
.
Returns: DelayedSignal
– A named tuple consisting of anumpy.ndarray
containing the audio data, followed by the sampling rate (in Hertz) and the starting time (in seconds) of the signal.Examples
Typically, this is used together with tuple unpacking to assign the audio data, the sampling rate and the starting time to separate variables:
>>> import sfs >>> sig = [1], 44100 >>> data, fs, signal_offset = sfs.util.as_delayed_signal(sig) >>> data array([1]) >>> fs 44100 >>> signal_offset 0

sfs.util.
as_xyz_components
(components, **kwargs)¶ Convert components to
XyzComponents
ofnumpy.ndarray
s.The components are first converted to NumPy arrays (using
numpy.asarray()
) which are then assembled into anXyzComponents
object.Parameters:  components (triple or pair of array_like) – The values to be used as X, Y and Z arrays. Z is optional.
 **kwargs – All further arguments are forwarded to
numpy.asarray()
, which is applied to the elements of components.

sfs.util.
asarray_1d
(a, **kwargs)¶ Squeeze the input and check if the result is onedimensional.
Returns a converted to a
numpy.ndarray
and stripped of all singleton dimensions. Scalars are “upgraded” to 1D arrays. The result must have exactly one dimension. If not, an error is raised.

sfs.util.
asarray_of_rows
(a, **kwargs)¶ Convert to 2D array, turn column vector into row vector.
Returns a converted to a
numpy.ndarray
and stripped of all singleton dimensions. If the result has exactly one dimension, it is reshaped into a 2D row vector.

sfs.util.
cart2sph
(x, y, z)¶ Cartesian to spherical coordinate transform.
\[\begin{split}\alpha = \arctan \left( \frac{y}{x} \right) \\ \beta = \arccos \left( \frac{z}{r} \right) \\ r = \sqrt{x^2 + y^2 + z^2}\end{split}\]with \(\alpha \in [0, 2\pi), \beta \in [0, \pi], r \geq 0\)
Parameters:  x (float or array_like) – xcomponent of Cartesian coordinates
 y (float or array_like) – ycomponent of Cartesian coordinates
 z (float or array_like) – zcomponent of Cartesian coordinates
Returns:  alpha (float or array_like) – Azimuth angle in radiants
 beta (float or array_like) – Elevation angle in radiants (with 0 denoting North pole)
 r (float or array_like) – Radius

sfs.util.
db
(x, power=False)¶ Convert x to decibel.
Parameters:  x (array_like) – Input data. Values of 0 lead to negative infinity.
 power (bool, optional) – If
power=False
(the default), x is squared before conversion.

sfs.util.
direction_vector
(alpha, beta=1.5707963267948966)¶ Compute normal vector from azimuth, colatitude.

sfs.util.
displacement
(v, omega)¶ Particle displacement
\[d(x, t) = \int_0^t v(x, t) dt\]

sfs.util.
image_sources_for_box
(x, L, N, prune=True)¶ Image source method for a cuboid room.
The classical method by Allen and Berkley [AB79].
Parameters:  x ((D,) array_like) – Original source location within box. Values between 0 and corresponding side length.
 L ((D,) array_like) – side lengths of room.
 N (int) – Maximum number of reflections per image source, see below.
 prune (bool, optional) – selection of image sources:
 If True (default): Returns all images reflected up to N times. This is the usual interpretation of N as “maximum order”.
 If False: Returns reflected up to N times between individual wall pairs, a total number of \(M := (2N+1)^D\). This larger set is useful e.g. to select image sources based on distance to listener, as suggested by [Bor84].
Returns:  xs ((M, D) array_like) – original & image source locations.
 wall_count ((M, 2D) array_like) – number of reflections at individual walls for each source.

sfs.util.
normalize
(p, grid, xnorm)¶ Normalize sound field wrt position xnorm.

sfs.util.
normalize_vector
(x)¶ Normalize a 1D vector.

sfs.util.
probe
(p, grid, x)¶ Determine the value at position x in the sound field p.

sfs.util.
rotation_matrix
(n1, n2)¶ Compute rotation matrix for rotation from n1 to n2.
Parameters: n1, n2 ((3,) array_like) – Two vectors. They don’t have to be normalized. Returns: (3, 3) numpy.ndarray – Rotation matrix.

sfs.util.
sph2cart
(alpha, beta, r)¶ Spherical to cartesian coordinate transform.
\[\begin{split}x = r \cos \alpha \sin \beta \\ y = r \sin \alpha \sin \beta \\ z = r \cos \beta\end{split}\]with \(\alpha \in [0, 2\pi), \beta \in [0, \pi], r \geq 0\)
Parameters:  alpha (float or array_like) – Azimuth angle in radiants
 beta (float or array_like) – Elevation angle in radiants (with 0 denoting North pole)
 r (float or array_like) – Radius
Returns:  x (float or array_like) – xcomponent of Cartesian coordinates
 y (float or array_like) – ycomponent of Cartesian coordinates
 z (float or array_like) – zcomponent of Cartesian coordinates

sfs.util.
spherical_hn2
(n, z)¶ Spherical Hankel function of 2nd kind.
Defined as http://dlmf.nist.gov/10.47.E6,
\[\hankel{2}{n}{z} = \sqrt{\frac{\pi}{2z}} \Hankel{2}{n + \frac{1}{2}}{z},\]where \(\Hankel{2}{n}{\cdot}\) is the Hankel function of the second kind and nth order, and \(z\) its complex argument.
Parameters:  n (array_like) – Order of the spherical Hankel function (n >= 0).
 z (array_like) – Argument of the spherical Hankel function.

sfs.util.
strict_arange
(start, stop, step=1, endpoint=False, dtype=None, **kwargs)¶ Like
numpy.arange()
, but compensating numeric errors.Unlike
numpy.arange()
, but similar tonumpy.linspace()
, providingendpoint=True
includes both endpoints.Parameters: start, stop, step, dtype – See
numpy.arange()
.endpoint – See
numpy.linspace()
.Note
With
endpoint=True
, the difference between start and end value must be an integer multiple of the corresponding spacing value!**kwargs – All further arguments are forwarded to
numpy.isclose()
.
Returns: numpy.ndarray – Array of evenly spaced values. See
numpy.arange()
.

sfs.util.
wavenumber
(omega, c=None)¶ Compute the wavenumber for a given radial frequency.

sfs.util.
xyz_grid
(x, y, z, spacing, endpoint=True, **kwargs)¶ Create a grid with given range and spacing.
Parameters:  x, y, z (float or pair of float) – Inclusive range of the respective coordinate or a single value if only a slice along this dimension is needed.
 spacing (float or triple of float) – Grid spacing. If a single value is specified, it is used for all dimensions, if multiple values are given, one value is used per dimension. If a dimension (x, y or z) has only a single value, the corresponding spacing is ignored.
 endpoint (bool, optional) – If
True
(the default), the endpoint of each range is included in the grid. UseFalse
to get a result similar tonumpy.arange()
. Seestrict_arange()
.  **kwargs – All further arguments are forwarded to
strict_arange()
.
Returns: XyzComponents
– A grid that can be used for sound field calculations.See also