api581-engine 0.1.4__py3-none-any.whl

api581/external_cracking.py

@@ -0,0 +1,63 @@
+"""Austenitic external and CUI chloride SCC, Part 2 §§17-18."""
+import math
+from typing import Literal
+from .core import Model, NonNegative, calculation, ensure
+from .external_corrosion import RateQuery, DRIVERS, CoatingExposure, coating_exposure
+from .scc_mechanisms import Assessment
+from .pof import InspectionEquivalent, inspection_equivalent
+from .cracking import SccBase, scc_base
+
+
+class SusceptibilityQuery(RateQuery):
+    mechanism: Literal["external_clscc","cui_clscc"]
+
+
+@calculation("damage/external-clscc-base-susceptibility", "External/CUI CLSCC climate-temperature base susceptibility", SusceptibilityQuery,
+             ["Part 2 Tables 17.2,18.2; PDF pp249,255"],
+             limitations=["Eligible austenitic material/service required. CUI complexity/condition/chloride adjustments not included. Source rows overlap at 93 C, requiring manual classification."])
+def base_susceptibility(x):
+    t=x.temperature_k-273.15
+    ensure(not math.isclose(t,93,abs_tol=1e-9,rel_tol=0),"Source temperature rows overlap at 93 C", "ambiguous_source")
+    if t<49 or t>149: level="none"
+    else:
+        column=DRIVERS.index(x.driver)
+        if x.mechanism=="external_clscc": rows=[("medium","low","none","high"),("low","low","none","medium")]
+        else: rows=[("high","medium","low","high"),("medium","low","none","high")]
+        level=rows[t>93][column]
+    return {"base_susceptibility":level}
+
+
+class CrackingAssessment(Assessment):
+    coating_age_years: NonNegative
+    coating_quality: Literal["none_or_poor","medium","high"]
+
+
+def assess(x):
+    ensure(not x.unrepaired_cracks,"Unrepaired cracking requires FFS evaluation", "ffs_required")
+    level="high" if x.confirmed_cracking else x.susceptibility
+    svi={"none":0,"low":1,"medium":10,"high":50}[level]
+    counts=inspection_equivalent(InspectionEquivalent(mechanism="external_clscc",**x.inspections.model_dump()))
+    grade,count="E",0
+    for letter in "abcd":
+        if counts[letter]: grade,count=letter.upper(),counts[letter]; break
+    ensure(count<=6,"Equivalent inspection count exceeds source table support")
+    base=scc_base(SccBase(severity_index=svi,inspection_grade=grade,inspection_count=count))["base_damage_factor"]
+    exposure=coating_exposure(CoatingExposure(years_since_thickness_reading=x.years_since_qualifying_inspection,
+                              coating_age_years=x.coating_age_years,coating_quality=x.coating_quality))
+    age_factor=max(exposure["corrosion_exposure_years"],1)**1.1
+    return {"effective_susceptibility":level,"severity_index":svi,"equivalent_inspection_grade":grade,
+            "equivalent_inspection_count":count,"base_damage_factor":base,"age_factor":age_factor,
+            "coating_credit_years":exposure["coating_credit_years"],"cracking_exposure_years":exposure["corrosion_exposure_years"],
+            "damage_factor":base*age_factor}
+
+
+@calculation("damage/external-clscc", "External chloride SCC damage factor", CrackingAssessment,
+             ["Part 2 §17.6.3 eqs (2.68)-(2.76), Table 17.3"], limitations=["Qualified susceptibility and inspection age supplied; eligible material/service screening is separate. External severity scale differs from internal CLSCC."])
+def external_clscc(x):
+    return assess(x)
+
+
+@calculation("damage/cui-clscc", "Chloride SCC under insulation damage factor", CrackingAssessment,
+             ["Part 2 §18.6.3 eqs (2.77)-(2.85), Table 17.3"], limitations=["Caller supplies susceptibility AFTER complexity, insulation-condition and chloride adjustments. Eligible material/service screening remains separate."])
+def cui_clscc(x):
+    return assess(x)

api581/fatigue.py

@@ -0,0 +1,56 @@
+"""Mechanical fatigue of piping, Part 2 §24; category choices are explicit."""
+from typing import Literal
+from pydantic import Field
+from .core import Model, calculation
+
+
+class FatigueBase(Model):
+    previous_failure_count: int = Field(ge=0,strict=True)
+    shaking_severity: Literal["minor","moderate","severe"]
+    shaking_duration_band: Literal["less_than_2_weeks","2_to_13_weeks","13_to_52_weeks"]
+    cyclic_loading: Literal["reciprocating_machinery","prv_chatter","high_pressure_drop_valve","none"]
+
+
+@calculation("damage/fatigue-base", "Piping mechanical fatigue base factor", FatigueBase,
+             ["Part 2 §24.6.3 STEP 1-5, eq (2.92); PDF p289"], limitations=["Piping only; caller selects vibration/duration band. Source gives no explicit duration factor above 52 weeks or unique numeric classification at 13 weeks."])
+def fatigue_base(x):
+    previous=1 if x.previous_failure_count==0 else (50 if x.previous_failure_count==1 else 500)
+    shaking={"minor":1,"moderate":50,"severe":500}[x.shaking_severity]
+    duration={"less_than_2_weeks":1,"2_to_13_weeks":.2,"13_to_52_weeks":.02}[x.shaking_duration_band]
+    cyclic={"reciprocating_machinery":50,"prv_chatter":25,"high_pressure_drop_valve":10,"none":1}[x.cyclic_loading]
+    return {"previous_failure_factor":previous,"shaking_factor":shaking,"shaking_duration_factor":duration,
+            "cyclic_loading_factor":cyclic,"base_damage_factor":max(previous,shaking*duration,cyclic)}
+
+
+class FatigueAdjustments(Model):
+    corrective_action: Literal["complete_engineering_analysis","experience_based_modification","none"]
+    total_pipe_fittings: int = Field(ge=0,strict=True)
+    damaged_or_improper_supports: bool
+    broken_or_directly_welded_gussets: bool
+    branch_design: Literal["threaded_socketweld_saddle_on","saddle_in","tee_or_weldolet","sweepolet"]
+    any_branch_above_nps_2: bool
+
+
+@calculation("damage/fatigue-adjustments", "Piping mechanical fatigue adjustment factors", FatigueAdjustments,
+             ["Part 2 §24.6.3 STEP 6, eq (2.93); PDF p290"])
+def fatigue_adjustments(x):
+    factors={"corrective_action_factor":{"complete_engineering_analysis":.002,"experience_based_modification":.2,"none":2}[x.corrective_action],
+             "complexity_factor":.5 if x.total_pipe_fittings<=5 else (1 if x.total_pipe_fittings<=10 else 2),
+             "pipe_condition_factor":2 if x.damaged_or_improper_supports or x.broken_or_directly_welded_gussets else 1,
+             "joint_branch_factor":{"threaded_socketweld_saddle_on":2,"saddle_in":1,"tee_or_weldolet":.2,"sweepolet":.02}[x.branch_design],
+             "branch_diameter_factor":.02 if x.any_branch_above_nps_2 else 1}
+    import math
+    return {**factors,"combined_adjustment_factor":math.prod(factors.values())}
+
+
+class FatigueAssessment(Model):
+    base: FatigueBase
+    adjustments: FatigueAdjustments
+
+
+@calculation("damage/mechanical-fatigue", "Piping mechanical fatigue damage factor", FatigueAssessment,
+             ["Part 2 eqs (2.92)-(2.93)"], limitations=["Piping only; qualitative categories supplied by caller. Not a stress-range/cycle-count fatigue life or FFS calculation."])
+def mechanical_fatigue(x):
+    base=fatigue_base(x.base)
+    factors=fatigue_adjustments(x.adjustments)
+    return {**base,**factors,"damage_factor":base["base_damage_factor"]*factors["combined_adjustment_factor"]}

api581/fireball.py

@@ -0,0 +1,163 @@
+"""Fireball radiation with explicit printed versus elevated-sphere geometry."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+from .effects import (FireballGeometry, fireball_geometry, FireballFraction,
+                      fireball_fraction, FireballEmissive, fireball_emissive)
+from .pool_fire import Atmosphere, _atmosphere
+
+GeometryBasis = Literal["api581_printed", "elevated_sphere_maximum"]
+_GEOMETRY_LIMIT = (
+    "Explicit basis required: api581_printed follows eqs(3.165)-(3.166), "
+    "C=.5*hypot(D,xs), F=D^2/(D^2+xs^2), without using H=.75D. "
+    "elevated_sphere_maximum is a separately identified geometric interpretation: "
+    "grade receiver at horizontal radius xs, sphere center H=.75D, receiver plane "
+    "normal facing the center, F=(D/(2*hypot(H,xs)))^2. It is not an authorized erratum."
+)
+
+
+class FireballMass(Model):
+    available_mass_kg: NonNegative
+    flammable_mass_fraction: Fraction
+
+
+@calculation("effects/fireball-mass", "Flammable mass available to a rupture fireball", FireballMass,
+             ["Part3 eq(3.157); PDF p555"],
+             limitations=["Mass fraction of available release inventory, not mole fraction or dispersion cloud mass. Instantaneous rupture applicability must be established by caller."])
+def mass(x):
+    return {"flammable_mass_kg":x.available_mass_kg*x.flammable_mass_fraction}
+
+
+class SphereView(Model):
+    diameter_m: Positive
+    distance_m: NonNegative
+    geometry_basis: GeometryBasis
+
+
+@calculation("effects/fireball-view-factor", "Fireball spherical radiation view factor", SphereView,
+             ["Part3 eqs(3.159),(3.165)-(3.166); PDF pp555-556"],
+             origin="api581_with_explicit_fireball_geometry_basis", limitations=[_GEOMETRY_LIMIT])
+def view(x):
+    if x.geometry_basis == "api581_printed":
+        center=.5*math.hypot(x.diameter_m,x.distance_m)
+        # The printed xs is used as the attenuation path, as stated below eq(3.166).
+        path=x.distance_m
+    else:
+        center=math.hypot(.75*x.diameter_m,x.distance_m)
+        path=center-.5*x.diameter_m
+    ensure(math.isfinite(center) and center > 0,"Fireball center distance outside numerical domain","numerical_failure")
+    factor=(.5*x.diameter_m/center)**2
+    ensure(factor > 0,"Fireball view factor underflow","numerical_failure")
+    return {"view_factor":factor,"model_center_distance_m":center,
+            "attenuation_path_m":path,"geometry_basis":x.geometry_basis}
+
+
+class RadiationSetup(Model):
+    diameter_m: Positive
+    surface_emissive_power_w_m2: NonNegative
+    atmosphere: Atmosphere
+    geometry_basis: GeometryBasis
+
+
+class FireballFlux(RadiationSetup):
+    distance_m: NonNegative
+
+
+def _tau(atmosphere,path):
+    # Validate the chosen atmospheric parameter even at zero distance/zero energy.
+    selected=_atmosphere(atmosphere,path if path > 0 else 1)
+    if path == 0 and atmosphere.transmissivity_model == "api_water_vapor":
+        return 1.0  # Physical cap of the zero-path limiting value.
+    return selected
+
+
+@calculation("effects/fireball-radiation-flux", "Fireball received thermal radiation", FireballFlux,
+             ["Part3 eqs(3.140),(3.164)-(3.166); PDF pp552,555-556"],
+             origin="api581_with_explicit_fireball_geometry_basis",
+             limitations=[_GEOMETRY_LIMIT,
+                          "Printed basis uses nominal xs for atmospheric attenuation. Elevated sphere uses center-to-receiver distance minus radius. Zero printed path uses capped limiting transmissivity1. No flame contact or LH2-specific validation."])
+def flux(x):
+    geometry=view(SphereView(diameter_m=x.diameter_m,distance_m=x.distance_m,geometry_basis=x.geometry_basis))
+    tau=_tau(x.atmosphere,geometry["attenuation_path_m"])
+    return {**geometry,"transmissivity":tau,
+            "received_flux_w_m2":tau*x.surface_emissive_power_w_m2*geometry["view_factor"]}
+
+
+class FireballDistance(RadiationSetup):
+    threshold_w_m2: Positive
+    maximum_distance_m: Positive
+    distance_tolerance_m: Positive = 1e-5
+    maximum_iterations: int = Field(default=100,ge=10,le=300,strict=True)
+
+
+@calculation("effects/fireball-distance", "Fireball thermal threshold distance and area", FireballDistance,
+             ["Part3 eqs(3.164)-(3.168); PDF pp555-556"],
+             origin="api581_threshold_iteration_with_explicit_fireball_geometry_basis",
+             limitations=[_GEOMETRY_LIMIT,
+                          "Monotone spherical flux solution within caller maximum distance; no automatic bracket expansion. Returns safe upper bracket, with error bounded by distance_tolerance_m. Area=pi*distance^2 per printed equations; elevated-sphere distance is horizontal radius. If origin is below threshold returns zero area and no claimed threshold root."])
+def distance(x):
+    setup=x.model_dump(include=set(RadiationSetup.model_fields))
+    def received(at):
+        return flux(FireballFlux(**setup,distance_m=at))["received_flux_w_m2"]
+    low,high=0.0,x.maximum_distance_m
+    at_origin=received(low)
+    if at_origin <= x.threshold_w_m2:
+        return {"safe_distance_m":0,"consequence_area_m2":0,"status":"below_limit_at_origin",
+                "iterations":0,"flux_residual_w_m2":None,"geometry_basis":x.geometry_basis}
+    ensure(received(high) <= x.threshold_w_m2,"Fireball threshold not bracketed by supplied maximum distance","unbracketed_threshold")
+    iterations=0
+    while high-low > x.distance_tolerance_m and iterations < x.maximum_iterations:
+        mid=low+(high-low)/2
+        ensure(low < mid < high,"Fireball distance iteration reached floating point resolution","numerical_failure")
+        if received(mid) > x.threshold_w_m2:
+            low=mid
+        else:
+            high=mid
+        iterations+=1
+    ensure(high-low <= x.distance_tolerance_m,"Fireball distance did not converge","nonconvergent_threshold")
+    return {"safe_distance_m":high,"consequence_area_m2":math.pi*high**2,"status":"threshold_solved",
+            "iterations":iterations,"flux_residual_w_m2":received(high)-x.threshold_w_m2,"geometry_basis":x.geometry_basis}
+
+
+class FireballConsequence(FireballMass):
+    heat_of_combustion_j_kg: Positive
+    burst_pressure_pa_abs: Positive
+    atmosphere: Atmosphere
+    geometry_basis: GeometryBasis
+    maximum_distance_m: Positive
+    personnel_threshold_w_m2: Positive = 12600
+    equipment_threshold_w_m2: Positive = 37800
+    distance_tolerance_m: Positive = 1e-5
+    maximum_iterations: int = Field(default=100,ge=10,le=300,strict=True)
+
+
+@calculation("effects/fireball-consequence", "Rupture fireball radiation consequence chain", FireballConsequence,
+             ["Part3 eqs(3.157)-(3.168); PDF pp555-556"],
+             origin="api581_composition_with_explicit_fireball_geometry_basis",
+             limitations=[_GEOMETRY_LIMIT,
+                          "Instantaneous rupture only. Caller qualifies inventory, combustion heat, and burst pressure: normal operating pressure for normal rupture or likely elevated pressure for PRD failure. Pressure correlation giving radiative fraction above1 is rejected. Constant or water-vapor atmospheric model is explicit. No ignition probability weighting, duration-dose injury model, or LH2 validation."])
+def consequence(x):
+    _tau(x.atmosphere,1)
+    flammable=mass(FireballMass(available_mass_kg=x.available_mass_kg,flammable_mass_fraction=x.flammable_mass_fraction))["flammable_mass_kg"]
+    beta=fireball_fraction(FireballFraction(burst_pressure_pa_abs=x.burst_pressure_pa_abs))["radiative_fraction"]
+    geometry=fireball_geometry(FireballGeometry(flammable_mass_kg=flammable))
+    base={"flammable_mass_kg":flammable,**geometry,"radiative_fraction":beta,"geometry_basis":x.geometry_basis}
+    if flammable == 0:
+        return {**base,"surface_emissive_power_w_m2":0,"personnel_area_m2":0,"equipment_area_m2":0,
+                "personnel_safe_distance_m":0,"equipment_safe_distance_m":0,
+                "personnel_status":"no_flammable_mass","equipment_status":"no_flammable_mass"}
+    ensure(geometry["diameter_m"] > 0 and geometry["duration_s"] > 0,
+           "Fireball geometry underflow","numerical_failure")
+    emissive=fireball_emissive(FireballEmissive(flammable_mass_kg=flammable,heat_of_combustion_j_kg=x.heat_of_combustion_j_kg,
+        radiative_fraction=beta,diameter_m=geometry["diameter_m"],duration_s=geometry["duration_s"]))["surface_emissive_power_w_m2"]
+    ensure(math.isfinite(emissive),"Fireball emissive power exceeds numerical domain","numerical_failure")
+    setup={"diameter_m":geometry["diameter_m"],"surface_emissive_power_w_m2":emissive,"atmosphere":x.atmosphere,
+           "geometry_basis":x.geometry_basis,"maximum_distance_m":x.maximum_distance_m,
+           "distance_tolerance_m":x.distance_tolerance_m,"maximum_iterations":x.maximum_iterations}
+    personnel=distance(FireballDistance(**setup,threshold_w_m2=x.personnel_threshold_w_m2))
+    equipment=distance(FireballDistance(**setup,threshold_w_m2=x.equipment_threshold_w_m2))
+    return {**base,"surface_emissive_power_w_m2":emissive,
+            "personnel_area_m2":personnel["consequence_area_m2"],"equipment_area_m2":equipment["consequence_area_m2"],
+            "personnel_safe_distance_m":personnel["safe_distance_m"],"equipment_safe_distance_m":equipment["safe_distance_m"],
+            "personnel_status":personnel["status"],"equipment_status":equipment["status"]}

api581/flash_pool.py

@@ -0,0 +1,111 @@
+"""Qualified EOS -> rainout -> steady boiling pool -> isolated native dispersion."""
+from typing import Literal
+from pydantic import Field
+from .core import Positive, NonNegative, calculation, ensure, REGISTRY
+from .flash_solver import PureLiquidFlashPartition, pure_liquid_flash_partition
+from .saturation import SaturationPressure, saturation_pressure
+from .evaporation import SurfaceInteraction, BoilingSteadySource, boiling_steady_source
+from .slabx_adapter import (NativeAtmosphere, NativeSubstance, NativePool, native_pool,
+    NativePoolFootprint, native_pool_footprint, NativePoolFlashFire, native_pool_flash_fire)
+
+
+class FlashedBoilingPool(PureLiquidFlashPartition):
+    ground_temperature_k: Positive
+    surface: SurfaceInteraction
+    maximum_pool_area_m2: Positive
+    engine: Literal['slabx','slabx-lh2']
+    atmosphere: NativeAtmosphere
+    receptor_height_m: NonNegative
+    averaging_time_s: Positive
+    plume_distance_limit_m: Positive = Field(le=1e6)
+    puff_time_limit_s: Positive | None = None
+    puff_steps: int = Field(default=40,ge=10,le=1000,strict=True)
+    threshold_volume_fraction: Positive = Field(le=1)
+    threshold_source: str = Field(min_length=1,max_length=1000)
+    meander_closure: Literal['ermak','sigma_theta']
+    lh2_plume_width_coupling: bool
+    native_property_basis: str = Field(min_length=1,max_length=1000)
+    timeout_s: Positive = Field(default=120,le=600)
+
+
+_SOURCE_LIMITATIONS=[
+        'Initially liquid pure fluid only, atmospheric final pressure101325Pa, positive adjusted constant rate and released mass. Boiling pool requires Tb<Tground, area support and time-to-steady shorter than mass/rate supply duration. Unsupported/zero rainout source fails explicitly.',
+        'Native constant source covers ONLY the steady window after time-to-steady, not startup, growing pool, depletion, post-release evaporation or simultaneous jet. Startup pool-feed mass is explicitly unmodeled; jet masses remain separate. Native time origin is start of steady window; no combined jet/pool footprint or risk is inferred.',
+        'Pure-fluid normal-boiling saturated cp, densities and latent heat map to native constant properties only with an explicit qualification basis. No fluid-wide or LH2 EOS/native model validation. Native LH2 premise and censoring still gate usable spatial results. Threshold is caller supplied, not automatically LFL/toxic.']
+
+
+@calculation('dispersion/flashed-boiling-pool-centreline','Pure-liquid flash through steady boiling-pool native centreline',FlashedBoilingPool,
+    ['Part3 §§5.1.3,5.7.2-5.7.4,5.8.5-5.8.6; PDF pp539-544; external SLABx dispersion'],
+    origin='qualified_eos_to_steady_pool_native_composition',limitations=[
+        *REGISTRY['dispersion/native-pool-centreline'].limitations,*_SOURCE_LIMITATIONS])
+def flashed_boiling_pool(x):
+    source,native=_prepare_flashed_boiling_pool(x)
+    return {**source,**native_pool(native),'integration_scope':'flashed_pure_liquid_boiling_pool_steady_window_centreline'}
+
+
+def _prepare_flashed_boiling_pool(x):
+    ensure(bool(x.native_property_basis.strip()) and bool(x.threshold_source.strip()),'Native property and threshold qualification required')
+    ensure(x.final_pressure_pa_abs==101325.,'Native pool integration requires atmospheric final pressure101325Pa')
+    ensure(x.adjusted_mass_rate_kg_s>0 and x.released_mass_kg>0,'Positive adjusted rate and released mass required','no_source_window')
+    partition=pure_liquid_flash_partition(PureLiquidFlashPartition(**x.model_dump(include=set(PureLiquidFlashPartition.model_fields))))
+    ensure(partition['pool_liquid_rate_kg_s']>0,'No liquid rainout source for boiling pool','no_pool_feed')
+    saturation=saturation_pressure(SaturationPressure(fluid=x.fluid,pressure_pa_abs=x.final_pressure_pa_abs,
+        qualification_basis=x.qualification_basis))
+    supply_duration=x.released_mass_kg/x.adjusted_mass_rate_kg_s
+    pool=boiling_steady_source(BoilingSteadySource(bubble_temperature_k=saturation['bubble_temperature_k'],
+        ground_temperature_k=x.ground_temperature_k,latent_heat_j_kg=saturation['latent_heat_j_kg'],surface=x.surface,
+        liquid_feed_rate_kg_s=partition['pool_liquid_rate_kg_s'],pool_vapor_density_kg_m3=saturation['vapor_density_kg_m3'],
+        supply_duration_s=supply_duration,maximum_pool_area_m2=x.maximum_pool_area_m2))
+    ensure(pool['support_status']=='supported','Steady boiling pool unsupported: '+pool['support_status'],'pool_source_unsupported')
+    start=pool['time_to_steady_s']
+    duration=supply_duration-start
+    ensure(x.averaging_time_s<=duration,'Averaging time exceeds supported steady-source window','unsupported_averaging_window')
+    substance=NativeSubstance(fluid_id=x.fluid.casefold(),molecular_weight_kg_kmol=saturation['molecular_weight_kg_kmol'],
+        vapor_heat_capacity_j_kg_k=saturation['vapor_specific_heat_j_kg_k'],liquid_heat_capacity_j_kg_k=saturation['liquid_specific_heat_j_kg_k'],
+        latent_heat_j_kg=saturation['latent_heat_j_kg'],normal_boiling_point_k=saturation['bubble_temperature_k'],
+        liquid_density_kg_m3=saturation['liquid_density_kg_m3'],property_source='CoolProp8.0.0 saturated normal-boiling properties; '+x.native_property_basis)
+    native_keys=('engine','atmosphere','receptor_height_m','averaging_time_s','plume_distance_limit_m','puff_time_limit_s',
+        'puff_steps','threshold_volume_fraction','threshold_source','meander_closure','lh2_plume_width_coupling','timeout_s')
+    native=NativePool(**x.model_dump(include=set(native_keys)),substance=substance,
+        vapor_source_rate_kg_s=pool['vapor_source_rate_kg_s'],source_area_m2=pool['pool_area_m2'],release_duration_s=duration,
+        source_qualification='Steady boiling pool only, excludes startup/jet; '+x.atmospheric_partition_basis)
+    source={**partition,**saturation,**pool,'steady_window_start_s':start,'steady_window_duration_s':duration,
+        'steady_evaporated_mass_kg':pool['vapor_source_rate_kg_s']*duration,
+        'startup_unmodeled_pool_mass_kg':partition['pool_liquid_rate_kg_s']*start}
+    return source,native
+
+
+class FlashedBoilingPoolFootprint(FlashedBoilingPool):
+    crosswind_half_span_m: Positive
+    crosswind_points_per_side: int = Field(default=65,ge=3,le=501,strict=True)
+
+
+@calculation('dispersion/flashed-boiling-pool-footprint','Pure-liquid flash through steady boiling-pool planar footprint',FlashedBoilingPoolFootprint,
+    ['Part3 §§5.7.2-5.7.4,5.8.5-5.8.6; external native planar concentration field'],
+    origin='qualified_eos_to_steady_pool_native_footprint',limitations=[
+        *_SOURCE_LIMITATIONS,
+        *REGISTRY['dispersion/native-pool-footprint'].limitations])
+def flashed_boiling_pool_footprint(x):
+    source,native=_prepare_flashed_boiling_pool(x)
+    footprint=native_pool_footprint(NativePoolFootprint(**native.model_dump(),
+        crosswind_half_span_m=x.crosswind_half_span_m,crosswind_points_per_side=x.crosswind_points_per_side))
+    return {**source,**footprint,'integration_scope':'flashed_pure_liquid_boiling_pool_steady_window_footprint'}
+
+
+class FlashedBoilingPoolFlashFire(FlashedBoilingPoolFootprint):
+    criterion_role: Literal['qualified_lfl']
+    receptor_height_m: Literal[0.0]
+
+
+@calculation('dispersion/flashed-boiling-pool-flash-fire','Pure-liquid flash through steady boiling-pool flash-fire areas',FlashedBoilingPoolFlashFire,
+    ['Part3 §§5.7.2-5.7.4,5.8.6,4.8.2.3; native LFL planar field'],
+    origin='qualified_eos_to_steady_pool_native_flash_fire',limitations=[
+        *REGISTRY['dispersion/flashed-boiling-pool-footprint'].limitations,
+        *REGISTRY['dispersion/native-pool-flash-fire'].limitations,
+        'Only this selected steady pool vapor scenario. No startup/jet/post-release pool consequence or ignition/GFF weighting. LFL declaration and averaging require owner qualification; no automatic criterion lookup or final risk.'])
+def flashed_boiling_pool_flash_fire(x):
+    source,native=_prepare_flashed_boiling_pool(x)
+    consequence=native_pool_flash_fire(NativePoolFlashFire(**native.model_dump(),
+        crosswind_half_span_m=x.crosswind_half_span_m,crosswind_points_per_side=x.crosswind_points_per_side,
+        criterion_role=x.criterion_role))
+    return {**source,**consequence,'integration_scope':'flashed_pure_liquid_boiling_pool_steady_window_flash_fire'}

api581/flash_solver.py

@@ -0,0 +1,122 @@
+"""Optional pure-fluid CoolProp flash backend with typed public registry integration."""
+import math
+from typing import Literal
+from pydantic import Field, model_validator
+from .core import Model, Positive, NonNegative, Fraction, ensure, calculation
+
+
+class PureFluidFlash(Model):
+    fluid: str = Field(pattern=r'^[A-Za-z][A-Za-z0-9_-]{0,79}$')
+    storage_pressure_pa_abs: Positive
+    storage_temperature_k: Positive | None = None
+    storage_vapor_mass_fraction: Fraction | None = None
+    final_pressure_pa_abs: Positive
+    method: Literal['isentropic','isenthalpic']
+    qualification_basis: str = Field(min_length=1)
+
+    @model_validator(mode='after')
+    def storage_state_is_unambiguous(self):
+        if (self.storage_temperature_k is None)==(self.storage_vapor_mass_fraction is None):
+            raise ValueError('Provide exactly one storage temperature or equilibrium vapor mass fraction')
+        return self
+
+
+@calculation('properties/pure-fluid-flash','Qualified pure-fluid isentropic or isenthalpic flash',PureFluidFlash,
+    ['Part3 §5.1.3,STEP1.3; PDF pp539-541'],origin='optional_coolprop_8_0_0_pure_fluid_flash',limitations=[
+        'Optional CoolProp8.0.0 required. Pure-fluid HEOS expansion only; no mixtures,arbitrary backend strings,supercritical final pressure or equilibrium chemistry. Isentropic source preference and acceptable isenthalpic alternative explicitly selected. Returns final equilibrium vapor mass fraction,not incremental vaporized fraction or API581 rainout. Single-phase Q=-1 is not a physical quality: phase identifies0/1 vapor fraction. Storage uses exactly one of PT (unambiguous single phase) or pressure/equilibrium mass quality (triple-point to subcritical coexistence). Saturated PT ambiguities and invalid EOS states fail explicitly. Signed quality change includes condensation and is not rainout. Pure-propane reference verified; no independent fluid-wide/LH2 validation or hydraulic two-phase flow calculation. Final pressure supplied explicitly; atmospheric applicability owner-qualified.'])
+def solve_pure_fluid_flash(inputs: PureFluidFlash) -> dict:
+    """Internal backend for Part3 §5.1.3; requires optional CoolProp8.0.0."""
+    ensure(bool(inputs.qualification_basis.strip()),'Fluid identity and EOS applicability qualification required')
+    ensure(inputs.final_pressure_pa_abs < inputs.storage_pressure_pa_abs,'Flash expansion requires final pressure below storage')
+    try:
+        import CoolProp
+        from CoolProp.CoolProp import PropsSI, PhaseSI, get_fluid_param_string
+    except ImportError:
+        ensure(False,'Pure-fluid flash requires optional CoolProp8.0.0','optional_engine_missing')
+    ensure(CoolProp.__version__=='8.0.0','Flash backend requires tested CoolProp8.0.0','engine_version_mismatch')
+    fluid=inputs.fluid
+    try:
+        ensure(get_fluid_param_string(fluid,'pure')=='true',
+            'Pseudopure fluids and mixtures are outside pure-fluid flash scope','unsupported_flash_fluid')
+        # No arbitrary backend strings or mixtures; fixed pure-fluid HEOS backend.
+        critical=PropsSI('pcrit',fluid)
+        ensure(inputs.final_pressure_pa_abs < critical,'Final pressure must be below critical pressure')
+        key='Smass' if inputs.method=='isentropic' else 'Hmass'
+        p=inputs.storage_pressure_pa_abs
+        if inputs.storage_vapor_mass_fraction is not None:
+            ensure(PropsSI('ptriple',fluid)<=p<critical,
+                'Equilibrium storage quality requires triple-point to subcritical pressure','unsupported_storage_phase')
+            storage_vapor_fraction=inputs.storage_vapor_mass_fraction
+            coordinate,coordinate_value='Q',storage_vapor_fraction
+            storage_phase=PhaseSI('P',p,coordinate,coordinate_value,fluid)
+            ensure(storage_phase=='twophase','EOS did not return an equilibrium storage state','invalid_engine_result')
+            t=PropsSI('T','P',p,coordinate,coordinate_value,fluid)
+            state_basis='pressure_quality'
+        else:
+            t=inputs.storage_temperature_k
+            coordinate,coordinate_value='T',t
+            storage_phase=PhaseSI('P',p,coordinate,coordinate_value,fluid)
+            if storage_phase in ('liquid','supercritical_liquid'):
+                storage_vapor_fraction=0.
+            elif storage_phase in ('gas','supercritical_gas'):
+                storage_vapor_fraction=1.
+            else:
+                ensure(False,'Storage PT state must be unambiguous single-phase liquid or gas','unsupported_storage_phase')
+            state_basis='pressure_temperature'
+        value=PropsSI(key,'P',p,coordinate,coordinate_value,fluid)
+        final=inputs.final_pressure_pa_abs
+        temperature=PropsSI('T','P',final,key,value,fluid)
+        phase=PhaseSI('P',final,key,value,fluid)
+        quality=PropsSI('Q','P',final,key,value,fluid)
+        if phase=='twophase':
+            ensure(0<=quality<=1,'EOS returned invalid two-phase mass quality','invalid_engine_result')
+            vapor_fraction=quality
+        elif phase in ('liquid','supercritical_liquid'):
+            vapor_fraction=0.
+        elif phase in ('gas','supercritical_gas'):
+            vapor_fraction=1.
+        else:
+            ensure(False,'Unsupported flashed phase: '+phase,'unsupported_flash_phase')
+        density=PropsSI('Dmass','P',final,key,value,fluid)
+        result=dict(flashed_temperature_k=temperature,vapor_mass_fraction=vapor_fraction,flashed_phase=phase,
+            bulk_density_kg_m3=density,conserved_property=key,conserved_value_si=value,engine_version=CoolProp.__version__,
+            storage_phase=storage_phase,storage_vapor_mass_fraction=storage_vapor_fraction,
+            vapor_mass_fraction_change=vapor_fraction-storage_vapor_fraction,
+            storage_temperature_k=t,storage_state_basis=state_basis)
+        ensure(all(math.isfinite(result[k]) for k in ('flashed_temperature_k','vapor_mass_fraction','bulk_density_kg_m3','conserved_value_si','storage_temperature_k')),
+            'Nonfinite EOS flash result','invalid_engine_result')
+        ensure(temperature>0 and density>0 and t>0,'Nonpositive EOS temperature/density','invalid_engine_result')
+        return result
+    except ValueError as exc:
+        from .core import DomainError
+        if isinstance(exc,DomainError):
+            raise
+        ensure(False,'CoolProp could not solve supplied pure-fluid state','flash_solver_failure')
+
+
+class PureLiquidFlashPartition(PureFluidFlash):
+    adjusted_mass_rate_kg_s: NonNegative
+    released_mass_kg: NonNegative
+    equation_basis: Literal['api581_printed','post_flash_mass_balance']
+    atmospheric_partition_basis: str = Field(min_length=1)
+
+
+@calculation('release/pure-liquid-flash-partition','Pure-liquid flash with explicit pool/jet composition basis',PureLiquidFlashPartition,
+    ['Part3 §§5.7.1-5.7.3 eqs(3.98)-(3.102); PDF p543'],
+    origin='qualified_pure_liquid_flash_source_partition_composition',limitations=[
+        'Optional CoolProp8.0.0; only unambiguous initially liquid pure fluid. Final pressure and atmospheric applicability must be qualified. Kletz rainout correlation is used, not experimentally validated for every fluid. Printed entrainment and conservation interpretation remain explicitly distinct; no silent erratum. Input mass/rate already detection/isolation/inventory adjusted. No hydraulic rate calculation, pool evaporation, mixtures or LH2 validation.'])
+def pure_liquid_flash_partition(inputs: PureLiquidFlashPartition) -> dict:
+    from .source_partition import Rainout, rainout, SourcePartition, source_partition
+    ensure(bool(inputs.atmospheric_partition_basis.strip()),'Atmospheric partition applicability basis required')
+    state=solve_pure_fluid_flash(PureFluidFlash(**inputs.model_dump(include=set(PureFluidFlash.model_fields))))
+    ensure(state['storage_vapor_mass_fraction']==0.,
+        'Liquid-flash partition requires initially liquid storage; gas condensation is a separate path','unsupported_partition_storage_phase')
+    quality=state['vapor_mass_fraction']
+    fraction=rainout(Rainout(flash_mass_fraction=quality))['rainout_mass_fraction']
+    composition=(dict(stored_liquid_mass_fraction=1.,flash_mass_fraction=quality)
+        if inputs.equation_basis=='api581_printed' else dict(post_flash_vapor_mass_fraction=quality))
+    partition=source_partition(SourcePartition(adjusted_mass_rate_kg_s=inputs.adjusted_mass_rate_kg_s,
+        released_mass_kg=inputs.released_mass_kg,rainout_mass_fraction=fraction,equation_basis=inputs.equation_basis,
+        rainout_basis_source='API581 Kletz eqs(3.98)-(3.99); '+inputs.atmospheric_partition_basis,
+        flash_property_source='CoolProp8.0.0 '+inputs.method+'; '+inputs.qualification_basis,**composition))
+    return {**state,**partition,'rainout_mass_fraction':fraction}

api581/groundwater.py

@@ -0,0 +1,101 @@
+"""Annex2.B §11.3.3 groundwater guidance; no invented TKS/rate correlation."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, calculation, ensure
+from .thinning import WallLoss, Posterior
+from .clad_thinning import PressureStrength, CodeStrength
+from .thinning_conditions import ThinningConditions, QualifiedUnclad, qualified_unclad
+
+
+Units=Literal['printed_si','printed_us_converted']
+
+
+class GroundwaterChemistry(Model):
+    chloride_mg_l: NonNegative
+    sulfate_mg_l: NonNegative
+    dissolved_co2_mg_l: NonNegative
+    bicarbonate_mg_l: NonNegative
+    carbonate_mg_l: NonNegative
+    sulfide_mg_l: NonNegative
+    ammonia_mg_l: NonNegative
+    concentration_basis: str = Field(min_length=1)
+
+
+@calculation('damage/groundwater-tks','Groundwater Total Key Species on a qualified common concentration basis',GroundwaterChemistry,
+    ['Part2 Annex2.B §11.3.3; PDF p405'],limitations=[
+        'Sum of seven explicitly supplied species concentrations, public mg/L on a qualified common analytical basis. No missing species assumed zero, molar/mass conversion, speciation or charge balance. Inputs must not double-count total inorganic carbon or report nitrogen/sulfur equivalents without conversion qualification. Source supplies no TKS thresholds or TKS-to-corrosion-rate equation; no automatic corrosivity or corrosion rate inferred.'])
+def groundwater_tks(x):
+    ensure(bool(x.concentration_basis.strip()),'Consistent analytical species concentration basis required')
+    values=[getattr(x,name) for name in GroundwaterChemistry.model_fields if name!='concentration_basis']
+    try:
+        total=math.fsum(values)
+    except OverflowError:
+        ensure(False,'TKS sum exceeds finite numerical domain','numerical_failure')
+    return {'total_key_species_mg_l':total}
+
+
+class GroundwaterRate(Model):
+    corrosion_rate_m_year: NonNegative
+    unit_basis: Units
+    shared_boundary_policy: Literal['lower_severity','higher_severity'] | None = None
+
+
+@calculation('damage/groundwater-rate-classification','Groundwater steel corrosivity category from supplied corrosion rate',GroundwaterRate,
+    ['Part2 Annex2.B §11.3.3(a)-(d); PDF p405'],limitations=[
+        'Classifies a supplied steel corrosion rate, not TKS. Printed SI limits.03/.25/1.27mm/year differ from1/10/50mpy converted exactly. Explicit unit basis required. The medium/high shared.25mm/year or10mpy endpoint needs explicit lower/higher severity policy. Low is strictly below first threshold; very high strictly above last. No material-specific rate prediction, treatment credit or degradation immunity.'])
+def groundwater_rate_classification(x):
+    first,middle,last=(.00003,.00025,.00127) if x.unit_basis=='printed_si' else (.0000254,.000254,.00127)
+    rate=x.corrosion_rate_m_year
+    shared=rate==middle
+    ensure((x.shared_boundary_policy is not None)==shared,
+        'Medium/high shared endpoint requires a boundary policy, unused policy must be omitted','ambiguous_groundwater_boundary')
+    category=('low' if rate<first else 'medium' if rate<middle else
+        ('medium' if x.shared_boundary_policy=='lower_severity' else 'high') if shared else
+        'high' if rate<=last else 'very_high')
+    bounds={'low':(0.,first,'inclusive','exclusive'),'medium':(first,middle,'inclusive','inclusive'),
+        'high':(middle,last,'inclusive','inclusive'),'very_high':(last,None,'exclusive','unbounded')}
+    lower,upper,lower_relation,upper_relation=bounds[category]
+    return dict(corrosion_rate_m_year=rate,corrosivity_category=category,selected_unit_basis=x.unit_basis,
+        category_lower_bound_m_year=lower,category_upper_bound_m_year=upper,
+        lower_bound_relation=lower_relation,upper_bound_relation=upper_relation,shared_boundary_encountered=shared)
+
+
+class GroundwaterAssessment(Model):
+    chemistry: GroundwaterChemistry
+    qualified_rate: GroundwaterRate
+    steel_applicability_basis: str = Field(min_length=1)
+    specialist_rate_basis: str = Field(min_length=1)
+
+
+@calculation('damage/groundwater-assessment','Qualified groundwater chemistry and externally established steel corrosion rate',GroundwaterAssessment,
+    ['Part2 Annex2.B §11.3.3; PDF p405'],origin='source_guidance_with_qualified_external_rate',limitations=[
+        'Competent water-corrosivity specialist must establish the steel corrosion rate independently. TKS is reported alongside that rate, never used to invent source cutoffs or a rate regression. No groundwater-specific quantitative rate equation is provided by the standard. Chemistry, material and specialist qualifications are supplied, not independently verified.'])
+def groundwater_assessment(x):
+    ensure(bool(x.steel_applicability_basis.strip()) and bool(x.specialist_rate_basis.strip()),
+        'Steel applicability and competent-specialist rate bases required')
+    return {**groundwater_tks(x.chemistry),**groundwater_rate_classification(x.qualified_rate),
+        'rate_source':'qualified_external_groundwater_rate','tks_to_rate_model_available':False}
+
+
+class GroundwaterThinning(Model):
+    corrosion: GroundwaterAssessment
+    assessment_distribution: Literal['general','local']
+    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/groundwater-thinning-assessment','Qualified groundwater rate through non-AST unclad thinning',GroundwaterThinning,
+    ['Part2 Annex2.B §11.3.3; Part2 §4.5.7,Table4.8'],origin='qualified_external_groundwater_rate_to_thinning',limitations=[
+        'Same externally qualified groundwater rate drives loss and non-AST unclad thinning; general/local inspection and steel applicability require explicit basis. No automatic pitting multiplier, TKS-derived rate, MIC/deposit exclusions or treatment credit. Monitoring row must be other; no borrowed acid/sour-water credits. Qualified experience replacement remains separately available under Table4.8. No cladding, AST, FFS or all-mechanism assessment.'])
+def groundwater_thinning(x):
+    ensure(x.conditions.monitoring.row.mechanism=='other','Groundwater must use other-mechanism monitoring row')
+    corrosion=groundwater_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,'assessment_distribution':x.assessment_distribution}