mcp-server-mcsa 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

mcp_server_mcsa/analysis/motor.py

@@ -1,145 +1,147 @@
-"""Motor parameter calculations for MCSA.
-
-Computes synchronous speed, slip, rotor frequency, and expected fault
-frequencies from motor nameplate data and operating conditions.
-"""
-
-from __future__ import annotations
-
-from dataclasses import asdict, dataclass
-
-
-@dataclass(frozen=True)
-class MotorParameters:
-    """Computed operating parameters for an induction motor.
-
-    Attributes:
-        supply_freq_hz: Supply (line) frequency in Hz.
-        poles: Number of magnetic poles.
-        sync_speed_rpm: Synchronous speed in RPM.
-        rotor_speed_rpm: Measured rotor speed in RPM.
-        slip: Per-unit slip (0–1).
-        rotor_freq_hz: Mechanical rotational frequency in Hz.
-        slip_freq_hz: Slip frequency in Hz (s × f_supply).
-    """
-
-    supply_freq_hz: float
-    poles: int
-    sync_speed_rpm: float
-    rotor_speed_rpm: float
-    slip: float
-    rotor_freq_hz: float
-    slip_freq_hz: float
-
-    def to_dict(self) -> dict:
-        return asdict(self)
-
-
-def calculate_motor_parameters(
-    supply_freq_hz: float,
-    poles: int,
-    rotor_speed_rpm: float,
-) -> MotorParameters:
-    """Calculate motor operating parameters from nameplate / measured data.
-
-    Args:
-        supply_freq_hz: Supply frequency in Hz (e.g. 50 or 60).
-        poles: Number of poles (must be even, ≥ 2).
-        rotor_speed_rpm: Measured rotor speed in RPM.
-
-    Returns:
-        MotorParameters with all derived quantities.
-
-    Raises:
-        ValueError: If inputs are physically invalid.
-    """
-    if supply_freq_hz <= 0:
-        raise ValueError(f"Supply frequency must be > 0, got {supply_freq_hz}")
-    if poles < 2 or poles % 2 != 0:
-        raise ValueError(f"Poles must be even and ≥ 2, got {poles}")
-    if rotor_speed_rpm < 0:
-        raise ValueError(f"Rotor speed must be ≥ 0, got {rotor_speed_rpm}")
-
-    sync_speed_rpm = 120.0 * supply_freq_hz / poles
-
-    if rotor_speed_rpm > sync_speed_rpm:
-        raise ValueError(
-            f"Rotor speed ({rotor_speed_rpm} RPM) exceeds synchronous speed "
-            f"({sync_speed_rpm} RPM) — not valid for a motor (generator mode)."
-        )
-
-    slip = (sync_speed_rpm - rotor_speed_rpm) / sync_speed_rpm
-    rotor_freq_hz = rotor_speed_rpm / 60.0
-    slip_freq_hz = slip * supply_freq_hz
-
-    return MotorParameters(
-        supply_freq_hz=supply_freq_hz,
-        poles=poles,
-        sync_speed_rpm=sync_speed_rpm,
-        rotor_speed_rpm=rotor_speed_rpm,
-        slip=slip,
-        rotor_freq_hz=rotor_freq_hz,
-        slip_freq_hz=slip_freq_hz,
-    )
-
-
-def calculate_fault_frequencies(
-    params: MotorParameters,
-    harmonics: int = 3,
-) -> dict:
-    """Calculate expected fault frequencies for common induction‑motor faults.
-
-    Computes characteristic harmonic frequencies for:
-      - Broken Rotor Bars (BRB): sidebands at (1 ± 2ks)·f_s
-      - Eccentricity (static/dynamic): f_s ± k·f_r
-      - Stator inter‑turn faults: f_s ± 2k·f_r
-      - Mixed eccentricity: n·f_r (for n = 1 … harmonics)
-
-    Args:
-        params: Motor operating parameters.
-        harmonics: Number of harmonic orders to compute (default 3).
-
-    Returns:
-        Dictionary with fault type keys → lists of expected frequencies [Hz].
-    """
-    fs = params.supply_freq_hz
-    s = params.slip
-    fr = params.rotor_freq_hz
-
-    # Broken Rotor Bars — sidebands (1 ± 2ks)·fs
-    brb_lower = [(1 - 2 * k * s) * fs for k in range(1, harmonics + 1)]
-    brb_upper = [(1 + 2 * k * s) * fs for k in range(1, harmonics + 1)]
-
-    # Eccentricity — fs ± k·fr
-    ecc_freqs = []
-    for k in range(1, harmonics + 1):
-        ecc_freqs.append({"harmonic_order": k, "lower": fs - k * fr, "upper": fs + k * fr})
-
-    # Stator inter‑turn — fs ± 2k·fr
-    stator_freqs = []
-    for k in range(1, harmonics + 1):
-        stator_freqs.append({"harmonic_order": k, "lower": fs - 2 * k * fr, "upper": fs + 2 * k * fr})
-
-    # Mixed eccentricity — n·fr
-    mixed_ecc = [k * fr for k in range(1, harmonics + 1)]
-
-    return {
-        "motor_parameters": params.to_dict(),
-        "broken_rotor_bars": {
-            "description": "Sidebands at (1 ± 2k·s)·f_supply due to rotor asymmetry",
-            "lower_sidebands_hz": brb_lower,
-            "upper_sidebands_hz": brb_upper,
-        },
-        "eccentricity": {
-            "description": "Sidebands at f_supply ± k·f_rotor due to air‑gap non‑uniformity",
-            "sidebands": ecc_freqs,
-        },
-        "stator_faults": {
-            "description": "Sidebands at f_supply ± 2k·f_rotor due to stator winding asymmetry",
-            "sidebands": stator_freqs,
-        },
-        "mixed_eccentricity": {
-            "description": "Components at n·f_rotor (pure rotational harmonics)",
-            "frequencies_hz": mixed_ecc,
-        },
-    }
+"""Motor parameter calculations for MCSA.
+
+Computes synchronous speed, slip, rotor frequency, and expected fault
+frequencies from motor nameplate data and operating conditions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+
+@dataclass(frozen=True)
+class MotorParameters:
+    """Computed operating parameters for an induction motor.
+
+    Attributes:
+        supply_freq_hz: Supply (line) frequency in Hz.
+        poles: Number of magnetic poles.
+        sync_speed_rpm: Synchronous speed in RPM.
+        rotor_speed_rpm: Measured rotor speed in RPM.
+        slip: Per-unit slip (0–1).
+        rotor_freq_hz: Mechanical rotational frequency in Hz.
+        slip_freq_hz: Slip frequency in Hz (s × f_supply).
+    """
+
+    supply_freq_hz: float
+    poles: int
+    sync_speed_rpm: float
+    rotor_speed_rpm: float
+    slip: float
+    rotor_freq_hz: float
+    slip_freq_hz: float
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def calculate_motor_parameters(
+    supply_freq_hz: float,
+    poles: int,
+    rotor_speed_rpm: float,
+) -> MotorParameters:
+    """Calculate motor operating parameters from nameplate / measured data.
+
+    Args:
+        supply_freq_hz: Supply frequency in Hz (e.g. 50 or 60).
+        poles: Number of poles (must be even, ≥ 2).
+        rotor_speed_rpm: Measured rotor speed in RPM.
+
+    Returns:
+        MotorParameters with all derived quantities.
+
+    Raises:
+        ValueError: If inputs are physically invalid.
+    """
+    if supply_freq_hz <= 0:
+        raise ValueError(f"Supply frequency must be > 0, got {supply_freq_hz}")
+    if poles < 2 or poles % 2 != 0:
+        raise ValueError(f"Poles must be even and ≥ 2, got {poles}")
+    if rotor_speed_rpm < 0:
+        raise ValueError(f"Rotor speed must be ≥ 0, got {rotor_speed_rpm}")
+
+    sync_speed_rpm = 120.0 * supply_freq_hz / poles
+
+    if rotor_speed_rpm > sync_speed_rpm:
+        raise ValueError(
+            f"Rotor speed ({rotor_speed_rpm} RPM) exceeds synchronous speed "
+            f"({sync_speed_rpm} RPM) — not valid for a motor (generator mode)."
+        )
+
+    slip = (sync_speed_rpm - rotor_speed_rpm) / sync_speed_rpm
+    rotor_freq_hz = rotor_speed_rpm / 60.0
+    slip_freq_hz = slip * supply_freq_hz
+
+    return MotorParameters(
+        supply_freq_hz=supply_freq_hz,
+        poles=poles,
+        sync_speed_rpm=sync_speed_rpm,
+        rotor_speed_rpm=rotor_speed_rpm,
+        slip=slip,
+        rotor_freq_hz=rotor_freq_hz,
+        slip_freq_hz=slip_freq_hz,
+    )
+
+
+def calculate_fault_frequencies(
+    params: MotorParameters,
+    harmonics: int = 3,
+) -> dict:
+    """Calculate expected fault frequencies for common induction‑motor faults.
+
+    Computes characteristic harmonic frequencies for:
+      - Broken Rotor Bars (BRB): sidebands at (1 ± 2ks)·f_s
+      - Eccentricity (static/dynamic): f_s ± k·f_r
+      - Stator inter‑turn faults: f_s ± 2k·f_r
+      - Mixed eccentricity: n·f_r (for n = 1 … harmonics)
+
+    Args:
+        params: Motor operating parameters.
+        harmonics: Number of harmonic orders to compute (default 3).
+
+    Returns:
+        Dictionary with fault type keys → lists of expected frequencies [Hz].
+    """
+    fs = params.supply_freq_hz
+    s = params.slip
+    fr = params.rotor_freq_hz
+
+    # Broken Rotor Bars — sidebands (1 ± 2ks)·fs
+    brb_lower = [(1 - 2 * k * s) * fs for k in range(1, harmonics + 1)]
+    brb_upper = [(1 + 2 * k * s) * fs for k in range(1, harmonics + 1)]
+
+    # Eccentricity — fs ± k·fr
+    ecc_freqs = []
+    for k in range(1, harmonics + 1):
+        ecc_freqs.append({"harmonic_order": k, "lower": fs - k * fr, "upper": fs + k * fr})
+
+    # Stator inter‑turn — fs ± 2k·fr
+    stator_freqs = []
+    for k in range(1, harmonics + 1):
+        stator_freqs.append(
+            {"harmonic_order": k, "lower": fs - 2 * k * fr, "upper": fs + 2 * k * fr}
+        )
+
+    # Mixed eccentricity — n·fr
+    mixed_ecc = [k * fr for k in range(1, harmonics + 1)]
+
+    return {
+        "motor_parameters": params.to_dict(),
+        "broken_rotor_bars": {
+            "description": "Sidebands at (1 ± 2k·s)·f_supply due to rotor asymmetry",
+            "lower_sidebands_hz": brb_lower,
+            "upper_sidebands_hz": brb_upper,
+        },
+        "eccentricity": {
+            "description": "Sidebands at f_supply ± k·f_rotor due to air‑gap non‑uniformity",
+            "sidebands": ecc_freqs,
+        },
+        "stator_faults": {
+            "description": "Sidebands at f_supply ± 2k·f_rotor due to stator winding asymmetry",
+            "sidebands": stator_freqs,
+        },
+        "mixed_eccentricity": {
+            "description": "Components at n·f_rotor (pure rotational harmonics)",
+            "frequencies_hz": mixed_ecc,
+        },
+    }

mcp_server_mcsa/analysis/preprocessing.py

@@ -1,180 +1,180 @@
-"""Signal pre‑processing for MCSA.
-
-Offset removal, normalisation, windowing, and digital filtering of
-stator‑current time‑domain signals prior to spectral analysis.
-"""
-
-from __future__ import annotations
-
-from typing import Literal
-
-import numpy as np
-from numpy.typing import NDArray
-from scipy import signal as sig
-
-
-def remove_dc_offset(x: NDArray[np.floating]) -> NDArray[np.floating]:
-    """Remove the DC (mean) component from a signal."""
-    return x - np.mean(x)
-
-
-def normalize_signal(
-    x: NDArray[np.floating],
-    nominal_current: float | None = None,
-) -> NDArray[np.floating]:
-    """Normalise signal amplitude.
-
-    Args:
-        x: Input signal.
-        nominal_current: If provided, normalise to this value (p.u.).
-            Otherwise normalise by RMS.
-
-    Returns:
-        Normalised signal array.
-    """
-    if nominal_current is not None and nominal_current > 0:
-        return x / nominal_current
-    rms = np.sqrt(np.mean(x ** 2))
-    if rms == 0:
-        return x
-    return x / rms
-
-
-def apply_window(
-    x: NDArray[np.floating],
-    window: Literal["hann", "hamming", "blackman", "flattop", "rectangular"] = "hann",
-) -> NDArray[np.floating]:
-    """Apply a window function to the signal.
-
-    Args:
-        x: Input signal array.
-        window: Window type name.
-
-    Returns:
-        Windowed signal.
-    """
-    n = len(x)
-    if window == "rectangular":
-        return x.copy()
-    w = sig.get_window(window, n)
-    return x * w
-
-
-def bandpass_filter(
-    x: NDArray[np.floating],
-    fs: float,
-    low_hz: float,
-    high_hz: float,
-    order: int = 5,
-) -> NDArray[np.floating]:
-    """Apply a Butterworth bandpass filter.
-
-    Args:
-        x: Input signal.
-        fs: Sampling frequency in Hz.
-        low_hz: Lower cutoff frequency.
-        high_hz: Upper cutoff frequency.
-        order: Filter order.
-
-    Returns:
-        Bandpass‑filtered signal.
-    """
-    nyq = fs / 2.0
-    if low_hz <= 0 or high_hz >= nyq or low_hz >= high_hz:
-        raise ValueError(
-            f"Invalid cutoff frequencies: low={low_hz}, high={high_hz}, Nyquist={nyq}"
-        )
-    sos = sig.butter(order, [low_hz / nyq, high_hz / nyq], btype="bandpass", output="sos")
-    return sig.sosfiltfilt(sos, x)
-
-
-def notch_filter(
-    x: NDArray[np.floating],
-    fs: float,
-    notch_freq_hz: float,
-    quality_factor: float = 30.0,
-) -> NDArray[np.floating]:
-    """Apply a notch (band‑reject) filter at a specific frequency.
-
-    Useful for removing strong supply harmonics or converter switching noise.
-
-    Args:
-        x: Input signal.
-        fs: Sampling frequency in Hz.
-        notch_freq_hz: Centre frequency to reject.
-        quality_factor: Q factor (higher = narrower notch).
-
-    Returns:
-        Filtered signal.
-    """
-    b, a = sig.iirnotch(notch_freq_hz, quality_factor, fs)
-    return sig.filtfilt(b, a, x)
-
-
-def lowpass_filter(
-    x: NDArray[np.floating],
-    fs: float,
-    cutoff_hz: float,
-    order: int = 5,
-) -> NDArray[np.floating]:
-    """Apply a Butterworth lowpass filter (anti‑aliasing or smoothing).
-
-    Args:
-        x: Input signal.
-        fs: Sampling frequency in Hz.
-        cutoff_hz: Cutoff frequency in Hz.
-        order: Filter order.
-
-    Returns:
-        Lowpass‑filtered signal.
-    """
-    nyq = fs / 2.0
-    if cutoff_hz <= 0 or cutoff_hz >= nyq:
-        raise ValueError(f"Cutoff must be in (0, {nyq}), got {cutoff_hz}")
-    sos = sig.butter(order, cutoff_hz / nyq, btype="low", output="sos")
-    return sig.sosfiltfilt(sos, x)
-
-
-def preprocess_pipeline(
-    x: NDArray[np.floating],
-    fs: float,
-    nominal_current: float | None = None,
-    window: Literal["hann", "hamming", "blackman", "flattop", "rectangular"] = "hann",
-    bandpass: tuple[float, float] | None = None,
-    notch_freqs: list[float] | None = None,
-    notch_q: float = 30.0,
-) -> NDArray[np.floating]:
-    """Full pre‑processing pipeline for a stator‑current signal.
-
-    Steps (in order):
-      1. DC offset removal
-      2. Optional notch filtering (e.g. supply harmonics)
-      3. Optional bandpass filtering
-      4. Normalisation
-      5. Windowing
-
-    Args:
-        x: Raw current signal.
-        fs: Sampling frequency in Hz.
-        nominal_current: Nominal current for normalisation (A). None → RMS.
-        window: Window function name.
-        bandpass: Optional (low, high) Hz tuple for bandpass filtering.
-        notch_freqs: Optional list of frequencies to notch out.
-        notch_q: Q factor for notch filters.
-
-    Returns:
-        Pre‑processed signal ready for spectral analysis.
-    """
-    y = remove_dc_offset(x)
-
-    if notch_freqs:
-        for nf in notch_freqs:
-            y = notch_filter(y, fs, nf, quality_factor=notch_q)
-
-    if bandpass is not None:
-        y = bandpass_filter(y, fs, bandpass[0], bandpass[1])
-
-    y = normalize_signal(y, nominal_current)
-    y = apply_window(y, window)
-
-    return y
+"""Signal pre‑processing for MCSA.
+
+Offset removal, normalisation, windowing, and digital filtering of
+stator‑current time‑domain signals prior to spectral analysis.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy import signal as sig
+
+
+def remove_dc_offset(x: NDArray[np.floating]) -> NDArray[np.floating]:
+    """Remove the DC (mean) component from a signal."""
+    return x - np.mean(x)
+
+
+def normalize_signal(
+    x: NDArray[np.floating],
+    nominal_current: float | None = None,
+) -> NDArray[np.floating]:
+    """Normalise signal amplitude.
+
+    Args:
+        x: Input signal.
+        nominal_current: If provided, normalise to this value (p.u.).
+            Otherwise normalise by RMS.
+
+    Returns:
+        Normalised signal array.
+    """
+    if nominal_current is not None and nominal_current > 0:
+        return x / nominal_current
+    rms = np.sqrt(np.mean(x ** 2))
+    if rms == 0:
+        return x
+    return x / rms
+
+
+def apply_window(
+    x: NDArray[np.floating],
+    window: Literal["hann", "hamming", "blackman", "flattop", "rectangular"] = "hann",
+) -> NDArray[np.floating]:
+    """Apply a window function to the signal.
+
+    Args:
+        x: Input signal array.
+        window: Window type name.
+
+    Returns:
+        Windowed signal.
+    """
+    n = len(x)
+    if window == "rectangular":
+        return x.copy()
+    w = sig.get_window(window, n)
+    return x * w  # type: ignore[return-value]
+
+
+def bandpass_filter(
+    x: NDArray[np.floating],
+    fs: float,
+    low_hz: float,
+    high_hz: float,
+    order: int = 5,
+) -> NDArray[np.floating]:
+    """Apply a Butterworth bandpass filter.
+
+    Args:
+        x: Input signal.
+        fs: Sampling frequency in Hz.
+        low_hz: Lower cutoff frequency.
+        high_hz: Upper cutoff frequency.
+        order: Filter order.
+
+    Returns:
+        Bandpass‑filtered signal.
+    """
+    nyq = fs / 2.0
+    if low_hz <= 0 or high_hz >= nyq or low_hz >= high_hz:
+        raise ValueError(
+            f"Invalid cutoff frequencies: low={low_hz}, high={high_hz}, Nyquist={nyq}"
+        )
+    sos = sig.butter(order, [low_hz / nyq, high_hz / nyq], btype="bandpass", output="sos")
+    return sig.sosfiltfilt(sos, x)
+
+
+def notch_filter(
+    x: NDArray[np.floating],
+    fs: float,
+    notch_freq_hz: float,
+    quality_factor: float = 30.0,
+) -> NDArray[np.floating]:
+    """Apply a notch (band‑reject) filter at a specific frequency.
+
+    Useful for removing strong supply harmonics or converter switching noise.
+
+    Args:
+        x: Input signal.
+        fs: Sampling frequency in Hz.
+        notch_freq_hz: Centre frequency to reject.
+        quality_factor: Q factor (higher = narrower notch).
+
+    Returns:
+        Filtered signal.
+    """
+    b, a = sig.iirnotch(notch_freq_hz, quality_factor, fs)
+    return sig.filtfilt(b, a, x)
+
+
+def lowpass_filter(
+    x: NDArray[np.floating],
+    fs: float,
+    cutoff_hz: float,
+    order: int = 5,
+) -> NDArray[np.floating]:
+    """Apply a Butterworth lowpass filter (anti‑aliasing or smoothing).
+
+    Args:
+        x: Input signal.
+        fs: Sampling frequency in Hz.
+        cutoff_hz: Cutoff frequency in Hz.
+        order: Filter order.
+
+    Returns:
+        Lowpass‑filtered signal.
+    """
+    nyq = fs / 2.0
+    if cutoff_hz <= 0 or cutoff_hz >= nyq:
+        raise ValueError(f"Cutoff must be in (0, {nyq}), got {cutoff_hz}")
+    sos = sig.butter(order, cutoff_hz / nyq, btype="low", output="sos")
+    return sig.sosfiltfilt(sos, x)
+
+
+def preprocess_pipeline(
+    x: NDArray[np.floating],
+    fs: float,
+    nominal_current: float | None = None,
+    window: Literal["hann", "hamming", "blackman", "flattop", "rectangular"] = "hann",
+    bandpass: tuple[float, float] | None = None,
+    notch_freqs: list[float] | None = None,
+    notch_q: float = 30.0,
+) -> NDArray[np.floating]:
+    """Full pre‑processing pipeline for a stator‑current signal.
+
+    Steps (in order):
+      1. DC offset removal
+      2. Optional notch filtering (e.g. supply harmonics)
+      3. Optional bandpass filtering
+      4. Normalisation
+      5. Windowing
+
+    Args:
+        x: Raw current signal.
+        fs: Sampling frequency in Hz.
+        nominal_current: Nominal current for normalisation (A). None → RMS.
+        window: Window function name.
+        bandpass: Optional (low, high) Hz tuple for bandpass filtering.
+        notch_freqs: Optional list of frequencies to notch out.
+        notch_q: Q factor for notch filters.
+
+    Returns:
+        Pre‑processed signal ready for spectral analysis.
+    """
+    y = remove_dc_offset(x)
+
+    if notch_freqs:
+        for nf in notch_freqs:
+            y = notch_filter(y, fs, nf, quality_factor=notch_q)
+
+    if bandpass is not None:
+        y = bandpass_filter(y, fs, bandpass[0], bandpass[1])
+
+    y = normalize_signal(y, nominal_current)
+    y = apply_window(y, window)
+
+    return y