timoshenko-engine 2.0.1__py3-none-any.whl

timoshenko/__init__.py

@@ -0,0 +1,173 @@
+"""Timoshenko: composable structural engineering primitives."""
+
+from . import adapters, assets, beams, csv_source, health, mechanics, modal, mqtt, observations, oma, plugins, polygon, pressure, project, report, sections, sensorthings, session, shafts, stability, storage, strength, uncertainty, vibration
+from .assets import Asset, Relation
+from .adapters import AcknowledgingObservationSource, ObservationSource, SessionRunner
+from .csv_source import CSVObservationSource, CSVSourceError
+from .plugins import (
+    ENTRY_POINT_GROUP,
+    PLUGIN_API_VERSION,
+    EnginePlugin,
+    PluginCompatibilityError,
+    PluginContributions,
+    PluginError,
+    PluginLoadError,
+    PluginRegistry,
+)
+from .beams import (
+    BeamDeflection,
+    cantilever_tip_load,
+    cantilever_uniform_load,
+    simply_supported_midpoint_load,
+    simply_supported_uniform_load,
+)
+from .health import HealthAssessment
+from .mechanics import (
+    axial_strain,
+    axial_stress,
+    average_shear_stress,
+    bending_stress,
+    rectangular_max_shear_stress,
+    thermal_strain,
+    youngs_modulus_from_shear,
+)
+from .modal import ModalResult, Mode
+from .mqtt import MQTTSourceError, MqttObservationSource
+from .sensorthings import SensorThingsObservationSource, SensorThingsPlugin, SensorThingsSourceError
+from .monitor import MonitoringResult, monitor
+from .observations import Observation, ObservationBatch
+from .multichannel import MultiChannelData, load_multichannel_csv
+from .oma import FDDMode, FDDResult, identify_fdd
+from .pressure import ThinWallCylinderResult, thin_wall_cylinder_stress
+from .polygon import PolygonSectionProperties, polygon_section
+from .project import LoadedProject, ProjectManifest, ProjectRunResult, load_project, read_manifest, run_project
+from .storage import BatchAppendResult, SQLiteStore
+from .session import MonitoringSession, SessionIngestResult, SessionReport, SessionRestoreResult
+from .sections import SectionProperties
+from .sections import circular_tube as circular_tube_section
+from .sections import i_section
+from .sections import rectangular_tube as rectangular_tube_section
+from .sections import rectangle as rectangle_section
+from .sections import solid_circle as solid_circle_section
+from .sensors import SensorData, load_sensors
+from .shafts import CircularTorsionResult, circular_shaft_torsion
+from .structure import Structure
+from .stability import euler_critical_load
+from .stability import slenderness_ratio
+from .strength import PlaneStressResult, plane_stress
+from .update import update
+from .uncertainty import UncertaintyError, UncertaintyResult, propagate as propagate_uncertainty
+from .vibration import RayleighDampingResult, damping_ratio, harmonic_response, natural_frequency_hz, rayleigh_damping_coefficients
+
+__version__ = "2.0.1"
+
+__all__ = [
+    "HealthAssessment",
+    "Asset",
+    "BatchAppendResult",
+    "CSVObservationSource",
+    "CSVSourceError",
+    "UncertaintyError",
+    "UncertaintyResult",
+    "SensorThingsObservationSource",
+    "SensorThingsPlugin",
+    "SensorThingsSourceError",
+    "BeamDeflection",
+    "CircularTorsionResult",
+    "ModalResult",
+    "Mode",
+    "MonitoringSession",
+    "MqttObservationSource",
+    "MQTTSourceError",
+    "FDDMode",
+    "FDDResult",
+    "LoadedProject",
+    "MultiChannelData",
+    "MonitoringResult",
+    "Observation",
+    "ObservationBatch",
+    "ObservationSource",
+    "AcknowledgingObservationSource",
+    "EnginePlugin",
+    "ENTRY_POINT_GROUP",
+    "PLUGIN_API_VERSION",
+    "PluginCompatibilityError",
+    "PluginContributions",
+    "PluginError",
+    "PluginLoadError",
+    "PluginRegistry",
+    "SensorData",
+    "Structure",
+    "SectionProperties",
+    "ThinWallCylinderResult",
+    "RayleighDampingResult",
+    "PlaneStressResult",
+    "PolygonSectionProperties",
+    "ProjectManifest",
+    "ProjectRunResult",
+    "Relation",
+    "SQLiteStore",
+    "SessionIngestResult",
+    "SessionReport",
+    "SessionRestoreResult",
+    "SessionRunner",
+    "axial_strain",
+    "axial_stress",
+    "average_shear_stress",
+    "bending_stress",
+    "beams",
+    "csv_source",
+    "cantilever_tip_load",
+    "cantilever_uniform_load",
+    "circular_shaft_torsion",
+    "circular_tube_section",
+    "damping_ratio",
+    "euler_critical_load",
+    "harmonic_response",
+    "health",
+    "i_section",
+    "load_sensors",
+    "load_multichannel_csv",
+    "mechanics",
+    "modal",
+    "mqtt",
+    "monitor",
+    "natural_frequency_hz",
+    "identify_fdd",
+    "oma",
+    "observations",
+    "plane_stress",
+    "propagate_uncertainty",
+    "pressure",
+    "project",
+    "plugins",
+    "polygon",
+    "polygon_section",
+    "report",
+    "rectangle_section",
+    "rectangular_tube_section",
+    "rayleigh_damping_coefficients",
+    "rectangular_max_shear_stress",
+    "read_manifest",
+    "sections",
+    "sensorthings",
+    "session",
+    "shafts",
+    "simply_supported_midpoint_load",
+    "simply_supported_uniform_load",
+    "slenderness_ratio",
+    "solid_circle_section",
+    "stability",
+    "strength",
+    "thermal_strain",
+    "thin_wall_cylinder_stress",
+    "update",
+    "vibration",
+    "assets",
+    "adapters",
+    "storage",
+    "uncertainty",
+    "load_project",
+    "run_project",
+    "youngs_modulus_from_shear",
+]

timoshenko/_validation.py

@@ -0,0 +1,19 @@
+"""Shared argument checks for the analytic formula modules."""
+
+from __future__ import annotations
+
+import math
+
+
+def positive(name: str, value: float) -> float:
+    value = float(value)
+    if not math.isfinite(value) or value <= 0.0:
+        raise ValueError(f"{name} must be finite and greater than zero")
+    return value
+
+
+def finite(name: str, value: float) -> float:
+    value = float(value)
+    if not math.isfinite(value):
+        raise ValueError(f"{name} must be finite")
+    return value

timoshenko/adapters.py

@@ -0,0 +1,111 @@
+"""Lifecycle contracts for caller-provided observation sources."""
+
+from __future__ import annotations
+
+from typing import Iterator, Protocol, runtime_checkable
+
+from .observations import ObservationBatch
+from .session import MonitoringSession, SessionIngestResult
+
+
+@runtime_checkable
+class ObservationSource(Protocol):
+    """Synchronous pull-source contract for gateways and replay adapters.
+
+    ``open`` acquires the source, ``read_batch`` returns the next arrival-order
+    batch (or ``None`` at end of stream), and ``close`` releases resources.
+    Implementations own protocol timeouts, reconnect rules, and authentication.
+    """
+
+    def open(self) -> None: ...
+
+    def read_batch(self) -> ObservationBatch | None: ...
+
+    def close(self) -> None: ...
+
+
+@runtime_checkable
+class AcknowledgingObservationSource(ObservationSource, Protocol):
+    """Optional extension for sources that acknowledge only after ingestion."""
+
+    def acknowledge(self, batch: ObservationBatch, result: SessionIngestResult) -> None: ...
+
+
+class SessionRunner:
+    """Drive one monitoring session from a source with explicit cleanup.
+
+    Use as a context manager so early loop exit and exceptions still close the
+    source. The runner does not retry reads or hide source errors.
+    """
+
+    def __init__(
+        self,
+        source: ObservationSource,
+        session: MonitoringSession,
+        *,
+        max_batches: int | None = None,
+    ):
+        if not isinstance(session, MonitoringSession):
+            raise TypeError("session must be a MonitoringSession")
+        if any(not callable(getattr(source, name, None)) for name in ("open", "read_batch", "close")):
+            raise TypeError("source must provide callable open(), read_batch(), and close() methods")
+        if max_batches is not None and (isinstance(max_batches, bool) or int(max_batches) != max_batches or int(max_batches) < 1):
+            raise ValueError("max_batches must be a positive integer or None")
+        self.source = source
+        self.session = session
+        self.max_batches = None if max_batches is None else int(max_batches)
+        self._active = False
+        self._consuming = False
+
+    def __enter__(self) -> "SessionRunner":
+        if self._active:
+            raise RuntimeError("SessionRunner is already active")
+        try:
+            self.source.open()
+        except BaseException as open_error:
+            try:
+                self.source.close()
+            except BaseException as close_error:
+                if hasattr(open_error, "add_note"):
+                    open_error.add_note(f"Source cleanup after open failure also failed: {close_error!r}")
+            raise
+        self._active = True
+        self._consuming = False
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> bool:
+        self._active = False
+        try:
+            self.source.close()
+        except BaseException as close_error:
+            if exc is None:
+                raise
+            if hasattr(exc, "add_note"):
+                exc.add_note(f"Closing the observation source also failed: {close_error!r}")
+        return False
+
+    def __iter__(self) -> Iterator[SessionIngestResult]:
+        if not self._active:
+            raise RuntimeError("use SessionRunner inside a 'with' block")
+        if self._consuming:
+            raise RuntimeError("SessionRunner supports one active iteration at a time")
+        self._consuming = True
+        try:
+            read_count = 0
+            while self.max_batches is None or read_count < self.max_batches:
+                batch = self.source.read_batch()
+                if batch is None:
+                    return
+                if not isinstance(batch, ObservationBatch):
+                    raise TypeError("ObservationSource.read_batch() must return ObservationBatch or None")
+                read_count += 1
+                result = self.session.ingest(batch)
+                acknowledge = getattr(self.source, "acknowledge", None)
+                if callable(acknowledge):
+                    acknowledge(batch, result)
+                yield result
+        finally:
+            self._consuming = False
+
+
+__all__ = ["AcknowledgingObservationSource", "ObservationSource", "SessionRunner"]

timoshenko/assets.py

@@ -0,0 +1,57 @@
+"""Minimal digital-twin asset and relation records."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class Asset:
+    asset_id: str
+    asset_type: str
+    name: str = ""
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        asset_id, asset_type = str(self.asset_id).strip(), str(self.asset_type).strip()
+        if not asset_id or not asset_type:
+            raise ValueError("asset_id and asset_type must be non-empty")
+        if not isinstance(self.metadata, Mapping):
+            raise ValueError("asset metadata must be a mapping")
+        object.__setattr__(self, "asset_id", asset_id)
+        object.__setattr__(self, "asset_type", asset_type)
+        object.__setattr__(self, "name", str(self.name))
+        object.__setattr__(self, "metadata", dict(self.metadata))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"asset_id": self.asset_id, "asset_type": self.asset_type, "name": self.name, "metadata": dict(self.metadata)}
+
+
+@dataclass(frozen=True)
+class Relation:
+    source_asset_id: str
+    relation_type: str
+    target_asset_id: str
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        source, kind, target = (str(item).strip() for item in (self.source_asset_id, self.relation_type, self.target_asset_id))
+        if not source or not kind or not target:
+            raise ValueError("relation source, type, and target must be non-empty")
+        if source == target:
+            raise ValueError("self-relations are not supported")
+        if not isinstance(self.metadata, Mapping):
+            raise ValueError("relation metadata must be a mapping")
+        object.__setattr__(self, "source_asset_id", source)
+        object.__setattr__(self, "relation_type", kind)
+        object.__setattr__(self, "target_asset_id", target)
+        object.__setattr__(self, "metadata", dict(self.metadata))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source_asset_id": self.source_asset_id,
+            "relation_type": self.relation_type,
+            "target_asset_id": self.target_asset_id,
+            "metadata": dict(self.metadata),
+        }

timoshenko/beams.py

@@ -0,0 +1,75 @@
+"""Closed-form small-deflection beam responses for common load cases.
+
+Euler-Bernoulli bending deflection is always reported. If both shear modulus
+and cross-sectional area are supplied, a first-order shear-deflection term is
+also returned (constant ``kappa`` shear-correction approximation).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ._validation import finite as _finite, positive as _positive
+
+
+@dataclass(frozen=True)
+class BeamDeflection:
+    bending_m: float
+    shear_m: float
+
+    @property
+    def total_m(self) -> float:
+        return self.bending_m + self.shear_m
+
+
+def _response(bending: float, shear_force_factor: float, *, shear_modulus_pa: float | None,
+              area_m2: float | None, shear_correction: float) -> BeamDeflection:
+    if (shear_modulus_pa is None) != (area_m2 is None):
+        raise ValueError("provide both shear_modulus_pa and area_m2 to include shear deflection")
+    shear = 0.0
+    if shear_modulus_pa is not None and area_m2 is not None:
+        g = _positive("shear_modulus_pa", shear_modulus_pa)
+        a = _positive("area_m2", area_m2)
+        kappa = _positive("shear_correction", shear_correction)
+        shear = shear_force_factor / (kappa * g * a)
+    return BeamDeflection(float(bending), float(shear))
+
+
+def cantilever_tip_load(load_n: float, span_m: float, youngs_modulus_pa: float,
+                        second_moment_m4: float, *, shear_modulus_pa: float | None = None,
+                        area_m2: float | None = None, shear_correction: float = 5.0 / 6.0) -> BeamDeflection:
+    """Tip deflection of a cantilever with a point load at its free end."""
+    p, length = _finite("load_n", load_n), _positive("span_m", span_m)
+    e, inertia = _positive("youngs_modulus_pa", youngs_modulus_pa), _positive("second_moment_m4", second_moment_m4)
+    return _response(p * length**3 / (3 * e * inertia), p * length,
+                     shear_modulus_pa=shear_modulus_pa, area_m2=area_m2, shear_correction=shear_correction)
+
+
+def cantilever_uniform_load(load_n_per_m: float, span_m: float, youngs_modulus_pa: float,
+                            second_moment_m4: float, *, shear_modulus_pa: float | None = None,
+                            area_m2: float | None = None, shear_correction: float = 5.0 / 6.0) -> BeamDeflection:
+    """Free-end deflection of a cantilever under a full-span uniform load."""
+    w, length = _finite("load_n_per_m", load_n_per_m), _positive("span_m", span_m)
+    e, inertia = _positive("youngs_modulus_pa", youngs_modulus_pa), _positive("second_moment_m4", second_moment_m4)
+    return _response(w * length**4 / (8 * e * inertia), w * length**2 / 2,
+                     shear_modulus_pa=shear_modulus_pa, area_m2=area_m2, shear_correction=shear_correction)
+
+
+def simply_supported_midpoint_load(load_n: float, span_m: float, youngs_modulus_pa: float,
+                                   second_moment_m4: float, *, shear_modulus_pa: float | None = None,
+                                   area_m2: float | None = None, shear_correction: float = 5.0 / 6.0) -> BeamDeflection:
+    """Midspan deflection of a simply supported beam with a center point load."""
+    p, length = _finite("load_n", load_n), _positive("span_m", span_m)
+    e, inertia = _positive("youngs_modulus_pa", youngs_modulus_pa), _positive("second_moment_m4", second_moment_m4)
+    return _response(p * length**3 / (48 * e * inertia), p * length / 4,
+                     shear_modulus_pa=shear_modulus_pa, area_m2=area_m2, shear_correction=shear_correction)
+
+
+def simply_supported_uniform_load(load_n_per_m: float, span_m: float, youngs_modulus_pa: float,
+                                  second_moment_m4: float, *, shear_modulus_pa: float | None = None,
+                                  area_m2: float | None = None, shear_correction: float = 5.0 / 6.0) -> BeamDeflection:
+    """Midspan deflection of a simply supported beam under full-span UDL."""
+    w, length = _finite("load_n_per_m", load_n_per_m), _positive("span_m", span_m)
+    e, inertia = _positive("youngs_modulus_pa", youngs_modulus_pa), _positive("second_moment_m4", second_moment_m4)
+    return _response(5 * w * length**4 / (384 * e * inertia), w * length**2 / 8,
+                     shear_modulus_pa=shear_modulus_pa, area_m2=area_m2, shear_correction=shear_correction)

timoshenko/csv_source.py

@@ -0,0 +1,187 @@
+"""Bounded-memory CSV observation replay source."""
+
+from __future__ import annotations
+
+import csv
+from datetime import datetime
+import math
+from pathlib import Path
+from typing import TextIO
+
+from .observations import Observation, ObservationBatch
+
+
+class CSVSourceError(ValueError):
+    """Raised when a CSV file cannot be read as the configured observation schema."""
+
+
+def _parse_timestamp(value: str) -> float:
+    text = value.strip()
+    try:
+        result = float(text)
+    except ValueError:
+        iso_text = text[:-1] + "+00:00" if text.endswith(("Z", "z")) else text
+        try:
+            parsed = datetime.fromisoformat(iso_text)
+        except ValueError as error:
+            raise ValueError("timestamp must be Unix seconds or timezone-aware ISO-8601") from error
+        if parsed.tzinfo is None or parsed.utcoffset() is None:
+            raise ValueError("ISO-8601 timestamps must include a timezone")
+        result = parsed.timestamp()
+    if not math.isfinite(result):
+        raise ValueError("timestamp must be finite")
+    return result
+
+
+def _parse_quality(value: str) -> bool:
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "good", "valid"}:
+        return True
+    if normalized in {"0", "false", "no", "bad", "invalid"}:
+        return False
+    raise ValueError("quality must be one of true/false, 1/0, yes/no, good/bad, or valid/invalid")
+
+
+class CSVObservationSource:
+    """Read long-format sensor CSV incrementally as :class:`ObservationBatch` objects.
+
+    The source never loads the whole file. Column names are explicit, event time
+    is required, and every emitted batch has a stable source/row-range identity.
+    Numeric timestamps mean Unix seconds; ISO-8601 timestamps must include a
+    timezone. All values are preserved in the CSV's declared unit.
+    """
+
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        source_id: str | None = None,
+        batch_size: int = 256,
+        timestamp_column: str = "timestamp",
+        sensor_id_column: str = "sensor_id",
+        name_column: str | None = "name",
+        unit_column: str = "unit",
+        value_column: str = "value",
+        quality_column: str | None = "quality",
+        asset_id_column: str | None = "asset_id",
+    ):
+        size = int(batch_size)
+        if isinstance(batch_size, bool) or size != batch_size or not 1 <= size <= 4096:
+            raise ValueError("batch_size must be an integer between 1 and 4096")
+        columns = [timestamp_column, sensor_id_column, unit_column, value_column]
+        columns.extend(column for column in (name_column, quality_column, asset_id_column) if column is not None)
+        normalized = [str(column).strip() for column in columns]
+        if any(not column for column in normalized) or len(set(normalized)) != len(normalized):
+            raise ValueError("configured CSV column names must be non-empty and distinct")
+        self.path = Path(path)
+        if source_id is None:
+            source_value = f"csv:{self.path.name}"
+        else:
+            source_value = str(source_id).strip()
+        if not source_value:
+            raise ValueError("source_id must be non-empty")
+        self.source_id = source_value
+        self.batch_size = size
+        self.timestamp_column = str(timestamp_column).strip()
+        self.sensor_id_column = str(sensor_id_column).strip()
+        self.name_column = None if name_column is None else str(name_column).strip()
+        self.unit_column = str(unit_column).strip()
+        self.value_column = str(value_column).strip()
+        self.quality_column = None if quality_column is None else str(quality_column).strip()
+        self.asset_id_column = None if asset_id_column is None else str(asset_id_column).strip()
+        self._file: TextIO | None = None
+        self._reader: csv.DictReader | None = None
+        self._row_sequence = 0
+
+    def open(self) -> None:
+        if self._file is not None:
+            raise RuntimeError("CSV observation source is already open")
+        try:
+            file = self.path.open("r", newline="", encoding="utf-8-sig")
+        except OSError as error:
+            raise CSVSourceError(f"cannot open observation CSV {self.path}: {error}") from error
+        reader = csv.DictReader(file, strict=True)
+        headers = reader.fieldnames
+        if not headers or any(header is None or not header.strip() for header in headers):
+            file.close()
+            raise CSVSourceError("CSV must contain a header row with non-empty column names")
+        if len(set(headers)) != len(headers):
+            file.close()
+            raise CSVSourceError("CSV header contains duplicate column names")
+        required = {
+            self.timestamp_column,
+            self.sensor_id_column,
+            self.unit_column,
+            self.value_column,
+        }
+        required.update(column for column in (self.name_column, self.quality_column, self.asset_id_column) if column is not None)
+        missing = required - set(headers)
+        if missing:
+            file.close()
+            raise CSVSourceError(f"CSV is missing configured columns: {', '.join(sorted(missing))}")
+        self._file = file
+        self._reader = reader
+        self._row_sequence = 0
+
+    def read_batch(self) -> ObservationBatch | None:
+        if self._reader is None:
+            raise RuntimeError("open() must be called before read_batch()")
+        rows: list[Observation] = []
+        first_row_sequence = self._row_sequence + 1
+        while len(rows) < self.batch_size:
+            try:
+                row = next(self._reader)
+            except StopIteration:
+                break
+            except csv.Error as error:
+                raise CSVSourceError(f"malformed CSV near line {self._reader.line_num}: {error}") from error
+            line_number = self._reader.line_num
+            if None in row:
+                raise CSVSourceError(f"row near line {line_number} has more fields than the CSV header")
+            if all(value is None or not value.strip() for value in row.values()):
+                continue
+            try:
+                sensor_id = self._required(row, self.sensor_id_column)
+                unit = self._required(row, self.unit_column)
+                raw_name = sensor_id if self.name_column is None else self._required(row, self.name_column)
+                timestamp = _parse_timestamp(self._required(row, self.timestamp_column))
+                value = float(self._required(row, self.value_column))
+                quality = True if self.quality_column is None else _parse_quality(self._required(row, self.quality_column))
+                raw_asset_id = "" if self.asset_id_column is None else (row.get(self.asset_id_column) or "").strip()
+                observation = Observation(
+                    sensor_id=sensor_id,
+                    name=raw_name,
+                    unit=unit,
+                    value=value,
+                    timestamp=timestamp,
+                    quality=quality,
+                    asset_id=raw_asset_id or None,
+                    source_id=self.source_id,
+                    metadata={"csv_line": line_number},
+                )
+            except (TypeError, ValueError) as error:
+                raise CSVSourceError(f"invalid observation near CSV line {line_number}: {error}") from error
+            rows.append(observation)
+            self._row_sequence += 1
+        if not rows:
+            return None
+        return ObservationBatch(
+            rows,
+            source_id=self.source_id,
+            batch_id=f"{self.source_id}:rows:{first_row_sequence}-{self._row_sequence}",
+        )
+
+    @staticmethod
+    def _required(row: dict[str | None, str | None], column: str) -> str:
+        value = row.get(column)
+        if value is None or not value.strip():
+            raise ValueError(f"{column!r} must not be empty")
+        return value.strip()
+
+    def close(self) -> None:
+        file, self._file, self._reader = self._file, None, None
+        if file is not None:
+            file.close()
+
+
+__all__ = ["CSVObservationSource", "CSVSourceError"]