api581-engine 0.1.4__py3-none-any.whl

api581/effects.py

@@ -0,0 +1,232 @@
+"""Independent consequence primitives; explicit applicability and provenance."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, Positive, NonNegative, Fraction, calculation, ensure
+
+
+class JetPower(Model):
+    mass_rate_kg_s: NonNegative
+    heat_of_combustion_j_kg: Positive
+    radiative_fraction: Fraction = .35
+
+
+@calculation("effects/jet-fire-power", "Jet fire radiated power", JetPower,
+             ["Part 3 §5.8.3.2 eq (3.152); PDF p554"],
+             limitations=["SI radiated power; external applicability validation required for LH2."])
+def jet_power(x):
+    return {"radiated_power_w": x.mass_rate_kg_s * x.heat_of_combustion_j_kg * x.radiative_fraction}
+
+
+class JetFlux(Model):
+    radiated_power_w: NonNegative
+    distance_m: Positive
+    atmospheric_transmissivity: Fraction
+
+
+@calculation("effects/jet-fire-flux", "Point-source jet fire received radiation", JetFlux,
+             ["Part 3 eqs (3.153)-(3.154); PDF p554"], limitations=["Far-field point source at grade; flame impingement and near field not represented."])
+def jet_flux(x):
+    return {"received_flux_w_m2": x.atmospheric_transmissivity * x.radiated_power_w / (4 * math.pi * x.distance_m ** 2)}
+
+
+class JetDistance(Model):
+    radiated_power_w: NonNegative
+    threshold_w_m2: Positive
+    transmissivity_model: Literal["constant", "api_water_vapor"]
+    atmospheric_transmissivity: Fraction | None = None
+    water_partial_pressure_pa: Positive | None = None
+
+
+@calculation("effects/jet-fire-distance", "Jet fire threshold radius and consequence area", JetDistance,
+             ["Part 3 eqs (3.140), (3.152)-(3.156)"],
+             limitations=["Constant transmissivity is an explicitly supplied approximation; api_water_vapor uses distance-dependent attenuation capped at physical maximum 1.",
+                          "Water-vapor mode uses eq (3.140) exponent -0.09 with C19=1.085 and pressure in kPa; the base-edition table labels C19 dimensions with exponent 0.092, recorded as a source discrepancy.",
+                          "Point source at grade; LH2-specific validation outstanding."])
+def jet_distance(x):
+    ensure((x.transmissivity_model == "constant" and x.atmospheric_transmissivity is not None and x.water_partial_pressure_pa is None)
+           or (x.transmissivity_model == "api_water_vapor" and x.water_partial_pressure_pa is not None and x.atmospheric_transmissivity is None),
+           "Provide exactly the parameter for the selected transmissivity model")
+    if x.radiated_power_w == 0 or (x.transmissivity_model == "constant" and x.atmospheric_transmissivity == 0):
+        return {"threshold_distance_m": 0, "consequence_area_m2": 0, "transmissivity_at_distance": None}
+    def tau(r):
+        return x.atmospheric_transmissivity if x.transmissivity_model == "constant" else min(1, 1.085 * (x.water_partial_pressure_pa / 1000 * r) ** (-.09))
+    high = math.sqrt(x.radiated_power_w / (4 * math.pi * x.threshold_w_m2))
+    low = 0.0
+    for _ in range(100):
+        mid = (low + high) / 2
+        if mid == 0:
+            break
+        flux = tau(mid) * x.radiated_power_w / (4 * math.pi * mid ** 2)
+        if flux > x.threshold_w_m2:
+            low = mid
+        else:
+            high = mid
+    radius = (low + high) / 2
+    return {"threshold_distance_m": radius, "consequence_area_m2": math.pi * radius ** 2,
+            "transmissivity_at_distance": tau(radius)}
+
+
+class FlashFire(Model):
+    area_within_lfl_m2: NonNegative
+
+
+@calculation("effects/flash-fire", "Flash fire consequence areas", FlashFire,
+             ["Part 3 §4.8.2.3, §5.8.6"], limitations=["LFL footprint must come from a validated dispersion model."])
+def flash_fire(x):
+    return {"personnel_area_m2": x.area_within_lfl_m2, "equipment_area_m2": .25 * x.area_within_lfl_m2}
+
+
+class PoolArea(Model):
+    liquid_rate_kg_s: NonNegative
+    burning_rate_kg_m2_s: Positive
+    available_liquid_mass_kg: NonNegative
+    density_kg_m3: Positive
+    pool_depth_m: Positive = .005
+    site_maximum_area_m2: Positive
+
+
+@calculation("effects/pool-fire-area", "Pool burning area and radius", PoolArea,
+             ["Part 3 eqs (3.131)-(3.134); PDF pp550-551"],
+             limitations=["Pool geometry only; burning rate supplied by caller; surface radiation/view factors not included. Site limit is mandatory."])
+def pool_area(x):
+    burning_area = x.liquid_rate_kg_s / x.burning_rate_kg_m2_s
+    mass_area = x.available_liquid_mass_kg / (x.density_kg_m3 * x.pool_depth_m)
+    area = min(burning_area, mass_area, x.site_maximum_area_m2)
+    return {"burning_area_m2": burning_area, "inventory_limited_area_m2": mass_area,
+            "pool_area_m2": area, "pool_radius_m": math.sqrt(area / math.pi)}
+
+
+class EmpiricalArea(Model):
+    coefficient_a: NonNegative
+    exponent_b: Positive
+    release_magnitude: NonNegative
+    magnitude_unit: Literal["kg/s", "kg"]
+    coefficient_source: str = Field(min_length=1, max_length=500)
+
+
+@calculation("consequence/power-law-area", "Level 1 consequence power-law primitive", EmpiricalArea,
+             ["Part 3 eqs (3.16)-(3.17)"],
+             limitations=["Caller-supplied SI coefficients only; does not select reference fluid or perform Type 0 blending. Not a complete Level 1 COF."])
+def power_area(x):
+    return {"area_m2": x.coefficient_a * x.release_magnitude ** x.exponent_b,
+            "coefficient_source": x.coefficient_source}
+
+
+class EventTree(Model):
+    phase: Literal["vapor", "liquid"]
+    release_type: Literal["continuous", "instantaneous"]
+    ignition_probability: Fraction
+    immediate_given_ignition: Fraction
+    vce_given_delayed: Fraction
+
+
+@calculation("events/leakage-tree", "Single-phase leakage event tree", EventTree,
+             ["Part 3 §5.8.1.6, Figure 5.3"],
+             limitations=["Leakage only, not rupture Figure 5.4; branch probabilities supplied by caller. Two-phase tree deferred."])
+def leakage_tree(x):
+    pi, immediate, vce = x.ignition_probability, x.immediate_given_ignition, x.vce_given_delayed
+    fire = "pool_fire" if x.phase == "liquid" else ("jet_fire" if x.release_type == "continuous" else "fireball")
+    probabilities = {"safe_dispersion": 1 - pi, fire: pi * immediate,
+                     "vce": pi * (1 - immediate) * vce, "flash_fire": pi * (1 - immediate) * (1 - vce)}
+    return {"terminal_probabilities": probabilities, "probability_sum": math.fsum(probabilities.values())}
+
+
+class Probit(Model):
+    intercept: float = Field(allow_inf_nan=False)
+    slope: Positive
+    concentration_exponent: Positive
+    concentration: NonNegative
+    exposure_duration: NonNegative
+    concentration_unit: str = Field(min_length=1, max_length=50)
+    duration_unit: str = Field(min_length=1, max_length=50)
+    coefficient_source: str = Field(min_length=1, max_length=500)
+
+
+@calculation("effects/toxic-probit", "User-parameterized toxic probit", Probit,
+             ["Part 3 §5.9.2"], origin="engineering_utility",
+             limitations=["Coefficient units must match supplied concentration/time. This generic utility uses caller-qualified coefficients; Table4.14 species calculations are separately available through toxic-species-probit."])
+def toxic_probit(x):
+    if x.concentration == 0 or x.exposure_duration == 0:
+        return {"probit": None, "effect_probability": 0}
+    y = x.intercept + x.slope * (x.concentration_exponent * math.log(x.concentration) + math.log(x.exposure_duration))
+    return {"probit": y, "effect_probability": .5 * math.erfc(-(y - 5) / math.sqrt(2))}
+
+
+class PoolBurning(Model):
+    heat_of_combustion_j_kg: Positive
+    latent_heat_j_kg: Positive
+    boiling: bool
+    specific_heat_j_kg_k: Positive | None = None
+    boiling_temperature_k: Positive | None = None
+    ambient_temperature_k: Positive | None = None
+
+
+@calculation("effects/pool-burning-rate", "Pool fire surface mass burning rate", PoolBurning,
+             ["Part 3 eqs (3.128)-(3.129), Annex 3.B C17; PDF pp550,648"],
+             limitations=["Empirical pool burning correlation; LH2 applicability not validated. Does not model unignited pool evaporation."])
+def pool_burning(x):
+    denominator = x.latent_heat_j_kg
+    if not x.boiling:
+        ensure(all(v is not None for v in (x.specific_heat_j_kg_k, x.boiling_temperature_k, x.ambient_temperature_k)),
+               "Non-boiling pool requires Cp, boiling and ambient temperatures")
+        ensure(x.boiling_temperature_k >= x.ambient_temperature_k, "Non-boiling pool requires boiling temperature >= ambient")
+        denominator += x.specific_heat_j_kg_k * (x.boiling_temperature_k - x.ambient_temperature_k)
+    return {"burning_rate_kg_m2_s": .001481 * x.heat_of_combustion_j_kg / denominator}
+
+
+class FireballGeometry(Model):
+    flammable_mass_kg: NonNegative
+
+
+@calculation("effects/fireball-geometry", "Fireball diameter, height and duration", FireballGeometry,
+             ["Part 3 eqs (3.158)-(3.161), Annex 3.B C22-C24; PDF pp555,648"],
+             limitations=["Instantaneous rupture fireball model; no continuous-release fireball. Empirical exponents follow printed 0.333/0.167."])
+def fireball_geometry(x):
+    mass = x.flammable_mass_kg
+    diameter = 5.8 * mass ** .333
+    duration = .45 * mass ** .333 if mass <= 29937 else 2.6 * mass ** .167
+    return {"diameter_m": diameter, "center_height_m": .75 * diameter, "duration_s": duration}
+
+
+class FireballFraction(Model):
+    burst_pressure_pa_abs: Positive
+
+
+@calculation("effects/fireball-radiative-fraction", "Fireball pressure-based radiative fraction", FireballFraction,
+             ["Part 3 eq (3.163), Annex 3.B C25; PDF pp555,648"],
+             limitations=["Raw correlation; results above 1 are rejected rather than silently capped. Applicability must be independently established."])
+def fireball_fraction(x):
+    fraction = .0296 * (x.burst_pressure_pa_abs / 1000) ** .32
+    ensure(fraction <= 1, "Pressure correlation exceeds a physical radiative fraction of 1")
+    return {"radiative_fraction": fraction}
+
+
+class FireballEmissive(Model):
+    flammable_mass_kg: NonNegative
+    heat_of_combustion_j_kg: Positive
+    radiative_fraction: Fraction
+    diameter_m: Positive
+    duration_s: Positive
+
+
+@calculation("effects/fireball-emissive-power", "Fireball surface emissive power", FireballEmissive,
+             ["Part 3 eq (3.162); PDF p555"])
+def fireball_emissive(x):
+    return {"surface_emissive_power_w_m2": x.radiative_fraction * x.flammable_mass_kg * x.heat_of_combustion_j_kg /
+            (math.pi * x.diameter_m ** 2 * x.duration_s)}
+
+
+class TntEquivalence(Model):
+    flammable_cloud_mass_kg: NonNegative
+    combustion_heat_j_kg: Positive
+    explosion_yield: Fraction
+    tnt_heat_j_kg: Positive
+    tnt_heat_source: str = Field(min_length=1, max_length=500)
+
+
+@calculation("effects/vce-tnt-equivalence", "VCE TNT equivalent mass", TntEquivalence,
+             ["Part 3 eq (3.169); PDF pp557-558"],
+             limitations=["TNT heat is mandatory: original text J/kg and Btu/lb values are inconsistent. Cloud mass definition and yield must be consistent. Blast pressure and distances require separate caller-qualified fit-domain inputs; equivalence alone does not establish blast-curve applicability."])
+def tnt_equivalence(x):
+    return {"tnt_equivalent_mass_kg": x.explosion_yield * x.flammable_cloud_mass_kg * x.combustion_heat_j_kg / x.tnt_heat_j_kg}

api581/evaporation.py

@@ -0,0 +1,181 @@
+"""Unignited boiling/non-boiling pool vapor sources, with steady-state gates."""
+import math
+from typing import Literal
+from .core import Model, NonNegative, Positive, calculation, ensure
+
+_SURFACES={"concrete":(.92,4.16e-7,1),"soil_average":(.96,4.59e-7,3),
+           "soil_sandy_dry":(.26,1.98e-7,3),"soil_sandy_moist_8pct":(.59,3.36e-7,3)}
+
+
+class SurfaceLookup(Model):
+    surface: Literal["concrete","soil_average","soil_sandy_dry","soil_sandy_moist_8pct"]
+
+
+class SurfaceInteraction(Model):
+    thermal_conductivity_w_m_k: Positive
+    thermal_diffusivity_m2_s: Positive
+    roughness_factor: Positive
+
+
+@calculation("properties/pool-surface-interaction", "SI liquid-pool ground interaction properties", SurfaceLookup,
+             ["Part3 Table5.2M; PDF p582"],
+             limitations=["Printed SI table values directly; no exact back-conversion of rounded US table. Historical representative ground properties, not measured site or cryogenic validation. Concrete is source default but public selection is explicit."])
+def surface_lookup(x):
+    k,a,rough=_SURFACES[x.surface]
+    return {"thermal_conductivity_w_m_k":k,"thermal_diffusivity_m2_s":a,"roughness_factor":rough}
+
+
+class PoolTemperatures(Model):
+    bubble_temperature_k: Positive
+    ground_temperature_k: Positive
+
+
+@calculation("release/pool-evaporation-regime", "Pool boiling/non-boiling temperature classification", PoolTemperatures,
+             ["Part3 §5.7.4.2-5.7.4.3; PDF p544"],
+             limitations=["Tb<Tg boiling; Tb>Tg non-boiling. Source gives no equality rule: equal temperatures return boundary_requires_qualification. Bubble temperature and ground temperature are supplied, not calculated with an EOS."])
+def regime(x):
+    label="boiling" if x.bubble_temperature_k < x.ground_temperature_k else (
+          "non_boiling" if x.bubble_temperature_k > x.ground_temperature_k else "boundary_requires_qualification")
+    return {"regime":label}
+
+
+class BoilingSetup(PoolTemperatures):
+    latent_heat_j_kg: Positive
+    surface: SurfaceInteraction
+    gravity_m_s2: Positive = 9.81
+
+
+def _boiling_coefficient(x):
+    ensure(x.bubble_temperature_k < x.ground_temperature_k,"Boiling model requires Tb<Tg")
+    k=x.surface.thermal_conductivity_w_m_k
+    a=x.surface.thermal_diffusivity_m2_s
+    coefficient=math.pi**1.5*x.surface.roughness_factor*k*(x.ground_temperature_k-x.bubble_temperature_k)/(
+        x.latent_heat_j_kg*math.sqrt(math.pi*a))
+    ensure(math.isfinite(coefficient) and coefficient > 0,"Boiling coefficient outside finite positive numerical domain","numerical_failure")
+    return coefficient
+
+
+class BoilingEvaporation(BoilingSetup):
+    vapor_volumetric_rate_m3_s: NonNegative
+    time_to_steady_s: NonNegative
+
+
+@calculation("release/boiling-pool-evaporation", "Printed boiling-pool evaporation correlation", BoilingEvaporation,
+             ["Part3 eq(3.103), Annex3.B C14=1; PDF pp544,647; Vdot/tp nomenclature PDF579"],
+             limitations=["Uses pi^1.5, not1.5. Vdot is vapor volume leaving pool surface, not liquid feed volume. Time is time to steady state per source nomenclature; this primitive does not assert an arbitrary transient evolution. No rainout, flash/EOS, inventory, site limit or LH2 validation."])
+def boiling_evaporation(x):
+    coefficient=_boiling_coefficient(x)
+    rate=coefficient*math.sqrt(2*x.gravity_m_s2*x.vapor_volumetric_rate_m3_s)*x.time_to_steady_s
+    ensure(rate > 0 or x.vapor_volumetric_rate_m3_s == 0 or x.time_to_steady_s == 0,
+           "Boiling evaporation rate underflow","numerical_failure")
+    return {"evaporation_rate_kg_s":rate,"latent_heat_rate_w":rate*x.latent_heat_j_kg}
+
+
+class BoilingRadius(Model):
+    vapor_volumetric_rate_m3_s: NonNegative
+    time_to_steady_s: NonNegative
+    gravity_m_s2: Positive = 9.81
+
+
+@calculation("release/boiling-pool-radius", "Boiling-pool spreading radius at steady-state time", BoilingRadius,
+             ["Part3 eq(3.104); PDF p544; Vdot/tp nomenclature PDF579"],
+             limitations=["r=sqrt(2/3)*(8*g*Vdot/pi)^.25*tp^.75. Vdot is vapor leaving the surface. Unconstrained correlation: no bund/terrain/site-area clipping or inventory mass balance."])
+def boiling_radius(x):
+    radius=math.sqrt(2/3)*(8*x.gravity_m_s2*x.vapor_volumetric_rate_m3_s/math.pi)**.25*x.time_to_steady_s**.75
+    ensure(radius > 0 or x.vapor_volumetric_rate_m3_s == 0 or x.time_to_steady_s == 0,
+           "Boiling pool radius underflow","numerical_failure")
+    area=math.pi*radius**2
+    ensure(area > 0 or radius == 0,"Boiling pool area underflow","numerical_failure")
+    return {"pool_radius_m":radius,"pool_area_m2":area}
+
+
+class BoilingSteadySource(BoilingSetup):
+    liquid_feed_rate_kg_s: NonNegative
+    pool_vapor_density_kg_m3: Positive
+    supply_duration_s: Positive
+    maximum_pool_area_m2: Positive
+
+
+@calculation("release/boiling-pool-steady-source", "Boiling equilibrium vapor source with duration/site support checks", BoilingSteadySource,
+             ["Part3 eqs(3.103)-(3.104), §5.7.4.2; PDF p544; Vdot definition PDF579"],
+             origin="api581_steady_pool_with_explicit_support_checks",
+             limitations=["At equilibrium evaporation=liquid feed; Vdot=feed/pool-vapor-density, not feed/liquid-density. Solves tp from eq3.103 then radius from3.104. Usable source returned only if feed persists beyond tp and equilibrium area fits supplied site limit. Failed support is not silently clipped or replaced by feed. No growing-pool transient, finite-inventory depletion, drainage or post-release evaporation solver."])
+def boiling_steady_source(x):
+    coefficient=_boiling_coefficient(x)
+    feed=x.liquid_feed_rate_kg_s
+    if feed == 0:
+        return {"equilibrium_evaporation_rate_kg_s":0,"vapor_volumetric_rate_m3_s":0,"time_to_steady_s":None,
+                "pool_radius_m":0,"pool_area_m2":0,"vapor_source_rate_kg_s":0,"support_status":"no_feed"}
+    volume=feed/x.pool_vapor_density_kg_m3
+    ensure(math.isfinite(volume) and volume > 0,"Pool vapor volumetric rate outside numerical domain","numerical_failure")
+    time=feed/(coefficient*math.sqrt(2*x.gravity_m_s2*volume))
+    ensure(math.isfinite(time) and time > 0,"Pool steady-state time outside numerical domain","numerical_failure")
+    geometry=boiling_radius(BoilingRadius(vapor_volumetric_rate_m3_s=volume,time_to_steady_s=time,gravity_m_s2=x.gravity_m_s2))
+    ensure(math.isfinite(geometry["pool_area_m2"]),"Pool equilibrium area outside numerical domain","numerical_failure")
+    duration_limited=time >= x.supply_duration_s
+    area_limited=geometry["pool_area_m2"] > x.maximum_pool_area_m2
+    status=("duration_and_area_limited" if duration_limited and area_limited else "duration_limited" if duration_limited else (
+            "area_limited" if area_limited else "supported"))
+    return {"equilibrium_evaporation_rate_kg_s":feed,"vapor_volumetric_rate_m3_s":volume,"time_to_steady_s":time,**geometry,
+            "vapor_source_rate_kg_s":feed if status == "supported" else None,"support_status":status}
+
+
+class NonBoilingSetup(PoolTemperatures):
+    bubble_pressure_at_ground_pa_abs: NonNegative
+    ambient_pressure_pa_abs: Positive = 101325
+    molecular_weight_kg_kmol: Positive
+    storage_temperature_k: Positive
+    wind_speed_m_s: NonNegative
+
+
+def _nonboiling_coefficient(x):
+    ensure(x.bubble_temperature_k > x.ground_temperature_k,"Non-boiling model requires Tb>Tg")
+    ensure(x.bubble_pressure_at_ground_pa_abs < x.ambient_pressure_pa_abs,
+           "Non-boiling bubble pressure at ground temperature must be below atmospheric pressure")
+    # Printed Pb,g is kPa; R=8314 J/(kmol K), C15=4.685.
+    coefficient=4.685*(x.bubble_pressure_at_ground_pa_abs/1000*x.molecular_weight_kg_kmol/(
+        8314*x.storage_temperature_k))*x.wind_speed_m_s**.78
+    ensure(math.isfinite(coefficient),"Non-boiling coefficient outside numerical domain","numerical_failure")
+    ensure(coefficient > 0 or x.bubble_pressure_at_ground_pa_abs == 0 or x.wind_speed_m_s == 0,
+           "Non-boiling coefficient underflow","numerical_failure")
+    return coefficient
+
+
+class NonBoilingEvaporation(NonBoilingSetup):
+    pool_radius_m: NonNegative
+
+
+@calculation("release/nonboiling-pool-evaporation", "Non-boiling pool wind-driven vapor generation", NonBoilingEvaporation,
+             ["Part3 eq(3.105), Annex3.B C15; PDF pp544,647; P/R/Ts units PDF578-579"],
+             limitations=["Follows printed C15=4.685 with Pb,g in kPa and R=8314; Pa public input divided by1000. Denominator uses printed storage Ts, not automatic substitution of ground temperature. Wind exponent.78 and radius exponent1.89. Wind qualified at6ft above grade. Zero wind gives zero correlation rate, not a model of molecular diffusion/quiescent evaporation. No site/inventory clipping or LH2 validation."])
+def nonboiling_evaporation(x):
+    coefficient=_nonboiling_coefficient(x)
+    rate=coefficient*x.pool_radius_m**1.89
+    ensure(rate > 0 or coefficient == 0 or x.pool_radius_m == 0,"Non-boiling evaporation underflow","numerical_failure")
+    return {"evaporation_rate_kg_s":rate}
+
+
+class NonBoilingSteadySource(NonBoilingSetup):
+    liquid_feed_rate_kg_s: NonNegative
+    maximum_pool_area_m2: Positive
+
+
+@calculation("release/nonboiling-pool-steady-source", "Non-boiling equilibrium source radius and site support check", NonBoilingSteadySource,
+             ["Part3 eq(3.105), §5.7.4.3; PDF p544"],
+             origin="api581_steady_pool_inverse_with_explicit_site_check",
+             limitations=["Solves evaporation=feed for radius. Time to equilibrium is not supplied by this equation and is not invented. Positive feed with zero wind/vapor pressure has no finite equilibrium in this correlation. Site limit failures return no usable source; no arbitrary radius clipping. Requires a separately qualified sustained feed/equilibrium assumption, not a transient pool or mass-balance simulation."])
+def nonboiling_steady_source(x):
+    coefficient=_nonboiling_coefficient(x)
+    feed=x.liquid_feed_rate_kg_s
+    if feed == 0:
+        return {"equilibrium_evaporation_rate_kg_s":0,"pool_radius_m":0,"pool_area_m2":0,
+                "vapor_source_rate_kg_s":0,"support_status":"no_feed"}
+    if coefficient == 0:
+        return {"equilibrium_evaporation_rate_kg_s":None,"pool_radius_m":None,"pool_area_m2":None,
+                "vapor_source_rate_kg_s":None,"support_status":"no_finite_steady_state"}
+    radius=math.exp((math.log(feed)-math.log(coefficient))/1.89)
+    area=math.pi*radius**2
+    ensure(math.isfinite(area) and area > 0 and radius > 0,"Non-boiling equilibrium geometry outside numerical domain","numerical_failure")
+    supported=area <= x.maximum_pool_area_m2
+    return {"equilibrium_evaporation_rate_kg_s":feed,"pool_radius_m":radius,"pool_area_m2":area,
+            "vapor_source_rate_kg_s":feed if supported else None,"support_status":"supported" if supported else "area_limited"}

api581/evidence.py

@@ -0,0 +1,81 @@
+"""Packaged verification evidence accessors for installed consumers."""
+from __future__ import annotations
+
+from hashlib import sha256
+from importlib.resources import files
+from typing import Any, TypedDict
+import json
+
+
+_RESOURCE = "native-engine-evidence.json"
+_SOFTWARE_TEST_RESOURCE = "software-test-evidence.json"
+_REFERENCE_FIXTURE_RESOURCE = "reference-fixture-evidence.json"
+
+
+class ValidationEvidence(TypedDict):
+    """Stable JSON shape linking a calculation to its verification record."""
+    manifest: str
+    packaged_manifest: str
+    verification_scripts: list[str]
+
+
+def native_engine_evidence() -> dict[str, Any]:
+    """Return a fresh copy of the packaged native-engine evidence manifest."""
+    resource = files("api581").joinpath("data", _RESOURCE)
+    return json.loads(resource.read_text(encoding="utf-8"))
+
+
+def native_engine_evidence_hash() -> str:
+    """Return the SHA-256 of the packaged native-engine evidence manifest."""
+    resource = files("api581").joinpath("data", _RESOURCE)
+    return sha256(resource.read_bytes()).hexdigest()
+
+
+def software_test_evidence() -> dict[str, Any]:
+    """Return the packaged calculation-to-test-module evidence manifest."""
+    resource = files("api581").joinpath("data", _SOFTWARE_TEST_RESOURCE)
+    return json.loads(resource.read_text(encoding="utf-8"))
+
+
+def software_test_evidence_hash() -> str:
+    """Return the SHA-256 of the packaged software-test evidence manifest."""
+    resource = files("api581").joinpath("data", _SOFTWARE_TEST_RESOURCE)
+    return sha256(resource.read_bytes()).hexdigest()
+
+
+def reference_fixture_evidence() -> dict[str, Any]:
+    """Return deterministic hand-calculated reference fixtures."""
+    resource = files("api581").joinpath("data", _REFERENCE_FIXTURE_RESOURCE)
+    return json.loads(resource.read_text(encoding="utf-8"))
+
+
+def reference_fixture_evidence_hash() -> str:
+    resource = files("api581").joinpath("data", _REFERENCE_FIXTURE_RESOURCE)
+    return sha256(resource.read_bytes()).hexdigest()
+
+
+def calculation_test_modules(identifier: str) -> list[str]:
+    """Return direct test-module references for one registered calculation."""
+    from .catalog import calculation_evidence
+    return list(calculation_evidence(identifier)["software_test_modules"])
+
+
+def calculation_public_test_modules(identifier: str) -> list[str]:
+    """Return test modules that invoke the public ``evaluate`` boundary."""
+    from .catalog import calculation_evidence
+    return list(calculation_evidence(identifier)["direct_public_test_modules"])
+
+
+def calculation_validation_evidence(identifier: str) -> list[ValidationEvidence]:
+    """Return validation-manifest links for one registered calculation ID."""
+    from .catalog import calculation_evidence
+    return calculation_evidence(identifier)["validation_evidence"]
+
+
+__all__ = [
+    "ValidationEvidence", "native_engine_evidence", "native_engine_evidence_hash",
+    "software_test_evidence", "software_test_evidence_hash", "calculation_test_modules",
+    "calculation_public_test_modules",
+    "reference_fixture_evidence", "reference_fixture_evidence_hash",
+    "calculation_validation_evidence",
+]

api581/external_corrosion.py

@@ -0,0 +1,148 @@
+"""External corrosion/CUI rate, coating and Bayesian damage calculations."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, Positive, NonNegative, Fraction, calculation, ensure
+from .thinning import StrengthRatio, strength_ratio, Posterior, posterior, ThinningBase, thinning_base
+
+Driver=Literal["marine_or_cooling_tower","temperate","arid_dry","severe"]
+DRIVERS=("marine_or_cooling_tower","temperate","arid_dry","severe")
+# SI mm/year. External -8 C severe cell contradicts US table; do not silently repair it.
+EXTERNAL=[(-12,(0,0,0,0)),(-8,(.025,0,0,None)),(6,(.127,.076,.025,.254)),(32,(.127,.076,.025,.254)),
+          (71,(.127,.051,.025,.254)),(107,(.025,0,0,.051)),(121,(0,0,0,0))]
+CUI=[(-12,(0,0,0,0)),(-8,(.025,0,0,.076)),(6,(.127,.076,.025,.254)),(32,(.127,.076,.025,.254)),
+     (71,(.254,.127,.051,.508)),(107,(.127,.025,.025,.254)),(135,(.051,.025,0,.254)),(162,(.025,0,0,.127)),(176,(0,0,0,0))]
+
+
+class RateQuery(Model):
+    temperature_k: Positive
+    driver: Driver
+
+
+def interpolate_rate(table,x):
+    t=x.temperature_k-273.15
+    column=DRIVERS.index(x.driver)
+    ensure(table[0][0]-1e-9<=t<=table[-1][0]+1e-9,"Temperature outside source table range; no extrapolation")
+    for temp,values in table:
+        if math.isclose(t,temp,abs_tol=1e-9,rel_tol=0):
+            ensure(values[column] is not None,"Conflicting SI/US source cell requires reconciliation", "ambiguous_source")
+            return values[column]/1000
+    for (a,va),(b,vb) in zip(table,table[1:]):
+        if a<t<b:
+            ensure(va[column] is not None and vb[column] is not None,"Interpolation touches a conflicting source cell", "ambiguous_source")
+            return (va[column]+(vb[column]-va[column])*(t-a)/(b-a))/1000
+    ensure(False,"Unresolved table interpolation")
+
+
+@calculation("damage/external-base-rate", "External corrosion SI base rate", RateQuery,
+             ["Part 2 Table 15.2M; PDF p231"], limitations=["Linear interpolation only within -12..121 C. Severe -8 C cell and adjacent interpolation are disabled due to SI/US mismatch."])
+def external_base_rate(x):
+    return {"base_corrosion_rate_m_year":interpolate_rate(EXTERNAL,x)}
+
+
+@calculation("damage/cui-base-rate", "CUI SI base corrosion rate", RateQuery,
+             ["Part 2 Table 16.2M; PDF p243"], limitations=["Linear interpolation only within -12..176 C; material/service screening separate."])
+def cui_base_rate(x):
+    return {"base_corrosion_rate_m_year":interpolate_rate(CUI,x)}
+
+
+class ExposurePeriod(Model):
+    temperature_k: Positive
+    duration_fraction: Fraction
+
+
+class WeightedRate(Model):
+    mechanism: Literal["external","cui"]
+    driver: Driver
+    periods: list[ExposurePeriod]=Field(min_length=1,max_length=1000)
+
+
+@calculation("damage/external-time-weighted-rate", "Time-weighted external/CUI base rate", WeightedRate,
+             ["Part 2 Tables 15.2M/16.2M note 3"], limitations=["Weights describe operating-time fractions and must sum to one; all period temperatures must lie within the selected source table."])
+def time_weighted_rate(x):
+    ensure(math.isclose(math.fsum(p.duration_fraction for p in x.periods),1,abs_tol=1e-9),"Duration fractions must sum to 1")
+    table=EXTERNAL if x.mechanism=="external" else CUI
+    rates=[interpolate_rate(table,RateQuery(temperature_k=p.temperature_k,driver=x.driver)) for p in x.periods]
+    return {"base_corrosion_rate_m_year":math.fsum(p.duration_fraction*r for p,r in zip(x.periods,rates)),"period_rates_m_year":rates}
+
+
+class RateAdjustment(Model):
+    base_corrosion_rate_m_year: NonNegative
+    water_retaining_design: bool
+    soil_or_water_interface: bool
+
+
+@calculation("damage/external-rate-adjust", "External corrosion design/interface adjustment", RateAdjustment,
+             ["Part 2 eq (2.34); PDF p224"])
+def external_rate_adjust(x):
+    factor=2 if x.water_retaining_design or x.soil_or_water_interface else 1
+    return {"design_interface_factor":factor,"corrosion_rate_m_year":x.base_corrosion_rate_m_year*factor}
+
+
+class CuiAdjustment(RateAdjustment):
+    insulation: Literal["unknown","foamglass","pearlite","fiberglass","mineral_wool","calcium_silicate","asbestos"]
+    complexity: Literal["below_average","average","above_average"]
+    insulation_condition: Literal["below_average","average","above_average"]
+
+
+@calculation("damage/cui-rate-adjust", "CUI insulation/condition/complexity adjustment", CuiAdjustment,
+             ["Part 2 eq (2.51), §16.6.3, Table 16.3; PDF pp234-235,244"])
+def cui_rate_adjust(x):
+    insulation={"foamglass":.75,"pearlite":1}.get(x.insulation,1.25)
+    complexity={"below_average":.75,"average":1,"above_average":1.25}[x.complexity]
+    condition={"below_average":1.25,"average":1,"above_average":.75}[x.insulation_condition]
+    design=2 if x.water_retaining_design or x.soil_or_water_interface else 1
+    return {"insulation_factor":insulation,"complexity_factor":complexity,"condition_factor":condition,"design_interface_factor":design,
+            "corrosion_rate_m_year":x.base_corrosion_rate_m_year*insulation*complexity*condition*design}
+
+
+class CoatingExposure(Model):
+    years_since_thickness_reading: NonNegative
+    coating_age_years: NonNegative
+    coating_quality: Literal["none_or_poor","medium","high"]
+
+
+@calculation("damage/coating-exposure", "Coating-adjusted corrosion exposure time", CoatingExposure,
+             ["Part 2 eqs (2.36)-(2.42),(2.53)-(2.59); PDF pp224,235"])
+def coating_exposure(x):
+    window={"none_or_poor":0,"medium":5,"high":15}[x.coating_quality]
+    credit=min(window,x.coating_age_years)
+    if x.years_since_thickness_reading<x.coating_age_years:
+        credit-=min(window,x.coating_age_years-x.years_since_thickness_reading)
+    credit=min(x.years_since_thickness_reading,max(0,credit))
+    return {"coating_credit_years":credit,"corrosion_exposure_years":x.years_since_thickness_reading-credit}
+
+
+class ExternalAssessment(Model):
+    rate: RateAdjustment
+    coating: CoatingExposure
+    strength: StrengthRatio
+    inspections: Posterior
+
+
+class CuiAssessment(ExternalAssessment):
+    rate: CuiAdjustment
+
+
+def assess(x):
+    rate=cui_rate_adjust(x.rate) if isinstance(x.rate,CuiAdjustment) else external_rate_adjust(x.rate)
+    exposure=coating_exposure(x.coating)
+    wall_loss=rate["corrosion_rate_m_year"]*exposure["corrosion_exposure_years"]/x.strength.starting_thickness_m
+    strength=strength_ratio(x.strength)
+    post=posterior(x.inspections)
+    base=thinning_base(ThinningBase(wall_loss_fraction=wall_loss,strength_ratio=strength["strength_ratio"],posterior=post["posterior_probabilities"]))
+    return {"corrosion_rate_m_year":rate["corrosion_rate_m_year"],**exposure,"wall_loss_fraction":wall_loss,**strength,**post,
+            "reliability_indices":base["reliability_indices"],"weighted_failure_probability":base["weighted_failure_probability"],"damage_factor":base["base_damage_factor"]}
+
+
+@calculation("damage/external-corrosion", "External corrosion Bayesian damage factor", ExternalAssessment,
+             ["Part 2 §15.6.3 eqs (2.34)-(2.50)"], limitations=["Internal-pressure-governed strength path only; eligible material/service, base rate, flow stress and inspection validity supplied. No internal-thinning floor/adjustments applied."])
+def external_assessment(x):
+    return assess(x)
+
+
+@calculation("damage/cui", "Corrosion-under-insulation Bayesian damage factor", CuiAssessment,
+             ["Part 2 §16.6.3 eqs (2.51)-(2.67)"], limitations=["Internal-pressure-governed strength path (2.63) only; the Min/Max discrepancy in source (2.62) is not inferred. Base rate and inspection validity supplied. No internal-thinning floor/adjustments applied.",
+                 "Source STEP 13 references Tables 5.6/5.7, which do not identify prior/conditional probability tables. This implementation explicitly adopts general-thinning Tables 4.5/4.6, consistent with external-corrosion methodology; this interpretation requires independent engineering verification."])
+def cui_assessment(x):
+    return assess(x)