api581-engine 0.1.4__py3-none-any.whl

api581/tank_integrated.py

@@ -0,0 +1,51 @@
+"""Geometry/soil-to-financial-risk composition for a single AST bottom."""
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, REGISTRY, calculation, finite_tree
+from .tank_source import BottomSource, bottom_source
+from .tank_environment import Location, GroundwaterArrival, groundwater_arrival
+from .tank_financial import TankRepairBasis, DamageBasis, BottomFinancial, BottomAssessment, bottom_assessment
+from .tank_environment import Hole
+
+
+class BottomEconomics(Model):
+    repair: TankRepairBasis
+    outage_multiplier: Positive
+    override_outage_days: dict[Hole, NonNegative] = Field(default_factory=dict)
+    production_cost_per_day: NonNegative
+    cost_by_location_per_bbl: dict[Location, NonNegative]
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+    cost_basis: str = Field(min_length=1, max_length=500)
+    fraction_leaving_dike: Fraction
+    fraction_on_site: Fraction
+    fraction_off_site: Fraction
+
+
+class BottomIntegrated(DamageBasis):
+    source: BottomSource
+    distance_to_groundwater_m: NonNegative
+    economics: BottomEconomics
+
+
+@calculation("tank/bottom-integrated-assessment", "AST bottom geometry and soil through source, financial consequence and annual risk", BottomIntegrated,
+    [*REGISTRY["tank/bottom-source-assessment"].references,"Part3 eq(3.244); PDF p601",
+     *REGISTRY["tank/bottom-risk-assessment"].references],
+    origin="api581_composition_with_supplied_damage_and_valuation",
+    limitations=[*REGISTRY["tank/bottom-source-assessment"].limitations,
+                 *REGISTRY["tank/bottom-risk-assessment"].limitations,
+                 "Computes source inventory/rates/volumes, summed table GFF and seepage arrival from the same geometry/soil request. DF applicability and monetary qualification are external supplied assumptions. Single bottom only; no shell, whole-tank common-cause or digital-twin sensor assimilation inferred."])
+def integrated(x):
+    source = bottom_source(x.source)
+    finite_tree(source)
+    arrival = groundwater_arrival(GroundwaterArrival(distance_to_groundwater_m=x.distance_to_groundwater_m,
+        seepage_velocity_m_day=source["seepage_velocity_m_day"]))
+    financial = BottomFinancial(**x.economics.model_dump(),
+        generic_frequency_by_hole_per_year=source["generic_frequency_by_hole_per_year"],
+        generic_frequency_source="Part2 Table3.1; total eq3.208; computed within same bottom source",
+        tank_diameter_m=x.source.tank_diameter_m,
+        leaked_volume_by_hole_bbl={h:source["released_volume_by_hole_bbl"][h] for h in ("small","medium","large")},
+        total_tank_volume_bbl=source["available_volume_bbl"],detection_time_days=source["detection_time_days"],
+        groundwater_arrival_time_days=arrival["arrival_time_days"])
+    result = bottom_assessment(BottomAssessment(financial=financial,management_score=x.management_score,
+        total_damage_factor=x.total_damage_factor,damage_factor_source=x.damage_factor_source))
+    return {**source,**result,"groundwater_arrival_time_days":arrival["arrival_time_days"],
+        "integration_scope":"bottom_geometry_soil_source_financial_risk_with_supplied_df"}

api581/tank_shell.py

@@ -0,0 +1,141 @@
+"""AST diked pool effects and continuous-shell Level2 area/risk composition."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, REGISTRY, calculation, ensure, finite_tree
+from .pool_fire import PoolConsequence, pool_consequence
+from .level2_summary import FlammableCase, flammable_case
+from .toxic_level2 import ToxicCloudArea, ToxicCase, toxic_case
+from .tank_environment import HOLES, FrequencyWeights, _weights
+from .tank_financial import TankComponent, generic_frequency, DamageBasis, ShellFinancial, ShellAssessment, shell_assessment
+from .tank_source import ShellSource, shell_source
+from .tank_integrated import BottomEconomics
+
+DikeBasis = Literal["burning_pool_area", "burning_and_consequence_area"]
+
+
+class DikedPool(PoolConsequence):
+    site_maximum_area_m2: Positive | None = None
+    dike_area_m2: Positive
+    dike_limit_basis: DikeBasis
+
+
+@calculation("tank/diked-pool-consequence", "AST pool radiation with explicit dike-area interpretation", DikedPool,
+    ["Part3 §6.7.2; PDF p596", *REGISTRY["effects/pool-fire-consequence"].references],
+    origin="api581_pool_chain_with_explicit_ast_dike_interpretation",
+    limitations=[*REGISTRY["effects/pool-fire-consequence"].limitations,
+        "Source says pool fire area must not exceed dike area without distinguishing burning pool from radiation consequence. Required burning_pool_area caps physical pool before radiation; burning_and_consequence_area additionally clips reported consequence areas numerically. Neither is an authorized erratum. Raw radiation areas and threshold separations remain separately labeled; numerical clipping is not a spatial dike intersection. No ignition/hole weighting."])
+def diked_pool(x):
+    cap = min(x.dike_area_m2, x.site_maximum_area_m2) if x.site_maximum_area_m2 is not None else x.dike_area_m2
+    fields = {k:getattr(x,k) for k in PoolConsequence.model_fields}
+    fields["site_maximum_area_m2"] = cap
+    result = pool_consequence(PoolConsequence(**fields))
+    raw_equipment, raw_personnel = result["equipment_area_m2"], result["personnel_area_m2"]
+    equipment = min(raw_equipment,x.dike_area_m2) if x.dike_limit_basis == "burning_and_consequence_area" else raw_equipment
+    personnel = min(raw_personnel,x.dike_area_m2) if x.dike_limit_basis == "burning_and_consequence_area" else raw_personnel
+    distances = {"unclipped_"+k:result.pop(k) for k in ("personnel_safe_surface_distance_m","equipment_safe_surface_distance_m")}
+    return {**result,**distances,"equipment_area_m2":equipment,"personnel_area_m2":personnel,
+        "unclipped_equipment_area_m2":raw_equipment,"unclipped_personnel_area_m2":raw_personnel,
+        "effective_pool_area_limit_m2":cap,"dike_area_m2":x.dike_area_m2,"dike_limit_basis":x.dike_limit_basis,
+        "equipment_area_clipped":equipment < raw_equipment,"personnel_area_clipped":personnel < raw_personnel}
+
+
+class ShellCase(FlammableCase):
+    release_type: Literal["continuous"] = "continuous"
+    toxic_components: list[ToxicCloudArea] = Field(max_length=100)
+    toxic_applicability: Literal["evaluated","not_applicable"]
+    toxic_applicability_source: str = Field(min_length=1,max_length=1000)
+    dike_area_m2: Positive
+    burning_pool_area_m2: NonNegative
+    pool_dike_limit_basis: DikeBasis
+
+
+_AREA_LIMITS = [
+    "AST shell release type is continuous, including rupture. Raw event probabilities and flammable/toxic footprints are externally qualified. All five canonical flammable events required; inapplicable fireball branch zero. Shared non-ignition probability weights toxic once; empty toxic components require explicit not-applicable basis.",
+    "NFNT is not determined for AST per §6.10 and is absent from the request. Pool burning area must fit dike; explicit dike interpretation and raw footprint provenance are required. Burning area0 requires zero pool radiation footprint; no circular radiation area is silently clipped after weighting.",
+]
+
+
+@calculation("tank/shell-level2-case", "AST continuous shell event-weighted flammable and toxic areas", ShellCase,
+    ["Part3 §§6.5,6.7.2,6.8-6.11; PDF pp596,598", "Part3 eqs(3.176)-(3.177),(3.188)"],
+    origin="api581_ast_conditional_event_composition",limitations=_AREA_LIMITS)
+def shell_case(x):
+    ensure(x.toxic_applicability_source.strip(), "Toxic applicability source must be nonblank")
+    ensure(bool(x.toxic_components) == (x.toxic_applicability == "evaluated"), "Toxic components must match applicability")
+    ensure(x.burning_pool_area_m2 <= x.dike_area_m2, "Burning pool exceeds dike area", "dike_area_exceeded")
+    pool = next((o for o in x.outcomes if o.event == "pool_fire"),None)
+    pool_areas = [] if pool is None else [pool.equipment_area_m2,pool.personnel_area_m2]
+    if x.correlated_jet_pool is not None:
+        pool_areas += [x.correlated_jet_pool.pool_equipment_area_m2,x.correlated_jet_pool.pool_personnel_area_m2]
+    ensure(x.burning_pool_area_m2 > 0 or all(a == 0 for a in pool_areas), "No burning pool requires zero pool footprints")
+    if x.pool_dike_limit_basis == "burning_and_consequence_area":
+        ensure(all(a <= x.dike_area_m2 for a in pool_areas), "Pool consequence area exceeds selected literal dike cap", "dike_area_exceeded")
+    flame = flammable_case(FlammableCase(**x.model_dump(include=set(FlammableCase.model_fields))))
+    toxic = toxic_case(ToxicCase(components=x.toxic_components,non_ignition_probability=x.non_ignition_probability))["personnel_area_m2"] if x.toxic_components else 0.
+    return {**flame,"toxic_personnel_area_m2":toxic,"nfnt_status":"not_determined_for_ast"}
+
+
+class ShellSummary(Model):
+    cases: list[ShellCase] = Field(min_length=4,max_length=4)
+
+
+@calculation("tank/shell-level2-summary", "AST four-hole GFF-weighted flammable plus toxic final areas", ShellSummary,
+    ["Part3 §§6.10-6.11,eqs(3.178)-(3.179),(3.191),(3.202)-(3.204); PDF pp560,567,572-573,598"],
+    origin="api581_ast_level2_mechanism_composition",limitations=_AREA_LIMITS+[
+        "Exactly four canonical holes on one common dike basis. Uses COURSE-1-10 Table3.1 frequencies with eq3.208 total. Mechanism GFF averages precede final equipment=flammable and personnel=flammable+toxic; this is Level2 additive composition with NFNT absent, not Level1 maximum selection. No DF in GFF averaging."])
+def shell_summary(x):
+    ensure({c.hole for c in x.cases} == set(HOLES), "Exactly four distinct canonical holes required")
+    ensure(len({(c.dike_area_m2,c.pool_dike_limit_basis) for c in x.cases}) == 1, "Four cases must share dike area and interpretation")
+    gff = generic_frequency(TankComponent(component_type="COURSE-1-10"))
+    weights = _weights(FrequencyWeights(generic_frequency_by_hole_per_year=gff["by_hole_per_year"]))
+    cases = {c.hole:shell_case(c) for c in x.cases}
+    names = ("flammable_equipment_area_m2","flammable_personnel_area_m2","toxic_personnel_area_m2")
+    values = {name:math.fsum(weights[h]*cases[h][name] for h in HOLES) for name in names}
+    personnel = values["flammable_personnel_area_m2"]+values["toxic_personnel_area_m2"]
+    return {**values,"equipment_area_m2":values["flammable_equipment_area_m2"],"personnel_area_m2":personnel,
+        "consequence_area_m2":max(values["flammable_equipment_area_m2"],personnel),
+        "generic_frequency_per_year":gff["total_per_year"],"nfnt_status":"not_determined_for_ast",
+        **{"by_hole_"+name:{h:cases[h][name] for h in HOLES} for name in names}}
+
+
+class ShellEconomics(BottomEconomics):
+    equipment_cost_per_m2: NonNegative
+    population_density_per_m2: NonNegative
+    cost_per_injury: NonNegative
+
+
+class ShellIntegrated(DamageBasis):
+    source: ShellSource
+    cases: list[ShellCase] = Field(min_length=4,max_length=4)
+    economics: ShellEconomics
+
+
+@calculation("tank/shell-integrated-assessment", "AST shell source, supplied event footprints, financial consequence and annual risk", ShellIntegrated,
+    [*REGISTRY["tank/shell-source-assessment"].references,*REGISTRY["tank/shell-level2-summary"].references,
+     *REGISTRY["tank/shell-risk-assessment"].references],
+    origin="api581_ast_source_with_qualified_event_footprints_and_supplied_damage",
+    limitations=[*REGISTRY["tank/shell-source-assessment"].limitations,*REGISTRY["tank/shell-level2-summary"].limitations,
+        *REGISTRY["tank/shell-risk-assessment"].limitations,
+        "Computes source/GFF/environment from one geometry request and inserts event/GFF-weighted AST areas into financial risk. Footprints and event probabilities remain external and must be qualified for this computed source. Does not infer dispersion, EOS, source-to-footprint consistency or whole-tank spatial overlap. Dry source requires zero flammable/toxic footprints for every hole."])
+def shell_integrated(x):
+    source = shell_source(x.source)
+    finite_tree(source)
+    areas = shell_summary(ShellSummary(cases=x.cases))
+    finite_tree(areas)
+    if not source["course_wet"]:
+        for case in x.cases:
+            ensure(case.burning_pool_area_m2 == 0, "Dry source cannot have a burning pool")
+            ensure(all(o.equipment_area_m2 == o.personnel_area_m2 == 0 for o in case.outcomes), "Dry source cannot have flammable footprints")
+            ensure(not case.toxic_components or all(c.cloud_area_m2 == 0 for c in case.toxic_components), "Dry source cannot have toxic footprints")
+            if case.correlated_jet_pool is not None:
+                ensure(all(getattr(case.correlated_jet_pool,k) == 0 for k in (
+                    "jet_equipment_area_m2","jet_personnel_area_m2","pool_equipment_area_m2","pool_personnel_area_m2")),
+                    "Dry source cannot have correlated footprints")
+    financial = ShellFinancial(**x.economics.model_dump(),
+        generic_frequency_by_hole_per_year=source["generic_frequency_by_hole_per_year"],
+        generic_frequency_source="Part2 Table3.1; sum eq3.208; computed within same shell source",
+        released_volume_by_hole_bbl=source["released_volume_by_hole_bbl"],
+        equipment_area_m2=areas["equipment_area_m2"],personnel_area_m2=areas["personnel_area_m2"])
+    risk = shell_assessment(ShellAssessment(financial=financial,management_score=x.management_score,
+        total_damage_factor=x.total_damage_factor,damage_factor_source=x.damage_factor_source))
+    return {**source,**areas,**risk,"integration_scope":"shell_geometry_source_supplied_event_footprints_financial_risk"}

api581/tank_source.py

@@ -0,0 +1,152 @@
+"""AST tabulated hole selection and geometry-to-release source composition."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, Positive, NonNegative, Fraction, calculation, ensure
+from . import tank as t
+from .tank_financial import TankComponent, generic_frequency
+
+HOLES = ("small", "medium", "large", "rupture")
+
+
+class ShellHoles(Model):
+    tank_diameter_m: Positive
+
+
+class BottomHoles(ShellHoles):
+    has_release_prevention_barrier: bool
+
+
+def _holes(diameters):
+    areas = {h: math.pi/4*d*d for h,d in zip(HOLES,diameters)}
+    ensure(all(a > 0 or d == 0 for a,d in zip(areas.values(),diameters)), "Hole area underflow", "numerical_failure")
+    return {"diameter_by_hole_m": dict(zip(HOLES,diameters)), "area_by_hole_m2": areas}
+
+
+@calculation("tank/shell-hole-sizes", "AST shell-course representative hole diameters and areas", ShellHoles,
+    ["Part3 Tables6.3/6.3M; PDF p606"], limitations=[
+        "Small3.175mm, medium6.35mm, large50.8mm, rupture=tank diameter/4. This selects representative holes, not measured-hole classification. Rupture diameter is a source convention, not validation of tank-diameter/4 orifice hydraulics."])
+def shell_holes(x):
+    ensure(x.tank_diameter_m/4 > 0, "Rupture diameter underflow", "numerical_failure")
+    return _holes((.003175,.00635,.0508,x.tank_diameter_m/4))
+
+
+@calculation("tank/bottom-hole-sizes", "AST bottom representative hole diameters and areas", BottomHoles,
+    ["Part3 Tables6.4/6.4M; PDF pp606-607"], limitations=[
+        "Small3.175mm with RPB or12.7mm without, medium/large zero, rupture=tank diameter/4. Printed SI Table6.4M rupture row shows only Yes; US Table6.4 explicitly covers Yes/No under shared tank-diameter/4 formula. No-RPB rupture follows that US row converted to SI, not an authorized SI erratum. No rupture flow/hole count inferred from Table6.5."])
+def bottom_holes(x):
+    ensure(x.tank_diameter_m/4 > 0, "Rupture diameter underflow", "numerical_failure")
+    return _holes((.003175 if x.has_release_prevention_barrier else .0127,0.,0.,x.tank_diameter_m/4))
+
+
+class ShellSource(Model):
+    tank_diameter_m: Positive
+    fill_height_m: NonNegative
+    course_index: int = Field(ge=1,strict=True)
+    course_height_m: Positive
+    fluid: t.Fluid
+    diameter_boundary_basis: Literal["printed_3_17_mm","inch_0_125"]
+    discharge_coefficient: Fraction = .61
+    gravity_m_s2: Positive = 9.81
+
+
+class BottomSource(Model):
+    tank_diameter_m: Positive
+    fill_height_m: NonNegative
+    fluid: t.Fluid
+    soil: t.Soil
+    water_density_kg_m3: Positive
+    water_dynamic_viscosity_pa_s: Positive
+    foundation: Literal["concrete_asphalt","other"]
+    has_release_prevention_barrier: bool
+    detection_overlap_basis: Literal["foundation_priority","barrier_priority"] | None = None
+    transition_hole_basis: Literal["api581_printed","per_hole_scaled"]
+    soil_contact_factor: Positive = .21
+    gravity_m_s2: Positive = 9.81
+
+
+def _release_outputs(holes,inventory,rates,detection,volumes,component_type):
+    gff = generic_frequency(TankComponent(component_type=component_type))
+    return {**holes,**inventory,"generic_frequency_by_hole_per_year":gff["by_hole_per_year"],
+        "generic_total_per_year":gff["total_per_year"],"printed_generic_total_per_year":gff["printed_total_per_year"],
+        "generic_total_basis":gff["total_basis"],
+        "native_rate_by_hole_bbl_day":{h:rates[h]["native_rate_bbl_day"] if rates[h] is not None else None for h in HOLES},
+        "mass_rate_by_hole_kg_s":{h:rates[h]["mass_rate_kg_s"] if rates[h] is not None else None for h in HOLES},
+        "detection_time_by_hole_days":detection,
+        "release_duration_by_hole_days":{h:volumes[h]["release_duration_days"] for h in HOLES},
+        "released_volume_by_hole_bbl":{h:volumes[h]["released_volume_bbl"] for h in HOLES},
+        "released_volume_by_hole_m3":{h:volumes[h]["released_volume_m3"] for h in HOLES},
+        "released_mass_by_hole_kg":{h:volumes[h]["released_mass_kg"] for h in HOLES},
+        "release_type":"continuous"}
+
+
+_SOURCE_LIMITS = [
+    "Uses representative Table6.1M liquid properties, constant head and C13=6.29bbl/m3. No operating-temperature EOS, connected inventory or transient drainage. Source mass=Bbl printing is not used as kg: mass is volume*density, the explicitly qualified dimensional interpretation.",
+    "Table3.1 hole frequencies use eq3.208 summed total, with printed total returned separately. One component only; no whole-tank course summation, area consequences or damage applicability inferred. AST release type remains continuous. No generic detection/isolation reduction factors.",
+]
+
+
+@calculation("tank/shell-source-assessment", "Compose AST shell holes, head, inventory, rates and released quantities", ShellSource,
+    ["Part3 §§6.1-6.7,Tables6.1M/6.3M,eqs(3.208)-(3.209),(3.214)-(3.227); PDF pp592-597,604,606"], limitations=_SOURCE_LIMITS+[
+        "Equal-height courses; source at course lower edge. Above-fill courses use physical dry inventory/head0. Shell3.17mm vs3.175mm detection ambiguity requires explicit boundary basis. Eq3.209 evaluated for all four representative holes as STEP3.3 specifies; nominal rupture rate is a printed constant-head convention, not validated catastrophic-rupture hydraulics. Rupture uses full above-course inventory with null duration/detection; no invented rupture duration."])
+def shell_source(x):
+    properties = t.fluid_table(t.FluidLookup(fluid=x.fluid))
+    rho = properties["liquid_density_kg_m3"]
+    holes = shell_holes(ShellHoles(tank_diameter_m=x.tank_diameter_m))
+    inventory = t.shell_inventory(t.ShellInventory(tank_diameter_m=x.tank_diameter_m,
+        fill_height_m=x.fill_height_m,liquid_density_kg_m3=rho,course_index=x.course_index,course_height_m=x.course_height_m))
+    ensure(all(math.isfinite(v) for v in inventory.values()), "Shell inventory overflow", "numerical_failure")
+    rates, detection, volumes = {}, {}, {}
+    for h in HOLES:
+        diameter = holes["diameter_by_hole_m"][h]
+        rates[h] = t.shell_flow(t.ShellFlow(hole_diameter_m=diameter,liquid_head_m=inventory["available_liquid_head_m"],
+            liquid_density_kg_m3=rho,discharge_coefficient=x.discharge_coefficient,gravity_m_s2=x.gravity_m_s2))
+        ensure(all(math.isfinite(v) for v in rates[h].values()), "Shell flow overflow", "numerical_failure")
+        detection[h] = None if h == "rupture" else t.shell_detection(t.ShellDetection(
+            hole_diameter_m=diameter,diameter_boundary_basis=x.diameter_boundary_basis))["detection_time_days"]
+        volumes[h] = t.release_volume(t.ReleaseVolume(release_case="rupture" if h == "rupture" else "leak",
+            native_rate_bbl_day=rates[h]["native_rate_bbl_day"],available_volume_m3=inventory["available_volume_m3"],
+            liquid_density_kg_m3=rho,detection_time_days=detection[h] if detection[h] is not None else 0))
+    return {**_release_outputs(holes,inventory,rates,detection,volumes,"COURSE-1-10"),
+        "liquid_density_kg_m3":rho,"source_scope":"single_shell_course"}
+
+
+@calculation("tank/bottom-source-assessment", "Compose AST soil, holes, inventory, seepage and released quantities", BottomSource,
+    ["Part3 §§6.1-6.7,Tables6.1M/6.2M/6.4/6.4M/6.5,eqs(3.205)-(3.212),(3.219)-(3.230); PDF pp592-598,604-607"], limitations=_SOURCE_LIMITS+[
+        "Soil arithmetic mean preserves reversed printed bounds; explicit water reference properties required. RPB small-hole head.0762m when filled; empty tank zero. SI C37 threshold retained despite SI/US mismatch. Transition count omission requires explicit printed vs per-hole-scaled basis. No-RPB rupture diameter follows complete US Table6.4 row; SI rupture row is incomplete.",
+        "Medium/large holes have zero count/flow. Table6.5 gives no rupture count, so rupture flow and duration are null; rupture volume is whole inventory per eq3.230. Bottom detection with concrete/asphalt AND RPB requires explicit priority. Count outside30.5-91.4m is flagged, not qualified by this composition."])
+def bottom_source(x):
+    properties = t.fluid_table(t.FluidLookup(fluid=x.fluid))
+    rho = properties["liquid_density_kg_m3"]
+    soil = t.soil_table(t.SoilLookup(soil=x.soil))
+    water = t.water_conductivity(t.WaterConductivity(**{k:soil[k] for k in (
+        "printed_lower_bound_cm_s","printed_upper_bound_cm_s")}))["water_hydraulic_conductivity_m_day"]
+    conductivity = t.fluid_conductivity(t.FluidConductivity(water_hydraulic_conductivity_m_day=water,
+        liquid_density_kg_m3=rho,dynamic_viscosity_pa_s=properties["dynamic_viscosity_pa_s"],
+        water_density_kg_m3=x.water_density_kg_m3,water_dynamic_viscosity_pa_s=x.water_dynamic_viscosity_pa_s))["product_hydraulic_conductivity_m_day"]
+    ensure(math.isfinite(conductivity), "Product conductivity overflow", "numerical_failure")
+    velocity = t.seepage(t.Seepage(product_hydraulic_conductivity_m_day=conductivity,porosity=soil["porosity"]))["seepage_velocity_m_day"]
+    holes = bottom_holes(BottomHoles(tank_diameter_m=x.tank_diameter_m,
+        has_release_prevention_barrier=x.has_release_prevention_barrier))
+    counts = t.bottom_hole_count(t.BottomHoleCount(tank_diameter_m=x.tank_diameter_m))
+    inventory = t.bottom_inventory(t.BottomInventory(tank_diameter_m=x.tank_diameter_m,fill_height_m=x.fill_height_m,liquid_density_kg_m3=rho))
+    ensure(all(math.isfinite(v) for v in inventory.values()), "Bottom inventory overflow", "numerical_failure")
+    detect = t.bottom_detection(t.BottomDetection(foundation=x.foundation,
+        has_release_prevention_barrier=x.has_release_prevention_barrier,overlap_basis=x.detection_overlap_basis))
+    rates, detection, volumes = {}, {}, {}
+    for h in HOLES:
+        rates[h] = None if h == "rupture" else t.bottom_flow(t.BottomFlow(hole_diameter_m=holes["diameter_by_hole_m"][h],
+            liquid_height_m=x.fill_height_m,product_hydraulic_conductivity_m_day=conductivity,liquid_density_kg_m3=rho,
+            number_of_holes=counts[h+"_hole_count"],has_release_prevention_barrier=x.has_release_prevention_barrier,
+            transition_hole_basis=x.transition_hole_basis,soil_contact_factor=x.soil_contact_factor,gravity_m_s2=x.gravity_m_s2))
+        rate = 0 if rates[h] is None else rates[h]["native_rate_bbl_day"]
+        ensure(math.isfinite(rate), "Bottom flow overflow", "numerical_failure")
+        detection[h] = None if h == "rupture" else detect["detection_time_days"]
+        volumes[h] = t.release_volume(t.ReleaseVolume(release_case="rupture" if h == "rupture" else "leak",
+            native_rate_bbl_day=rate,available_volume_m3=inventory["available_volume_m3"],liquid_density_kg_m3=rho,
+            detection_time_days=detect["detection_time_days"]))
+    return {**_release_outputs(holes,inventory,rates,detection,volumes,"TANKBOTTOM"),**counts,
+        "liquid_density_kg_m3":rho,"product_hydraulic_conductivity_m_day":conductivity,"seepage_velocity_m_day":velocity,
+        "bottom_flow_equation":rates["small"]["equation"],"applied_small_hole_multiplier":rates["small"]["applied_hole_multiplier"],
+        "detection_time_days":detect["detection_time_days"],"detection_selected_basis":detect["selected_basis"],
+        "source_scope":"single_tank_bottom"}

api581/tank_thinning.py

@@ -0,0 +1,204 @@
+"""2016 AST-bottom thinning: dedicated Art equation, table and adjustments."""
+from bisect import bisect_left
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, REGISTRY, calculation, ensure, finite_tree
+from .tank_corrosion import BottomCorrosion, assessment as corrosion_assessment
+from .tank_source import BottomSource
+from .tank_integrated import BottomEconomics, BottomIntegrated, integrated
+
+Grade = Literal["a","b","c","d","e"]
+Lookup = Literal["exact_rows_only","linear_between_rows","conservative_upper_row"]
+_ART = tuple(i/20 for i in range(21))
+# Column order is E,D,C,B,A, as printed in Table4.7 (not the text's4.8).
+_ROWS = (
+    (.1,.1,.1,.1,.1),(4,1,.5,.4,.4),(14,3,1,.7,.7),(32,8,2,1,1),
+    (56,18,6,2,1),(87,32,11,4,3),(125,53,21,9,6),(170,80,36,16,12),
+    (222,115,57,29,21),(281,158,86,47,36),(347,211,124,73,58),
+    (420,273,173,109,89),(500,346,234,158,133),(587,430,309,222,192),
+    (681,527,401,305,270),(782,635,510,409,370),(890,757,638,538,498),
+    (1005,893,789,696,658),(1126,1044,963,888,856),(1255,1209,1163,1118,1098),
+    (1390,1390,1390,1390,1390))
+
+
+class BottomMinimumThickness(Model):
+    release_prevention_barrier: bool
+    thickness_basis: Literal["api581_2016_default","documented_owner_method"]
+    owner_minimum_thickness_m: Positive | None = None
+    owner_method_basis: str | None = None
+
+
+@calculation("tank/bottom-minimum-thickness", "AST floor minimum thickness for thinning calculation", BottomMinimumThickness,
+    ["Part2 §4.5.7 STEP5(3)-(4); PDF p153"],limitations=[
+        "Historical 2016 source defaults0.1in without RPB and0.05in with RPB converted exactly to SI. Owner documented alternate method permitted. Not current API653 acceptance, design-code compliance or FFS verification."])
+def minimum_thickness(x):
+    if x.thickness_basis == "api581_2016_default":
+        ensure(x.owner_minimum_thickness_m is None and x.owner_method_basis is None,"Default thickness cannot have owner override")
+        value = .00127 if x.release_prevention_barrier else .00254
+    else:
+        ensure(x.owner_minimum_thickness_m is not None and x.owner_method_basis is not None and bool(x.owner_method_basis.strip()),"Owner thickness requires value and documented method")
+        value = x.owner_minimum_thickness_m
+    return {"minimum_thickness_m":value,"thickness_basis":x.thickness_basis}
+
+
+class BottomWallParameter(Model):
+    starting_thickness_m: Positive
+    corrosion_rate_m_year: NonNegative
+    elapsed_years: NonNegative
+    minimum_thickness_m: Positive
+    corrosion_allowance_m: NonNegative
+
+
+@calculation("tank/bottom-wall-parameter", "AST floor remaining thickness and Art parameter", BottomWallParameter,
+    ["Part2 §4.5.7 STEP6(1),eq(2.12); PDF p153"],limitations=[
+        "Art=max(1-(starting_thickness-rate*elapsed)/(minimum_thickness+corrosion_allowance),0). This is not non-AST fractional wall loss. Starting thickness and elapsed time must refer to same qualified baseline. Negative predicted remaining thickness is returned diagnostically; no clamp to hide penetration. Art>1 is outside the damage table and rejected by subsequent lookup."])
+def wall_parameter(x):
+    loss = x.corrosion_rate_m_year*x.elapsed_years
+    remaining = x.starting_thickness_m-loss
+    denominator = x.minimum_thickness_m+x.corrosion_allowance_m
+    finite_tree([loss,remaining,denominator])
+    art = max(1-remaining/denominator,0.)
+    finite_tree(art)
+    return {"art_parameter":art,"predicted_remaining_thickness_m":remaining,"predicted_wall_loss_m":loss,
+        "reference_thickness_m":denominator,"at_or_below_minimum_thickness":remaining <= x.minimum_thickness_m,
+        "predicted_penetration":remaining <= 0}
+
+
+class BottomInspectionSelection(Model):
+    eligible_inspection_grades: list[Grade] = Field(max_length=10000)
+    eligibility_basis: str = Field(min_length=1)
+
+
+@calculation("tank/bottom-inspection-selection", "Select one AST floor inspection credit", BottomInspectionSelection,
+    ["Part2 §§4.5.5-4.5.6,Table4.7; PDF pp151-152,163"],limitations=[
+        "Only best effectiveness of eligible inspections is credited, never stacked or Bayesian-upgraded. Empty list/E gives no credit. Caller qualifies actual inspection effectiveness under Annex2.C.5 and inclusion in baseline-to-assessment period; furnished-to-measured baseline reset does not preserve earlier inspection credit automatically."])
+def inspection_selection(x):
+    ensure(bool(x.eligibility_basis.strip()),"Inspection eligibility basis must not be blank")
+    grade = min(x.eligible_inspection_grades,default="e")
+    return {"selected_inspection_grade":grade,"credited_inspection_count":0 if grade == "e" else 1,
+        "eligible_inspection_count":len(x.eligible_inspection_grades)}
+
+
+class BottomBaseDamage(Model):
+    art_parameter: NonNegative
+    inspection_grade: Grade
+    lookup_policy: Lookup
+
+
+@calculation("tank/bottom-thinning-base", "AST floor tabulated base thinning damage factor", BottomBaseDamage,
+    ["Part2 §4.5.7 STEP13,Table4.7; PDF pp155,163"],limitations=[
+        "Uses all21x5 printed cells. STEP13 calls it Table4.8, but actual AST table is4.7; actual4.8 is online monitoring. Table covers0<=Art<=1. No extrapolation or terminal-row saturation for Art>1. Between-row handling is explicit owner numerical policy: linear, upper-row conservative, or exact-only; source gives no explicit interpolation instruction. Inspection columns assume at most one credited inspection."])
+def base_damage(x):
+    ensure(x.art_parameter <= 1,"AST Art exceeds1; predicted penetration is outside tabulated damage domain", "ast_damage_table_exceeded")
+    i = bisect_left(_ART,x.art_parameter)
+    column = "edcba".index(x.inspection_grade)
+    if _ART[i] == x.art_parameter:
+        lo = hi = i
+        weight = 0.
+        value = float(_ROWS[i][column])
+    else:
+        ensure(x.lookup_policy != "exact_rows_only","Art lies between table rows; choose qualified interpolation policy", "ast_damage_between_rows")
+        lo, hi = i-1, i
+        weight = (x.art_parameter-_ART[lo])/(_ART[hi]-_ART[lo])
+        value = float(_ROWS[hi][column]) if x.lookup_policy == "conservative_upper_row" else _ROWS[lo][column]+weight*(_ROWS[hi][column]-_ROWS[lo][column])
+    return {"base_damage_factor":value,"lower_art_row":_ART[lo],"upper_art_row":_ART[hi],
+        "interpolation_weight":weight,"lookup_policy":x.lookup_policy}
+
+
+class BottomAdjustments(Model):
+    construction: Literal["welded","riveted"]
+    maintained_per_api653: bool
+    settlement_category: Literal["exceeds_api653","meets_api653","never_evaluated","concrete_no_settlement"]
+
+
+@calculation("tank/bottom-thinning-adjustment-factors", "AST floor construction maintenance and settlement factors", BottomAdjustments,
+    ["Part2 §4.5.7 STEP15(4)-(6); PDF p156"],limitations=[
+        "Owner qualifies actual construction, historical API653 maintenance and settlement category. Factors are not a structural settlement assessment. Online monitoring for AST-bottom corrosion uses other-mechanism table value1 in integrated APIs; no invented monitoring credit."])
+def adjustment_factors(x):
+    return {"welded_construction_factor":1. if x.construction == "welded" else 10.,
+        "maintenance_factor":1. if x.maintained_per_api653 else 5.,
+        "settlement_factor":{"exceeds_api653":2.,"meets_api653":1.,"never_evaluated":1.5,"concrete_no_settlement":1.}[x.settlement_category]}
+
+
+class BottomThinningBasis(Model):
+    starting_thickness_m: Positive
+    elapsed_years: NonNegative
+    baseline_basis: str = Field(min_length=1)
+    corrosion_allowance_m: NonNegative
+    minimum_thickness: BottomMinimumThickness
+    inspections: BottomInspectionSelection
+    lookup_policy: Lookup
+    adjustments: BottomAdjustments
+
+
+class BottomThinning(BottomThinningBasis):
+    corrosion_rate_m_year: NonNegative
+    corrosion_rate_basis: str = Field(min_length=1)
+
+
+def _thinning(basis, rate):
+    ensure(bool(basis.baseline_basis.strip()),"Thickness/time baseline basis must not be blank")
+    minimum = minimum_thickness(basis.minimum_thickness)
+    wall = wall_parameter(BottomWallParameter(starting_thickness_m=basis.starting_thickness_m,corrosion_rate_m_year=rate,
+        elapsed_years=basis.elapsed_years,minimum_thickness_m=minimum["minimum_thickness_m"],corrosion_allowance_m=basis.corrosion_allowance_m))
+    selected = inspection_selection(basis.inspections)
+    base = base_damage(BottomBaseDamage(art_parameter=wall["art_parameter"],inspection_grade=selected["selected_inspection_grade"],lookup_policy=basis.lookup_policy))
+    factors = adjustment_factors(basis.adjustments)
+    value = base["base_damage_factor"]*factors["welded_construction_factor"]*factors["maintenance_factor"]*factors["settlement_factor"]
+    finite_tree(value)
+    return {**minimum,**wall,**selected,**base,**factors,"thinning_damage_factor":max(value,.1),"online_monitoring_factor":1.}
+
+
+@calculation("tank/bottom-thinning-assessment", "AST floor dedicated thinning damage assessment", BottomThinning,
+    ["Part2 §4.5.7,eqs(2.12),(2.23),Tables4.7-4.8; PDF pp152-156,163-164"],limitations=[
+        "Carbon-steel unlined AST bottom with qualified supplied net corrosion rate. Uses dedicated table, not pressure strength-ratio/Bayesian non-AST equations. One inspection credit. Injection/deadleg factors1 as non-piping; monitoring1 for other-corrosion-mechanism row. No automatic baseline reset, coating/lining credit, variable corrosion history or all-mechanism DF. Minimum-thickness flag is diagnostic, not acceptance/FFS."])
+def thinning_assessment(x):
+    ensure(bool(x.corrosion_rate_basis.strip()),"Corrosion-rate basis must not be blank")
+    return _thinning(x,x.corrosion_rate_m_year)
+
+
+class BottomCorrosionThinning(Model):
+    corrosion: BottomCorrosion
+    thinning: BottomThinningBasis
+
+
+@calculation("tank/bottom-corrosion-thinning-assessment", "AST floor two-sided corrosion through thinning damage", BottomCorrosionThinning,
+    [*REGISTRY["tank/bottom-corrosion-assessment"].references,*REGISTRY["tank/bottom-thinning-assessment"].references],
+    origin="api581_composition",limitations=[
+        "Carbon-steel unlined AST floor only. Comparable baseline corrosion rates and provenance required; do not multiply already-corrected measured net rates again. RPB resistivity override and CP inspection gate enforced. Temperature and minimum-rate policies remain explicit.",
+        *REGISTRY["tank/bottom-thinning-assessment"].limitations,
+        "Same combined product/soil rate drives Art; same RPB status must drive corrosion and default minimum thickness. No second external-corrosion DF added for the same soil-side loss."])
+def corrosion_thinning(x):
+    ensure((x.corrosion.bottom_type != "single_bottom") == x.thinning.minimum_thickness.release_prevention_barrier,"RPB status must agree between corrosion and thinning")
+    rate = corrosion_assessment(x.corrosion)
+    finite_tree(rate)
+    return {**rate,**_thinning(x.thinning,rate["combined_corrosion_rate_m_year"])}
+
+
+class BottomCorrosionRisk(Model):
+    damage: BottomCorrosionThinning
+    source: BottomSource
+    distance_to_groundwater_m: NonNegative
+    economics: BottomEconomics
+    management_score: NonNegative = Field(le=1000)
+    damage_scope: Literal["qualified_thinning_only"]
+    other_mechanisms_exclusion_basis: str = Field(min_length=1)
+
+
+@calculation("tank/bottom-corrosion-risk-assessment", "AST floor corrosion through source consequence and annual financial risk", BottomCorrosionRisk,
+    [*REGISTRY["tank/bottom-corrosion-thinning-assessment"].references,*REGISTRY["tank/bottom-integrated-assessment"].references],
+    origin="api581_composition_with_qualified_thinning_only_scope",limitations=[
+        *REGISTRY["tank/bottom-corrosion-thinning-assessment"].limitations,
+        *REGISTRY["tank/bottom-source-assessment"].limitations,
+        *REGISTRY["tank/bottom-financial-consequence"].limitations,
+        "This composition derives DF internally for explicit qualified thinning-only scope; other applicable mechanisms must be excluded with owner basis. Uniform computed DF and Fms apply to all four holes. Annual financial risk=sum(GFF)*DF*Fms*already-GFF-weighted consequence. Single bottom, not all-mechanism or whole-tank risk. Corrosion, thickness and source RPB status must agree."])
+def corrosion_risk(x):
+    ensure(bool(x.other_mechanisms_exclusion_basis.strip()),"Thinning-only risk requires exclusion basis for other mechanisms")
+    ensure(x.source.has_release_prevention_barrier == (x.damage.corrosion.bottom_type != "single_bottom"),"RPB status must agree between damage and release source")
+    damage = corrosion_thinning(x.damage)
+    finite_tree(damage)
+    risk = integrated(BottomIntegrated(source=x.source,distance_to_groundwater_m=x.distance_to_groundwater_m,economics=x.economics,
+        management_score=x.management_score,total_damage_factor=damage["thinning_damage_factor"],
+        damage_factor_source="Same-request AST-bottom eq2.12,Table4.7,eq2.23; owner-qualified thinning-only scope"))
+    return {**damage,**risk,"total_damage_factor":damage["thinning_damage_factor"],
+        "integration_scope":"bottom_corrosion_thinning_source_financial_risk_qualified_thinning_only"}