pyPRB 1.0.0__py3-none-any.whl

pyPRB/processing/synchronous_averaging.py

@@ -0,0 +1,321 @@
+"""Synchronous averaging extraction method.
+
+Extracts the fundamental (once-per-revolution) vibration component by
+averaging revolution-locked signal segments.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ._vibration_extractor import _rfft
+
+
+class SynchronousAveraging:
+    """Extracts the fundamental vibration component via synchronous averaging.
+
+    The trigger signal (e.g. from a photoelectric probe) is used to
+    segment the response signal into individual revolutions.  These
+    segments are resampled to a common length and averaged, suppressing
+    noise that is not synchronous with the rotation.  The fundamental
+    component is then extracted from FFT bin 1 of the averaged waveform.
+
+    Parameters
+    ----------
+    edge : str
+        Trigger edge used to define revolution boundaries:
+        ``'rising'`` (default) or ``'falling'``.
+    period_tolerance : float
+        Relative tolerance for rejecting segments whose length deviates
+        from the expected rotation period.  Default is 0.1 (±10 %).
+    plotting : bool
+        If ``True``, show diagnostic plots (trigger crossings and
+        synchronous average) during each call to :meth:`extract`.
+        Requires matplotlib (install with ``pip install pyPRB[plot]``).
+
+    Attributes
+    ----------
+    segments_ : list of np.ndarray
+        Individual resampled revolution segments from the last call to
+        :meth:`extract`.
+    averaged_ : np.ndarray
+        Synchronously averaged waveform from the last call to
+        :meth:`extract`.
+
+    Examples
+    --------
+    >>> from pyPRB.processing import SynchronousAveraging, VibrationExtractor
+    >>> method = SynchronousAveraging(edge='rising', period_tolerance=0.3,
+    ...                               plotting=True)
+    >>> extractor = VibrationExtractor(sample_rate=10000, rotation_freq=25.0,
+    ...                                method=method)
+    """
+
+    def __init__(
+        self,
+        edge: str = "rising",
+        period_tolerance: float = 0.1,
+        plotting: bool = False,
+    ):
+        if edge not in ("rising", "falling"):
+            raise ValueError(f"edge must be 'rising' or 'falling', got '{edge}'.")
+        if not 0 < period_tolerance < 1:
+            raise ValueError(
+                f"period_tolerance must be between 0 and 1, got {period_tolerance}."
+            )
+        self.edge = edge
+        self.period_tolerance = period_tolerance
+        self.plotting = plotting
+        self.segments_: list[np.ndarray] = []
+        self.averaged_: np.ndarray | None = None
+
+    def extract(
+        self,
+        signal: np.ndarray,
+        trigger: np.ndarray,
+        sample_rate: float,
+        rotation_freq: float,
+    ) -> tuple[float, float]:
+        """Extract the fundamental amplitude and phase.
+
+        Parameters
+        ----------
+        signal : np.ndarray
+            Response signal (acceleration, velocity, …).
+        trigger : np.ndarray
+            Trigger signal from a photoelectric probe.
+        sample_rate : float
+            Sampling rate in Hz.
+        rotation_freq : float
+            Rotation frequency in Hz.
+
+        Returns
+        -------
+        amplitude : float
+            Peak amplitude of the fundamental component.
+        phase_deg : float
+            Phase of the fundamental component in degrees.
+        """
+        crossings = self._find_trigger_crossings(trigger)
+
+        expected_period = sample_rate / rotation_freq
+        self.averaged_, self.segments_ = self._synchronous_average(
+            signal, crossings, expected_period,
+        )
+        amplitude, phase_deg = self._extract_fundamental(self.averaged_)
+
+        if self.plotting:
+            time = np.arange(len(trigger)) / sample_rate
+            n_total = len(crossings) - 1
+            n_rejected = n_total - len(self.segments_)
+            self._plot_extraction(
+                time, trigger, crossings, rotation_freq,
+                self.segments_, self.averaged_, amplitude, phase_deg,
+                expected_period=expected_period,
+                n_total=n_total,
+                n_rejected=n_rejected,
+            )
+
+        return amplitude, phase_deg
+
+    def _find_trigger_crossings(self, trigger: np.ndarray) -> np.ndarray:
+        """Return sample indices where the trigger signal crosses its mean.
+
+        Parameters
+        ----------
+        trigger : np.ndarray
+            Trigger signal (e.g. from a photoelectric probe).
+
+        Returns
+        -------
+        np.ndarray
+            Integer sample indices of detected crossings.
+
+        Raises
+        ------
+        ValueError
+            If no crossings are found.
+        """
+        threshold = np.mean(trigger)
+        trigger_bool = trigger > threshold
+        diff = np.diff(trigger_bool.astype(np.int8))
+
+        if self.edge == "rising":
+            crossings = np.where(diff > 0)[0]
+        else:
+            crossings = np.where(diff < 0)[0]
+
+        if len(crossings) == 0:
+            raise ValueError(
+                f"No {self.edge} crossings found in the trigger signal. "
+                "Check that the trigger channel contains a periodic pulse."
+            )
+
+        return crossings
+
+    def _synchronous_average(
+        self,
+        signal: np.ndarray,
+        crossings: np.ndarray,
+        expected_period: float,
+    ) -> tuple[np.ndarray, list[np.ndarray]]:
+        """Average one-revolution segments of *signal* locked to *crossings*.
+
+        Each segment between consecutive trigger crossings is resampled to a
+        common length (median valid period) and then averaged.  Segments whose
+        length deviates more than ``self.period_tolerance`` from
+        *expected_period* are rejected.
+
+        Parameters
+        ----------
+        signal : np.ndarray
+            Response signal.
+        crossings : np.ndarray
+            Sample indices of trigger crossings.
+        expected_period : float
+            Expected period in samples (``sample_rate / rotation_freq``).
+
+        Returns
+        -------
+        averaged : np.ndarray
+            Averaged waveform of length equal to the median valid period.
+        segments : list of np.ndarray
+            Individual resampled segments.
+
+        Raises
+        ------
+        ValueError
+            If fewer than 2 valid segments remain after rejection.
+        """
+        periods = np.diff(crossings)
+
+        lo = (1 - self.period_tolerance) * expected_period
+        hi = (1 + self.period_tolerance) * expected_period
+        valid_mask = (periods >= lo) & (periods <= hi)
+
+        if np.sum(valid_mask) < 2:
+            raise ValueError(
+                f"Only {int(np.sum(valid_mask))} valid segment(s) found "
+                f"(expected period ≈ {expected_period:.0f} samples, "
+                f"tolerance ±{self.period_tolerance*100:.0f}%). "
+                "Check rotation frequency and trigger signal."
+            )
+
+        median_period = np.median(periods[valid_mask])
+        target_samples = int(np.round(median_period))
+
+        segments = []
+        for i in range(len(crossings) - 1):
+            if not valid_mask[i]:
+                continue
+            start = crossings[i]
+            end = crossings[i + 1]
+            if start < 0 or end > len(signal):
+                continue
+            segment = signal[start:end]
+            x_old = np.linspace(0, 1, len(segment))
+            x_new = np.linspace(0, 1, target_samples)
+            resampled = np.interp(x_new, x_old, segment)
+            segments.append(resampled)
+
+        averaged = np.mean(np.array(segments), axis=0)
+        return averaged, segments
+
+    @staticmethod
+    def _extract_fundamental(averaged: np.ndarray) -> tuple[float, float]:
+        """Extract the fundamental amplitude and phase from an averaged waveform.
+
+        The averaged waveform spans exactly one revolution, so FFT bin 1
+        corresponds to the fundamental (once-per-revolution) component.
+
+        Parameters
+        ----------
+        averaged : np.ndarray
+            One-revolution averaged waveform.
+
+        Returns
+        -------
+        amplitude : float
+            Peak amplitude of the fundamental component.
+        phase_deg : float
+            Phase of the fundamental component in degrees.
+        """
+        _, H = _rfft(averaged, sample_rate=len(averaged))
+        amplitude = float(np.abs(H[1]))
+        phase_deg = float(np.degrees(np.angle(H[1])))
+        return amplitude, phase_deg
+
+    # ------------------------------------------------------------------
+    # Plotting
+    # ------------------------------------------------------------------
+
+    def _plot_extraction(
+        self,
+        time: np.ndarray,
+        trigger: np.ndarray,
+        crossings: np.ndarray,
+        rotation_freq: float,
+        segments: list[np.ndarray],
+        averaged: np.ndarray,
+        amplitude: float,
+        phase_deg: float,
+        expected_period: float,
+        n_total: int,
+        n_rejected: int,
+        n_periods: int = 5,
+    ) -> None:
+        """Plot trigger crossings and synchronous average in one figure."""
+        from ._vibration_extractor import _import_matplotlib
+        plt = _import_matplotlib()
+
+        fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(12, 8))
+
+        # -- Trigger crossings --
+        t_end = n_periods / rotation_freq
+        mask = time <= t_end
+
+        ax1.plot(time[mask], trigger[mask], color="steelblue", label="Trigger")
+        ax1.axhline(np.mean(trigger), color="gray", linestyle="--",
+                     linewidth=0.8, label="Threshold")
+
+        crossings_in_window = crossings[crossings < np.sum(mask)]
+        ax1.scatter(time[crossings_in_window], trigger[crossings_in_window],
+                    color="red", zorder=5, s=30, label="Crossings")
+        ax1.set_xlabel("Time (s)")
+        ax1.set_ylabel("Amplitude")
+        ax1.set_title(f"Trigger crossings ({len(crossings)} total, "
+                      f"first {n_periods} periods shown)")
+        ax1.legend()
+
+        # -- Synchronous average --
+        target_samples = len(averaged)
+        angle = np.linspace(0, 360, target_samples, endpoint=False)
+        angle_rad = np.linspace(0, 2 * np.pi, target_samples, endpoint=False)
+        cosine_fit = amplitude * np.cos(angle_rad + np.deg2rad(phase_deg))
+
+        lo = (1 - self.period_tolerance) * expected_period
+        hi = (1 + self.period_tolerance) * expected_period
+
+        for seg in segments:
+            ax2.plot(angle, seg, color="gray", alpha=0.1)
+        ax2.plot(angle, averaged, color="red", linewidth=2, label="Average")
+        ax2.plot(angle, cosine_fit, color="blue", linestyle="--",
+                 label=f"Fundamental: {amplitude:.4g} @ {phase_deg:.1f}\u00b0")
+        ax2.set_xlabel("Angle (\u00b0)")
+        ax2.set_ylabel("Amplitude")
+        ax2.set_xlim(0, 360)
+        ax2.set_xticks(np.arange(0, 361, 45))
+        ax2.axhline(0, color="black", linewidth=0.5, linestyle="--")
+        ax2.set_title(
+            f"Synchronous average \u2014 "
+            f"{len(segments)}/{n_total} segments "
+            f"({n_rejected} rejected, "
+            f"tolerance \u00b1{self.period_tolerance*100:.0f}%)\n"
+            f"Expected period: {expected_period:.0f} samples, "
+            f"bounds: [{lo:.0f}, {hi:.0f}], "
+            f"median period: {target_samples} samples"
+        )
+        ax2.legend()
+
+        plt.tight_layout()
+        plt.show(block=True)

pyprb-1.0.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: pyPRB
+Version: 1.0.0
+Summary: Static and dynamic rotor balancing using portable measurement equipment calculations based on Brüel & Kjær guide.
+Project-URL: homepage, https://github.com/ladisk/pyPRB
+Project-URL: documentation, https://github.com/ladisk/pyPRB
+Project-URL: source, https://github.com/ladisk/pyPRB
+Author-email: Gašper Krivic <gasper.krivic@fs.uni-lj.si>
+Maintainer-email: Gašper Krivic <gasper.krivic@fs.uni-lj.si>
+License-Expression: MIT
+License-File: License
+Keywords: balancing,dynamics,mechanical-engineering,rotor,vibration
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: tabulate>=0.8.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: matplotlib>=3.5.0; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: sphinx; extra == 'dev'
+Requires-Dist: sphinx-book-theme; extra == 'dev'
+Requires-Dist: sphinx-copybutton>=0.5.2; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Requires-Dist: wheel; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5.0; extra == 'plot'
+Description-Content-Type: text/x-rst
+
+Rotor Balancing
+===============
+
+A Python package for static and dynamic rotor balancing calculations based on the methodology described in "Static and Dynamic Balancing using portable measuring equipment" by John Vaughan (Brüel & Kjær Application Note).
+
+
+Features
+--------
+
+* **VibrationVector**: Represents unbalance by means of a vector
+* **MassVector**: Represents a mass placed at an angular position on a rotor
+* **StaticBalancing**: Single-plane balancing for rotors
+* **DynamicBalancing**: Two-plane balancing for rotors
+* **VibrationExtractor**: Extracts vibration vectors from time-domain signals
+* **detect_rotation_freq**: Detects rotation frequency from a trigger signal
+* Four pluggable extraction methods: **IQDemodulation** (default),
+  **LeastSquaresFit**, **SynchronousAveraging**, **FFTExtraction**
+
+Installation
+------------
+
+Install from PyPI:
+
+.. code-block:: bash
+
+    pip install pyPRB
+
+Or install from source:
+
+.. code-block:: bash
+
+    git clone https://github.com/ladisk/pyPRB.git
+    cd pyPRB
+    pip install .
+
+For development installation:
+
+.. code-block:: bash
+
+    pip install -e .[dev]
+
+
+Quick Start
+-----------
+
+Static Balancing Example
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from pyPRB import VibrationVector, MassVector, StaticBalancing
+
+    # Initial measurements
+    V_0 = VibrationVector(amplitude=3.4, phase=116)  # No trial mass
+    V_1 = VibrationVector(amplitude=1.8, phase=42)   # With trial mass
+
+    # Trial mass: 2.0 g mounted at 0° on the rotor
+    trial_mass = MassVector(2.0, 0.0)
+
+    # Create balancer
+    balancer = StaticBalancing(V_0, V_1, trial_mass=trial_mass)
+
+    # Display measurement table
+    print(balancer)
+
+    # Compute compensation
+    comp_mass = balancer.compute_compensation()
+    # Output: Compensation mass: 2.01 g at position -30.8° on the rotor.
+
+
+Dynamic Balancing Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from pyPRB import VibrationVector, MassVector, DynamicBalancing
+
+    # Initial measurements (no trial masses)
+    V_1_0 = VibrationVector(7.2, 238)   # Plane 1
+    V_2_0 = VibrationVector(13.5, 296)  # Plane 2
+
+    # With trial mass in Plane 1
+    V_1_1 = VibrationVector(4.9, 114)   # Plane 1
+    V_2_1 = VibrationVector(9.2, 347)   # Plane 2
+
+    # With trial mass in Plane 2
+    V_1_2 = VibrationVector(4.0, 79)    # Plane 1
+    V_2_2 = VibrationVector(12.0, 292)  # Plane 2
+
+    # Trial masses: 2.5 g each, mounted at 0° on their respective planes
+    trial_mass_1 = MassVector(2.5, 0.0)
+    trial_mass_2 = MassVector(2.5, 0.0)
+
+    # Create balancer
+    balancer = DynamicBalancing(
+        V_1_0, V_2_0, V_1_1, V_2_1, V_1_2, V_2_2,
+        trial_mass_1=trial_mass_1, trial_mass_2=trial_mass_2
+    )
+
+    # Display measurement table
+    print(balancer)
+
+    # Compute compensations for both planes
+    comp_mass_1, comp_mass_2 = balancer.compute_compensation()
+    # Output:
+    # +---------+---------------------+------------+
+    # |  Plane  |  Compensation Mass  |  Position  |
+    # +=========+=====================+============+
+    # |    1    |       2.95 g        |   50.2°    |
+    # +---------+---------------------+------------+
+    # |    2    |       2.84 g        |   -81.9°   |
+    # +---------+---------------------+------------+
+
+
+Extracting Vibration Vectors from Measurements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    import numpy as np
+    from pyPRB import (
+        VibrationExtractor, detect_rotation_freq,
+        MassVector, StaticBalancing,
+    )
+
+    # Synthetic signals (B&K Example 2)
+    sample_rate = 10000  # Hz
+    f0_true = 25.0       # rotation frequency (Hz)
+    duration = 5.0       # s
+    t = np.arange(0, duration, 1 / sample_rate)
+    rng = np.random.default_rng(0)
+
+    trigger = np.sign(np.sin(2 * np.pi * f0_true * t))
+    signal_run0 = (3.4 * np.cos(2 * np.pi * f0_true * t + np.deg2rad(116))
+                   + 0.05 * rng.standard_normal(len(t)))
+    signal_run1 = (1.8 * np.cos(2 * np.pi * f0_true * t + np.deg2rad(42))
+                   + 0.05 * rng.standard_normal(len(t)))
+
+    # 1. Detect rotation frequency from the trigger signal
+    f0 = detect_rotation_freq(trigger, sample_rate=sample_rate, max_freq=50.0)
+
+    # 2. Create extractor (default method: IQ demodulation)
+    extractor = VibrationExtractor(sample_rate=sample_rate, rotation_freq=f0)
+
+    # 3. Extract vibration vectors for each measurement run
+    V_0 = extractor.get_vibration_vector(signal_run0, trigger)
+    V_1 = extractor.get_vibration_vector(signal_run1, trigger)
+
+    # 4. Use the vectors for balancing
+    trial_mass = MassVector(2.0, 0.0)
+    balancer = StaticBalancing(V_0, V_1, trial_mass=trial_mass)
+    comp_mass = balancer.compute_compensation()
+    # Output: Compensation mass: 2.01 g at position -30.8° on the rotor.
+
+
+Balancing procedure
+-------------------
+
+Static Balancing
+~~~~~~~~~~~~~~~~
+
+For a rotor with unbalance in a single plane:
+
+1. Measure initial vibration vector **V₀**
+2. Add known trial mass **m** and measure resulting vibration **V₁**
+3. Compute compensation mass with `StaticBalancing`
+
+Dynamic Balancing
+~~~~~~~~~~~~~~~~~
+
+For a rotor requiring two-plane balancing:
+
+1. Measure initial vibration vectors in both planes: **V₁,₀** and **V₂,₀**
+2. Add trial mass **m₁,₁** in plane 1, measure: **V₁,₁** and **V₂,₁**
+3. Add trial mass **m₂,₂** in plane 2, measure: **V₁,₂** and **V₂,₂**
+4. Compute compensation masses in both planes with `DynamicBalancing`

pyprb-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pyPRB/__init__.py,sha256=ZZ7txiNRkP2D08updlbrMINpo2OiBkGZqHzJUVg4NfY,2292
+pyPRB/__version__.py,sha256=HZH0pz5_uN82TsyQYT2XElxfADrhYTOqcXOuYtt-e-o,142
+pyPRB/core.py,sha256=7XdlQ08FmRMamm8hGTYLHyB3_bKqgtSEo-R6GaRD_Qg,17733
+pyPRB/processing/__init__.py,sha256=Z4S0P3R7mwlRWurEjzvUFvMNlm-xyKV2FZP6oL5UWp0,1219
+pyPRB/processing/_vibration_extractor.py,sha256=jNpZGiqnwjyZcvA3ftRTspFtyWH2_3PQztjpCrJvpCk,10258
+pyPRB/processing/fft_extraction.py,sha256=hagyDYOui93qG5Lgqh7QPVv5TUoHqISw-EK0FqGAXK4,8094
+pyPRB/processing/iq_demodulation.py,sha256=o9eAAUyElh-i0Mj4D6Qx9K2GOjWOuXm4eeYS3bKwI4Q,9375
+pyPRB/processing/least_squares_fit.py,sha256=3JNScG35HUmpUhb157X4ZwymT2q9T5ji14O3uSmO3fE,7273
+pyPRB/processing/synchronous_averaging.py,sha256=GlpmcY54F6nZek2EDcvy_vHEN8BGjclWbcCyVtlKqXQ,11416
+pyprb-1.0.0.dist-info/METADATA,sha256=3_ediBp4iqcTEfaCIRITRYosODm261pAyr0jjtuBZNs,7198
+pyprb-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pyprb-1.0.0.dist-info/licenses/License,sha256=cAmeVSRCFsLHARbJSzk3MUkKSz9k86pVhTF9Irlo3mc,1102
+pyprb-1.0.0.dist-info/RECORD,,

pyprb-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyprb-1.0.0.dist-info/licenses/License

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Gašper Krivic 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.