timoshenko-engine 2.0.1__py3-none-any.whl

timoshenko/oma.py

@@ -0,0 +1,254 @@
+"""Basic frequency-domain decomposition (FDD) for aligned output channels."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+import numpy as np
+
+from .multichannel import MultiChannelData
+
+
+@dataclass(frozen=True)
+class FDDMode:
+    frequency_hz: float
+    singular_value: float
+    singular_value_index: int
+    channel_ids: tuple[str, ...]
+    units: tuple[str, ...]
+    shape_real: tuple[float, ...]
+    shape_imag: tuple[float, ...]
+    singular_value_ratio: float
+
+    def to_dict(self) -> dict:
+        return {
+            "frequency_hz": self.frequency_hz,
+            "singular_value": self.singular_value,
+            "singular_value_index": self.singular_value_index,
+            "channel_ids": list(self.channel_ids),
+            "units": list(self.units),
+            "mode_shape": [
+                {"real": real, "imag": imag} for real, imag in zip(self.shape_real, self.shape_imag)
+            ],
+            "singular_value_ratio": self.singular_value_ratio,
+        }
+
+
+@dataclass(frozen=True)
+class FDDResult:
+    modes: tuple[FDDMode, ...]
+    sampling_hz: float
+    sample_count: int
+    resolution_hz: float
+    segment_count: int
+    nperseg: int
+    channel_ids: tuple[str, ...]
+    units: tuple[str, ...]
+    method: str = "welch_frequency_domain_decomposition"
+    status: str = "ok"
+    notes: tuple[str, ...] = ()
+
+    @property
+    def frequencies_hz(self) -> tuple[float, ...]:
+        return tuple(mode.frequency_hz for mode in self.modes)
+
+    def to_dict(self) -> dict:
+        return {
+            "modes": [mode.to_dict() for mode in self.modes],
+            "sampling_hz": self.sampling_hz,
+            "sample_count": self.sample_count,
+            "resolution_hz": self.resolution_hz,
+            "segment_count": self.segment_count,
+            "nperseg": self.nperseg,
+            "channel_ids": list(self.channel_ids),
+            "units": list(self.units),
+            "method": self.method,
+            "status": self.status,
+            "notes": list(self.notes),
+        }
+
+
+def identify_fdd(
+    observations: MultiChannelData,
+    *,
+    nperseg: int | None = None,
+    overlap: float = 0.5,
+    max_modes: int = 8,
+    max_singular_values: int = 4,
+    min_frequency_hz: float | None = None,
+    max_frequency_hz: float | None = None,
+    min_peak_ratio: float = 0.05,
+    min_singular_value_ratio: float = 0.05,
+) -> FDDResult:
+    """Estimate modal frequencies and complex mode shapes with Welch FDD.
+
+    The cross-spectral-density matrix is estimated from mean-removed Hann
+    segments, then decomposed frequency-by-frequency. The largest singular
+    value curves are searched for local peaks. This is a first-pass FDD
+    estimator: it does not use stabilization diagrams, SSI, damping fits,
+    environmental normalization, or damage classification.
+    """
+    if not isinstance(observations, MultiChannelData):
+        raise TypeError("observations must be MultiChannelData; use tm.load_multichannel_csv() or construct it explicitly")
+    if len(set(observations.units)) != 1:
+        raise ValueError("FDD requires channels with the same measurement unit; calibrate/transform mixed-unit channels first")
+    sample_count, channel_count = observations.samples.shape
+    nperseg_value, hop, segment_count, resolution, low, high = _plan(
+        sample_count,
+        observations.sampling_hz,
+        nperseg=nperseg,
+        overlap=overlap,
+        max_modes=max_modes,
+        max_singular_values=max_singular_values,
+        min_frequency_hz=min_frequency_hz,
+        max_frequency_hz=max_frequency_hz,
+        min_peak_ratio=min_peak_ratio,
+        min_singular_value_ratio=min_singular_value_ratio,
+    )
+    starts = range(0, sample_count - nperseg_value + 1, hop)
+
+    values = observations.samples
+    window = np.hanning(nperseg_value)
+    window_power = float(np.sum(window**2))
+    frequencies = np.fft.rfftfreq(nperseg_value, d=1.0 / observations.sampling_hz)
+    frequency_count = len(frequencies)
+    retained = min(int(max_singular_values), channel_count)
+    spectral_matrices = np.zeros((frequency_count, channel_count, channel_count), dtype=np.complex128)
+    for start in starts:
+        segment = values[start : start + nperseg_value]
+        segment = segment - np.mean(segment, axis=0, keepdims=True)
+        spectrum = np.fft.rfft(segment * window[:, None], axis=0)
+        spectral_matrices += np.einsum("fc,fd->fcd", spectrum, np.conjugate(spectrum), optimize=True)
+    spectral_matrices /= segment_count * observations.sampling_hz * window_power
+    if nperseg_value % 2 == 0:
+        spectral_matrices[1:-1] *= 2.0
+    else:
+        spectral_matrices[1:] *= 2.0
+
+    singular = np.zeros((frequency_count, retained), dtype=float)
+    vectors = np.zeros((frequency_count, channel_count, retained), dtype=np.complex128)
+    for idx in range(frequency_count):
+        eigenvalues, eigenvectors = np.linalg.eigh(spectral_matrices[idx])
+        order = np.argsort(eigenvalues)[::-1][:retained]
+        singular[idx, :] = np.maximum(eigenvalues[order].real, 0.0)
+        vectors[idx, :, :] = eigenvectors[:, order]
+
+    in_band = (frequencies >= low) & (frequencies <= high)
+    leading_peak = float(np.max(singular[in_band, 0])) if np.any(in_band) else 0.0
+    candidates: list[tuple[float, int, int]] = []
+    for rank in range(retained):
+        curve = singular[:, rank]
+        curve_max = float(np.max(curve[in_band])) if np.any(in_band) else 0.0
+        if curve_max <= 0.0:
+            continue
+        if rank > 0 and leading_peak > 0.0 and curve_max / leading_peak < min_singular_value_ratio:
+            continue
+        for idx in range(1, frequency_count - 1):
+            rank_ratio = float(curve[idx] / singular[idx, 0]) if singular[idx, 0] > 0.0 else 0.0
+            if (
+                in_band[idx]
+                and curve[idx] >= curve[idx - 1]
+                and curve[idx] > curve[idx + 1]
+                and curve[idx] >= curve_max * min_peak_ratio
+                and rank_ratio >= min_singular_value_ratio
+            ):
+                candidates.append((float(curve[idx]), rank, idx))
+    candidates.sort(reverse=True)
+    chosen: list[tuple[float, int, int]] = []
+    for candidate in candidates:
+        _, rank, idx = candidate
+        if all(abs(float(frequencies[idx] - frequencies[other_idx])) >= 2.0 * resolution for _, _, other_idx in chosen):
+            chosen.append(candidate)
+        if len(chosen) >= max_modes:
+            break
+    chosen.sort(key=lambda item: float(frequencies[item[2]]))
+
+    modes: list[FDDMode] = []
+    for value, rank, idx in chosen:
+        shape = vectors[idx, :, rank]
+        magnitude = np.abs(shape)
+        maximum = float(np.max(magnitude))
+        if maximum > 0.0:
+            shape = shape / maximum
+            phase_reference = int(np.argmax(np.abs(shape)))
+            shape = shape * np.exp(-1j * np.angle(shape[phase_reference]))
+        modes.append(FDDMode(
+            frequency_hz=float(frequencies[idx]),
+            singular_value=value,
+            singular_value_index=rank + 1,
+            channel_ids=tuple(observations.channel_ids),
+            units=tuple(observations.units),
+            shape_real=tuple(float(item.real) for item in shape),
+            shape_imag=tuple(float(item.imag) for item in shape),
+            singular_value_ratio=float(value / singular[idx, 0]) if singular[idx, 0] > 0.0 else 0.0,
+        ))
+    notes = (
+        "Frequency resolution is sampling_hz / nperseg; longer windows improve resolution but reduce the number of averages.",
+        "Mode-shape components are normalized to unit peak magnitude; their overall scale and phase are arbitrary.",
+        "Peaks from different singular-value curves can be missed or duplicated for close/repeated modes; review results against engineering context.",
+    )
+    return FDDResult(
+        modes=tuple(modes),
+        sampling_hz=observations.sampling_hz,
+        sample_count=int(sample_count),
+        resolution_hz=resolution,
+        segment_count=segment_count,
+        nperseg=nperseg_value,
+        channel_ids=tuple(observations.channel_ids),
+        units=tuple(observations.units),
+        status="ok" if modes else "no_peaks_found",
+        notes=notes,
+    )
+
+
+def validate_options(sample_count: int, sampling_hz: float, **options) -> None:
+    """Check ``identify_fdd`` options for a record length without any data.
+
+    Raises the same errors ``identify_fdd`` would raise for these options, so
+    long-running callers can reject a bad configuration up front.
+    """
+    _plan(int(sample_count), float(sampling_hz), **options)
+
+
+def _plan(
+    sample_count: int,
+    sampling_hz: float,
+    *,
+    nperseg: int | None = None,
+    overlap: float = 0.5,
+    max_modes: int = 8,
+    max_singular_values: int = 4,
+    min_frequency_hz: float | None = None,
+    max_frequency_hz: float | None = None,
+    min_peak_ratio: float = 0.05,
+    min_singular_value_ratio: float = 0.05,
+) -> tuple[int, int, int, float, float, float]:
+    """Validate options and return segment length, hop, count, resolution and band."""
+    if max_modes < 1 or max_singular_values < 1:
+        raise ValueError("max_modes and max_singular_values must be positive")
+    if not 0.0 <= min_peak_ratio < 1.0:
+        raise ValueError("min_peak_ratio must be in [0, 1)")
+    if not math.isfinite(float(min_singular_value_ratio)) or not 0.0 <= float(min_singular_value_ratio) <= 1.0:
+        raise ValueError("min_singular_value_ratio must be finite and in [0, 1]")
+    overlap_value = float(overlap)
+    if not math.isfinite(overlap_value) or not 0.0 <= overlap_value <= 0.9:
+        raise ValueError("overlap must be finite and in [0, 0.9]")
+    if nperseg is None:
+        available = max(8, min(1024, int(sample_count * (1.0 - overlap_value))))
+        nperseg_value = 2 ** int(math.floor(math.log2(available)))
+    else:
+        nperseg_value = int(nperseg)
+    if nperseg_value < 8 or nperseg_value > 4096 or nperseg_value > sample_count:
+        raise ValueError("nperseg must be between 8 and min(sample_count, 4096)")
+    hop = max(1, int(round(nperseg_value * (1.0 - overlap_value))))
+    segment_count = len(range(0, sample_count - nperseg_value + 1, hop))
+    if segment_count < 2:
+        raise ValueError("at least two overlapping FFT segments are required; lower nperseg or overlap less")
+    resolution = sampling_hz / nperseg_value
+    low = float(min_frequency_hz) if min_frequency_hz is not None else resolution
+    high = float(max_frequency_hz) if max_frequency_hz is not None else sampling_hz / 2.0
+    high = min(high, sampling_hz / 2.0)
+    if not math.isfinite(low) or low < 0.0 or not math.isfinite(high) or high <= low:
+        raise ValueError("frequency bounds must be finite and non-negative, with max greater than min")
+    return nperseg_value, hop, segment_count, resolution, low, high

timoshenko/plugins.py

@@ -0,0 +1,142 @@
+"""Explicit, versioned discovery of optional observation-source plugins."""
+
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+import inspect
+import re
+from typing import Any, Callable, Protocol, runtime_checkable
+
+from .adapters import ObservationSource
+
+
+PLUGIN_API_VERSION = "1"
+ENTRY_POINT_GROUP = "timoshenko.plugins"
+
+
+class PluginError(RuntimeError):
+    """Base exception for invalid or incompatible engine plugins."""
+
+
+class PluginCompatibilityError(PluginError):
+    """Raised when a plugin targets a different plugin API version."""
+
+
+class PluginLoadError(PluginError):
+    """Raised when installed plugin code cannot be loaded or registered."""
+
+
+@runtime_checkable
+class EnginePlugin(Protocol):
+    name: str
+    api_version: str
+
+    def register(self, registry: "PluginContributions") -> None: ...
+
+
+class PluginContributions:
+    """A staging area; contributions become visible only after registration succeeds."""
+
+    def __init__(self) -> None:
+        self._source_factories: dict[str, Callable[..., ObservationSource]] = {}
+
+    def register_source(self, name: str, factory: Callable[..., ObservationSource]) -> None:
+        key = _normalize_name(name, "source")
+        if not callable(factory):
+            raise TypeError("source factory must be callable")
+        if key in self._source_factories:
+            raise PluginError(f"source factory {key!r} was registered more than once by this plugin")
+        self._source_factories[key] = factory
+
+
+class PluginRegistry:
+    """Registry for optional adapter/source factories supplied by plugins.
+
+    Entry points are loaded only when ``load_entry_points`` is explicitly
+    called. Loading executes installed Python code in this process; this is
+    discovery/version checking, not a sandbox.
+    """
+
+    def __init__(self) -> None:
+        self._source_factories: dict[str, Callable[..., ObservationSource]] = {}
+        self._plugins: dict[str, str] = {}
+
+    @property
+    def installed_plugins(self) -> tuple[str, ...]:
+        return tuple(sorted(self._plugins))
+
+    @property
+    def source_names(self) -> tuple[str, ...]:
+        return tuple(sorted(self._source_factories))
+
+    def register(self, plugin: EnginePlugin) -> None:
+        name = _normalize_name(getattr(plugin, "name", ""), "plugin")
+        api_version = str(getattr(plugin, "api_version", ""))
+        callback = getattr(plugin, "register", None)
+        if not callable(callback):
+            raise PluginError("plugin must provide a callable register(registry) method")
+        if api_version != PLUGIN_API_VERSION:
+            raise PluginCompatibilityError(
+                f"plugin {name!r} targets API {api_version!r}; this engine supports {PLUGIN_API_VERSION!r}"
+            )
+        if name in self._plugins:
+            raise PluginError(f"plugin {name!r} is already registered")
+
+        staged = PluginContributions()
+        try:
+            callback(staged)
+        except Exception as error:
+            raise PluginLoadError(f"plugin {name!r} failed during registration: {error}") from error
+        collisions = sorted(set(staged._source_factories) & set(self._source_factories))
+        if collisions:
+            raise PluginError(f"plugin {name!r} conflicts with registered source name(s): {', '.join(collisions)}")
+        self._source_factories.update(staged._source_factories)
+        self._plugins[name] = api_version
+
+    def create_source(self, name: str, **configuration: Any) -> ObservationSource:
+        key = _normalize_name(name, "source")
+        try:
+            factory = self._source_factories[key]
+        except KeyError:
+            raise KeyError(f"no source factory registered as {key!r}; available: {', '.join(self.source_names) or '(none)'}") from None
+        source = factory(**configuration)
+        if any(not callable(getattr(source, method, None)) for method in ("open", "read_batch", "close")):
+            raise PluginError(f"source factory {key!r} did not return an ObservationSource")
+        return source
+
+    @classmethod
+    def load_entry_points(cls, *, group: str = ENTRY_POINT_GROUP) -> "PluginRegistry":
+        """Load plugins advertised in package metadata; failures are explicit."""
+        registry = cls()
+        for point in sorted(entry_points(group=group), key=lambda item: item.name):
+            try:
+                exported = point.load()
+                if inspect.isclass(exported) or (callable(exported) and not callable(getattr(exported, "register", None))):
+                    exported = exported()
+                registry.register(exported)
+            except Exception as error:
+                if isinstance(error, PluginLoadError):
+                    raise PluginLoadError(f"entry point {point.name!r}: {error}") from error
+                raise PluginLoadError(f"could not load entry point {point.name!r}: {error}") from error
+        return registry
+
+
+def _normalize_name(value: Any, kind: str) -> str:
+    if not isinstance(value, str):
+        raise PluginError(f"{kind} name must be a string")
+    name = value.strip().lower()
+    if not re.fullmatch(r"[a-z][a-z0-9_.-]{0,62}", name):
+        raise PluginError(f"{kind} name must match [a-z][a-z0-9_.-]{{0,62}}")
+    return name
+
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "PLUGIN_API_VERSION",
+    "EnginePlugin",
+    "PluginCompatibilityError",
+    "PluginContributions",
+    "PluginError",
+    "PluginLoadError",
+    "PluginRegistry",
+]

timoshenko/polygon.py

@@ -0,0 +1,254 @@
+"""Analytic area properties for simple polygonal cross-sections."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+from typing import Iterable, Sequence
+
+Point2D = tuple[float, float]
+Ring = Sequence[Point2D]
+_MAX_VERTICES = 512
+_MAX_SPAN_M = 1e50
+
+
+@dataclass(frozen=True)
+class PolygonSectionProperties:
+    """Geometric properties of a uniform polygonal section (SI units).
+
+    ``second_moment_x_m4`` is about the centroidal x-axis (integral of y²),
+    ``second_moment_y_m4`` is about the centroidal y-axis (integral of x²),
+    and ``product_moment_xy_m4`` is the centroidal integral of x*y.
+    Section moduli distinguish the positive and negative sides because a
+    general polygon need not be symmetric about either centroidal axis.
+    """
+
+    area_m2: float
+    centroid_x_m: float
+    centroid_y_m: float
+    second_moment_x_m4: float
+    second_moment_y_m4: float
+    product_moment_xy_m4: float
+    section_modulus_x_positive_m3: float
+    section_modulus_x_negative_m3: float
+    section_modulus_y_positive_m3: float
+    section_modulus_y_negative_m3: float
+
+
+def polygon_section(
+    outer: Ring,
+    *,
+    holes: Iterable[Ring] = (),
+) -> PolygonSectionProperties:
+    """Calculate area, centroid, second moments, product moment and moduli.
+
+    Coordinates are ``(x, y)`` pairs in metres. The outer ring must describe a
+    simple boundary; each optional hole must be a simple ring strictly inside
+    it. Ring winding and explicit closure (repeating the first point) do not
+    affect the result. Up to 512 total vertices are accepted.
+
+    This computes uniform-density geometric properties only. It does not
+    resolve stress under coupled bending, principal-axis design checks,
+    material regions, plastic properties or torsion constants.
+    """
+    hole_rings = list(holes)
+    rings = [_normalize_ring(outer, "outer")] + [
+        _normalize_ring(ring, f"holes[{index}]") for index, ring in enumerate(hole_rings)
+    ]
+    if sum(map(len, rings)) > _MAX_VERTICES:
+        raise ValueError(f"outer and hole rings may contain at most {_MAX_VERTICES} total vertices")
+
+    origin_x, origin_y = rings[0][0]
+    shifted = [[(x - origin_x, y - origin_y) for x, y in ring] for ring in rings]
+    span = max(
+        max(x for ring in shifted for x, _ in ring) - min(x for ring in shifted for x, _ in ring),
+        max(y for ring in shifted for _, y in ring) - min(y for ring in shifted for _, y in ring),
+    )
+    if not math.isfinite(span) or span <= 0.0 or span > _MAX_SPAN_M:
+        raise ValueError("polygon coordinate span must be finite, non-zero, and no greater than 1e50 m")
+
+    area_tolerance = 1e-12 * span * span
+    length_tolerance = 1e-12 * span
+    for ring_index, ring in enumerate(shifted):
+        _ensure_simple(ring, area_tolerance, length_tolerance, f"ring {ring_index}")
+        if abs(_ring_integrals(ring)[0]) <= area_tolerance:
+            raise ValueError(f"ring {ring_index} must enclose a non-zero area")
+    _validate_holes(shifted, area_tolerance, length_tolerance)
+
+    area = first_x = first_y = inertia_x_origin = inertia_y_origin = product_origin = 0.0
+    for index, ring in enumerate(shifted):
+        values = _ring_integrals(ring)
+        signed_area = values[0]
+        role = 1.0 if index == 0 else -1.0
+        normalize = role if signed_area > 0.0 else -role
+        area += normalize * values[0]
+        first_x += normalize * values[1]
+        first_y += normalize * values[2]
+        inertia_x_origin += normalize * values[3]
+        inertia_y_origin += normalize * values[4]
+        product_origin += normalize * values[5]
+
+    if not math.isfinite(area) or area <= area_tolerance:
+        raise ValueError("outer ring and holes must leave a positive finite material area")
+    cx_local, cy_local = first_x / area, first_y / area
+    ixx = inertia_x_origin - area * cy_local**2
+    iyy = inertia_y_origin - area * cx_local**2
+    ixy = product_origin - area * cx_local * cy_local
+    # Roundoff can make a theoretically zero product moment tiny and negative
+    # inertias tiny around very slender geometries. Do not hide material errors.
+    if not all(math.isfinite(v) for v in (cx_local, cy_local, ixx, iyy, ixy)):
+        raise ValueError("polygon dimensions produced non-finite properties")
+    if ixx <= 0.0 or iyy <= 0.0:
+        raise ValueError("polygon dimensions produced non-positive centroidal second moments")
+
+    min_x, max_x = min(x for x, _ in shifted[0]), max(x for x, _ in shifted[0])
+    min_y, max_y = min(y for _, y in shifted[0]), max(y for _, y in shifted[0])
+    distances = (max_y - cy_local, cy_local - min_y, max_x - cx_local, cx_local - min_x)
+    if any(distance <= 0.0 or not math.isfinite(distance) for distance in distances):
+        raise ValueError("polygon section must have positive extreme-fibre distances on every side")
+
+    result_values = (
+        area,
+        origin_x + cx_local,
+        origin_y + cy_local,
+        ixx,
+        iyy,
+        ixy,
+        ixx / distances[0],
+        ixx / distances[1],
+        iyy / distances[2],
+        iyy / distances[3],
+    )
+    if not all(math.isfinite(value) for value in result_values):
+        raise ValueError("polygon dimensions produced non-finite section properties")
+    return PolygonSectionProperties(*result_values)
+
+
+def _normalize_ring(ring: Ring, name: str) -> list[Point2D]:
+    try:
+        points = []
+        for point in ring:
+            if len(point) != 2:
+                raise ValueError(f"{name} vertices must have exactly two coordinates")
+            points.append((float(point[0]), float(point[1])))
+    except (TypeError, ValueError, IndexError) as exc:
+        raise ValueError(f"{name} must be an iterable of finite (x, y) coordinate pairs") from exc
+    if len(points) > 1 and points[-1] == points[0]:
+        points.pop()
+    if len(points) < 3:
+        raise ValueError(f"{name} must contain at least three distinct vertices")
+    if any(not math.isfinite(x) or not math.isfinite(y) for x, y in points):
+        raise ValueError(f"{name} coordinates must be finite")
+    if any(points[index] == points[(index + 1) % len(points)] for index in range(len(points))):
+        raise ValueError(f"{name} must not contain repeated consecutive vertices")
+    return points
+
+
+def _ring_integrals(ring: Sequence[Point2D]) -> tuple[float, float, float, float, float, float]:
+    area2 = first_x6 = first_y6 = inertia_x12 = inertia_y12 = product24 = 0.0
+    for (x0, y0), (x1, y1) in zip(ring, (*ring[1:], ring[0])):
+        cross = x0 * y1 - x1 * y0
+        area2 += cross
+        first_x6 += (x0 + x1) * cross
+        first_y6 += (y0 + y1) * cross
+        inertia_x12 += (y0 * y0 + y0 * y1 + y1 * y1) * cross
+        inertia_y12 += (x0 * x0 + x0 * x1 + x1 * x1) * cross
+        product24 += (2*x0*y0 + x0*y1 + x1*y0 + 2*x1*y1) * cross
+    return area2/2, first_x6/6, first_y6/6, inertia_x12/12, inertia_y12/12, product24/24
+
+
+def _ensure_simple(ring: Sequence[Point2D], area_tolerance: float, length_tolerance: float, label: str) -> None:
+    count = len(ring)
+    for index in range(count):
+        previous, current, following = ring[index - 1], ring[index], ring[(index + 1) % count]
+        incoming = (previous[0] - current[0], previous[1] - current[1])
+        outgoing = (following[0] - current[0], following[1] - current[1])
+        cross = incoming[0] * outgoing[1] - incoming[1] * outgoing[0]
+        dot = incoming[0] * outgoing[0] + incoming[1] * outgoing[1]
+        if abs(cross) <= area_tolerance and dot > length_tolerance**2:
+            raise ValueError(f"{label} must not contain a backtracking overlapping edge")
+    for first in range(count):
+        a, b = ring[first], ring[(first + 1) % count]
+        for second in range(first + 1, count):
+            if second == first or second == (first + 1) % count or (second + 1) % count == first:
+                continue
+            c, d = ring[second], ring[(second + 1) % count]
+            if _segments_intersect(a, b, c, d, area_tolerance, length_tolerance):
+                raise ValueError(f"{label} must not self-intersect")
+
+
+def _segments_intersect(
+    a: Point2D,
+    b: Point2D,
+    c: Point2D,
+    d: Point2D,
+    area_tolerance: float,
+    length_tolerance: float,
+) -> bool:
+    def orient(p: Point2D, q: Point2D, r: Point2D) -> float:
+        return (q[0] - p[0]) * (r[1] - p[1]) - (q[1] - p[1]) * (r[0] - p[0])
+
+    def on_segment(p: Point2D, q: Point2D, r: Point2D) -> bool:
+        return (
+            min(p[0], r[0]) - length_tolerance <= q[0] <= max(p[0], r[0]) + length_tolerance
+            and min(p[1], r[1]) - length_tolerance <= q[1] <= max(p[1], r[1]) + length_tolerance
+        )
+
+    ab_c, ab_d, cd_a, cd_b = orient(a, b, c), orient(a, b, d), orient(c, d, a), orient(c, d, b)
+    if ((ab_c > area_tolerance and ab_d < -area_tolerance) or (ab_c < -area_tolerance and ab_d > area_tolerance)) and (
+        (cd_a > area_tolerance and cd_b < -area_tolerance) or (cd_a < -area_tolerance and cd_b > area_tolerance)
+    ):
+        return True
+    return (
+        abs(ab_c) <= area_tolerance and on_segment(a, c, b)
+        or abs(ab_d) <= area_tolerance and on_segment(a, d, b)
+        or abs(cd_a) <= area_tolerance and on_segment(c, a, d)
+        or abs(cd_b) <= area_tolerance and on_segment(c, b, d)
+    )
+
+
+def _point_in_ring(point: Point2D, ring: Sequence[Point2D]) -> bool:
+    x, y = point
+    inside = False
+    previous = ring[-1]
+    for current in ring:
+        x0, y0 = previous
+        x1, y1 = current
+        if (y0 > y) != (y1 > y):
+            crossing_x = (x1 - x0) * (y - y0) / (y1 - y0) + x0
+            if x < crossing_x:
+                inside = not inside
+        previous = current
+    return inside
+
+
+def _validate_holes(
+    rings: Sequence[Sequence[Point2D]], area_tolerance: float, length_tolerance: float
+) -> None:
+    outer = rings[0]
+    holes = rings[1:]
+    for index, hole in enumerate(holes):
+        if not _point_in_ring(hole[0], outer):
+            raise ValueError(f"hole {index} must be strictly inside the outer ring")
+        if _rings_intersect(hole, outer, area_tolerance, length_tolerance):
+            raise ValueError(f"hole {index} must not touch or cross the outer ring")
+        for earlier_index, earlier in enumerate(holes[:index]):
+            if (
+                _rings_intersect(hole, earlier, area_tolerance, length_tolerance)
+                or _point_in_ring(hole[0], earlier)
+                or _point_in_ring(earlier[0], hole)
+            ):
+                raise ValueError(f"holes {earlier_index} and {index} must not overlap or contain one another")
+
+
+def _rings_intersect(
+    first: Sequence[Point2D],
+    second: Sequence[Point2D],
+    area_tolerance: float,
+    length_tolerance: float,
+) -> bool:
+    return any(
+        _segments_intersect(a, b, c, d, area_tolerance, length_tolerance)
+        for a, b in zip(first, (*first[1:], first[0]))
+        for c, d in zip(second, (*second[1:], second[0]))
+    )

timoshenko/pressure.py

@@ -0,0 +1,33 @@
+"""Thin-wall closed-cylinder membrane stress estimates."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+
+@dataclass(frozen=True)
+class ThinWallCylinderResult:
+    hoop_stress_pa: float
+    longitudinal_stress_pa: float
+    thickness_to_mean_radius_ratio: float
+
+
+def thin_wall_cylinder_stress(pressure_difference_pa: float, mean_radius_m: float,
+                              wall_thickness_m: float) -> ThinWallCylinderResult:
+    """Estimate membrane stresses in a closed-end thin cylindrical vessel.
+
+    The input is the inside-minus-outside pressure. The approximation assumes
+    a circular, thin, closed-ended cylinder and membrane behavior; local end,
+    nozzle, instability, fatigue, code, and thick-wall effects are excluded.
+    """
+    pressure, radius, thickness = map(float, (pressure_difference_pa, mean_radius_m, wall_thickness_m))
+    if not all(math.isfinite(v) for v in (pressure, radius, thickness)):
+        raise ValueError("inputs must be finite")
+    if radius <= 0.0 or thickness <= 0.0:
+        raise ValueError("mean radius and wall thickness must be positive")
+    return ThinWallCylinderResult(
+        hoop_stress_pa=pressure * radius / thickness,
+        longitudinal_stress_pa=pressure * radius / (2.0 * thickness),
+        thickness_to_mean_radius_ratio=thickness / radius,
+    )