feat: save sound composer project (#248)

Co-authored-by: pyansys-ci-bot <[email protected]>

Author: ansaminard

doc/changelog.d/248.added.md

@@ -0,0 +1 @@
+feat: save sound composer project

pyproject.toml

@@ -26,6 +26,7 @@ dependencies = [
     "matplotlib>=3.8.2,<4",
     "platformdirs>=3.6.0",
     "requests>=2.30.0",
+    "scipy>=1.15.2",
 ]
 
 [project.optional-dependencies]

src/ansys/sound/core/signal_processing/filter.py

@@ -24,9 +24,10 @@
 
 import warnings
 
-from ansys.dpf.core import Field, Operator
+from ansys.dpf.core import Field, Operator, TimeFreqSupport, fields_factory, locations
 import matplotlib.pyplot as plt
 import numpy as np
+import scipy
 
 from .._pyansys_sound import PyAnsysSoundException, PyAnsysSoundWarning
 from ..signal_processing import SignalProcessingParent
@@ -42,10 +43,14 @@ class Filter(SignalProcessingParent):
     This class allows designing, loading, and applying a digital filter to a signal. The filter
     coefficients can be provided directly, using the attributes :attr:`b_coefficients` and
     :attr:`a_coefficients`, or computed from a specific frequency response function (FRF), using
-    the methods :meth:`design_FIR_from_FRF` or :meth:`design_FIR_from_FRF_file`. In this latter
-    case, the filter is designed as a minimum-phase FIR filter, and the filter denominator
+    the attribute :attr:`frf` or the method :meth:`design_FIR_from_FRF_file`. In this latter case,
+    the filter is designed as a minimum-phase FIR filter, and the filter denominator
     (:attr:`a_coefficients`) is set to 1 as a consequence.
 
+    Note that only one filter definition source (coefficients, FRF, or FRF file) can be provided
+    when instantiating the class. After class instantiation, anytime the coefficients are changed,
+    the FRF is updated accordingly, and vice versa.
+
     Filtering a signal consists in applying the filter coefficients :math:`b[k]` and :math:`a[k]`
     in the following difference equation, with :math:`x[n]` the input signal, and :math:`y[n]` the
     output signal:
@@ -66,6 +71,7 @@ def __init__(
         b_coefficients: list[float] = None,
         a_coefficients: list[float] = None,
         sampling_frequency: float = 44100.0,
+        frf: Field = None,
         file: str = "",
         signal: Field = None,
     ):
@@ -74,16 +80,21 @@ def __init__(
         Parameters
         ----------
         a_coefficients : list[float], default: None
-            Denominator coefficients of the filter.
+            Denominator coefficients of the filter. This is mutually exclusive with parameters
+            ``frf`` and ``file``.
         b_coefficients : list[float], default: None
-            Numerator coefficients of the filter.
+            Numerator coefficients of the filter. This is mutually exclusive with parameters ``frf``
+            and ``file``.
         sampling_frequency : float, default: 44100.0
             Sampling frequency associated with the filter coefficients, in Hz.
+        frf : Field, default: None
+            Frequency response function (FRF) of the filter, in dB. This is mutually exclusive with
+            parameters ``a_coefficients``, ``b_coefficients``, and ``file``.
         file : str, default: ""
             Path to the file containing the frequency response function (FRF) to load. The text
             file shall have the same text format (with the header `AnsysSound_FRF`), as supported
-            by Ansys Sound SAS. If ``file`` is specified, parameters ``a_coefficients`` and
-            ``b_coefficients`` are ignored.
+            by Ansys Sound SAS. This is mutually exclusive with parameters ``a_coefficients``,
+            ``b_coefficients``, and ``frf``.
         signal : Field, default: None
             Signal to filter.
         """
@@ -95,18 +106,28 @@ def __init__(
 
         self.__sampling_frequency = sampling_frequency
 
-        if file != "":
-            if a_coefficients is not None or b_coefficients is not None:
-                warnings.warn(
-                    PyAnsysSoundWarning(
-                        "Specified parameters a_coefficients and b_coefficients are ignored "
-                        "because FRF file is also specified."
-                    )
-                )
-            self.design_FIR_from_FRF_file(file)
-        else:
+        # Initialize attributes before processing arguments (because of their mutual dependencies).
+        self.__a_coefficients = None
+        self.__b_coefficients = None
+        self.__frf = None
+
+        # Check which filter definition source (coefficients, FRF, or FRF file) is provided (there
+        # should be less than 2).
+        is_coefficients_specified = not (a_coefficients is None and b_coefficients is None)
+        is_frf_specified = frf is not None
+        is_frf_file_specified = file != ""
+        if (is_coefficients_specified + is_frf_specified + is_frf_file_specified) > 1:
+            raise PyAnsysSoundException(
+                "Only one filter definition source (coefficients, FRF, or FRF file) must be "
+                "provided. Specify either `a_coefficients` and `b_coefficients`, `frf`, or `file`."
+            )
+        elif a_coefficients is not None or b_coefficients is not None:
             self.a_coefficients = a_coefficients
             self.b_coefficients = b_coefficients
+        elif frf is not None:
+            self.frf = frf
+        elif file != "":
+            self.design_FIR_from_FRF_file(file)
 
         self.signal = signal
 
@@ -142,6 +163,9 @@ def a_coefficients(self, coefficients: list[float]):
         """Set filter's denominator coefficients."""
         self.__a_coefficients = coefficients
 
+        # Update the FRF to match the new coefficients (if both are set).
+        self.__compute_FRF_from_coefficients()
+
     @property
     def b_coefficients(self) -> list[float]:
         """Numerator coefficients of the filter's transfer function."""
@@ -152,6 +176,34 @@ def b_coefficients(self, coefficients: list[float]):
         """Set filter's numerator coefficients."""
         self.__b_coefficients = coefficients
 
+        # Update the FRF to match the new coefficients (if both are set).
+        self.__compute_FRF_from_coefficients()
+
+    @property
+    def frf(self) -> Field:
+        """Frequency response function (FRF) of the filter.
+
+        Contains the response magnitude in dB of the filter as a function of frequency.
+        """
+        return self.__frf
+
+    @frf.setter
+    def frf(self, frf: Field):
+        """Set frequency response function."""
+        if frf is not None:
+            if not (isinstance(frf, Field)):
+                raise PyAnsysSoundException("Specified FRF must be provided as a DPF field.")
+
+            freq_data = frf.time_freq_support.time_frequencies.data
+            if len(frf.data) < 2 or len(freq_data) < 2:
+                raise PyAnsysSoundException(
+                    "Specified FRF must have at least two frequency points."
+                )
+        self.__frf = frf
+
+        # Update coefficients to match the FRF.
+        self.__compute_coefficients_from_FRF()
+
     @property
     def signal(self) -> Field:
         """Input signal."""
@@ -213,61 +265,30 @@ def design_FIR_from_FRF_file(self, file: str):
         self.__operator_load.run()
 
         # Get the output.
-        frf = self.__operator_load.get_output(0, "field")
-
-        # Compute the filter coefficients.
-        self.design_FIR_from_FRF(frf)
-
-    def design_FIR_from_FRF(self, frf: Field):
-        """Design a minimum-phase FIR filter from a frequency response function (FRF).
-
-        Computes the filter coefficients according to the filter sampling frequency and the
-        provided FRF data.
-
-        .. note::
-            If the maximum frequency specified in the FRF extends beyond half the filter sampling
-            frequency, the FRF data is truncated to this frequency. If, on the contrary, the FRF
-            maximum frequency is lower than half the filter sampling frequency, the FRF is
-            zero-padded between the two.
-
-        Parameters
-        ----------
-        frf : Field
-            Frequency response function (FRF).
-        """
-        # Set operator inputs.
-        self.__operator_design.connect(0, frf)
-        self.__operator_design.connect(1, self.__sampling_frequency)
-
-        # Run the operator.
-        self.__operator_design.run()
-
-        # Get the output.
-        self.b_coefficients = list(map(float, self.__operator_design.get_output(0, "vec_double")))
-        self.a_coefficients = list(map(float, self.__operator_design.get_output(1, "vec_double")))
+        self.frf = self.__operator_load.get_output(0, "field")
 
     def process(self):
         """Filter the signal with the current coefficients."""
         # Check input signal.
         if self.signal is None:
             raise PyAnsysSoundException(
-                f"Input signal is not set. Use {__class__.__name__}.signal."
+                f"Input signal is not set. Use `{__class__.__name__}.signal`."
             )
 
         if self.a_coefficients is None or len(self.a_coefficients) == 0:
             raise PyAnsysSoundException(
                 "Filter's denominator coefficients (a_coefficients) must be defined and cannot be "
-                f"empty. Use {__class__.__name__}.a_coefficients, or the methods "
-                f"{__class__.__name__}.design_FIR_from_FRF() or "
-                f"{__class__.__name__}.design_FIR_from_FRF_file()."
+                f"empty. Use `{__class__.__name__}.a_coefficients`, "
+                f"`{__class__.__name__}.frf`, or the "
+                f"`{__class__.__name__}.design_FIR_from_FRF_file()` method."
             )
 
         if self.b_coefficients is None or len(self.b_coefficients) == 0:
             raise PyAnsysSoundException(
                 "Filter's numerator coefficients (b_coefficients) must be defined and cannot be "
-                f"empty. Use {__class__.__name__}.b_coefficients, or the methods "
-                f"{__class__.__name__}.design_FIR_from_FRF() or "
-                f"{__class__.__name__}.design_FIR_from_FRF_file()."
+                f"empty. Use `{__class__.__name__}.b_coefficients`, "
+                f"`{__class__.__name__}.frf`, or the "
+                f"`{__class__.__name__}.design_FIR_from_FRF_file()` method."
             )
 
         # Set operator inputs.
@@ -293,7 +314,7 @@ def get_output(self) -> Field:
             warnings.warn(
                 PyAnsysSoundWarning(
                     "Output is not processed yet. "
-                    f"Use the {__class__.__name__}.process() method."
+                    f"Use the `{__class__.__name__}.process()` method."
                 )
             )
         return self._output
@@ -317,7 +338,7 @@ def plot(self):
         """Plot the filtered signal in a figure."""
         if self._output == None:
             raise PyAnsysSoundException(
-                f"Output is not processed yet. Use the {__class__.__name__}.process() method."
+                f"Output is not processed yet. Use the `{__class__.__name__}.process()` method."
             )
         output = self.get_output()
 
@@ -329,3 +350,93 @@ def plot(self):
         plt.ylabel("Amplitude")
         plt.grid(True)
         plt.show()
+
+    def plot_FRF(self):
+        """Plot the frequency response function (FRF) of the filter."""
+        if self.frf is None:
+            raise PyAnsysSoundException(
+                "Filter's frequency response function (FRF) is not set. Use "
+                f"`{__class__.__name__}.frf`, or `{__class__.__name__}.a_coefficients` and "
+                f"`{__class__.__name__}.b_coefficients`, or the "
+                f"`{__class__.__name__}.design_FIR_from_FRF_file()` method."
+            )
+
+        plt.plot(self.frf.time_freq_support.time_frequencies.data, self.frf.data)
+        plt.title("Frequency response function (FRF) of the filter")
+        plt.xlabel("Frequency (Hz)")
+        plt.ylabel("Magnitude (dB)")
+        plt.grid(True)
+        plt.show()
+
+    def __compute_coefficients_from_FRF(self):
+        """Design a minimum-phase FIR filter from the frequency response function (FRF).
+
+        Computes the filter coefficients according to the filter sampling frequency and the
+        currently set FRF.
+
+        .. note::
+            If the maximum frequency in the FRF extends beyond half the filter sampling frequency,
+            the FRF data is truncated to this frequency to compute the coefficients. If, on the
+            contrary, the FRF maximum frequency is lower than half the filter sampling frequency,
+            the FRF data is zero-padded between the two.
+        """
+        if self.frf is None:
+            self.__a_coefficients = None
+            self.__b_coefficients = None
+        else:
+            self.__operator_design.connect(0, self.frf)
+            self.__operator_design.connect(1, self.__sampling_frequency)
+
+            self.__operator_design.run()
+
+            # Bypass the coefficients setters to avoid infinite loops.
+            self.__b_coefficients = list(
+                map(float, self.__operator_design.get_output(0, "vec_double"))
+            )
+            self.__a_coefficients = list(
+                map(float, self.__operator_design.get_output(1, "vec_double"))
+            )
+
+    def __compute_FRF_from_coefficients(self):
+        """Compute the frequency response function (FRF) from the filter coefficients.
+
+        Computes the FRF from the filter coefficients, using the function ``scipy.signal.freqz()``.
+        If either the numerator or denominator coefficients are empty or not set, the FRF is set to
+        ``None``.
+
+        .. note::
+            The computed FRF length is equal to the number of coefficients in the filter's
+            numerator.
+        """
+        if (
+            self.b_coefficients is None
+            or self.a_coefficients is None
+            or len(self.b_coefficients) == 0
+            or len(self.a_coefficients) == 0
+        ):
+            self.__frf = None
+        else:
+            freq, complex_response = scipy.signal.freqz(
+                b=self.b_coefficients,
+                a=self.a_coefficients,
+                worN=len(self.b_coefficients),
+                whole=False,
+                plot=None,
+                fs=self.__sampling_frequency,
+                include_nyquist=True,
+            )
+
+            f_freq = fields_factory.create_scalar_field(
+                num_entities=1, location=locations.time_freq
+            )
+            f_freq.append(freq, 1)
+
+            frf_support = TimeFreqSupport()
+            frf_support.time_frequencies = f_freq
+
+            # Bypass the FRF setter to avoid infinite loops.
+            self.__frf = fields_factory.create_scalar_field(
+                num_entities=1, location=locations.time_freq
+            )
+            self.__frf.append(20 * np.log10(abs(complex_response)), 1)
+            self.__frf.time_freq_support = frf_support