pyPRB 1.0.0__tar.gz

pyprb-1.0.0/.gitignore

@@ -0,0 +1,109 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+.static_storage/
+.media/
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/build/
+docs/source/api/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# VSCode
+.vscode/

pyprb-1.0.0/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.

pyprb-1.0.0/PKG-INFO

@@ -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/README.rst

@@ -0,0 +1,176 @@
+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/docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx-copybutton
+sphinx-book-theme

pyprb-1.0.0/pyPRB/__init__.py

@@ -0,0 +1,69 @@
+"""
+Rotor Balancing Package
+=======================
+
+A Python package for static and dynamic rotor balancing calculations based on
+the influence coefficient method described in "Static and Dynamic Balancing
+using portable measuring equipment" by John Vaughan, Bruel & Kjaer.
+
+Classes
+-------
+VibrationVector
+    Represents vibration measurements as vectors with amplitude and phase.
+
+MassVector
+    Represents a mass placed at an angular position on a rotor.
+
+StaticBalancing
+    Performs single-plane (static) balancing calculations.
+
+DynamicBalancing
+    Performs two-plane (dynamic) balancing calculations.
+
+Examples
+--------
+Static balancing:
+
+>>> from pyPRB import VibrationVector, MassVector, StaticBalancing
+>>> V_0 = VibrationVector(3.4, 116)  # initial vibration vector
+>>> V_1 = VibrationVector(1.8, 42)  # vibration vector after trial mass
+>>> trial_mass = MassVector(2.0, 0.0)
+>>> balancer = StaticBalancing(V_0, V_1, trial_mass=trial_mass)
+>>> comp_mass = balancer.compute_compensation()
+
+Dynamic balancing:
+
+>>> from pyPRB import VibrationVector, MassVector, DynamicBalancing
+>>> V_1_0 = VibrationVector(7.2, 238)
+>>> V_2_0 = VibrationVector(13.5, 296)
+>>> V_1_1 = VibrationVector(4.9, 114)
+>>> V_2_1 = VibrationVector(9.2, 347)
+>>> V_1_2 = VibrationVector(4.0, 79)
+>>> V_2_2 = VibrationVector(12.0, 292)
+>>> trial_mass_1 = MassVector(2.5, 0.0)
+>>> trial_mass_2 = MassVector(2.5, 0.0)
+>>> 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)
+>>> comp_mass_1, comp_mass_2 = balancer.compute_compensation()
+"""
+
+from .core import VibrationVector, MassVector, StaticBalancing, DynamicBalancing
+from .processing import VibrationExtractor, IQDemodulation, LeastSquaresFit, SynchronousAveraging, FFTExtraction, detect_rotation_freq
+from .__version__ import __version__, __author__, __email__
+
+# Define what gets imported with "from pyPRB import *"
+__all__ = [
+    'VibrationVector',
+    'MassVector',
+    'StaticBalancing',
+    'DynamicBalancing',
+    'VibrationExtractor',
+    'IQDemodulation',
+    'LeastSquaresFit',
+    'SynchronousAveraging',
+    'FFTExtraction',
+    'detect_rotation_freq',
+    '__version__',
+]

pyprb-1.0.0/pyPRB/__version__.py

@@ -0,0 +1,5 @@
+"""Version information for pyPRB package."""
+
+__version__ = '1.0.0'
+__author__ = 'Gašper Krivic'
+__email__ = 'gasper.krivic@fs.uni-lj.si'