RotorVibe

Composable rotating-machine vibration analysis for Python.

RotorVibe turns calibrated waveform blocks into spectra, bearing-frequency markers, condition-relative evidence and inspectable diagnostic candidates. Use the NumPy API inside your own application; the local web dashboard is optional.

Alpha research release, version 0.1.0a5. Signal calculations and bounded software checks are documented. Fault classifiers have not qualified for unattended field diagnosis: new-bearing and independent-rig transfer tests failed. No remaining-life prediction, automatic shutdown authority or standards certification is supplied.

한국어 설명 · User guide · Algorithm notes · Development record · Continue this research · Source/rights policy

Install

Python 3.11+ with NumPy 2.x and SciPy 1.13+ is required.

Install the explicit alpha version (Python 3.11+):

python -m pip install rotorvibe==0.1.0a5

The 0.1.0a5 release integrates P0–P2. GitHub release, PyPI and Zenodo version DOI identify this release. The earlier 0.1.0a1 files remain historical, immutable artifacts.

For an editable checkout and verification tools:

git clone https://github.com/lyullee/rotorvibe.git
cd rotorvibe
python -m pip install -e ".[verification]"
python -m unittest discover -s tests -v

The public facade is rotorvibe; the earlier vibration namespace remains available so existing Python integrations can keep their imports. Raw experimental data and trained rig-specific profiles are acquired separately, not installed by pip.

P0–P2 release and verification

The release preparation passed 224 tests, seven documentation blocks in two clean environments, and 58 additional engineering checks using previously exposed reader fixtures. See combined release record for exact scope, reproduction commands and final publication-check locations. Release CI gates Windows/Linux Python 3.11–3.13, real optional-package checks and installed-wheel regressions before publishing. Counts from historical phases are not added together.

This is software verification. New measured fault accuracy and field remaining-life accuracy remain unqualified. A 48 kHz/four-channel burst case missed its 250 ms latency budget 17 times. The sealed P1 waveforms were not fitted or tested.

P2 composition APIs — 0.1.0a5

These are in-process Python APIs. No server or database is required. All times are seconds in the named caller clock; frequency axes are Hz. See P2 guide for full parameter contracts and verification for results.

The DSP heatmap now averages PSD within explicit frequency bins instead of interpolating isolated grid points. Narrow tones remain visible and discrete PSD power is preserved (apart from the declared display floor). The existing spectrogram['frequencies'] and ['db'] fields remain; bin edges and representation metadata are added. This display is not a lossless STFT or a model feature matrix.

import numpy as np
from rotorvibe import (AnalysisConfig, SignalBlock, VibrationAnalyzer,
                      SpectrogramAccumulator, SpectrogramStage)

fs = 12000
history = SpectrogramAccumulator(hop_seconds=0.25, max_frames=32, max_age_seconds=10)
seen = []
def consumer(result):
    result.payload['metrics']['rms'] = -999  # isolated local edit

analyzer = VibrationAnalyzer(AnalysisConfig(unit='m/s^2'),
    stages={'history': SpectrogramStage(history)}, sinks=(consumer, seen.append))
t = np.arange(2 * fs) / fs
rows = analyzer.push(SignalBlock(np.sin(2 * np.pi * 100 * t), fs,
    unit='m/s^2', channels=('radial',), metadata={'asset_id': 'demo-motor'}))
assert len(rows) == 5 and len(history.snapshot()['rows']) == 5
assert rows[-1].metrics['rms'] > 0 and seen[-1] is not rows[-1]

Run python examples/p2_composition.py for a reviewed illustrative-rule chain. For the optional actual package bridge, first install the inspected Git commit (the version was unavailable from the queried package index), then the local extra:

python -m pip install "git+https://github.com/lyullee/process-monitoring-toolkit.git@79b4cf52a0acd0d0cbd3addbe82c3d98d6385e5a"
python -m pip install ".[process]"
python examples/process_bridge.py

That example runs SignalBatch -> SignalBlock -> AnalysisResult -> feature SignalBatch -> Monitor. Reused synthetic rows demonstrate wiring only. Production fit, calibration and final acquisitions must remain independent. Real remaining-life accuracy and statistical interval calibration are still unqualified.

P1 monitoring APIs — included in 0.1.0a5

P1 adds installation/RPM/load-scoped normal registration, recording-disjoint calibration, actionable holds, coverage-aware evaluation, measured-speed angle features, explicit lifecycle hooks and a bounded host-driven processing queue. These P1 APIs are included in 0.1.0a5; install the pinned version above or this source checkout.

P1 complete composition example

This synthetic example tests API wiring. The four generated records do not prove independent normal sessions, and its evidence flags must not be copied to field data.

import numpy as np
from rotorvibe import (AcquisitionInfo, AcquisitionQualityStage, AnalysisConfig,
    SignalBlock, VibrationAnalyzer, NormalRecording, fit_normal_reference,
    NormalReferenceBank, ReferenceStage, DecisionStage, GuidanceStage,
    AlarmStage, RealtimeProcessor)

fs = 12000
config = AnalysisConfig(sample_rate_hz=fs, unit="g", window_seconds=2,
                        hop_seconds=2, load=0.5, rpm=1200)
# Synthetic test declarations only; measured data need actual reviewed evidence.
info = AcquisitionInfo("demo-rig", "sensor-1", "mount-1", "demo-calibration",
    "2026-11-04", "2027-01-01", ("radial",), ("radial",), fs, "g",
    (1, 6000), 5500, "controller_nominal",
    calibrated=True, mounting_verified=True, anti_alias_verified=True)

def block(index, amplitude, installation="mount-1"):
    source = {"asset_id": "demo-rig", "condition_id": "steady",
              "load_unit": "fraction_rated", "acquisition": info.to_dict()}
    source["acquisition"]["sensor_installation_id"] = installation
    samples = amplitude * np.sin(2 * np.pi * 20 * np.arange(fs * 2) / fs)
    return SignalBlock(samples, fs, unit="g", rpm=1200, start_time_s=index * 2,
                       channels=("radial",), metadata=source)

preprocessor = VibrationAnalyzer(config)
def recording(index, amplitude, role):
    return NormalRecording(f"record-{index}", f"acquisition-{index}",
        (preprocessor.analyze(block(index, amplitude)),), True, role)

profile = fit_normal_reference(
    [recording(0, 1.00, "normal_fit"), recording(1, 1.04, "normal_fit")],
    [recording(2, 1.01, "normal_calibration"),
     recording(3, 1.03, "normal_calibration")],
    name="demo-reference", rpm_range=(1188, 1212), load_range=(0.4, 0.6))
bank = NormalReferenceBank([profile])
analyzer = VibrationAnalyzer(config, stages={
    "acquisition": AcquisitionQualityStage(),
    "reference": ReferenceStage(bank),
    "decision": DecisionStage("reference"),
    "guidance": GuidanceStage("decision"),
    "alarm": AlarmStage(score_stage="decision", expected_score_name="normal_score",
        warning=profile["anomaly_limit"], danger=2 * profile["anomaly_limit"],
        persistence_seconds=0, release_seconds=0),
})
processor = RealtimeProcessor(analyzer, max_pending=2, overflow="reject")
assert processor.submit(block(4, 1.02))["accepted"]
normal = processor.process_next()[0]
assert normal.payload["decision"]["status"] == "normal"
assert processor.submit(block(5, 1.02, installation="new-mount"))["accepted"]
held = processor.process_next()[0]
assert held.payload["decision"]["status"] == "hold"
assert held.payload["guidance"]["required_actions"]
assert held.payload["alarm"]["level"] == "unavailable"
print(normal.payload["decision"]["status"], held.payload["guidance"])
processor.close()

The time reference path requires <=3% within-window speed variation. The optional single-channel angle reference path uses representation='angle' and actual measured RPM; its grid and feature schema are stored in the new profile. The raw trace is available as result.rpm_trace / payload['_rpm_trace']; to_dict(include_features=False) omits it. Existing fixed-speed models still hold on unsupported variable speed.

Profile lifecycle belongs to the host. preserve_profiles=False clears an owned BaselineStage profile; a ReferenceStage detaches from its shared bank without deleting host profiles. Call stage.activate() to reattach; bank.clear() is an explicit host action. For direct analyze() windows the host still declares stream boundaries with reset; automatic continuity detection applies to push(). Custom stages opt in via reset_state(*, preserve_profiles=True).

Benchmarks include a real observed limit: queued 48 kHz/4-channel bursts exceeded a 0.25 s latency budget. Queue controls expose this; they do not make the condition pass. New external archives are sealed and have not trained or qualified these models. See P1 operating guide, verification and remaining qualification and new data receipt.

P0 fixes and common module I/O (0.1.0a2 candidate)

This checkout includes the P0 fixes introduced in the earlier 0.1.0a2 candidate. The archived/PyPI 0.1.0a1 distribution remains unchanged; use the pinned 0.1.0a5 distribution or its matching source tag for these APIs. No new measured-data accuracy or field qualification is claimed.

Common mapping fields:

Thresholds are not interchangeable: a baseline score and a conditioned normal_score have different calibration. Set warning/danger for the selected model and optionally enforce expected_score_name. The adapter does not infer new thresholds.

Executable baseline → common decision → alarm example

Synthetic repeated waves below demonstrate integration, not independent healthy acquisitions or a field-calibrated alarm. Zero persistence is for this short example.

import numpy as np
from rotorvibe import (AnalysisConfig, SignalBlock, VibrationAnalyzer,
                       BaselineStage, DecisionStage, AlarmStage)

fs = 12000
values = 0.2 * np.sin(2 * np.pi * 20 * np.arange(fs) / fs)
config = AnalysisConfig(sample_rate_hz=fs, unit="g", rpm=1200,
                        window_seconds=1, hop_seconds=1)
baseline = BaselineStage(config)
baseline.begin(name="synthetic-demo", windows=20)
analyzer = VibrationAnalyzer(config, stages={
    "baseline": baseline,
    "decision": DecisionStage("baseline"),
    "alarm": AlarmStage(score_stage="decision", expected_score_name="score",
                        persistence_seconds=0, release_seconds=0),
})
for index in range(21):
    result = analyzer.analyze(SignalBlock(
        values, fs, unit="g", start_time_s=index, rpm=1200,
        metadata={"asset_id": "demo-rig", "condition_id": "steady"},
    ))
assert result.payload["decision"]["status"] == "scored"
assert result.payload["alarm"]["level"] == "normal"
held = analyzer.analyze(SignalBlock(
    values, fs, unit="g", start_time_s=21, rpm=1200,
    metadata={"asset_id": "different-rig", "condition_id": "steady"},
))
assert held.payload["decision"]["status"] == "hold"
assert held.payload["alarm"]["level"] == "unavailable"
print(result.payload["decision"], held.payload["alarm"])

Release workflow contract

The initial archive-restoration workflow has been replaced. Release dispatch requires an existing version tag (e.g. v0.1.0a2), never main. The guard checks tag syntax, package/facade versions, HEAD/tag equality and a clean checkout. It performs no source restoration, commit, ref update or push. Build/tests/content audits and an installed wheel/example check precede publishing. PyPI and GitHub use the same build artifacts; SHA256SUMS accompanies the GitHub release. Publishing is triggered only by an explicit version-tag push or release dispatch, not an ordinary branch push.

The candidate has not been published merely by running local validation. See P0 validation and compatibility notes for actual checks.

Module map: purpose, inputs and outputs

Start here when integrating RotorVibe into another Python system. Each row is an importable calculation or integration unit. A web server is not required for the core. Names in rotorvibe.__all__ are available from rotorvibe; deeper utilities use the vibration.* import paths shown below. N = samples, C = channels, W = observations/windows, F = features; Hz = cycles/s and RPM = rev/min.

host DAQ -> SignalBlock + AnalysisConfig -> VibrationAnalyzer
    -> DSP / bearing markers -> ordered stages -> AnalysisResult -> host sinks
                               baseline -> alarm
                               normal gate -> conditional fault-type head
                               caller-supplied measurement rule

Core calculations and replaceable interfaces

Normal references, alarms and experimental diagnostic units

Profiles are explicit dictionaries, not bundled trained models. Training arrays are [W,F]; feature names/order must match at inference. groups[W] identifies original acquisitions, not shuffled windows. scope records the actual asset/sensor/condition contract used by that profile. Keep normal fitting, calibration and final test acquisitions disjoint. These models are experimental, with operational_use=False.

Engineering measurement and user-supplied criteria

The vibration.iso namespace has no distributed ISO/KS threshold tables or machine selectors. Limits come from the caller. available_standards() returns ().

Integration, acquisition, data access and optional service

Exact input contract and configuration parameters

analyze requires N == round(sample_rate_hz * window_seconds); push accepts arbitrary nonempty chunks and returns zero or more complete windows. Config and block sample rate, channel count and input unit must agree. One analyzer instance owns one stream; the host serializes calls and owns DAQ scheduling.

Output contract: what downstream code receives

Stage order is insertion order. Later stages can read earlier named payloads. Raw-window stages receive calibrated full arrays, not plot-decimated arrays. Stage/sink exceptions propagate to the caller; sinks run synchronously after stages. Use separate analyzer instances for different assets. A diagnostic hold or a missing score must not be converted to normal or zero risk by the downstream system.

For every public constructor/method signature and dataclass field, see the complete source-derived API reference. The tables above are the integration map; the user guide explains operating sequences.

A complete first calculation

This generated waveform verifies the API; it is not a measured fault example.

import numpy as np
from rotorvibe import AnalysisConfig, SignalBlock, VibrationAnalyzer

fs = 12000
t = np.arange(fs) / fs
samples = 0.20 * np.sin(2 * np.pi * 20 * t)

analyzer = VibrationAnalyzer(AnalysisConfig(
    sample_rate_hz=fs, channels=1, unit="m/s^2",
    window_seconds=1, hop_seconds=0.25, rpm=1200,
))
result = analyzer.analyze(SignalBlock(
    samples, fs, unit="m/s^2", rpm=1200,
    channels=("drive_radial",), clock_id="daq_elapsed", episode_id="run-001",
    metadata={"asset_id": "motor-01", "condition_id": "rated_load"},
))
print(result.valid, result.metrics)
serializable = result.to_dict(include_features=False)

samples may also be an N × C array. A one-dimensional input represents one channel. Supply the physical unit, channel ordering, time basis and actual asset identity; a numeric array alone cannot establish sensor calibration or installation.

Connect modules directly

The host controls acquisition, scheduling, storage and decisions. An analyzer instance owns one stream; application callbacks receive the results synchronously.

import numpy as np
from rotorvibe import AnalysisConfig, SignalBlock, VibrationAnalyzer
from rotorvibe import BearingGeometry, BearingMap

received = []  # Replace with your own event bus / storage callback.

class MyCalculation:
    def __call__(self, result):
        return {"quality_accepted": result.valid}

fs = 12000
samples = 0.20 * np.sin(2 * np.pi * 20 * np.arange(fs) / fs)
analyzer = VibrationAnalyzer(
    AnalysisConfig(sample_rate_hz=fs, unit="m/s^2", rpm=1200,
                   bearing_id="demo", window_seconds=1),
    bearing_provider=BearingMap({"demo": BearingGeometry(8, 7.0, 35.0)}),
    stages={"host_calculation": MyCalculation()},
    sinks=(received.append,),
)
result = analyzer.analyze(SignalBlock(
    samples, fs, unit="m/s^2", rpm=1200, channels=("drive_radial",),
    clock_id="daq_elapsed", episode_id="run-001",
    metadata={"asset_id": "motor-01", "condition_id": "rated_load"},
))
assert received[0] is not result  # Independent sink snapshot; same output values.
assert received[0].to_dict() == result.to_dict()
assert result.payload["host_calculation"]["quality_accepted"] is True
print(result.metrics["rms"], result.payload["host_calculation"])

For streaming input, call analyzer.push(block) and consume the returned list of completed windows. Gaps, sequence changes, operating identity and clock continuity matter. analyze(block) handles one complete block directly. Raw-window stages can implement analyze_window(result, readonly_values) to use calibrated samples instead of a display-decimated waveform. See composition examples and the module catalog.

What is implemented

Bearing-frequency example

from rotorvibe import BearingGeometry

# Illustrative geometry in a common diameter unit, not a vendor catalog entry.
bearing = BearingGeometry(rolling_elements=8, rolling_diameter=7.0,
                          pitch_diameter=35.0, contact_angle_deg=0)
print(bearing.frequencies(1200))

Diagnostic states are different outcomes

normal means the applicable normal gate accepted the observation. hold means there is no supported decision, not that the machine is healthy. anomaly_unknown means deviation is detected but a trained fault type is not supported. fault_candidate is a hypothesis within the model's recorded scope, not confirmation of a physical root cause. Distances and similarity weights are not calibrated fault probabilities. Keep operational_use=False for the research classifiers.

The morphology head must follow an anomaly gate. A standalone call to FaultDiscriminator assumes that anomaly screening has already happened; it cannot identify a healthy class. A two-stage composition shows the ordering. No downloaded profile is silently enabled.

Evidence: retain the failures

The following experiments have different datasets and protocols. Their percentages must not be merged into a single product accuracy score.

In the latest unadapted evaluation, 580 windows all held in the real API. Zero alerts with zero accepted healthy observations does not demonstrate a zero false-alarm rate. The offline stress route is explicitly separate from the product API and must not be used to hide an asset mismatch. UFRJ native CSV units are not explicit in its official page; both fixed amplitude assumptions are reported without choosing one.

The private research workspace passed 547 checks, including its licensed standards route. That is a historical count, not the public release's test count. Public release checks are recorded separately in research/public_verification.json; the normative table tests are excluded and replaced with synthetic caller-rule checks. Read the latest external assessment and the evidence index before quoting any performance figure.

Standards and copyright boundary

The private development project investigated ten supplied KS/ISO editions. This public release deliberately excludes the PDFs, transcriptions, threshold lookup tables, normative selectors and corresponding table fixtures. vibration.iso now accepts an explicit custom_rule; it does not select an ISO machine category for you. The example rules use invented demonstration numbers, not published standard limits.

Independent algorithm implementations, our explanatory comments and our experiment results are released under MIT. The original external measurements, papers, vendor catalogs and standards retain their own terms. Citation identifiers and legal license text are intentionally preserved; third-party substantive prose and figures are not repackaged. See the rights inventory.

Optional dashboard

rotorvibe-monitor --host 127.0.0.1 --port 8765

The service does not simulate measured validation data when no dataset is present. Use your own live waveform input or explicitly acquired research files. Python hosts that construct Application must call close() to stop workers and sockets. VIBRATION_RUNTIME_HOME selects a writable state directory; VIBRATION_PROJECT_HOME locates separately acquired datasets. Do not point these variables at confidential data when hosting an externally reachable service.

Published artifacts and documentation versions

Version 0.1.0a1 is public on PyPI, GitHub Releases and Zenodo. All three distribute the same SHA-256-verified wheel and source archive. The GitHub main README includes subsequent documentation clarifications; immutable 0.1.0a1 archives and their embedded PyPI README remain the original release snapshot. No numerical model or training data changed.

Reproduce, continue, cite

1. Start with synthetic core checks; they need no PDFs or raw data.
2. Use the source inventory to acquire external files under their own terms.
3. Distinguish historical replay from a new blind test: every previously opened recording is listed as exposed and cannot become a fresh holdout again.
4. Freeze model, preprocessing, thresholds, metadata mapping and record membership before opening the next holdout. Audit by original acquisition, not random windows.
5. Keep independent normal reference, calibration and final-test records. Record unsupported coverage and false negatives as well as correct classifications.

Continuation instructions identify exact commands, preserved artifacts, unavailable private components, model hashes and next validation needs. The archive DOI is 10.5281/zenodo.23937890; use CITATION.cff for software citation. A DOI identifies an archived release; it does not certify a diagnostic model.

Copyright © 2026 Ugwiyeon Lee. Original software: MIT.