api581-engine 0.1.4__py3-none-any.whl

api581/acscc_screening.py

@@ -0,0 +1,88 @@
+"""ACSCC alkaline-water and FCCU feed-change screening, Part2 section10.3."""
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, calculation, ensure
+from .scc_mechanisms import AcsccSusceptibility, acscc_susceptibility, Assessment, InspectionCounts, assess
+
+
+class AcsccScreen(Model):
+    material: Literal['carbon_steel','low_alloy_steel','other_material']
+    water_present: bool
+    water_ph: float | None = Field(default=None,strict=True,allow_inf_nan=False)
+    fccu_feed_sulfur_reduced: bool
+    fccu_feed_nitrogen_increased: bool
+    screening_basis: str = Field(min_length=1)
+
+
+@calculation('damage/acscc-screening','ACSCC alkaline-water and FCCU feed-change evaluation triggers',AcsccScreen,
+    ['Part2 §10.3; PDF p196'],limitations=[
+        'Carbon/low-alloy steel: alkaline water pH>7.5 or reduced-sulfur/increased-nitrogen FCCU feed changes trigger evaluation. Exactly7.5 does not pass the strict water trigger. Feed-change triggers are independent review flags, not proof of carbonate concentration or susceptibility. Water presence requires its qualified pH; absent water must omit pH. No H2S threshold, cyanide exclusion, carbonate estimate, PWHT credit or damage factor is inferred. Outside scope is not overall immunity or zero risk.'])
+def acscc_screening(x):
+    ensure(bool(x.screening_basis.strip()),'Qualified material/water chemistry and FCCU feed-change review basis required')
+    ensure((x.water_ph is not None)==x.water_present,'Water pH required exactly when water is present')
+    triggers=[]
+    if x.water_present and x.water_ph>7.5:
+        triggers.append('alkaline_water_ph_above_7_5')
+    if x.fccu_feed_sulfur_reduced:
+        triggers.append('fccu_feed_sulfur_reduced')
+    if x.fccu_feed_nitrogen_increased:
+        triggers.append('fccu_feed_nitrogen_increased')
+    eligible=x.material!='other_material'
+    return {'evaluate_acscc':eligible and bool(triggers),'material_in_scope':eligible,'evaluation_triggers':triggers}
+
+
+class AcsccWaterSusceptibility(Model):
+    water_ph: float = Field(strict=True,allow_inf_nan=False)
+    carbonate_ppm: NonNegative
+    pwht: bool
+    shared_ph_boundary_policy: Literal['lower_ph_row','higher_ph_row'] | None = None
+    carbonate_measurement_basis: str = Field(min_length=1)
+    traditional_alkalinity_only: bool
+    service_fabrication_basis: str = Field(min_length=1)
+
+
+@calculation('damage/acscc-water-susceptibility','Qualified numeric water pH to ACSCC carbonate/PWHT susceptibility',AcsccWaterSusceptibility,
+    ['Part2 Table10.2 and note1; PDF p199'],limitations=[
+        'Numeric pH mapped to existing Table10.2 bands. Shared8.0/9.0 endpoints require explicit lower/higher-pH row selection; no automatic susceptibility-maximizing policy.7.5 enters7.5_to_8, independently of screening strict>7.5.100ppm carbonate belongs high-concentration column. Traditional P/M alkalinity alone is rejected per note1; caller supplies qualified carbonate method. No carbonate inference from total alkalinity, PWHT certification, numeric pH rounding allowance or material applicability.'])
+def acscc_water_susceptibility(x):
+    ensure(bool(x.carbonate_measurement_basis.strip()) and bool(x.service_fabrication_basis.strip()),
+        'Qualified carbonate analysis and service/fabrication bases required')
+    ensure(not x.traditional_alkalinity_only,'Traditional P/M alkalinity alone is ineffective for carbonate in sour water','unsupported_carbonate_measurement')
+    ph=x.water_ph
+    boundary=ph in (8.,9.)
+    ensure((x.shared_ph_boundary_policy is not None)==boundary,
+        'Shared pH8/9 endpoints require a row policy; unused policy must be omitted','ambiguous_acscc_ph_boundary')
+    if boundary:
+        bands=('7.5_to_8','8_to_9') if ph==8. else ('8_to_9','at_least_9')
+        band=bands[x.shared_ph_boundary_policy=='higher_ph_row']
+    else:
+        band='below_7.5' if ph<7.5 else '7.5_to_8' if ph<8. else '8_to_9' if ph<9. else 'at_least_9'
+    result=acscc_susceptibility(AcsccSusceptibility(water_ph_band=band,carbonate_ppm=x.carbonate_ppm,pwht=x.pwht))
+    return {**result,'selected_ph_band':band,'shared_ph_boundary_encountered':boundary}
+
+
+class AcsccQualifiedAssessment(Model):
+    screening: AcsccScreen
+    water: AcsccWaterSusceptibility
+    confirmed_cracking: bool
+    unrepaired_cracks: bool
+    years_since_qualifying_inspection: NonNegative
+    inspections: InspectionCounts
+    inspection_basis: str = Field(min_length=1)
+
+
+@calculation('damage/acscc-qualified-assessment','ACSCC screen and common water chemistry through inspection/age DF',AcsccQualifiedAssessment,
+    ['Part2 §§10.3,10.6.3,Table10.2-10.3,Table6.3; eq(2.29); PDF pp196-199'],
+    origin='qualified_acscc_water_to_existing_scc_df',limitations=[
+        'Requires positive screening and water-present numeric pH consistent with susceptibility input. FCCU feed change can trigger review but cannot replace water/carbonate data needed by Table10.2. Shared pH8/9 policy, qualified carbonate measurement and PWHT remain explicit. Confirmed cracking forceshigh; unrepaired cracks requireFFS. Independent mechanism-specific inspection age/coverage required; existing six-equivalent-inspection support retained. No chemical speciation, automatic damage detection, FFS or whole-asset risk.'])
+def acscc_qualified_assessment(x):
+    ensure(not x.unrepaired_cracks,'Unrepaired ACSCC requires separate FFS evaluation','ffs_required')
+    ensure(bool(x.inspection_basis.strip()),'ACSCC-specific inspection age and effectiveness basis required')
+    screen=acscc_screening(x.screening)
+    ensure(screen['evaluate_acscc'],'ACSCC material/environment review screen not met','acscc_outside_screen')
+    ensure(x.screening.water_present,'ACSCC table requires qualified aqueous carbonate conditions','acscc_water_required')
+    ensure(x.screening.water_ph==x.water.water_ph,'Screening and susceptibility water pH must agree','acscc_ph_mismatch')
+    water=acscc_water_susceptibility(x.water)
+    result=assess('acscc',Assessment(susceptibility=water['susceptibility'],confirmed_cracking=x.confirmed_cracking,
+        unrepaired_cracks=False,years_since_qualifying_inspection=x.years_since_qualifying_inspection,inspections=x.inspections))
+    return {**screen,**water,**result}

api581/alkaline_sour_water.py

@@ -0,0 +1,267 @@
+"""2016 Annex2.B section7 NH4HS sour-water corrosion and sour-water routing."""
+from bisect import bisect_left
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure, finite_tree
+from .co2_corrosion import PSI_PA
+from .acid_sour_water import AcidSourRoute, route as acid_route, AcidSourAssessment, assessment as acid_assessment
+from .thinning import Posterior, WallLoss
+from .clad_thinning import PressureStrength, CodeStrength
+from .thinning_conditions import ThinningConditions, QualifiedUnclad, qualified_unclad
+
+Units = Literal["printed_si","printed_us_converted"]
+_C = (.02,.05,.1,.15)
+_VSI = (3.05,4.57,6.10,7.62,9.14)
+_VUS = tuple(v*.3048 for v in (10,15,20,25,30))
+_SI = ((.08,.10,.13,.20,.28),(.15,.23,.30,.38,.46),(.51,.69,.89,1.09,1.27),(1.14,1.78,2.54,3.81,5.08))
+_US = ((3,4,5,8,11),(6,9,12,15,18),(20,27,35,43,50),(45,70,100,150,200))
+
+
+class H2SPartialPressure(Model):
+    total_pressure_pa_abs: Positive
+    h2s_mole_fraction: Fraction
+
+
+@calculation("properties/h2s-partial-pressure", "H2S partial pressure from absolute pressure and mole fraction", H2SPartialPressure,
+    ["Part2 Table2.B.7.1; PDF p379"],limitations=["Public mole fraction0..1, not printed mole-percent number multiplied without/100. AbsolutePa, not gauge. Product only; no gas-liquid equilibrium, dissolvedH2S or fugacity calculation."])
+def partial_pressure(x):
+    p = x.total_pressure_pa_abs*x.h2s_mole_fraction
+    ensure(p > 0 or x.h2s_mole_fraction == 0,"H2S partial-pressure underflow","numerical_failure")
+    return {"h2s_partial_pressure_pa_abs":p}
+
+
+class NH4HSEstimate(Model):
+    h2s_mass_fraction: Fraction
+    nh3_mass_fraction: Fraction
+    analytical_basis: str = Field(min_length=1)
+    excess_h2s_policy: Literal["reject_disputed_branch","qualified_printed_literal"]
+    excess_h2s_qualification_basis: str | None = None
+    equality_policy: Literal["reject_unassigned_equality","qualified_lower_branch","qualified_upper_branch"]
+    equality_qualification_basis: str | None = None
+
+
+@calculation("damage/alkaline-sour-water-nh4hs-estimate", "Source NH4HS analytical approximation with disputed branch gate", NH4HSEstimate,
+    ["Part2 Table2.B.7.1; PDF p379"],limitations=[
+        "Source prefers ionic process model. Printed ifH2S<2*NH3:NH4HS=1.5*H2S; ifH2S>2*NH3:NH4HS=3*H2S, notNH3. Excess branch rejected unless qualified literal use; no undocumented ammonia-limited repair. Equality unassigned, requires explicit qualified lower/upper selection or error. Public mass fractions, same condensed-water analytical basis, H2S+NH3<=1. Literal estimate can exceed1; raw value/flag retained, not clipped or claimed mass-balanced chemistry. Integrated table rejects out-of-range concentration."])
+def nh4hs_estimate(x):
+    ensure(bool(x.analytical_basis.strip()) and x.h2s_mass_fraction+x.nh3_mass_fraction <= 1,"Analytical basis or common mass fractions invalid")
+    excess = x.excess_h2s_policy == "qualified_printed_literal"
+    ensure((x.excess_h2s_qualification_basis is not None and bool(x.excess_h2s_qualification_basis.strip())) if excess else x.excess_h2s_qualification_basis is None,"Disputed excess policy and basis must agree")
+    equality = x.equality_policy != "reject_unassigned_equality"
+    ensure((x.equality_qualification_basis is not None and bool(x.equality_qualification_basis.strip())) if equality else x.equality_qualification_basis is None,"Equality policy and basis must agree")
+    equal = x.h2s_mass_fraction == 2*x.nh3_mass_fraction
+    if equal:
+        ensure(equality,"ExactH2S=2*NH3 boundary unassigned by source","nh4hs_unassigned_equality")
+        upper = x.equality_policy == "qualified_upper_branch"
+        branch = "qualified_equality_upper" if upper else "qualified_equality_lower"
+    else:
+        upper = x.h2s_mass_fraction > 2*x.nh3_mass_fraction
+        branch = "printed_excess_h2s" if upper else "printed_lower_h2s"
+    ensure(not upper or excess,"Disputed printed excess-H2S formula requires qualified literal policy","nh4hs_disputed_formula")
+    value = x.h2s_mass_fraction*(3. if upper else 1.5)
+    return {"estimated_nh4hs_mass_fraction":value,"concentration_estimate_branch":branch,"estimated_fraction_exceeds_one":value > 1}
+
+
+class AlkalineVelocity(Model):
+    phase_regime: Literal["two_phase","liquid_full"]
+    vapor_velocity_m_s: NonNegative | None = None
+    liquid_velocity_m_s: NonNegative | None = None
+    qualification_basis: str = Field(min_length=1)
+
+
+@calculation("damage/alkaline-sour-water-velocity-selection", "Select vapor or liquid velocity for NH4HS table", AlkalineVelocity,
+    ["Part2 Table2.B.7.1; PDF p379"],limitations=[
+        "Two-phase system uses vapor-phase velocity, liquid-full system uses liquid velocity. Bulk/mixture velocity is not substituted. Two-phase liquid velocity may be supplied as contextual input but is not selected. Vapor input in liquid-full case rejected. No phase fractions, holdup, slip velocity or wall-shear calculation inferred."])
+def velocity_selection(x):
+    ensure(bool(x.qualification_basis.strip()),"Phase-specific velocity qualification required")
+    if x.phase_regime == "two_phase":
+        ensure(x.vapor_velocity_m_s is not None,"Two-phase NH4HS table requires vapor velocity")
+        v,phase = x.vapor_velocity_m_s,"vapor"
+    else:
+        ensure(x.liquid_velocity_m_s is not None and x.vapor_velocity_m_s is None,"Liquid-full case requires liquid velocity and no vapor velocity")
+        v,phase = x.liquid_velocity_m_s,"liquid"
+    return {"selected_velocity_m_s":v,"selected_velocity_phase":phase}
+
+
+class AlkalineBase(Model):
+    nh4hs_mass_fraction: Fraction
+    selected_velocity_m_s: NonNegative
+    unit_basis: Units
+    lookup_policy: Literal["exact_nodes_only","bilinear","maximum_bracketing_value"]
+
+
+def _bracket(nodes,value):
+    value = next((n for n in nodes if abs(n-value) <= 1e-10),value)
+    ensure(nodes[0] <= value <= nodes[-1],"NH4HS concentration/velocity outside source table; no extrapolation")
+    i = bisect_left(nodes,value)
+    return (i,i,0.) if value == nodes[i] else (i-1,i,(value-nodes[i-1])/(nodes[i]-nodes[i-1]))
+
+
+@calculation("damage/alkaline-sour-water-base-rate", "NH4HS and phase-velocity baseline carbon-steel corrosion rate", AlkalineBase,
+    ["Part2 Tables2.B.7.2/7.2M; PDF pp379-380"],limitations=[
+        "20cells per unit basis:NH4HS2/5/10/15wt%,SI3.05/4.57/6.10/7.62/9.14m/s,US10/15/20/25/30ft/s. Public fractions/m/s/m-year; rounded SI rates/grid versus exactUS conversions explicit. Exact/bilinear/max-bracketing numerical policy required; no concentration or velocity extrapolation/edge defaults. Baseline before pressure correction, not independently modeled temperature/hydrocarbon effects."])
+def base_rate(x):
+    a,b,wc = _bracket(_C,x.nh4hs_mass_fraction)
+    c,d,wv = _bracket(_VSI if x.unit_basis == "printed_si" else _VUS,x.selected_velocity_m_s)
+    ensure(x.lookup_policy != "exact_nodes_only" or (a == b and c == d),"Exact baseline node policy does not interpolate")
+    table = _SI if x.unit_basis == "printed_si" else _US
+    if x.lookup_policy == "maximum_bracketing_value":
+        value = max(table[a][c],table[a][d],table[b][c],table[b][d])
+    else:
+        lo,hi = table[a][c]+wv*(table[a][d]-table[a][c]),table[b][c]+wv*(table[b][d]-table[b][c])
+        value = lo+wc*(hi-lo)
+    return {"baseline_corrosion_rate_m_year":value*(.001 if x.unit_basis == "printed_si" else .0000254)}
+
+
+class AlkalinePressure(Model):
+    baseline_corrosion_rate_m_year: NonNegative
+    h2s_partial_pressure_pa_abs: NonNegative
+    equation_basis: Units
+
+
+@calculation("damage/alkaline-sour-water-pressure-adjustment", "NH4HS sour-water H2S partial-pressure correction", AlkalinePressure,
+    ["Part2 Tables2.B.7.2/7.2M notes1-2; PDF pp379-380"],limitations=[
+        "US factor=1+(p_psia-50)/25 below50, /40 above;SI=1+(p_kPa-345)/173 below345,/276 above. At reference both expressions return1. Finalrate=max(baseline*factor,0). Public absolutePa; rounded pressure thresholds/slopes differ, basis explicit. Negative factor/low-pressure zero clamp flagged, not actual immunity to sour-water/wetH2S damage. No extrapolation range is specified by source pressure notes; owner qualifies actual pressure applicability."])
+def pressure_adjustment(x):
+    p,ref,low,high = (x.h2s_partial_pressure_pa_abs/1000,345.,173.,276.) if x.equation_basis == "printed_si" else (x.h2s_partial_pressure_pa_abs/PSI_PA,50.,25.,40.)
+    branch = "at_reference" if p == ref else "below_reference" if p < ref else "above_reference"
+    raw = 1+(p-ref)/(low if p < ref else high)
+    factor = max(raw,0.)
+    rate = x.baseline_corrosion_rate_m_year*factor
+    finite_tree([raw,factor,rate])
+    ensure(rate > 0 or factor == 0 or x.baseline_corrosion_rate_m_year == 0,"Pressure-adjusted rate underflow","numerical_failure")
+    return {"corrosion_rate_m_year":rate,"unclamped_pressure_factor":raw,"pressure_correction_factor":factor,
+        "negative_pressure_factor_clamped":raw < 0,"pressure_correction_branch":branch}
+
+
+class SuppliedNH4HS(Model):
+    method: Literal["supplied"]
+    nh4hs_mass_fraction: Fraction
+    qualification_basis: str = Field(min_length=1)
+
+
+class EstimatedNH4HS(NH4HSEstimate):
+    method: Literal["source_approximation"]
+
+
+class AlkalineWet(Model):
+    concentration: SuppliedNH4HS | EstimatedNH4HS = Field(discriminator="method")
+    velocity: AlkalineVelocity
+    h2s_partial_pressure_pa_abs: NonNegative
+    baseline_unit_basis: Units
+    pressure_equation_basis: Units
+    lookup_policy: Literal["exact_nodes_only","bilinear","maximum_bracketing_value"]
+    thinning_threshold_basis: Units
+    qualification_basis: str = Field(min_length=1)
+
+
+class AlkalineAssessment(Model):
+    material: Literal["carbon_steel"]
+    free_water_present: bool
+    ph: float | None = Field(default=None,gt=7,le=14,strict=True,allow_inf_nan=False)
+    h2s_ammonia_service_qualified: bool
+    applicability_basis: str = Field(min_length=1)
+    wet_model: AlkalineWet | None = None
+
+
+@calculation("damage/alkaline-sour-water-assessment", "Qualified alkaline NH4HS carbon-steel corrosion assessment", AlkalineAssessment,
+    ["Part2 Annex2.B §7,Tables7.1-7.2M; Table1.2; PDF pp323,378-381"],origin="api581_composition_with_explicit_source_policies",limitations=[
+        "Carbon-steel free-water/H2S/NH3 service above neutralpH only; wet concentration preferably supplied from qualified ionic model/analysis. Disputed source approximations retain gates. Phase-specific velocity selected once; pressure correction applied to same baseline. Source table general/local classification uses<=6.1m/s or<=20ft/s as explicit threshold basis. Temperature/HC-water ratio effects are secondary but no quantitative correction supplied; not invented. Dry0 is NH4HS-specific, not zero all-mechanismDF. Low-pressure source clamp0 not validated absence of damage. No wetH2S cracking, material-alloy extension or process equilibrium inferred."])
+def alkaline_assessment(x):
+    ensure(bool(x.applicability_basis.strip()),"Alkaline service/water/pH applicability basis required")
+    if not x.free_water_present:
+        ensure(x.ph is None and x.wet_model is None,"Dry alkaline branch cannot carry unused aqueous pH/model")
+        return {"corrosion_rate_m_year":0.,"baseline_corrosion_rate_m_year":None,"nh4hs_mass_fraction_used":None,"concentration_source":None,
+            "selected_velocity_m_s":None,"selected_velocity_phase":None,"unclamped_pressure_factor":None,"pressure_correction_factor":None,
+            "negative_pressure_factor_clamped":False,"pressure_correction_branch":None,"source_thinning_type":None,"calculation_branch":"no_free_water"}
+    ensure(x.ph is not None and x.h2s_ammonia_service_qualified and x.wet_model is not None,"Wet alkaline calculation requires qualifiedpH>7 H2S/NH3 and wet model")
+    m = x.wet_model
+    ensure(bool(m.qualification_basis.strip()),"Condensed-water concentration and pressure applicability qualification required")
+    if m.concentration.method == "supplied":
+        ensure(bool(m.concentration.qualification_basis.strip()),"Supplied NH4HS concentration qualification required")
+        concentration = m.concentration.nh4hs_mass_fraction
+    else:
+        concentration = nh4hs_estimate(m.concentration)["estimated_nh4hs_mass_fraction"]
+    vel = velocity_selection(m.velocity)
+    base = base_rate(AlkalineBase(nh4hs_mass_fraction=concentration,selected_velocity_m_s=vel["selected_velocity_m_s"],unit_basis=m.baseline_unit_basis,lookup_policy=m.lookup_policy))
+    adjusted = pressure_adjustment(AlkalinePressure(baseline_corrosion_rate_m_year=base["baseline_corrosion_rate_m_year"],h2s_partial_pressure_pa_abs=m.h2s_partial_pressure_pa_abs,equation_basis=m.pressure_equation_basis))
+    threshold = 6.1 if m.thinning_threshold_basis == "printed_si" else 20*.3048
+    return {**base,**vel,**adjusted,"nh4hs_mass_fraction_used":concentration,"concentration_source":m.concentration.method,
+        "source_thinning_type":"general" if vel["selected_velocity_m_s"] <= threshold else "local","calculation_branch":"wet_nh4hs_model"}
+
+
+class AlkalineThinning(Model):
+    corrosion: AlkalineAssessment
+    assessment_distribution: Literal["general","local"]
+    distribution_qualification_basis: str = Field(min_length=1)
+    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/alkaline-sour-water-thinning-assessment", "NH4HS corrosion through qualified non-AST unclad thinning DF", AlkalineThinning,
+    ["Part2 Annex2.B §7,Table1.2; Part2 §4.5.7,Table4.8"],origin="api581_composition_with_explicit_source_policies",limitations=[
+        "Same selected phase velocity and rate drive sour-water monitoring and wall loss. Explicit source general/local classification retained separately from owner-qualified inspection/distribution; no automatic coverage validation. Source pressure-clamp0 does not force DF0: strength/uncertainty/floor remain. Non-AST unclad only; no ammonia/wetH2S cracking, material extension, two-phase EOS, all-mechanismDF or code/FFS."])
+def alkaline_thinning(x):
+    ensure(bool(x.distribution_qualification_basis.strip()),"Actual general/local distribution and inspection basis required")
+    corrosion = alkaline_assessment(x.corrosion)
+    monitor = x.conditions.monitoring.row
+    ensure(monitor.mechanism == "sour_water","NH4HS model requires sour-water monitoring row")
+    if corrosion["selected_velocity_m_s"] is not None:
+        ensure(monitor.velocity_m_s == corrosion["selected_velocity_m_s"],"Monitoring must use same selected phase velocity as NH4HS rate model")
+    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,"assessment_distribution":x.assessment_distribution}
+
+
+from .hydrochloric_acid import HClAssessment, assessment as hcl_assessment
+
+
+class SourWaterAssessment(Model):
+    screening: AcidSourRoute
+    acid_model: AcidSourAssessment | None = None
+    alkaline_model: AlkalineAssessment | None = None
+    hcl_model: HClAssessment | None = None
+    hcl_shared_phase_qualification_basis: str | None = None
+
+
+@calculation("damage/sour-water-assessment", "Route qualified sour water to acid or alkaline quantitative model", SourWaterAssessment,
+    ["Part2 Annex2.B §§2,7,10,Figures2.1,10.1; PDF pp324-330,378-381,392-396"],origin="api581_composition_with_explicit_source_policies",limitations=[
+        "Reuses explicit free-water/pH/chloride policies. Executes only matching supplied acid/alkaline/HCl model, never sums them. Acid child screening must match entire shared request; alkaline child must have same free-water/pH. HCl child requires shared separated-phase qualification and matching available pH/chloride; screeningroute alone does not establish dilute HCl applicability. Neutral-unclassified errors, never zero. Returns common selected-rate fields; independent APIs retain detailed diagnostics including HCl999-cell flags. Dry0 source-specific; no all-mechanismDF or immunity statement."])
+def sour_water_assessment(x):
+    routed = acid_route(x.screening)
+    choice = routed["corrosion_route"]
+    if choice != "hydrochloric_acid":
+        ensure(x.hcl_model is None and x.hcl_shared_phase_qualification_basis is None,"Non-HCl route cannot carry unused HCl model or basis")
+    if choice == "no_free_water":
+        ensure(x.acid_model is None and x.alkaline_model is None,"Dry route cannot carry unused quantitative models")
+        result = {"corrosion_rate_m_year":0.,"base_corrosion_rate_m_year":None,"selected_rate_is_screening_bound":False,"localized_attack_review_required":False}
+    elif choice == "acid_sour_water":
+        ensure(x.acid_model is not None and x.alkaline_model is None,"Acid route requires only matching acid model")
+        ensure(x.acid_model.screening == x.screening,"Acid child and shared screening requests must match")
+        result = acid_assessment(x.acid_model)
+    elif choice == "alkaline_sour_water":
+        ensure(x.alkaline_model is not None and x.acid_model is None,"Alkaline route requires only matching alkaline model")
+        ensure(x.alkaline_model.free_water_present == x.screening.free_water_present and x.alkaline_model.ph == x.screening.ph,"Alkaline model and shared pH/water must match")
+        alkaline = alkaline_assessment(x.alkaline_model)
+        result = {**alkaline,"base_corrosion_rate_m_year":alkaline["baseline_corrosion_rate_m_year"],"selected_rate_is_screening_bound":False,
+            "localized_attack_review_required":alkaline["source_thinning_type"] == "local"}
+    elif choice == "hydrochloric_acid":
+        ensure(x.hcl_model is not None and x.acid_model is None and x.alkaline_model is None,"HCl route requires only matching HCl model")
+        ensure(x.hcl_shared_phase_qualification_basis is not None and bool(x.hcl_shared_phase_qualification_basis.strip()),"HCl child and shared screening need same separated acid-phase qualification")
+        ensure(x.hcl_model.free_water_present == x.screening.free_water_present,"HCl and shared free-water state must match")
+        hcl = hcl_assessment(x.hcl_model)
+        if hcl["ph_used"] is not None:
+            ensure(hcl["ph_used"] == x.screening.ph,"HCl model and shared separated-phase pH must match")
+        if hcl["chloride_mass_fraction_used"] is not None and x.screening.chloride_concentration_ppm is not None:
+            ensure(abs(hcl["chloride_mass_fraction_used"]*1e6-x.screening.chloride_concentration_ppm) <= 1e-9,"HCl and shared chloride concentration must match")
+        result = {"corrosion_rate_m_year":hcl["corrosion_rate_m_year"],"base_corrosion_rate_m_year":hcl["corrosion_rate_m_year"],
+            "selected_rate_is_screening_bound":False,"localized_attack_review_required":True}
+    else:
+        ensure(False,"Sour-water route needs neutral-boundary resolution; no automatic zero","different_corrosion_mechanism")
+    return {**routed,"corrosion_rate_m_year":result["corrosion_rate_m_year"],"selected_model_base_rate_m_year":result["base_corrosion_rate_m_year"],
+        "selected_rate_is_screening_bound":result["selected_rate_is_screening_bound"],"localized_attack_review_required":result["localized_attack_review_required"]}

api581/amine_corrosion.py

@@ -0,0 +1,277 @@
+"""2016 Annex2.B section8 amine tables, chemistry policies and thinning."""
+from bisect import bisect_left
+from itertools import product
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure, finite_tree
+from ._amine_tables import TABLES
+from .thinning import Posterior, WallLoss
+from .clad_thinning import PressureStrength, CodeStrength
+from .thinning_conditions import ThinningConditions, QualifiedUnclad, qualified_unclad
+
+Amine = Literal["mea","dea","mdea"]
+Units = Literal["printed_si","printed_us_converted"]
+Lookup = Literal["exact_nodes_only","linear_loading_temperature","maximum_bracketing_value"]
+_RICH = (.15,.25,.35,.45,.55,.65,.7)
+
+
+def _qualified(value,message):
+    ensure(bool(value.strip()),message)
+
+
+def _bracket(nodes,value):
+    value=next((n for n in nodes if abs(n-value)<=1e-10),value)
+    ensure(nodes[0]<=value<=nodes[-1],"Outside amine table; no extrapolation")
+    i=bisect_left(nodes,value)
+    return (i,i,0.) if value==nodes[i] else (i-1,i,(value-nodes[i-1])/(nodes[i]-nodes[i-1]))
+
+
+class AmineAcidGasLoading(Model):
+    h2s_amount_mol: NonNegative
+    co2_amount_mol: NonNegative
+    active_amine_amount_mol: Positive
+    common_sample_basis: str = Field(min_length=1)
+
+
+@calculation("damage/amine-acid-gas-loading", "Combined H2S and CO2 loading per mole of active amine", AmineAcidGasLoading,
+    ["Part2 Annex2.B §8.1,Table8.1; PDF pp382-383"],limitations=[
+        "Both acid gases on same representative sample basis divided by active, not total or degraded amine. No HSAS-to-active-amine subtraction, equilibrium or rich/lean process-state inference. Zero acid-gas loading valid; denominator strictly positive. Owner process analysis/qualification required."])
+def acid_gas_loading(x):
+    _qualified(x.common_sample_basis,"Common sample and active-amine analytical basis required")
+    result=(x.h2s_amount_mol+x.co2_amount_mol)/x.active_amine_amount_mol
+    finite_tree(result)
+    return {"acid_gas_loading_mol_mol":result}
+
+
+class AmineLoadingSelection(Model):
+    acid_gas_loading_mol_mol: NonNegative
+    loading_gap_policy: Literal["reject_unassigned_0p10_to_0p15","qualified_lean_row","qualified_first_rich_row"]
+    loading_gap_qualification_basis: str | None = None
+
+
+@calculation("damage/amine-loading-selection", "Amine lean/rich source loading rows and explicit gap selection", AmineLoadingSelection,
+    ["Part2 Tables2.B.8.2-8.3M; PDF pp384-387"],limitations=[
+        "Carbon tables have lean<0.1 and rich nodes0.15..0.7.0.1<=loading<0.15 is unassigned, default rejected; owner-qualified nearest lean/first-rich mapping flagged, never interpolation across incompatible velocity thresholds. Rich nodes may be numerically bracketed; rate lookup separately selects interpolation. Loading>0.7 rejected. Returned row indices0lean,1..7rich are table coordinates, not process rich/lean designation."])
+def loading_selection(x):
+    q=x.loading_gap_policy!="reject_unassigned_0p10_to_0p15"
+    ensure((x.loading_gap_qualification_basis is not None and bool(x.loading_gap_qualification_basis.strip())) if q else x.loading_gap_qualification_basis is None,
+        "Loading gap policy and qualification basis must agree")
+    value=x.acid_gas_loading_mol_mol
+    gap=.1<=value<.15
+    if value<.1:
+        a=b=0; w=0.
+    elif gap:
+        ensure(q,"Carbon amine loading0.10..0.15 lacks printed row","amine_loading_gap")
+        a=b=0 if x.loading_gap_policy=="qualified_lean_row" else 1; w=0.
+    else:
+        a,b,w=_bracket(_RICH,value)
+        a+=1; b+=1
+    return {"lower_loading_row_index":a,"upper_loading_row_index":b,"loading_interpolation_weight":w,
+        "table_loading_regime":"lean" if a==0 else "rich","loading_gap_mapping_used":gap}
+
+
+class AmineContaminantSelection(Model):
+    amine_type: Amine
+    contaminant_mass_fraction: Fraction
+    mdea_scale_policy: Literal["not_mdea","qualified_basic_data_organic_ppm_bands","qualified_printed_wt_percent_nodes"]
+    mdea_scale_qualification_basis: str | None = None
+    four_percent_boundary_policy: Literal["basic_data_middle_band","printed_four_percent_high_row"] | None = None
+    four_percent_qualification_basis: str | None = None
+
+
+@calculation("damage/amine-contaminant-row", "Select amine HSAS or MDEA organic-acid contamination row", AmineContaminantSelection,
+    ["Part2 Table2.B.8.1,Tables8.2-8.3M; PDF pp383-387"],limitations=[
+        "MEA/DEA basic-data<=2wt%,2..4,>4 maplow/middle/high table rows2/3/4. Exact4 conflicts with printed high-row4: explicit middle/high policy/basis required. MDEA basic-data organic-acid<500,500..4000,>4000wppm differs from tableHSAS0.5/2.25/4wt%; explicit qualified basic-data band mapping or literal exactwt%node policy required. Never treat500ppm as0.5wt%. No hidden HSAS composition or active-amine correction. No interpolation between contaminant categories."])
+def contaminant_row(x):
+    c=x.contaminant_mass_fraction
+    if x.amine_type=="mdea":
+        ensure(x.mdea_scale_policy!="not_mdea" and x.mdea_scale_qualification_basis is not None and bool(x.mdea_scale_qualification_basis.strip()),"MDEA source scale conflict needs explicit policy and basis")
+        ensure(x.four_percent_boundary_policy is None and x.four_percent_qualification_basis is None,"MEA/DEA boundary fields do not apply to MDEA")
+        if x.mdea_scale_policy=="qualified_basic_data_organic_ppm_bands":
+            ppm=c*1e6
+            row="low" if ppm<500 else "middle" if ppm<=4000 else "high"
+        else:
+            index=next((i for i,n in enumerate((.005,.0225,.04)) if abs(c-n)<=1e-12),None)
+            ensure(index is not None,"Printed MDEA wt% policy accepts only literal0.5/2.25/4wt% nodes")
+            row=("low","middle","high")[index]
+    else:
+        ensure(x.mdea_scale_policy=="not_mdea" and x.mdea_scale_qualification_basis is None,"MDEA fields unused for MEA/DEA")
+        if c==.04:
+            ensure(x.four_percent_boundary_policy is not None and x.four_percent_qualification_basis is not None and bool(x.four_percent_qualification_basis.strip()),"Exact4wt% HSAS requires source boundary policy and basis")
+            row="middle" if x.four_percent_boundary_policy=="basic_data_middle_band" else "high"
+        else:
+            ensure(x.four_percent_boundary_policy is None and x.four_percent_qualification_basis is None,"Four-percent boundary policy applies only at4wt%")
+            row="low" if c<=.02 else "middle" if c<.04 else "high"
+    return {"contaminant_row":row,"printed_hsas_row_mass_fraction":((.005,.0225,.04) if x.amine_type=="mdea" else (.02,.03,.04))[("low","middle","high").index(row)]}
+
+
+class AmineStrength(Model):
+    amine_type: Amine
+    amine_mass_fraction: Fraction
+
+
+@calculation("damage/amine-strength-factor", "Carbon-steel amine concentration multiplier", AmineStrength,
+    ["Part2 Table2.B.8.4; PDF p388"],limitations=[
+        "MEA<=20wt%:1,21..25:1.5,>25:2;DEA<=30:1,31..40:1.2,>40:1.5;MDEA<=50:1 only. Continuous20..21 and30..31 gaps rejected, no rounding/interpolation. MDEA>50 not supplied. Positive active process solution concentration required. Carbon-table factor, not extra stainless multiplier or concentration derating credit."])
+def strength_factor(x):
+    c=x.amine_mass_fraction
+    ensure(c>0,"Amine concentration must be positive")
+    if x.amine_type=="mea":
+        ensure(c<=.2 or c>=.21,"MEA20..21wt% multiplier gap")
+        f=1. if c<=.2 else 1.5 if c<=.25 else 2.
+    elif x.amine_type=="dea":
+        ensure(c<=.3 or c>=.31,"DEA30..31wt% multiplier gap")
+        f=1. if c<=.3 else 1.2 if c<=.4 else 1.5
+    else:
+        ensure(c<=.5,"No MDEA strength factor above50wt%")
+        f=1.
+    return {"amine_strength_factor":f}
+
+
+class AmineCarbonBaseRate(Model):
+    table_family: Literal["mea_dea","mdea"]
+    loading: AmineLoadingSelection
+    contaminant_row: Literal["low","middle","high"]
+    maximum_temperature_k: Positive
+    velocity_m_s: NonNegative
+    unit_basis: Units
+    lookup_policy: Lookup
+
+
+@calculation("damage/amine-carbon-base-rate", "Carbon-steel amine loading temperature contamination velocity tables", AmineCarbonBaseRate,
+    ["Part2 Tables2.B.8.2-8.3M; PDF pp384-387"],limitations=[
+        "1152physical source cells:2families x2units x8loading rows x3contamination rows x6temperatures x2velocity. Base rates before strength factor. Lean velocity low<=6.1m/s or20ft/s,rich<=1.5m/s or5ft/s; equality low, no velocity interpolation. Rich loading/temperature interpolation explicit, not across lean gap. Contaminant row is source table coordinate; process classification independent API. Unit differences preserved, temperature outside table rejected. No local evaporation/metal-temperature prediction, film transient or automatic amineSCC."])
+def carbon_base_rate(x):
+    selected=loading_selection(x.loading)
+    lean=selected["table_loading_regime"]=="lean"
+    threshold=(6.1 if lean else 1.5) if x.unit_basis=="printed_si" else (20 if lean else 5)*.3048
+    high=x.velocity_m_s>threshold
+    temps=tuple(t+273.15 for t in (88,93,104,116,127,132)) if x.unit_basis=="printed_si" else tuple((t-32)*5/9+273.15 for t in (190,200,220,240,260,270))
+    a,b,v=_bracket(temps,x.maximum_temperature_k)
+    i,j,w=selected["lower_loading_row_index"],selected["upper_loading_row_index"],selected["loading_interpolation_weight"]
+    ensure(x.lookup_policy!="exact_nodes_only" or (a==b and i==j),"Exact amine table policy does not interpolate")
+    data=TABLES[x.table_family+("_si" if x.unit_basis=="printed_si" else "_us")]
+    row=("low","middle","high").index(x.contaminant_row)
+    def cell(l,t):
+        return data[3*l+row][2*t+int(high)]
+    native=max(cell(l,t) for l,t in product((i,j),(a,b))) if x.lookup_policy=="maximum_bracketing_value" else (1-w)*((1-v)*cell(i,a)+v*cell(i,b))+w*((1-v)*cell(j,a)+v*cell(j,b))
+    return {**selected,"base_corrosion_rate_m_year":native*(.001 if x.unit_basis=="printed_si" else .0000254),
+        "velocity_band":"high" if high else "low","velocity_threshold_m_s":threshold,
+        "source_table_id":"2.B.8."+("2" if x.table_family=="mea_dea" else "3")+("M" if x.unit_basis=="printed_si" else "")}
+
+
+class AmineStainlessRate(Model):
+    acid_gas_loading_mol_mol: NonNegative
+    maximum_temperature_k: Positive
+    unit_basis: Units
+    lookup_policy: Lookup
+    low_loading_policy: Literal["reject_below_0p1","qualified_first_row"]
+    low_loading_qualification_basis: str | None = None
+    normal_service_conditions_qualified: bool
+    qualification_basis: str = Field(min_length=1)
+
+
+@calculation("damage/amine-stainless-rate", "Type300 stainless amine loading corrosion table", AmineStainlessRate,
+    ["Part2 Table2.B.8.5,§8.3,Figure8.1; PDF pp382,388-389"],limitations=[
+        "8loading x2unit cells,temperature<=149C or300F explicitly selected. Below0.1loading not printed: reject or qualified first-row screening value flagged, not guaranteed bound. No loading>0.7 or high-temperature extrapolation. Normal service qualification required: source says extreme concentration/temperature/degradation can cause up to200x, not fixed multiplier or guaranteed upper bound. No carbon strength factor on stainless and no inferred HSAS/velocity modifier. Source figure Type300 scope; not all chromium/nickel/copper alloys."])
+def stainless_rate(x):
+    _qualified(x.qualification_basis,"Stainless material and normal service qualification required")
+    ensure(x.normal_service_conditions_qualified,"Extreme stainless conditions require separate qualified corrosion assessment; no automatic200x factor")
+    q=x.low_loading_policy=="qualified_first_row"
+    ensure((x.low_loading_qualification_basis is not None and bool(x.low_loading_qualification_basis.strip())) if q else x.low_loading_qualification_basis is None,"Stainless low-loading policy and basis must agree")
+    threshold=149+273.15 if x.unit_basis=="printed_si" else (300-32)*5/9+273.15
+    ensure(x.maximum_temperature_k<=threshold,"Above stainless amine table temperature limit")
+    below=x.acid_gas_loading_mol_mol<.1
+    ensure(not below or q,"Stainless loading below first printed0.1 node")
+    data=TABLES["stainless"]
+    a,b,w=_bracket(tuple(r[0] for r in data),max(x.acid_gas_loading_mol_mol,.1))
+    ensure(x.lookup_policy!="exact_nodes_only" or a==b,"Exact stainless table policy does not interpolate")
+    col=1 if x.unit_basis=="printed_si" else 2
+    native=max(data[a][col],data[b][col]) if x.lookup_policy=="maximum_bracketing_value" else (1-w)*data[a][col]+w*data[b][col]
+    return {"corrosion_rate_m_year":native*(.001 if x.unit_basis=="printed_si" else .0000254),"low_loading_first_row_used":below,"source_table_id":"2.B.8.5"}
+
+
+class AmineCarbonService(Model):
+    method: Literal["carbon_table"]
+    material: Literal["carbon_steel","low_alloy_steel"]
+    low_alloy_qualification_basis: str | None = None
+    solution: AmineStrength
+    contaminants: AmineContaminantSelection
+    loading: AmineLoadingSelection
+    maximum_temperature_k: Positive
+    velocity_m_s: NonNegative
+    unit_basis: Units
+    lookup_policy: Lookup
+    classification_qualification_basis: str = Field(min_length=1)
+    qualification_basis: str = Field(min_length=1)
+
+
+class AmineStainlessService(AmineStainlessRate):
+    method: Literal["type300_stainless_table"]
+    amine_type: Amine
+
+
+class AmineAssessment(Model):
+    amine_service_present: bool
+    applicability_basis: str = Field(min_length=1)
+    rate_model: AmineCarbonService | AmineStainlessService | None = Field(default=None,discriminator="method")
+
+
+@calculation("damage/amine-corrosion-assessment", "Qualified amine chemistry and material corrosion assessment", AmineAssessment,
+    ["Part2 Annex2.B §8,Tables8.1-8.5,Figure8.1,Table1.2; PDF pp323,382-389"],origin="api581_composition_with_explicit_source_policies",limitations=[
+        "MEA/DEA/MDEA chemical gas-treating amines only; no physical solvent/DIPA extension. Same amine in strength/contaminants required. CS table and qualified figurelow-alloy branch use base*strength once;Type300 stainless uses normal-service table without carbon multiplier. CS classification explicitly qualified to rate-table velocity columns: overviewstrict boundaries/body6.01vs6.1/1.52vs1.5 differ; equality follows rate-table low, not unqualified universal limit. Stainless source type not inferred without velocity:None. No-service0 specific, not totalDF0. Maximum local metal temperature/amine concentration, active loading and contaminant applicability external; no amineSCC."])
+def assessment(x):
+    _qualified(x.applicability_basis,"Amine service and process applicability qualification required")
+    if not x.amine_service_present:
+        ensure(x.rate_model is None,"No-amine branch cannot carry unused rate model")
+        return {"corrosion_rate_m_year":0.,"base_corrosion_rate_m_year":None,"amine_strength_factor":None,"contaminant_row":None,
+            "printed_hsas_row_mass_fraction":None,"table_loading_regime":None,"loading_gap_mapping_used":False,"velocity_band":None,
+            "velocity_threshold_m_s":None,"low_loading_first_row_used":False,"source_table_id":None,"source_thinning_type":None,"calculation_branch":"no_amine_service"}
+    ensure(x.rate_model is not None,"Exposed amine service requires qualified rate model")
+    m=x.rate_model
+    _qualified(m.qualification_basis,"Maximum local conditions and material qualification required")
+    if m.method=="carbon_table":
+        low=m.material=="low_alloy_steel"
+        ensure((m.low_alloy_qualification_basis is not None and bool(m.low_alloy_qualification_basis.strip())) if low else m.low_alloy_qualification_basis is None,"Figure low-alloy/table carbon-steel difference needs qualified material basis")
+        ensure(m.solution.amine_type==m.contaminants.amine_type,"Solution and contaminant amine types must match")
+        _qualified(m.classification_qualification_basis,"Explicit rate-table velocity classification and inspection basis required")
+        contaminant=contaminant_row(m.contaminants)
+        base=carbon_base_rate(AmineCarbonBaseRate(table_family="mdea" if m.solution.amine_type=="mdea" else "mea_dea",loading=m.loading,
+            contaminant_row=contaminant["contaminant_row"],maximum_temperature_k=m.maximum_temperature_k,velocity_m_s=m.velocity_m_s,unit_basis=m.unit_basis,lookup_policy=m.lookup_policy))
+        factor=strength_factor(m.solution)["amine_strength_factor"]
+        return {"corrosion_rate_m_year":base["base_corrosion_rate_m_year"]*factor,"base_corrosion_rate_m_year":base["base_corrosion_rate_m_year"],
+            "amine_strength_factor":factor,**contaminant,"table_loading_regime":base["table_loading_regime"],"loading_gap_mapping_used":base["loading_gap_mapping_used"],
+            "velocity_band":base["velocity_band"],"velocity_threshold_m_s":base["velocity_threshold_m_s"],"low_loading_first_row_used":False,
+            "source_table_id":base["source_table_id"],"source_thinning_type":"general" if base["velocity_band"]=="low" else "local","calculation_branch":"carbon_amine_model"}
+    result=stainless_rate(m)
+    return {**result,"base_corrosion_rate_m_year":result["corrosion_rate_m_year"],"amine_strength_factor":None,"contaminant_row":None,
+        "printed_hsas_row_mass_fraction":None,"table_loading_regime":None,"loading_gap_mapping_used":False,"velocity_band":None,
+        "velocity_threshold_m_s":None,"source_thinning_type":None,"calculation_branch":"type300_stainless_model"}
+
+
+class AmineThinning(Model):
+    corrosion: AmineAssessment
+    assessment_distribution: Literal["general","local"]
+    distribution_qualification_basis: str = Field(min_length=1)
+    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/amine-thinning-assessment", "Amine rate through qualified non-AST unclad thinning DF", AmineThinning,
+    ["Part2 Annex2.B §8,Table1.2; §4.5.7,Table4.8"],origin="api581_composition_with_explicit_source_policies",limitations=[
+        "Same final base*strength rate drives wall loss; amine monitoring row must match table velocity band when carbon model supplies one. Monitoring regime basis and actual inspection distribution qualified explicitly. Stainless has no rate-table velocity classification; owner monitoring regime remains separately qualified. No-amine0 does not bypass generalDF floor/uncertainty. Non-AST unclad only; no amineSCC, process equilibrium, code/FFS or all-mechanism risk inference."])
+def thinning_assessment(x):
+    _qualified(x.distribution_qualification_basis,"Actual general/local distribution and inspection qualification required")
+    corrosion=assessment(x.corrosion)
+    monitor=x.conditions.monitoring.row
+    ensure(monitor.mechanism=="amine","Amine corrosion requires amine monitoring row")
+    if corrosion["velocity_band"] is not None:
+        ensure(monitor.amine_velocity_regime==corrosion["velocity_band"],"Monitoring and corrosion must use same qualified amine velocity band")
+    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,"assessment_distribution":x.assessment_distribution}