api581-engine 0.1.4__py3-none-any.whl

api581/oxidation.py

@@ -0,0 +1,145 @@
+"""2016 high-temperature oxidation tables, screen and non-AST thinning."""
+from bisect import bisect_left
+from typing import Literal
+from pydantic import Field
+from .core import Model, Positive, NonNegative, calculation, ensure
+from .thinning import Posterior, WallLoss
+from .clad_thinning import PressureStrength, CodeStrength
+from .thinning_conditions import ThinningConditions, QualifiedUnclad, qualified_unclad
+
+Material = Literal["carbon_steel","cr_1_25","cr_2_25","cr_5","cr_7","cr_9","cr_12","ss_304","ss_309","ss_310_hk","alloy_800h_hp"]
+Units = Literal["printed_si","printed_us_converted"]
+_C = (496,524,552,579,607,635,663,691,718,746,774,802,829,857,885,913,941,968,996,1024,1052,1079,1107,1135)
+_F = tuple(range(925,2076,50))
+_US = (
+    (2,4,6,9,14,22,33,48),
+    (2,3,4,7,12,18,30,46),
+    (1,1,2,4,9,14,24,41),
+    (1,1,1,2,4,6,15,35,65),
+    (1,1,1,1,1,2,3,6,17,37,60),
+    (1,1,1,1,1,1,1,2,5,11,23,40,60),
+    (1,1,1,1,1,1,1,1,3,8,15,30,50),
+    (1,1,1,1,1,1,1,1,1,2,3,4,6,9,13,18,25,35,48),
+    (1,1,1,1,1,1,1,1,1,1,2,3,4,6,8,10,13,16,20,30,40,50),
+    (1,1,1,1,1,1,1,1,1,1,1,2,3,4,5,7,8,10,13,15,19,23,27,31),
+    (1,1,1,1,1,1,1,1,1,1,1,2,3,4,6,8,10,13,17,21,27,33,41,50))
+_SI = (
+    (.05,.1,.15,.23,.36,.56,.84,1.22),
+    (.05,.08,.1,.18,.3,.46,.76,1.17),
+    (.03,.03,.05,.1,.23,.36,.61,1.04),
+    (.03,.03,.03,.05,.1,.15,.38,.89,1.65),
+    (.03,.03,.03,.03,.03,.05,.08,.15,.43,.94,1.52),
+    (.03,.03,.03,.03,.03,.03,.03,.05,.13,.28,.58,1.02,1.52),
+    (.03,.03,.03,.03,.03,.03,.03,.03,.08,.2,.38,.76,1.27),
+    (.03,.03,.03,.03,.03,.03,.03,.03,.03,.05,.08,.1,.15,.23,.33,.46,.64,.89,1.22),
+    (.03,.03,.03,.03,.03,.03,.03,.03,.03,.03,.05,.08,.1,.15,.2,.25,.33,.41,.51,.76,1.02,1.27),
+    (.03,.03,.03,.03,.03,.03,.03,.03,.03,.03,.03,.05,.08,.1,.13,.18,.2,.25,.33,.38,.48,.58,.69,.79),
+    (.03,.03,.03,.03,.03,.03,.03,.03,.03,.03,.03,.05,.08,.1,.15,.2,.25,.33,.43,.53,.69,.84,1.04,1.27))
+
+
+class OxidationScreen(Model):
+    maximum_metal_temperature_k: Positive
+    oxygen_present: bool
+    threshold_basis: Units
+
+
+@calculation("damage/oxidation-screen", "High-temperature oxidation temperature and oxygen screening", OxidationScreen,
+    ["Part2 Annex2.B Table1.1,§9.1; PDF pp322,389"],limitations=[
+        "Annex screen requires metal temperature>=482C(900F) AND oxygen present. Printed SI482C differs from exact900F conversion: basis explicit. Screening out does not assert rate0 or no other damage; description says onset approximately482C forCS and higher for alloys. Maximum METAL temperature controls, including furnace tube metal, not bulk gas/fluid temperature."])
+def screen(x):
+    threshold = 482+273.15 if x.threshold_basis == "printed_si" else (900-32)*5/9+273.15
+    return {"screen_temperature_threshold_k":threshold,"temperature_screen_met":x.maximum_metal_temperature_k >= threshold,
+        "evaluate_high_temperature_oxidation":x.maximum_metal_temperature_k >= threshold and x.oxygen_present}
+
+
+class OxidationTableRow(Model):
+    material: Material
+    unit_basis: Units
+
+
+@calculation("damage/oxidation-table-row", "Full oxidation table row with explicit unavailable cells", OxidationTableRow,
+    ["Part2 Tables2.B.9.2/9.2M/9.3/9.3M; PDF pp390-391"],limitations=[
+        "11 named material rows,24 temperature columns,SI andUS. Combined source material labels310SS/HK and800H/HP preserved as grouped categories, not arbitrary alloy equivalence. Rounded SI temperatures/rates differ from exact US conversions. Printed dashes returnedNone, never0 or material failure-temperature certification. No continuous interpolation in chromium composition."])
+def table_row(x):
+    i = Material.__args__.index(x.material)
+    native = (_SI if x.unit_basis == "printed_si" else _US)[i]
+    rates = list(native)+[None]*(24-len(native))
+    nodes = [c+273.15 for c in _C] if x.unit_basis == "printed_si" else [(f-32)*5/9+273.15 for f in _F]
+    conversion = .001 if x.unit_basis == "printed_si" else .0000254
+    return {"temperature_nodes_k":nodes,"corrosion_rates_m_year":[v*conversion if v is not None else None for v in rates],
+        "native_rates":rates,"native_rate_unit":"mm/year" if x.unit_basis == "printed_si" else "mpy",
+        "source_table_ids":["2.B.9.2M","2.B.9.3M"] if x.unit_basis == "printed_si" else ["2.B.9.2","2.B.9.3"]}
+
+
+class OxidationRate(OxidationTableRow):
+    maximum_metal_temperature_k: Positive
+    lookup_policy: Literal["exact_nodes_only","linear_between_nodes","upper_temperature_node"]
+    below_table_policy: Literal["reject_below_table","qualified_first_node_value"]
+    first_node_qualification_basis: str | None = None
+
+
+@calculation("damage/oxidation-rate", "Material and maximum-metal-temperature oxidation rate", OxidationRate,
+    ["Part2 §9.3,Tables2.B.9.2-9.3M; PDF pp389-391"],limitations=[
+        "No source interpolation rule: exact,linear or upper-temperature-node numerical policy must be selected. No high-temperature extrapolation or interpolation touching unavailable dash. Below first printed node496C/925F is rejected or explicitly qualified first-node estimate; source screening begins482C/900F, does not supply this gap's rate. First-node policy not a zero/ambient-corrosion assumption. Adjacent tables are joined only where both bordering cells exist. Primitive lookup does not itself qualify oxygen or actual metal-temperature identification."])
+def rate(x):
+    qualified = x.below_table_policy == "qualified_first_node_value"
+    ensure((x.first_node_qualification_basis is not None and bool(x.first_node_qualification_basis.strip())) if qualified else x.first_node_qualification_basis is None,
+        "First-node policy and qualification basis must agree")
+    row = table_row(x)
+    nodes,values = row["temperature_nodes_k"],row["corrosion_rates_m_year"]
+    t = next((n for n in nodes if abs(n-x.maximum_metal_temperature_k) <= 1e-9),x.maximum_metal_temperature_k)
+    ensure(t <= nodes[-1],"Temperature exceeds oxidation table; no extrapolation","oxidation_table_range")
+    first = t < nodes[0]
+    ensure(not first or qualified,"Temperature below first oxidation row; explicit qualified estimate required","oxidation_table_range")
+    if first:
+        lo = hi = 0
+        weight,basis = 0.,"qualified_first_node"
+    else:
+        hi = bisect_left(nodes,t)
+        lo = hi if t == nodes[hi] else hi-1
+        weight = 0. if lo == hi else (t-nodes[lo])/(nodes[hi]-nodes[lo])
+        ensure(lo == hi or x.lookup_policy != "exact_nodes_only","Exact oxidation-node policy does not interpolate")
+        basis = "exact_cell" if lo == hi else "upper_temperature_node" if x.lookup_policy == "upper_temperature_node" else "linear_between_nodes"
+    ensure(values[lo] is not None and values[hi] is not None,"Oxidation table cell unavailable; no zero or dash interpolation","oxidation_rate_unavailable")
+    value = values[hi] if basis == "upper_temperature_node" else values[lo]+weight*(values[hi]-values[lo])
+    return {"corrosion_rate_m_year":value,"lower_temperature_node_k":nodes[lo],"upper_temperature_node_k":nodes[hi],
+        "interpolation_weight":weight,"rate_calculation_basis":basis,"first_node_value_used":first}
+
+
+class OxidationAssessment(Model):
+    oxidation: OxidationRate
+    oxygen_present: bool
+    screening_threshold_basis: Units
+    applicability_basis: str = Field(min_length=1)
+
+
+@calculation("damage/oxidation-assessment", "Screened qualified maximum-metal-temperature oxidation estimate", OxidationAssessment,
+    ["Part2 Annex2.B Table1.1,§9,Tables2.B.9.2-9.3M; PDF pp322,389-391"],origin="api581_composition_with_explicit_table_policy",limitations=[
+        "Owner qualifies named material, oxygen and actual maximum exposed metal temperature. Screen-out rejects quantitative estimate instead of reporting invented rate0. One assessed surface/exposure; no implicit second-side loss or duplicate atmospheric/CUI corrosion DF. Source calls oxidation general thinning. Does not evaluate creep, thermal fatigue, oxide spallation cycling, carburization/sulfidation, metallurgy, service suitability or total damage."])
+def oxidation_assessment(x):
+    ensure(bool(x.applicability_basis.strip()),"Oxygen/material/maximum-metal-temperature qualification basis required")
+    screened = screen(OxidationScreen(maximum_metal_temperature_k=x.oxidation.maximum_metal_temperature_k,oxygen_present=x.oxygen_present,threshold_basis=x.screening_threshold_basis))
+    ensure(screened["evaluate_high_temperature_oxidation"],"Oxidation screening criteria not met; no quantitative zero rate inferred")
+    return {**screened,**rate(x.oxidation),"thinning_type":"general"}
+
+
+class OxidationThinning(Model):
+    corrosion: OxidationAssessment
+    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/oxidation-thinning-assessment", "Oxidation rate through qualified non-AST unclad thinning DF", OxidationThinning,
+    ["Part2 Annex2.B §9; Part2 §4.5.7"],origin="api581_composition_with_explicit_table_policy",limitations=[
+        "Same qualified oxidation rate drives single constant-baseline unclad non-AST thinning. Strength/allowable stress/flow stress/minimum thickness must be qualified at governing design temperature; no room-temperature strength assumption. Monitoring row must be other, table factor1; qualified experience replacement remains available underTable4.8 note1. Liquid-corrosion rows cannot supply borrowed credits. Inspection eligibility needs owner qualification for oxidation. No AST/cladding, automatic creep/high-temperature code evaluation, FFS or all-mechanism DF."])
+def oxidation_thinning(x):
+    ensure(x.conditions.monitoring.row.mechanism == "other","Oxidation uses other-mechanism monitoring row; liquid-corrosion credits cannot be borrowed")
+    corrosion = oxidation_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=corrosion["corrosion_rate_m_year"],elapsed_years=x.elapsed_years),
+        strength=x.strength,inspections=x.inspections,conditions=x.conditions))
+    return {**corrosion,**result}

api581/pascc_screening.py

@@ -0,0 +1,78 @@
+"""PASCC sulfur-exposure/material screen; shutdown mitigation is not screening."""
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, calculation, ensure
+from .scc_mechanisms import PasccSusceptibility, pascc_susceptibility, Assessment, InspectionCounts, assess
+
+
+class PasccScreen(Model):
+    material: Literal['austenitic_stainless_steel','nickel_based_alloy','other_material']
+    sulfur_bearing_compounds_exposure: bool
+    exposure_basis: str = Field(min_length=1)
+
+
+@calculation('damage/pascc-screening','PASCC austenitic stainless/nickel alloy sulfur exposure screen',PasccScreen,
+    ['Part2 §11.3; PDF p201'],limitations=[
+        'Austenitic stainless steel or nickel-based alloy exposed to sulfur-bearing compounds requires PASCC susceptibility evaluation. No automatic exclusion for normal-operation dryness, low-carbon/stabilized grade, low operating temperature, alkaline wash or nitrogen purge; shutdown air/moisture and mitigation remain separate evaluation. Material category does not authorize every Table11.2 cell. Screen-out is outside this procedure, not global immunity or zero DF.'])
+def pascc_screening(x):
+    ensure(bool(x.exposure_basis.strip()),'Qualified alloy identity and sulfur exposure history basis required')
+    material=x.material!='other_material'
+    return {'evaluate_pascc':material and x.sulfur_bearing_compounds_exposure,
+        'screening_reason':'outside_material_scope' if not material else 'sulfur_exposure_absent' if not x.sulfur_bearing_compounds_exposure else 'evaluate'}
+
+
+class PasccFigure(Model):
+    alloy: PasccSusceptibility
+    sulfur_oxygen_water_during_operation: bool
+    sulfur_oxygen_water_during_shutdown: bool
+    qualified_rp0170_downtime_protection: bool
+    protection_basis: str | None = None
+    confirmed_cracking: bool
+    unrepaired_cracks: bool
+    service_alloy_basis: str = Field(min_length=1)
+
+
+@calculation('damage/pascc-figure-susceptibility','PASCC Figure11.1 exposure and qualified downtime protection',PasccFigure,
+    ['Part2 Figure11.1,Table11.2; PDF pp205-206'],limitations=[
+        'Caller qualifies simultaneous sulfur/oxygen/water exposure in operation/shutdown and Table11.2 alloy/thermal history. No exposure in either phase returns none without table lookup. RP0170 downtime protection, when qualified, reduces table susceptibility one level high->medium->low->none exactly as Figure11.1. Confirmed cracks forcehigh before exposure/protection; unrepaired cracks requireFFS. No RP0170 compliance verification or automatic shutdown exposure inference. Existing SI427C table threshold/unsupported cells retained.'])
+def pascc_figure_susceptibility(x):
+    ensure(not x.unrepaired_cracks,'Unrepaired PASCC requires separate FFS evaluation','ffs_required')
+    ensure(bool(x.service_alloy_basis.strip()),'Qualified alloy/thermal history and operation/shutdown exposure basis required')
+    ensure((x.protection_basis is not None)==x.qualified_rp0170_downtime_protection,'Downtime protection and basis must agree')
+    if x.protection_basis is not None:
+        ensure(bool(x.protection_basis.strip()),'Downtime protection basis must be nonblank')
+    if x.confirmed_cracking:
+        base,selected,used='high','high',False
+    elif not (x.sulfur_oxygen_water_during_operation or x.sulfur_oxygen_water_during_shutdown):
+        base,selected,used='none','none',False
+    else:
+        base=pascc_susceptibility(x.alloy)['susceptibility']
+        levels=('none','low','medium','high')
+        used=x.qualified_rp0170_downtime_protection
+        selected=levels[max(0,levels.index(base)-int(used))]
+    return {'table_or_override_susceptibility':base,'susceptibility':selected,'downtime_reduction_applied':used}
+
+
+class PasccQualifiedAssessment(Model):
+    screening: PasccScreen
+    service: PasccFigure
+    years_since_qualifying_inspection: NonNegative
+    inspections: InspectionCounts
+    inspection_basis: str = Field(min_length=1)
+
+
+@calculation('damage/pascc-qualified-assessment','PASCC screen/Figure11.1 through inspection and age DF',PasccQualifiedAssessment,
+    ['Part2 §§11.3,11.6.3,Figure11.1,Tables11.2-11.3; eq(2.30); PDF pp201-206'],
+    origin='qualified_pascc_exposure_protection_to_df',limitations=[
+        'Requires positive material/sulfur screen and independent alloy-group identity/thermal-history qualification. Nickel-family screening cannot use H/L-grade300SS or321SS table groups. Mixed-named table groups require owner matching, not automatic grade inference. Figure11.1 exposures/protection and mechanism-specific inspection period remain explicit. Confirmed cracks override mitigation; unrepairedFFS. Existing equivalent-count/age rules retained. No whole-asset risk or FFS.'])
+def pascc_qualified_assessment(x):
+    selected=pascc_figure_susceptibility(x.service)
+    ensure(bool(x.inspection_basis.strip()),'PASCC-specific inspection period and coverage basis required')
+    screen=pascc_screening(x.screening)
+    ensure(screen['evaluate_pascc'],'PASCC material/sulfur screen not met','pascc_outside_screen')
+    if x.screening.material=='nickel_based_alloy':
+        ensure(x.service.alloy.material_group not in ('h_grade_300ss','l_grade_300ss','321ss'),
+            'Nickel family contradicts stainless-only table group','pascc_material_mismatch')
+    result=assess('pascc',Assessment(susceptibility=selected['susceptibility'],confirmed_cracking=x.service.confirmed_cracking,
+        unrepaired_cracks=False,years_since_qualifying_inspection=x.years_since_qualifying_inspection,inspections=x.inspections))
+    return {**screen,**selected,**result}

api581/physical_explosion.py

@@ -0,0 +1,190 @@
+"""Physical explosion/BLEVE and Level2 NFNT aggregation in explicit SI units."""
+import math
+from typing import Annotated, Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+from .blast import (BlastFitDomain, BlastDistance, distance,
+                    BuildingPressureThreshold, building_threshold)
+
+Hole = Literal["small", "medium", "large", "rupture"]
+Gamma = Annotated[float,Field(gt=1,strict=True,allow_inf_nan=False)]
+
+
+class RuptureConditions(Model):
+    burst_pressure_pa_abs: Positive
+    ambient_pressure_pa_abs: Positive = 101325
+
+
+def _pressure_difference(x):
+    ensure(x.burst_pressure_pa_abs >= x.ambient_pressure_pa_abs,
+           "Burst pressure must be at least ambient absolute pressure")
+    return x.burst_pressure_pa_abs-x.ambient_pressure_pa_abs
+
+
+class PhysicalTnt(RuptureConditions):
+    vapor_volume_m3: NonNegative
+    heat_capacity_ratio: Gamma
+
+
+@calculation("effects/physical-explosion-tnt", "Gas-vessel Brode energy and TNT equivalent", PhysicalTnt,
+             ["Part3 eq(3.192), Annex3.B C29; PDF pp569,648; pressure units PDF578"],
+             limitations=["C29=4.303e-4 with source pressures in kPa; Pa inputs therefore use4.303e-7 kg/J. Uses vapor space volume, not total two-phase vessel volume. k>1, absolute burst pressure>=ambient. Returns potential rupture energy, not ignition-dependent combustion energy; no real-gas or vessel fragmentation calculation."])
+def physical_tnt(x):
+    delta=_pressure_difference(x)
+    energy=x.vapor_volume_m3*delta/(x.heat_capacity_ratio-1)
+    equivalent=4.303e-7*energy
+    ensure(math.isfinite(energy) and math.isfinite(equivalent),"Physical rupture energy exceeds numerical domain","numerical_failure")
+    ensure(equivalent > 0 or delta == 0 or x.vapor_volume_m3 == 0,
+           "Physical rupture energy underflow","numerical_failure")
+    return {"vapor_stored_energy_j":energy,"tnt_equivalent_mass_kg":equivalent}
+
+
+class FlashedAmount(Model):
+    stored_liquid_mass_kg: NonNegative
+    liquid_flash_mass_fraction: Fraction
+    molecular_weight_kg_kmol: Positive
+
+
+@calculation("release/bleve-flashed-amount", "Flashed liquid mass and amount for BLEVE", FlashedAmount,
+             ["Part3 STEP10.3(1), nomenclature nv/MW; PDF pp571,576"],
+             origin="api581_input_preparation",
+             limitations=["Caller supplies liquid flash mass fraction qualified at atmospheric release; this is not an EOS/isenthalpic flash solver. Amount is kmol (source kg-mol), not mol. Only stored liquid is counted; pre-existing vapor is handled separately."])
+def flashed_amount(x):
+    mass=x.stored_liquid_mass_kg*x.liquid_flash_mass_fraction
+    amount=mass/x.molecular_weight_kg_kmol
+    ensure(math.isfinite(amount),"Flashed amount exceeds numerical domain","numerical_failure")
+    ensure(amount > 0 or x.stored_liquid_mass_kg == 0 or x.liquid_flash_mass_fraction == 0,
+           "Flashed amount underflow","numerical_failure")
+    return {"flashed_liquid_mass_kg":mass,"flashed_amount_kmol":amount}
+
+
+class BleveLiquidTnt(RuptureConditions):
+    flashed_amount_kmol: NonNegative
+    storage_temperature_k: Positive
+
+
+@calculation("effects/bleve-liquid-tnt", "Flashed-liquid BLEVE expansion energy and TNT equivalent", BleveLiquidTnt,
+             ["Part3 eq(3.195), Annex3.B C30; PDF pp569,648; nv/R units PDF576,578"],
+             limitations=["Uses printed C30=9.76e-8 kg/J and R=8314 J/(kmol*K), nv in kmol, storage temperature K, natural log of absolute burst/ambient pressure. Does not infer flash amount from fluid properties. Vapor-space contribution is excluded and must be added separately for two-phase contents. No combustion/fireball energy included."])
+def bleve_liquid_tnt(x):
+    delta=_pressure_difference(x)
+    # log1p preserves tiny positive overpressure; logarithm difference avoids
+    # overflow of the pressure ratio for widely separated positive pressures.
+    log_ratio=(math.log1p(delta/x.ambient_pressure_pa_abs) if delta <= x.ambient_pressure_pa_abs
+               else math.log(x.burst_pressure_pa_abs)-math.log(x.ambient_pressure_pa_abs))
+    energy=x.flashed_amount_kmol*8314*x.storage_temperature_k*log_ratio
+    equivalent=9.76e-8*energy
+    ensure(math.isfinite(energy) and math.isfinite(equivalent),"BLEVE expansion energy exceeds numerical domain","numerical_failure")
+    ensure(equivalent > 0 or delta == 0 or x.flashed_amount_kmol == 0,
+           "BLEVE expansion energy underflow","numerical_failure")
+    return {"liquid_expansion_energy_j":energy,"tnt_equivalent_mass_kg":equivalent}
+
+
+class BlastTargets(Model):
+    hole: Hole
+    fit_domain: BlastFitDomain
+    personnel_building_collapse_probability: Fraction = .5
+    equipment_threshold_overpressure_pa: Positive = 34500
+    distance_tolerance_m: Positive = 1e-5
+    maximum_iterations: int = Field(default=100,ge=10,le=300,strict=True)
+
+
+def _targets(x,potential):
+    event=potential if x.hole == "rupture" else 0
+    pressure=building_threshold(BuildingPressureThreshold(
+        building_collapse_probability=x.personnel_building_collapse_probability))["side_on_overpressure_pa"]
+    setup=dict(tnt_equivalent_mass_kg=event,fit_domain=x.fit_domain,
+        distance_tolerance_m=x.distance_tolerance_m,maximum_iterations=x.maximum_iterations)
+    personnel=distance(BlastDistance(**setup,threshold_overpressure_pa=pressure))
+    equipment=distance(BlastDistance(**setup,threshold_overpressure_pa=x.equipment_threshold_overpressure_pa))
+    return {"potential_tnt_equivalent_mass_kg":potential,"event_tnt_equivalent_mass_kg":event,
+            "personnel_threshold_overpressure_pa":pressure,"equipment_threshold_overpressure_pa":x.equipment_threshold_overpressure_pa,
+            "personnel_building_collapse_probability":x.personnel_building_collapse_probability,
+            "personnel_safe_distance_m":personnel["safe_distance_m"],"equipment_safe_distance_m":equipment["safe_distance_m"],
+            "personnel_area_m2":personnel["consequence_area_m2"],"equipment_area_m2":equipment["consequence_area_m2"],
+            "personnel_status":personnel["status"] if x.hole == "rupture" else "not_rupture",
+            "equipment_status":equipment["status"] if x.hole == "rupture" else "not_rupture","hole":x.hole}
+
+
+class PhysicalConsequence(PhysicalTnt,BlastTargets):
+    pass
+
+
+@calculation("effects/physical-explosion-consequence", "Gas-vessel rupture blast consequence", PhysicalConsequence,
+             ["Part3 eqs(3.192)-(3.194), STEP10.2; PDF pp569-571"],
+             origin="api581_physical_explosion_composition",
+             limitations=["Only rupture hole produces blast area; other holes return not_rupture with zero event equivalent and area while retaining potential inventory rupture energy. Personnel default is probit5 (50% building collapse), equipment default34500Pa. Reuses caller-qualified TNT fit domain; no extrapolation, direct lethality, fragmentation or LH2 validation."])
+def physical_consequence(x):
+    energy=physical_tnt(PhysicalTnt(**x.model_dump(include=set(PhysicalTnt.model_fields))))
+    return {"vapor_stored_energy_j":energy["vapor_stored_energy_j"],**_targets(x,energy["tnt_equivalent_mass_kg"])}
+
+
+class VaporPortion(Model):
+    vapor_volume_m3: NonNegative
+    heat_capacity_ratio: Gamma
+
+
+class BleveConsequence(BleveLiquidTnt,BlastTargets):
+    stored_vapor: VaporPortion | None = None
+
+
+@calculation("effects/bleve-consequence", "Liquid/two-phase BLEVE blast consequence", BleveConsequence,
+             ["Part3 eqs(3.192),(3.195)-(3.197), STEP10.3; PDF pp569-572"],
+             origin="api581_bleve_composition",
+             limitations=["Sums liquid and pre-existing vapor TNT equivalents using their distinct printed C30/C29 coefficients. Shared absolute burst/ambient pressure; vapor volume must exclude liquid, flashed amount must exclude pre-existing vapor. No automatic EOS, superheat applicability, fireball or combustion calculation. Only rupture produces blast area. Caller-qualified fit domain and building-collapse proxy limits apply; LH2 validation outstanding."])
+def bleve_consequence(x):
+    liquid=bleve_liquid_tnt(BleveLiquidTnt(**x.model_dump(include=set(BleveLiquidTnt.model_fields))))
+    vapor={"vapor_stored_energy_j":0,"tnt_equivalent_mass_kg":0}
+    if x.stored_vapor is not None:
+        vapor=physical_tnt(PhysicalTnt(**x.stored_vapor.model_dump(),burst_pressure_pa_abs=x.burst_pressure_pa_abs,
+            ambient_pressure_pa_abs=x.ambient_pressure_pa_abs))
+    total=liquid["tnt_equivalent_mass_kg"]+vapor["tnt_equivalent_mass_kg"]
+    ensure(math.isfinite(total),"Combined BLEVE TNT equivalent exceeds numerical domain","numerical_failure")
+    return {"liquid_expansion_energy_j":liquid["liquid_expansion_energy_j"],"vapor_stored_energy_j":vapor["vapor_stored_energy_j"],
+            "liquid_tnt_equivalent_mass_kg":liquid["tnt_equivalent_mass_kg"],"vapor_tnt_equivalent_mass_kg":vapor["tnt_equivalent_mass_kg"],
+            **_targets(x,total)}
+
+
+class NfntCase(Model):
+    hole: Hole
+    non_ignition_probability: Fraction
+    physical_equipment_area_m2: NonNegative = 0
+    physical_personnel_area_m2: NonNegative = 0
+    bleve_equipment_area_m2: NonNegative = 0
+    bleve_personnel_area_m2: NonNegative = 0
+    steam_chemical_personnel_area_m2: NonNegative = 0
+
+
+@calculation("consequence/level2-nfnt-case", "Level2 NFNT maximum areas and non-ignition weighting", NfntCase,
+             ["Part3 eqs(3.198)-(3.199), §5.10.5; PDF p570"],
+             limitations=["Inputs are event-conditional unweighted areas. Uses maximum, not sum, then applies non-ignition probability once. Physical/BLEVE areas must be zero for non-rupture holes. Steam/chemical area can be supplied by Level1 NFNT calculation. This does not infer event-tree probabilities."])
+def nfnt_case(x):
+    ensure(x.hole == "rupture" or not any((x.physical_equipment_area_m2,x.physical_personnel_area_m2,
+        x.bleve_equipment_area_m2,x.bleve_personnel_area_m2)),"Physical/BLEVE areas must be zero outside rupture case")
+    equipment=max(x.physical_equipment_area_m2,x.bleve_equipment_area_m2)
+    personnel=max(x.physical_personnel_area_m2,x.bleve_personnel_area_m2,x.steam_chemical_personnel_area_m2)
+    return {"equipment_area_m2":x.non_ignition_probability*equipment,"personnel_area_m2":x.non_ignition_probability*personnel}
+
+
+class NfntFrequencyCase(NfntCase):
+    generic_frequency_per_year: NonNegative
+
+
+class NfntSummary(Model):
+    cases: list[NfntFrequencyCase] = Field(min_length=4,max_length=4)
+
+
+@calculation("consequence/level2-nfnt-summary", "Four-hole Level2 NFNT GFF-weighted final areas", NfntSummary,
+             ["Part3 eqs(3.198)-(3.201); PDF p570"],
+             origin="api581_nfnt_four_hole_composition",
+             limitations=["Requires small,medium,large,rupture once each, including zero-frequency holes. Weights per-case non-ignition-adjusted maximum areas by supplied generic frequencies, not DF-adjusted failure frequencies. No annual risk or financial consequence is computed by this area average."])
+def nfnt_summary(x):
+    ensure({c.hole for c in x.cases} == {"small","medium","large","rupture"},"Require four distinct canonical hole sizes")
+    total=math.fsum(c.generic_frequency_per_year for c in x.cases)
+    ensure(math.isfinite(total) and total > 0,"Total generic frequency must be finite and positive")
+    areas={c.hole:nfnt_case(NfntCase(**c.model_dump(exclude={"generic_frequency_per_year"}))) for c in x.cases}
+    return {"total_generic_frequency_per_year":total,
+            "equipment_area_m2":math.fsum(c.generic_frequency_per_year/total*areas[c.hole]["equipment_area_m2"] for c in x.cases),
+            "personnel_area_m2":math.fsum(c.generic_frequency_per_year/total*areas[c.hole]["personnel_area_m2"] for c in x.cases),
+            "by_hole_equipment_area_m2":{h:v["equipment_area_m2"] for h,v in areas.items()},
+            "by_hole_personnel_area_m2":{h:v["personnel_area_m2"] for h,v in areas.items()}}

api581/pof.py

@@ -0,0 +1,207 @@
+"""Part 1 frequency/reliability and Part 2 governing factor calculations."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, Positive, NonNegative, Fraction, calculation, ensure
+
+HOLES = ("small", "medium", "large", "rupture")
+STANDARD = (8e-6, 2e-5, 2e-6, 6e-7)
+GFF = {k: STANDARD for k in ["COMPR", "HEXSS", "HEXTS", "PIPE-8", "PIPE-10", "PIPE-12",
+       "PIPE-16", "PIPEGT16", "PUMP2S", "PUMPR", "PUMP1S", "KODRUM", "COLBTM", "FINFAN",
+       "FILTER", "DRUM", "REACTOR", "COLTOP", "COLMID"]}
+GFF.update({"COMPC": (8e-6, 2e-5, 2e-6, 0), "PIPE-1": (2.8e-5, 0, 0, 2.6e-6),
+            "PIPE-2": (2.8e-5, 0, 0, 2.6e-6), "PIPE-4": (8e-6, 2e-5, 0, 2.6e-6),
+            "PIPE-6": (8e-6, 2e-5, 0, 2.6e-6)})
+
+
+class Component(Model):
+    component_type: str
+
+
+@calculation("frequency/generic", "Component generic failure frequencies", Component,
+             ["Part 2 Table 3.1; PDF p147"], limitations=["Non-tank lookup. Tank rows with differing printed/summed totals are exposed separately by tank/generic-frequency using eq3.208. HEXTUBE is not a 2016 table entry."])
+def generic(x):
+    ensure(x.component_type in GFF, f"Unsupported component_type; supported: {', '.join(GFF)}")
+    values = GFF[x.component_type]
+    return {"by_hole_per_year": dict(zip(HOLES, values)), "total_per_year": math.fsum(values)}
+
+
+class Management(Model):
+    score: NonNegative = Field(le=1000)
+
+
+@calculation("frequency/management-factor", "Management systems factor", Management,
+             ["Part 2 §3.5.4 eqs (2.9)-(2.10); PDF p145"])
+def management(x):
+    percent = x.score / 10
+    return {"score_percent": percent, "management_factor": 10 ** (1 - .02 * percent)}
+
+
+class Frequency(Model):
+    generic_frequency_per_year: NonNegative
+    total_damage_factor: NonNegative
+    management_factor: Positive
+
+
+@calculation("frequency/adjusted", "Damage-adjusted annual failure frequency", Frequency,
+             ["Part 1 eq (1.1); Part 2 eq (2.1)"], limitations=["DF is supplied by caller; this endpoint does not assess damage applicability."])
+def adjusted(x):
+    return {"annual_failure_frequency": x.generic_frequency_per_year * x.total_damage_factor * x.management_factor,
+            "unit": "1/year"}
+
+
+class PofMethodSelection(Model):
+    method: Literal["structural_reliability", "statistical_generic_data", "expert_judgment", "combined"]
+    qualification_basis: str = Field(min_length=1, max_length=1000)
+    uncertainty_quantified: bool
+
+
+@calculation(
+    "frequency/pof-method-selection",
+    "Probability-of-failure methodology selection",
+    PofMethodSelection,
+    ["Part 2 §3.2; PDF p142"],
+    limitations=[
+        "Records the API 581 method route and qualification evidence; it does not calculate a structural reliability probability, fit a statistical distribution, or convert expert judgment into a numeric POF. Numeric Level 1 POF remains frequency/adjusted using GFF×DF×FMS."
+    ],
+)
+def pof_method_selection(x):
+    ensure(bool(x.qualification_basis.strip()), "POF method qualification_basis must be nonblank")
+    return {
+        "method": x.method,
+        "qualification_basis": x.qualification_basis,
+        "uncertainty_quantified": x.uncertainty_quantified,
+        "numeric_pof_route": "gff_df_fms" if x.method in ("statistical_generic_data", "combined") else "external_method_result",
+    }
+
+
+class GoverningDamage(Model):
+    thinning: NonNegative
+    lining: NonNegative | None = None
+    external: list[NonNegative] = Field(max_length=4)
+    scc: list[NonNegative] = Field(max_length=9)
+    htha: NonNegative
+    fatigue: NonNegative
+    brittle_fracture: NonNegative
+    temper_embrittlement: NonNegative
+    embrittlement_885f: NonNegative
+    sigma_embrittlement: NonNegative
+    thinning_external_distribution: Literal["local", "general"]
+
+
+@calculation("damage/combine", "Governing and total damage factors", GoverningDamage,
+             ["Part 2 §3.4.2 eqs (2.2)-(2.8); PDF pp142-143"],
+             limitations=["Caller must identify applicable mechanisms; empty lists mean explicitly no applicable mechanism."])
+def combine(x):
+    thin = min(x.thinning, x.lining) if x.lining is not None else x.thinning
+    ext, scc = max(x.external, default=0), max(x.scc, default=0)
+    active = lambda v: v if v > 1 else 0
+    brit = max(active(x.brittle_fracture) + active(x.temper_embrittlement),
+               active(x.embrittlement_885f), active(x.sigma_embrittlement))
+    wall = max(thin, ext) if x.thinning_external_distribution == "local" else thin + ext
+    return {"governing_thinning": thin, "governing_external": ext, "governing_scc": scc,
+            "governing_brittle": brit, "total_damage_factor": wall + scc + x.htha + brit + x.fatigue}
+
+
+class InspectionEquivalent(Model):
+    mechanism: Literal["scc", "external_clscc", "cui_clscc", "htha"]
+    a: int = Field(ge=0)
+    b: int = Field(ge=0)
+    c: int = Field(ge=0)
+    d: int = Field(ge=0)
+
+
+@calculation("inspection/equivalent", "Equivalent inspection counts", InspectionEquivalent,
+             ["Part 2 §3.4.3; PDF p143"], limitations=["Not applicable to thinning or external corrosion; E inspections cannot be upgraded."])
+def inspection_equivalent(x):
+    d, rd = divmod(x.d, 2)
+    c, rc = divmod(x.c + d, 2)
+    b, rb = divmod(x.b + c, 2)
+    return {"a": x.a + b, "b": rb, "c": rc, "d": rd}
+
+
+class InspectionEffectivenessSummary(Model):
+    mechanism: Literal["scc", "external_clscc", "cui_clscc", "htha"]
+    categories: list[Literal["A", "B", "C", "D", "E"]] = Field(min_length=1, max_length=100)
+
+
+@calculation(
+    "inspection/effectiveness-summary",
+    "Combine inspection effectiveness history into highest category and equivalent counts",
+    InspectionEffectivenessSummary,
+    ["Part 2 §3.4.3; Part 2 Annex C §2.C.2; PDF pp143,443-445"],
+    origin="api581_inspection_effectiveness_history_composition",
+    limitations=[
+        "Applies the printed A-D equivalence rule used for SCC-family mechanisms: two lower-category inspections promote one step; E inspections never receive credit. It does not assess whether the individual inspection method satisfies an Annex C table.",
+        "Categories must already be qualified by a mechanism-specific inspection API or owner-user review. No date, coverage, age escalation or inspection effectiveness inference is performed here."
+    ],
+)
+def effectiveness_summary(x):
+    counts = {category.lower(): x.categories.count(category) for category in "ABCDE"}
+    equivalent = inspection_equivalent(InspectionEquivalent(
+        mechanism=x.mechanism, a=counts["a"], b=counts["b"], c=counts["c"], d=counts["d"]
+    ))
+    highest = next((category for category in "ABCD" if counts[category.lower()]), "E")
+    return {
+        "mechanism": x.mechanism,
+        "highest_effectiveness_category": highest,
+        "inspection_count": len(x.categories),
+        "creditable_inspection_count": sum(counts[c.lower()] for c in "ABCD"),
+        "counts": counts,
+        "equivalent_counts": equivalent,
+        "e_inspection_count": counts["e"],
+        "qualification_status": "caller_qualified_categories",
+    }
+
+
+class Weibull(Model):
+    shape: Positive
+    characteristic_life_years: Positive
+    age_years: NonNegative
+
+
+@calculation("reliability/weibull", "Two-parameter Weibull reliability", Weibull,
+             ["Part 1 eq (1.2), §8.3.2 eq (1.56)"],
+             limitations=["User-supplied parameters only; PRD environmental and inspection adjustments not included."])
+def weibull(x):
+    z = (x.age_years / x.characteristic_life_years) ** x.shape
+    hazard = None if x.age_years == 0 and x.shape < 1 else (
+        x.shape / x.characteristic_life_years * (x.age_years / x.characteristic_life_years) ** (x.shape - 1)
+        if x.age_years > 0 else (1 / x.characteristic_life_years if x.shape == 1 else 0))
+    return {"cumulative_failure_probability": -math.expm1(-z), "survival_probability": math.exp(-z),
+            "hazard_per_year": hazard, "hazard_singular_at_origin": hazard is None}
+
+
+class WeibullQuantile(Model):
+    shape: Positive
+    characteristic_life_years: Positive
+    probability: Fraction = Field(lt=1)
+
+
+@calculation("reliability/weibull-quantile", "Time to a Weibull failure probability", WeibullQuantile,
+             ["Part 1 §8.3.2 eq (1.57)"])
+def weibull_quantile(x):
+    return {"age_years": x.characteristic_life_years * (-math.log1p(-x.probability)) ** (1 / x.shape)}
+
+
+class Mttf(Model):
+    shape: Positive
+    mean_life_years: Positive
+
+
+@calculation("reliability/weibull-from-mttf", "Convert mean life to Weibull characteristic life", Mttf,
+             ["Part 1 §8.3.4.2"], origin="engineering_utility")
+def from_mttf(x):
+    return {"characteristic_life_years": x.mean_life_years / math.gamma(1 + 1 / x.shape)}
+
+
+class Poisson(Model):
+    annual_failure_frequency: NonNegative
+    duration_years: NonNegative
+
+
+@calculation("reliability/poisson-probability", "Constant-frequency period probability", Poisson,
+             ["Part 1 §4.1 Probability of Failure", "Part 1 §4.1.2 Generic Failure Frequency Method"],
+             origin="engineering_utility", limitations=["Assumes a constant-rate Poisson process; not the GFF frequency itself."])
+def poisson(x):
+    return {"period_failure_probability": -math.expm1(-x.annual_failure_frequency * x.duration_years)}