timoshenko-engine 2.0.1__py3-none-any.whl

timoshenko/sensorthings.py

@@ -0,0 +1,259 @@
+"""Bounded HTTP pull adapter for scalar OGC SensorThings observations."""
+
+from __future__ import annotations
+
+from datetime import datetime
+import hashlib
+import json
+import math
+from typing import Any, Callable
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from .observations import Observation, ObservationBatch
+from .plugins import PLUGIN_API_VERSION
+
+
+class SensorThingsSourceError(RuntimeError):
+    """Raised for SensorThings transport, pagination, or mapping failures."""
+
+
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+
+
+def _origin(url: str) -> tuple[str, str, int]:
+    parsed = urlsplit(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname or parsed.username or parsed.password or parsed.fragment:
+        raise ValueError("SensorThings URLs must be absolute HTTP(S) URLs without embedded credentials or fragments")
+    try:
+        port = parsed.port
+    except ValueError as error:
+        raise ValueError("SensorThings URL contains an invalid port") from error
+    scheme = parsed.scheme.lower()
+    return scheme, parsed.hostname.lower(), _DEFAULT_PORTS[scheme] if port is None else port
+
+
+class _SameOriginRedirectHandler(HTTPRedirectHandler):
+    """Follow HTTP redirects only within the configured origin.
+
+    urllib's default handler follows any redirect and copies request headers,
+    including ``Authorization``, to the new location. A redirect to another
+    host, port, or scheme (including an HTTPS to HTTP downgrade) would hand
+    the bearer token to that origin, so it is refused instead.
+    """
+
+    def __init__(self, origin: tuple[str, str, int]):
+        self._allowed_origin = origin
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        try:
+            target = _origin(newurl)
+        except ValueError:
+            target = None
+        if target != self._allowed_origin:
+            fp.close()
+            raise SensorThingsSourceError(f"refusing HTTP {code} redirect away from the configured SensorThings origin")
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def _phenomenon_timestamp(value: Any) -> float:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError("phenomenonTime must be a timezone-aware ISO-8601 instant")
+    text = value.strip()
+    if "/" in text:
+        raise ValueError("interval phenomenonTime values are not supported; provide instant observations")
+    iso_text = text[:-1] + "+00:00" if text.endswith(("Z", "z")) else text
+    parsed = datetime.fromisoformat(iso_text)
+    if parsed.tzinfo is None or parsed.utcoffset() is None:
+        raise ValueError("phenomenonTime must include a timezone")
+    return parsed.timestamp()
+
+
+class SensorThingsObservationSource:
+    """Read one configured SensorThings Datastream Observations collection.
+
+    Supply the collection URL, a stable sensor identifier, and a unit because
+    this adapter does not perform Datastream metadata discovery. It follows
+    server-provided ``@iot.nextLink`` URLs as opaque pagination cursors and
+    emits one bounded batch per response page. Only scalar numeric ``result``
+    values and instant ``phenomenonTime`` values are mapped. Quality defaults
+    to false unless the caller explicitly opts into another default or maps a
+    boolean property from SensorThings ``parameters``.
+    """
+
+    def __init__(
+        self,
+        observations_url: str,
+        *,
+        sensor_id: str,
+        unit: str,
+        name: str | None = None,
+        source_id: str | None = None,
+        bearer_token: str | None = None,
+        quality_parameter: str | None = None,
+        default_quality: bool = False,
+        timeout_s: float = 15.0,
+        max_response_bytes: int = 4_194_304,
+        max_observations_per_page: int = 4096,
+        fetcher: Callable[[Request, float, int], bytes] | None = None,
+    ):
+        url = str(observations_url).strip()
+        if not url:
+            raise ValueError("observations_url must be non-empty")
+        origin = _origin(url)
+        sensor_value, unit_value = str(sensor_id).strip(), str(unit).strip()
+        if not sensor_value or not unit_value:
+            raise ValueError("sensor_id and unit must be non-empty")
+        timeout = float(timeout_s)
+        byte_limit, observation_limit = int(max_response_bytes), int(max_observations_per_page)
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout_s must be finite and positive")
+        if isinstance(max_response_bytes, bool) or byte_limit != max_response_bytes or not 1 <= byte_limit <= 67_108_864:
+            raise ValueError("max_response_bytes must be an integer between 1 and 67108864")
+        if isinstance(max_observations_per_page, bool) or observation_limit != max_observations_per_page or not 1 <= observation_limit <= 65_536:
+            raise ValueError("max_observations_per_page must be an integer between 1 and 65536")
+        token = None if bearer_token is None else str(bearer_token).strip()
+        if token == "":
+            raise ValueError("bearer_token must be non-empty or None")
+        if type(default_quality) is not bool:
+            raise ValueError("default_quality must be a bool")
+        quality_key = None if quality_parameter is None else str(quality_parameter).strip()
+        if quality_key == "":
+            raise ValueError("quality_parameter must be non-empty or None")
+        self.observations_url = url
+        self.sensor_id = sensor_value
+        self.name = sensor_value if name is None else str(name).strip()
+        if not self.name:
+            raise ValueError("name must be non-empty")
+        self.unit = unit_value
+        self.source_id = str(source_id).strip() if source_id is not None else f"sensorthings:{sensor_value}"
+        if not self.source_id:
+            raise ValueError("source_id must be non-empty")
+        self.bearer_token = token
+        self.quality_parameter = quality_key
+        self.default_quality = default_quality
+        self.timeout_s = timeout
+        self.max_response_bytes = byte_limit
+        self.max_observations_per_page = observation_limit
+        self._origin = origin
+        self._fetcher = fetcher
+        self._next_url: str | None = None
+        self._opened = False
+
+    def open(self) -> None:
+        if self._opened:
+            raise RuntimeError("SensorThings observation source is already open")
+        self._next_url = self.observations_url
+        self._opened = True
+
+    def read_batch(self) -> ObservationBatch | None:
+        if not self._opened:
+            raise RuntimeError("open() must be called before read_batch()")
+        if self._next_url is None:
+            return None
+        page_url, self._next_url = self._next_url, None
+        try:
+            payload = self._fetch_page(page_url)
+            document = json.loads(payload.decode("utf-8"))
+            if not isinstance(document, dict) or not isinstance(document.get("value"), list):
+                raise ValueError("response must be a JSON object with a 'value' array")
+            items = document["value"]
+            if len(items) > self.max_observations_per_page:
+                raise ValueError(f"response has more than {self.max_observations_per_page} observations")
+            next_link = document.get("@iot.nextLink")
+            if next_link is not None:
+                if not isinstance(next_link, str) or not next_link.strip():
+                    raise ValueError("@iot.nextLink must be a non-empty URL string")
+                next_link = next_link.strip()
+                if _origin(next_link) != self._origin:
+                    raise ValueError("@iot.nextLink must remain on the configured service origin")
+            observations = [self._observation(item, index) for index, item in enumerate(items)]
+            self._next_url = next_link
+            batch_material = [item.get("@iot.id") for item in items]
+            if any(item_id is None for item_id in batch_material):
+                batch_material = items
+            digest = hashlib.sha256(
+                json.dumps(batch_material, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False).encode("utf-8")
+            ).hexdigest()
+            return ObservationBatch(
+                observations,
+                source_id=self.source_id,
+                batch_id=f"{self.source_id}:page:{digest}",
+            )
+        except SensorThingsSourceError:
+            raise
+        except (ValueError, TypeError, KeyError, OverflowError, UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise SensorThingsSourceError(f"invalid SensorThings observation page: {error}") from error
+
+    def _fetch_page(self, url: str) -> bytes:
+        headers = {"Accept": "application/json"}
+        if self.bearer_token is not None:
+            headers["Authorization"] = f"Bearer {self.bearer_token}"
+        request = Request(url, headers=headers, method="GET")
+        try:
+            if self._fetcher is not None:
+                payload = self._fetcher(request, self.timeout_s, self.max_response_bytes)
+            else:
+                opener = build_opener(_SameOriginRedirectHandler(self._origin))
+                with opener.open(request, timeout=self.timeout_s) as response:
+                    status = getattr(response, "status", 200)
+                    if not 200 <= int(status) < 300:
+                        raise SensorThingsSourceError(f"SensorThings server returned HTTP {status}")
+                    payload = response.read(self.max_response_bytes + 1)
+        except SensorThingsSourceError:
+            raise
+        except (HTTPError, URLError, TimeoutError, OSError) as error:
+            raise SensorThingsSourceError(f"SensorThings request failed: {error}") from error
+        if not isinstance(payload, bytes):
+            raise SensorThingsSourceError("SensorThings fetcher must return response bytes")
+        if len(payload) > self.max_response_bytes:
+            raise SensorThingsSourceError(f"SensorThings response exceeded {self.max_response_bytes} bytes")
+        return payload
+
+    def _observation(self, item: Any, index: int) -> Observation:
+        if not isinstance(item, dict):
+            raise ValueError(f"value[{index}] must be an Observation JSON object")
+        result = item.get("result")
+        if isinstance(result, bool) or not isinstance(result, (int, float)):
+            raise ValueError(f"value[{index}].result must be a scalar number")
+        timestamp = _phenomenon_timestamp(item.get("phenomenonTime"))
+        observation_id = item.get("@iot.id")
+        metadata = {} if observation_id is None else {"sensorthings_observation_id": observation_id}
+        quality = self.default_quality
+        if self.quality_parameter is not None:
+            parameters = item.get("parameters")
+            if parameters is not None and not isinstance(parameters, dict):
+                raise ValueError(f"value[{index}].parameters must be an object")
+            if isinstance(parameters, dict) and self.quality_parameter in parameters:
+                parameter_value = parameters[self.quality_parameter]
+                if type(parameter_value) is not bool:
+                    raise ValueError(f"value[{index}].parameters[{self.quality_parameter!r}] must be boolean")
+                quality = parameter_value
+        return Observation(
+            sensor_id=self.sensor_id,
+            name=self.name,
+            unit=self.unit,
+            value=float(result),
+            timestamp=timestamp,
+            quality=quality,
+            source_id=self.source_id,
+            metadata=metadata,
+        )
+
+    def close(self) -> None:
+        self._opened = False
+        self._next_url = None
+
+
+class SensorThingsPlugin:
+    """Built-in source plugin for ``PluginRegistry``."""
+
+    name = "timoshenko-sensorthings"
+    api_version = PLUGIN_API_VERSION
+
+    def register(self, registry) -> None:
+        registry.register_source("sensorthings", SensorThingsObservationSource)
+
+
+__all__ = ["SensorThingsObservationSource", "SensorThingsPlugin", "SensorThingsSourceError"]

timoshenko/session.py

@@ -0,0 +1,388 @@
+"""Bounded-memory event-time monitoring sessions for caller-supplied streams."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+import heapq
+import math
+from typing import Any, Sequence
+
+import numpy as np
+
+from .health import HealthAssessment, assess, validate_review_threshold
+from .modal import ModalResult, identify
+from .modal import validate_options as validate_peak_picking_options
+from .multichannel import MultiChannelData
+from .observations import ObservationBatch
+from .oma import FDDResult, identify_fdd
+from .oma import validate_options as validate_fdd_options
+from .sensors import SensorData
+from .storage import SQLiteStore
+from .structure import Structure
+from .update import update
+
+
+@dataclass(frozen=True)
+class SessionReport:
+    sequence: int
+    event_time_s: float
+    method: str
+    structure: Structure
+    modal: ModalResult | FDDResult
+    health: HealthAssessment
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "sequence": self.sequence,
+            "event_time_s": self.event_time_s,
+            "method": self.method,
+            "structure": {
+                "structure_id": self.structure.structure_id,
+                "natural_frequencies_hz": list(self.structure.natural_frequencies_hz),
+                "reference_frequencies_hz": list(self.structure.baseline_frequencies_hz),
+                "update_status": self.structure.update_status,
+            },
+            "modal": self.modal.to_dict(),
+            "health": self.health.to_dict(),
+        }
+
+
+@dataclass(frozen=True)
+class SessionIngestResult:
+    accepted_count: int
+    rejected_quality_count: int
+    unknown_sensor_count: int
+    missing_timestamp_count: int
+    invalid_time_count: int
+    out_of_order_count: int
+    unit_mismatch_count: int
+    duplicate_batch: bool
+    reports: tuple[SessionReport, ...]
+
+    @property
+    def status(self) -> str:
+        return "analyzed" if self.reports else "buffering"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "status": self.status,
+            "accepted_count": self.accepted_count,
+            "rejected_quality_count": self.rejected_quality_count,
+            "unknown_sensor_count": self.unknown_sensor_count,
+            "missing_timestamp_count": self.missing_timestamp_count,
+            "invalid_time_count": self.invalid_time_count,
+            "out_of_order_count": self.out_of_order_count,
+            "unit_mismatch_count": self.unit_mismatch_count,
+            "duplicate_batch": self.duplicate_batch,
+            "reports": [report.to_dict() for report in self.reports],
+        }
+
+
+@dataclass(frozen=True)
+class SessionRestoreResult:
+    restored_samples: int
+    samples_per_sensor: int
+    ready_for_analysis: bool
+    last_event_time_s: float | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "restored_samples": self.restored_samples,
+            "samples_per_sensor": self.samples_per_sensor,
+            "ready_for_analysis": self.ready_for_analysis,
+            "last_event_time_s": self.last_event_time_s,
+        }
+
+
+class MonitoringSession:
+    """Analyze regularly sampled point observations in bounded rolling windows.
+
+    The host supplies observations; this class does not connect to a broker.
+    Each sensor timestamp is mapped to the nearest sample grid point and must
+    fall within ``timestamp_tolerance_s``. Late/duplicate sensor points are
+    counted and excluded from the active buffer. If a sample is missing, the
+    session waits until a new contiguous full window is available; it never
+    interpolates or bridges a gap.
+
+    Each analysis updates the model supplied at construction, so the reported
+    ``update_scale_factor`` is always relative to that original model. With a
+    store, a batch is persisted only after it has been processed: a batch that
+    fails part-way can be redelivered and its remaining samples still reach
+    the session, while an already processed batch is skipped as a duplicate.
+    """
+
+    def __init__(
+        self,
+        structure: Structure,
+        *,
+        sensor_ids: Sequence[str],
+        units: Sequence[str],
+        sampling_hz: float,
+        window_samples: int,
+        hop_samples: int | None = None,
+        timestamp_tolerance_s: float | None = None,
+        analysis_options: dict[str, Any] | None = None,
+        store: SQLiteStore | None = None,
+        review_threshold_pct: float | None = None,
+    ):
+        if not isinstance(structure, Structure):
+            raise TypeError("structure must be a timoshenko.Structure")
+        ids = tuple(str(value).strip() for value in sensor_ids)
+        unit_values = tuple(str(value).strip() for value in units)
+        hz = float(sampling_hz)
+        window = int(window_samples)
+        hop = max(1, window // 4) if hop_samples is None else int(hop_samples)
+        tolerance = 0.25 / hz if timestamp_tolerance_s is None and math.isfinite(hz) and hz > 0 else float(timestamp_tolerance_s or 0.0)
+        if not ids or len(ids) > 32 or any(not value for value in ids) or len(set(ids)) != len(ids):
+            raise ValueError("sensor_ids must contain 1–32 distinct, non-empty ids")
+        if len(unit_values) != len(ids) or any(not value for value in unit_values):
+            raise ValueError("units must contain one non-empty unit per sensor")
+        if len(ids) > 1 and len(set(unit_values)) != 1:
+            raise ValueError("FDD monitoring requires every channel to use the same measurement unit")
+        if not math.isfinite(hz) or hz <= 0.0:
+            raise ValueError("sampling_hz must be finite and positive")
+        if window < 16 or window > 65_536:
+            raise ValueError("window_samples must be between 16 and 65536")
+        if hop < 1 or hop > window:
+            raise ValueError("hop_samples must be between 1 and window_samples")
+        if not math.isfinite(tolerance) or tolerance < 0.0 or tolerance >= 0.5 / hz:
+            raise ValueError("timestamp_tolerance_s must be finite, non-negative, and less than half a sample interval")
+        if store is not None and not isinstance(store, SQLiteStore):
+            raise TypeError("store must be a SQLiteStore or None")
+
+        self._structure = structure
+        self._sensor_ids = ids
+        self._units = unit_values
+        self._sampling_hz = hz
+        self._window_samples = window
+        self._hop_samples = hop
+        self._timestamp_tolerance_s = tolerance
+        self._options = dict(analysis_options or {})
+        allowed = (
+            {"max_modes", "min_frequency_hz", "max_frequency_hz", "min_peak_ratio"}
+            if len(ids) == 1
+            else {
+                "nperseg", "overlap", "max_modes", "max_singular_values",
+                "min_frequency_hz", "max_frequency_hz", "min_peak_ratio",
+                "min_singular_value_ratio",
+            }
+        )
+        unexpected = set(self._options) - allowed
+        if unexpected:
+            raise ValueError(f"unsupported analysis option(s) for this session: {', '.join(sorted(unexpected))}")
+        # Check option values now; otherwise a bad value surfaces only when the
+        # first full window arrives, possibly hours into a live stream.
+        validate = validate_peak_picking_options if len(ids) == 1 else validate_fdd_options
+        validate(window, hz, **self._options)
+        self._review_threshold_pct = validate_review_threshold(review_threshold_pct)
+        self._baseline_structure = structure
+        self._store = store
+        self._buffers = {sensor_id: deque(maxlen=window) for sensor_id in ids}
+        self._last_key: dict[str, int] = {}
+        self._seen_by_key: dict[int, set[str]] = {}
+        self._seen_key_heap: list[int] = []
+        self._last_complete_key: int | None = None
+        self._complete_run = 0
+        self._last_analysis_key: int | None = None
+        self._sequence = 0
+
+    @property
+    def structure(self) -> Structure:
+        return self._structure
+
+    @property
+    def buffered_samples_by_sensor(self) -> dict[str, int]:
+        return {sensor_id: len(buffer) for sensor_id, buffer in self._buffers.items()}
+
+    def restore(self, *, extra_history_samples: int = 64) -> SessionRestoreResult:
+        """Restore the newest common contiguous window from the configured store.
+
+        The stored structure/model definition remains the caller's input; this
+        method restores observation buffers and stream cursors only. It never
+        re-appends restored observations or reruns an old analysis report.
+        """
+        if self._store is None:
+            raise RuntimeError("restore requires a SQLiteStore configured on this session")
+        extra = int(extra_history_samples)
+        if extra < 0 or extra > 4096:
+            raise ValueError("extra_history_samples must be between 0 and 4096")
+        candidate_limit = min(self._window_samples + extra, 262_144)
+        values_by_sensor: dict[str, dict[int, float]] = {}
+        last_keys: dict[str, int] = {}
+        for sensor_id, unit in zip(self._sensor_ids, self._units):
+            samples: dict[int, float] = {}
+            recent = self._store.recent_observations(
+                sensor_id=sensor_id,
+                unit=unit,
+                limit=candidate_limit,
+            )
+            for observation in recent:
+                if observation.timestamp is None:
+                    continue
+                key = int(round(observation.timestamp * self._sampling_hz))
+                grid_time = key / self._sampling_hz
+                if abs(observation.timestamp - grid_time) > self._timestamp_tolerance_s:
+                    continue
+                samples.setdefault(key, observation.value)
+            values_by_sensor[sensor_id] = samples
+            if samples:
+                last_keys[sensor_id] = max(samples)
+
+        common = set.intersection(*(set(samples) for samples in values_by_sensor.values()))
+        common_keys = sorted(common)
+        contiguous: list[int] = []
+        if common_keys:
+            contiguous = [common_keys[-1]]
+            for key in reversed(common_keys[:-1]):
+                if contiguous[-1] - key != 1:
+                    break
+                contiguous.append(key)
+            contiguous.reverse()
+        restored_keys = contiguous[-self._window_samples :]
+        self._seen_by_key.clear()
+        for sensor_id, buffer in self._buffers.items():
+            buffer.clear()
+            values = values_by_sensor[sensor_id]
+            for key in restored_keys:
+                buffer.append((key, values[key]))
+        for key in restored_keys:
+            self._seen_by_key[key] = set(self._sensor_ids)
+        self._seen_key_heap = list(restored_keys)
+        self._last_complete_key = restored_keys[-1] if restored_keys else None
+        self._complete_run = len(restored_keys)
+        self._last_key = last_keys
+        self._last_analysis_key = restored_keys[-1] if len(restored_keys) >= self._window_samples else None
+        last_time = None if not restored_keys else restored_keys[-1] / self._sampling_hz
+        return SessionRestoreResult(
+            restored_samples=len(restored_keys) * len(self._sensor_ids),
+            samples_per_sensor=len(restored_keys),
+            ready_for_analysis=len(restored_keys) >= self._window_samples,
+            last_event_time_s=last_time,
+        )
+
+    def ingest(self, batch: ObservationBatch) -> SessionIngestResult:
+        if not isinstance(batch, ObservationBatch):
+            raise TypeError("batch must be an ObservationBatch")
+        if self._store is not None and self._store.has_batch(batch):
+            return SessionIngestResult(0, 0, 0, 0, 0, 0, 0, True, ())
+
+        accepted = rejected_quality = unknown = missing_time = invalid_time = out_of_order = unit_mismatch = 0
+        reports: list[SessionReport] = []
+        index_by_sensor = {sensor_id: idx for idx, sensor_id in enumerate(self._sensor_ids)}
+        for observation in batch.observations:
+            idx = index_by_sensor.get(observation.sensor_id)
+            if idx is None:
+                unknown += 1
+                continue
+            if not observation.quality:
+                rejected_quality += 1
+                continue
+            if observation.timestamp is None:
+                missing_time += 1
+                continue
+            if observation.unit != self._units[idx]:
+                unit_mismatch += 1
+                continue
+            key = int(round(observation.timestamp * self._sampling_hz))
+            grid_time = key / self._sampling_hz
+            if abs(observation.timestamp - grid_time) > self._timestamp_tolerance_s:
+                invalid_time += 1
+                continue
+            previous = self._last_key.get(observation.sensor_id)
+            if previous is not None and key <= previous:
+                out_of_order += 1
+                continue
+            self._last_key[observation.sensor_id] = key
+            self._buffers[observation.sensor_id].append((key, observation.value))
+            if key not in self._seen_by_key:
+                self._seen_by_key[key] = set()
+                heapq.heappush(self._seen_key_heap, key)
+            self._seen_by_key[key].add(observation.sensor_id)
+            accepted += 1
+            if len(self._seen_by_key[key]) == len(self._sensor_ids):
+                # Keys complete in increasing order because every sensor's keys
+                # increase, so a run counter tells cheaply whether a full
+                # contiguous window can exist before scanning the buffers.
+                contiguous = self._last_complete_key is not None and key == self._last_complete_key + 1
+                self._complete_run = self._complete_run + 1 if contiguous else 1
+                self._last_complete_key = key
+                if self._complete_run >= self._window_samples:
+                    report = self._maybe_analyze(key)
+                    if report is not None:
+                        reports.append(report)
+            cutoff = key - 2 * self._window_samples
+            while self._seen_key_heap and self._seen_key_heap[0] < cutoff:
+                self._seen_by_key.pop(heapq.heappop(self._seen_key_heap), None)
+
+        if self._store is not None:
+            self._store.append_batch(batch)
+        return SessionIngestResult(accepted, rejected_quality, unknown, missing_time, invalid_time, out_of_order, unit_mismatch, False, tuple(reports))
+
+    def _latest_contiguous_window(self) -> tuple[list[int], np.ndarray] | None:
+        values_by_sensor = {
+            sensor_id: {key: value for key, value in buffer}
+            for sensor_id, buffer in self._buffers.items()
+        }
+        common = set.intersection(*(set(values) for values in values_by_sensor.values()))
+        if not common:
+            return None
+        keys = sorted(common)
+        run: list[int] = [keys[-1]]
+        for key in reversed(keys[:-1]):
+            if run[-1] - key != 1:
+                break
+            run.append(key)
+        run.reverse()
+        if len(run) < self._window_samples:
+            return None
+        selected = run[-self._window_samples :]
+        matrix = np.asarray(
+            [[values_by_sensor[sensor_id][key] for sensor_id in self._sensor_ids] for key in selected],
+            dtype=float,
+        )
+        return selected, matrix
+
+    def _maybe_analyze(self, completed_key: int) -> SessionReport | None:
+        if self._last_analysis_key is not None and completed_key - self._last_analysis_key < self._hop_samples:
+            return None
+        snapshot = self._latest_contiguous_window()
+        if snapshot is None:
+            return None
+        keys, matrix = snapshot
+        if len(self._sensor_ids) == 1:
+            observations: SensorData | MultiChannelData = SensorData(
+                samples=matrix[:, 0],
+                sampling_hz=self._sampling_hz,
+                unit=self._units[0],
+                channel=self._sensor_ids[0],
+            )
+            modal = identify(observations, **self._options)
+            method = "peak_picking"
+        else:
+            observations = MultiChannelData(
+                samples=matrix,
+                sampling_hz=self._sampling_hz,
+                channel_ids=self._sensor_ids,
+                units=self._units,
+            )
+            modal = identify_fdd(observations, **self._options)
+            method = "fdd"
+        if modal.modes:
+            self._structure = update(self._baseline_structure, modal)
+        health = assess(
+            structure=self._structure,
+            observations=observations,
+            modal_result=modal,
+            review_threshold_pct=self._review_threshold_pct,
+        )
+        self._sequence += 1
+        self._last_analysis_key = keys[-1]
+        return SessionReport(
+            sequence=self._sequence,
+            event_time_s=keys[-1] / self._sampling_hz,
+            method=method,
+            structure=self._structure,
+            modal=modal,
+            health=health,
+        )

timoshenko/shafts.py

@@ -0,0 +1,36 @@
+"""Elastic Saint-Venant torsion formulas for circular prismatic shafts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+
+@dataclass(frozen=True)
+class CircularTorsionResult:
+    polar_moment_m4: float
+    maximum_shear_stress_pa: float
+    twist_rad: float
+
+
+def circular_shaft_torsion(torque_nm: float, length_m: float, shear_modulus_pa: float,
+                           outer_diameter_m: float, inner_diameter_m: float = 0.0) -> CircularTorsionResult:
+    """Return elastic outer-fiber shear stress and twist for a round shaft.
+
+    The shaft is prismatic and circular, with constant torque and linear
+    isotropic elastic behavior. An inner diameter of zero describes a solid
+    shaft. Non-circular sections and restrained warping are not covered.
+    """
+    torque, length = float(torque_nm), float(length_m)
+    shear = float(shear_modulus_pa)
+    outer, inner = float(outer_diameter_m), float(inner_diameter_m)
+    if not all(math.isfinite(v) for v in (torque, length, shear, outer, inner)):
+        raise ValueError("all inputs must be finite")
+    if length <= 0.0 or shear <= 0.0 or outer <= 0.0 or inner < 0.0 or inner >= outer:
+        raise ValueError("length, shear modulus, and outer diameter must be positive; inner diameter must be in [0, outer)")
+    polar = math.pi * (outer**4 - inner**4) / 32.0
+    return CircularTorsionResult(
+        polar_moment_m4=polar,
+        maximum_shear_stress_pa=torque * (outer / 2.0) / polar,
+        twist_rad=torque * length / (shear * polar),
+    )