acoular 24.5__py3-none-any.whl → 24.10__py3-none-any.whl

acoular/tbeamform.py

@@ -25,7 +25,6 @@ from numpy import (
     argmax,
     array,
     ceil,
-    concatenate,
     dot,
     empty,
     float32,
@@ -44,17 +43,18 @@ from numpy import (
     where,
     zeros,
 )
-from numpy.linalg import norm
+from scipy.linalg import norm
 from traits.api import Bool, CArray, Delegate, Enum, Float, Instance, Int, List, Property, Range, Trait, cached_property
 from traits.trait_errors import TraitError
 
+from .base import SamplesGenerator, TimeOut
 from .fbeamform import SteeringVector
 from .grids import RectGrid
 
 # acoular imports
 from .internal import digest
-from .tfastfuncs import _delayandsum4, _delayandsum5, _delays, _steer_I, _steer_II, _steer_III, _steer_IV
-from .tprocess import TimeInOut
+from .tfastfuncs import _delayandsum4, _delayandsum5, _delays
+from .tools.utils import SamplesBuffer
 from .trajectory import Trajectory
 
 
@@ -92,11 +92,14 @@ def const_power_weight(bf):
 possible_weights = {'none': None, 'power': const_power_weight}
 
 
-class BeamformerTime(TimeInOut):
+class BeamformerTime(TimeOut):
     """Provides a basic time domain beamformer with time signal output
     for a spatially fixed grid.
     """
 
+    #: Data source; :class:`~acoular.base.SamplesGenerator` or derived object.
+    source = Instance(SamplesGenerator)
+
     # Instance of :class:`~acoular.fbeamform.SteeringVector` or its derived classes
     # that contains information about the steering vector. This is a private trait.
     # Do not set this directly, use `steer` trait instead.
@@ -115,9 +118,14 @@ class BeamformerTime(TimeInOut):
             self._steer_obj = steer
         elif steer in ('true level', 'true location', 'classic', 'inverse'):
             # Type of steering vectors, see also :ref:`Sarradj, 2012<Sarradj2012>`.
+            msg = (
+                "Deprecated use of 'steer' trait. Please use the 'steer' with an object of class "
+                "'SteeringVector'. Using a string to specify the steer type will be removed in "
+                'version 25.01.'
+            )
             warn(
-                "Deprecated use of 'steer' trait. Please use object of class 'SteeringVector' in the future.",
-                Warning,
+                msg,
+                DeprecationWarning,
                 stacklevel=2,
             )
             self._steer_obj.steer_type = steer
@@ -135,7 +143,11 @@ class BeamformerTime(TimeInOut):
         return self._steer_obj.env
 
     def _set_env(self, env):
-        warn("Deprecated use of 'env' trait. ", Warning, stacklevel=2)
+        msg = (
+            "Deprecated use of 'env' trait. Please use the 'steer' trait with an object of class  "
+            "'SteeringVector'. The 'env' trait will be removed in version 25.01."
+        )
+        warn(msg, DeprecationWarning, stacklevel=2)
         self._steer_obj.env = env
 
     # The speed of sound.
@@ -147,7 +159,11 @@ class BeamformerTime(TimeInOut):
         return self._steer_obj.env.c
 
     def _set_c(self, c):
-        warn("Deprecated use of 'c' trait. ", Warning, stacklevel=2)
+        msg = (
+            "Deprecated use of 'c' trait. Please use the 'steer' trait with an object of class  "
+            "'SteeringVector'. The 'c' trait will be removed in version 25.01."
+        )
+        warn(msg, DeprecationWarning, stacklevel=2)
         self._steer_obj.env.c = c
 
     # :class:`~acoular.grids.Grid`-derived object that provides the grid locations.
@@ -159,7 +175,11 @@ class BeamformerTime(TimeInOut):
         return self._steer_obj.grid
 
     def _set_grid(self, grid):
-        warn("Deprecated use of 'grid' trait. ", Warning, stacklevel=2)
+        msg = (
+            "Deprecated use of 'grid' trait. Please use the 'steer' trait with an object of class  "
+            "'SteeringVector'. The 'grid' trait will be removed in version 25.01."
+        )
+        warn(msg, DeprecationWarning, stacklevel=2)
         self._steer_obj.grid = grid
 
     # :class:`~acoular.microphones.MicGeom` object that provides the microphone locations.
@@ -171,7 +191,11 @@ class BeamformerTime(TimeInOut):
         return self._steer_obj.mics
 
     def _set_mpos(self, mpos):
-        warn("Deprecated use of 'mpos' trait. ", Warning, stacklevel=2)
+        msg = (
+            "Deprecated use of 'mpos' trait. Please use the 'steer' trait with an object of class  "
+            "'SteeringVector' which has an attribute 'mics'. The 'mpos' trait will be removed in version 25.01."
+        )
+        warn(msg, DeprecationWarning, stacklevel=2)
         self._steer_obj.mics = mpos
 
     # Sound travel distances from microphone array center to grid points (r0)
@@ -181,11 +205,21 @@ class BeamformerTime(TimeInOut):
     r0 = Property()
 
     def _get_r0(self):
+        msg = (
+            "Deprecated use of 'r0' trait. Please use the 'steer' trait with an object of class  "
+            "'SteeringVector'. The 'r0' trait will be removed in version 25.01."
+        )
+        warn(msg, DeprecationWarning, stacklevel=2)
         return self._steer_obj.r0
 
     rm = Property()
 
     def _get_rm(self):
+        msg = (
+            "Deprecated use of 'rm' trait. Please use the 'steer' trait with an object of class  "
+            "'SteeringVector'. The 'rm' trait will be removed in version 25.01."
+        )
+        warn(msg, DeprecationWarning, stacklevel=2)
         return self._steer_obj.rm
 
     # --- End of backwards compatibility traits --------------------------------------
@@ -197,12 +231,6 @@ class BeamformerTime(TimeInOut):
     weights = Trait('none', possible_weights, desc='spatial weighting function')
     # (from timedomain.possible_weights)
 
-    # buffer with microphone time signals used for processing. Internal use
-    buffer = CArray(desc='buffer containing microphone signals')
-
-    # index indicating position of current processing sample. Internal use.
-    bufferIndex = Int(desc='index indicating position in buffer')
-
     # internal identifier
     digest = Property(
         depends_on=['_steer_obj.digest', 'source.digest', 'weights', '__class__'],
@@ -215,40 +243,28 @@ class BeamformerTime(TimeInOut):
     def _get_weights(self):
         return self.weights_(self)[newaxis] if self.weights_ else 1.0
 
-    def _fill_buffer(self, num):
-        """Generator that fills the signal buffer."""
-        weights = self._get_weights()
-        for block in self.source.result(num):
-            block *= weights
-            ns = block.shape[0]
-            bufferSize = self.buffer.shape[0]
-            self.buffer[0 : (bufferSize - ns)] = self.buffer[-(bufferSize - ns) :]
-            self.buffer[-ns:, :] = block
-            self.bufferIndex -= ns
-            yield
-
     def result(self, num=2048):
-        """Python generator that yields the *squared* deconvolved beamformer
-        output with optional removal of autocorrelation block-wise.
+        """Python generator that yields the time-domain beamformer output.
+
+        The output time signal starts for source signals that were emitted from
+        the :class:`~acoular.grids.Grid` at `t=0`.
 
         Parameters
         ----------
-        num : integer, defaults to 2048
+        num : int
             This parameter defines the size of the blocks to be yielded
-            (i.e. the number of samples per block).
-
-        Returns
-        -------
-        Samples in blocks of shape  \
-        (num, :attr:`~BeamformerTime.numchannels`).
-            :attr:`~BeamformerTime.numchannels` is usually very \
-            large (number of grid points).
-            The last block may be shorter than num. \
-            The output starts for signals that were emitted
-            from the grid at `t=0`.
-
+            (i.e. the number of samples per block). Defaults to 2048.
+
+        Yields
+        ------
+        numpy.ndarray
+            Samples in blocks of shape (num, :attr:`~BeamformerTime.numchannels`).
+                :attr:`~BeamformerTime.numchannels` is usually very \
+                large (number of grid points).
+                The last block returned by the generator may be shorter than num.
         """
         # initialize values
+        steer_func = self.steer._steer_funcs_time[self.steer.steer_type]
         fdtype = float64
         idtype = int64
         numMics = self.steer.mics.num_mics
@@ -258,33 +274,29 @@ class BeamformerTime(TimeInOut):
         # delays = empty((1,self.grid.size,numMics),dtype=fdtype)
         d_index = empty((1, self.grid.size, numMics), dtype=idtype)
         d_interp2 = empty((1, self.grid.size, numMics), dtype=fdtype)
-        _steer_III(self.rm[newaxis, :, :], self.r0[newaxis, :], amp)
-        _delays(self.rm[newaxis, :, :], c, d_interp2, d_index)
+        steer_func(self.steer.rm[newaxis, :, :], self.steer.r0[newaxis, :], amp)
+        _delays(self.steer.rm[newaxis, :, :], c, d_interp2, d_index)
         amp.shape = amp.shape[1:]
         # delays.shape = delays.shape[1:]
         d_index.shape = d_index.shape[1:]
         d_interp2.shape = d_interp2.shape[1:]
-        maxdelay = int((self.rm / c).max()) + 2 + num  # +2 because of interpolation
-        initialNumberOfBlocks = int(ceil(maxdelay / num))
-        bufferSize = initialNumberOfBlocks * num
-        self.buffer = zeros((bufferSize, numMics), dtype=float)
-        self.bufferIndex = bufferSize  # indexing current time sample in buffer
-        fill_buffer_generator = self._fill_buffer(num)
-        for _ in range(initialNumberOfBlocks):
-            next(fill_buffer_generator)
+        max_sample_delay = int((self.steer.rm / c).max()) + 2
+        weights = self._get_weights()
 
-        # start processing
-        flag = True
-        while flag:
-            samplesleft = self.buffer.shape[0] - self.bufferIndex
-            if samplesleft - maxdelay <= 0:
-                num += samplesleft - maxdelay
-                maxdelay += samplesleft - maxdelay
+        buffer = SamplesBuffer(
+            source=self.source,
+            length=int(ceil((num + max_sample_delay) / num)) * num,
+            result_num=num + max_sample_delay,
+            shift_index_by='num',
+            dtype=fdtype,
+        )
+        for p_res in buffer.result(num):
+            p_res *= weights
+            if p_res.shape[0] < buffer.result_num:  # last block shorter
+                num = p_res.shape[0] - max_sample_delay
                 n_index = arange(0, num + 1)[:, newaxis]
-                flag = False
             # init step
-            p_res = array(self.buffer[self.bufferIndex : self.bufferIndex + maxdelay, :])
-            Phi, autopow = self.delay_and_sum(num, p_res, d_interp2, d_index, amp)
+            Phi, autopow = self._delay_and_sum(num, p_res, d_interp2, d_index, amp)
             if 'Cleant' not in self.__class__.__name__:
                 if 'Sq' not in self.__class__.__name__:
                     yield Phi[:num]
@@ -293,6 +305,7 @@ class BeamformerTime(TimeInOut):
                 else:
                     yield Phi[:num] ** 2
             else:
+                p_res_copy = p_res.copy()
                 Gamma = zeros(Phi.shape)
                 Gamma_autopow = zeros(Phi.shape)
                 J = 0
@@ -304,12 +317,12 @@ class BeamformerTime(TimeInOut):
                     t_float = d_interp2[imax] + d_index[imax] + n_index
                     t_ind = t_float.astype(int64)
                     for m in range(numMics):
-                        p_res[t_ind[: num + 1, m], m] -= self.damp * interp(
+                        p_res_copy[t_ind[: num + 1, m], m] -= self.damp * interp(
                             t_ind[: num + 1, m],
                             t_float[:num, m],
-                            Phi[:num, imax] * self.r0[imax] / self.rm[imax, m],
+                            Phi[:num, imax] * self.steer.r0[imax] / self.steer.rm[imax, m],
                         )
-                    nextPhi, nextAutopow = self.delay_and_sum(num, p_res, d_interp2, d_index, amp)
+                    nextPhi, nextAutopow = self._delay_and_sum(num, p_res_copy, d_interp2, d_index, amp)
                     if self.r_diag:
                         pownextPhi = (nextPhi[:num] ** 2 - nextAutopow).sum(0).clip(min=0)
                     else:
@@ -330,13 +343,8 @@ class BeamformerTime(TimeInOut):
                     yield Gamma[:num] ** 2 - (self.damp**2) * Gamma_autopow[:num]
                 else:
                     yield Gamma[:num] ** 2
-            self.bufferIndex += num
-            try:
-                next(fill_buffer_generator)
-            except:
-                pass
 
-    def delay_and_sum(self, num, p_res, d_interp2, d_index, amp):
+    def _delay_and_sum(self, num, p_res, d_interp2, d_index, amp):
         """Standard delay-and-sum method."""
         result = empty((num, self.grid.size), dtype=float)  # output array
         autopow = empty((num, self.grid.size), dtype=float)  # output array
@@ -362,6 +370,28 @@ class BeamformerTimeSq(BeamformerTime):
     def _get_digest(self):
         return digest(self)
 
+    def result(self, num=2048):
+        """Python generator that yields the **squared** time-domain beamformer output.
+
+        The squared output time signal starts for source signals that were emitted from
+        the :class:`~acoular.grids.Grid` at `t=0`.
+
+        Parameters
+        ----------
+        num : int
+            This parameter defines the size of the blocks to be yielded
+            (i.e. the number of samples per block). Defaults to 2048.
+
+        Yields
+        ------
+        numpy.ndarray
+            Samples in blocks of shape (num, :attr:`~BeamformerTime.numchannels`).
+                :attr:`~BeamformerTime.numchannels` is usually very \
+                large (number of grid points).
+                The last block returned by the generator may be shorter than num.
+        """
+        return super().result(num)
+
 
 class BeamformerTimeTraj(BeamformerTime):
     """Provides a basic time domain beamformer with time signal output
@@ -399,7 +429,7 @@ class BeamformerTimeTraj(BeamformerTime):
     def _get_digest(self):
         return digest(self)
 
-    def get_moving_gpos(self):
+    def _get_moving_gpos(self):
         """Python generator that yields the moving grid coordinates samplewise."""
 
         def cross(a, b):
@@ -409,7 +439,7 @@ class BeamformerTimeTraj(BeamformerTime):
             return array([a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]])
 
         start_t = 0.0
-        gpos = self.grid.pos()
+        gpos = self.grid.gpos
         trajg = self.trajectory.traj(start_t, delta_t=1 / self.source.sample_freq)
         trajg1 = self.trajectory.traj(start_t, delta_t=1 / self.source.sample_freq, der=1)
         rflag = (self.rvec == 0).all()  # flag translation vs. rotation
@@ -431,7 +461,7 @@ class BeamformerTimeTraj(BeamformerTime):
                 #                print(loc[:])
                 yield tpos
 
-    def get_macostheta(self, g1, tpos, rm):
+    def _get_macostheta(self, g1, tpos, rm):
         vvec = array(g1)  # velocity vector
         ma = norm(vvec) / self.steer.env.c  # machnumber
         fdv = (vvec / sqrt((vvec * vvec).sum()))[:, newaxis]  # unit vecor velocity
@@ -444,30 +474,25 @@ class BeamformerTimeTraj(BeamformerTime):
             return self.steer.ref  # full((self.steer.grid.size,), self.steer.ref)
         return self.env._r(tpos)
 
-    def increase_buffer(self, num):
-        ar = zeros((num, self.steer.mics.num_mics), dtype=self.buffer.dtype)
-        self.buffer = concatenate((ar, self.buffer), axis=0)
-        self.bufferIndex += num
-
     def result(self, num=2048):
-        """Python generator that yields the deconvolved output block-wise.
+        """Python generator that yields the time-domain beamformer output.
+
+        The output time signal starts for source signals that were emitted from
+        the :class:`~acoular.grids.Grid` at `t=0`.
 
         Parameters
         ----------
-        num : integer, defaults to 2048
+        num : int
             This parameter defines the size of the blocks to be yielded
-            (i.e. the number of samples per block).
-
-        Returns
-        -------
-        Samples in blocks of shape  \
-        (num, :attr:`~BeamformerTime.numchannels`).
-            :attr:`~BeamformerTime.numchannels` is usually very \
-            large (number of grid points).
-            The last block may be shorter than num. \
-            The output starts for signals that were emitted
-            from the grid at `t=0`.
-
+            (i.e. the number of samples per block). Defaults to 2048.
+
+        Yields
+        ------
+        numpy.ndarray
+            Samples in blocks of shape (num, :attr:`~BeamformerTime.numchannels`).
+                :attr:`~BeamformerTime.numchannels` is usually very \
+                large (number of grid points).
+                The last block returned by the generator may be shorter than num.
         """
         # initialize values
         if self.precision == 64:
@@ -489,25 +514,17 @@ class BeamformerTimeTraj(BeamformerTime):
         d_index = empty((num, self.grid.size, numMics), dtype=idtype)
         d_interp2 = empty((num, self.grid.size, numMics), dtype=fdtype)
         blockr0 = empty((num, self.grid.size), dtype=fdtype)
-        self.buffer = zeros((2 * num, numMics), dtype=fdtype)
-        self.bufferIndex = self.buffer.shape[0]
-        movgpos = self.get_moving_gpos()  # create moving grid pos generator
+        movgpos = self._get_moving_gpos()  # create moving grid pos generator
         movgspeed = self.trajectory.traj(0.0, delta_t=1 / self.source.sample_freq, der=1)
-        fill_buffer_generator = self._fill_buffer(num)
-        for _i in range(2):
-            next(fill_buffer_generator)
+        weights = self._get_weights()
 
         # preliminary implementation of different steering vectors
-        steer_func = {
-            'classic': _steer_I,
-            'inverse': _steer_II,
-            'true level': _steer_III,
-            'true location': _steer_IV,
-        }[self.steer.steer_type]
+        steer_func = self.steer._steer_funcs_time[self.steer.steer_type]
 
         # start processing
         flag = True
-        dflag = True  # data is available
+        buffer = SamplesBuffer(source=self.source, length=num * 2, shift_index_by='num', dtype=fdtype)
+        buffered_result = buffer.result(num)
         while flag:
             for i in range(num):
                 tpos = next(movgpos).astype(fdtype)
@@ -516,30 +533,27 @@ class BeamformerTimeTraj(BeamformerTime):
                 blockrm[i, :, :] = rm
                 if self.conv_amp:
                     ht = next(movgspeed)
-                    blockrmconv[i, :, :] = rm * (1 - self.get_macostheta(ht, tpos, rm)) ** 2
+                    blockrmconv[i, :, :] = rm * (1 - self._get_macostheta(ht, tpos, rm)) ** 2
             if self.conv_amp:
                 steer_func(blockrmconv, blockr0, amp)
             else:
                 steer_func(blockrm, blockr0, amp)
             _delays(blockrm, c, d_interp2, d_index)
-            # _modf(delays, d_interp2, d_index)
-            maxdelay = (d_index.max((1, 2)) + arange(0, num)).max() + 2  # + because of interpolation
-            # increase buffer size because of greater delays
-            while maxdelay > self.buffer.shape[0] and dflag:
-                self.increase_buffer(num)
-                try:
-                    next(fill_buffer_generator)
-                except:
-                    dflag = False
-            samplesleft = self.buffer.shape[0] - self.bufferIndex
-            # last block may be shorter
-            if samplesleft - maxdelay <= 0:
-                num = sum((d_index.max((1, 2)) + 1 + arange(0, num)) < samplesleft)
+            max_sample_delay = (d_index.max((1, 2)) + 2).max()  # + because of interpolation
+            buffer.result_num = num + max_sample_delay
+
+            try:
+                time_block = next(buffered_result)
+                time_block *= weights
+            except StopIteration:
+                break
+            if time_block.shape[0] < buffer.result_num:  # last block shorter
+                num = sum((d_index.max((1, 2)) + 1 + arange(0, num)) < time_block.shape[0])
                 n_index = arange(num, dtype=idtype)[:, newaxis]
                 flag = False
             # init step
-            p_res = self.buffer[self.bufferIndex : self.bufferIndex + maxdelay, :].copy()
-            Phi, autopow = self.delay_and_sum(num, p_res, d_interp2, d_index, amp)
+            p_res = time_block.copy()
+            Phi, autopow = self._delay_and_sum(num, p_res, d_interp2, d_index, amp)
             if 'Cleant' not in self.__class__.__name__:
                 if 'Sq' not in self.__class__.__name__:
                     yield Phi[:num]
@@ -578,7 +592,7 @@ class BeamformerTimeTraj(BeamformerTime):
                             t_float[:num, m],
                             h / blockrm1[:num, imax, m],
                         )
-                    nextPhi, nextAutopow = self.delay_and_sum(num, p_res, d_interp2, d_index, amp)
+                    nextPhi, nextAutopow = self._delay_and_sum(num, p_res, d_interp2, d_index, amp)
                     if self.r_diag:
                         pownextPhi = (nextPhi[:num] * nextPhi[:num] - nextAutopow).sum(0).clip(min=0)
                     else:
@@ -599,13 +613,8 @@ class BeamformerTimeTraj(BeamformerTime):
                     yield Gamma[:num] ** 2 - (self.damp**2) * Gamma_autopow[:num]
                 else:
                     yield Gamma[:num] ** 2
-            self.bufferIndex += num
-            try:
-                next(fill_buffer_generator)
-            except:
-                dflag = False
 
-    def delay_and_sum(self, num, p_res, d_interp2, d_index, amp):
+    def _delay_and_sum(self, num, p_res, d_interp2, d_index, amp):
         """Standard delay-and-sum method."""
         fdtype = float64 if self.precision == 64 else float32
         result = empty((num, self.grid.size), dtype=fdtype)  # output array
@@ -639,12 +648,34 @@ class BeamformerTimeSqTraj(BeamformerTimeSq, BeamformerTimeTraj):
     def _get_digest(self):
         return digest(self)
 
+    def result(self, num=2048):
+        """Python generator that yields the **squared** time-domain beamformer output.
+
+        The squared output time signal starts for source signals that were emitted from
+        the :class:`~acoular.grids.Grid` at `t=0`.
+
+        Parameters
+        ----------
+        num : int
+            This parameter defines the size of the blocks to be yielded
+            (i.e. the number of samples per block). Defaults to 2048.
+
+        Yields
+        ------
+        numpy.ndarray
+            Samples in blocks of shape (num, :attr:`~BeamformerTime.numchannels`).
+                :attr:`~BeamformerTime.numchannels` is usually very \
+                large (number of grid points).
+                The last block returned by the generator may be shorter than num.
+        """
+        return super().result(num)
+
 
 class BeamformerCleant(BeamformerTime):
-    """CLEANT deconvolution method, see :ref:`Cousson et al., 2019<Cousson2019>`.
+    """CLEANT deconvolution method.
 
     An implementation of the CLEAN method in time domain. This class can only
-    be used for static sources.
+    be used for static sources. See :cite:`Cousson2019` for details.
     """
 
     #: Boolean flag, always False
@@ -666,13 +697,34 @@ class BeamformerCleant(BeamformerTime):
     def _get_digest(self):
         return digest(self)
 
+    def result(self, num=2048):
+        """Python generator that yields the deconvolved time-domain beamformer output.
+
+        The output starts for signals that were emitted from the :class:`~acoular.grids.Grid` at `t=0`.
+
+        Parameters
+        ----------
+        num : int
+            This parameter defines the size of the blocks to be yielded
+            (i.e. the number of samples per block). Defaults to 2048.
+
+        Yields
+        ------
+        numpy.ndarray
+            Samples in blocks of shape (num, :attr:`~BeamformerTime.numchannels`).
+                :attr:`~BeamformerTime.numchannels` is usually very \
+                large (number of grid points).
+                The last block returned by the generator may be shorter than num.
+        """
+        return super().result(num)
+
 
 class BeamformerCleantSq(BeamformerCleant):
-    """CLEANT deconvolution method, see :ref:`Cousson et al., 2019<Cousson2019>`
-    with optional removal of autocorrelation.
+    """CLEANT deconvolution method with optional removal of autocorrelation.
 
     An implementation of the CLEAN method in time domain. This class can only
-    be used for static sources.
+    be used for static sources. See :cite:`Cousson2019` for details on the method
+    and :cite:`Kujawski2020` for details on the autocorrelation removal.
     """
 
     #: Boolean flag, if 'True' (default), the main diagonal is removed before beamforming.
@@ -687,12 +739,35 @@ class BeamformerCleantSq(BeamformerCleant):
     def _get_digest(self):
         return digest(self)
 
+    def result(self, num=2048):
+        """Python generator that yields the *squared* deconvolved time-domain beamformer output.
+
+        The output starts for signals that were emitted from the :class:`~acoular.grids.Grid` at `t=0`.
+        Per default, block-wise removal of autocorrelation is performed, which can be turned of by setting
+        :attr:`r_diag` to `False`.
+
+        Parameters
+        ----------
+        num : int
+            This parameter defines the size of the blocks to be yielded
+            (i.e. the number of samples per block). Defaults to 2048.
+
+        Yields
+        ------
+        numpy.ndarray
+            Samples in blocks of shape (num, :attr:`~BeamformerTime.numchannels`).
+                :attr:`~BeamformerTime.numchannels` is usually very \
+                large (number of grid points).
+                The last block returned by the generator may be shorter than num.
+        """
+        return super().result(num)
+
 
 class BeamformerCleantTraj(BeamformerCleant, BeamformerTimeTraj):
-    """CLEANT deconvolution method, see :ref:`Cousson et al., 2019<Cousson2019>`.
+    """CLEANT deconvolution method.
 
     An implementation of the CLEAN method in time domain for moving sources
-    with known trajectory.
+    with known trajectory. See :cite:`Cousson2019` for details.
     """
 
     #: Floating point and integer precision
@@ -718,13 +793,34 @@ class BeamformerCleantTraj(BeamformerCleant, BeamformerTimeTraj):
     def _get_digest(self):
         return digest(self)
 
+    def result(self, num=2048):
+        """Python generator that yields the deconvolved time-domain beamformer output.
+
+        The output starts for signals that were emitted from the :class:`~acoular.grids.Grid` at `t=0`.
+
+        Parameters
+        ----------
+        num : int
+            This parameter defines the size of the blocks to be yielded
+            (i.e. the number of samples per block). Defaults to 2048.
+
+        Yields
+        ------
+        numpy.ndarray
+            Samples in blocks of shape (num, :attr:`~BeamformerTime.numchannels`).
+                :attr:`~BeamformerTime.numchannels` is usually very \
+                large (number of grid points).
+                The last block returned by the generator may be shorter than num.
+        """
+        return super().result(num)
+
 
 class BeamformerCleantSqTraj(BeamformerCleantTraj, BeamformerTimeSq):
-    """CLEANT deconvolution method, see :ref:`Cousson et al., 2019<Cousson2019>`
-    with optional removal of autocorrelation.
+    """CLEANT deconvolution method with optional removal of autocorrelation.
 
     An implementation of the CLEAN method in time domain for moving sources
-    with known trajectory.
+    with known trajectory. See :cite:`Cousson2019` for details on the method and
+    :cite:`Kujawski2020` for details on the autocorrelation removal.
     """
 
     #: Boolean flag, if 'True' (default), the main diagonal is removed before beamforming.
@@ -751,10 +847,36 @@ class BeamformerCleantSqTraj(BeamformerCleantTraj, BeamformerTimeSq):
     def _get_digest(self):
         return digest(self)
 
+    def result(self, num=2048):
+        """Python generator that yields the *squared* deconvolved time-domain beamformer output.
+
+        The output starts for signals that were emitted from the :class:`~acoular.grids.Grid` at `t=0`.
+        Per default, block-wise removal of autocorrelation is performed, which can be turned of by setting
+        :attr:`r_diag` to `False`.
 
-class IntegratorSectorTime(TimeInOut):
+        Parameters
+        ----------
+        num : int
+            This parameter defines the size of the blocks to be yielded
+            (i.e. the number of samples per block). Defaults to 2048.
+
+        Yields
+        ------
+        numpy.ndarray
+            Samples in blocks of shape (num, :attr:`~BeamformerTime.numchannels`).
+                :attr:`~BeamformerTime.numchannels` is usually very \
+                large (number of grid points).
+                The last block returned by the generator may be shorter than num.
+        """
+        return super().result(num)
+
+
+class IntegratorSectorTime(TimeOut):
     """Provides an Integrator in the time domain."""
 
+    #: Data source; :class:`~acoular.base.SamplesGenerator` or derived object.
+    source = Instance(SamplesGenerator)
+
     #: :class:`~acoular.grids.RectGrid` object that provides the grid locations.
     grid = Trait(RectGrid, desc='beamforming grid')