timoshenko-engine 2.0.1__py3-none-any.whl

timoshenko/uncertainty.py

@@ -0,0 +1,261 @@
+"""Uncertainty propagation for user-supplied scalar engineering equations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+from statistics import NormalDist
+from types import MappingProxyType
+from typing import Any, Callable, Mapping, Sequence
+
+import numpy as np
+
+
+class UncertaintyError(ValueError):
+    """Raised when uncertainty inputs or equation evaluations are invalid."""
+
+
+@dataclass(frozen=True)
+class UncertaintyResult:
+    """Scalar estimate and propagated uncertainty with method provenance."""
+
+    estimate: float
+    standard_uncertainty: float
+    confidence_level: float
+    interval_low: float
+    interval_high: float
+    method: str
+    input_names: tuple[str, ...]
+    sensitivity_coefficients: Mapping[str, float]
+    sample_count: int
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "input_names", tuple(self.input_names))
+        object.__setattr__(self, "sensitivity_coefficients", MappingProxyType(dict(self.sensitivity_coefficients)))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "estimate": self.estimate,
+            "standard_uncertainty": self.standard_uncertainty,
+            "confidence_level": self.confidence_level,
+            "interval": [self.interval_low, self.interval_high],
+            "method": self.method,
+            "input_names": list(self.input_names),
+            "sensitivity_coefficients": dict(self.sensitivity_coefficients),
+            "sample_count": self.sample_count,
+        }
+
+
+def propagate(
+    function: Callable[..., float],
+    inputs: Mapping[str, float],
+    *,
+    standard_uncertainties: Mapping[str, float] | None = None,
+    covariance: Sequence[Sequence[float]] | None = None,
+    method: str = "first_order",
+    confidence_level: float = 0.95,
+    relative_step: float = 1e-5,
+    samples: int = 10_000,
+    seed: int | None = 0,
+) -> UncertaintyResult:
+    """Propagate input standard uncertainties through a scalar callable.
+
+    ``inputs`` names are passed to ``function`` as keyword arguments. Supply
+    either independent ``standard_uncertainties`` by name or a full covariance
+    matrix ordered like ``inputs``. ``first_order`` uses centered finite
+    differences and the GUM linearized covariance law. ``monte_carlo`` draws
+    from the multivariate normal distribution described by the same input
+    estimates and covariance. The caller remains responsible for choosing
+    suitable input uncertainty models and units.
+    """
+    if not callable(function):
+        raise TypeError("function must be callable")
+    if not isinstance(inputs, Mapping) or not inputs:
+        raise UncertaintyError("inputs must be a non-empty mapping of keyword names to values")
+    if any(not isinstance(name, str) for name in inputs):
+        raise UncertaintyError("input names must be strings")
+    names = tuple(name.strip() for name in inputs)
+    if any(not name or name != original for name, original in zip(names, inputs)) or len(set(names)) != len(names):
+        raise UncertaintyError("input names must be non-empty and distinct")
+    if len(names) > 32:
+        raise UncertaintyError("at most 32 uncertain inputs are supported")
+    values = np.asarray([_finite_scalar(inputs[key], f"input {key!r}") for key in inputs], dtype=float)
+    if (standard_uncertainties is None) == (covariance is None):
+        raise UncertaintyError("supply exactly one of standard_uncertainties or covariance")
+    if standard_uncertainties is not None:
+        if not isinstance(standard_uncertainties, Mapping) or set(standard_uncertainties) != set(inputs):
+            raise UncertaintyError("standard_uncertainties must provide one value for every input name")
+        deviations = np.asarray(
+            [_finite_scalar(standard_uncertainties[key], f"standard uncertainty for {key!r}") for key in inputs],
+            dtype=float,
+        )
+        if np.any(deviations < 0.0):
+            raise UncertaintyError("standard uncertainties must be non-negative")
+        with np.errstate(over="ignore", invalid="ignore"):
+            covariance_matrix = np.diag(deviations * deviations)
+        if not np.isfinite(covariance_matrix).all():
+            raise UncertaintyError("standard uncertainties are too large to form finite variances")
+    else:
+        try:
+            covariance_matrix = np.asarray(covariance, dtype=float)
+        except (TypeError, ValueError) as error:
+            raise UncertaintyError("covariance must be a numeric square matrix") from error
+        if covariance_matrix.shape != (len(names), len(names)) or not np.isfinite(covariance_matrix).all():
+            raise UncertaintyError("covariance must be a finite square matrix ordered like inputs")
+        scale = max(float(np.max(np.abs(covariance_matrix))), np.finfo(float).tiny)
+        if not np.allclose(covariance_matrix, covariance_matrix.T, rtol=1e-10, atol=1e-12 * scale):
+            raise UncertaintyError("covariance matrix must be symmetric")
+        covariance_matrix = 0.5 * (covariance_matrix + covariance_matrix.T)
+        try:
+            eigenvalues, eigenvectors = np.linalg.eigh(covariance_matrix)
+        except np.linalg.LinAlgError as error:
+            raise UncertaintyError("could not validate covariance matrix") from error
+        if float(eigenvalues[0]) < -1e-10 * scale:
+            raise UncertaintyError("covariance matrix must be positive semidefinite")
+        if np.any(eigenvalues < 0.0):
+            covariance_matrix = (eigenvectors * np.maximum(eigenvalues, 0.0)) @ eigenvectors.T
+
+    confidence = _finite_scalar(confidence_level, "confidence_level")
+    if not 0.5 < confidence < 1.0:
+        raise UncertaintyError("confidence_level must be greater than 0.5 and less than 1")
+    method_value = str(method).strip().lower()
+    if method_value not in {"first_order", "monte_carlo"}:
+        raise UncertaintyError("method must be 'first_order' or 'monte_carlo'")
+    nominal = _evaluate(function, names, values, "nominal inputs")
+
+    if method_value == "first_order":
+        step_scale = _finite_scalar(relative_step, "relative_step")
+        if not 0.0 < step_scale < 0.1:
+            raise UncertaintyError("relative_step must be greater than 0 and less than 0.1")
+        deviations = np.sqrt(np.maximum(np.diag(covariance_matrix), 0.0))
+        sensitivities: dict[str, float] = {}
+        for index, name in enumerate(names):
+            scale = max(abs(float(values[index])), float(deviations[index]))
+            if scale == 0.0:
+                scale = 1.0
+            step = step_scale * scale
+            if step == 0.0 or not math.isfinite(step):
+                raise UncertaintyError(f"could not choose a finite difference step for {name!r}")
+            plus, minus = values.copy(), values.copy()
+            plus[index] += step
+            minus[index] -= step
+            y_plus = _try_evaluate(function, names, plus)
+            y_minus = _try_evaluate(function, names, minus)
+            if y_plus is not None and y_minus is not None:
+                derivative = (y_plus - y_minus) / (2.0 * step)
+            elif y_plus is not None:
+                derivative = (y_plus - nominal) / step
+            elif y_minus is not None:
+                derivative = (nominal - y_minus) / step
+            else:
+                raise UncertaintyError(f"cannot estimate sensitivity for {name!r} near the supplied input")
+            if not math.isfinite(derivative):
+                raise UncertaintyError(f"sensitivity for {name!r} is non-finite")
+            sensitivities[name] = float(derivative)
+        gradient = np.asarray([sensitivities[name] for name in names], dtype=float)
+        with np.errstate(over="ignore", invalid="ignore"):
+            variance = float(gradient @ covariance_matrix @ gradient)
+            variance_scale = float(np.abs(gradient) @ np.abs(covariance_matrix) @ np.abs(gradient))
+        if not math.isfinite(variance) or not math.isfinite(variance_scale):
+            raise UncertaintyError("propagated variance is non-finite")
+        if variance < -1e-12 * max(variance_scale, np.finfo(float).tiny):
+            raise UncertaintyError("propagated variance became negative")
+        standard = math.sqrt(max(variance, 0.0))
+        coverage = NormalDist().inv_cdf(0.5 + confidence / 2.0)
+        low, high = nominal - coverage * standard, nominal + coverage * standard
+        if not all(math.isfinite(value) for value in (standard, low, high)):
+            raise UncertaintyError("uncertainty interval is non-finite")
+        return UncertaintyResult(
+            estimate=nominal,
+            standard_uncertainty=standard,
+            confidence_level=confidence,
+            interval_low=low,
+            interval_high=high,
+            method=method_value,
+            input_names=names,
+            sensitivity_coefficients=sensitivities,
+            sample_count=0,
+        )
+
+    try:
+        sample_count = int(samples)
+    except (TypeError, ValueError, OverflowError) as error:
+        raise UncertaintyError("samples must be an integer between 100 and 100000") from error
+    if isinstance(samples, bool) or sample_count != samples or not 100 <= sample_count <= 100_000:
+        raise UncertaintyError("samples must be an integer between 100 and 100000")
+    if seed is not None and (isinstance(seed, bool) or not isinstance(seed, (int, np.integer))):
+        raise UncertaintyError("seed must be an integer or None")
+    try:
+        rng = np.random.default_rng(seed)
+        draws = rng.multivariate_normal(
+            values,
+            covariance_matrix,
+            size=sample_count,
+            check_valid="raise",
+            method="eigh",
+        )
+    except (ValueError, np.linalg.LinAlgError) as error:
+        raise UncertaintyError(f"could not sample the configured input distribution: {error}") from error
+    output = np.empty(sample_count, dtype=float)
+    for index, draw in enumerate(draws):
+        try:
+            output[index] = _evaluate(function, names, draw, f"Monte Carlo sample {index}")
+        except UncertaintyError as error:
+            raise UncertaintyError(
+                f"Monte Carlo evaluation failed at sample {index}; choose an input distribution whose samples stay in the equation domain"
+            ) from error
+    estimate = float(np.mean(output))
+    standard = float(np.std(output, ddof=1))
+    alpha = (1.0 - confidence) / 2.0
+    low, high = (float(value) for value in np.quantile(output, [alpha, 1.0 - alpha]))
+    if not all(math.isfinite(value) for value in (estimate, standard, low, high)):
+        raise UncertaintyError("Monte Carlo summary contains a non-finite value")
+    return UncertaintyResult(
+        estimate=estimate,
+        standard_uncertainty=standard,
+        confidence_level=confidence,
+        interval_low=low,
+        interval_high=high,
+        method=method_value,
+        input_names=names,
+        sensitivity_coefficients={},
+        sample_count=sample_count,
+    )
+
+
+def _finite_scalar(value: Any, label: str) -> float:
+    if isinstance(value, (bool, np.bool_)) or not np.isscalar(value):
+        raise UncertaintyError(f"{label} must be a finite real number")
+    try:
+        result = float(value)
+    except (TypeError, ValueError) as error:
+        raise UncertaintyError(f"{label} must be a finite real number") from error
+    if not math.isfinite(result):
+        raise UncertaintyError(f"{label} must be a finite real number")
+    return result
+
+
+def _evaluate(function: Callable[..., float], names: tuple[str, ...], values: Sequence[float], label: str) -> float:
+    try:
+        result = function(**dict(zip(names, values)))
+    except Exception as error:
+        raise UncertaintyError(f"equation evaluation failed for {label}: {error}") from error
+    if isinstance(result, (bool, np.bool_)) or not np.isscalar(result):
+        raise UncertaintyError(f"equation output for {label} must be a finite scalar number")
+    try:
+        output = float(result)
+    except (TypeError, ValueError) as error:
+        raise UncertaintyError(f"equation output for {label} must be a finite scalar number") from error
+    if not math.isfinite(output):
+        raise UncertaintyError(f"equation output for {label} must be a finite scalar number")
+    return output
+
+
+def _try_evaluate(function: Callable[..., float], names: tuple[str, ...], values: Sequence[float]) -> float | None:
+    try:
+        return _evaluate(function, names, values, "finite difference input")
+    except UncertaintyError:
+        return None
+
+
+__all__ = ["UncertaintyError", "UncertaintyResult", "propagate"]

timoshenko/update.py

@@ -0,0 +1,46 @@
+"""Transparent, deliberately constrained modal model update."""
+
+from __future__ import annotations
+
+import math
+import statistics
+
+from .modal import ModalResult, pair_modes
+from .oma import FDDResult
+from .structure import Structure
+
+
+def update(structure: Structure, modal: ModalResult | FDDResult) -> Structure:
+    """Scale all story stiffnesses uniformly to fit identified frequencies.
+
+    The scale is the median of ``(measured / analytical frequency) ** 2``
+    across modes paired by :func:`timoshenko.modal.pair_modes`. This follows
+    the uniform-stiffness relation ``f proportional to sqrt(k/m)``. It accepts
+    single-channel FFT or multi-channel FDD modal results. It cannot localize
+    damage or update stories independently. The scale is relative to the
+    stiffness of ``structure`` as passed in.
+    """
+    if not isinstance(structure, Structure):
+        raise TypeError("structure must be a timoshenko.Structure")
+    if not isinstance(modal, (ModalResult, FDDResult)):
+        raise TypeError("modal must be a result from tm.modal.identify() or tm.modal.identify_fdd()")
+    if modal.status != "ok" or not modal.modes:
+        raise ValueError(f"cannot update structure from modal result with status {modal.status!r}")
+
+    analytical = structure.natural_frequencies_hz
+    pairs = pair_modes(analytical, modal.frequencies_hz)
+    scale_by_mode = [
+        (modal.modes[observed].frequency_hz / analytical[reference]) ** 2
+        for reference, observed in pairs
+    ]
+    if not scale_by_mode or any(not math.isfinite(scale) or scale <= 0.0 for scale in scale_by_mode):
+        raise ValueError("modal/model frequency pairing produced an invalid stiffness scale")
+    scale = float(statistics.median(scale_by_mode))
+    spread_pct = 100.0 * statistics.median(abs(value - scale) for value in scale_by_mode) / scale
+    status = "updated" if len(pairs) == structure.story_count else "updated_partial_modes"
+    return structure.with_update(
+        stiffness_scale=scale,
+        observed_frequencies_hz=[modal.modes[observed].frequency_hz for _, observed in pairs],
+        mode_scale_spread_pct=spread_pct,
+        status=status,
+    )

timoshenko/vibration.py

@@ -0,0 +1,138 @@
+"""Single-degree-of-freedom and proportional vibration primitives."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+from ._validation import positive as _positive
+
+
+def natural_frequency_hz(mass_kg: float, stiffness_n_m: float) -> float:
+    """Undamped natural frequency ``sqrt(k/m)/(2*pi)`` for an SDOF system."""
+    m, k = _positive("mass_kg", mass_kg), _positive("stiffness_n_m", stiffness_n_m)
+    return math.sqrt(k / m) / (2.0 * math.pi)
+
+
+def damping_ratio(mass_kg: float, stiffness_n_m: float, damping_n_s_m: float) -> float:
+    """Viscous damping ratio ``c/(2*sqrt(k*m))``."""
+    m, k = _positive("mass_kg", mass_kg), _positive("stiffness_n_m", stiffness_n_m)
+    c = float(damping_n_s_m)
+    if not math.isfinite(c) or c < 0.0:
+        raise ValueError("damping_n_s_m must be finite and non-negative")
+    return c / (2.0 * math.sqrt(k * m))
+
+
+@dataclass(frozen=True)
+class HarmonicResponse:
+    displacement_amplitude_m: float
+    phase_lag_rad: float
+    frequency_ratio: float
+
+
+@dataclass(frozen=True)
+class RayleighDampingResult:
+    """Two-frequency fit for mass- and stiffness-proportional viscous damping."""
+
+    frequency_1_hz: float
+    damping_ratio_1: float
+    frequency_2_hz: float
+    damping_ratio_2: float
+    alpha_mass_s_inv: float
+    beta_stiffness_s: float
+
+    def modal_damping_ratio(self, frequency_hz: float) -> float:
+        """Evaluate the fitted Rayleigh damping ratio at a positive frequency."""
+        frequency = _positive("frequency_hz", frequency_hz)
+        omega = 2.0 * math.pi * frequency
+        ratio = 0.5 * (self.alpha_mass_s_inv / omega + self.beta_stiffness_s * omega)
+        if not math.isfinite(ratio):
+            raise ValueError("Rayleigh damping ratio is non-finite at this frequency")
+        return ratio
+
+    def to_dict(self) -> dict[str, float | str]:
+        return {
+            "frequency_1_hz": self.frequency_1_hz,
+            "damping_ratio_1": self.damping_ratio_1,
+            "frequency_2_hz": self.frequency_2_hz,
+            "damping_ratio_2": self.damping_ratio_2,
+            "alpha_mass_s_inv": self.alpha_mass_s_inv,
+            "beta_stiffness_s": self.beta_stiffness_s,
+            "alpha_unit": "s^-1",
+            "beta_unit": "s",
+        }
+
+
+def rayleigh_damping_coefficients(
+    frequency_1_hz: float,
+    damping_ratio_1: float,
+    frequency_2_hz: float,
+    damping_ratio_2: float,
+) -> RayleighDampingResult:
+    """Fit passive Rayleigh coefficients to two modal damping targets.
+
+    For ``C = alpha_M M + beta_K K``, modal damping is
+    ``zeta(omega) = alpha_M/(2 omega) + beta_K omega/2``. Frequencies are
+    supplied in Hz and converted internally to angular frequency. Negative
+    fitted coefficients are rejected because they do not define a passive
+    two-term Rayleigh damping model over positive frequencies.
+    """
+    f1, f2 = _positive("frequency_1_hz", frequency_1_hz), _positive("frequency_2_hz", frequency_2_hz)
+    z1, z2 = float(damping_ratio_1), float(damping_ratio_2)
+    if not math.isfinite(z1) or z1 < 0.0 or not math.isfinite(z2) or z2 < 0.0:
+        raise ValueError("target damping ratios must be finite and non-negative")
+    original = (f1, z1, f2, z2)
+    if f2 < f1:
+        f1, f2, z1, z2 = f2, f1, z2, z1
+    relative_gap = (f2 - f1) / f2
+    if relative_gap <= 1e-8:
+        raise ValueError("target frequencies must be distinct and sufficiently separated")
+    omega_1, omega_2 = 2.0 * math.pi * f1, 2.0 * math.pi * f2
+    if not math.isfinite(omega_1) or not math.isfinite(omega_2) or omega_1 <= 0.0 or omega_2 <= 0.0:
+        raise ValueError("target frequencies are outside the supported numerical range")
+    ratio = omega_1 / omega_2
+    denominator = 1.0 - ratio * ratio
+    alpha = 2.0 * omega_1 * (z1 - z2 * ratio) / denominator
+    beta = 2.0 * (z2 - z1 * ratio) / (omega_2 * denominator)
+    if not math.isfinite(alpha) or not math.isfinite(beta):
+        raise ValueError("Rayleigh coefficient fit produced a non-finite value")
+    alpha_tolerance = 1e-12 * max(omega_1 * z1, omega_2 * z2, math.ulp(0.0))
+    beta_tolerance = 1e-12 * max(z1 / omega_1, z2 / omega_2, math.ulp(0.0))
+    if alpha < -alpha_tolerance or beta < -beta_tolerance:
+        raise ValueError("these two targets require a negative coefficient and cannot be fit by passive Rayleigh damping")
+    alpha, beta = max(alpha, 0.0), max(beta, 0.0)
+    result = RayleighDampingResult(
+        frequency_1_hz=original[0],
+        damping_ratio_1=original[1],
+        frequency_2_hz=original[2],
+        damping_ratio_2=original[3],
+        alpha_mass_s_inv=alpha,
+        beta_stiffness_s=beta,
+    )
+    if not (
+        math.isclose(result.modal_damping_ratio(original[0]), original[1], rel_tol=1e-9, abs_tol=1e-12)
+        and math.isclose(result.modal_damping_ratio(original[2]), original[3], rel_tol=1e-9, abs_tol=1e-12)
+    ):
+        raise ValueError("Rayleigh coefficient fit could not reproduce both targets at floating-point precision")
+    return result
+
+
+def harmonic_response(force_amplitude_n: float, excitation_hz: float, mass_kg: float,
+                      stiffness_n_m: float, damping_n_s_m: float) -> HarmonicResponse:
+    """Steady-state displacement amplitude and phase for a harmonically forced SDOF."""
+    force = float(force_amplitude_n)
+    if not math.isfinite(force):
+        raise ValueError("force_amplitude_n must be finite")
+    excitation = float(excitation_hz)
+    if not math.isfinite(excitation) or excitation < 0.0:
+        raise ValueError("excitation_hz must be finite and non-negative")
+    m, k = _positive("mass_kg", mass_kg), _positive("stiffness_n_m", stiffness_n_m)
+    zeta = damping_ratio(m, k, damping_n_s_m)
+    omega_n = math.sqrt(k / m)
+    ratio = (2.0 * math.pi * excitation) / omega_n
+    denominator = math.hypot(1.0 - ratio**2, 2.0 * zeta * ratio)
+    if denominator == 0.0:
+        raise ValueError("undamped resonance has unbounded steady-state response")
+    amplitude = abs(force) / k / denominator
+    phase = math.atan2(2.0 * zeta * ratio, 1.0 - ratio**2)
+    return HarmonicResponse(amplitude, phase, ratio)

timoshenko_engine-2.0.1.dist-info/METADATA

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: timoshenko-engine
+Version: 2.0.1
+Summary: Composable structural engineering calculations and analysis primitives for Python applications.
+Author: Ayberk Korkmaz
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Ayberkrk/timoshenko
+Project-URL: Repository, https://github.com/Ayberkrk/timoshenko
+Project-URL: Issues, https://github.com/Ayberkrk/timoshenko/issues
+Project-URL: Documentation, https://github.com/Ayberkrk/timoshenko/tree/main/docs
+Keywords: civil engineering,structural engineering,structural health monitoring,modal analysis,digital twin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: mqtt
+Requires-Dist: paho-mqtt<3,>=2.1; extra == "mqtt"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Ayberkrk/timoshenko/main/assets/timoshenko-logo.png" alt="Timoshenko Engine logo" width="920">
+</p>
+
+<h1 align="center">Timoshenko Engine</h1>
+
+<p align="center">
+  Reusable structural engineering building blocks for Python applications.
+</p>
+
+<p align="center">
+  <img alt="Version 2.0.1" src="https://img.shields.io/badge/version-2.0.1-orange?style=for-the-badge">
+  <img alt="Alpha" src="https://img.shields.io/badge/stage-alpha-orange?style=for-the-badge">
+  <img alt="Python 3.10 to 3.13" src="https://img.shields.io/badge/python-3.10%20to%203.13-blue?style=for-the-badge">
+  <img alt="Apache 2.0 license" src="https://img.shields.io/badge/license-Apache--2.0-green?style=for-the-badge">
+  <a href="https://github.com/Ayberkrk/timoshenko/actions/workflows/tests.yml"><img alt="Tests" src="https://github.com/Ayberkrk/timoshenko/actions/workflows/tests.yml/badge.svg"></a>
+</p>
+
+Timoshenko packages common structural calculations, modal analysis, sensor
+workflows, and monitoring components so applications can reuse them instead
+of rebuilding the same foundations for every project. It is an embeddable
+Python library and engine core, not a hosted monitoring service or a general
+finite-element solver.
+
+> **Alpha:** the API may still change between releases. Timoshenko is not yet
+> published on PyPI; install it from GitHub or from a checkout as shown below.
+
+## Install
+
+From GitHub:
+
+```bash
+python -m pip install "timoshenko-engine @ git+https://github.com/Ayberkrk/timoshenko"
+```
+
+Or from the root of a checkout:
+
+```bash
+python -m pip install .
+```
+
+The distribution package is named `timoshenko-engine`. The Python import
+package is named `timoshenko`:
+
+```python
+import timoshenko as tm
+print(tm.__version__)
+```
+
+To install optional MQTT support, use:
+
+```bash
+python -m pip install '.[mqtt]'
+```
+
+A future published release can be installed with
+`python -m pip install timoshenko-engine`. That command is only usable after a
+release is available from the selected package index.
+
+## Quick start
+
+```python
+import timoshenko as tm
+
+structure = tm.Structure(
+    structure_id="building-01",
+    story_masses_kg=[120_000.0, 110_000.0],
+    story_stiffness_n_m=[85_000_000.0, 70_000_000.0],
+)
+
+sensors = tm.load_sensors(
+    "acceleration.csv",
+    sampling_hz=100.0,
+    column="acceleration_m_s2",
+    unit="m/s^2",
+)
+
+modal = tm.modal.identify(sensors)
+updated = tm.update(structure, modal)
+health = tm.health.assess(structure=updated, observations=sensors)
+
+print(health.to_dict())
+```
+
+For a one-shot pipeline, `tm.monitor(structure, sensors)` performs the same
+analysis sequence and returns a serializable result. The model update applies
+one global stiffness multiplier and keeps the analytical reference frequencies
+separate from measured frequencies.
+
+## What it provides
+
+| Area | Reusable components |
+|---|---|
+| Structural models | Lumped-mass shear-building models and analytical natural frequencies |
+| Modal analysis | Single-channel peak picking, damping estimates when resolvable, and multi-channel FDD with complex mode shapes |
+| Model comparison | Log-frequency mode pairing, global stiffness updating, and evidence-oriented health assessment |
+| Monitoring | Caller-fed bounded sessions, batch validation, source adapters, and optional plugins |
+| Data workflow | Sensor CSV loading, project manifests, local SQLite history, and CSV replay |
+| Reporting | Standalone HTML reports with an embedded SVG frequency comparison |
+| Engineering calculations | Beam cases, section properties, mechanics, vibration, stability, stress, pressure, torsion, and uncertainty helpers |
+
+Timoshenko can be used module by module or embedded in a larger product such as
+Cauren. Sensor collection, application-specific risk rules, and engineering
+interpretation remain with the integrating application.
+
+## Multi-channel modal screening
+
+FDD requires synchronized channels with a common sample rate and unit:
+
+```python
+signals = tm.load_multichannel_csv(
+    "aligned_accelerometers.csv",
+    columns=["deck_left", "deck_center", "deck_right"],
+    sampling_hz=100.0,
+    units=["m/s^2"] * 3,
+)
+fdd = tm.identify_fdd(signals, nperseg=1024, max_modes=5)
+print(fdd.to_dict())
+```
+
+This first FDD implementation returns candidate frequencies and complex mode
+shapes. It does not estimate damping or issue a damage or safety conclusion.
+
+## Bounded monitoring session
+
+A caller supplies timestamped observation batches. The session aligns samples,
+waits for a fresh contiguous analysis window after gaps, and emits reports after
+each configured hop:
+
+```python
+session = tm.MonitoringSession(
+    structure,
+    sensor_ids=["deck-left", "deck-right"],
+    units=["m/s^2", "m/s^2"],
+    sampling_hz=100.0,
+    window_samples=2048,
+    hop_samples=512,
+    analysis_options={"nperseg": 512, "max_modes": 4},
+)
+result = session.ingest(batch)
+for report in result.reports:
+    tm.report.save_html(report, "reports/latest.html")
+```
+
+A gateway remains responsible for collecting data and handling transport
+reconnection. Timoshenko does not run a background collector or select an alarm
+policy.
+
+## Further examples and documentation
+
+- [Documentation home](docs/index.md)
+- [Architecture](docs/architecture.md)
+- [Data contract](docs/data-contract.md)
+- [Historical CSV replay](docs/csv-source.md)
+- [Plugin contract](docs/plugin-contract.md)
+- [Rayleigh damping](docs/rayleigh-damping.md)
+- [Section properties](docs/section-properties.md)
+- [Polygon section properties](docs/polygon-sections.md)
+- [Equation uncertainty](docs/uncertainty.md)
+- [Numerical methods and limits](docs/numerical-methods.md)
+- [Monitoring sessions](docs/live-sessions.md)
+- [Source adapters](docs/adapters.md)
+- [Project manifests](docs/project-manifest.md)
+- [Local storage](docs/storage.md)
+- [Reports](docs/reporting.md)
+- [Optional MQTT adapter](docs/mqtt-adapter.md)
+- [SensorThings adapter](docs/sensorthings-adapter.md)
+- [Engineering calculations](examples/engineering_primitives.py)
+- [Runnable examples](examples/)
+- [Publishing and citation](docs/publishing.md)
+
+## Limits and engineering posture
+
+- Timoshenko is alpha software and is not a structural safety certification tool.
+- Its shear-building model is a small lumped-mass reference model, not a full FEM solver.
+- Modal identification is a screening estimate. A single sensor may miss a mode near a modal node.
+- Damping is reported only when the averaged spectrum resolves the half-power bandwidth; otherwise it is `None`.
+- FDD requires synchronized channels and does not estimate damping.
+- The model update applies a single stiffness scale. It cannot locate or size local damage.
+- A frequency shift is evidence for human review, not a damage verdict. Temperature, sensor placement, boundary conditions, and other effects can shift measurements.
+- A monitoring session consumes data supplied by the caller. It does not implement a broker subscription, reconnect loop, scheduler, hosted dashboard, or alarm policy.
+- Closed-form mechanics and section functions rely on their documented ideal assumptions. They are not code-compliance checks.
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+python -m pytest
+```
+
+To build the documentation locally, install the optional documentation tools
+and run MkDocs:
+
+```bash
+python -m pip install -e ".[docs]"
+python -m mkdocs serve
+```
+
+The test suite checks analytical cases, input validation, adapters, storage,
+monitoring sessions, and reports. Package distributions should be built and
+installed in a clean environment before a release is uploaded.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).