api581-engine 0.1.4__py3-none-any.whl

api581/tank_corrosion.py

@@ -0,0 +1,256 @@
+"""Carbon-steel AST floor corrosion, 2016 Annex 2.B section 14."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, calculation, ensure
+
+Pad = Literal["soil_high_salt", "crushed_limestone", "native_soil", "construction_grade_sand",
+    "continuous_asphalt", "continuous_concrete", "oil_sand", "high_resistivity_low_chloride_sand"]
+Bottom = Literal["rpb_not_per_api650", "rpb_per_api650", "single_bottom"]
+Boundary = Literal["lower_resistivity_interval", "higher_resistivity_interval"]
+Policy = Literal["apply_2_mpy_recommendation", "qualified_no_floor"]
+_PADS = dict(zip(Pad.__args__, (1.5, 1.4, 1.3, 1.15, 1., 1., .7, .7)))
+
+
+class BottomBase(Model):
+    side: Literal["soil", "product"]
+    unit_basis: Literal["printed_si", "printed_us_mpy"]
+
+
+@calculation("tank/bottom-base-corrosion-rate", "AST floor reference base corrosion rate", BottomBase,
+    ["Part2 Annex2.B §14.3.1-14.3.2,Tables2.B.14.3,14.10; PDF pp430-435"], limitations=[
+        "Fallback rates only; comparable inspection-derived base rates take precedence. Rounded SI and US pairs differ. Soil reference: moderate resistivity, continuous asphalt/concrete, good drainage, no functioning CP, single bottom, below24C. Product reference: no required coating, below24C, no coil, no regular water draws. Not a measured net rate."])
+def base(x):
+    si, us = (.13, 5.) if x.side == "soil" else (.05, 2.)
+    return dict(base_corrosion_rate_m_year=si/1000 if x.unit_basis == "printed_si" else us*.0000254,
+        printed_si_rate_mm_year=si, printed_us_rate_mpy=us, side=x.side, unit_basis=x.unit_basis)
+
+
+class BottomSoilRateEquation(Model):
+    base_corrosion_rate_m_year: NonNegative
+    resistivity_factor: NonNegative
+    pad_factor: NonNegative
+    drainage_factor: NonNegative
+    cathodic_protection_factor: NonNegative
+    bottom_type_factor: NonNegative
+    temperature_factor: NonNegative
+
+
+@calculation("tank/bottom-soil-rate-equation", "AST floor soil-side corrosion rate equation", BottomSoilRateEquation,
+    ["Part2 Annex2.B §14.2.1,eq(2.B.37); PDF p430"], limitations=[
+        "Independent equation kernel only. Factors and reference base rate are supplied and must be qualified from §14.3 tables or comparable inspection data. No soil classification, factor selection, AST applicability or measured-rate correction is inferred."])
+def soil_rate_equation(x):
+    rate = _rate(x.base_corrosion_rate_m_year, [x.resistivity_factor, x.pad_factor,
+        x.drainage_factor, x.cathodic_protection_factor, x.bottom_type_factor,
+        x.temperature_factor])
+    return dict(soil_corrosion_rate_m_year=rate)
+
+
+class BottomProductRateEquation(Model):
+    base_corrosion_rate_m_year: NonNegative
+    product_condition_factor: NonNegative
+    temperature_factor: NonNegative
+    steam_coil_factor: NonNegative
+    water_draw_factor: NonNegative
+
+
+@calculation("tank/bottom-product-rate-equation", "AST floor product-side corrosion rate equation", BottomProductRateEquation,
+    ["Part2 Annex2.B §14.2.2,eq(2.B.38); PDF p430"], limitations=[
+        "Independent equation kernel only. Factors and reference base rate are supplied and must be qualified from §14.3 tables or comparable inspection data. No product wetness, temperature, coil or water-draw classification is inferred."])
+def product_rate_equation(x):
+    rate = _rate(x.base_corrosion_rate_m_year, [x.product_condition_factor,
+        x.temperature_factor, x.steam_coil_factor, x.water_draw_factor])
+    return dict(product_corrosion_rate_m_year=rate)
+
+
+class BottomResistivity(Model):
+    release_prevention_barrier: bool
+    soil_resistivity_ohm_m: Positive | None = None
+    shared_boundary_basis: Boundary | None = None
+
+
+@calculation("tank/bottom-soil-resistivity-factor", "AST floor native-soil resistivity factor", BottomResistivity,
+    ["Part2 Annex2.B §14.3.1(a),Table2.B.14.4; PDF pp430,433"], limitations=[
+        "RPB or unknown resistivity uses1 by source instruction. Public ohm m; source ohm cm=100*ohm m. Shared1000/2000ohm cm endpoints require explicit interval basis. High-resistivity factor is.66 for AST, not the buried-pipe.60 factor."])
+def resistivity(x):
+    v = x.soil_resistivity_ohm_m
+    if x.release_prevention_barrier or v is None:
+        ensure(x.shared_boundary_basis is None, "Interval basis is inapplicable when resistivity is not used")
+        return dict(resistivity_factor=1., selection_reason="rpb" if x.release_prevention_barrier else "unknown_assume_moderate")
+    if v in (10., 20.):
+        ensure(x.shared_boundary_basis is not None, "Shared resistivity endpoint requires interval basis", "ambiguous_soil_resistivity_boundary")
+        i = (1 if v == 10 else 2)+(x.shared_boundary_basis == "higher_resistivity_interval")
+    else:
+        ensure(x.shared_boundary_basis is None, "Interval basis applies only at shared endpoints")
+        i = 0 if v < 5 else 1 if v < 10 else 2 if v < 20 else 3 if v <= 100 else 4
+    return dict(resistivity_factor=(1.5, 1.25, 1., .83, .66)[i], selection_reason="resistivity_table")
+
+
+class BottomPad(Model):
+    pad_type: Pad
+
+
+@calculation("tank/bottom-pad-factor", "AST floor foundation pad factor", BottomPad,
+    ["Part2 Annex2.B Table2.B.14.5; PDF p434"], limitations=["Owner qualifies actual pad category; no interpolation or automatic soil classification."])
+def pad(x):
+    return dict(pad_factor=_PADS[x.pad_type])
+
+
+class BottomDrainage(Model):
+    drainage_category: Literal["one_third_frequently_underwater", "storm_water_collects", "no_storm_water_collects"]
+
+
+@calculation("tank/bottom-drainage-factor", "AST floor drainage factor", BottomDrainage,
+    ["Part2 Annex2.B §14.3.1(c),Table2.B.14.6; PDF pp430,434"], limitations=[
+        "Owner selects category: table says one-third frequently underwater; prose describes more than one-third circumference underwater for extended periods. No invented numeric exposure classifier."])
+def drainage(x):
+    return dict(drainage_factor={"one_third_frequently_underwater":3., "storm_water_collects":2., "no_storm_water_collects":1.}[x.drainage_category])
+
+
+class BottomCP(Model):
+    protection_category: Literal["none", "present_not_per_api651", "present_per_api651"]
+    effectiveness_verified_by_high_level_inspection: bool
+    verification_basis: str | None = None
+
+
+@calculation("tank/bottom-cp-factor", "AST floor cathodic protection factor with inspection credit gate", BottomCP,
+    ["Part2 Annex2.B §14.3.1(d),Table2.B.14.7; PDF pp431,434"], limitations=[
+        "Table nominal factors1/.66/.33; text allows no credit without High Level inspection verifying effective CP under referenced NACE RP0169 or equivalent. Owner supplies verification basis. Historical references do not establish current compliance."])
+def cp(x):
+    verified = x.effectiveness_verified_by_high_level_inspection
+    if verified:
+        ensure(x.protection_category != "none", "Absent CP cannot receive verified credit")
+        ensure(x.verification_basis is not None and bool(x.verification_basis.strip()), "Verified CP requires inspection basis")
+    else:
+        ensure(x.verification_basis is None, "Unverified CP cannot supply verification basis")
+    nominal = {"none":1., "present_not_per_api651":.66, "present_per_api651":.33}[x.protection_category]
+    return dict(nominal_table_factor=nominal, cathodic_protection_factor=nominal if verified else 1., credit_applied=verified)
+
+
+class BottomType(Model):
+    bottom_type: Bottom
+
+
+@calculation("tank/bottom-type-factor", "AST floor construction factor", BottomType,
+    ["Part2 Annex2.B Table2.B.14.8; PDF p434"], limitations=["RPB classification is supplied by the owner; qualified RPB and single bottom both have factor1."])
+def bottom_type(x):
+    return dict(bottom_type_factor=1.4 if x.bottom_type == "rpb_not_per_api650" else 1.)
+
+
+class BottomTemperature(Model):
+    highest_operating_temperature_k: Positive
+    threshold_basis: Literal["printed_si", "printed_us_converted"]
+
+
+@calculation("tank/bottom-temperature-factor", "AST floor soil and product temperature factor", BottomTemperature,
+    ["Part2 Annex2.B Tables2.B.14.9,14.12; PDF p435"], limitations=[
+        "Both tables have identical five bands. Printed SI24/66/93/121C differ from US75/150/200/250F converted to K; basis required. Above highest threshold source factor returns1; not a qualification of high-temperature or cryogenic service."])
+def temperature(x):
+    bounds = [c+273.15 for c in (24.,66.,93.,121.)] if x.threshold_basis == "printed_si" else [(f-32)*5/9+273.15 for f in (75.,150.,200.,250.)]
+    i = next((i for i, b in enumerate(bounds) if x.highest_operating_temperature_k <= b), 4)
+    return dict(temperature_factor=(1.,1.1,1.3,1.4,1.)[i], source_row=i+1, threshold_basis=x.threshold_basis)
+
+
+class BottomProductCondition(Model):
+    product_condition: Literal["wet", "dry"]
+
+
+@calculation("tank/bottom-product-condition-factor", "AST floor product wetness factor", BottomProductCondition,
+    ["Part2 Annex2.B §14.3.2(a),Table2.B.14.11; PDF pp431,435"], limitations=["Wet means significant bottom sediment and water; owner qualifies actual condition."])
+def product_condition(x):
+    return dict(product_condition_factor=2.5 if x.product_condition == "wet" else 1.)
+
+
+class BottomSteamCoil(Model):
+    steam_coil_present: bool
+
+
+@calculation("tank/bottom-steam-coil-factor", "AST floor steam coil factor", BottomSteamCoil,
+    ["Part2 Annex2.B Table2.B.14.13; PDF p436"], limitations=["Presence multiplier only; no detailed steam-leak thermal model."])
+def steam_coil(x):
+    return dict(steam_coil_factor=1.15 if x.steam_coil_present else 1.)
+
+
+class BottomWaterDraw(Model):
+    water_draw_practice: Literal["none_or_not_regular", "weekly", "after_every_receipt"]
+
+
+@calculation("tank/bottom-water-draw-factor", "AST floor qualified regular water draw factor", BottomWaterDraw,
+    ["Part2 Annex2.B §14.3.2(d),Table2.B.14.14; PDF pp431,436"], limitations=["Credit.7 requires weekly draws or draws after every receipt; merely having a drain earns no credit."])
+def water_draw(x):
+    return dict(water_draw_factor=1. if x.water_draw_practice == "none_or_not_regular" else .7)
+
+
+class BottomCombine(Model):
+    soil_corrosion_rate_m_year: NonNegative
+    product_corrosion_rate_m_year: NonNegative
+    product_distribution: Literal["general", "local"]
+    minimum_rate_policy: Policy
+    no_floor_qualification_basis: str | None = None
+
+
+@calculation("tank/bottom-corrosion-rate-combine", "AST floor two-sided corrosion-rate combination", BottomCombine,
+    ["Part2 Annex2.B §14.3.3; PDF p431"], limitations=[
+        "Soil corrosion is local. General product corrosion adds both rates; local product corrosion uses maximum. Source recommends minimum2mpy=.0000508m/year. Explicit qualified bypass retains raw value. General/local selection follows section14.3.3; summary Table2.B.1.2 lists AST product as local. No AST damage factor computed here."])
+def combine(x):
+    apply = x.minimum_rate_policy == "apply_2_mpy_recommendation"
+    ensure((x.no_floor_qualification_basis is None) if apply else (x.no_floor_qualification_basis is not None and bool(x.no_floor_qualification_basis.strip())), "Floor policy and qualification basis must agree")
+    values = x.soil_corrosion_rate_m_year, x.product_corrosion_rate_m_year
+    raw = sum(values) if x.product_distribution == "general" else max(values)
+    return dict(raw_combined_rate_m_year=raw, combined_corrosion_rate_m_year=max(raw,.0000508) if apply else raw,
+        recommended_minimum_rate_m_year=.0000508, minimum_applied=apply and raw < .0000508,
+        combination_rule="sum" if x.product_distribution == "general" else "maximum")
+
+
+class BottomCorrosion(Model):
+    material: Literal["carbon_steel"]
+    applicability_basis: str = Field(min_length=1)
+    soil_base_corrosion_rate_m_year: NonNegative
+    product_base_corrosion_rate_m_year: NonNegative
+    soil_base_rate_source: str = Field(min_length=1)
+    product_base_rate_source: str = Field(min_length=1)
+    bottom_type: Bottom
+    soil_resistivity_ohm_m: Positive | None = None
+    shared_boundary_basis: Boundary | None = None
+    pad: BottomPad
+    drainage: BottomDrainage
+    cathodic_protection: BottomCP
+    temperature: BottomTemperature
+    product_condition: BottomProductCondition
+    steam_coil: BottomSteamCoil
+    water_draw: BottomWaterDraw
+    product_distribution: Literal["general", "local"]
+    minimum_rate_policy: Policy
+    no_floor_qualification_basis: str | None = None
+
+
+def _rate(base_rate, factors):
+    if base_rate == 0:
+        return 0.
+    rate = base_rate*math.prod(factors)
+    ensure(rate > 0 and math.isfinite(rate), "Corrosion-rate product outside finite positive range", "numerical_failure")
+    return rate
+
+
+@calculation("tank/bottom-corrosion-assessment", "AST floor soil and product corrosion assessment", BottomCorrosion,
+    ["Part2 Annex2.B §14.3,eqs(2.B.37-38),Tables2.B.14.4-14; PDF pp430-436"], limitations=[
+        "Carbon-steel AST floor only. Explicit comparable base rates and provenance required; measured net rates must not be multiplied again without qualification. RPB soil-resistivity override derives from bottom type. Single highest operating temperature drives both source temperature factors. CP inspection gate enforced. No coating credit, remaining life, AST thinning damage factor or complete asset risk calculation."])
+def assessment(x):
+    ensure(all(s.strip() for s in (x.applicability_basis,x.soil_base_rate_source,x.product_base_rate_source)), "Qualification and provenance must not be blank")
+    fsr = resistivity(BottomResistivity(release_prevention_barrier=x.bottom_type != "single_bottom",
+        soil_resistivity_ohm_m=x.soil_resistivity_ohm_m, shared_boundary_basis=x.shared_boundary_basis))["resistivity_factor"]
+    fpa, fdr = pad(x.pad)["pad_factor"], drainage(x.drainage)["drainage_factor"]
+    cp_result = cp(x.cathodic_protection)
+    fcp = cp_result["cathodic_protection_factor"]
+    ftb = bottom_type(BottomType(bottom_type=x.bottom_type))["bottom_type_factor"]
+    ft = temperature(x.temperature)["temperature_factor"]
+    fpc = product_condition(x.product_condition)["product_condition_factor"]
+    fsc, fwd = steam_coil(x.steam_coil)["steam_coil_factor"], water_draw(x.water_draw)["water_draw_factor"]
+    soil_rate = _rate(x.soil_base_corrosion_rate_m_year,[fsr,fpa,fdr,fcp,ftb,ft])
+    product_rate = _rate(x.product_base_corrosion_rate_m_year,[fpc,ft,fsc,fwd])
+    result = combine(BottomCombine(soil_corrosion_rate_m_year=soil_rate,product_corrosion_rate_m_year=product_rate,
+        product_distribution=x.product_distribution,minimum_rate_policy=x.minimum_rate_policy,no_floor_qualification_basis=x.no_floor_qualification_basis))
+    return dict(**result,soil_corrosion_rate_m_year=soil_rate,product_corrosion_rate_m_year=product_rate,
+        resistivity_factor=fsr,pad_factor=fpa,drainage_factor=fdr,cathodic_protection_factor=fcp,bottom_type_factor=ftb,
+        temperature_factor=ft,product_condition_factor=fpc,steam_coil_factor=fsc,water_draw_factor=fwd,
+        cp_credit_applied=cp_result["credit_applied"])

api581/tank_environment.py

@@ -0,0 +1,186 @@
+"""AST environmental allocation and bottom repair; native volume unit is bbl."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+
+HOLES = ("small", "medium", "large", "rupture")
+Hole = Literal["small", "medium", "large", "rupture"]
+LOCATIONS = ("in_dike", "surface_on_site", "surface_off_site", "subsoil", "groundwater", "surface_water")
+Location = Literal["in_dike", "surface_on_site", "surface_off_site", "subsoil", "groundwater", "surface_water"]
+_COSTS = {"low": (10, 50, 100, 500, 1000, 500),
+          "medium": (10, 50, 250, 1500, 5000, 1500),
+          "high": (10, 50, 500, 3000, 10000, 5000)}
+
+
+class EnvironmentalCostTable(Model):
+    sensitivity: Literal["low", "medium", "high"]
+
+
+@calculation("tank/environment-cost-table", "AST estimated environmental costs in source USD/bbl", EnvironmentalCostTable,
+    ["Part3 Table6.6; PDF p608"], limitations=["Historical source estimates, not current prices. Source supplies no explicit price year for Table6.6; no 2001 assumption is inferred from repair Table4.15. End user must qualify applicability and escalation."])
+def environment_cost_table(x):
+    return {"cost_by_location_usd_per_bbl": dict(zip(LOCATIONS, _COSTS[x.sensitivity]))}
+
+
+class SurfaceSpill(Model):
+    released_volume_bbl: NonNegative
+    fraction_leaving_dike: Fraction
+    fraction_on_site: Fraction
+    fraction_off_site: Fraction
+
+
+@calculation("tank/surface-spill-partition", "Sequential AST surface spill allocation", SurfaceSpill,
+    ["Part3 eqs(3.232)-(3.235),(3.238)-(3.241); PDF pp599-600"],
+    limitations=["Fractions are conditional: on-site applies to volume leaving dike; off-site applies to what remains after on-site. Use fractions0..1, not percentage numbers0..100. No dike capacity or surface transport simulation."])
+def surface_spill(x):
+    return _surface(x, x.released_volume_bbl)
+
+
+class GroundwaterArrival(Model):
+    distance_to_groundwater_m: NonNegative
+    seepage_velocity_m_day: NonNegative
+
+
+@calculation("tank/groundwater-arrival", "AST seepage travel time to groundwater", GroundwaterArrival,
+    ["Part3 eq(3.244); PDF p601"], limitations=["Zero distance means already at groundwater; positive distance with zero velocity returns null arrival time, not infinity. No plume, retardation or groundwater migration model."])
+def groundwater_arrival(x):
+    if x.distance_to_groundwater_m == 0:
+        return {"arrival_time_days": 0, "arrival_status": "already_at_groundwater"}
+    if x.seepage_velocity_m_day == 0:
+        return {"arrival_time_days": None, "arrival_status": "no_finite_arrival"}
+    arrival = x.distance_to_groundwater_m/x.seepage_velocity_m_day
+    ensure(math.isfinite(arrival) and arrival > 0, "Groundwater travel time outside numerical range", "numerical_failure")
+    return {"arrival_time_days": arrival, "arrival_status": "finite_travel"}
+
+
+class SubsurfaceSpill(Model):
+    leaked_volume_bbl: NonNegative
+    detection_time_days: Positive
+    groundwater_arrival_time_days: NonNegative | None
+
+
+@calculation("tank/subsurface-spill-partition", "AST bottom leakage allocation to groundwater and subsoil", SubsurfaceSpill,
+    ["Part3 eqs(3.245)-(3.247); PDF p601"], limitations=["Printed detection time is the denominator, even if inventory depletion limits actual leak duration. This is not a transient transport solution. Null arrival means no finite arrival. Positive detection time required; zero-volume leakage returns zero in both compartments."])
+def subsurface_spill(x):
+    arrival = x.groundwater_arrival_time_days
+    fraction = 0 if arrival is None or arrival >= x.detection_time_days else 1-arrival/x.detection_time_days
+    groundwater = x.leaked_volume_bbl*fraction
+    return {"groundwater_bbl": groundwater, "subsoil_bbl": x.leaked_volume_bbl-groundwater,
+            "groundwater_fraction": fraction}
+
+
+class FrequencyWeights(Model):
+    generic_frequency_by_hole_per_year: dict[Hole, NonNegative]
+
+
+def _weights(x):
+    rates = x.generic_frequency_by_hole_per_year
+    ensure(set(rates) == set(HOLES), "Exactly small, medium, large and rupture frequencies required", "incomplete_hole_set")
+    scale = max(rates.values())
+    ensure(scale > 0, "Total generic frequency must be positive")
+    scaled = {h: rates[h]/scale for h in HOLES}
+    total = math.fsum(scaled.values())
+    return {h: scaled[h]/total for h in HOLES}
+
+
+class EnvironmentalBasis(FrequencyWeights):
+    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
+
+
+def _check_costs(x):
+    ensure(set(x.cost_by_location_per_bbl) == set(LOCATIONS), "All six environmental cost locations required", "incomplete_cost_set")
+    ensure(bool(x.cost_basis.strip()), "Cost basis must identify source or qualified valuation")
+
+
+def _surface(x, volume):
+    outside = volume*x.fraction_leaving_dike
+    after_on_site = outside*(1-x.fraction_on_site)
+    return {"in_dike_bbl": volume*(1-x.fraction_leaving_dike),
+            "surface_on_site_bbl": outside*x.fraction_on_site,
+            "surface_off_site_bbl": after_on_site*x.fraction_off_site,
+            "surface_water_bbl": after_on_site*(1-x.fraction_off_site)}
+
+
+def _surface_cost(x, volumes):
+    return math.fsum(volumes[k+"_bbl"]*x.cost_by_location_per_bbl[k]
+                     for k in ("in_dike", "surface_on_site", "surface_off_site", "surface_water"))
+
+
+class ShellEnvironment(EnvironmentalBasis):
+    released_volume_by_hole_bbl: dict[Hole, NonNegative]
+
+
+_ENV_LIMITS = ["Caller supplies qualified per-hole GFF; total is their sum (eq3.208), including rupture in leak denominator. No ambiguous printed tank-total lookup. Frequencies are normalized once; no ignition probability applied.",
+               "Costs are per bbl in one declared currency and caller-declared cost basis. No implicit escalation, FX conversion or current-price claim. Table6.6 values require owner qualification."]
+
+
+@calculation("tank/shell-environment-cost", "GFF-weighted AST shell environmental consequence", ShellEnvironment,
+    ["Part3 eqs(3.208),(3.231)-(3.243); PDF pp593,599-600"], limitations=_ENV_LIMITS)
+def shell_environment(x):
+    _check_costs(x)
+    weights = _weights(x)
+    ensure(set(x.released_volume_by_hole_bbl) == set(HOLES), "Exactly four released-volume holes required", "incomplete_hole_set")
+    leak = math.fsum(weights[h]*x.released_volume_by_hole_bbl[h] for h in HOLES[:3])
+    rupture = weights["rupture"]*x.released_volume_by_hole_bbl["rupture"]
+    leak_volumes, rupture_volumes = _surface(x, leak), _surface(x, rupture)
+    leak_cost, rupture_cost = _surface_cost(x, leak_volumes), _surface_cost(x, rupture_volumes)
+    return {"weighted_leak_volume_bbl": leak, "weighted_rupture_volume_bbl": rupture,
+            "weighted_leak_surface_volumes_bbl": leak_volumes, "weighted_rupture_surface_volumes_bbl": rupture_volumes,
+            "leak_environment_cost": leak_cost, "rupture_environment_cost": rupture_cost,
+            "environment_cost": leak_cost+rupture_cost, "currency": x.currency, "cost_basis": x.cost_basis}
+
+
+class BottomEnvironment(EnvironmentalBasis):
+    leaked_volume_by_hole_bbl: dict[Literal["small", "medium", "large"], NonNegative]
+    total_tank_volume_bbl: NonNegative
+    detection_time_days: Positive
+    groundwater_arrival_time_days: NonNegative | None
+
+
+@calculation("tank/bottom-environment-cost", "GFF-weighted AST bottom environmental consequence", BottomEnvironment,
+    ["Part3 eqs(3.238)-(3.249); PDF pp600-601"], limitations=_ENV_LIMITS+[
+        "Bottom leaks enter subsoil/groundwater; rupture releases total tank inventory to four surface locations. Printed detection-time partition retained despite inventory-limited release duration. Surrounding-equipment and injury costs are not applicable to bottom assessment; this API returns environmental cost only."])
+def bottom_environment(x):
+    _check_costs(x)
+    weights = _weights(x)
+    ensure(set(x.leaked_volume_by_hole_bbl) == set(HOLES[:3]), "Exactly three leakage holes required", "incomplete_hole_set")
+    parts = {h: subsurface_spill(SubsurfaceSpill(leaked_volume_bbl=x.leaked_volume_by_hole_bbl[h],
+        detection_time_days=x.detection_time_days, groundwater_arrival_time_days=x.groundwater_arrival_time_days)) for h in HOLES[:3]}
+    groundwater = math.fsum(weights[h]*parts[h]["groundwater_bbl"] for h in HOLES[:3])
+    subsoil = math.fsum(weights[h]*parts[h]["subsoil_bbl"] for h in HOLES[:3])
+    leak_cost = math.fsum((groundwater*x.cost_by_location_per_bbl["groundwater"], subsoil*x.cost_by_location_per_bbl["subsoil"]))
+    rupture = weights["rupture"]*x.total_tank_volume_bbl
+    rupture_volumes = _surface(x, rupture)
+    rupture_cost = _surface_cost(x, rupture_volumes)
+    return {"weighted_groundwater_volume_bbl": groundwater, "weighted_subsoil_volume_bbl": subsoil,
+            "weighted_rupture_volume_bbl": rupture, "weighted_rupture_surface_volumes_bbl": rupture_volumes,
+            "leak_environment_cost": leak_cost, "rupture_environment_cost": rupture_cost,
+            "environment_cost": leak_cost+rupture_cost, "currency": x.currency, "cost_basis": x.cost_basis}
+
+
+class BottomRepair(FrequencyWeights):
+    tank_diameter_m: Positive
+    repair_cost_by_hole: dict[Hole, NonNegative]
+    material_factor: Positive
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+    cost_basis: str = Field(min_length=1, max_length=500)
+
+
+@calculation("tank/bottom-repair-cost", "AST bottom repair with rupture-only diameter scaling", BottomRepair,
+    ["Part3 eq(3.250),Tables4.15/4.16,Annex3.B C36; PDF pp532-533,601,649"], limitations=[
+        "Caller supplies all four repair costs and qualified GFF. Only rupture cost scales by (D/30.5m)^2; small/medium/large repair costs do not. Historical financial/repair-table returns USD2001; caller must explicitly qualify escalation/currency and retain consistent cost basis."])
+def bottom_repair(x):
+    weights = _weights(x)
+    ensure(set(x.repair_cost_by_hole) == set(HOLES), "Exactly four repair cost holes required", "incomplete_hole_set")
+    ensure(bool(x.cost_basis.strip()), "Cost basis must identify source or qualified valuation")
+    # Avoid squaring diameter when rupture contributes nothing.
+    rupture = weights["rupture"]*x.repair_cost_by_hole["rupture"]
+    rupture = 0 if rupture == 0 else rupture*(x.tank_diameter_m/30.5)**2
+    cost = math.fsum([weights[h]*x.repair_cost_by_hole[h] for h in HOLES[:3]]+[rupture])*x.material_factor
+    return {"component_repair_cost": cost, "currency": x.currency, "cost_basis": x.cost_basis}

api581/tank_financial.py

@@ -0,0 +1,202 @@
+"""AST component financial consequence and uniform-DF financial risk composition."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, calculation, ensure
+from .pof import Management, management
+from .cost_tables import REPAIR, MATERIAL, OUTAGE, SurroundingOutage, surrounding_outage
+from .tank_environment import (
+    HOLES, Hole, FrequencyWeights, _weights, BottomEnvironment, ShellEnvironment,
+    bottom_environment, shell_environment, BottomRepair, bottom_repair,
+)
+
+TankType = Literal["TANKBOTTOM", "COURSE-1-10"]
+_GFF = {"TANKBOTTOM": (7.2e-4, 0., 0., 2e-6), "COURSE-1-10": (7e-5, 2.5e-5, 5e-6, 1e-7)}
+_PRINTED_TOTAL = {"TANKBOTTOM": 7.2e-4, "COURSE-1-10": 1e-4}
+
+
+def _product(*values):
+    if any(v == 0 for v in values):
+        return 0.
+    value = math.prod(values)
+    ensure(math.isfinite(value) and value > 0, "Positive product outside numerical range", "numerical_failure")
+    return value
+
+
+class TankComponent(Model):
+    component_type: TankType
+
+
+@calculation("tank/generic-frequency", "AST generic frequencies with explicit equation-summed total", TankComponent,
+    ["Part2 Table3.1; Part3 eq(3.208); PDF pp147,593"], limitations=[
+        "Uses the sum of four hole frequencies authorized by eq3.208. Printed tank totals differ and are returned separately; this is not an authorized correction of Table3.1. COURSE-1-10 is one shell-course component, not the whole tank or ten multiplied courses."])
+def generic_frequency(x):
+    values = _GFF[x.component_type]
+    total = math.fsum(values)
+    printed = _PRINTED_TOTAL[x.component_type]
+    return {"by_hole_per_year": dict(zip(HOLES, values)), "total_per_year": total,
+            "printed_total_per_year": printed, "sum_minus_printed_per_year": total-printed,
+            "total_basis": "hole_sum_eq3_208"}
+
+
+class TankOutage(FrequencyWeights):
+    component_type: TankType
+    outage_multiplier: Positive
+    override_days: dict[Hole, NonNegative] = Field(default_factory=dict)
+
+
+@calculation("tank/component-outage", "AST GFF-weighted component outage duration", TankOutage,
+    ["Part3 eq(3.88),Table4.17,§6.12; PDF pp506,534,599-601"], limitations=[
+        "All four qualified per-hole GFF are supplied by caller and normalized by their sum. Source NA is not zero: nonzero-frequency NA requires owner override. Zero-frequency NA contributes zero. No automatic diameter correction of outage duration."])
+def component_outage(x):
+    weights = _weights(x)
+    days = dict(zip(HOLES, OUTAGE[x.component_type]))
+    days.update(x.override_days)
+    for h in HOLES:
+        ensure(days[h] is not None or x.generic_frequency_by_hole_per_year[h] == 0,
+               f"Outage NA for nonzero-frequency hole {h}; supply override_days", "missing_outage_override")
+    value = math.fsum(weights[h]*(days[h] if days[h] is not None else 0) for h in HOLES)*x.outage_multiplier
+    return {"component_outage_days": value, "effective_days_by_hole": days}
+
+
+class TankRepairBasis(Model):
+    material_id: Literal[tuple(MATERIAL)]
+    price_factor_since_2001: Positive
+    usd_to_output_currency: Positive
+    cost_basis_year: int = Field(ge=2001, le=2200)
+
+
+class OperatingCosts(Model):
+    repair: TankRepairBasis
+    outage_multiplier: Positive
+    override_outage_days: dict[Hole, NonNegative] = Field(default_factory=dict)
+    production_cost_per_day: NonNegative
+    generic_frequency_source: str = Field(min_length=1, max_length=500)
+
+
+class BottomFinancial(BottomEnvironment, OperatingCosts):
+    tank_diameter_m: Positive
+
+
+class ShellFinancial(ShellEnvironment, OperatingCosts):
+    equipment_area_m2: NonNegative
+    personnel_area_m2: NonNegative
+    equipment_cost_per_m2: NonNegative
+    population_density_per_m2: NonNegative
+    cost_per_injury: NonNegative
+
+
+_FIN_LIMITS = [
+    "Per-hole GFF, release volumes and qualified environmental costs are supplied inputs. Environment, production, surrounding-equipment and injury unit costs must use the declared currency and repair.cost_basis_year; cost_basis records the common valuation. Table6.6 has no stated price year and must be qualified explicitly before combining with escalated USD2001 repair costs.",
+    "Component-only consequence. Damage applicability, release hydraulics, consequence areas and monetary qualification are not inferred. Per-hole frequencies normalize once including rupture. No additional ignition weighting or automatic whole-tank course summation.",
+]
+
+
+def _environment(x, cls, fn):
+    # Only original validated fields enter a submodel; no derived values are coerced.
+    return fn(cls(**{k: getattr(x, k) for k in cls.model_fields}))
+
+
+def _outage(x, component_type):
+    ensure(bool(x.generic_frequency_source.strip()), "Generic frequency source must be nonblank")
+    return component_outage(TankOutage(component_type=component_type,
+        generic_frequency_by_hole_per_year=x.generic_frequency_by_hole_per_year,
+        outage_multiplier=x.outage_multiplier, override_days=x.override_outage_days))["component_outage_days"]
+
+
+def _repair(x, component_type):
+    weights = _weights(x)
+    if component_type == "TANKBOTTOM":
+        reference = bottom_repair(BottomRepair(
+            generic_frequency_by_hole_per_year=x.generic_frequency_by_hole_per_year,
+            tank_diameter_m=x.tank_diameter_m, repair_cost_by_hole=dict(zip(HOLES, REPAIR[component_type])),
+            material_factor=MATERIAL[x.repair.material_id], currency="USD", cost_basis="Table4.15 USD2001"))["component_repair_cost"]
+    else:
+        reference = math.fsum(weights[h]*v for h,v in zip(HOLES, REPAIR[component_type]))*MATERIAL[x.repair.material_id]
+    return _product(reference, x.repair.price_factor_since_2001, x.repair.usd_to_output_currency)
+
+
+def _result(x, repair, outage, environment, surrounding=0., surrounding_days=0., injury=0., reference_surrounding=0.):
+    production = _product(outage+surrounding_days, x.production_cost_per_day)
+    return {"component_repair_cost": repair, "surrounding_equipment_cost": surrounding,
+            "business_interruption_cost": production, "injury_cost": injury, "environmental_cost": environment["environment_cost"],
+            "component_outage_days": outage, "surrounding_outage_days": surrounding_days,
+            "surrounding_cost_reference_usd_2001": reference_surrounding,
+            "leak_environment_cost": environment["leak_environment_cost"], "rupture_environment_cost": environment["rupture_environment_cost"],
+            "financial_consequence": math.fsum([repair, surrounding, production, injury, environment["environment_cost"]]),
+            "currency": x.currency, "cost_basis_year": x.repair.cost_basis_year, "cost_basis": x.cost_basis}
+
+
+@calculation("tank/bottom-financial-consequence", "Compose AST bottom repair, production and environmental consequence", BottomFinancial,
+    ["Part3 §6.12.3,eqs(3.88),(3.90),(3.243)-(3.250); PDF pp506,600-601"], limitations=_FIN_LIMITS+[
+        "Bottom surrounding-equipment and injury costs are not applicable per §6.12.3 and returned zero. Rupture repair alone scales by diameter squared. Groundwater uses printed detection time, not inventory depletion time."])
+def bottom_financial(x):
+    environment = _environment(x, BottomEnvironment, bottom_environment)
+    outage = _outage(x, "TANKBOTTOM")
+    return _result(x, _repair(x, "TANKBOTTOM"), outage, environment)
+
+
+@calculation("tank/shell-financial-consequence", "Compose five AST shell-course financial consequence categories", ShellFinancial,
+    ["Part3 §6.12.2,eqs(3.85)-(3.91),(3.231)-(3.243); PDF pp505-506,599-600"], limitations=_FIN_LIMITS+[
+        "Areas must already be GFF-weighted from a qualified AST flammable/toxic assessment. No automatic AST NFNT area is inferred. Surrounding-outage correlation uses equivalent USD2001 via explicit escalation/FX factors; damage area is not converted again."])
+def shell_financial(x):
+    environment = _environment(x, ShellEnvironment, shell_environment)
+    outage = _outage(x, "COURSE-1-10")
+    surrounding = _product(x.equipment_area_m2, x.equipment_cost_per_m2)
+    reference = surrounding/x.repair.usd_to_output_currency/x.repair.price_factor_since_2001
+    ensure(math.isfinite(reference), "Reference surrounding cost overflow", "numerical_failure")
+    ensure(reference > 0 or surrounding == 0, "Reference surrounding cost underflow", "numerical_failure")
+    days = surrounding_outage(SurroundingOutage(surrounding_damage_cost_usd=reference))["surrounding_outage_days"]
+    injury = _product(x.personnel_area_m2, x.population_density_per_m2, x.cost_per_injury)
+    return _result(x, _repair(x, "COURSE-1-10"), outage, environment, surrounding, days, injury, reference)
+
+
+class DamageBasis(Model):
+    management_score: NonNegative = Field(le=1000)
+    total_damage_factor: NonNegative
+    damage_factor_source: str = Field(min_length=1, max_length=500)
+
+
+class BottomAssessment(DamageBasis):
+    financial: BottomFinancial
+
+
+class ShellAssessment(DamageBasis):
+    financial: ShellFinancial
+
+
+_RISK_LIMITS = _FIN_LIMITS+[
+    "Uniform supplied DF and Fms apply to all four holes of one component. Annual financial risk is sum(GFF)*DF*Fms*already-GFF-weighted financial consequence. This composition does not calculate damage applicability, dynamic release, whole-tank common-cause risk or individual/societal risk.",
+]
+
+
+def _assessment(x, fn):
+    ensure(bool(x.damage_factor_source.strip()), "Damage factor source must be nonblank")
+    financial = fn(x.financial)
+    fms = management(Management(score=x.management_score))["management_factor"]
+    rates = x.financial.generic_frequency_by_hole_per_year
+    total = math.fsum(rates.values())
+    adjusted = {h: _product(rates[h], x.total_damage_factor, fms) for h in HOLES}
+    annual = math.fsum(adjusted.values())
+    ensure(math.isfinite(annual), "Annual frequency overflow", "numerical_failure")
+    ensure(annual > 0 or x.total_damage_factor == 0, "Annual frequency underflow", "numerical_failure")
+    return {**financial, "generic_frequency_per_year": total, "management_factor": fms,
+            "annual_failure_frequency": annual, "annual_frequency_by_hole": adjusted,
+            "financial_risk_per_year": _product(annual, financial["financial_consequence"]),
+            "integration_scope": "supplied_uniform_df_and_tank_release_consequences"}
+
+
+@calculation("tank/bottom-risk-assessment", "AST bottom financial consequence and annual risk", BottomAssessment,
+    ["Part1 eqs(1.1),(1.8); Part2 eqs(2.9)-(2.10); Part3 §6.12.3"], limitations=_RISK_LIMITS+[
+        "Bottom assessment returns financial risk only; no unsupported zero-valued physical consequence area is implied. Surrounding-equipment and injury costs are not applicable; rupture-only repair diameter scaling and printed detection-time groundwater partition retained."])
+def bottom_assessment(x):
+    return _assessment(x, bottom_financial)
+
+
+@calculation("tank/shell-risk-assessment", "AST shell-course financial and area risks", ShellAssessment,
+    ["Part1 eqs(1.1),(1.6)-(1.8); Part2 eqs(2.9)-(2.10); Part3 §6.12.2"], limitations=_RISK_LIMITS+[
+        "Equipment/personnel area risks use externally qualified GFF-weighted AST areas. No automatic AST NFNT, course summation or whole-tank spatial overlap resolution."])
+def shell_assessment(x):
+    result = _assessment(x, shell_financial)
+    return {**result, "equipment_area_risk_m2_per_year": _product(result["annual_failure_frequency"], x.financial.equipment_area_m2),
+            "personnel_area_risk_m2_per_year": _product(result["annual_failure_frequency"], x.financial.personnel_area_m2)}