`fbeamform`#

Implements beamformers in the frequency domain.

`SteeringVector`	Basic class for implementing steering vectors with monopole source transfer models.
`BeamformerBase`	Beamforming using the basic delay-and-sum algorithm in the frequency domain.
`BeamformerFunctional`	Functional beamforming algorithm.
`BeamformerCapon`	Beamforming using the Capon (Mininimum Variance) algorithm.
`BeamformerEig`	Beamforming using eigenvalue and eigenvector techniques.
`BeamformerMusic`	Beamforming using the MUSIC algorithm.
`BeamformerClean`	CLEAN deconvolution algorithm.
`BeamformerDamas`	DAMAS deconvolution algorithm.
`BeamformerDamasPlus`	DAMAS deconvolution [2] for solving the system of equations.
`BeamformerOrth`	Orthogonal deconvolution algorithm.
`BeamformerCleansc`	CLEAN-SC deconvolution algorithm.
`BeamformerCMF`	Covariance Matrix Fitting algorithm.
`BeamformerSODIX`	Source directivity modeling in the cross-spectral matrix (SODIX) algorithm.
`BeamformerGIB`	Beamforming GIB methods with different normalizations.
`BeamformerAdaptiveGrid`	Abstract base class for array methods without predefined grid.
`BeamformerGridlessOrth`	Orthogonal beamforming without predefined grid.
`PointSpreadFunction`	The point spread function.
`L_p`(x)	Calculates the sound pressure level from the squared sound pressure.
`integrate`(data, grid, sector)	Integrates a sound pressure map over a given sector.

class acoular.fbeamform.SteeringVector#

Bases: HasStrictTraits

Basic class for implementing steering vectors with monopole source transfer models.

Handles four different steering vector formulations. See [3] for details.

grid = Instance(Grid, desc='beamforming grid')#: Grid-derived object that provides the grid locations.

mics = Instance(MicGeom, desc='microphone geometry')#: MicGeom object that provides the microphone locations.

steer_type = Enum('true level', 'true location', 'classic', 'inverse', desc='type of steering vectors used')#: Type of steering vectors, see also [3]. Defaults to ‘true level’.

env = Instance(Environment(), Environment)#: Environment or derived object, which provides information about the sound propagation in the medium. Defaults to standard Environment object.

ref = Property(desc='reference position or distance')#: Reference position or distance at which to evaluate the sound pressure of a grid point. If set to a scalar, this is used as reference distance to the grid points. If set to a vector, this is interpreted as x,y,z coordinates of the reference position. Defaults to [0.,0.,0.].

transfer(f, ind=None)#

Calculates the transfer matrix for one frequency.

Parameters:

ffloat: Frequency for which to calculate the transfer matrix
ind(optional) array of ints: If set, only the transfer function of the gridpoints addressed by the given indices will be calculated. Useful for algorithms like CLEAN-SC, where not the full transfer matrix is needed

Returns:

array of complex128: array of shape (ngridpts, nmics) containing the transfer matrix for the given frequency

steer_vector(f, ind=None)#

Calculates the steering vectors based on the transfer function.

See also [3].

Parameters:

ffloat: Frequency for which to calculate the transfer matrix
ind(optional) array of ints: If set, only the steering vectors of the gridpoints addressed by the given indices will be calculated. Useful for algorithms like CLEAN-SC, where not the full transfer matrix is needed

Returns:

array of complex128: array of shape (ngridpts, nmics) containing the steering vectors for the given frequency

class acoular.fbeamform.LazyBfResult(bf)#

Bases: object

Manages lazy per-frequency evaluation.

class acoular.fbeamform.BeamformerBase#

Bases: HasStrictTraits

Beamforming using the basic delay-and-sum algorithm in the frequency domain.

freq_data = Instance(PowerSpectra, desc='freq data object')#: PowerSpectra object that provides the cross spectral matrix and eigenvalues

r_diag = Bool(True, desc='removal of diagonal')#: Boolean flag, if ‘True’ (default), the main diagonal is removed before beamforming.

r_diag_norm = Float( …#: If r_diag==True: if r_diag_norm==0.0, the standard normalization = num_mics/(num_mics-1) is used. If r_diag_norm !=0.0, the user input is used instead. If r_diag==False, the normalization is 1.0 either way.

precision = Enum('float64', 'float32', desc='precision (32/64 Bit) of result, corresponding to numpy dtypes')#: Floating point precision of property result. Corresponding to numpy dtypes. Default = 64 Bit.

cached = Bool(True, desc='cached flag')#: Boolean flag, if ‘True’ (default), the result is cached in h5 files.

result = Property(desc='beamforming result')#: The beamforming result as squared sound pressure values at all grid point locations (readonly). Returns a (number of frequencies, number of gridpoints) array-like of floats. Values can only be accessed via the index operator [].

sig_loss_norm()#

If the diagonal of the CSM is removed one has to handle the loss of signal energy.

Done via a normalization factor.

synthetic(f, num=0)#

Evaluates the beamforming result for an arbitrary frequency band.

Parameters:

f: float

Band center frequency.

numinteger

Controls the width of the frequency bands considered; defaults to 0 (single frequency line).

num	frequency band width
0	single frequency line
1	octave band
3	third-octave band
n	1/n-octave band

Returns:

array of floats: The synthesized frequency band values of the beamforming result at each grid point . Note that the frequency resolution and therefore the bandwidth represented by a single frequency line depends on the sampling frequency and used FFT block size.

integrate(sector, frange=None, num=0)#

Integrates result map over a given sector.

Parameters:

sector: array of floats or :class:`~acoular.grids.Sector`

either an array, tuple or list with arguments for the ‘indices’ method of a Grid-derived class (e.g. RectGrid.indices or RectGrid3D.indices). Possible sectors would be array([xmin, ymin, xmax, ymax]) or array([x, y, radius]) or an instance of a Sector-derived class

frange: tuple or None

a tuple of (fmin,fmax) frequencies to include in the result if num*==0, or band center frequency/frequencies for which to return the results if *num>0; if None, then the frequency range is determined from the settings of the PowerSpectra.ind_low and PowerSpectra.ind_high of freq_data

numinteger

Controls the width of the frequency bands considered; defaults to 0 (single frequency line). Only considered if frange is not None.

num	frequency band width
0	single frequency line
1	octave band
3	third-octave band
n	1/n-octave band

Returns:

res or (f, res): array of floats or tuple(array of floats, array of floats): If frange*==None or *num>0, the spectrum (all calculated frequency bands) for the integrated sector is returned as res. The dimension of this array is the number of frequencies given by freq_data and entries not computed are zero. If frange!=None and num*==0, then (f, res) is returned where *f are the (band) frequencies and the dimension of both arrays is determined from frange

class acoular.fbeamform.BeamformerFunctional#

Bases: BeamformerBase

Functional beamforming algorithm.

See [4] for details.

gamma = Float(1, desc='functional exponent')#: Functional exponent, defaults to 1 (= Classic Beamforming).

r_diag = Enum(False, desc='False, as Functional Beamformer is only well defined for the full CSM')#: Functional Beamforming is only well defined for full CSM

r_diag_norm = Enum( …#: Normalization factor in case of CSM diagonal removal. Defaults to 1.0 since Functional Beamforming is only well defined for full CSM.

class acoular.fbeamform.BeamformerCapon#

Bases: BeamformerBase

Beamforming using the Capon (Mininimum Variance) algorithm.

See [5] for details.

r_diag_norm = Enum( …#: Normalization factor in case of CSM diagonal removal. Defaults to 1.0 since Beamformer Capon is only well defined for full CSM.

class acoular.fbeamform.BeamformerEig#

Bases: BeamformerBase

Beamforming using eigenvalue and eigenvector techniques.

See [6] for details.

n = Int(-1, desc='No. of eigenvalue')#: Number of component to calculate: 0 (smallest) … num_channels-1; defaults to -1, i.e. num_channels-1

class acoular.fbeamform.BeamformerMusic#

Bases: BeamformerEig

Beamforming using the MUSIC algorithm.

See [7] for details.

r_diag_norm = Enum( …#: Normalization factor in case of CSM diagonal removal. Defaults to 1.0 since BeamformerMusic is only well defined for full CSM.

class acoular.fbeamform.PointSpreadFunction#

Bases: HasStrictTraits

The point spread function.

This class provides tools to calculate the PSF depending on the used microphone geometry, focus grid, flow environment, etc. The PSF is needed by several deconvolution algorithms to correct the aberrations when using simple delay-and-sum beamforming.

grid_indices = CArray( …#: Indices of grid points to calculate the PSF for.

calcmode = Enum('single', 'block', 'full', 'readonly', desc='mode of calculation / storage')#

Flag that defines how to calculate and store the point spread function defaults to ‘single’.

‘full’: Calculate the full PSF (for all grid points) in one go (should be used if the PSF
at all grid points is needed, as with DAMAS)
‘single’: Calculate the PSF for the grid points defined by grid_indices, one by one
(useful if not all PSFs are needed, as with CLEAN)
‘block’: Calculate the PSF for the grid points defined by grid_indices, in one go
(useful if not all PSFs are needed, as with CLEAN)
‘readonly’: Do not attempt to calculate the PSF since it should already be cached (useful
if multiple processes have to access the cache file)

precision = Enum('float64', 'float32', desc='precision (32/64 Bit) of result, corresponding to numpy dtypes')#: Floating point precision of property psf. Corresponding to numpy dtypes. Default = 64 Bit.

psf = Property(desc='point spread function')#: The actual point spread function.

freq = Float(1.0, desc='frequency')#: Frequency to evaluate the PSF for; defaults to 1.0.

calc_psf(ac, gp)#: point-spread function calculation.

class acoular.fbeamform.BeamformerDamas#

Bases: BeamformerBase

DAMAS deconvolution algorithm.

See [2] for details.

psf_precision = Enum('float64', 'float32', desc='precision of PSF')#: The floating-number-precision of the PSFs. Default is 64 bit.

n_iter = Int(100, desc='number of iterations')#: Number of iterations, defaults to 100.

damp = Float(1.0, desc='damping factor in modified gauss-seidel-DAMAS-approach')#: Damping factor in modified gauss-seidel

calcmode = Enum('full', 'single', 'block', 'readonly', desc='mode of psf calculation / storage')#: Flag that defines how to calculate and store the point spread function, defaults to ‘full’. See PointSpreadFunction.calcmode for details.

class acoular.fbeamform.BeamformerDamasPlus#

Bases: BeamformerDamas

DAMAS deconvolution [2] for solving the system of equations.

Instead of the original Gauss-Seidel iterations, this class employs the NNLS or linear programming solvers from scipy.optimize or one of several optimization algorithms from the scikit-learn module. Needs a-priori delay-and-sum beamforming (BeamformerBase).

method = Enum('NNLS', 'LP', 'LassoLars', 'OMPCV', desc='method used for solving deconvolution problem')#: Type of fit method to be used (‘LassoLars’, ‘OMPCV’, ‘LP’, or ‘NNLS’, defaults to ‘NNLS’). These methods are implemented in the scikit-learn module or within scipy.optimize respectively.

n_iter = Int(500, desc='maximum number of iterations')#: Maximum number of iterations, tradeoff between speed and precision; defaults to 500

unit_mult = Float(1e9, desc='unit multiplier')#: Unit multiplier for evaluating, e.g., nPa instead of Pa. Values are converted back before returning. Temporary conversion may be necessary to not reach machine epsilon within fitting method algorithms. Defaults to 1e9.

class acoular.fbeamform.BeamformerOrth#

Bases: BeamformerBase

Orthogonal deconvolution algorithm.

See [8] for details. New faster implementation without explicit (BeamformerEig).

eva_list = CArray(dtype=int, value=np.array([-1]), desc='components')#: List of components to consider, use this to directly set the eigenvalues used in the beamformer. Alternatively, set n.

n = Int(1)#: Number of components to consider, defaults to 1. If set, eva_list will contain the indices of the n largest eigenvalues. Setting eva_list afterwards will override this value.

class acoular.fbeamform.BeamformerCleansc#

Bases: BeamformerBase

CLEAN-SC deconvolution algorithm.

See [9] for details. Classic delay-and-sum beamforming is already included.

n_iter = Int(0, desc='no of iterations')#: no of CLEAN-SC iterations defaults to 0, i.e. automatic (max 2*num_channels)

damp = Range(0.01, 1.0, 0.6, desc='damping factor')#: iteration damping factor defaults to 0.6

stopn = Int(3, desc='stop criterion index')#: iteration stop criterion for automatic detection iteration stops if power[i]>power[i-stopn] defaults to 3

class acoular.fbeamform.BeamformerClean#

Bases: BeamformerBase

CLEAN deconvolution algorithm.

See [10] for details.

psf_precision = Enum('float64', 'float32', desc='precision of PSF.')#: The floating-number-precision of the PSFs. Default is 64 bit.

class acoular.fbeamform.BeamformerCMF#

Bases: BeamformerBase

Covariance Matrix Fitting algorithm.

This is not really a beamformer, but an inverse method. See [11] for details.

method = Enum( …#: Type of fit method to be used (‘LassoLars’, ‘LassoLarsBIC’, ‘OMPCV’ or ‘NNLS’, defaults to ‘LassoLars’). These methods are implemented in the scikit-learn module.

alpha = Range(0.0, 1.0, 0.0, desc='Lasso weight factor')#: Weight factor for LassoLars method, defaults to 0.0. (Use values in the order of 10^⁻9 for good results.)

n_iter = Int(500, desc='maximum number of iterations')#: Total or maximum number of iterations (depending on method), tradeoff between speed and precision; defaults to 500

unit_mult = Float(1e9, desc='unit multiplier')#: Unit multiplier for evaluating, e.g., nPa instead of Pa. Values are converted back before returning. Temporary conversion may be necessary to not reach machine epsilon within fitting method algorithms. Defaults to 1e9.

show = Bool(False, desc='show output of PyLops solvers')#: If True, shows the status of the PyLops solver. Only relevant in case of FISTA or Split_Bregman

r_diag_norm = Enum( …#: Energy normalization in case of diagonal removal not implemented for inverse methods.

class acoular.fbeamform.BeamformerSODIX#

Bases: BeamformerBase

Source directivity modeling in the cross-spectral matrix (SODIX) algorithm.

See [12] and [13] for details.

method = Enum('fmin_l_bfgs_b', desc='fit method used')#: Type of fit method to be used (‘fmin_l_bfgs_b’). These methods are implemented in the scipy module.

n_iter = Int(200, desc='maximum number of iterations')#: Maximum number of iterations, tradeoff between speed and precision; defaults to 200

alpha = Range(0.0, 1.0, 0.0, desc='regularization factor')#: Weight factor for regularization, defaults to 0.0.

unit_mult = Float(1e9, desc='unit multiplier')#: Unit multiplier for evaluating, e.g., nPa instead of Pa. Values are converted back before returning. Temporary conversion may be necessary to not reach machine epsilon within fitting method algorithms. Defaults to 1e9.

r_diag_norm = Enum( …#: Energy normalization in case of diagonal removal not implemented for inverse methods.

class acoular.fbeamform.BeamformerGIB#

Bases: BeamformerEig

Beamforming GIB methods with different normalizations.

See [14] for details.

unit_mult = Float(1e9, desc='unit multiplier')#: Unit multiplier for evaluating, e.g., nPa instead of Pa. Values are converted back before returning. Temporary conversion may be necessary to not reach machine epsilon within fitting method algorithms. Defaults to 1e9.

n_iter = Int(10, desc='maximum number of iterations')#: Total or maximum number of iterations (depending on method), tradeoff between speed and precision; defaults to 10

method = Enum( …#: Type of fit method to be used (‘Suzuki’, ‘LassoLars’, ‘LassoLarsCV’, ‘LassoLarsBIC’, ‘OMPCV’ or ‘NNLS’, defaults to ‘Suzuki’). These methods are implemented in the scikit-learn module.

alpha = Range(0.0, 1.0, 0.0, desc='Lasso weight factor')#: Weight factor for LassoLars method, defaults to 0.0.

pnorm = Float(1, desc='Norm for regularization')#: Norm to consider for the regularization in InverseIRLS and Suzuki methods defaults to L-1 Norm

beta = Float(0.9, desc='fraction of sources maintained')#: Beta - Fraction of sources maintained after each iteration defaults to 0.9

eps_perc = Float(0.05, desc='regularization parameter')#: eps - Regularization parameter for Suzuki algorithm defaults to 0.05.

r_diag_norm = Enum( …#: Energy normalization in case of diagonal removal not implemented for inverse methods.

class acoular.fbeamform.BeamformerAdaptiveGrid#

Bases: BeamformerBase, Grid

Abstract base class for array methods without predefined grid.

integrate(sector)#

Integrates result map over a given sector.

Parameters:

sector: :class:`~acoular.grids.Sector` or derived: Gives the sector over which to integrate

Returns:

array of floats: The spectrum (all calculated frequency bands) for the integrated sector.

class acoular.fbeamform.BeamformerGridlessOrth#

Bases: BeamformerAdaptiveGrid

Orthogonal beamforming without predefined grid.

See [15] for details.

eva_list = CArray(dtype=int, value=np.array([-1]), desc='components')#: List of components to consider, use this to directly set the eigenvalues used in the beamformer. Alternatively, set n.

n = Int(1)#: Number of components to consider, defaults to 1. If set, eva_list will contain the indices of the n largest eigenvalues. Setting eva_list afterwards will override this value.

bounds = List(Tuple(Float, Float), minlen=3, maxlen=3, value=[(-1.0, 1.0), (-1.0, 1.0), (0.01, 1.0)])#: Geometrical bounds of the search domain to consider. bound is a list that contains exactly three tuple of (min,max) for each of the coordinates x, y, z. Defaults to [(-1.,1.),(-1.,1.),(0.01,1.)]

shgo = Dict#: options dictionary for the SHGO solver, see scipy docs. Default is Sobol sampling Nelder-Mead local minimizer, 256 initial sampling points and 1 iteration

r_diag_norm = Enum( …#: No normalization implemented. Defaults to 1.0.

acoular.fbeamform.L_p(x)#

Calculates the sound pressure level from the squared sound pressure.

\(L_p = 10 \lg ( x / 4\cdot 10^{-10})\)

Parameters:

x: array of floats: The squared sound pressure values

Returns:

array of floats: The corresponding sound pressure levels in dB. If x<0, -350.0 dB is returned.

acoular.fbeamform.integrate(data, grid, sector)#

Integrates a sound pressure map over a given sector.

This function can be applied on beamforming results to quantitatively analyze the sound pressure in a given sector. If used with Beamformer.result(), the output is identical to the result of the intrinsic Beamformer.integrate method. It can, however, also be used with the Beamformer.synthetic output.

Parameters:

data: array of floats: Contains the calculated squared sound pressure values in Pa**2. If data has the same number of entries than the number of grid points only one value is returned. In case of a 2-D array with the second dimension identical to the number of grid points an array containing as many entries as the first dimension is returned.
grid: Grid object: Object of a Grid-derived class that provides the grid locations.
sector: array of floats or :class:`~acoular.grids.Sector`-derived object: Tuple with arguments for the indices method of a Grid-derived class (e.g. RectGrid.indices or RectGrid3D.indices). Possible sectors would be np.array([xmin, ymin, xmax, ymax]) or np.array([x, y, radius]). Alternatively, a Sector-derived object can be used.

Returns:

array of floats: The spectrum (all calculated frequency bands) for the integrated sector.

fbeamform#

`fbeamform`#