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

acoular/h5cache.py

@@ -4,16 +4,16 @@
 
 # imports from other packages
 import gc
-from os import listdir, path
+from pathlib import Path
 from weakref import WeakValueDictionary
 
-from traits.api import Bool, Delegate, Dict, HasPrivateTraits, Instance
+from traits.api import Bool, Delegate, Dict, HasStrictTraits, Instance
 
 from .configuration import Config, config
 from .h5files import _get_cachefile_class
 
 
-class HDF5Cache(HasPrivateTraits):
+class HDF5Cache(HasStrictTraits):
     """Cache class that handles opening and closing 'tables.File' objects."""
 
     config = Instance(Config)
@@ -24,26 +24,16 @@ class HDF5Cache(HasPrivateTraits):
 
     open_files = WeakValueDictionary()
 
-    open_file_reference = Dict()
+    open_file_reference = Dict(key_trait=Path, value_trait=int)
 
     def _idle_if_busy(self):
         while self.busy:
             pass
 
-    def open_cachefile(self, filename, mode):
-        file = _get_cachefile_class()
-        return file(path.join(self.cache_dir, filename), mode)
-
     def close_cachefile(self, cachefile):
-        self.open_file_reference.pop(get_basename(cachefile))
+        self.open_file_reference.pop(Path(cachefile.filename))
         cachefile.close()
 
-    def get_filename(self, file):
-        file_class = _get_cachefile_class()
-        if isinstance(file, file_class):
-            return get_basename(file)
-        return 0
-
     def get_open_cachefiles(self):
         try:
             return self.open_files.itervalues()
@@ -53,7 +43,6 @@ class HDF5Cache(HasPrivateTraits):
     def close_unreferenced_cachefiles(self):
         for cachefile in self.get_open_cachefiles():
             if not self.is_reference_existent(cachefile):
-                #                print("close unreferenced File:",get_basename(cachefile))
                 self.close_cachefile(cachefile)
 
     def is_reference_existent(self, file):
@@ -69,46 +58,50 @@ class HDF5Cache(HasPrivateTraits):
                 break
         return exist_flag
 
-    def is_cachefile_existent(self, filename):
-        if filename in listdir(self.cache_dir):
-            return True
-        return False
-
     def _increase_file_reference_counter(self, filename):
         self.open_file_reference[filename] = self.open_file_reference.get(filename, 0) + 1
 
     def _decrease_file_reference_counter(self, filename):
         self.open_file_reference[filename] = self.open_file_reference[filename] - 1
 
+    def get_cache_directories(self):
+        """Return a list of all used cache directories (if multiple paths exist)."""
+        return list({str(k.parent) for k in self.open_file_reference})
+
     def _print_open_files(self):
-        print(list(self.open_file_reference.items()))
+        """Prints open cache files and the number of objects referencing a cache file.
+
+        If multiple cache files are open at different paths, the full path is printed.
+        Otherwise, only the filename is logged.
+        """
+        if len(self.open_file_reference.values()) > 1:
+            print(list({str(k): v for k, v in self.open_file_reference.items()}.items()))
+        else:
+            print(list({str(k.name): v for k, v in self.open_file_reference.items()}.items()))
 
     def get_cache_file(self, obj, basename, mode='a'):
         """Returns pytables .h5 file to h5f trait of calling object for caching."""
         self._idle_if_busy()  #
         self.busy = True
+        file_cls = _get_cachefile_class()
+        filename = (Path(self.cache_dir) / (basename + '_cache.h5')).resolve()
 
-        filename = basename + '_cache.h5'
-        obj_filename = self.get_filename(obj.h5f)
+        if config.global_caching == 'readonly' and not filename.exists():
+            obj.h5f = None
+            self.busy = False
+            return  # cachefile is not created in readonly mode
 
-        if obj_filename:
-            if obj_filename == filename:
+        if isinstance(obj.h5f, file_cls):
+            if Path(obj.h5f.filename).resolve() == filename:
                 self.busy = False
                 return
-            self._decrease_file_reference_counter(obj_filename)
+            self._decrease_file_reference_counter(obj.h5f.filename)
 
         if filename not in self.open_files:  # or tables.file._open_files.filenames
-            if config.global_caching == 'readonly' and not self.is_cachefile_existent(
-                filename,
-            ):  # condition ensures that cachefile is not created in readonly mode
-                obj.h5f = None
-                self.busy = False
-                #                self._print_open_files()
-                return
             if config.global_caching == 'readonly':
                 mode = 'r'
-            f = self.open_cachefile(filename, mode)
-            self.open_files[filename] = f
+            file = file_cls(filename, mode)
+            self.open_files[filename] = file
 
         obj.h5f = self.open_files[filename]
         self._increase_file_reference_counter(filename)
@@ -121,7 +114,3 @@ class HDF5Cache(HasPrivateTraits):
 
 
 H5cache = HDF5Cache(config=config)
-
-
-def get_basename(file):
-    return path.basename(file.filename)

acoular/h5files.py

@@ -111,9 +111,7 @@ if config.have_tables:
         def is_cached(self, nodename, group=None):
             if not group:
                 group = self.root
-            if nodename in group:
-                return True
-            return False
+            return nodename in group
 
         def create_compressible_array(self, nodename, shape, precision, group=None):
             if not group:
@@ -190,9 +188,7 @@ if config.have_h5py:
         def is_cached(self, nodename, group=None):
             if not group:
                 group = '/'
-            if group + nodename in self:
-                return True
-            return False
+            return group + nodename in self
 
         def create_compressible_array(self, nodename, shape, precision, group=None):
             in_file_path = self._get_in_file_path(nodename, group)

acoular/microphones.py

@@ -1,93 +1,180 @@
 # ------------------------------------------------------------------------------
 # Copyright (c) Acoular Development Team.
 # ------------------------------------------------------------------------------
-"""Implements support for array microphone arrangements.
+"""
+Implements support for array microphone arrangements.
 
 .. autosummary::
     :toctree: generated/
 
     MicGeom
-
 """
 
 # imports from other packages
-import errno
-from os import path, strerror
+import xml.dom.minidom
+from pathlib import Path
 
 from numpy import array, average
 from scipy.spatial.distance import cdist
-from traits.api import Bool, CArray, File, HasPrivateTraits, ListInt, Property, cached_property, on_trait_change
+from traits.api import (
+    CArray,
+    File,
+    HasStrictTraits,
+    List,
+    Property,
+    cached_property,
+    on_trait_change,
+)
 
+# acoular imports
+from .deprecation import deprecated_alias
 from .internal import digest
 
 
-class MicGeom(HasPrivateTraits):
-    """Provides the geometric arrangement of microphones in the array.
-
-    The geometric arrangement of microphones is read in from an
-    xml-source with element tag names `pos` and attributes Name, `x`, `y` and `z`.
-    Can also be used with programmatically generated arrangements.
+@deprecated_alias({'mpos_tot': 'pos_total', 'mpos': 'pos', 'from_file': 'file'}, read_only=['mpos'])
+class MicGeom(HasStrictTraits):
     """
+    Provide the geometric arrangement of microphones in an array.
+
+    This class allows you to define, import, and manage the spatial positions of microphones in a
+    microphone array. The positions can be read from an XML file or set programmatically. Invalid
+    microphones can be excluded by specifying their indices via :attr:`invalid_channels`.
+
+    Notes
+    -----
+    - The microphone geometry as in :attr:`total_pos` is automatically changed if the :attr:`file`
+      attribute is updated.
+    - Small numerical values in the computed :attr:`center` are set to zero for numerical stability.
+
+    Examples
+    --------
+    To set a microphone geomerty for ``n`` programmatically, first a ``(3,n)`` array is needed. In
+    this case we'll use ``n=9`` and generate an array containing the positional data.
+
+    >>> import numpy as np
+    >>>
+    >>> # Generate a (3,3) grid of points in the x-y plane
+    >>> x = np.linspace(-1, 1, 3)  # Generate 3 points for x, from -1 to 1
+    >>> y = np.linspace(-1, 1, 3)  # Generate 3 points for y, from -1 to 1
+    >>>
+    >>> # Create a meshgrid for 3D coordinates, with z=0 for all points
+    >>> X, Y = np.meshgrid(x, y)
+    >>> Z = np.zeros_like(X)  # Set all z-values to 0
+    >>>
+    >>> # Stack the coordinates into a single (3,9) array
+    >>> points = np.vstack([X.ravel(), Y.ravel(), Z.ravel()])
+    >>> points
+    array([[-1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1.],
+           [-1., -1., -1.,  0.,  0.,  0.,  1.,  1.,  1.],
+           [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
+
+    Now, to implement this array as a microphone geomertry, create a :class:`MicGeom` object and
+    assign the array to it the by using the :attr:`pos_total` attribute:
 
-    #: Name of the .xml-file from wich to read the data.
-    from_file = File(filter=['*.xml'], desc='name of the xml file to import')
+    >>> from acoular import MicGeom
+    >>> mg = MicGeom(pos_total=points)
+    >>> mg.pos
+    array([[-1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1.],
+           [-1., -1., -1.,  0.,  0.,  0.,  1.,  1.,  1.],
+           [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
 
-    #: Validate mic geom from file
-    validate_file = Bool(True, desc='Validate mic geom from file')
+    The microphones along the diagonal can be removed by setting their indices in the
+    :attr:`invalid_channels` attribute:
 
-    #: Basename of the .xml-file, without the extension; is set automatically / readonly.
-    basename = Property(depends_on='from_file', desc='basename of xml file')
+    >>> mg.invalid_channels = [0, 4, 9]
+    >>> mg.pos
+    array([[ 0.,  1., -1.,  1., -1.,  0.,  1.],
+           [-1., -1.,  0.,  0.,  1.,  1.,  1.],
+           [ 0.,  0.,  0.,  0.,  0.,  0.,  0.]])
 
-    #: List that gives the indices of channels that should not be considered.
-    #: Defaults to a blank list.
-    invalid_channels = ListInt(desc='list of invalid channels')
+    But they will still be included in :attr:`pos_total`:
 
-    #: Number of microphones in the array; readonly.
-    num_mics = Property(depends_on=['mpos'], desc='number of microphones in the geometry')
+    >>> mg.pos_total
+    array([[-1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1.],
+           [-1., -1., -1.,  0.,  0.,  0.,  1.,  1.,  1.],
+           [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
 
-    #: Center of the array (arithmetic mean of all used array positions); readonly.
-    center = Property(depends_on=['mpos'], desc='array center')
+    To export this microphone geometry, use the :meth:`export_mpos` method. Note that the
+    microphones marked as invalid in :attr:`invalid_channels` will not be exported.
 
-    #: Aperture of the array (greatest extent between two microphones); readonly.
-    aperture = Property(depends_on=['mpos'], desc='array aperture')
+    >>> mg.export_mpos('micgeom.xml')  # doctest: +SKIP
+
+    The newly generated ``micgeom.xml`` file looks like this:
+
+    .. code-block:: xml
+
+        <?xml version="1.1" encoding="utf-8"?><MicArray name="micgeom">
+          <pos Name="Point 1" x="0.0" y="-1.0" z="0.0"/>
+          <pos Name="Point 2" x="1.0" y="-1.0" z="0.0"/>
+          <pos Name="Point 3" x="-1.0" y="0.0" z="0.0"/>
+          <pos Name="Point 4" x="1.0" y="0.0" z="0.0"/>
+          <pos Name="Point 5" x="-1.0" y="1.0" z="0.0"/>
+          <pos Name="Point 6" x="0.0" y="1.0" z="0.0"/>
+          <pos Name="Point 7" x="1.0" y="1.0" z="0.0"/>
+        </MicArray>
+
+    Note that when importing a microphone geometry, the XML file needs to look similar to this one:
+    There must be ``<pos>`` elements with ``Name``, ``x``, ``y``, and ``z`` attributes.
+
+    To load this same file as a new :class:`MicGeom` object, the ``micgeom.xml`` file can be
+    assigned to the :attr:`file` attribute:
+
+    >>> new_mg = MicGeom(file='micgeom.xml')  # doctest: +SKIP
+    >>> new_mg.pos  # doctest: +SKIP
+    array([[ 0.,  1., -1.,  1., -1.,  0.,  1.],
+           [-1., -1.,  0.,  0.,  1.,  1.,  1.],
+           [ 0.,  0.,  0.,  0.,  0.,  0.,  0.]])
+    """
 
-    #: Positions as (3, :attr:`num_mics`) array of floats, may include also invalid
-    #: microphones (if any). Set either automatically on change of the
-    #: :attr:`from_file` argument or explicitely by assigning an array of floats.
-    mpos_tot = CArray(dtype=float, desc='x, y, z position of all microphones')
+    #: Path to the XML file containing microphone positions. The XML file should have elements with
+    #: the tag ``pos`` and attributes ``Name``, ``x``, ``y``, and ``z``.
+    file = File(filter=['*.xml'], exists=True, desc='name of the xml file to import')
 
-    #: Positions as (3, :attr:`num_mics`) array of floats, without invalid
-    #: microphones; readonly.
-    mpos = Property(depends_on=['mpos_tot', 'invalid_channels'], desc='x, y, z position of microphones')
+    #: Array containing the ``x, y, z`` positions of all microphones, including invalid ones, shape
+    #: ``(3,`` :attr:`num_mics` ``)``. This is set automatically when :attr:`file` changes or
+    #: explicitly by assigning an array of floats.
+    pos_total = CArray(dtype=float, shape=(3, None), desc='x, y, z position of all microphones')
 
-    # internal identifier
-    digest = Property(depends_on=['mpos'])
+    #: Array containing the ``x, y, z`` positions of valid microphones (i.e., excluding those in
+    #: :attr:`invalid_channels`), shape ``(3,`` :attr:`num_mics` ``)``. (read-only)
+    pos = Property(depends_on=['pos_total', 'invalid_channels'], desc='x, y, z position of used microphones')
+
+    #: List of indices indicating microphones to be excluded from calculations and results.
+    #: Default is ``[]``.
+    invalid_channels = List(int, desc='list of invalid channels')
+
+    #: Number of valid microphones in the array. (read-only)
+    num_mics = Property(depends_on=['pos'], desc='number of microphones in the geometry')
+
+    #: The geometric center of the array, calculated as the arithmetic mean of the positions of all
+    #: valid microphones. (read-only)
+    center = Property(depends_on=['pos'], desc='array center')
+
+    #: The maximum distance between any two valid microphones in the array. (read-only)
+    aperture = Property(depends_on=['pos'], desc='array aperture')
+
+    #: A unique identifier for the geometry, based on its properties. (read-only)
+    digest = Property(depends_on=['pos'])
 
     @cached_property
     def _get_digest(self):
         return digest(self)
 
     @cached_property
-    def _get_basename(self):
-        return path.splitext(path.basename(self.from_file))[0]
-
-    @cached_property
-    def _get_mpos(self):
-        if self.validate_file:
-            if len(self.invalid_channels) == 0:
-                return self.mpos_tot
-            allr = [i for i in range(self.mpos_tot.shape[-1]) if i not in self.invalid_channels]
-            return self.mpos_tot[:, array(allr)]
-        raise FileNotFoundError(errno.ENOENT, strerror(errno.ENOENT), self.from_file)
+    def _get_pos(self):
+        if len(self.invalid_channels) == 0:
+            return self.pos_total
+        allr = [i for i in range(self.pos_total.shape[-1]) if i not in self.invalid_channels]
+        return self.pos_total[:, array(allr)]
 
     @cached_property
     def _get_num_mics(self):
-        return self.mpos.shape[-1]
+        return self.pos.shape[-1]
 
     @cached_property
     def _get_center(self):
-        if self.mpos.any():
-            center = average(self.mpos, axis=1)
+        if self.pos.any():
+            center = average(self.pos, axis=1)
             # set very small values to zero
             center[abs(center) < 1e-16] = 0.0
             return center
@@ -95,45 +182,81 @@ class MicGeom(HasPrivateTraits):
 
     @cached_property
     def _get_aperture(self):
-        if self.mpos.any():
-            return cdist(self.mpos.T, self.mpos.T).max()
+        if self.pos.any():
+            return cdist(self.pos.T, self.pos.T).max()
         return None
 
-    @on_trait_change('basename')
-    def import_mpos(self):
-        """Import the microphone positions from .xml file.
-        Called when :attr:`basename` changes.
-        """
-        if not path.isfile(self.from_file):
-            # no file there
-            self.mpos_tot = array([], 'd')
-            # raise error: File not found on _get functions
-            self.validate_file = False
-
-        import xml.dom.minidom
-
-        doc = xml.dom.minidom.parse(self.from_file)
+    @on_trait_change('file')
+    def _import_mpos(self):
+        # Import the microphone positions from an XML file.
+        #
+        # This method parses the XML file specified in :attr:`file` and extracts the ``x``, ``y``,
+        # and ``z`` positions of microphones. The data is stored in :attr:`pos_total` attribute as
+        # an array of shape ``(3,`` :attr:`num_mics` ``)``.
+        #
+        # This method is called when :attr:`file` changes.
+        #
+        # Raises
+        # ------
+        # xml.parsers.expat.ExpatError
+        #     If the XML file is malformed or cannot be parsed.
+        # ValueError
+        #     If the attributes ``x``, ``y``, or ``z`` in any ``<pos>`` element are missing or
+        #     cannot be converted to a float.
+        #
+        # Examples
+        # --------
+        # The microphone geometry changes by changing the :attr:`file` attribute.
+        #
+        # >>> from acoular import MicGeom  # doctest: +SKIP
+        # >>> mg = MicGeom(file='/path/to/geom1.xml')  # doctest: +SKIP
+        # >>> mg.center  # doctest: +SKIP
+        # array([-0.25,  0.  ,  0.25]) # doctest: +SKIP
+        # >>> mg.file = '/path/to/geom2.xml'  # doctest: +SKIP
+        # >>> mg.center  # doctest: +SKIP
+        # array([0.        , 0.33333333, 0.66666667]) # doctest: +SKIP
+        doc = xml.dom.minidom.parse(self.file)
         names = []
         xyz = []
         for el in doc.getElementsByTagName('pos'):
             names.append(el.getAttribute('Name'))
             xyz.append([float(el.getAttribute(a)) for a in 'xyz'])
-        self.mpos_tot = array(xyz, 'd').swapaxes(0, 1)
-        self.validate_file = True
+        self.pos_total = array(xyz, 'd').swapaxes(0, 1)
 
     def export_mpos(self, filename):
-        """Export the microphone positions to .xml file.
+        """
+        Export the microphone positions to an XML file.
+
+        This method generates an XML file containing the positions of all valid microphones in the
+        array. Each microphone is represented by a ``<pos>`` element with ``Name``, ``x``, ``y``,
+        and ``z`` attributes. The generated XML is formatted to match the structure required for
+        importing into the :class:`MicGeom` class.
 
         Parameters
         ----------
-        filename : str
-            Name of the file to which the microphone positions are written.
+        filename : :class:`str`
+            The path to the file to which the microphone positions will be written. The file
+            extension must be ``.xml``.
+
+        Raises
+        ------
+        :obj:`OSError`
+            If the file cannot be written due to permissions issues or invalid file paths.
+
+        Notes
+        -----
+        - The file will be saved in UTF-8 encoding.
+        - The ``Name`` attribute for each microphone is set as ``"Point {i+1}"``, where ``i`` is the
+          index of the microphone.
+        - This method only exports the positions of the valid microphones (those not listed in
+          :attr:`invalid_channels`).
         """
-        basename = path.splitext(path.basename(filename))[0]
-        with open(filename, 'w') as f:
+        filepath = Path(filename)
+        basename = filepath.stem
+        with filepath.open('w', encoding='utf-8') as f:
             f.write(f'<?xml version="1.1" encoding="utf-8"?><MicArray name="{basename}">\n')
-            for i in range(self.mpos.shape[-1]):
+            for i in range(self.pos.shape[-1]):
                 f.write(
-                    f'  <pos Name="Point {i+1}" x="{self.mpos[0, i]}" y="{self.mpos[1, i]}" z="{self.mpos[2, i]}"/>\n',
+                    f'  <pos Name="Point {i+1}" x="{self.pos[0, i]}" y="{self.pos[1, i]}" z="{self.pos[2, i]}"/>\n',
                 )
             f.write('</MicArray>')