oak-understory-shared-engineering-bench 0.1.0__tar.gz

oak_understory_shared_engineering_bench-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.eggs/
+*.egg-info/
+build/
+dist/
+
+# uv
+.uv/
+
+# OS / editor
+.DS_Store
+
+# Backtest working set: the fetched corpus + the ONNX embedding model.
+# Hundreds of MB, reproducible from the pinned snapshot and a bounded
+# date, and therefore fetched rather than carried.
+.cache/
+
+# Builder staging (should never appear here, but just in case)
+_staging/
+docs/*.print.html

oak_understory_shared_engineering_bench-0.1.0/Makefile

@@ -0,0 +1,11 @@
+# GENERATED — source: manifest.toml
+# DO NOT EDIT BY HAND. Regenerated on every `sync`; edits are lost.
+# To change it, edit manifest.toml (or the template) and re-run sync.
+# A harness library's developer entrypoints. `make check` is what CI runs.
+
+.PHONY: test check
+
+test:
+	python -m pytest -q
+
+check: test

oak_understory_shared_engineering_bench-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: oak-understory-shared-engineering-bench
+Version: 0.1.0
+Summary: an Understory commons: shared discipline assets, no seat.
+Requires-Python: >=3.13
+Requires-Dist: cambium-ai<0.4,>=0.3
+Requires-Dist: oak-understory-common<3,>=2
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'

oak_understory_shared_engineering_bench-0.1.0/oak_understory_shared_engineering_bench/__init__.py

@@ -0,0 +1,25 @@
+"""The engineering commons — a shared bench, and deliberately no vocabulary.
+
+⭐ A commons carries METHODS and NEVER A STOPLIST, and `commons_has_no_stoplist`
+refuses one at scaffold time. That asymmetry is the design: a Reynolds number is the
+same number whichever engineering discipline computes it, so five faculties each
+carrying a copy would be five places for it to drift — but a shared VOCABULARY would
+make every cross-domain match between two of those faculties a topic match, which is
+the one failure the whole thesis rests on avoiding.
+
+Five exact Tier-1 calculations, each conferring affordances selected by a computed
+value rather than by applicability:
+
+    flow       laminar preserves, turbulent combines; the transition band confers
+               nothing, being unstable rather than intermediate
+    mechanics  within the elastic limit a member recovers; past it, it degrades
+    buckling   slenderness limits, material strength bounds
+    thermal    a stack holds heat or transfers it
+    signals    above Nyquist reconstructs; below, it degrades irreversibly
+"""
+
+from oak_understory_shared_engineering_bench import (  # noqa: F401
+    buckling, flow, mechanics, signals, thermal,
+)
+
+__all__ = ["buckling", "flow", "mechanics", "signals", "thermal"]

oak_understory_shared_engineering_bench-0.1.0/oak_understory_shared_engineering_bench/buckling.py

@@ -0,0 +1,87 @@
+"""Column stability — the Euler critical load (Tier 1).
+
+    P_cr = pi^2 E I / (K L)^2
+
+⭐ The calculation that decides which failure mode you are designing against. A
+short column crushes and a slender one buckles, and buckling arrives without
+warning at a load the material's strength says is perfectly safe. Comparing the two
+is the whole point: a strength check alone is how a slender strut passes on paper
+and folds in service.
+"""
+
+from __future__ import annotations
+
+from oak_understory_common.method_doc import MethodDoc
+
+METHOD_DOC = MethodDoc(
+    title="Will this column crush or fold?",
+    what="Works out the load at which a slender column suddenly bows sideways, and "
+        "says whether that happens before or after the material would be crushed.",
+    inputs="Elastic modulus in pascals, second moment of area in metres to the "
+        "fourth, unsupported length in metres, an end-fixity factor, the "
+        "cross-sectional area in square metres, and the yield strength in pascals.",
+    outputs="Critical buckling load in newtons, and the squash load in newtons. "
+        "Both are forces; the smaller one is what governs.",
+    limits="⭐ Euler is an IDEAL: perfectly straight, perfectly centred, perfectly "
+        "elastic. Real columns have an initial bow and an eccentric load, so they "
+        "fail BELOW this figure — the number is an upper bound, not a rating, and "
+        "using it as a rating is how a strut is undersized. It is invalid for stocky "
+        "columns, where the material yields before the elastic formula applies and "
+        "the result is meaningless rather than merely optimistic. The end-fixity "
+        "factor assumes an idealised support; a real joint is rarely either pinned "
+        "or truly fixed, and K is where most of the error enters. Nothing here "
+        "covers local buckling of thin walls, torsional modes, or eccentric loading.",
+    tier=1,
+    when_to_use="Whenever a member carries compression and is not obviously stocky.",
+    references=(
+        "Euler L, Methodus inveniendi lineas curvas, 1744.",
+        "Timoshenko SP & Gere JM, Theory of Elastic Stability, 2nd ed.",
+    ),
+)
+
+import math
+
+#: Standard end-fixity factors. The field's, and named so a caller does not
+#: silently pass 1.0 for a cantilever, which understates the length by half.
+K_PINNED_PINNED = 1.0
+K_FIXED_FIXED = 0.5
+K_FIXED_PINNED = 0.699
+K_FIXED_FREE = 2.0
+
+METHOD_ID = "engineering.buckling.euler_critical_load"
+VERSION = "0.1.0"
+
+AFFORDANCES: tuple[str, ...] = ("constrain", "bound")
+
+
+def critical_load_n(modulus_pa: float, second_moment_m4: float,
+                    length_m: float, end_fixity: float = K_PINNED_PINNED) -> float:
+    """``pi^2 E I / (K L)^2`` in newtons."""
+    if min(modulus_pa, second_moment_m4, length_m, end_fixity) <= 0:
+        raise ValueError("modulus, second moment, length and fixity must be positive")
+    return math.pi ** 2 * modulus_pa * second_moment_m4 / (end_fixity * length_m) ** 2
+
+
+def squash_load_n(area_m2: float, yield_pa: float) -> float:
+    """The load at which the material simply crushes: ``A x sigma_y``."""
+    if min(area_m2, yield_pa) <= 0:
+        raise ValueError("area and yield strength must be positive")
+    return area_m2 * yield_pa
+
+
+def affordances(critical_n: float, squash_n: float) -> tuple[str, ...]:
+    """What the member lets you do, selected by WHICH failure arrives first.
+
+    ``constrain`` — buckling governs: the usable load is capped well below the
+    material's strength, and adding stronger material buys nothing. ⭐ Named
+    `constrain` and not `limit`: `electrical` claims `limit`, and RCGS renames the
+    capability rather than narrowing a stoplist.
+    ``bound`` — the material governs: strength sets the ceiling, which is the
+    ordinary case a strength calculation already describes.
+    """
+    return ("constrain",) if critical_n < squash_n else ("bound",)
+
+
+__all__ = ["AFFORDANCES", "K_FIXED_FIXED", "K_FIXED_FREE", "K_FIXED_PINNED",
+           "K_PINNED_PINNED", "METHOD_ID", "VERSION", "affordances",
+           "critical_load_n", "squash_load_n"]

oak_understory_shared_engineering_bench-0.1.0/oak_understory_shared_engineering_bench/dimensionless.py

@@ -0,0 +1,170 @@
+"""⭐ DIMENSIONLESS GROUPS — the one method that is domain-free by construction.
+
+Every other method in this institution answers one question in one discipline. This
+one does something none of them do, and it is the reason it was built.
+
+## ⭐ Why this is a RETRIEVAL key and not just another rule
+
+`risks-and-falsifiers.md` §2f measured seven method libraries closing an affordance
+vocabulary and **not one of them making it selective**: five to nine terms over
+hundreds of items, carrying two or three bits between them. The affordance TERM is
+not the retrieval unit.
+
+A dimensionless group is. **Re = 270 000 in a chiller pipe is the same structure as
+Re = 270 000 in a blood vessel or a wind tunnel** — not by analogy but by
+equivalence, because the governing equations are identical once non-dimensionalised.
+Two systems with matching groups are *dynamically similar*, and that is the whole
+content of transposition, computed exactly rather than argued.
+
+That is why aircraft are tested as scale models and why a heat exchanger correlation
+from 1930 still works on a fluid nobody had then. The group is the invariant; the
+domain is what it was measured in.
+
+## What this does and does not claim
+
+It computes named groups from whatever quantities a caller supplies and reports which
+groups two systems share. ⚠️ **Matching groups mean the two systems obey the same
+equations — NOT that a solution transfers.** Boundary conditions, geometry and the
+groups nobody thought to compute all still differ, and similitude that ignores an
+unmatched group is how a scale model gives a confidently wrong answer.
+"""
+
+from __future__ import annotations
+
+import math
+
+from oak_understory_common.method_doc import MethodDoc
+
+METHOD_DOC = MethodDoc(
+    title="Which dimensionless groups two systems share",
+    what="Reduces a set of physical quantities to the dimensionless groups that "
+        "govern them, and says which groups two different systems have in common.",
+    inputs="A mapping of quantity name to value for each system — density, "
+        "velocity, a length, viscosity, a diffusivity, and so on. Missing "
+        "quantities simply mean the groups needing them are not computed.",
+    outputs="Each group it could form, as a DIMENSIONLESS number, plus the groups "
+        "two systems match on and the relative difference on each. A ratio has no "
+        "unit and comparing it across domains is the entire point.",
+    limits="⭐ Matching groups mean two systems obey the same EQUATIONS. They do not "
+        "mean a solution transfers: boundary conditions, geometry and any group "
+        "nobody computed still differ, and similitude that ignores an unmatched "
+        "group is how a scale model gives a confidently wrong answer. It forms only "
+        "the groups it holds definitions for — an unnamed group governing the "
+        "problem is invisible here, and its absence is silent. It cannot tell "
+        "whether the quantities it was handed are the RIGHT ones: a caller who omits "
+        "the governing length scale gets a clean, wrong Reynolds number. And two "
+        "systems matching on one group out of five are not similar; the count "
+        "matters more than any single match.",
+    tier=1,
+    when_to_use="Before assuming a result from one domain applies in another, and to "
+        "find domains where a problem has already been solved.",
+    references=(
+        "Buckingham E, On physically similar systems, Phys. Rev. 1914.",
+        "Barenblatt GI, Scaling, Self-similarity, and Intermediate Asymptotics.",
+    ),
+)
+
+METHOD_ID = "engineering.dimensionless.groups"
+VERSION = "0.1.0"
+
+#: ⭐ Selected by the computed match, never by identity. `compare` when two systems
+#: share enough groups to be worth reading across; `distinguish` when they do not.
+AFFORDANCES: tuple[str, ...] = ("compare", "distinguish")
+
+#: Standard gravity, m/s².
+GRAVITY = 9.80665
+
+#: How close two groups must be to count as matched, as a relative difference.
+#: 10% because similitude is judged on order rather than on decimals — a scale
+#: model matched to 1% on Reynolds is a rare luxury, and 10% is the working line.
+MATCH_TOLERANCE = 0.10
+
+#: Two systems sharing fewer than this many groups are not similar in any useful
+#: sense. One shared group out of five is a coincidence with a name.
+MIN_SHARED = 2
+
+
+def _q(system, *names):
+    """The quantities, or None if any is missing. Absence is not zero."""
+    out = []
+    for name in names:
+        value = system.get(name)
+        if value is None:
+            return None
+        out.append(float(value))
+    return out
+
+
+def groups(system: dict) -> dict[str, float]:
+    """Every named group this module can form from what it was given.
+
+    ⭐ A group whose quantities are absent is OMITTED, never defaulted. A Reynolds
+    number computed with an assumed viscosity is a clean number about a system
+    nobody described.
+    """
+    out: dict[str, float] = {}
+
+    if (v := _q(system, "density", "velocity", "length", "viscosity")) and v[3] > 0:
+        out["reynolds"] = v[0] * v[1] * v[2] / v[3]
+    if (v := _q(system, "velocity", "length")) and v[1] > 0:
+        out["froude"] = v[0] / math.sqrt(GRAVITY * v[1])
+    if (v := _q(system, "velocity", "sound_speed")) and v[1] > 0:
+        out["mach"] = v[0] / v[1]
+    if (v := _q(system, "frequency", "length", "velocity")) and v[2] > 0:
+        out["strouhal"] = v[0] * v[1] / v[2]
+    if (v := _q(system, "heat_transfer_coefficient", "length", "conductivity")) and v[2] > 0:
+        out["biot"] = v[0] * v[1] / v[2]
+    if (v := _q(system, "velocity", "length", "diffusivity")) and v[2] > 0:
+        out["peclet"] = v[0] * v[1] / v[2]
+    if (v := _q(system, "viscosity", "density", "diffusivity")) and v[1] > 0 and v[2] > 0:
+        out["prandtl"] = (v[0] / v[1]) / v[2]
+    if (v := _q(system, "density", "velocity", "length", "surface_tension")) and v[3] > 0:
+        out["weber"] = v[0] * v[1] ** 2 * v[2] / v[3]
+    if (v := _q(system, "reaction_rate", "length", "velocity")) and v[2] > 0:
+        out["damkohler"] = v[0] * v[1] / v[2]
+    return out
+
+
+def shared(a: dict, b: dict, *, tolerance: float = MATCH_TOLERANCE) -> dict[str, float]:
+    """Groups both systems form, and the relative difference on each.
+
+    Only groups BOTH systems could form are considered. A group one system lacks is
+    not a mismatch — it is an unknown, and reporting it as a difference would make
+    an incomplete description look like a dissimilar system.
+    """
+    ga, gb = groups(a), groups(b)
+    out: dict[str, float] = {}
+    for name in sorted(set(ga) & set(gb)):
+        scale = max(abs(ga[name]), abs(gb[name]))
+        if scale == 0:
+            out[name] = 0.0
+            continue
+        out[name] = abs(ga[name] - gb[name]) / scale
+    return out
+
+
+def matched(a: dict, b: dict, *, tolerance: float = MATCH_TOLERANCE) -> tuple[str, ...]:
+    """The groups on which two systems agree within ``tolerance``."""
+    return tuple(name for name, diff in shared(a, b, tolerance=tolerance).items()
+                 if diff <= tolerance)
+
+
+def affordances(matches: tuple[str, ...], comparable: int) -> tuple[str, ...]:
+    """What the comparison lets you do, selected by how many groups matched.
+
+    ``compare`` — enough shared groups agree that the two systems obey the same
+    equations and a result from one is worth reading across.
+    ``distinguish`` — they do not: whatever the systems have in common, it is not
+    the physics, and a transposition between them would be a metaphor.
+
+    ⭐ It confers NOTHING when the two systems share too few computable groups to
+    judge. That is an unknown, not a negative, and the third outcome exists for the
+    same reason the impasse detector's does.
+    """
+    if comparable < MIN_SHARED:
+        return ()
+    return ("compare",) if len(matches) >= MIN_SHARED else ("distinguish",)
+
+
+__all__ = ["AFFORDANCES", "GRAVITY", "MATCH_TOLERANCE", "METHOD_DOC", "METHOD_ID",
+           "MIN_SHARED", "VERSION", "affordances", "groups", "matched", "shared"]

oak_understory_shared_engineering_bench-0.1.0/oak_understory_shared_engineering_bench/flow.py

@@ -0,0 +1,82 @@
+"""Flow regime — the Reynolds number (Tier 1).
+
+    Re = rho x v x D / mu
+
+Dimensionless, exact, and the calculation fluid engineering is organised around: it
+decides whether a flow is orderly enough to predict from first principles or has to
+be treated statistically. Nothing else about a pipe changes that answer.
+"""
+
+from __future__ import annotations
+
+from oak_understory_common.method_doc import MethodDoc
+
+METHOD_DOC = MethodDoc(
+    title="Is this flow orderly or churning?",
+    what="Works out whether a fluid moving through a pipe travels in smooth layers "
+        "or breaks up into churning eddies.",
+    inputs="Fluid density in kilograms per cubic metre, average speed in metres per "
+        "second, the pipe's internal diameter in metres, and dynamic viscosity in "
+        "pascal-seconds.",
+    outputs="The Reynolds number — a pure ratio with NO units. It is not a speed, "
+        "not a pressure, and a bigger number is not a faster flow.",
+    limits="⭐ The 2300 and 4000 boundaries are for STEADY flow in a straight, "
+        "smooth, circular pipe, and every one of those words is load-bearing: a "
+        "bend, a rough wall, a sudden expansion or a pulsating supply all trip "
+        "turbulence early, and a carefully isolated laboratory pipe can stay "
+        "laminar into the tens of thousands. Between 2300 and 4000 the flow is "
+        "genuinely indeterminate — it is not 'mildly turbulent', it is unstable and "
+        "may be either — so this method confers nothing there rather than guessing. "
+        "It assumes a Newtonian fluid, so it is wrong for blood, slurries and "
+        "polymer melts, whose viscosity depends on how hard they are sheared.",
+    tier=1,
+    when_to_use="Before applying any pressure-drop or heat-transfer correlation, "
+        "because almost all of them are valid in one regime only.",
+    references=(
+        "Reynolds O, An experimental investigation of the circumstances which "
+        "determine whether the motion of water shall be direct or sinuous, 1883.",
+        "White FM, Fluid Mechanics, 7th ed.",
+    ),
+)
+
+#: The classical transition band for pipe flow. The field's, not derived here.
+LAMINAR_BELOW = 2300.0
+TURBULENT_ABOVE = 4000.0
+
+METHOD_ID = "engineering.flow.reynolds_number"
+VERSION = "0.1.0"
+
+AFFORDANCES: tuple[str, ...] = ("preserve", "combine")
+
+
+def reynolds_number(density_kg_m3: float, velocity_m_s: float,
+                    diameter_m: float, viscosity_pa_s: float) -> float:
+    """``rho v D / mu``. Dimensionless and exact given the inputs."""
+    if min(density_kg_m3, diameter_m, viscosity_pa_s) <= 0:
+        raise ValueError("density, diameter and viscosity must be positive")
+    if velocity_m_s < 0:
+        raise ValueError("velocity may not be negative")
+    return density_kg_m3 * velocity_m_s * diameter_m / viscosity_pa_s
+
+
+def affordances(reynolds: float) -> tuple[str, ...]:
+    """What a flow regime lets you do, selected by the computed number.
+
+    ``preserve`` — laminar: layers stay separate, so anything carried in one stays
+    there and the profile is predictable in closed form.
+    ``combine`` — turbulent: eddies mix across the whole cross-section, which is
+    what you want for mixing and heat transfer and cannot have in laminar flow.
+
+    Between the two boundaries it confers NOTHING. The transition band is unstable
+    rather than intermediate, and a method that split the difference there would be
+    asserting a regime the physics does not have.
+    """
+    if reynolds < LAMINAR_BELOW:
+        return ("preserve",)
+    if reynolds > TURBULENT_ABOVE:
+        return ("combine",)
+    return ()
+
+
+__all__ = ["AFFORDANCES", "LAMINAR_BELOW", "METHOD_ID", "TURBULENT_ABOVE", "VERSION",
+           "affordances", "reynolds_number"]

oak_understory_shared_engineering_bench-0.1.0/oak_understory_shared_engineering_bench/mechanics.py

@@ -0,0 +1,156 @@
+"""Elastic response — deflection and the yield margin, for a NAMED arrangement (Tier 1).
+
+    delta = a F L^3 / (E I)          a from the support condition
+    sigma = M c / I,  M = b F L      b from the support condition
+
+Exact within the elastic regime, which is precisely the thing the second calculation
+is for: it says whether the first one is still allowed to be believed.
+
+## ⭐ Why the support condition is now an argument and not an assumption
+
+Until 2026-08-03 this module computed **one** arrangement — a cantilever with a load
+at the free end — behind a decision named `beam-loading`, and exposed no way to say
+so. §3e measured what that cost: the chiller briefing's headline finding, *"423% of
+yield; PAST YIELD"*, reads **52.8% of yield and confers `restore`** for the same total
+load carried as a distributed load on a simple span. **Not a caveat on a failure: a
+pass.** The method's own `limits` had named the gap — *"other supports … are all
+outside it"* — and the protocol gave nobody a way to close it.
+
+So the arrangement is a **reading**: a required, declared argument, refused rather
+than defaulted. `M = F L` and `M = F L / 8` are both right, and which one you meant is
+not a detail the library may choose on your behalf.
+
+⭐ The table below is enumerated, which this codebase normally refuses. It is the
+legitimate exception, and the same one `units.py` makes for the SI base symbols:
+these are the standard tabulated cases of the discipline, fixed by Roark rather than
+by judgement, and **an unrecognised name raises instead of falling back.**
+"""
+
+from __future__ import annotations
+
+from oak_understory_common.method_doc import MethodDoc
+
+METHOD_DOC = MethodDoc(
+    title="How far it bends, and whether it springs back",
+    what="Works out how far a loaded beam bends, and whether the load leaves it "
+        "permanently deformed or lets it return to shape.",
+    inputs="Load in newtons, length in metres, the material's elastic modulus in "
+        "pascals, the section's second moment of area in metres to the fourth, the "
+        "distance from the neutral axis to the outer fibre in metres, and the "
+        "material's yield strength in pascals — and the SUPPORT CONDITION, which is "
+        "required and has no default.",
+    outputs="Deflection in metres and bending stress in pascals. A deflection is a "
+        "distance, not a fraction of the length.",
+    limits="⭐ Both formulas are ELASTIC and small-deflection: they assume the beam "
+        "returns to shape and that it has barely moved. Past yield the first is "
+        "simply wrong — it keeps returning a tidy number for a beam that is "
+        "bending permanently — which is why the yield margin is computed alongside "
+        "rather than left to the caller. ⭐ It covers the five STANDARD support "
+        "conditions and no others: a partially fixed end, a continuous beam over "
+        "several supports, an overhang, a non-central point load and any combined "
+        "loading are all outside it, and the answers differ by factors of several "
+        "between arrangements — which is why the support condition is a required "
+        "argument here and not a default. Buckling, fatigue under repeated loading "
+        "and dynamic amplification are outside it too, and fatigue in particular "
+        "breaks things that never come close to yield in a single application.",
+    tier=1,
+    when_to_use="For a first-pass sizing check, and to know whether a more careful "
+        "analysis is needed because yield is close.",
+    references=(
+        "Gere JM & Goodno BJ, Mechanics of Materials, 8th ed.",
+        "Roark's Formulas for Stress and Strain, 8th ed., Table 8.1.",
+    ),
+)
+
+#: Utilisation above which the elastic assumption is no longer safe to rely on. A
+#: conventional design margin, not derived from anything measured here.
+YIELD_MARGIN = 1.0
+
+#: ⭐ The standard tabulated cases: (deflection coefficient a, moment coefficient b),
+#: so ``delta = a F L^3 / (E I)`` and ``M = b F L``. For the distributed cases F is
+#: the TOTAL load on the span, which is what makes the arrangements comparable at
+#: equal load — the comparison §3e turned on.
+#:
+#: ⚠️ Enumerated deliberately, and an unknown name RAISES. See the module docstring.
+SUPPORTS: dict[str, tuple[float, float]] = {
+    "cantilever-tip-point": (1.0 / 3.0, 1.0),
+    "simply-supported-central-point": (1.0 / 48.0, 1.0 / 4.0),
+    "simply-supported-distributed": (5.0 / 384.0, 1.0 / 8.0),
+    "fixed-fixed-central-point": (1.0 / 192.0, 1.0 / 8.0),
+    "fixed-fixed-distributed": (1.0 / 384.0, 1.0 / 12.0),
+}
+
+#: ⚠️ The id is KEPT although the module now covers five arrangements. A method id is
+#: a published name that experiments, results JSONs and tests bind to by string, and
+#: the standing rule is EXTEND, NEVER RENAME. The VERSION carries the change instead.
+METHOD_ID = "engineering.mechanics.cantilever"
+VERSION = "0.2.0"
+
+AFFORDANCES: tuple[str, ...] = ("restore", "degrade")
+
+
+def coefficients(support: str) -> tuple[float, float]:
+    """``(a, b)`` for a named arrangement. ⭐ Raises on anything unrecognised.
+
+    Falling back to a default here would reinstate the exact defect this argument
+    was added to remove, and it would do it invisibly.
+    """
+    try:
+        return SUPPORTS[support]
+    except (KeyError, TypeError):
+        raise ValueError(
+            f"{support!r} is not one of the standard arrangements "
+            f"{sorted(SUPPORTS)}. There is no default: which arrangement the number "
+            f"describes changes it by a factor of several, and guessing on the "
+            f"caller's behalf is how a pass was reported as a failure (§3e)."
+        ) from None
+
+
+def max_deflection_m(load_n: float, length_m: float, modulus_pa: float,
+                     second_moment_m4: float, support: str) -> float:
+    """``a F L³ / (E I)`` in metres, for the named arrangement."""
+    if min(length_m, modulus_pa, second_moment_m4) <= 0:
+        raise ValueError("length, modulus and second moment must be positive")
+    a, _ = coefficients(support)
+    return a * load_n * length_m ** 3 / (modulus_pa * second_moment_m4)
+
+
+def bending_stress_pa(load_n: float, length_m: float, fibre_distance_m: float,
+                      second_moment_m4: float, support: str) -> float:
+    """``M c / I`` at the governing section, where ``M = b F L``."""
+    if min(length_m, fibre_distance_m, second_moment_m4) <= 0:
+        raise ValueError("length, fibre distance and second moment must be positive")
+    _, b = coefficients(support)
+    return b * load_n * length_m * fibre_distance_m / second_moment_m4
+
+
+def tip_deflection_m(load_n: float, length_m: float, modulus_pa: float,
+                     second_moment_m4: float) -> float:
+    """⚠️ LEGACY — the cantilever-only deflection, kept because it is a published
+    name. New callers use :func:`max_deflection_m` with an explicit arrangement."""
+    return max_deflection_m(load_n, length_m, modulus_pa, second_moment_m4,
+                            "cantilever-tip-point")
+
+
+def utilisation(stress_pa: float, yield_pa: float) -> float:
+    """Stress over yield strength. 1.0 is the elastic limit exactly."""
+    if yield_pa <= 0:
+        raise ValueError("yield strength must be positive")
+    return stress_pa / yield_pa
+
+
+def affordances(stress_pa: float, yield_pa: float) -> tuple[str, ...]:
+    """What the loaded member lets you do, selected by the computed utilisation.
+
+    ``restore`` — within the elastic limit, so the deflection is reversible and the
+    part returns to shape when the load comes off. ⭐ Named `restore` and not
+    `recover`, which `materials` claims.
+    ``degrade`` — past yield: the deformation is permanent, and the deflection
+    number computed above has stopped being true of it.
+    """
+    return ("restore",) if utilisation(stress_pa, yield_pa) < YIELD_MARGIN else ("degrade",)
+
+
+__all__ = ["AFFORDANCES", "METHOD_ID", "SUPPORTS", "VERSION", "YIELD_MARGIN",
+           "affordances", "bending_stress_pa", "coefficients", "max_deflection_m",
+           "tip_deflection_m", "utilisation"]