timoshenko-engine 2.0.1__py3-none-any.whl

timoshenko/health.py

@@ -0,0 +1,149 @@
+"""Evidence-oriented modal health comparison."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+from .modal import ModalResult, identify, pair_modes
+from .multichannel import MultiChannelData
+from .oma import FDDResult, identify_fdd
+from .sensors import SensorData
+from .structure import Structure
+
+
+@dataclass(frozen=True)
+class ModeChange:
+    """One observed mode compared with the reference mode it was paired to.
+
+    ``mode_number`` is the 1-based reference mode and ``observed_mode_number``
+    the 1-based position in the modal result. A change no larger than the
+    spectral resolution is ``resolution_limited``: its sign and size are set
+    by the frequency grid, not by the structure.
+    """
+
+    mode_number: int
+    reference_frequency_hz: float
+    observed_frequency_hz: float
+    change_pct: float
+    observed_mode_number: int = 0
+    resolution_limited: bool = False
+
+
+@dataclass(frozen=True)
+class HealthAssessment:
+    structure_id: str
+    status: str
+    mode_changes: tuple[ModeChange, ...]
+    modal_result: ModalResult | FDDResult
+    review_recommended: bool
+    evidence_summary: str
+    limitations: tuple[str, ...]
+    review_threshold_pct: float | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "structure_id": self.structure_id,
+            "status": self.status,
+            "mode_changes": [
+                {
+                    "mode_number": item.mode_number,
+                    "observed_mode_number": item.observed_mode_number,
+                    "reference_frequency_hz": item.reference_frequency_hz,
+                    "observed_frequency_hz": item.observed_frequency_hz,
+                    "change_pct": item.change_pct,
+                    "resolution_limited": item.resolution_limited,
+                }
+                for item in self.mode_changes
+            ],
+            "modal_result": self.modal_result.to_dict(),
+            "review_recommended": self.review_recommended,
+            "review_threshold_pct": self.review_threshold_pct,
+            "evidence_summary": self.evidence_summary,
+            "limitations": list(self.limitations),
+        }
+
+
+def validate_review_threshold(value: float | None) -> float | None:
+    """Return a finite positive review threshold in percent, or ``None``."""
+    if value is None:
+        return None
+    threshold = float(value)
+    if not math.isfinite(threshold) or threshold <= 0.0:
+        raise ValueError("review_threshold_pct must be finite and greater than zero, or None")
+    return threshold
+
+
+def assess(
+    *,
+    structure: Structure,
+    observations: SensorData | MultiChannelData,
+    modal_result: ModalResult | FDDResult | None = None,
+    review_threshold_pct: float | None = None,
+) -> HealthAssessment:
+    """Compare observed frequencies with the structure's preserved baseline.
+
+    Observed modes are paired with reference modes by nearest frequency (see
+    :func:`timoshenko.modal.pair_modes`). ``review_recommended`` is raised
+    only when the caller supplies ``review_threshold_pct`` and a paired mode
+    drops by at least that percentage by more than the spectral resolution.
+    The engine does not choose that threshold: a meaningful value depends on
+    the asset, its environmental variability, and a calibrated baseline.
+    No safety category or probability of failure is assigned.
+    """
+    if not isinstance(structure, Structure):
+        raise TypeError("structure must be a timoshenko.Structure")
+    if not isinstance(observations, (SensorData, MultiChannelData)):
+        raise TypeError("observations must be SensorData or MultiChannelData")
+    threshold = validate_review_threshold(review_threshold_pct)
+    if modal_result is not None:
+        result = modal_result
+    elif isinstance(observations, SensorData):
+        result = identify(observations)
+    else:
+        result = identify_fdd(observations)
+    if not isinstance(result, (ModalResult, FDDResult)):
+        raise TypeError("modal_result must be a ModalResult or FDDResult")
+    reference = structure.baseline_frequencies_hz
+    pairs = pair_modes(reference, result.frequencies_hz)
+    changes = []
+    for reference_index, observed_index in pairs:
+        reference_hz = float(reference[reference_index])
+        observed_hz = float(result.modes[observed_index].frequency_hz)
+        changes.append(ModeChange(
+            mode_number=reference_index + 1,
+            reference_frequency_hz=reference_hz,
+            observed_frequency_hz=observed_hz,
+            change_pct=100.0 * (observed_hz - reference_hz) / reference_hz,
+            observed_mode_number=observed_index + 1,
+            resolution_limited=abs(observed_hz - reference_hz) <= result.resolution_hz,
+        ))
+    enough = result.status == "ok" and bool(changes)
+    status = "evidence_available" if enough else "insufficient_evidence"
+    summary = (
+        f"Compared {len(changes)} observed mode(s) with the reference model."
+        if enough
+        else "No usable modal frequency could be compared with the reference model."
+    )
+    notes = [
+        "Frequency shifts can have several causes, including temperature, boundary conditions, sensor placement, and structural change.",
+        "This assessment is not a diagnosis of damage or a statement of structural safety.",
+    ]
+    unpaired = len(result.modes) - len(changes)
+    if unpaired:
+        notes.append(f"{unpaired} observed peak(s) were not paired with a reference mode and were not compared.")
+    if threshold is None:
+        notes.append("No review threshold was supplied, so no review flag is raised; choose one from a calibrated baseline.")
+    review = threshold is not None and any(
+        not change.resolution_limited and change.change_pct <= -threshold for change in changes
+    )
+    return HealthAssessment(
+        structure_id=structure.structure_id,
+        status=status,
+        mode_changes=tuple(changes),
+        modal_result=result,
+        review_recommended=review,
+        evidence_summary=summary,
+        limitations=tuple(notes),
+        review_threshold_pct=threshold,
+    )

timoshenko/mechanics.py

@@ -0,0 +1,54 @@
+"""Small, unit-explicit mechanics calculations for linear elastic materials.
+
+All inputs use SI units. These functions calculate textbook quantities; they
+do not perform code checks, resistance factors, or safety certification.
+"""
+
+from __future__ import annotations
+
+import math
+
+from ._validation import finite as _finite, positive as _positive
+
+
+def axial_stress(force_n: float, area_m2: float) -> float:
+    """Average normal stress ``N/A`` in pascals; tension is positive."""
+    return _finite("force_n", force_n) / _positive("area_m2", area_m2)
+
+
+def bending_stress(moment_nm: float, section_modulus_m3: float) -> float:
+    """Extreme-fiber elastic bending stress ``M/S`` in pascals."""
+    return _finite("moment_nm", moment_nm) / _positive("section_modulus_m3", section_modulus_m3)
+
+
+def average_shear_stress(shear_n: float, area_m2: float) -> float:
+    """Average shear stress ``V/A`` in pascals (not a peak-stress estimate)."""
+    return _finite("shear_n", shear_n) / _positive("area_m2", area_m2)
+
+
+def rectangular_max_shear_stress(shear_n: float, area_m2: float) -> float:
+    """Maximum elastic shear stress ``1.5 V/A`` for a solid rectangle."""
+    return 1.5 * average_shear_stress(shear_n, area_m2)
+
+
+def axial_strain(stress_pa: float, youngs_modulus_pa: float) -> float:
+    """Uniaxial elastic strain ``sigma/E`` (dimensionless)."""
+    return _finite("stress_pa", stress_pa) / _positive("youngs_modulus_pa", youngs_modulus_pa)
+
+
+def thermal_strain(expansion_per_k: float, temperature_change_k: float) -> float:
+    """Free isotropic thermal strain ``alpha * delta_T`` (dimensionless)."""
+    alpha = float(expansion_per_k)
+    delta_t = float(temperature_change_k)
+    if not math.isfinite(alpha) or not math.isfinite(delta_t):
+        raise ValueError("thermal expansion coefficient and temperature change must be finite")
+    return alpha * delta_t
+
+
+def youngs_modulus_from_shear(shear_modulus_pa: float, poisson_ratio: float) -> float:
+    """Return ``E = 2 G (1 + nu)`` for an isotropic linear elastic material."""
+    shear = _positive("shear_modulus_pa", shear_modulus_pa)
+    nu = float(poisson_ratio)
+    if not math.isfinite(nu) or not -1.0 < nu < 0.5:
+        raise ValueError("poisson_ratio must be finite and satisfy -1 < nu < 0.5")
+    return 2.0 * shear * (1.0 + nu)

timoshenko/modal.py

@@ -0,0 +1,243 @@
+"""Frequency-domain operational modal identification for one sensor channel."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+import numpy as np
+
+from .sensors import SensorData
+from .oma import FDDMode, FDDResult, identify_fdd
+
+
+@dataclass(frozen=True)
+class Mode:
+    frequency_hz: float
+    amplitude: float
+    damping_ratio: float | None = None
+
+
+@dataclass(frozen=True)
+class ModalResult:
+    modes: tuple[Mode, ...]
+    sampling_hz: float
+    sample_count: int
+    resolution_hz: float
+    channel: str
+    method: str = "hann_windowed_fft_peak_picking"
+    status: str = "ok"
+    notes: tuple[str, ...] = ()
+
+    @property
+    def frequencies_hz(self) -> tuple[float, ...]:
+        return tuple(mode.frequency_hz for mode in self.modes)
+
+    def to_dict(self) -> dict:
+        return {
+            "modes": [
+                {"frequency_hz": mode.frequency_hz, "amplitude": mode.amplitude, "damping_ratio": mode.damping_ratio}
+                for mode in self.modes
+            ],
+            "sampling_hz": self.sampling_hz,
+            "sample_count": self.sample_count,
+            "resolution_hz": self.resolution_hz,
+            "channel": self.channel,
+            "method": self.method,
+            "status": self.status,
+            "notes": list(self.notes),
+        }
+
+
+def identify(
+    sensor_data: SensorData,
+    *,
+    max_modes: int = 6,
+    min_frequency_hz: float | None = None,
+    max_frequency_hz: float | None = None,
+    min_peak_ratio: float = 0.03,
+) -> ModalResult:
+    """Estimate modal peaks with a Hann-windowed single-sided FFT.
+
+    This simple operational modal analysis uses one channel, so modes may be
+    missed when that sensor is near a modal node. It is intended as a
+    screening estimate; poly-reference identification and mode shapes are not
+    part of release 0.1.
+    """
+    if not isinstance(sensor_data, SensorData):
+        raise TypeError("sensor_data must be a timoshenko.SensorData; use tm.load_sensors() first")
+    resolution, low, high = _plan(
+        len(sensor_data.samples),
+        sensor_data.sampling_hz,
+        max_modes=max_modes,
+        min_frequency_hz=min_frequency_hz,
+        max_frequency_hz=max_frequency_hz,
+        min_peak_ratio=min_peak_ratio,
+    )
+
+    values = np.asarray(sensor_data.samples, dtype=float)
+    values = values - float(np.mean(values))
+    if float(np.max(np.abs(values))) <= np.finfo(float).eps:
+        return ModalResult((), sensor_data.sampling_hz, len(values), resolution, sensor_data.channel, status="insufficient_signal", notes=("The input channel is constant after mean removal.",))
+    window = np.hanning(len(values))
+    spectrum = np.abs(np.fft.rfft(values * window))
+    frequencies = np.fft.rfftfreq(len(values), d=1.0 / sensor_data.sampling_hz)
+    in_band = (frequencies >= low) & (frequencies <= high)
+    candidates = [
+        idx for idx in range(1, len(spectrum) - 1)
+        if in_band[idx] and spectrum[idx] >= spectrum[idx - 1] and spectrum[idx] > spectrum[idx + 1]
+    ]
+    max_amplitude = float(max((spectrum[idx] for idx in candidates), default=0.0))
+    candidates = [idx for idx in candidates if max_amplitude > 0.0 and spectrum[idx] >= max_amplitude * min_peak_ratio]
+    selected: list[int] = []
+    for idx in sorted(candidates, key=lambda item: float(spectrum[item]), reverse=True):
+        if all(abs(float(frequencies[idx] - frequencies[other])) >= 2.0 * resolution for other in selected):
+            selected.append(idx)
+        if len(selected) >= max_modes:
+            break
+    selected.sort(key=lambda item: float(frequencies[item]))
+    damping_psd = _averaged_psd(values, sensor_data.sampling_hz)
+    modes = tuple(
+        Mode(
+            frequency_hz=float(frequencies[idx]),
+            amplitude=float(spectrum[idx]),
+            damping_ratio=None if damping_psd is None else _half_power_damping(*damping_psd, float(frequencies[idx])),
+        )
+        for idx in selected
+    )
+    notes = ["Frequency spacing is limited by the record duration."] if resolution > 0.25 else []
+    if any(mode.damping_ratio is not None for mode in modes):
+        notes.append(
+            "Damping ratios are coarse half-power screening estimates from an averaged spectrum; "
+            "expect scatter of about a factor of two on ambient data."
+        )
+    if any(mode.damping_ratio is None for mode in modes):
+        notes.append(
+            "Damping is withheld where the record is too short to resolve the half-power bandwidth "
+            f"with {_MIN_DAMPING_AVERAGES} averages and at least {_MIN_DAMPING_BINS:g} frequency bins."
+        )
+    notes = tuple(notes)
+    return ModalResult(
+        modes=modes,
+        sampling_hz=sensor_data.sampling_hz,
+        sample_count=len(values),
+        resolution_hz=resolution,
+        channel=sensor_data.channel,
+        status="ok" if modes else "no_peaks_found",
+        notes=notes,
+    )
+
+
+def pair_modes(reference_hz, observed_hz) -> tuple[tuple[int, int], ...]:
+    """Pair observed with reference frequencies by nearest log-frequency.
+
+    Each observed frequency is assigned to the reference mode it is closest
+    to on a logarithmic scale; when several observed peaks claim the same
+    reference mode only the closest one is kept. Returns ``(reference_index,
+    observed_index)`` pairs in reference order. Unlike index pairing, a mode
+    missed at a sensor node, or a spurious peak, does not shift the comparison
+    onto the wrong reference mode. A uniform stiffness change scales every
+    frequency by the same factor, so each mode stays nearest to its own
+    reference unless the change exceeds the spacing between modes.
+    """
+    references = [float(value) for value in reference_hz]
+    best: dict[int, tuple[float, int]] = {}
+    for observed_index, value in enumerate(observed_hz):
+        frequency = float(value)
+        if not references or not math.isfinite(frequency) or frequency <= 0.0:
+            continue
+        distances = [abs(math.log(frequency / reference)) for reference in references]
+        reference_index = min(range(len(references)), key=distances.__getitem__)
+        if reference_index not in best or distances[reference_index] < best[reference_index][0]:
+            best[reference_index] = (distances[reference_index], observed_index)
+    return tuple((reference_index, best[reference_index][1]) for reference_index in sorted(best))
+
+
+_MIN_DAMPING_AVERAGES = 8
+_MIN_DAMPING_BINS = 4.0
+
+
+def validate_options(sample_count: int, sampling_hz: float, **options) -> None:
+    """Check ``identify`` options for a record length without any data.
+
+    Raises the same errors ``identify`` would raise for these options, so
+    long-running callers can reject a bad configuration up front.
+    """
+    _plan(int(sample_count), float(sampling_hz), **options)
+
+
+def _plan(
+    sample_count: int,
+    sampling_hz: float,
+    *,
+    max_modes: int = 6,
+    min_frequency_hz: float | None = None,
+    max_frequency_hz: float | None = None,
+    min_peak_ratio: float = 0.03,
+) -> tuple[float, float, float]:
+    """Validate options and return resolution and the searched frequency band."""
+    if max_modes < 1:
+        raise ValueError("max_modes must be at least one")
+    if not 0.0 <= min_peak_ratio < 1.0:
+        raise ValueError("min_peak_ratio must be in [0, 1)")
+    resolution = sampling_hz / sample_count
+    low = float(min_frequency_hz) if min_frequency_hz is not None else resolution
+    high = min(float(max_frequency_hz), sampling_hz / 2.0) if max_frequency_hz is not None else sampling_hz / 2.0
+    if not math.isfinite(low) or low < 0.0 or not math.isfinite(high) or high <= low:
+        raise ValueError("frequency bounds must be finite, non-negative, and have max greater than min")
+    return resolution, low, high
+
+
+def _averaged_psd(values: np.ndarray, sampling_hz: float) -> tuple[np.ndarray, np.ndarray] | None:
+    """Welch power spectrum with 50% overlap and at least eight averages.
+
+    A single periodogram of ambient response fluctuates by about 100% per
+    bin, so its half-power points land on noise spikes. The segment length is
+    the longest power of two that still gives the required averages.
+    """
+    longest = len(values) / (1.0 + (_MIN_DAMPING_AVERAGES - 1) / 2.0)
+    if longest < 64:
+        return None
+    nperseg = 2 ** int(math.floor(math.log2(longest)))
+    window = np.hanning(nperseg)
+    power = np.zeros(nperseg // 2 + 1)
+    count = 0
+    for start in range(0, len(values) - nperseg + 1, nperseg // 2):
+        segment = values[start : start + nperseg]
+        power += np.abs(np.fft.rfft((segment - np.mean(segment)) * window)) ** 2
+        count += 1
+    return power / count, np.fft.rfftfreq(nperseg, d=1.0 / sampling_hz)
+
+
+def _half_power_damping(power: np.ndarray, frequencies: np.ndarray, frequency_hz: float) -> float | None:
+    """Half-power bandwidth damping, or ``None`` when it is not resolved.
+
+    A Hann window alone gives a half-power width of about 1.44 bins, so a
+    bandwidth narrower than ``_MIN_DAMPING_BINS`` bins describes the window
+    and record length rather than the structure.
+    """
+    resolution = float(frequencies[1] - frequencies[0])
+    nearest = int(round(frequency_hz / resolution))
+    low, high = max(1, nearest - 1), min(len(power) - 2, nearest + 1)
+    if high < low:
+        return None
+    peak_idx = low + int(np.argmax(power[low : high + 1]))
+    half_power = float(power[peak_idx]) / 2.0
+    if half_power <= 0.0:
+        return None
+    f_left: float | None = None
+    for idx in range(peak_idx, 0, -1):
+        p0, p1 = float(power[idx - 1]), float(power[idx])
+        if p0 <= half_power < p1:
+            f_left = float(frequencies[idx - 1]) + (half_power - p0) * resolution / (p1 - p0)
+            break
+    f_right: float | None = None
+    for idx in range(peak_idx, len(power) - 1):
+        p0, p1 = float(power[idx]), float(power[idx + 1])
+        if p0 > half_power >= p1:
+            f_right = float(frequencies[idx]) + (p0 - half_power) * resolution / (p0 - p1)
+            break
+    f_peak = float(frequencies[peak_idx])
+    if f_left is None or f_right is None or f_right - f_left < _MIN_DAMPING_BINS * resolution:
+        return None
+    return min(1.0, (f_right - f_left) / (2.0 * f_peak))

timoshenko/monitor.py

@@ -0,0 +1,48 @@
+"""One-shot composition of the 0.1 engineering analysis steps."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .health import HealthAssessment, assess
+from .modal import ModalResult, identify
+from .sensors import SensorData
+from .structure import Structure
+from .update import update
+
+
+@dataclass(frozen=True)
+class MonitoringResult:
+    structure: Structure
+    modal: ModalResult
+    health: HealthAssessment
+
+    def to_dict(self) -> dict:
+        return {
+            "structure": {
+                "structure_id": self.structure.structure_id,
+                "story_count": self.structure.story_count,
+                "natural_frequencies_hz": list(self.structure.natural_frequencies_hz),
+                "reference_frequencies_hz": list(self.structure.baseline_frequencies_hz),
+                "observed_frequencies_hz": list(self.structure.observed_frequencies_hz),
+                "update_scale_factor": self.structure.update_scale_factor,
+                "update_mode_count": self.structure.update_mode_count,
+                "update_mode_scale_spread_pct": self.structure.update_mode_scale_spread_pct,
+                "update_status": self.structure.update_status,
+            },
+            "modal": self.modal.to_dict(),
+            "health": self.health.to_dict(),
+        }
+
+
+def monitor(structure: Structure, sensors: SensorData, *, review_threshold_pct: float | None = None) -> MonitoringResult:
+    """Run modal identification, uniform model update, then health comparison."""
+    modal_result = identify(sensors)
+    updated_structure = update(structure, modal_result) if modal_result.modes else structure
+    health_result = assess(
+        structure=updated_structure,
+        observations=sensors,
+        modal_result=modal_result,
+        review_threshold_pct=review_threshold_pct,
+    )
+    return MonitoringResult(structure=updated_structure, modal=modal_result, health=health_result)