api581-engine 0.1.4__py3-none-any.whl

api581/soil_corrosion.py

@@ -0,0 +1,191 @@
+"""2016 Annex2.B §12 buried-carbon-steel soil-side corrosion rates."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, calculation, ensure, finite_tree
+from .thinning import WallLoss, StrengthRatio, Posterior, UncladThinning, unclad
+
+Profile = Literal["dry_inland_sand","variable_industrial_silt","saturated_coastal_clay"]
+Coating = Literal["bare","fusion_bonded_epoxy","liquid_epoxy","asphalt_enamel","asphalt_mastic",
+    "coal_tar_enamel","extruded_pe_mastic_or_rubber","mill_pe_tape_mastic","field_pe_tape_mastic","three_layer_pe_pp"]
+CP = Literal["unprotected_adjacent_cp_stray_current","no_cp","not_annual_or_partly_noncompliant",
+    "annual_on_potential_entire_structure","annual_polarized_or_instant_off_entire_structure"]
+_BASE = {"dry_inland_sand":(.03,1.,"Sand; low chlorides inland/non-industrial; homogeneous fine silt or sand; dry desert-like"),
+    "variable_industrial_silt":(.13,5.,"Silt; moderate industrial contaminants; mixed particles; variable moisture"),
+    "saturated_coastal_clay":(.25,10.,"Clay; high chlorides coastal; >50% gravel; normally saturated")}
+_COAT = {k:(1.,1.1,1.5,1.1) for k in ("fusion_bonded_epoxy","liquid_epoxy","asphalt_enamel","asphalt_mastic")}
+_COAT.update(coal_tar_enamel=(1.,1.2,2.,1.5),extruded_pe_mastic_or_rubber=(1.,1.2,3.,1.5),
+    mill_pe_tape_mastic=(1.5,1.2,3.,1.5),field_pe_tape_mastic=(2.,2.,3.,1.5),three_layer_pe_pp=(1.,1.2,2.,1.2))
+_CP = dict(zip(("unprotected_adjacent_cp_stray_current","no_cp","not_annual_or_partly_noncompliant",
+    "annual_on_potential_entire_structure","annual_polarized_or_instant_off_entire_structure"),(10.,1.,.8,.4,.05)))
+
+
+class SoilBaseRate(Model):
+    condition_profile: Profile
+    unit_basis: Literal["printed_si","printed_us_mpy"]
+
+
+@calculation("damage/soil-base-rate-table", "Soil base corrosion-rate reference profiles", SoilBaseRate,
+    ["Part2 Annex2.B §12.4.2,Table2.B.12.2; PDF pp417,420"],limitations=[
+        "Three full soil/contaminant/particle/moisture profiles, not automatic classification by soil name alone. Measured comparable rates take precedence under source guidance. Mixed conditions require qualified owner base rate, no invented interpolation. Printed SI.03/.13/.25mm/y differ from exact1/5/10mpy conversion; selected basis explicit."])
+def base_rate(x):
+    si,mpy,description = _BASE[x.condition_profile]
+    rate = si/1000 if x.unit_basis == "printed_si" else mpy*.0000254
+    return {"corrosion_rate_m_year":rate,"printed_si_rate_mm_year":si,"printed_us_rate_mpy":mpy,
+        "selected_unit_basis":x.unit_basis,"condition_description":description}
+
+
+class SoilResistivity(Model):
+    soil_resistivity_ohm_m: Positive
+    shared_boundary_basis: Literal["lower_resistivity_interval","higher_resistivity_interval"] | None = None
+
+
+@calculation("damage/soil-resistivity-factor", "Optional soil resistivity adjustment factor", SoilResistivity,
+    ["Part2 Annex2.B §12.4.3,Table2.B.12.3; PDF pp417-418,420"],limitations=[
+        "Public resistivity ohm m; source ohm cm=100*ohm m. Shared1000/2000ohm cm endpoints require explicit lower/higher interval selection.500 belongs500-1000,10000 belongs2000-10000. No inferred continuous resistivity interpolation. Omit adjustment when already incorporated in base rate to avoid double counting."])
+def resistivity(x):
+    value = x.soil_resistivity_ohm_m
+    if value in (10.,20.):
+        ensure(x.shared_boundary_basis is not None,"Shared resistivity endpoint requires interval basis","ambiguous_soil_resistivity_boundary")
+        index = (1 if value == 10. else 2)+(x.shared_boundary_basis == "higher_resistivity_interval")
+    else:
+        index = 0 if value < 5 else 1 if value < 10 else 2 if value < 20 else 3 if value <= 100 else 4
+    return {"resistivity_factor":(1.5,1.25,1.,.83,.6)[index],"source_row":index+1}
+
+
+class SoilTemperature(Model):
+    equipment_temperature_k: Positive
+    threshold_basis: Literal["printed_si","printed_us_converted"]
+
+
+@calculation("damage/soil-temperature-factor", "Buried equipment soil-corrosion temperature factor", SoilTemperature,
+    ["Part2 Annex2.B §12.4.4,Table2.B.12.4; PDF pp418,420"],limitations=[
+        "SI uses49/104C; US uses120/220F converted exactly to K. Paired boundaries differ, so basis required. Middle interval includes both endpoints; outer factors1, middle2. This table lookup does not qualify cryogenic/high-temperature buried service or frozen-soil chemistry."])
+def temperature(x):
+    low,high = (322.15,377.15) if x.threshold_basis == "printed_si" else ((120-32)*5/9+273.15,(220-32)*5/9+273.15)
+    return {"temperature_factor":2. if low <= x.equipment_temperature_k <= high else 1.,
+        "lower_boundary_k":low,"upper_boundary_k":high,"threshold_basis":x.threshold_basis}
+
+
+class SoilCathodicProtection(Model):
+    protection_category: CP
+
+
+@calculation("damage/soil-cp-factor", "Soil corrosion cathodic-protection effectiveness factor", SoilCathodicProtection,
+    ["Part2 Annex2.B §12.4.5,Table2.B.12.5; PDF pp418,421"],limitations=[
+        "Owner classifies actual coverage, annual testing,2016 NACE-reference compliance and adjacent-CP stray-current risk. No-CP1 differs from unprotected/untested with adjacent-CP stray current10. Factor.05 requires full-structure annual polarized/instant-off criteria; not automatic interpretation of one potential reading. Large/dynamic stray currents require specialist analysis under source scope."])
+def cathodic_protection(x):
+    return {"cathodic_protection_factor":_CP[x.protection_category]}
+
+
+class SoilCoating(Model):
+    coating_type: Coating
+    coating_age_years: NonNegative
+    rated_temperature_occasionally_exceeded: bool
+    maintenance_rare_or_none: bool
+
+
+@calculation("damage/soil-coating-factor", "Product of independent soil-coating effectiveness factors", SoilCoating,
+    ["Part2 Annex2.B §12.4.6,eq(2.B.22),Table2.B.12.6; PDF pp419,421"],limitations=[
+        "Factors apply independently; age multiplier only for age>20years, nonapplicable multipliers1. Bare factor1. Applies even without CP. Source worked mill-PE example prints1.5*1.2*3*1.5=13.5, but table-factor product is8.1; calculation follows factor multiplication, reports printed example separately and does not assert an authorized erratum."])
+def coating(x):
+    if x.coating_type == "bare":
+        ensure(not x.rated_temperature_occasionally_exceeded and not x.maintenance_rare_or_none,
+            "Bare structure cannot have coating-temperature/maintenance conditions")
+        factors = [1.,1.,1.,1.]
+    else:
+        base,age,abuse,maintenance = _COAT[x.coating_type]
+        factors = [base,age if x.coating_age_years > 20 else 1.,abuse if x.rated_temperature_occasionally_exceeded else 1.,
+            maintenance if x.maintenance_rare_or_none else 1.]
+    example = x.coating_type == "mill_pe_tape_mastic" and x.coating_age_years > 20 and x.rated_temperature_occasionally_exceeded and x.maintenance_rare_or_none
+    return {"coating_effectiveness_factor":math.prod(factors),"base_factor":factors[0],"age_factor":factors[1],
+        "temperature_abuse_factor":factors[2],"maintenance_factor":factors[3],
+        "calculation_basis":"table_factor_product","printed_example_discrepancy_applies":example,
+        "printed_example_reported_factor":13.5 if example else None}
+
+
+class SoilRateEquation(Model):
+    base_corrosion_rate_m_year: NonNegative
+    resistivity_factor: Positive
+    temperature_factor: Positive
+    cathodic_protection_factor: Positive
+    coating_effectiveness_factor: Positive
+
+
+@calculation("damage/soil-rate-equation", "Soil corrosion multiplicative rate equation", SoilRateEquation,
+    ["Part2 Annex2.B eq(2.B.21); PDF p417"],limitations=[
+        "CR=CRB*FSR*FT*FCP*FCE. Qualified factors supplied; no automatic material/service selection. Does not clamp to minimum corrosion rate or infer coating as zero-corrosion protection."])
+def rate_equation(x):
+    if x.base_corrosion_rate_m_year == 0:
+        value = 0.
+    else:
+        value = math.exp(math.fsum(math.log(v) for v in (x.base_corrosion_rate_m_year,x.resistivity_factor,
+            x.temperature_factor,x.cathodic_protection_factor,x.coating_effectiveness_factor)))
+        ensure(value > 0,"Positive soil corrosion rate underflow","numerical_failure")
+    return {"corrosion_rate_m_year":value}
+
+
+class SoilRate(Model):
+    material: Literal["carbon_steel"]
+    in_contact_with_soil: bool
+    applicability_basis: str = Field(min_length=1,max_length=1000)
+    base_corrosion_rate_m_year: NonNegative
+    base_rate_source: str = Field(min_length=1,max_length=1000)
+    resistivity_application: Literal["apply","already_in_base","omitted_by_qualification"]
+    resistivity: SoilResistivity | None = None
+    resistivity_omission_basis: str | None = Field(default=None,min_length=1,max_length=1000)
+    temperature: SoilTemperature
+    cathodic_protection: SoilCathodicProtection
+    coating: SoilCoating
+
+
+_SOIL_LIMITS = [
+    "Annex2.B screening requires carbon steel in soil contact. Owner qualifies buried-service applicability, actual soil/base rate and current/coating condition. Uses Table2.B.1.2 local thinning classification; not atmospheric/CUI corrosion, AST floor automatic model, MIC/stray-current detailed analysis or arbitrary cryogenic service.",
+    "Optional resistivity factor must be explicitly applied or omitted with basis, including when already incorporated in base rate. No duplicate soil-resistivity weighting. Source SI/US rate/temperature rounding, resistivity shared endpoints and coating example8.1vs13.5 remain explicit. Coating uses table product, not erroneous worked arithmetic.",
+    "Base-rate reference conditions must be qualified before reapplying CP,coating or temperature effects. Already-adjusted measured net rates can feed the existing thinning kernel directly; this composition does not infer which effects a measured rate already contains.",
+]
+
+
+@calculation("damage/soil-corrosion-rate", "Compose qualified soil-side corrosion base rate and table factors", SoilRate,
+    ["Part2 Annex2.B Tables2.B.1.1/1.2,§12,eq(2.B.21); PDF pp322-323,417-421"],limitations=_SOIL_LIMITS)
+def soil_rate(x):
+    ensure(x.in_contact_with_soil,"Soil contact screening not met","soil_screen_not_met")
+    ensure(x.applicability_basis.strip() and x.base_rate_source.strip(),"Applicability and base-rate sources must be nonblank")
+    if x.resistivity_application == "apply":
+        ensure(x.resistivity is not None and x.resistivity_omission_basis is None,"Applied resistivity needs input and no omission basis")
+        fsr = resistivity(x.resistivity)["resistivity_factor"]
+    else:
+        ensure(x.resistivity is None and x.resistivity_omission_basis is not None and x.resistivity_omission_basis.strip(),
+            "Omitted/already-in-base resistivity needs explicit basis and no duplicate input")
+        fsr = 1.
+    ft = temperature(x.temperature)["temperature_factor"]
+    fcp = cathodic_protection(x.cathodic_protection)["cathodic_protection_factor"]
+    fce = coating(x.coating)
+    factors = dict(resistivity_factor=fsr,temperature_factor=ft,cathodic_protection_factor=fcp,
+        coating_effectiveness_factor=fce["coating_effectiveness_factor"])
+    rate = rate_equation(SoilRateEquation(base_corrosion_rate_m_year=x.base_corrosion_rate_m_year,**factors))
+    return {**rate,**factors,"base_corrosion_rate_m_year":x.base_corrosion_rate_m_year,
+        "thinning_type":"local","resistivity_application":x.resistivity_application,
+        "coating_calculation_basis":fce["calculation_basis"],"coating_example_discrepancy_applies":fce["printed_example_discrepancy_applies"]}
+
+
+class SoilThinning(Model):
+    soil: SoilRate
+    elapsed_years: NonNegative
+    strength: StrengthRatio
+    inspections: Posterior
+    online_monitoring_factor: Positive
+    assessment_scope: Literal["unclad_internal_pressure_governed_non_ast"]
+
+
+@calculation("damage/soil-thinning-assessment", "Soil corrosion rate through unclad non-AST thinning DF", SoilThinning,
+    ["Part2 Annex2.B §12; Part2 §4.5.7 eqs(2.13),(2.18)-(2.23)"],
+    origin="api581_soil_rate_to_unclad_thinning_composition",limitations=_SOIL_LIMITS+[
+        "Single soil-side mechanism for qualified unclad non-AST internal-pressure-governed component and one constant-rate interval. No automatic history integration across coating-age20,CP or temperature changes. Same starting thickness from strength input feeds wall loss. Uses existing Bayesian thinning kernel and supplied monitoring factor. Injection/deadleg factors1 for this soil-only path. No AST floor, structural/external-pressure, cladding or automatic inspection-effectiveness determination. Result is not total all-mechanism DF or inspection acceptance."])
+def soil_thinning(x):
+    rate = soil_rate(x.soil)
+    finite_tree(rate)
+    result = unclad(UncladThinning(wall=WallLoss(starting_thickness_m=x.strength.starting_thickness_m,
+        corrosion_rate_m_year=rate["corrosion_rate_m_year"],elapsed_years=x.elapsed_years),strength=x.strength,
+        inspections=x.inspections,injection_point_factor=1.,deadleg_factor=1.,online_monitoring_factor=x.online_monitoring_factor))
+    return {**rate,**result,"assessment_scope":x.assessment_scope}

api581/source_partition.py

@@ -0,0 +1,169 @@
+"""Level2 pressure-phase screening and explicit rainout/aerosol source bases."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+from .release import Orifice, orifice, Gas, gas, Liquid, liquid
+
+Phase = Literal["vapor","liquid","two_phase"]
+Basis = Literal["api581_printed","post_flash_mass_balance"]
+
+
+class PhaseScreen(Model):
+    storage_pressure_pa_abs: Positive
+    saturation_pressure_at_storage_pa_abs: Positive
+    ambient_pressure_pa_abs: Positive = 101325
+
+
+@calculation("release/level2-release-phase", "Pressure-based Level2 release-phase screening", PhaseScreen,
+             ["Part3 eqs(3.95)-(3.97); PDF p541"],
+             limitations=["Release phase at opening differs from storage phase and final atmospheric flashed phase. Source inequalities overlap at Psat=Ps and omit equality at Psat=Patm; these boundaries return no selected phase. Ps=Patm returns no_driving_pressure. Saturation pressure is caller-qualified; no supercritical EOS inference."])
+def phase_screen(x):
+    ps,pv,pa=x.storage_pressure_pa_abs,x.saturation_pressure_at_storage_pa_abs,x.ambient_pressure_pa_abs
+    ensure(ps >= pa,"Storage pressure must be at least ambient pressure")
+    if ps == pa:
+        return {"release_phase":None,"status":"no_driving_pressure"}
+    if pv == ps:
+        return {"release_phase":None,"status":"saturation_storage_boundary"}
+    if pv == pa:
+        return {"release_phase":None,"status":"saturation_ambient_boundary"}
+    return {"release_phase":"vapor" if pv > ps else "two_phase" if pv > pa else "liquid","status":"classified"}
+
+
+class Level2Orifice(PhaseScreen):
+    diameter_m: NonNegative
+    gas_temperature_k: Positive | None = None
+    gas_molecular_weight_kg_kmol: Positive | None = None
+    gas_heat_capacity_ratio: Positive | None = None
+    liquid_density_kg_m3: Positive | None = None
+    gas_discharge_coefficient: Fraction = .9
+    liquid_discharge_coefficient: Fraction = .61
+    liquid_viscosity_factor: Positive = 1
+    qualified_boundary_phase: Phase | None = None
+    boundary_phase_source: str | None = Field(default=None,min_length=1,max_length=1000)
+
+
+@calculation("release/level2-orifice-rate", "Level2 phase-selected gas/liquid/conservative two-phase source rate", Level2Orifice,
+             ["Part3 §§5.3.3-5.3.6 eqs(3.95)-(3.97); PDF pp541-542; §4.3 eqs(3.3),(3.6)-(3.7)"],
+             origin="api581_phase_selected_orifice_composition",
+             limitations=["Two-phase branch uses source-permitted conservative LIQUID approximation, not HEM/Omega or a flashing two-phase flow solver. Vapor uses ideal gas constant upstream model. Boundary phase override requires a nonblank owner basis and cannot contradict a classified phase. No-driving-pressure returns zero without inventing phase. Caller qualifies saturation pressure and properties; no thermodynamic or LH2 validation."])
+def level2_orifice(x):
+    selected=phase_screen(PhaseScreen(**x.model_dump(include=set(PhaseScreen.model_fields))))
+    phase=selected["release_phase"]
+    ensure((x.qualified_boundary_phase is None) == (x.boundary_phase_source is None),"Boundary phase and source must be supplied together")
+    if x.boundary_phase_source is not None:
+        ensure(bool(x.boundary_phase_source.strip()),"Boundary phase source must be nonblank")
+    if selected["status"] == "no_driving_pressure":
+        ensure(x.qualified_boundary_phase is None,"No phase override for zero driving pressure")
+        return {"mass_rate_kg_s":0,"area_m2":orifice(Orifice(diameter_m=x.diameter_m))["area_m2"],
+                "release_phase":None,"rate_method":"no_driving_pressure","phase_basis":"pressure_screen"}
+    if phase is None:
+        ensure(x.qualified_boundary_phase is not None,"Source pressure boundary requires qualified phase selection","phase_boundary_requires_qualification")
+        phase=x.qualified_boundary_phase
+    else:
+        ensure(x.qualified_boundary_phase is None or x.qualified_boundary_phase == phase,"Boundary override contradicts classified phase")
+    if phase == "vapor":
+        ensure(all(v is not None for v in (x.gas_temperature_k,x.gas_molecular_weight_kg_kmol,x.gas_heat_capacity_ratio)),
+               "Vapor phase requires gas temperature, molecular weight and heat capacity ratio")
+        ensure(x.gas_heat_capacity_ratio > 1,"Gas heat capacity ratio must exceed1")
+        result=gas(Gas(diameter_m=x.diameter_m,upstream_pressure_pa_abs=x.storage_pressure_pa_abs,
+            downstream_pressure_pa_abs=x.ambient_pressure_pa_abs,temperature_k=x.gas_temperature_k,
+            molecular_weight_kg_kmol=x.gas_molecular_weight_kg_kmol,heat_capacity_ratio=x.gas_heat_capacity_ratio,
+            discharge_coefficient=x.gas_discharge_coefficient))
+        method="ideal_gas"
+    else:
+        ensure(x.liquid_density_kg_m3 is not None,"Liquid or conservative two-phase source requires liquid density")
+        result=liquid(Liquid(diameter_m=x.diameter_m,upstream_pressure_pa_abs=x.storage_pressure_pa_abs,
+            downstream_pressure_pa_abs=x.ambient_pressure_pa_abs,density_kg_m3=x.liquid_density_kg_m3,
+            discharge_coefficient=x.liquid_discharge_coefficient,viscosity_factor=x.liquid_viscosity_factor))
+        method="liquid" if phase == "liquid" else "liquid_conservative_two_phase"
+    return {"mass_rate_kg_s":result["mass_rate_kg_s"],"area_m2":result["area_m2"],"release_phase":phase,"rate_method":method,
+            "phase_basis":"qualified_boundary" if selected["release_phase"] is None else "pressure_screen"}
+
+
+class Rainout(Model):
+    flash_mass_fraction: Fraction
+
+
+@calculation("release/kletz-rainout-fraction", "Kletz rainout mass-fraction correlation", Rainout,
+             ["Part3 eqs(3.98)-(3.99); PDF p543"],
+             limitations=["Rainout=max(0,1-2*flash_fraction). Flash fraction must be supplied by qualified isentropic/isenthalpic atmospheric flash calculation. This correlation does not calculate flash state or verify entrainment composition; no LH2 validation."])
+def rainout(x):
+    return {"rainout_mass_fraction":max(0,1-2*x.flash_mass_fraction)}
+
+
+class RateSplit(Model):
+    adjusted_mass_rate_kg_s: NonNegative
+    rainout_mass_fraction: Fraction
+
+
+@calculation("release/rainout-rate-split", "Rainout pool and aerosol-containing jet rates", RateSplit,
+             ["Part3 eqs(3.100)-(3.101); PDF p543"],
+             limitations=["Pool=adjusted rate*rainout; jet=adjusted rate*(1-rainout). Jet may contain liquid aerosol and must not be labeled pure vapor. Rainout correlation/flash composition supplied separately; no pool evaporation in this split."])
+def rate_split(x):
+    return {"pool_liquid_rate_kg_s":x.adjusted_mass_rate_kg_s*x.rainout_mass_fraction,
+            "jet_total_rate_kg_s":x.adjusted_mass_rate_kg_s*(1-x.rainout_mass_fraction)}
+
+
+class Entrainment(Model):
+    rainout_mass_fraction: Fraction
+    equation_basis: Basis
+    stored_liquid_mass_fraction: Fraction | None = None
+    flash_mass_fraction: Fraction | None = None
+    post_flash_vapor_mass_fraction: Fraction | None = None
+
+
+@calculation("release/jet-liquid-entrainment", "Printed or post-flash-mass-balance aerosol fraction", Entrainment,
+             ["Part3 eq(3.102); PDF p543; phase-fraction nomenclature PDF575-576"],
+             origin="api581_with_explicit_entrainment_basis",
+             limitations=["api581_printed uses stored_liquid_fraction*flash_fraction/(1-rainout), exactly the printed product. Reports physical_range but does not prove EOS consistency. post_flash_mass_balance uses supplied total post-flash vapor fraction and remaining liquid after rainout, a separately labeled conservation interpretation, not an authorized erratum. Exactly the selected basis fields required. No jet at rainout1 has no defined composition; returns None, not division by zero."])
+def entrainment(x):
+    printed=x.equation_basis == "api581_printed"
+    ensure((printed and x.stored_liquid_mass_fraction is not None and x.flash_mass_fraction is not None and x.post_flash_vapor_mass_fraction is None)
+           or (not printed and x.stored_liquid_mass_fraction is None and x.flash_mass_fraction is None and x.post_flash_vapor_mass_fraction is not None),
+           "Provide exactly the parameters for selected entrainment basis")
+    jet_fraction=1-x.rainout_mass_fraction
+    if not printed:
+        ensure(math.fsum([x.post_flash_vapor_mass_fraction,x.rainout_mass_fraction]) <= 1,
+               "Post-flash vapor plus rainout exceeds total mass")
+    if jet_fraction == 0:
+        ensure(printed or x.post_flash_vapor_mass_fraction == 0,"No-jet rainout cannot coexist with positive post-flash vapor")
+        return {"entrained_liquid_mass_fraction":None,"jet_vapor_mass_fraction":None,"physical_range":True,
+                "jet_fraction_nonzero":False,"equation_basis":x.equation_basis}
+    if printed:
+        fraction=x.stored_liquid_mass_fraction*x.flash_mass_fraction/jet_fraction
+        physical=0 <= fraction <= 1
+        vapor=1-fraction if physical else None
+    else:
+        # min removes only <=1ulp ratio overshoot at a rounded exact mass boundary.
+        vapor=min(1,x.post_flash_vapor_mass_fraction/jet_fraction)
+        fraction=1-vapor
+        physical=True
+    return {"entrained_liquid_mass_fraction":fraction,"jet_vapor_mass_fraction":vapor,"physical_range":physical,
+            "jet_fraction_nonzero":True,"equation_basis":x.equation_basis}
+
+
+class SourcePartition(Entrainment):
+    adjusted_mass_rate_kg_s: NonNegative
+    released_mass_kg: NonNegative
+    rainout_basis_source: str = Field(min_length=1,max_length=1000)
+    flash_property_source: str = Field(min_length=1,max_length=1000)
+
+
+@calculation("release/level2-source-partition", "Pool/jet/vapor/aerosol mass and rate partition", SourcePartition,
+             ["Part3 eqs(3.100)-(3.102), STEP7.3-7.6; PDF pp543,545"],
+             origin="api581_source_partition_with_explicit_entrainment_basis",
+             limitations=["Adjusted total rate and released mass must be qualified after detection/isolation and inventory limits. Pool+jet and jet-vapor+jet-liquid conserve mass. Printed composition is explicit and not asserted as EOS closure; nonphysical printed fractions rejected. Rainout and flash properties supplied with source; no pool evaporation, flash/EOS, two-phase hydraulic solver or actual dispersion run."])
+def source_partition(x):
+    ensure(x.rainout_basis_source.strip() and x.flash_property_source.strip(),"Rainout and flash-property sources must be nonblank")
+    composition=entrainment(Entrainment(**x.model_dump(include=set(Entrainment.model_fields))))
+    ensure(composition["physical_range"],"Printed entrained-liquid fraction outside0..1 cannot define physical source","invalid_entrainment_fraction")
+    rates=rate_split(RateSplit(adjusted_mass_rate_kg_s=x.adjusted_mass_rate_kg_s,rainout_mass_fraction=x.rainout_mass_fraction))
+    pool_mass=x.released_mass_kg*x.rainout_mass_fraction
+    jet_mass=x.released_mass_kg*(1-x.rainout_mass_fraction)
+    liquid_fraction=composition["entrained_liquid_mass_fraction"] or 0
+    vapor_fraction=composition["jet_vapor_mass_fraction"] or 0
+    return {**composition,**rates,"pool_liquid_mass_kg":pool_mass,"jet_total_mass_kg":jet_mass,
+            "jet_liquid_rate_kg_s":rates["jet_total_rate_kg_s"]*liquid_fraction,
+            "jet_vapor_rate_kg_s":rates["jet_total_rate_kg_s"]*vapor_fraction,
+            "jet_liquid_mass_kg":jet_mass*liquid_fraction,"jet_vapor_mass_kg":jet_mass*vapor_fraction}

api581/spatial.py

@@ -0,0 +1,87 @@
+"""Bounded planar threshold area on an explicitly triangulated sampled grid."""
+import math
+from typing import Annotated
+from pydantic import Field, model_validator
+from .core import Model, Positive, Fraction, calculation, ensure
+
+
+Coordinate = Annotated[float,Field(strict=True,allow_inf_nan=False)]
+
+
+class ConcentrationGrid(Model):
+    downwind_coordinates_m: list[Coordinate] = Field(min_length=2,max_length=4000)
+    crosswind_coordinates_m: list[Coordinate] = Field(min_length=2,max_length=4000)
+    volume_fraction_by_crosswind_then_downwind: list[list[Fraction]]
+    threshold_volume_fraction: Positive = Field(le=1)
+    sampling_basis: str = Field(min_length=1,max_length=1000)
+
+    @model_validator(mode="after")
+    def grid(self):
+        x,y = self.downwind_coordinates_m,self.crosswind_coordinates_m
+        if len(x)*len(y) > 1000000:
+            raise ValueError("Spatial grid limited to1000000 nodes")
+        if not all(math.isfinite(v) for v in x+y) or any(b <= a for axis in (x,y) for a,b in zip(axis,axis[1:])):
+            raise ValueError("Coordinates must be finite and strictly increasing")
+        if len(self.volume_fraction_by_crosswind_then_downwind) != len(y) or any(
+            len(row) != len(x) for row in self.volume_fraction_by_crosswind_then_downwind):
+            raise ValueError("Concentrations must have shape[crosswind][downwind]")
+        if not self.sampling_basis.strip():
+            raise ValueError("Sampling basis must be nonblank")
+        return self
+
+
+def _triangle_area(vertices,threshold):
+    """Clip a linear concentration triangle in a local unit-square frame."""
+    clipped = []
+    previous = vertices[-1]
+    for current in vertices:
+        a,b = previous[2] >= threshold,current[2] >= threshold
+        if a != b:
+            fraction = (threshold-previous[2])/(current[2]-previous[2])
+            clipped.append((previous[0]+fraction*(current[0]-previous[0]),
+                            previous[1]+fraction*(current[1]-previous[1])))
+        if b:
+            clipped.append(current[:2])
+        previous = current
+    if len(clipped) < 3:
+        return 0.
+    return abs(math.fsum(a[0]*b[1]-b[0]*a[1] for a,b in zip(clipped,clipped[1:]+clipped[:1])))/2
+
+
+@calculation("dispersion/threshold-grid-area", "Planar concentration exceedance area on a sampled triangulated grid", ConcentrationGrid,
+    ["Part3 §§5.8.5-5.8.6,5.9: external spatial concentration footprint boundary"],origin="engineering_spatial_postprocessing",
+    limitations=["Numerical postprocessing, not a printed API581 correlation. Each rectangular cell is split along lower-left to upper-right diagonal; concentration is linear on each triangle and the threshold polygon is clipped exactly on that interpolant. Results depend on supplied sampling, not an exact continuous-model contour.",
+        "Field is at one common receptor height/time-averaging/source basis. No circular area from centreline distance, vertical cloud mass or multi-weather/event union. Any edge reaching threshold censors the footprint: threshold_area_m2 is null; sampled_exceedance_area_m2 remains the within-grid diagnostic. Below-threshold nodes do not rule out unresolved subgrid peaks; caller must establish resolution/convergence."])
+def threshold_grid_area(x):
+    xs,ys,c = x.downwind_coordinates_m,x.crosswind_coordinates_m,x.volume_fraction_by_crosswind_then_downwind
+    threshold = x.threshold_volume_fraction
+    boundaries = []
+    for side,values in (("upwind",[r[0] for r in c]),("downwind",[r[-1] for r in c]),
+                        ("negative_crosswind",c[0]),("positive_crosswind",c[-1])):
+        if any(v >= threshold for v in values):
+            boundaries.append(side)
+    terms,count = [],0
+    for j in range(len(ys)-1):
+        dy = ys[j+1]-ys[j]
+        for i in range(len(xs)-1):
+            dx = xs[i+1]-xs[i]
+            cell = dx*dy
+            ensure(math.isfinite(cell) and cell > 0,"Spatial cell area outside numerical range","numerical_failure")
+            v00,v10,v11,v01 = c[j][i],c[j][i+1],c[j+1][i+1],c[j+1][i]
+            if max(v00,v10,v11,v01) < threshold:
+                continue
+            fraction = 1. if min(v00,v10,v11,v01) >= threshold else (
+                _triangle_area([(0.,0.,v00),(1.,0.,v10),(1.,1.,v11)],threshold)
+                +_triangle_area([(0.,0.,v00),(1.,1.,v11),(0.,1.,v01)],threshold))
+            ensure(0 <= fraction <= 1+1e-12,"Invalid interpolated area fraction","numerical_failure")
+            value = min(fraction,1.)*cell
+            ensure(value > 0 or fraction == 0,"Positive spatial area underflow","numerical_failure")
+            terms.append(value)
+            count += value > 0
+    area = math.fsum(terms)
+    reached = any(v >= threshold for row in c for v in row)
+    return {"sampled_exceedance_area_m2":area,"threshold_area_m2":None if boundaries else area,
+        "footprint_status":"boundary_censored" if boundaries else "closed_on_supplied_grid" if reached else "not_reached",
+        "boundary_sides":boundaries,"positive_area_cell_count":count,
+        "downwind_node_count":len(xs),"crosswind_node_count":len(ys),
+        "interpolation_basis":"piecewise_linear_main_diagonal_triangles"}

api581/ssc_screening.py

@@ -0,0 +1,77 @@
+"""SSC applicability screen kept separate from hydrogen severity and hardness."""
+from typing import Literal
+from pydantic import Field
+from .core import Model, Positive, NonNegative, calculation, ensure
+from .scc_mechanisms import WetH2sEnvironment, wet_h2s_environment, SscSusceptibility, ssc_susceptibility, Assessment, InspectionCounts, assess
+
+
+class SscScreen(Model):
+    material: Literal['carbon_steel','low_alloy_steel','other_material']
+    water_present: bool
+    h2s_present: bool
+    exposure_basis: str = Field(min_length=1)
+
+
+@calculation('damage/ssc-screening','SSC carbon/low-alloy steel wet-H2S any-concentration screen',SscScreen,
+    ['Part2 §8.3; PDF p184'],limitations=[
+        'Evaluate carbon/low-alloy steel whenever both water and H2S are present at any concentration. No1ppm, partial-pressure, pH, temperature, hardness or PWHT cutoff is used to exclude the mechanism at this screen. Presence flags require qualified local/process/upset exposure evidence. Environmental hydrogen severity, cyanide, weld/HAZ Brinnell hardness and heat treatment remain separate susceptibility inputs. Screen-out is outside this procedure, not DF0, FFS acceptance or immunity to other mechanisms.'])
+def ssc_screening(x):
+    ensure(bool(x.exposure_basis.strip()),'Qualified steel, water and H2S exposure basis required')
+    material=x.material!='other_material'
+    return {'evaluate_ssc':material and x.water_present and x.h2s_present,
+        'screening_reason':'outside_material_scope' if not material else 'water_absent' if not x.water_present else
+            'h2s_absent' if not x.h2s_present else 'evaluate'}
+
+
+@calculation('damage/hic-h2s-screening','HIC/SOHIC-H2S steel and wet-H2S any-concentration screen',SscScreen,
+    ['Part2 §9.3; PDF p189'],limitations=[
+        'Source material/water/H2S screening criteria coincide with SSC, but this identifier explicitly evaluates HIC/SOHIC-H2S. Carbon and low-alloy steel both enter screening; downstream Table9.3 carbon-steel material/sulfur/product assumptions require independent qualification. PWHT, seamless pipe, low sulfur or low H2S concentration alone do not exclude screening. No automatic SSC/HIC equivalence, SOHIC immunity, blister/crack FFS acceptance or zero DF.'])
+def hic_h2s_screening(x):
+    screen=ssc_screening(x)
+    return {'evaluate_hic_sohic_h2s':screen['evaluate_ssc'],'screening_reason':screen['screening_reason']}
+
+
+class SscQualifiedService(Model):
+    environment: WetH2sEnvironment
+    measured_brinnell_hardness: Positive
+    pwht: bool
+    service_basis: str = Field(min_length=1)
+
+
+@calculation('damage/ssc-qualified-susceptibility','SSC environment and measured hardness with cyanide susceptibility upgrade',SscQualifiedService,
+    ['Part2 Tables8.2-8.3; PDF p187'],limitations=[
+        'Cyanide note upgrades susceptibility, not environmental severity, one category none->low->medium->high, capped at high, only when pH>8.3 and water H2S>1000ppm. Brinnell must be actually measured, not converted microhardness; PWHT and process chemistry require qualification. Existing source pH gaps and overlapping1000ppm columns fail explicitly. No automatic material applicability or chemical speciation.'])
+def ssc_qualified_susceptibility(x):
+    ensure(bool(x.service_basis.strip()),'Qualified water chemistry, measured weldment Brinnell and PWHT basis required')
+    environment=wet_h2s_environment(x.environment)
+    base=ssc_susceptibility(SscSusceptibility(measured_brinnell_hardness=x.measured_brinnell_hardness,
+        pwht=x.pwht,environmental_severity=environment['environmental_severity']))['susceptibility']
+    levels=('none','low','medium','high')
+    selected=levels[min(3,levels.index(base)+int(environment['susceptibility_upgrade_required']))]
+    return {**environment,'unadjusted_susceptibility':base,'susceptibility':selected,
+        'cyanide_upgrade_applied':environment['susceptibility_upgrade_required']}
+
+
+class SscQualifiedAssessment(Model):
+    screening: SscScreen
+    service: SscQualifiedService
+    confirmed_cracking: bool
+    unrepaired_cracks: bool
+    years_since_qualifying_inspection: NonNegative
+    inspections: InspectionCounts
+    inspection_basis: str = Field(min_length=1)
+
+
+@calculation('damage/ssc-qualified-assessment','SSC material/exposure through environment/hardness/cyanide and DF',SscQualifiedAssessment,
+    ['Part2 §§8.3,8.5-8.6,Tables8.2-8.4,Table6.3; eq(2.27); PDF pp184-188'],
+    origin='qualified_ssc_environment_hardness_to_df',limitations=[
+        'Selected material/wet-H2S screen must pass. Reuses existing Table8.2 gaps/overlap guards, Table8.3 actual Brinnell/PWHT susceptibility and one-category cyanide note before crack override. Confirmed cracking forces high; unrepaired cracks require FFS. Caller qualifies mechanism-specific inspection period and coverage. Existing equivalent-count support up to6, age escalation and table DF preserved. No generic thinning-history reuse, FFS or total asset risk.'])
+def ssc_qualified_assessment(x):
+    ensure(not x.unrepaired_cracks,'Unrepaired SSC cracks require separate FFS evaluation','ffs_required')
+    ensure(bool(x.inspection_basis.strip()),'SSC-specific qualifying inspection age and coverage basis required')
+    screen=ssc_screening(x.screening)
+    ensure(screen['evaluate_ssc'],'SSC material/wet-H2S screen not met','ssc_outside_screen')
+    service=ssc_qualified_susceptibility(x.service)
+    result=assess('ssc',Assessment(susceptibility=service['susceptibility'],confirmed_cracking=x.confirmed_cracking,
+        unrepaired_cracks=False,years_since_qualifying_inspection=x.years_since_qualifying_inspection,inspections=x.inspections))
+    return {**screen,**service,**result}