timoshenko-engine 2.0.1__py3-none-any.whl

timoshenko/project.py

@@ -0,0 +1,251 @@
+"""Explicit, reproducible JSON project manifests and one-shot execution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+import math
+from pathlib import Path
+from typing import Any
+
+from .health import HealthAssessment, assess
+from .modal import ModalResult, identify
+from .multichannel import MultiChannelData, load_multichannel_csv
+from .oma import FDDResult, identify_fdd
+from .sensors import SensorData, load_sensors
+from .structure import Structure
+from .update import update
+
+
+@dataclass(frozen=True)
+class ProjectManifest:
+    """Validated manifest fields with file paths resolved from its directory."""
+
+    manifest_path: Path
+    schema_version: str
+    project_id: str
+    project_name: str
+    structure: Structure
+    observations_path: Path
+    sampling_hz: float
+    columns: tuple[str, ...]
+    channel_ids: tuple[str, ...]
+    units: tuple[str, ...]
+    method: str
+    options: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class LoadedProject:
+    manifest: ProjectManifest
+    observations: SensorData | MultiChannelData
+    source_sha256: str
+    manifest_sha256: str
+
+
+@dataclass(frozen=True)
+class ProjectRunResult:
+    project_id: str
+    project_name: str
+    manifest_path: str
+    source_path: str
+    source_sha256: str
+    manifest_sha256: str
+    method: str
+    analysis_options: dict[str, Any]
+    structure: Structure
+    modal: ModalResult | FDDResult
+    health: HealthAssessment
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "project_id": self.project_id,
+            "project_name": self.project_name,
+            "manifest_path": self.manifest_path,
+            "source_path": self.source_path,
+            "source_sha256": self.source_sha256,
+            "manifest_sha256": self.manifest_sha256,
+            "method": self.method,
+            "analysis_options": dict(self.analysis_options),
+            "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_status": self.structure.update_status,
+            },
+            "modal": self.modal.to_dict(),
+            "health": self.health.to_dict(),
+        }
+
+
+_SINGLE_OPTIONS = {"max_modes", "min_frequency_hz", "max_frequency_hz", "min_peak_ratio"}
+_FDD_OPTIONS = _SINGLE_OPTIONS | {"nperseg", "overlap", "max_singular_values", "min_singular_value_ratio"}
+
+
+def read_manifest(path: str | Path) -> ProjectManifest:
+    """Read and validate a version-1 JSON manifest; relative files resolve beside it."""
+    manifest_path = Path(path).expanduser().resolve()
+    if manifest_path.suffix.lower() != ".json":
+        raise ValueError("project manifests must use the .json extension in version 0.6")
+    payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("project manifest root must be a JSON object")
+    schema_version = str(payload.get("schema_version", ""))
+    if schema_version not in {"1", "1.0"}:
+        raise ValueError("unsupported schema_version; expected '1' or '1.0'")
+    project = payload.get("project")
+    if not isinstance(project, dict) or not str(project.get("id", "")).strip():
+        raise ValueError("project.id must be a non-empty string")
+    structure_payload = payload.get("structure")
+    if not isinstance(structure_payload, dict) or structure_payload.get("type") != "shear_building":
+        raise ValueError("version 0.6 supports structure.type='shear_building'")
+    structure = Structure(
+        structure_id=str(structure_payload.get("id") or project["id"]),
+        name=str(structure_payload.get("name") or project.get("name") or ""),
+        story_masses_kg=structure_payload.get("story_masses_kg", ()),
+        story_stiffness_n_m=structure_payload.get("story_stiffness_n_m", ()),
+        reference_frequencies_hz=structure_payload.get("reference_frequencies_hz", ()),
+    )
+    observation_payload = payload.get("observations")
+    if not isinstance(observation_payload, dict):
+        raise ValueError("observations must be a JSON object")
+    file_value = str(observation_payload.get("file", "")).strip()
+    if not file_value:
+        raise ValueError("observations.file must be a non-empty path")
+    source_path = (manifest_path.parent / file_value).resolve()
+    if source_path.suffix.lower() != ".csv":
+        raise ValueError("version 0.6 project manifests support CSV observations")
+    try:
+        sampling_hz = float(observation_payload["sampling_hz"])
+    except (KeyError, TypeError, ValueError):
+        raise ValueError("observations.sampling_hz must be a finite positive number") from None
+    if not math.isfinite(sampling_hz) or sampling_hz <= 0.0:
+        raise ValueError("observations.sampling_hz must be a finite positive number")
+    channels_payload = observation_payload.get("channels")
+    if not isinstance(channels_payload, list) or not channels_payload:
+        raise ValueError("observations.channels must be a non-empty list")
+    columns: list[str] = []
+    channel_ids: list[str] = []
+    units: list[str] = []
+    for idx, channel in enumerate(channels_payload, start=1):
+        if not isinstance(channel, dict):
+            raise ValueError(f"observations.channels[{idx - 1}] must be an object")
+        column = str(channel.get("column", "")).strip()
+        channel_id = str(channel.get("id") or column).strip()
+        unit = str(channel.get("unit", "unknown")).strip()
+        if not column or not channel_id or not unit:
+            raise ValueError(f"observations.channels[{idx - 1}] needs non-empty column, id, and unit")
+        columns.append(column)
+        channel_ids.append(channel_id)
+        units.append(unit)
+    if len(set(columns)) != len(columns) or len(set(channel_ids)) != len(channel_ids):
+        raise ValueError("channel columns and ids must each be unique")
+
+    analysis = payload.get("analysis", {})
+    if not isinstance(analysis, dict):
+        raise ValueError("analysis must be a JSON object")
+    default_method = "peak_picking" if len(columns) == 1 else "fdd"
+    method = str(analysis.get("method", default_method)).strip().lower()
+    allowed_options = _SINGLE_OPTIONS if method == "peak_picking" else _FDD_OPTIONS
+    if method not in {"peak_picking", "fdd"}:
+        raise ValueError("analysis.method must be 'peak_picking' or 'fdd'")
+    options = analysis.get("options", {})
+    if not isinstance(options, dict):
+        raise ValueError("analysis.options must be a JSON object")
+    unknown = sorted(set(options) - allowed_options)
+    if unknown:
+        raise ValueError(f"unsupported analysis options for {method}: {unknown}")
+    if method == "peak_picking" and len(columns) != 1:
+        raise ValueError("peak_picking requires exactly one channel; use fdd for multiple channels")
+    if method == "fdd" and len(columns) < 2:
+        raise ValueError("fdd requires at least two channels")
+
+    return ProjectManifest(
+        manifest_path=manifest_path,
+        schema_version=schema_version,
+        project_id=str(project["id"]).strip(),
+        project_name=str(project.get("name", "")).strip(),
+        structure=structure,
+        observations_path=source_path,
+        sampling_hz=sampling_hz,
+        columns=tuple(columns),
+        channel_ids=tuple(channel_ids),
+        units=tuple(units),
+        method=method,
+        options=dict(options),
+    )
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for block in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def load_project(path: str | Path) -> LoadedProject:
+    """Validate a manifest, load its CSV channels, and capture input provenance."""
+    manifest = read_manifest(path)
+    if not manifest.observations_path.is_file():
+        raise FileNotFoundError(f"observation CSV not found: {manifest.observations_path}")
+    if len(manifest.columns) == 1:
+        observations: SensorData | MultiChannelData = load_sensors(
+            manifest.observations_path,
+            sampling_hz=manifest.sampling_hz,
+            column=manifest.columns[0],
+            unit=manifest.units[0],
+            channel=manifest.channel_ids[0],
+        )
+    else:
+        observations = load_multichannel_csv(
+            manifest.observations_path,
+            columns=manifest.columns,
+            sampling_hz=manifest.sampling_hz,
+            units=manifest.units,
+            channel_ids=manifest.channel_ids,
+        )
+    return LoadedProject(
+        manifest=manifest,
+        observations=observations,
+        source_sha256=_sha256(manifest.observations_path),
+        manifest_sha256=_sha256(manifest.manifest_path),
+    )
+
+
+def run_project(project: LoadedProject | str | Path) -> ProjectRunResult:
+    """Execute one deterministic one-shot analysis described by a manifest."""
+    loaded = load_project(project) if isinstance(project, (str, Path)) else project
+    if not isinstance(loaded, LoadedProject):
+        raise TypeError("project must be a manifest path or LoadedProject from tm.load_project()")
+    manifest = loaded.manifest
+    if manifest.method == "peak_picking":
+        if not isinstance(loaded.observations, SensorData):
+            raise TypeError("peak_picking manifest must load one SensorData channel")
+        modal = identify(loaded.observations, **manifest.options)
+    else:
+        if not isinstance(loaded.observations, MultiChannelData):
+            raise TypeError("fdd manifest must load multiple channels")
+        modal = identify_fdd(loaded.observations, **manifest.options)
+
+    structure = manifest.structure
+    if modal.modes:
+        structure = update(structure, modal)
+    health = assess(structure=structure, observations=loaded.observations, modal_result=modal)
+    return ProjectRunResult(
+        project_id=manifest.project_id,
+        project_name=manifest.project_name,
+        manifest_path=str(manifest.manifest_path),
+        source_path=str(manifest.observations_path),
+        source_sha256=loaded.source_sha256,
+        manifest_sha256=loaded.manifest_sha256,
+        method=manifest.method,
+        analysis_options=dict(manifest.options),
+        structure=structure,
+        modal=modal,
+        health=health,
+    )

timoshenko/report.py

@@ -0,0 +1,154 @@
+"""Dependency-free human-readable reports for Timoshenko analysis results."""
+
+from __future__ import annotations
+
+from html import escape
+import math
+from pathlib import Path
+from typing import Any
+
+
+def _result_parts(result: Any) -> tuple[Any, Any, Any, str, str]:
+    """Extract the stable structure/modal/health view shared by result types."""
+    if not all(hasattr(result, name) for name in ("structure", "modal", "health")):
+        raise TypeError("result must be a Timoshenko monitoring, session, or project result")
+    structure, modal, health = result.structure, result.modal, result.health
+    if not hasattr(structure, "structure_id") or not hasattr(modal, "modes") or not hasattr(health, "mode_changes"):
+        raise TypeError("result does not expose the Timoshenko analysis result contract")
+    title = str(getattr(result, "project_name", "") or structure.name or structure.structure_id)
+    method = str(getattr(result, "method", "") or modal.method)
+    return structure, modal, health, title, method
+
+
+def _number(value: float | None, digits: int = 3) -> str:
+    if value is None:
+        return "—"
+    number = float(value)
+    if not math.isfinite(number):
+        return "—"
+    return f"{number:.{digits}f}"
+
+
+def _chart_svg(modal: Any, health: Any) -> str:
+    modes = list(modal.modes)
+    changes = {int(item.observed_mode_number): item for item in health.mode_changes}
+    width, height, margin = 780, max(230, 84 + 44 * len(modes)), 56
+    usable_width = width - 2 * margin
+    max_frequency = max(
+        [float(item.frequency_hz) for item in modes]
+        + [float(item.reference_frequency_hz) for item in changes.values()]
+        + [1.0]
+    )
+    scale = usable_width / max_frequency
+    pieces = [
+        f'<svg class="frequency-chart" viewBox="0 0 {width} {height}" role="img" aria-labelledby="chart-title chart-desc">',
+        '<title id="chart-title">Reference and observed modal frequencies</title>',
+        '<desc id="chart-desc">Horizontal lines compare model reference frequencies with the frequencies identified from observations.</desc>',
+        f'<line x1="{margin}" y1="26" x2="{width-margin}" y2="26" stroke="#94a3b8" stroke-width="1"/>',
+        f'<text x="{margin}" y="18" class="axis-label">0 Hz</text>',
+        f'<text x="{width-margin}" y="18" text-anchor="end" class="axis-label">{_number(max_frequency, 1)} Hz</text>',
+    ]
+    for index, mode in enumerate(modes):
+        y = 62 + index * 44
+        change = changes.get(index + 1)
+        label = f"Mode {change.mode_number}" if change is not None else "Unpaired"
+        pieces.append(f'<text x="4" y="{y+4}" class="mode-label">{label}</text>')
+        if change is not None:
+            reference_x = margin + float(change.reference_frequency_hz) * scale
+            pieces.append(f'<line x1="{margin}" y1="{y-5}" x2="{reference_x:.2f}" y2="{y-5}" stroke="#94a3b8" stroke-width="5" stroke-linecap="round"/>')
+            pieces.append(f'<circle cx="{reference_x:.2f}" cy="{y-5}" r="5" fill="#475569"/>')
+        observed_x = margin + float(mode.frequency_hz) * scale
+        pieces.append(f'<line x1="{margin}" y1="{y+7}" x2="{observed_x:.2f}" y2="{y+7}" stroke="#2563eb" stroke-width="5" stroke-linecap="round"/>')
+        pieces.append(f'<circle cx="{observed_x:.2f}" cy="{y+7}" r="5" fill="#1d4ed8"/>')
+        pieces.append(f'<text x="{width-margin+8}" y="{y-2}" class="value-label">{_number(mode.frequency_hz)} Hz</text>')
+    pieces.extend([
+        f'<circle cx="{margin+8}" cy="{height-19}" r="5" fill="#475569"/><text x="{margin+19}" y="{height-15}" class="legend">Model reference</text>',
+        f'<circle cx="{margin+170}" cy="{height-19}" r="5" fill="#1d4ed8"/><text x="{margin+181}" y="{height-15}" class="legend">Observed</text>',
+        '</svg>',
+    ])
+    return "".join(pieces)
+
+
+def to_html(result: Any, *, title: str | None = None) -> str:
+    """Render a self-contained accessible HTML report with a small SVG chart.
+
+    Supported inputs are ``MonitoringResult``, ``SessionReport``, and
+    ``ProjectRunResult``. Project paths/hashes and session timestamps are
+    included when the input provides them.
+    """
+    structure, modal, health, default_title, method = _result_parts(result)
+    display_title = escape(str(title or default_title))
+    modes = list(modal.modes)
+    changes = {int(item.observed_mode_number): item for item in health.mode_changes}
+    rows: list[str] = []
+    for index, mode in enumerate(modes, start=1):
+        change = changes.get(index)
+        reference = None if change is None else float(change.reference_frequency_hz)
+        shift = None if change is None else float(change.change_pct)
+        damping = getattr(mode, "damping_ratio", None)
+        rows.append(
+            "<tr>"
+            f"<th scope=\"row\">{change.mode_number if change is not None else 'unpaired'}</th>"
+            f"<td>{_number(reference)}</td>"
+            f"<td>{_number(float(mode.frequency_hz))}</td>"
+            f"<td>{_number(shift, 2)}{'%' if shift is not None else ''}</td>"
+            f"<td>{_number(damping, 4)}</td>"
+            "</tr>"
+        )
+    if not rows:
+        rows.append('<tr><td colspan="5">No usable modal frequencies were identified.</td></tr>')
+
+    metadata: list[str] = [
+        f"<dt>Structure</dt><dd>{escape(str(structure.structure_id))}</dd>",
+        f"<dt>Method</dt><dd>{escape(method)}</dd>",
+        f"<dt>Analysis status</dt><dd>{escape(str(modal.status))}</dd>",
+        f"<dt>Health evidence</dt><dd>{escape(str(health.status))}</dd>",
+    ]
+    if hasattr(result, "event_time_s"):
+        metadata.append(f"<dt>Window end (Unix time)</dt><dd>{_number(result.event_time_s, 3)}</dd>")
+    if hasattr(result, "source_sha256"):
+        metadata.append(f"<dt>Input SHA-256</dt><dd><code>{escape(str(result.source_sha256))}</code></dd>")
+        metadata.append(f"<dt>Manifest SHA-256</dt><dd><code>{escape(str(result.manifest_sha256))}</code></dd>")
+    limitations = "".join(f"<li>{escape(str(item))}</li>" for item in health.limitations)
+    notes = "".join(f"<li>{escape(str(item))}</li>" for item in getattr(modal, "notes", ()))
+    summary = escape(str(health.evidence_summary))
+    threshold = getattr(health, "review_threshold_pct", None)
+    if health.review_recommended:
+        review = f"Review recommended (frequency drop of at least {_number(threshold, 2)}%)"
+    elif threshold is None:
+        review = "No review threshold supplied; no review flag evaluated"
+    else:
+        review = f"No paired mode dropped by {_number(threshold, 2)}% or more"
+    chart = _chart_svg(modal, health)
+    return f"""<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>{display_title} — Timoshenko report</title>
+<style>
+:root{{color-scheme:light;--ink:#172033;--muted:#536178;--line:#dbe2ea;--blue:#1d4ed8;--paper:#fff;--wash:#f4f7fb}}
+*{{box-sizing:border-box}}body{{margin:0;background:var(--wash);color:var(--ink);font:16px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}}
+main{{max-width:980px;margin:36px auto;padding:36px;background:var(--paper);border:1px solid var(--line);border-radius:14px}}
+h1{{margin:0 0 8px;font-size:2rem}}h2{{margin:30px 0 10px;font-size:1.2rem}}.subtle,.axis-label,.legend{{color:var(--muted)}}
+dl{{display:grid;grid-template-columns:minmax(150px,220px) 1fr;gap:8px 16px;margin:20px 0}}dt{{font-weight:650}}dd{{margin:0;overflow-wrap:anywhere}}
+.summary{{padding:14px 16px;border-left:4px solid var(--blue);background:#eff6ff}}table{{width:100%;border-collapse:collapse}}th,td{{text-align:left;padding:10px 12px;border-bottom:1px solid var(--line);font-variant-numeric:tabular-nums}}thead{{background:var(--wash)}}
+.frequency-chart{{width:100%;height:auto;overflow:visible}}.mode-label,.value-label{{font:12px system-ui,sans-serif;fill:var(--ink)}}.axis-label,.legend{{font:11px system-ui,sans-serif;fill:var(--muted)}}code{{font-size:.85em;overflow-wrap:anywhere}}
+@media(max-width:640px){{main{{margin:0;padding:20px;border-radius:0}}dl{{grid-template-columns:1fr;gap:2px}}dd{{margin-bottom:10px}}}}
+</style></head><body><main>
+<p class="subtle">Timoshenko Engine · analysis report</p><h1>{display_title}</h1>
+<p class="summary">{summary}<br><strong>{escape(review)}</strong></p>
+<dl>{''.join(metadata)}</dl>
+<h2>Modal frequency comparison</h2>{chart}
+<table><thead><tr><th>Mode</th><th>Reference (Hz)</th><th>Observed (Hz)</th><th>Difference</th><th>Damping ratio</th></tr></thead><tbody>{''.join(rows)}</tbody></table>
+<h2>Method notes</h2><ul>{notes or '<li>No additional method notes.</li>'}</ul>
+<h2>Interpretation limits</h2><ul>{limitations or '<li>No limitation notes were supplied.</li>'}</ul>
+</main></body></html>"""
+
+
+def save_html(result: Any, path: str | Path, *, title: str | None = None) -> Path:
+    """Write a UTF-8 self-contained HTML report and return its resolved path."""
+    destination = Path(path).expanduser().resolve()
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(to_html(result, title=title), encoding="utf-8")
+    return destination
+
+
+__all__ = ["save_html", "to_html"]

timoshenko/sections.py

@@ -0,0 +1,119 @@
+"""Cross-section properties for common, prismatic sections (SI units)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+from ._validation import positive as _positive
+# Re-exported so the general polygon helper is also reachable as tm.sections.polygon_section.
+from .polygon import PolygonSectionProperties, polygon_section  # noqa: F401
+
+
+@dataclass(frozen=True)
+class SectionProperties:
+    area_m2: float
+    second_moment_y_m4: float
+    second_moment_z_m4: float
+    section_modulus_y_m3: float
+    section_modulus_z_m3: float
+
+
+def rectangle(width_m: float, height_m: float) -> SectionProperties:
+    """Return centroidal properties; y is the width axis, z the height axis."""
+    b, h = _positive("width_m", width_m), _positive("height_m", height_m)
+    area = b * h
+    iy, iz = b * h**3 / 12.0, h * b**3 / 12.0
+    return SectionProperties(area, iy, iz, iy / (h / 2.0), iz / (b / 2.0))
+
+
+def solid_circle(diameter_m: float) -> SectionProperties:
+    """Return centroidal properties for a solid circular section."""
+    d = _positive("diameter_m", diameter_m)
+    area = math.pi * d**2 / 4.0
+    inertia = math.pi * d**4 / 64.0
+    modulus = inertia / (d / 2.0)
+    return SectionProperties(area, inertia, inertia, modulus, modulus)
+
+
+def circular_tube(outer_diameter_m: float, inner_diameter_m: float) -> SectionProperties:
+    """Return centroidal properties for a concentric circular hollow section."""
+    outer = _positive("outer_diameter_m", outer_diameter_m)
+    inner = float(inner_diameter_m)
+    if not math.isfinite(inner) or inner < 0.0 or inner >= outer:
+        raise ValueError("inner_diameter_m must be finite, non-negative, and smaller than outer diameter")
+    area = math.pi * (outer**2 - inner**2) / 4.0
+    inertia = math.pi * (outer**4 - inner**4) / 64.0
+    modulus = inertia / (outer / 2.0)
+    return SectionProperties(area, inertia, inertia, modulus, modulus)
+
+
+def i_section(
+    overall_width_m: float,
+    overall_height_m: float,
+    web_thickness_m: float,
+    flange_thickness_m: float,
+) -> SectionProperties:
+    """Return centroidal properties of an ideal symmetric sharp-corner I-section.
+
+    The web is centered and joins two identical rectangular flanges. Fillets,
+    flange taper, and manufacturing tolerances are not included.
+    """
+    width = _positive("overall_width_m", overall_width_m)
+    height = _positive("overall_height_m", overall_height_m)
+    web = _positive("web_thickness_m", web_thickness_m)
+    flange = _positive("flange_thickness_m", flange_thickness_m)
+    if web >= width:
+        raise ValueError("web_thickness_m must be smaller than overall_width_m")
+    if 2.0 * flange >= height:
+        raise ValueError("twice flange_thickness_m must be smaller than overall_height_m")
+    web_height = height - 2.0 * flange
+    flange_offset = (height - flange) / 2.0
+    area = 2.0 * width * flange + web * web_height
+    inertia_y = (
+        2.0 * (width * flange**3 / 12.0 + width * flange * flange_offset**2)
+        + web * web_height**3 / 12.0
+    )
+    inertia_z = 2.0 * flange * width**3 / 12.0 + web_height * web**3 / 12.0
+    return _checked_properties(area, inertia_y, inertia_z, height / 2.0, width / 2.0)
+
+
+def rectangular_tube(
+    outer_width_m: float,
+    outer_height_m: float,
+    wall_thickness_m: float,
+) -> SectionProperties:
+    """Return centroidal properties of an ideal uniform-wall rectangular tube.
+
+    The shape has sharp corners and constant wall thickness. Corner radii,
+    weld geometry, and manufacturing tolerances are not included.
+    """
+    width = _positive("outer_width_m", outer_width_m)
+    height = _positive("outer_height_m", outer_height_m)
+    thickness = _positive("wall_thickness_m", wall_thickness_m)
+    if 2.0 * thickness >= min(width, height):
+        raise ValueError("twice wall_thickness_m must be smaller than both outer dimensions")
+    inner_height = height - 2.0 * thickness
+    inner_width = width - 2.0 * thickness
+    horizontal_plate_offset = (height - thickness) / 2.0
+    vertical_plate_offset = (width - thickness) / 2.0
+    area = 2.0 * width * thickness + 2.0 * thickness * inner_height
+    inertia_y = (
+        2.0 * (width * thickness**3 / 12.0 + width * thickness * horizontal_plate_offset**2)
+        + 2.0 * thickness * inner_height**3 / 12.0
+    )
+    inertia_z = (
+        2.0 * thickness * width**3 / 12.0
+        + 2.0 * (inner_height * thickness**3 / 12.0 + inner_height * thickness * vertical_plate_offset**2)
+    )
+    return _checked_properties(area, inertia_y, inertia_z, height / 2.0, width / 2.0)
+
+
+def _checked_properties(area: float, inertia_y: float, inertia_z: float, half_height: float, half_width: float) -> SectionProperties:
+    values = (area, inertia_y, inertia_z, half_height, half_width)
+    if any(not math.isfinite(value) or value <= 0.0 for value in values):
+        raise ValueError("section dimensions produced non-finite or non-positive geometric properties")
+    modulus_y, modulus_z = inertia_y / half_height, inertia_z / half_width
+    if not math.isfinite(modulus_y) or not math.isfinite(modulus_z):
+        raise ValueError("section dimensions produced non-finite section moduli")
+    return SectionProperties(area, inertia_y, inertia_z, modulus_y, modulus_z)

timoshenko/sensors.py

@@ -0,0 +1,142 @@
+"""Sensor series loading and validation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import csv
+import json
+import math
+from pathlib import Path
+from typing import Any, Sequence
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class SensorData:
+    """A single regularly sampled sensor channel."""
+
+    samples: tuple[float, ...] | Sequence[float]
+    sampling_hz: float
+    unit: str = "m/s^2"
+    channel: str = "sensor"
+    timestamps: tuple[float, ...] = ()
+
+    def __post_init__(self) -> None:
+        samples = tuple(float(value) for value in self.samples)
+        hz = float(self.sampling_hz)
+        if not math.isfinite(hz) or hz <= 0.0:
+            raise ValueError("sampling_hz must be finite and greater than zero")
+        if len(samples) < 8:
+            raise ValueError("at least 8 numeric samples are required")
+        if any(not math.isfinite(value) for value in samples):
+            raise ValueError("sensor samples must all be finite numeric values")
+        timestamps = tuple(float(value) for value in self.timestamps)
+        if timestamps and len(timestamps) != len(samples):
+            raise ValueError("timestamps must have one entry per sample")
+        if any(not math.isfinite(value) for value in timestamps):
+            raise ValueError("timestamps must be finite")
+        if timestamps and any(right <= left for left, right in zip(timestamps, timestamps[1:])):
+            raise ValueError("timestamps must be strictly increasing")
+        object.__setattr__(self, "samples", samples)
+        object.__setattr__(self, "sampling_hz", hz)
+        object.__setattr__(self, "timestamps", timestamps)
+
+    @property
+    def duration_seconds(self) -> float:
+        return len(self.samples) / self.sampling_hz
+
+
+def load_sensors(
+    source: str | Path | Sequence[float] | SensorData,
+    *,
+    sampling_hz: float | None = None,
+    column: str = "value",
+    unit: str = "m/s^2",
+    channel: str | None = None,
+) -> SensorData:
+    """Load one numeric channel from CSV, JSON, an array, or SensorData.
+
+    CSV files need a header matching ``column``. JSON may be a numeric array,
+    an object with ``samples``, or an array of objects containing ``column``.
+    Sampling frequency must be supplied because 0.1 does not infer time from
+    arbitrary file metadata. Blank or non-numeric samples are rejected rather
+    than skipped or interpolated.
+    """
+    if isinstance(source, SensorData):
+        if sampling_hz is not None and not math.isclose(float(sampling_hz), source.sampling_hz):
+            raise ValueError("sampling_hz conflicts with the supplied SensorData")
+        return source
+    if sampling_hz is None:
+        raise ValueError("sampling_hz is required for sensor input")
+
+    values: list[float]
+    source_name = channel or column
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        suffix = path.suffix.lower()
+        if suffix == ".csv":
+            with path.open("r", encoding="utf-8-sig", newline="") as handle:
+                # csv.reader rather than DictReader: DictReader silently skips
+                # blank lines, which in a one-column file are missing samples.
+                # Dropping them would shorten a regularly sampled record and
+                # shift every later sample in time.
+                reader = csv.reader(handle)
+                header = next(reader, [])
+                if column not in header:
+                    raise ValueError(f"CSV column {column!r} not found; columns are {header}")
+                position = header.index(column)
+                values = [
+                    _parse_numeric(row[position] if position < len(row) else None, reader.line_num)
+                    for row in reader
+                ]
+        elif suffix in {".json", ".jsonl"}:
+            text = path.read_text(encoding="utf-8")
+            if suffix == ".jsonl":
+                payload: Any = [json.loads(line) for line in text.splitlines() if line.strip()]
+            else:
+                payload = json.loads(text)
+            values = _values_from_json(payload, column)
+        else:
+            raise ValueError("sensor source must be a .csv, .json, or .jsonl file")
+        if not channel:
+            source_name = path.stem
+    else:
+        values = [float(value) for value in source]
+
+    return SensorData(
+        samples=values,
+        sampling_hz=float(sampling_hz),
+        unit=unit,
+        channel=source_name,
+    )
+
+
+def _parse_numeric(value: Any, line_no: int) -> float:
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        raise ValueError(f"sensor input line {line_no} is not numeric: {value!r}") from None
+    if not math.isfinite(number):
+        raise ValueError(f"sensor input line {line_no} is not finite")
+    return number
+
+
+def _values_from_json(payload: Any, column: str) -> list[float]:
+    if isinstance(payload, dict):
+        if "samples" in payload:
+            payload = payload["samples"]
+        elif column in payload:
+            payload = payload[column]
+        else:
+            raise ValueError("JSON object must contain 'samples' or the selected channel key")
+    if not isinstance(payload, list):
+        raise ValueError("JSON sensor data must be an array")
+    values = []
+    for idx, item in enumerate(payload, 1):
+        if isinstance(item, dict):
+            if column not in item:
+                raise ValueError(f"JSON sample {idx} has no {column!r} value")
+            item = item[column]
+        values.append(_parse_numeric(item, idx))
+    return values