acoular 25.1__py3-none-any.whl → 25.3__py3-none-any.whl

acoular/trajectory.py

@@ -19,30 +19,80 @@ from .internal import digest
 
 
 class Trajectory(HasStrictTraits):
-    """Describes a trajectory from sampled points.
-
-    Based on a discrete number of points in space and time, a
-    continuous trajectory is calculated using spline interpolation
-    of positions between samples.
     """
-
-    #: Dictionary that assigns discrete time instants (keys) to
-    #: sampled `(x, y, z)` positions along the trajectory (values).
+    Represents a trajectory as a continuous curve derived from sampled points.
+
+    The :class:`Trajectory` class computes a smooth, continuous path through a set of discrete
+    points in space and time using spline interpolation. It also supports evaluating the trajectory
+    and its derivatives at arbitrary time instants.
+
+    It can be used to:
+        - define the traveling path of a moving sound source, e.g. for microphone array data
+          simulation (see :class:`~acoular.sources.MovingPointSource`)
+        - move a source grid along a certain path to create a fixed focus
+          (see :class:`~acoular.tbeamform.BeamformerTimeTraj`
+          and :class:`~acoular.tbeamform.BeamformerCleantTraj`)
+
+    Exemplary use can also be seen in the
+    :ref:`rotating point source example<rotating_point_source>`.
+
+    See Also
+    --------
+    :class:`~acoular.sources.MovingPointSource` : Model a point source moving along a trajectory.
+    :class:`~acoular.sources.MovingPointSourceDipole` :
+        Model a point source dipole moving along a trajectory.
+    :class:`~acoular.sources.MovingLineSource` : Model a line source moving along a trajectory.
+    :class:`~acoular.tbeamform.BeamformerCleantTraj` :
+        Beamformer implementing the CLEAN method :cite:`Kujawski2020` in time domain
+        for moving sources with known trajectory.
+    :class:`~acoular.tbeamform.BeamformerTimeTraj` :
+        Basic time domain beamformer with time signal output for a grid moving along a trajectory.
+    :func:`scipy.interpolate.splprep` : Underlying spline generation function.
+    :func:`scipy.interpolate.splev` : Used for evaluating the spline.
+
+    Notes
+    -----
+    - Spline interpolation provides a smooth trajectory that passes through all sampled points.
+      The interpolation order is adjusted automatically based on the number of points.
+    - The trajectory can be used in simulations where a source's motion must be modeled
+      continuously.
+
+    Examples
+    --------
+    Create a trajectory and evaluate positions and velocities:
+
+    >>> from acoular import Trajectory
+    >>> points = {0.0: (0.0, 0.0, 0.0), 1.0: (1.0, 0.0, 0.0), 2.0: (2.0, 1.0, 0.0)}
+    >>> tr = Trajectory(points=points)
+    >>>
+    >>> tr.location(1.5)  # Position at t=1.5
+    [array(1.5), array(0.375), array(0.)]
+    >>>
+    >>> for pos in tr.traj(0.0, 2.0, 0.5):  # Positions every 0.5 seconds
+    ...     print(pos)
+    (np.float64(0.0), np.float64(0.0), np.float64(0.0))
+    (np.float64(0.5), np.float64(-0.125), np.float64(0.0))
+    (np.float64(1.0), np.float64(0.0), np.float64(0.0))
+    (np.float64(1.5), np.float64(0.375), np.float64(0.0))
+    """  # noqa W505
+
+    #: Dictionary mapping time instants (keys, as floats) to sampled ``(x, y, z)`` positions
+    #: (values, as tuples of floats) along the trajectory.
     points = Dict(
         key_trait=Float,
         value_trait=Tuple(Float, Float, Float),
         desc='sampled positions along the trajectory',
     )
 
-    #: Tuple of the start and end time, is set automatically
-    #: (depending on :attr:`points`).
+    #: Automatically determined tuple ``(t_min, t_max)`` representing the start and end times of the
+    #: trajectory, based on the keys in :attr:`points`.
     interval = Property()
     # t_min, t_max tuple
 
-    #: Spline data, internal use.
+    #: Internal representation of the spline, generated using :func:`scipy.interpolate.splprep`.
     tck = Property()
 
-    # internal identifier
+    #: A unique identifier for the trajectory, based on its points. (read-only)
     digest = Property(depends_on=['points[]'])
 
     @cached_property
@@ -62,54 +112,80 @@ class Trajectory(HasStrictTraits):
         return tcku[0]
 
     def location(self, t, der=0):
-        """Returns the positions for one or more instants in time.
+        """
+        Compute the trajectory's position or derivatives at specified times.
 
         Parameters
         ----------
-        t : array of floats
-            Instances in time to calculate the positions at.
-        der : integer
-            The order of derivative of the spline to compute, defaults to 0.
+        t : :class:`float` or array of :class:`floats<float>`
+            Time instant(s) at which to compute the position(s) or derivative(s).
+        der : :class:`int`, optional
+            Order of the derivative to compute:
+                - ``0`` for positions (default),
+                - ``1`` for velocities,
+                - ``2`` for accelerations, etc.
 
         Returns
         -------
-        (x, y, z) : tuple with arrays of floats
-            Positions at the given times; `x`, `y` and `z` have the same shape as `t`.
+        :class:`numpy.ndarray`
+            ``(x, y, z)`` arrays representing the trajectory's position (or derivative) at the given
+            time(s). The shape matches that of ``t``.
 
+        Examples
+        --------
+        >>> import acoular as ac
+        >>>
+        >>> points = {0.0: (0.0, 0.0, 0.0), 1.0: (1.0, 2.0, 0.0), 2.0: (2.0, 4.0, 0.0)}
+        >>> tr = ac.Trajectory(points=points)
+        >>> tr.location(1.0)  # Position at t=1.0
+        [array(1.), array(2.), array(0.)]
+        >>> tr.location([0.5, 1.5], der=1)  # Velocity at t=0.5 and t=1.5
+        [array([1., 1.]), array([2., 2.]), array([0., 0.])]
         """
         return splev(t, self.tck, der)
 
     def traj(self, t_start, t_end=None, delta_t=None, der=0):
-        """Python generator that yields locations along the trajectory.
+        """
+        Interate through trajectory positions or derivatives at specified intervals.
 
         Parameters
         ----------
-        t_start : float
-            Starting time of the trajectory, defaults to the earliest
-            time in :attr:`points`.
-        t_end : float
-            Ending time of the trajectory, defaults to the latest
-            time in :attr:`points`.
-        delta_t : float
-            Time interval between yielded trajectory points, defaults to earliest
-            time in :attr:`points`.
-
-        Returns
-        -------
-        (x, y, z) : tuples of floats
-            Positions at the desired times are yielded.
+        t_start : :class:`float`
+            Start time for the trajectory. Default is earliest key in :attr:`points`.
+        t_end : :class:`float`, optional
+            End time of the trajectory. Default is the latest key in :attr:`points`.
+        delta_t : :class:`float`, optional
+            Time interval between consecutive points to yield. Default is the value of ``t_start``.
+        der : int, optional
+            Order of the derivative to compute:
+                - ``0`` for positions (default),
+                - ``1`` for velocities,
+                - ``2`` for accelerations, etc.
+
+        Yields
+        ------
+        :class:`tuple` of :class:`floats<float>`
+            ``(x, y, z)`` positions or derivatives at the specified time intervals.
+
+        Notes
+        -----
+        The function precomputes all interpolated locations for efficiency and yields them
+        sequentially.
 
         Examples
         --------
-        x.traj(0.1)
-            Yields the position every 0.1 s within the
-            given :attr:`interval`.
-        x.traj(2.5, 4.5, 0.1)
-            Yields the position every 0.1 s between 2.5 s and 4.5 s.
-        x.traj(0.1, der=1)
-            Yields the 1st derivative of the spline (= velocity vector) every 0.1 s
-            within the given :attr:`interval`.
-
+        Create a trajectory and iterate through the positions in the :attr:`interval`:
+
+        >>> import acoular as ac
+        >>>
+        >>> points = {0.0: (0.0, 0.0, 0.0), 1.0: (1.0, 0.0, 0.0), 2.0: (2.0, 1.0, 0.0)}
+        >>> tr = ac.Trajectory(points=points)
+        >>> for pos in tr.traj(0.0, 2.0, 0.5):
+        ...     print(pos)
+        (np.float64(0.0), np.float64(0.0), np.float64(0.0))
+        (np.float64(0.5), np.float64(-0.125), np.float64(0.0))
+        (np.float64(1.0), np.float64(0.0), np.float64(0.0))
+        (np.float64(1.5), np.float64(0.375), np.float64(0.0))
         """
         if not delta_t:
             delta_t = t_start

acoular/version.py

@@ -4,5 +4,5 @@
 
 # separate file to find out about version without importing the acoular lib
 __author__ = 'Acoular Development Team'
-__date__ = '31 January 2024'
-__version__ = '25.01'
+__date__ = '12 March 2025'
+__version__ = '25.03'

{acoular-25.1.dist-info → acoular-25.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acoular
-Version: 25.1
+Version: 25.3
 Summary: Python library for acoustic beamforming
 Project-URL: homepage, https://acoular.org
 Project-URL: documentation, https://acoular.org
@@ -197,12 +197,13 @@ If you are interested in contributing, have a look at the [CONTRIBUTING.md](CONT
 This reads data from 64 microphone channels and computes a beamforming map for the 8kHz third octave band:
 
 ```python
-from os.path import join, split
+from pathlib import Path
+
 import acoular as ac
 import matplotlib.pylab as plt
 
 # this file contains the microphone coordinates
-micgeofile = join(split(ac.__file__)[0],'xml','array_64.xml')
+micgeofile = Path(ac.__file__).parent / 'xml' / 'array_64.xml'
 # set up object managing the microphone coordinates
 mg = ac.MicGeom( file=micgeofile )
 # generate test data, in real life this would come from an array measurement
@@ -214,7 +215,7 @@ ps = ac.PowerSpectra( source=ts, block_size=128, window='Hanning' )
 # alternatively, you can use the in-memory Mixer object directly:
 # ps = ac.PowerSpectra( source=p, block_size=128, window='Hanning' )
 # set up object managing the mapping grid
-rg = ac.RectGrid( x_min=-0.2, x_max=0.2, y_min=-0.2, y_max=0.2, z=0.3, \
+rg = ac.RectGrid( x_min=-0.2, x_max=0.2, y_min=-0.2, y_max=0.2, z=-0.3, \
 increment=0.01 )
 # set up steering vector, implicitely contains also the standard quiescent 
 # environment with standard speed of sound
@@ -229,7 +230,7 @@ Lm = ac.L_p( pm )
 # plot the map
 plt.imshow( Lm.T, origin='lower', vmin=Lm.max()-10, extent=rg.extend(), \
 interpolation='bicubic')
-plt.title(f'Beamformer (base) for 3 sources measured for 8000 Hz')
+plt.title('Beamformer (base) for 3 sources measured for 8000 Hz')
 plt.xlabel('x in m')
 plt.ylabel('y in m')
 plt.colorbar(label=r'$L_p$')

{acoular-25.1.dist-info → acoular-25.3.dist-info}/RECORD

@@ -3,30 +3,30 @@ acoular/base.py,sha256=gqFsfgSG1YrS-BAmV44ao6ckXo7v5B2VMX86QH3QowE,10717
 acoular/calib.py,sha256=P46L1U8Lk0_BSY3AQz0KO4g8rsZmi47j3YaQOlHK64A,7133
 acoular/configuration.py,sha256=QQU5HWjXEDMuMU3LEoaDnDszhqeJzCGhZ5oGbsW2qFY,8630
 acoular/deprecation.py,sha256=lfmCRvwYu_tXSEk5HfYDmagPCVBL7082m3oq5kvxOZ8,3810
-acoular/environments.py,sha256=EBkoj3Xo9VmR6qI6kKXZzCFqLtVP-XS95nAF3xqd2AQ,22498
+acoular/environments.py,sha256=tWRJSCzIa0eSBX2AGjrWciz12mq2nPzs0AAQc9yFGqk,35998
 acoular/fastFuncs.py,sha256=6Iqm-xy2T7qBaYpdpgUquup6JkAwdURhSXfAEkgqVOs,37362
 acoular/fbeamform.py,sha256=IY7RlM_7Yl8UjCgnDPVmAEmBASS83yGsefg6OAcWFCk,99057
-acoular/fprocess.py,sha256=tEeuzjlWxftcwnrF0KsoKoN_9hQ-zHKax98ssa2o4Zc,14734
-acoular/grids.py,sha256=fINM66R59BPHD0myBarkbDBNjt7vdhXR2VI4_vxj5Nw,39631
+acoular/fprocess.py,sha256=NK3Nt2jD0Dvq5kPLWvodFRGKd9oIpk6Rgy_U48R49Yg,20706
+acoular/grids.py,sha256=Mcc9lmh5qXLfAxu5mpImPNkUuEcd2wEas74ovlarmuY,58981
 acoular/h5cache.py,sha256=tHCJjHs26ZnRtPO6uj9PqJ2xMEEJup-A8FoiiojkkLw,4166
 acoular/h5files.py,sha256=RKMBfbFX8d_d4JEnyMyHQQjN74EhW6W4CE-drmDZakY,7553
 acoular/internal.py,sha256=qgluN_4Br7U74keTiavbmxRMkcNkoHcL1TihKTcMEBs,829
-acoular/microphones.py,sha256=muyIDWdfbjQfahJmiHTjl1KJlw0Exfcw0oSGZCXrQLI,4534
-acoular/process.py,sha256=NOiMULyH3aYFHRp3uKnPvLQuvz0HLXkzvHDHJzMQtfE,30099
+acoular/microphones.py,sha256=IrPDPB4v4mM2ONLkwODjgOVPTMZSSPoMAFXjAMp4QEw,10591
+acoular/process.py,sha256=86wfR87RsSpYqa7ZmC4FtmEmp4zPDL0ICq8QdiTYLeI,41043
 acoular/sdinput.py,sha256=93uQaO5Zt2DV83iyeoFMaPXww1rp0PP4HB6M-C2FDak,5109
-acoular/signals.py,sha256=GDJkM1oDFzhS8ibm1BVWGvJy2Gd-GBDZGs4fW94LqvA,12344
-acoular/sources.py,sha256=E8hBtpaAkY3VecdCWyfyIbP0wY06nKX6lr2KMaQETdg,55679
-acoular/spectra.py,sha256=53Piz1NPE7BTNUCkv0Dwe8AUQn8XiKWgFuKH01j2xN8,21160
+acoular/signals.py,sha256=ue_KtTbrcMUzX_aUM8pqhm3jviNGeh32Nk-wXrCVw_g,24416
+acoular/sources.py,sha256=7-XHQMeiE2D4NSxgbGpFDwZL08Xb92New6lsTxDwbfs,97225
+acoular/spectra.py,sha256=oU5m124tlvlIaN3MbqZarHw9hO6hMowpg3WY6FFqRXo,28837
 acoular/tbeamform.py,sha256=-CAvutAY4VK4cILq1GOu7oTjwNh_R0gjVCLjLmM-5U0,30857
 acoular/tfastfuncs.py,sha256=q2ZbDoWmFbGMZw1TT_h-21hn24qGi2of_ZqJVoLMYhc,7901
 acoular/tprocess.py,sha256=gm6lvIJogR0_S17StsXe4e_y2dssTLyaPH0mb-6ykN0,77502
 acoular/traitsviews.py,sha256=VO-i509WAMQG7KuJatlCWeexZeTAFEjmjbNDkGSfzX4,13773
-acoular/trajectory.py,sha256=vWYIMERnJ6SNOe3pyVL_Z-hsY2NjmOZTTdcRhCSUU7E,3943
-acoular/version.py,sha256=sdJuvOcO1kksddYczK0fqVXPreUk9IC3tOBHGsqhemU,380
+acoular/trajectory.py,sha256=cOawITHARdcsBwpHfBleosltDwU-31xtOlZ7clrcbvA,7910
+acoular/version.py,sha256=G10HLGx_t9fD3x7HMmmPoYx8REcItCTTVwu8YXjN1MA,378
 acoular/aiaa/__init__.py,sha256=5RhoERGQmLBf6uosr9hYHWy_MruKiyR5x-8cMRX4hT4,420
 acoular/aiaa/aiaa.py,sha256=WvQFr7D37QhdUVgrBOifE76zX9FFe1eexumQd1_3_2M,6310
 acoular/demo/__init__.py,sha256=fxf0-D7Pxepi0bmxPwCj3Yo-vgCC37faTLlPaotMkB0,380
-acoular/demo/acoular_demo.py,sha256=7JrR1hIXXDScOcohfhEJaZsfegu0CmfCoqe8SmJ8zZ4,3497
+acoular/demo/acoular_demo.py,sha256=HDANP1vA5OXBkuolpCeWRt8hr_jFKnu_sQRbCtbApPo,3513
 acoular/tools/__init__.py,sha256=z8RHRQhcmqkUKwD8v3pInpAMN8csPcN5J4Z9QXu_GjQ,511
 acoular/tools/helpers.py,sha256=L9Bi6WmGBiyF_Xz5L5wtIgk0tobd4FX8gG6mfGA8z2k,13468
 acoular/tools/metrics.py,sha256=y6TsavywfnuMScBcFxIrcKcDuC55WfIGkNFnCuuuj3Y,6136
@@ -49,8 +49,8 @@ acoular/xml/gfai_ring32.xml,sha256=liKaGpfgUn8R1psDmiw6qqpZi5SwtPWBRhwhqy7YuOc,1
 acoular/xml/minidsp_uma-16.xml,sha256=oBj7J96RTDZufsQ7S4rw0jAvLOoykJaIGgl6_2gMON4,1140
 acoular/xml/minidsp_uma-16_mirrored.xml,sha256=l6LUPIsEVg7HPMbs9NbnqZyFhpCSYS70glsbyH3IUOE,1418
 acoular/xml/tub_vogel64.xml,sha256=PixVMx5hMJjgBOekH46uu6D3ODqYVOLlk82zkYl4EBM,4424
-acoular-25.1.dist-info/METADATA,sha256=nO3qOShX0uZtIhJXcz-jPUnBT43a6uKXCVE2fH7Y_G0,12774
-acoular-25.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-acoular-25.1.dist-info/licenses/AUTHORS.rst,sha256=445q_Us_TnQx8s_GP2yringU2DMTk3-ycrk2REtSsx0,382
-acoular-25.1.dist-info/licenses/LICENSE,sha256=tbw7-nx204gXCo8p-NwwR7w8oKvNMWB4H07FTT6V9p8,1505
-acoular-25.1.dist-info/RECORD,,
+acoular-25.3.dist-info/METADATA,sha256=M_4x0wwsiPt3Pi93mMs1ryK-v3MrqiVT5R50bgo7PMM,12769
+acoular-25.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+acoular-25.3.dist-info/licenses/AUTHORS.rst,sha256=445q_Us_TnQx8s_GP2yringU2DMTk3-ycrk2REtSsx0,382
+acoular-25.3.dist-info/licenses/LICENSE,sha256=tbw7-nx204gXCo8p-NwwR7w8oKvNMWB4H07FTT6V9p8,1505
+acoular-25.3.dist-info/RECORD,,