api581-engine 0.1.4__py3-none-any.whl

api581/co2_screening.py

@@ -0,0 +1,205 @@
+"""CO2 Figure13.1 screening, source defaults and SI input preparation."""
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure, finite_tree
+from .co2_corrosion import CO2Assessment, CO2WetModel, assessment
+from .thinning import Posterior, WallLoss
+from .clad_thinning import PressureStrength, CodeStrength
+from .thinning_conditions import ThinningConditions, QualifiedUnclad, qualified_unclad
+
+
+class CO2PartialPressure(Model):
+    total_pressure_pa_abs: Positive
+    co2_mole_fraction: Fraction
+
+
+@calculation("properties/co2-partial-pressure", "CO2 partial pressure from absolute total pressure and mole fraction", CO2PartialPressure,
+    ["Part2 Table2.B.13.1; PDF p427"],limitations=[
+        "pCO2=mole fraction*absolute total pressure. Input is fraction0..1, not mole percent or gauge pressure. No fugacity/EOS calculation or clamping to4MPa integrated model limit. Pure input conversion does not establish free-water or material applicability."])
+def partial_pressure(x):
+    value = x.total_pressure_pa_abs*x.co2_mole_fraction
+    ensure(value > 0 or x.co2_mole_fraction == 0,"Partial pressure underflow","numerical_failure")
+    return {"co2_partial_pressure_pa_abs":value}
+
+
+class CO2MassFlowReynolds(Model):
+    diameter_m: Positive
+    cross_sectional_area_m2: Positive
+    mass_flow_kg_s: NonNegative
+    mixture_viscosity_pa_s: Positive
+
+
+@calculation("damage/co2-reynolds-mass-flow", "CO2 mixture Reynolds number from mass flow and area", CO2MassFlowReynolds,
+    ["Part2 eq(2.B.35); PDF p425"],limitations=[
+        "Re=mass_flow*diameter/(area*viscosity); mass flux=mass_flow/area. Source wording calls dottedm mass flux although printed formula divides byarea; API names dimensional quantities explicitly rather than dividing an already-area-normalized flux again. Area/hydraulic diameter and effective viscosity externally qualified; no mixture-property model or laminar correlation."])
+def mass_flow_reynolds(x):
+    flux = x.mass_flow_kg_s/x.cross_sectional_area_m2
+    re = flux*x.diameter_m/x.mixture_viscosity_pa_s
+    finite_tree([flux,re])
+    ensure((flux > 0 and re > 0) or x.mass_flow_kg_s == 0,"Mass-flow Reynolds underflow","numerical_failure")
+    return {"mass_flux_kg_m2_s":flux,"reynolds_number":re}
+
+
+class CO2MaterialScreen(Model):
+    material_category: Literal["carbon_steel","low_alloy_steel","stainless_steel","copper_alloy","other"]
+    interpretation: Literal["figure_13cr_ferrous","table_resistant_alloys"]
+    chromium_mass_fraction: Fraction | None = None
+    qualification_basis: str = Field(min_length=1)
+
+
+@calculation("damage/co2-material-screen", "CO2 figure chromium or table material screening", CO2MaterialScreen,
+    ["Part2 Figure2.B.13.1,Table2.B.13.1; PDF pp427,429"],limitations=[
+        "Figure screens carbon steel orCr<13%; equality13% is source-assumed resistant. Chromium threshold applied only to qualified ferrous categories, not copper with nominalCr0. Table interpretation lists stainless/copper assumed resistant and carbon/low-alloy evaluated. Other material remains not_covered, never automatic zero. Explicit interpretation preserves differences between named-alloy table and elemental figure. Source-assumed resistance is CO2-specific, not immunity to other corrosion/SCC or a verified material-performance conclusion."])
+def material_screen(x):
+    ensure(bool(x.qualification_basis.strip()),"Material identification/screening qualification required")
+    category = x.material_category
+    if x.interpretation == "table_resistant_alloys":
+        ensure(x.chromium_mass_fraction is None,"Chromium fraction is unused in table-only classification")
+        decision = "evaluate_co2" if category in ("carbon_steel","low_alloy_steel") else "source_assumed_resistant" if category in ("stainless_steel","copper_alloy") else "not_covered"
+    elif category == "carbon_steel":
+        ensure(x.chromium_mass_fraction is None,"Carbon-steel figure branch does not require competing chromium input")
+        decision = "evaluate_co2"
+    elif category in ("low_alloy_steel","stainless_steel"):
+        ensure(x.chromium_mass_fraction is not None,"Ferrous figure screen requires known chromium fraction")
+        decision = "evaluate_co2" if x.chromium_mass_fraction < .13 else "source_assumed_resistant"
+    else:
+        ensure(x.chromium_mass_fraction is None,"Figure chromium screen not generalized to non-ferrous/unknown material")
+        decision = "not_covered"
+    return {"material_screen_decision":decision,"source_material_resistance_assumed":decision == "source_assumed_resistant"}
+
+
+class CO2HydrocarbonWetting(Model):
+    liquid_hydrocarbons_present: bool
+    water_cut_policy: Literal["explicit_qualified_percent","source_default_30_percent"] | None = None
+    water_content_percent: float | None = Field(default=None,ge=0,le=100,strict=True,allow_inf_nan=False)
+    water_content_basis: str | None = None
+    mixture_velocity_m_s: NonNegative | None = None
+    qualification_basis: str = Field(min_length=1)
+
+
+@calculation("damage/co2-hydrocarbon-wetting-screen", "CO2 low-water high-velocity hydrocarbon figure screen", CO2HydrocarbonWetting,
+    ["Part2 Figure2.B.13.1,Table2.B.13.1; PDF pp427,429"],limitations=[
+        "LiquidHC AND water<20% AND velocity>1m/s gives source figure exemption. Equality20%/1m/s proceeds to moisture/water check. Percentage basis is not identified precisely in figure: explicit qualified water-cut percent/basis required; do not substitute gas water mass fraction or glycol composition. Missing liquid-system water cut can use explicit source default30%, which never grants exemption. NoHC proceeds to moisture check. This is a qualified legacy figure rule, not proof metal is oil-wet under actual multiphase flow."])
+def hydrocarbon_screen(x):
+    ensure(bool(x.qualification_basis.strip()),"Hydrocarbon/wetting applicability basis required")
+    if not x.liquid_hydrocarbons_present:
+        ensure(x.water_cut_policy is None and x.water_content_percent is None and x.water_content_basis is None and x.mixture_velocity_m_s is None,
+            "No-liquid-HC branch cannot contain unused liquid-system water/velocity fields")
+        water,default,exempt = None,False,False
+    else:
+        ensure(x.water_cut_policy is not None,"Liquid-HC water-cut policy required")
+        default = x.water_cut_policy == "source_default_30_percent"
+        if default:
+            ensure(x.water_content_percent is None and x.water_content_basis is None,"Default30% cannot have competing explicit water cut")
+            water = 30.
+        else:
+            ensure(x.water_content_percent is not None and x.water_content_basis is not None and bool(x.water_content_basis.strip()),"Explicit liquid water cut requires value and qualified percentage basis")
+            water = x.water_content_percent
+        if water < 20:
+            ensure(x.mixture_velocity_m_s is not None,"Low water cut requires velocity to resolve figure branch")
+        exempt = water < 20 and x.mixture_velocity_m_s > 1
+    return {"wetting_screen_decision":"figure_low_water_high_velocity_exemption" if exempt else "proceed_to_water_check",
+        "water_content_percent_used":water,"source_water_default_used":default}
+
+
+class CO2MoistureScreen(Model):
+    temperature_k: Positive
+    evidence: Literal["qualified_dew_point","qualified_free_water_present","qualified_no_free_water","source_missing_moisture_assume_wet"]
+    dew_point_temperature_k: Positive | None = None
+    dew_point_uncertainty_k: NonNegative | None = None
+    equality_policy: Literal["figure_strict_less","indeterminate_at_saturation"] | None = None
+    qualification_basis: str = Field(min_length=1)
+
+
+@calculation("damage/co2-moisture-screen", "CO2 free-water or dew-point screening with explicit uncertainty", CO2MoistureScreen,
+    ["Part2 §13.3.2,Table2.B.13.1,Figure2.B.13.1; PDF pp423-424,427,429"],limitations=[
+        "Known free-water presence/absence can be supplied with basis. Missing gas moisture can explicitly assume wet per table, flagged as source assumption. Qualified dew point requires owner uncertainty and equality policy: outside uncertainty interval classify; inside interval indeterminate. At zero uncertainty and equalT, figure_strict_less uses absent, alternative leaves indeterminate. Approximate eq2.B.25 is not assumed accurate within±10F: no automatic zero-uncertainty adoption of its output. Free-water states concern CO2 only, not all corrosion."])
+def moisture_screen(x):
+    ensure(bool(x.qualification_basis.strip()),"Moisture/free-water evidence basis required")
+    assumed = x.evidence == "source_missing_moisture_assume_wet"
+    if x.evidence == "qualified_dew_point":
+        ensure(x.dew_point_temperature_k is not None and x.dew_point_uncertainty_k is not None and x.equality_policy is not None,"Dew-point screen requires value, uncertainty and equality policy")
+        delta = x.temperature_k-x.dew_point_temperature_k
+        u = x.dew_point_uncertainty_k
+        state = "present" if delta < -u else "absent" if delta > u else "absent" if u == 0 and delta == 0 and x.equality_policy == "figure_strict_less" else "indeterminate"
+    else:
+        ensure(x.dew_point_temperature_k is None and x.dew_point_uncertainty_k is None and x.equality_policy is None,"Direct/default water evidence cannot carry competing dew-point inputs")
+        state = "absent" if x.evidence == "qualified_no_free_water" else "present"
+    return {"free_water_screen_state":state,"free_water_assumed_from_missing_data":assumed}
+
+
+class CO2ScreenedAssessment(Model):
+    temperature_k: Positive
+    pressure: CO2PartialPressure
+    material: CO2MaterialScreen
+    hydrocarbon_wetting: CO2HydrocarbonWetting | None = None
+    moisture: CO2MoistureScreen | None = None
+    wet_model: CO2WetModel | None = None
+    qualification_basis: str = Field(min_length=1)
+
+
+def _zero():
+    return {"corrosion_rate_m_year":0.,"base_corrosion_rate_m_year":0.,"model_ph":None,"temperature_ph_factor":None,
+        "fugacity_pa":None,"requested_shear_stress_pa":None,"applied_shear_stress_pa":None,"shear_cap_applied":False,
+        "glycol_factor":1.,"inhibitor_factor":1.,"applied_reduction_factor":1.,"sharp_temperature_interval_interpolated":False}
+
+
+@calculation("damage/co2-screened-assessment", "CO2 material hydrocarbon moisture screening through corrosion model", CO2ScreenedAssessment,
+    ["Part2 Annex2.B §13,Figure2.B.13.1,Table2.B.13.1; PDF pp423-429"],origin="api581_composition_with_explicit_figure_policies",limitations=[
+        "Explicit 2016 material/HC-water-velocity/dew-point policies, source defaults and qualified wet model; no autonomous metallurgy or actual wetting/EOS judgment. Source resistance/exemption yields CO2-specific0 with flags, not measured immunity or zero total DF. Indeterminate moisture errors rather than asserts dry. Unused downstream inputs on screened branches rejected; no hidden model fallback. Low-Cr stainless figure evaluation is not silently reclassified low-alloy: current quantitative model supports only named carbon/low-alloy steel. Same pressure/temperature/known velocity drives screens and wet kernel. Explicit free-water evidence or source wet assumption supersedes approximate dew-point generation."])
+def screened_assessment(x):
+    ensure(bool(x.qualification_basis.strip()),"Screened model applicability basis required")
+    pressure = partial_pressure(x.pressure)
+    p = pressure["co2_partial_pressure_pa_abs"]
+    material = material_screen(x.material)
+    state = material["material_screen_decision"]
+    ensure(state != "not_covered","Material not covered by selected source screening interpretation")
+    water = {"wetting_screen_decision":None,"water_content_percent_used":None,"source_water_default_used":False}
+    moisture = {"free_water_screen_state":None,"free_water_assumed_from_missing_data":False}
+    if state == "source_assumed_resistant" or p == 0:
+        ensure(x.hydrocarbon_wetting is None and x.moisture is None and x.wet_model is None,"Material/no-CO2 branch cannot carry unused downstream model inputs")
+        result,branch = _zero(),"source_material_resistance" if state == "source_assumed_resistant" else "no_co2"
+    else:
+        ensure(x.hydrocarbon_wetting is not None,"Susceptible nonzero-CO2 case requires qualified HC/water screen")
+        water = hydrocarbon_screen(x.hydrocarbon_wetting)
+        if water["wetting_screen_decision"] == "figure_low_water_high_velocity_exemption":
+            ensure(x.moisture is None and x.wet_model is None,"Figure HC exemption cannot carry unused moisture/wet model")
+            result,branch = _zero(),"figure_hydrocarbon_exemption"
+        else:
+            ensure(x.moisture is not None,"Water check requires direct evidence, dew point or explicit source assumption")
+            ensure(x.moisture.temperature_k == x.temperature_k,"Moisture screen and model temperatures must agree")
+            moisture = moisture_screen(x.moisture)
+            ensure(moisture["free_water_screen_state"] != "indeterminate","Moisture uncertainty interval unresolved; no automatic zero corrosion","co2_moisture_indeterminate")
+            if moisture["free_water_screen_state"] == "absent":
+                ensure(x.wet_model is None,"Dry branch cannot contain unused wet-model inputs")
+                result,branch = _zero(),"qualified_no_free_water"
+            else:
+                ensure(x.material.material_category in ("carbon_steel","low_alloy_steel"),"Quantitative CO2 kernel does not reclassify low-Cr stainless as low-alloy steel")
+                if x.wet_model is not None and x.wet_model.flow.method == "turbulent_flow" and x.hydrocarbon_wetting.mixture_velocity_m_s is not None:
+                    ensure(x.wet_model.flow.mixture_velocity_m_s == x.hydrocarbon_wetting.mixture_velocity_m_s,"HC screen and wet flow velocities must agree")
+                result = assessment(CO2Assessment(material=x.material.material_category,temperature_k=x.temperature_k,co2_partial_pressure_pa_abs=p,
+                    free_liquid_water_present=True,applicability_basis=x.qualification_basis,wet_model=x.wet_model))
+                result.pop("calculation_branch")
+                branch = "wet_carbonic_acid_model"
+    return {**result,**pressure,**material,**water,**moisture,"screened_calculation_branch":branch}
+
+
+class CO2ScreenedThinning(Model):
+    corrosion: CO2ScreenedAssessment
+    starting_thickness_m: Positive
+    elapsed_years: NonNegative
+    strength: PressureStrength | CodeStrength = Field(discriminator="method")
+    inspections: Posterior
+    conditions: ThinningConditions
+    qualification_basis: str = Field(min_length=1)
+
+
+@calculation("damage/co2-screened-thinning", "Screened CO2 rate through non-AST unclad thinning DF", CO2ScreenedThinning,
+    ["Part2 Annex2.B §13,Figure2.B.13.1; Part2 §4.5.7"],origin="api581_composition_with_explicit_figure_policies",limitations=[
+        "Unclad non-AST component and owner-qualified strength/inspection baseline. Retains material/HC exemption, moisture uncertainty/default flags and source-specific rate through DF. Zero CO2 rate is not total DF0 or omission of other mechanisms. No independent confirmation of legacy material/wetting rules, oil-water phase distribution, chromium chemistry, actual moisture or field conditions."])
+def screened_thinning(x):
+    rate = screened_assessment(x.corrosion)
+    result = qualified_unclad(QualifiedUnclad(assessment_scope="non_ast_unclad",qualification_basis=x.qualification_basis,
+        wall=WallLoss(starting_thickness_m=x.starting_thickness_m,corrosion_rate_m_year=rate["corrosion_rate_m_year"],elapsed_years=x.elapsed_years),
+        strength=x.strength,inspections=x.inspections,conditions=x.conditions))
+    return {**rate,**result}

api581/consequences.py

@@ -0,0 +1,250 @@
+"""Level 1 toxic, NFNT, final area and financial consequence calculations."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+
+
+class Mitigation(Model):
+    system: Literal["inventory_blowdown", "deluge_and_monitors", "monitors", "foam", "none"]
+    isolation_class: Literal["A", "B", "C"]
+
+
+@calculation("level1/mitigation", "Flammable consequence mitigation factor", Mitigation,
+             ["Part 3 Table 4.10; PDF p525"], limitations=["Select one applicable measure; no unsupported combination/stacking of credits."])
+def mitigation(x):
+    ensure(x.system != "inventory_blowdown" or x.isolation_class in ("A","B"), "Blowdown credit requires isolation class A or B")
+    return {"mitigation_fraction": {"inventory_blowdown":.25,"deluge_and_monitors":.2,"monitors":.05,"foam":.15,"none":0}[x.system]}
+
+
+class ToxicSource(Model):
+    theoretical_rate_kg_s: NonNegative
+    released_mass_kg: NonNegative
+    toxic_mass_fraction: Fraction
+
+
+@calculation("level1/toxic-source", "Toxic component rate and mass", ToxicSource,
+             ["Part 3 eqs (3.61)-(3.62); PDF p497"], limitations=["Use theoretical rate, without flammable detection magnitude reduction. Explicit toxic mitigation, if justified, is a separate input adjustment."])
+def toxic_source(x):
+    return {"toxic_rate_kg_s": x.theoretical_rate_kg_s*x.toxic_mass_fraction,"toxic_mass_kg": x.released_mass_kg*x.toxic_mass_fraction}
+
+
+class ToxicDuration(Model):
+    available_mass_kg: NonNegative
+    theoretical_rate_kg_s: NonNegative
+    detection_maximum_duration_s: NonNegative
+
+
+@calculation("level1/toxic-duration", "Toxic release exposure duration", ToxicDuration,
+             ["Part 3 §4.9.10 eq (3.67)"], limitations=["One-hour cap; detection magnitude reduction does not apply to toxic source rate."])
+def toxic_duration(x):
+    duration = min(3600,x.detection_maximum_duration_s,x.available_mass_kg/x.theoretical_rate_kg_s) if x.theoretical_rate_kg_s else 0
+    return {"duration_s":duration}
+
+
+AMMONIA = [(636.7,1.183),(846.3,1.181),(1053,1.180),(1256,1.178),(1455,1.176),(1650,1.174),
+           (1842,1.172),(2029,1.169),(2213,1.166),(2389,1.161),(2558,1.155),(2714,1.145)]
+CHLORINE = [(3350,1.097),(3518,1.095),(3798,1.092),(4191,1.089),(4694,1.085),(5312,1.082),
+            (6032,1.077),(6860,1.072),(7788,1.066),(8798,1.057),(9890,1.046),(10994,1.026)]
+
+
+class ToxicArea(Model):
+    fluid: Literal["ammonia","chlorine"]
+    release_type: Literal["continuous","instantaneous"]
+    toxic_rate_kg_s: NonNegative
+    toxic_mass_kg: NonNegative
+    duration_s: NonNegative
+    nonignition_probability: Fraction
+
+
+@calculation("level1/toxic-area", "Ammonia/chlorine toxic consequence area", ToxicArea,
+             ["Part 3 eqs (3.65)-(3.66), §4.9.11, Table 4.12M; PDF pp498,526"],
+             limitations=["Continuous curves support 5-60 minutes only; interpolate areas between duration curves, never extrapolate. Explicit nonignition probability supplied; no IDLH screening or spray credit selection."])
+def toxic_area(x):
+    if (x.release_type=="continuous" and (x.toxic_rate_kg_s==0 or x.duration_s==0)) or (x.release_type=="instantaneous" and x.toxic_mass_kg==0):
+        return {"unweighted_personnel_area_m2":0,"personnel_area_m2":0}
+    if x.release_type=="instantaneous":
+        a,b = (2.684,.9011) if x.fluid=="ammonia" else (3.528,1.177)
+        area=a*x.toxic_mass_kg**b
+    else:
+        ensure(300<=x.duration_s<=3600,"Continuous toxic duration must be within table range 300-3600 s")
+        rows=AMMONIA if x.fluid=="ammonia" else CHLORINE
+        position=x.duration_s/300-1
+        lo,hi=math.floor(position),math.ceil(position)
+        a,b=rows[lo]; lower=a*x.toxic_rate_kg_s**b
+        a,b=rows[hi]; upper=a*x.toxic_rate_kg_s**b
+        area=lower+(upper-lower)*(position-lo)
+    return {"unweighted_personnel_area_m2":area,"personnel_area_m2":area*x.nonignition_probability}
+
+
+class Steam(Model):
+    adjusted_rate_kg_s: NonNegative
+    released_mass_kg: NonNegative
+
+
+@calculation("level1/steam-area", "Steam leak personnel consequence area", Steam,
+             ["Part 3 eqs (3.69)-(3.71),(3.76); Annex 3.B C9,C10; PDF pp502,647"], limitations=["Level 1 steam burn correlation; no equipment damage area."])
+def steam(x):
+    continuous=.123*x.adjusted_rate_kg_s
+    instantaneous=9.744*x.released_mass_kg**.6384
+    weight=min(x.adjusted_rate_kg_s/25.2,1)
+    return {"continuous_area_m2":continuous,"instantaneous_area_m2":instantaneous,"instantaneous_weight":weight,
+            "personnel_area_m2":instantaneous*weight+continuous*(1-weight),"equipment_area_m2":0}
+
+
+class Acid(Model):
+    adjusted_rate_kg_s: NonNegative
+    differential_pressure_pa: NonNegative
+
+
+@calculation("level1/acid-caustic-area", "Acid/caustic splash personnel consequence", Acid,
+             ["Part 3 eqs (3.72)-(3.75); Annex 3.B C4B,C8,C11; PDF pp502,647"],
+             limitations=["Empirical correlation developed at approximately 15,30,60 psig. Reject extrapolation outside 103.4-413.7 kPa differential. Source has inconsistent C4/C4B naming; uses lb/s conversion 2.205."])
+def acid(x):
+    ensure(103400<=x.differential_pressure_pa<=413700,"Acid splash pressure outside documented 103.4-413.7 kPa range")
+    pressure=.145*x.differential_pressure_pa/1000
+    g=2696-21.9*pressure+1.474*pressure**2
+    h=.31-.00032*(pressure-40)**2
+    area=.2*.0929*g*(2.205*x.adjusted_rate_kg_s)**h if x.adjusted_rate_kg_s else 0
+    return {"personnel_area_m2":area,"equipment_area_m2":0,"coefficient_g":g,"exponent_h":h}
+
+
+class FinalArea(Model):
+    flammable_equipment_area_m2: NonNegative
+    flammable_personnel_area_m2: NonNegative
+    toxic_personnel_areas_m2: list[NonNegative] = Field(max_length=100)
+    nfnt_personnel_area_m2: NonNegative
+
+
+@calculation("consequence/final-area", "Final Level 1 consequence areas", FinalArea,
+             ["Part 3 §§4.9.12,4.11 eqs (3.81)-(3.84)"], limitations=["Inputs must be evaluated on the same basis; multiple toxic species use maximum, not area addition."])
+def final_area(x):
+    toxic=max(x.toxic_personnel_areas_m2,default=0)
+    injury=max(x.flammable_personnel_area_m2,toxic,x.nfnt_personnel_area_m2)
+    return {"equipment_area_m2":x.flammable_equipment_area_m2,"personnel_area_m2":injury,
+            "consequence_area_m2":max(x.flammable_equipment_area_m2,injury)}
+
+
+class HoleValue(Model):
+    hole: Literal["small","medium","large","rupture"]
+    generic_frequency_per_year: NonNegative
+    value: NonNegative
+
+
+class Weighted(Model):
+    holes: list[HoleValue] = Field(min_length=4,max_length=4)
+    value_unit: str = Field(min_length=1,max_length=50)
+
+
+@calculation("consequence/hole-weighted", "Generic-frequency weighted four-hole consequence", Weighted,
+             ["Part 3 eqs (3.27)-(3.28),(3.68),(3.78),(3.86),(3.88),(3.94)"],
+             limitations=["All four holes required; value may be area, repair cost, outage or spill volume. Already conditional consequences; no second event weighting."])
+def hole_weighted(x):
+    ensure({h.hole for h in x.holes}=={"small","medium","large","rupture"},"Exactly one value per hole is required")
+    total=math.fsum(h.generic_frequency_per_year for h in x.holes)
+    ensure(total>0,"Total generic frequency must be positive")
+    return {"weighted_value":math.fsum(h.generic_frequency_per_year*h.value for h in x.holes)/total,"value_unit":x.value_unit}
+
+
+class SurroundingCost(Model):
+    equipment_area_m2: NonNegative
+    replacement_cost_per_m2: NonNegative
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+
+
+@calculation("financial/surrounding-damage", "Surrounding equipment damage cost", SurroundingCost,["Part 3 eq (3.87)"])
+def surrounding_cost(x):
+    return {"cost":x.equipment_area_m2*x.replacement_cost_per_m2,"currency":x.currency}
+
+
+class ProductionCost(Model):
+    component_outage_days: NonNegative
+    surrounding_outage_days: NonNegative
+    production_cost_per_day: NonNegative
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+
+
+@calculation("financial/production-loss", "Business interruption cost", ProductionCost,["Part 3 eq (3.90)"])
+def production_cost(x):
+    return {"cost":(x.component_outage_days+x.surrounding_outage_days)*x.production_cost_per_day,"currency":x.currency}
+
+
+class InjuryCost(Model):
+    personnel_area_m2: NonNegative
+    population_density_per_m2: NonNegative
+    cost_per_injury: NonNegative
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+
+
+@calculation("financial/injury", "Potential injury cost", InjuryCost,["Part 3 eq (3.91)"])
+def injury_cost(x):
+    return {"cost":x.personnel_area_m2*x.population_density_per_m2*x.cost_per_injury,"currency":x.currency}
+
+
+class Spill(Model):
+    released_mass_kg: NonNegative
+    liquid_density_kg_m3: Positive
+    evaporated_fraction: Fraction
+    cleanup_cost_per_m3: NonNegative
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+
+
+@calculation("financial/spill-cleanup", "Liquid spill remediation volume and cost", Spill,
+             ["Part 3 eqs (3.93)-(3.94), expressed in m3"], limitations=["Caller must screen liquid phase, boiling point and ignition eligibility; evaporation fraction supplied. Cost basis is per m3, not per barrel."])
+def spill(x):
+    volume=x.released_mass_kg/x.liquid_density_kg_m3*(1-x.evaporated_fraction)
+    return {"remediation_volume_m3":volume,"cost":volume*x.cleanup_cost_per_m3,"currency":x.currency}
+
+
+class HoleFinancial(Model):
+    """Financial consequence components for one API 581 release hole."""
+    hole: Literal["small", "medium", "large", "rupture"]
+    generic_frequency_per_year: NonNegative
+    component_repair_cost: NonNegative
+    surrounding_equipment_cost: NonNegative
+    business_interruption_cost: NonNegative
+    injury_cost: NonNegative
+    environmental_cost: NonNegative
+
+
+class FinancialByHole(Model):
+    """Four-hole financial consequence roll-up on one declared basis."""
+    holes: list[HoleFinancial] = Field(min_length=4, max_length=4)
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+    cost_basis_year: int = Field(ge=1900, le=2200)
+
+
+@calculation(
+    "financial/hole-total",
+    "Four-hole financial consequence and annual risk roll-up",
+    FinancialByHole,
+    ["Part 3 §§4.11-4.12; eqs (3.86)-(3.94)"],
+    limitations=[
+        "All five cost categories are caller-qualified on one currency and cost basis year.",
+        "Per-hole generic frequencies must be disjoint and already include the applicable GFF basis; no second ignition or weather weighting is applied.",
+        "The API does not infer damage applicability, release hydraulics, cleanup unit costs, or currency escalation.",
+    ],
+)
+def financial_by_hole(x: FinancialByHole):
+    ensure(
+        {item.hole for item in x.holes} == {"small", "medium", "large", "rupture"},
+        "Exactly one financial row for each of the four holes is required",
+    )
+    total_frequency = math.fsum(item.generic_frequency_per_year for item in x.holes)
+    ensure(total_frequency > 0, "Total generic frequency must be positive")
+    rows = []
+    for item in x.holes:
+        total = math.fsum((item.component_repair_cost, item.surrounding_equipment_cost,
+                           item.business_interruption_cost, item.injury_cost,
+                           item.environmental_cost))
+        rows.append({"hole": item.hole, "generic_frequency_per_year": item.generic_frequency_per_year,
+                     "financial_consequence": total})
+    annual = math.fsum(row["generic_frequency_per_year"] * row["financial_consequence"] for row in rows)
+    return {
+        "currency": x.currency,
+        "cost_basis_year": x.cost_basis_year,
+        "total_generic_frequency_per_year": total_frequency,
+        "per_hole": rows,
+        "frequency_weighted_financial_consequence": annual / total_frequency,
+        "annual_financial_risk": annual,
+    }