api581-engine 0.1.4__py3-none-any.whl

api581/sulfuric_acid.py

@@ -0,0 +1,209 @@
+"""2016 sulfuric source tables, explicit header/cell conflicts 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
+from ._sulfuric_tables import TABLES
+from .thinning import Posterior, WallLoss
+from .clad_thinning import PressureStrength, CodeStrength
+from .thinning_conditions import ThinningConditions, QualifiedUnclad, qualified_unclad
+
+Material=Literal["carbon_steel","ss_304","ss_316","alloy_20","alloy_c276","alloy_b2"]
+Group=Literal["carbon_steel","stainless_steel","higher_alloy"]
+Units=Literal["printed_si","printed_us_converted"]
+
+
+def _qualified(value,message):
+    ensure(bool(value.strip()),message)
+
+
+def _group(material):
+    return "carbon_steel" if material=="carbon_steel" else "stainless_steel" if material.startswith("ss_") else "higher_alloy"
+
+
+class SulfuricAxes(Model):
+    material: Material
+    unit_basis: Units
+    carbon_si_velocity_policy: Literal["reject_ambiguous_header","qualified_printed_m_s","qualified_us_ft_s_header"]="reject_ambiguous_header"
+    carbon_si_velocity_qualification_basis: str | None=None
+
+
+@calculation("damage/sulfuric-table-axes", "Sulfuric material table concentration temperature and velocity axes", SulfuricAxes,
+    ["Part2 Tables2.B.5.2-5.7M; PDF pp365-372"],limitations=[
+        "Six named materials only. CS SI header saysm/s but repeats US numericft/s headings0,1,2,3,4.5,6.5,8.5,11.5,12: default reject, qualified literalSI or US-header interpretation explicit. SI/US temperature axes retained literally, includingAlloy20 SI70C versus US163.5F. No automatic temperature/unit repair, extrapolation or cross-material substitution. Axes alone do not establish table applicability."])
+def table_axes(x):
+    ambiguous=x.material=="carbon_steel" and x.unit_basis=="printed_si"
+    if ambiguous:
+        ensure(x.carbon_si_velocity_policy!="reject_ambiguous_header" and x.carbon_si_velocity_qualification_basis is not None and bool(x.carbon_si_velocity_qualification_basis.strip()),
+            "Carbon-steel SI velocity header requires explicit qualified interpretation","sulfuric_si_velocity_header")
+    else:
+        ensure(x.carbon_si_velocity_policy=="reject_ambiguous_header" and x.carbon_si_velocity_qualification_basis is None,"Carbon SI header policy unused for this table")
+    data=TABLES[x.material+"_"+x.unit_basis]
+    velocity=list(data["velocities_m_s"])
+    if ambiguous and x.carbon_si_velocity_policy=="qualified_us_ft_s_header":
+        velocity=[v*.3048 for v in velocity]
+    return {"acid_mass_fraction_nodes":sorted(data["concentrations"]),"temperature_nodes_k":list(data["temperatures_k"]),
+        "velocity_nodes_m_s":velocity,"source_table_id":"2.B.5."+str(("carbon_steel","ss_304","ss_316","alloy_20","alloy_c276","alloy_b2").index(x.material)+2)+("M" if x.unit_basis=="printed_si" else ""),
+        "carbon_si_velocity_interpretation":x.carbon_si_velocity_policy if ambiguous else "not_applicable"}
+
+
+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 sulfuric table; extrapolation not permitted")
+    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 SulfuricRate(SulfuricAxes):
+    acid_mass_fraction: Fraction
+    maximum_temperature_k: Positive
+    velocity_m_s: NonNegative
+    lookup_policy: Literal["exact_nodes_only","trilinear","maximum_bracketing_value"]
+    oxidants_present: bool | None=None
+    disputed_304_cell_policy: Literal["reject_disputed_cell","qualified_printed_literal"]="reject_disputed_cell"
+    disputed_304_qualification_basis: str | None=None
+
+
+@calculation("damage/sulfuric-table-rate", "Sulfuric concentration temperature velocity material corrosion table", SulfuricRate,
+    ["Part2 Annex2.B §5,Tables5.2-5.7M,Figure5.1; PDF pp363-373"],limitations=[
+        "1776physical SI/US cells. Rates are source maximum estimates, not certified universal bounds. CS turbulent localized enhancement already included, no added3x multiplier or automatic20..50% actual-rate discount. Literal999mpy/25.37mm/y flagged, not infinity/missing.30475wt%,middleT,highestv prints99mpy/2.51mm/y amid999: default reject exact cell/any bracketing corner; qualified printed literal requires basis and flag, no invented999 correction. B2 requires explicit no-oxidant state; oxidizingB2 rejected to source specialist route. Other tables reject unused oxidant input, no oxidant improvement credit. Trilinear/max-corner are explicit numerical policies, not original interpolation instruction; nonmonotonic concentration cannot be replaced by global monotonic rule."])
+def table_rate(x):
+    axes=table_axes(x)
+    if x.material=="alloy_b2":
+        ensure(x.oxidants_present is not None and not x.oxidants_present,"Oxidizing/unknown B2 sulfuric service requires specialist estimate","sulfuric_b2_oxidizing")
+    else:
+        ensure(x.oxidants_present is None,"Oxidant input only used for B2 table")
+    q=x.disputed_304_cell_policy=="qualified_printed_literal"
+    ensure((x.disputed_304_qualification_basis is not None and bool(x.disputed_304_qualification_basis.strip()) and x.material=="ss_304") if q else x.disputed_304_qualification_basis is None,
+        "304 disputed cell policy and material/qualification basis must agree")
+    data=TABLES[x.material+"_"+x.unit_basis]
+    a,b,w=_bracket(axes["acid_mass_fraction_nodes"],x.acid_mass_fraction)
+    i,j,v=_bracket(axes["temperature_nodes_k"],x.maximum_temperature_k)
+    l,m,u=_bracket(axes["velocity_nodes_m_s"],x.velocity_m_s)
+    ensure(x.lookup_policy!="exact_nodes_only" or (a==b and i==j and l==m),"Exact sulfuric policy does not interpolate")
+    corners=list(product((a,b),(i,j),(l,m)))
+    def rate(c,t,s):
+        return data["rates"][len(data["concentrations"])-1-c][t][s]
+    disputed=x.material=="ss_304" and any(axes["acid_mass_fraction_nodes"][c]==.75 and t==1 and s==2 for c,t,s in corners)
+    ensure(not disputed or q,"Sulfuric304 lookup touches disputed99mpy/2.51mm/y cell","sulfuric_disputed_304_cell")
+    if x.lookup_policy=="maximum_bracketing_value":
+        native=max(rate(*p) for p in corners)
+    else:
+        native=sum(wc*wt*wv*rate(c,t,s) for (c,wc),(t,wt),(s,wv) in product(((a,1-w),(b,w)),((i,1-v),(j,v)),((l,1-u),(m,u))))
+    return {"corrosion_rate_m_year":native*(.001 if x.unit_basis=="printed_si" else .0000254),"source_table_id":axes["source_table_id"],
+        "carbon_si_velocity_interpretation":axes["carbon_si_velocity_interpretation"],"source_999_corner_used":any(rate(*p)==(25.37 if x.unit_basis=="printed_si" else 999) for p in corners),
+        "disputed_304_cell_used":disputed,"source_localized_enhancement_already_included":x.material=="carbon_steel" and m>3}
+
+
+class SulfuricThinningClassification(Model):
+    material_group: Group
+    velocity_m_s: NonNegative
+    threshold_basis: Literal["overview_printed_si","overview_us_converted","detailed_carbon_body_si"]
+    equality_policy: Literal["reject_ambiguous_boundary","qualified_general","qualified_local"]
+    equality_qualification_basis: str | None=None
+
+
+@calculation("damage/sulfuric-thinning-classification", "Sulfuric source general/local thinning velocity classification", SulfuricThinningClassification,
+    ["Part2 Table2.B.1.2,Annex2.B §5.1; PDF pp323,363"],limitations=[
+        "Overview SI thresholdsCS.61/SS1.22/higher1.83m/s versus2/4/6ft/s; detailed CS bodyapprox.91m/s. Explicit basis preserves differences. Overview CS/SS equality overlaps; general equality resolution requires qualified policy, never guessed. Distinct from online-monitoring Table4.8 thresholds3/5/7ft/s and table velocity nodes; do not force all classifications equal. Actual distribution and inspection coverage external."])
+def thinning_classification(x):
+    q=x.equality_policy!="reject_ambiguous_boundary"
+    ensure((x.equality_qualification_basis is not None and bool(x.equality_qualification_basis.strip())) if q else x.equality_qualification_basis is None,"Equality policy and basis must agree")
+    if x.threshold_basis=="detailed_carbon_body_si":
+        ensure(x.material_group=="carbon_steel","Detailed carbon-body threshold only applies to carbon steel")
+        threshold=.91
+    else:
+        index=("carbon_steel","stainless_steel","higher_alloy").index(x.material_group)
+        threshold=(.61,1.22,1.83)[index] if x.threshold_basis=="overview_printed_si" else (2,4,6)[index]*.3048
+    equal=x.velocity_m_s==threshold
+    if equal:
+        ensure(q,"Sulfuric exact velocity boundary needs qualified general/local resolution","sulfuric_thinning_boundary")
+        kind="general" if x.equality_policy=="qualified_general" else "local"
+    else:
+        kind="general" if x.velocity_m_s<threshold else "local"
+    return {"source_thinning_type":kind,"thinning_velocity_threshold_m_s":threshold,"thinning_velocity_boundary_resolved":equal}
+
+
+class SulfuricTableService(Model):
+    method: Literal["source_table"]
+    table: SulfuricRate
+    table_conditions_and_passivity_qualified: bool
+    qualification_basis: str = Field(min_length=1)
+
+
+class SulfuricSpecialistRate(Model):
+    method: Literal["qualified_specialist_rate"]
+    material_description: str = Field(min_length=1)
+    material_group: Group
+    acid_mass_fraction: Fraction
+    maximum_temperature_k: Positive
+    velocity_m_s: NonNegative
+    oxidants_present: bool
+    corrosion_rate_m_year: NonNegative
+    source_reference: str = Field(min_length=1)
+    qualification_basis: str = Field(min_length=1)
+
+
+class SulfuricAssessment(Model):
+    sulfuric_service_present: bool
+    applicability_basis: str = Field(min_length=1)
+    rate_model: SulfuricTableService | SulfuricSpecialistRate | None=Field(default=None,discriminator="method")
+    classification: SulfuricThinningClassification | None=None
+
+
+@calculation("damage/sulfuric-corrosion-assessment", "Qualified sulfuric material rate and thinning classification assessment", SulfuricAssessment,
+    ["Part2 Annex2.B §5,Tables5.1-5.7M,Figure5.1,Table1.2; PDF pp323,363-373"],origin="api581_composition_with_explicit_source_policies",limitations=[
+        "Same velocity/material group must drive supplied classification and selected rate. Table conditions including concentration,maximum local/nozzle conditions,passivity and impurity applicability owner-qualified. No-service0 is sulfuric-specific, not based on free-water absence;100wt% sulfuric table remains valid. OxidizingB2 uses explicit qualified specialist rate/provenance, not fictitious oxidant multiplier or source table prediction. Specialist route may cover other qualified material/conditions. Source maximum estimates retained without extra3x or automatic actual-rate discount. General/local thresholds and online-monitoring thresholds intentionally distinct; no all-mechanismDF/FFS or corrosion equilibrium inferred."])
+def assessment(x):
+    _qualified(x.applicability_basis,"Sulfuric service and concentration applicability qualification required")
+    if not x.sulfuric_service_present:
+        ensure(x.rate_model is None and x.classification is None,"No-sulfuric branch cannot carry unused rate/classification")
+        return {"corrosion_rate_m_year":0.,"source_table_id":None,"carbon_si_velocity_interpretation":"not_applicable","source_999_corner_used":False,
+            "disputed_304_cell_used":False,"source_localized_enhancement_already_included":False,"source_thinning_type":None,"thinning_velocity_threshold_m_s":None,
+            "thinning_velocity_boundary_resolved":False,"rate_source":None,"calculation_branch":"no_sulfuric_service"}
+    ensure(x.rate_model is not None and x.classification is not None,"Sulfuric service requires rate model and classification")
+    m=x.rate_model
+    _qualified(m.qualification_basis,"Actual material/conditions and selected rate qualification required")
+    if m.method=="source_table":
+        ensure(m.table_conditions_and_passivity_qualified,"Source table conditions/passivity must be qualified")
+        velocity=m.table.velocity_m_s; group=_group(m.table.material)
+        result=table_rate(m.table)
+    else:
+        _qualified(m.material_description,"Specialist material identification required")
+        _qualified(m.source_reference,"Specialist rate source reference required")
+        ensure(m.acid_mass_fraction>0,"Exposed sulfuric service requires positive acid concentration")
+        velocity=m.velocity_m_s; group=m.material_group
+        result={"corrosion_rate_m_year":m.corrosion_rate_m_year,"source_table_id":None,"carbon_si_velocity_interpretation":"not_applicable",
+            "source_999_corner_used":False,"disputed_304_cell_used":False,"source_localized_enhancement_already_included":False}
+    ensure(x.classification.velocity_m_s==velocity and x.classification.material_group==group,"Rate and thinning classification must use same velocity/material group")
+    return {**result,**thinning_classification(x.classification),"rate_source":"source_maximum_estimate" if m.method=="source_table" else "qualified_specialist_estimate","calculation_branch":"qualified_sulfuric_service"}
+
+
+class SulfuricThinning(Model):
+    corrosion: SulfuricAssessment
+    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/sulfuric-thinning-assessment", "Qualified sulfuric corrosion through non-AST unclad thinning DF", SulfuricThinning,
+    ["Part2 Annex2.B §5,Table1.2; §4.5.7,Table4.8"],origin="api581_composition_with_explicit_source_policies",limitations=[
+        "Same final rate drives wall loss; same physical velocity/material group must be used for sulfuric monitoring and source classification, but their threshold values differ. Source general/local and actual owner-qualified inspection distribution retained separately. No extra localized3x multiplication or rate discount. No-service0 not DF0; uncertainty/floor retained. Non-AST unclad only, no source condition certification,all-mechanismDF or code/FFS acceptance."])
+def thinning_assessment(x):
+    _qualified(x.distribution_qualification_basis,"Actual inspection coverage and general/local distribution qualification required")
+    corrosion=assessment(x.corrosion)
+    row=x.conditions.monitoring.row
+    ensure(row.mechanism=="sulfuric_acid","Sulfuric corrosion requires sulfuric monitoring row")
+    if x.corrosion.classification is not None:
+        ensure(row.velocity_m_s==x.corrosion.classification.velocity_m_s and row.sulfuric_material_group==x.corrosion.classification.material_group,
+            "Monitoring and corrosion must use same physical velocity/material group")
+    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}

api581/tank.py

@@ -0,0 +1,260 @@
+"""AST source, inventory and seepage calculations with printed native units."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+
+Fluid=Literal["gasoline","light_diesel","heavy_diesel","fuel_oil","crude_oil","heavy_fuel_oil","heavy_crude_oil"]
+Soil=Literal["coarse_sand","fine_sand","very_fine_sand","silt","sandy_clay","clay","concrete_asphalt","gravel"]
+_FLUIDS={"gasoline":(100,684.018,.00401),"light_diesel":(149,734.011,.00104),"heavy_diesel":(205,764.527,.00246),
+    "fuel_oil":(280,775.019,.0369),"crude_oil":(280,775.019,.0369),"heavy_fuel_oil":(422,900.026,.046),"heavy_crude_oil":(422,900.026,.046)}
+_SOILS={"coarse_sand":(.1,.01,.33),"fine_sand":(.01,.001,.33),"very_fine_sand":(.001,.00001,.33),
+    "silt":(1e-5,1e-6,.41),"sandy_clay":(1e-6,1e-7,.45),"clay":(1e-7,1e-8,.50),
+    "concrete_asphalt":(1e-10,1e-11,.3),"gravel":(1,10,.4)}
+BBL_PER_M3=6.29  # Printed C13, not a silently substituted exact oil-barrel conversion.
+
+
+class FluidLookup(Model):
+    fluid: Fluid
+
+
+@calculation("tank/fluid-table", "AST SI representative fluid properties", FluidLookup,
+             ["Part3 Table6.1M; PDF p604"],limitations=["Historical representative liquid properties, not an operating-temperature EOS. Printed SI density/viscosity retained. No automatic alias to a Level1 representative fluid or LH2 properties."])
+def fluid_table(x):
+    mw,rho,mu=_FLUIDS[x.fluid]
+    return {"molecular_weight_kg_kmol":mw,"liquid_density_kg_m3":rho,"dynamic_viscosity_pa_s":mu}
+
+
+class SoilLookup(Model):
+    soil: Soil
+
+
+@calculation("tank/soil-table", "AST SI soil conductivity bounds and porosity", SoilLookup,
+             ["Part3 Table6.2M; PDF p605"],limitations=["Printed lower/upper labels are reversed for most rows; fields preserve printed labels and values without sorting. Eq3.207 arithmetic mean is symmetric. Raw conductivity units cm/s, not m/day. Representative soil values need site qualification."])
+def soil_table(x):
+    lower,upper,porosity=_SOILS[x.soil]
+    return {"printed_lower_bound_cm_s":lower,"printed_upper_bound_cm_s":upper,"porosity":porosity}
+
+
+class WaterConductivity(Model):
+    printed_lower_bound_cm_s: NonNegative
+    printed_upper_bound_cm_s: NonNegative
+
+
+@calculation("tank/soil-water-conductivity", "Mean water hydraulic conductivity in m/day", WaterConductivity,
+             ["Part3 eq(3.207),Annex3.B C31; PDF pp593,648"],limitations=["Uses arithmetic mean, not geometric mean: C31=864 converts cm/s to m/day. Accepts reversed printed bound ordering without relabeling it."])
+def water_conductivity(x):
+    return {"water_hydraulic_conductivity_m_day":432*x.printed_lower_bound_cm_s+432*x.printed_upper_bound_cm_s}
+
+
+class FluidConductivity(Model):
+    water_hydraulic_conductivity_m_day: NonNegative
+    liquid_density_kg_m3: Positive
+    dynamic_viscosity_pa_s: Positive
+    water_density_kg_m3: Positive
+    water_dynamic_viscosity_pa_s: Positive
+
+
+@calculation("tank/fluid-conductivity", "Product hydraulic conductivity from water reference", FluidConductivity,
+             ["Part3 eq(3.205); PDF p592"],limitations=["Water density/viscosity must be supplied at qualified reference conditions. Product/water density ratio and inverse viscosity ratio applied; no hidden standard-water defaults or temperature correction."])
+def fluid_conductivity(x):
+    if x.water_hydraulic_conductivity_m_day == 0:
+        return {"product_hydraulic_conductivity_m_day":0}
+    value=math.exp(math.log(x.water_hydraulic_conductivity_m_day)+math.log(x.liquid_density_kg_m3)-math.log(x.water_density_kg_m3)
+        +math.log(x.water_dynamic_viscosity_pa_s)-math.log(x.dynamic_viscosity_pa_s))
+    ensure(value > 0,"Product conductivity underflow","numerical_failure")
+    return {"product_hydraulic_conductivity_m_day":value}
+
+
+class Seepage(Model):
+    product_hydraulic_conductivity_m_day: NonNegative
+    porosity: Fraction
+
+
+@calculation("tank/seepage-velocity", "AST product seepage velocity through soil", Seepage,
+             ["Part3 eq(3.206); PDF p592"],limitations=["Conductivity divided by strictly positive porosity. Representative porous-medium approximation; no groundwater plume or capillary/unsaturated transport solver."])
+def seepage(x):
+    ensure(x.porosity > 0,"Porosity must be strictly positive")
+    return {"seepage_velocity_m_day":x.product_hydraulic_conductivity_m_day/x.porosity}
+
+
+class BottomHoleCount(Model):
+    tank_diameter_m: Positive
+
+
+@calculation("tank/bottom-hole-count", "AST bottom small-hole count from diameter", BottomHoleCount,
+             ["Part3 Table6.5,Annex3.B C36; PDF pp607,649"],limitations=["max(1,nint((D/30.5)^2)) with positive half-up nearest-integer rounding, not Python bankers rounding. Medium/large counts0. Formula evaluated outside tabulated30.5-91.4m range is flagged; no extrapolation validity claimed."])
+def bottom_hole_count(x):
+    value=(x.tank_diameter_m/30.5)**2
+    ensure(math.isfinite(value),"Hole count outside numerical domain","numerical_failure")
+    return {"small_hole_count":max(1,math.floor(value+.5)),"medium_hole_count":0,"large_hole_count":0,
+            "outside_tabulated_diameter_range":not 30.5 <= x.tank_diameter_m <= 91.4}
+
+
+class BottomInventory(Model):
+    tank_diameter_m: Positive
+    fill_height_m: NonNegative
+    liquid_density_kg_m3: Positive
+
+
+def _inventory(diameter,head,density):
+    volume=math.pi/4*diameter**2*head if head > 0 else 0
+    ensure(volume > 0 or head == 0,"Positive tank inventory underflow","numerical_failure")
+    mass=volume*density
+    ensure(mass > 0 or volume == 0,"Positive inventory mass underflow","numerical_failure")
+    return {"available_volume_m3":volume,"available_volume_bbl":volume*BBL_PER_M3,"available_mass_kg":mass}
+
+
+@calculation("tank/bottom-inventory", "Full cylindrical AST bottom inventory", BottomInventory,
+             ["Part3 eqs(3.219)-(3.221); PDF p596"],limitations=["Vertical cylindrical tank, full contents above bottom. Printed C13=6.29bbl/m3 retained. No roof volume, dished geometry or connected inventory."])
+def bottom_inventory(x):
+    return _inventory(x.tank_diameter_m,x.fill_height_m,x.liquid_density_kg_m3)
+
+
+class ShellInventory(BottomInventory):
+    course_index: int = Field(ge=1,strict=True)
+    course_height_m: Positive
+
+
+@calculation("tank/shell-course-inventory", "Inventory and head above AST shell-course lower edge", ShellInventory,
+             ["Part3 eqs(3.214)-(3.218); PDF pp595-596"],limitations=["Leak located at course lower edge, equal course heights, index starts1. Above-fill courses return physical dry head/inventory0 instead of negative fluid. This dry-course handling is explicit geometry interpretation. Printed C13=6.29 retained."])
+def shell_inventory(x):
+    elevation=(x.course_index-1)*x.course_height_m
+    head=max(0,x.fill_height_m-elevation)
+    return {**_inventory(x.tank_diameter_m,head,x.liquid_density_kg_m3),"course_bottom_elevation_m":elevation,
+            "available_liquid_head_m":head,"course_wet":head > 0}
+
+
+def _flow(native,density):
+    volume=native/(BBL_PER_M3*86400)
+    mass=volume*density
+    ensure(volume > 0 and mass > 0 or native == 0,"Positive tank flow conversion underflow","numerical_failure")
+    return {"native_rate_bbl_day":native,"volume_rate_m3_s":volume,"mass_rate_kg_s":mass}
+
+
+class ShellFlow(Model):
+    hole_diameter_m: NonNegative
+    liquid_head_m: NonNegative
+    liquid_density_kg_m3: Positive
+    discharge_coefficient: Fraction = .61
+    gravity_m_s2: Positive = 9.81
+
+
+@calculation("tank/shell-flow", "Constant-head AST shell-course liquid discharge", ShellFlow,
+             ["Part3 eq(3.209),Annex3.B C32; PDF pp593-594,648"],limitations=["Printed C32=.543 with orifice area mm2, g/head in SI, native result bbl/day. Converts result to m3/s with C13=6.29; rounded constants differ slightly from exact Torricelli units. Cd constrained to source fully-turbulent.60-.65 range, default.61. Constant head, not tank drainage transient or detection/isolation reduction."])
+def shell_flow(x):
+    ensure(.60 <= x.discharge_coefficient <= .65,"Shell discharge coefficient outside source.60-.65 range")
+    area=math.pi*x.hole_diameter_m**2/4
+    native=.543*x.discharge_coefficient*(area*1e6)*math.sqrt(2*x.gravity_m_s2*x.liquid_head_m)
+    ensure(native > 0 or x.hole_diameter_m == 0 or x.liquid_head_m == 0,"Shell source rate underflow","numerical_failure")
+    return {**_flow(native,x.liquid_density_kg_m3),"hole_area_m2":area}
+
+
+class BottomFlow(Model):
+    hole_diameter_m: NonNegative
+    liquid_height_m: NonNegative
+    product_hydraulic_conductivity_m_day: NonNegative
+    liquid_density_kg_m3: Positive
+    number_of_holes: int = Field(ge=0,strict=True)
+    has_release_prevention_barrier: bool
+    transition_hole_basis: Literal["api581_printed","per_hole_scaled"]
+    soil_contact_factor: Positive = .21
+    gravity_m_s2: Positive = 9.81
+
+
+@calculation("tank/bottom-flow", "AST bottom Bernoulli/Giraud/transition discharge", BottomFlow,
+             ["Part3 eqs(3.210)-(3.212),Annex3.B C33-C40; PDF pp594,649"],
+             origin="api581_bottom_flow_with_explicit_transition_count_basis",
+             limitations=["Native units d mm, head m, Kh m/day, result bbl/day. Printed C37 SI/US regime thresholds disagree under conversion; SI threshold used literally, no cross-unit regime equivalence claimed. Eq3.210/211 multiply number of holes; printed3.212 omits it. Required api581_printed preserves omission; per_hole_scaled is explicit alternative, not authorized erratum. RPB substitutes head.0762m when liquid exists; empty tank remains zero. Soil-contact factor.21-1.15. Small-hole constant-head soil leak model, not rupture inventory or groundwater transport."])
+def bottom_flow(x):
+    ensure(.21 <= x.soil_contact_factor <= 1.15,"Soil contact factor outside source.21-1.15 range")
+    d=x.hole_diameter_m*1000
+    h=0 if x.liquid_height_m == 0 else .0762 if x.has_release_prevention_barrier else x.liquid_height_m
+    kh=x.product_hydraulic_conductivity_m_day
+    if d == 0 or h == 0 or kh == 0 or x.number_of_holes == 0:
+        return {**_flow(0,x.liquid_density_kg_m3),"per_hole_native_rate_bbl_day":0,"equation":"zero_flow","liquid_head_used_m":h,
+                "lower_conductivity_threshold_m_day":None,"upper_conductivity_threshold_m_day":None,
+                "applied_hole_multiplier":0,"transition_hole_basis":x.transition_hole_basis}
+    upper=86.4*d**2
+    lower=1.408e-8*math.exp((1.8*math.log(d)-math.log(x.soil_contact_factor)-.4*math.log(h))/.74)
+    ensure(math.isfinite(upper) and math.isfinite(lower) and 0 < lower <= upper,"Bottom-flow threshold ordering outside model domain")
+    if kh > upper:
+        single=.0815*math.pi*d**2*math.sqrt(2*x.gravity_m_s2*h)
+        equation="3.210"
+    elif kh <= lower:
+        single=29.6195*x.soil_contact_factor*d**.2*h**.9*kh**.74
+        equation="3.211"
+    else:
+        ld,lh,lk=math.log10(d),math.log10(h),math.log10(kh)
+        m=5.9352-.4324*ld+.5405*lh
+        ensure(m > 0,"Transition exponent m must be positive")
+        base=(3.9365+2*ld-lk)/m
+        ensure(base > 0,"Transition fractional-power base must be positive")
+        single=1.1341*10**(2*ld+.5*lh-.74*base**m)
+        equation="3.212"
+    multiplier=1 if equation == "3.212" and x.transition_hole_basis == "api581_printed" else x.number_of_holes
+    ensure(single > 0,"Positive bottom discharge underflow","numerical_failure")
+    return {**_flow(single*multiplier,x.liquid_density_kg_m3),"per_hole_native_rate_bbl_day":single,"equation":equation,
+            "liquid_head_used_m":h,"lower_conductivity_threshold_m_day":lower,"upper_conductivity_threshold_m_day":upper,
+            "applied_hole_multiplier":multiplier,"transition_hole_basis":x.transition_hole_basis}
+
+
+class ShellDetection(Model):
+    hole_diameter_m: NonNegative
+    diameter_boundary_basis: Literal["printed_3_17_mm","inch_0_125"]
+
+
+@calculation("tank/shell-detection-time", "AST shell leak detection-time criterion", ShellDetection,
+             ["Part3 §6.7.2 STEP7.2,eq(3.223); PDF pp596-597"],limitations=["Source prints3.17mm paired with.125inch=3.175mm; required basis preserves selection. Diameter at/below selected boundary7days, above1day. AST does not apply generic detection/isolation reduction factors."])
+def shell_detection(x):
+    boundary=.00317 if x.diameter_boundary_basis == "printed_3_17_mm" else .003175
+    return {"detection_time_days":7 if x.hole_diameter_m <= boundary else 1,"diameter_boundary_m":boundary}
+
+
+class BottomDetection(Model):
+    foundation: Literal["concrete_asphalt","other"]
+    has_release_prevention_barrier: bool
+    overlap_basis: Literal["foundation_priority","barrier_priority"] | None = None
+
+
+@calculation("tank/bottom-detection-time", "AST bottom leak detection-time criterion", BottomDetection,
+             ["Part3 §6.7.3 STEP7.2; PDF p597"],limitations=["Concrete/asphalt7days, RPB30days, otherwise360days. Conditions overlap if concrete/asphalt AND RPB: explicit priority required instead of inventing precedence. This is source detection time, not a generic isolation-system factor."])
+def bottom_detection(x):
+    concrete=x.foundation == "concrete_asphalt"
+    if concrete and x.has_release_prevention_barrier:
+        ensure(x.overlap_basis is not None,"Concrete/asphalt with RPB requires explicit detection priority")
+        return {"detection_time_days":7 if x.overlap_basis == "foundation_priority" else 30,
+                "selected_basis":"concrete_asphalt" if x.overlap_basis == "foundation_priority" else "barrier"}
+    return {"detection_time_days":7 if concrete else 30 if x.has_release_prevention_barrier else 360,
+            "selected_basis":"concrete_asphalt" if concrete else "barrier" if x.has_release_prevention_barrier else "unprotected"}
+
+
+class ReleaseVolume(Model):
+    release_case: Literal["leak","rupture"]
+    native_rate_bbl_day: NonNegative
+    available_volume_m3: NonNegative
+    liquid_density_kg_m3: Positive
+    detection_time_days: NonNegative
+
+
+@calculation("tank/release-volume", "Inventory-limited AST leakage or full-volume rupture", ReleaseVolume,
+             ["Part3 eqs(3.223)-(3.230),§6.5; PDF pp596-598"],
+             origin="api581_release_volume_with_dimensional_mass_conversion",
+             limitations=["Leak volume is min(rate*min(inventory/rate,detection time),inventory); rupture uses all available volume without invented duration. Source AST release type remains continuous. Eq3.225/227 print mass=Bbl without density/conversion; printed_mass_index preserves that number separately. released_mass_kg uses(volume m3*density) from3.218/221, an explicit dimensional interpretation, not an authorized erratum. C13=6.29 retained."])
+def release_volume(x):
+    available=x.available_volume_m3*BBL_PER_M3
+    if x.release_case == "rupture":
+        native=available
+        duration=None
+    elif x.native_rate_bbl_day == 0 or available == 0:
+        native=duration=0
+    else:
+        duration=min(available/x.native_rate_bbl_day,x.detection_time_days)
+        ensure(duration > 0 or x.detection_time_days == 0,"Positive AST leak duration underflow","numerical_failure")
+        native=min(available,x.native_rate_bbl_day*duration)
+        ensure(native > 0 or x.detection_time_days == 0,"Positive AST release volume underflow","numerical_failure")
+    volume=x.available_volume_m3 if native == available else native/BBL_PER_M3
+    mass=volume*x.liquid_density_kg_m3
+    ensure(volume > 0 and mass > 0 or native == 0,"AST volume/mass conversion underflow","numerical_failure")
+    return {"release_duration_days":duration,"released_volume_bbl":native,"released_volume_m3":volume,
+            "released_mass_kg":mass,"printed_mass_index":native,"release_type":"continuous"}