api581-engine 0.1.4__py3-none-any.whl

api581/thinning_selection.py

@@ -0,0 +1,81 @@
+"""Source-wide measured-rate precedence and multi-mechanism thinning selection."""
+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
+
+
+class MeasuredThinningRate(Model):
+    corrosion_rate_m_year: NonNegative
+    representative_for_current_period: bool
+    measurement_basis: str = Field(min_length=1)
+
+
+class FallbackThinningRate(Model):
+    corrosion_rate_m_year: NonNegative
+    method: Literal['calculated','estimated']
+    rate_basis: str = Field(min_length=1)
+
+
+class MechanismThinningRate(Model):
+    mechanism_id: str = Field(min_length=1,max_length=100)
+    thinning_type: Literal['general','local']
+    measured: MeasuredThinningRate | None = None
+    fallback: FallbackThinningRate | None = None
+
+
+class ThinningRateSelection(Model):
+    mechanisms: list[MechanismThinningRate] = Field(min_length=1,max_length=100)
+    applicability_and_period_basis: str = Field(min_length=1)
+
+
+@calculation('damage/thinning-rate-selection','Measured-first and maximum-mechanism rate with governing thinning type',ThinningRateSelection,
+    ['Part2 §§4.5.2,4.5.4; PDF pp150-151'],limitations=[
+        'Caller supplies all applicable mechanisms for one component, assessed surface and common current-process plan period. Representative measured CML/history rate wins within each mechanism, including explicit zero. Otherwise exactly the supplied calculated/estimated fallback is used; no invented priority between estimated and calculated rates. Rate is maximum across mechanisms, not sum. Local inspection type governs if any applicable mechanism is local, even when its rate is lower. No missing mechanism assumed absent, automatic mechanism screening, CML regression, rate confidence inference or forecast. Long-term current-process representativeness and rate/type provenance require qualification.'])
+def thinning_rate_selection(x):
+    ensure(bool(x.applicability_and_period_basis.strip()),'Applicable mechanisms and common assessed period qualification required')
+    ids=[m.mechanism_id for m in x.mechanisms]
+    ensure(all(s.strip() for s in ids) and len(set(ids))==len(ids),'Mechanism IDs must be nonblank and unique')
+    rates,sources,ignored={},{},{}
+    for item in x.mechanisms:
+        ensure(item.measured is not None or item.fallback is not None,'Every mechanism requires a measured rate or explicit fallback')
+        if item.measured is not None:
+            ensure(item.measured.representative_for_current_period and bool(item.measured.measurement_basis.strip()),
+                'Measured rate requires qualified current-process/period representativeness')
+            rates[item.mechanism_id]=item.measured.corrosion_rate_m_year
+            sources[item.mechanism_id]='measured'
+        else:
+            ensure(bool(item.fallback.rate_basis.strip()),'Fallback calculated/estimated rate basis required')
+            rates[item.mechanism_id]=item.fallback.corrosion_rate_m_year
+            sources[item.mechanism_id]=item.fallback.method
+        ignored[item.mechanism_id]=item.measured is not None and item.fallback is not None
+    maximum=max(rates.values())
+    distribution='local' if any(m.thinning_type=='local' for m in x.mechanisms) else 'general'
+    return dict(corrosion_rate_m_year=maximum,assessment_distribution=distribution,
+        governing_rate_mechanism_ids=sorted(k for k,v in rates.items() if v==maximum),
+        governing_type_mechanism_ids=sorted(m.mechanism_id for m in x.mechanisms if m.thinning_type==distribution),
+        rate_by_mechanism_m_year=rates,selection_source_by_mechanism=sources,fallback_ignored_by_mechanism=ignored)
+
+
+class SelectedMechanismThinning(Model):
+    selection: ThinningRateSelection
+    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/thinning-selected-mechanisms','Selected multi-mechanism rate through qualified non-AST thinning',SelectedMechanismThinning,
+    ['Part2 §§4.5.2,4.5.4,4.5.7; Table4.8'],origin='qualified_multi_mechanism_rate_to_thinning',limitations=[
+        'Maximum selected rate drives one common wall/strength baseline; most localized assigned mechanism governs inspection scope. Caller must qualify inspections for that governing type and all applicable loss locations. Generic composition uses other monitoring row with table factor1; mechanism-specific credits cannot be borrowed across mechanisms. Qualified Table4.8 experience replacement is explicit. Custom priors remain supported. No rate summation, multiple-surface loss, all-mechanism DF, AST, cladding, CML history interpretation or whole-asset risk.'])
+def selected_mechanism_thinning(x):
+    ensure(x.conditions.monitoring.row.mechanism=='other','Generic multi-mechanism composition requires other monitoring row')
+    selection=thinning_rate_selection(x.selection)
+    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=selection['corrosion_rate_m_year'],elapsed_years=x.elapsed_years),
+        strength=x.strength,inspections=x.inspections,conditions=x.conditions))
+    return {**selection,**result}

api581/thinning_type.py

@@ -0,0 +1,34 @@
+"""API 581 Annex 2.B thinning-type designation."""
+
+from typing import Literal
+from pydantic import Field
+from .core import Model, calculation, ensure
+
+
+class ThinningTypeSelection(Model):
+    effective_inspection_types: list[Literal["general", "localized"]] = Field(default_factory=list, max_length=100)
+    applicable_mechanism_types: list[Literal["general", "localized"]] = Field(min_length=1, max_length=100)
+    qualification_basis: str = Field(min_length=1, max_length=1000)
+
+
+@calculation(
+    "damage/thinning-type",
+    "API 581 Annex 2.B.1.2 general versus localized thinning designation",
+    ThinningTypeSelection,
+    ["Part 2 Annex B §1.2; Part 2 §4.5.2, PDF p321"],
+    origin="api581_annex_2b1_2_thinning_type_selection",
+    limitations=[
+        "Effective inspection designation takes precedence. If no effective inspection type is supplied, any applicable localized mechanism conservatively selects localized thinning. This API does not screen mechanisms or calculate corrosion rates.",
+        "The caller must qualify the mechanism list and inspection effectiveness; an empty inspection list is treated as unknown, not as evidence of general thinning."
+    ],
+)
+def thinning_type(x):
+    ensure(x.qualification_basis.strip(), "Thinning-type qualification basis must be nonblank")
+    observed = x.effective_inspection_types
+    source = "effective_inspection_results" if observed else "applicable_mechanism_conservative_default"
+    types = observed or x.applicable_mechanism_types
+    selected = "localized" if "localized" in types else "general"
+    return {"thinning_type": selected, "selection_source": source,
+            "effective_inspection_types": observed,
+            "applicable_mechanism_types": x.applicable_mechanism_types,
+            "qualification_basis": x.qualification_basis}

api581/toxic_criteria.py

@@ -0,0 +1,111 @@
+"""Explicit historical toxic-criterion priority with exposure-duration matching."""
+import math
+from typing import Literal
+from pydantic import Field, model_validator
+from .core import Model, Positive, Fraction, calculation, ensure, finite_tree
+from .toxic_level2 import ToxicFluid, SpeciesThreshold, impact_table, species_threshold, MixtureLimit, mixture_limit, _ROWS, _TABLE_LIMIT
+
+Kind = Literal["probit50","lc50","erpg3","aegl3","teel3","idlh","epa_endpoint"]
+_TIER = dict(probit50=1,lc50=1,erpg3=2,aegl3=2,teel3=2,idlh=3,epa_endpoint=3)
+
+
+class CriterionCandidate(Model):
+    criterion_id: str = Field(min_length=1,max_length=100)
+    kind: Kind
+    concentration_ppm: Positive = Field(le=1e6)
+    exposure_duration_s: Positive
+    source: str = Field(min_length=1,max_length=1000)
+
+    @model_validator(mode="after")
+    def source_basis(self):
+        if not self.criterion_id.strip() or not self.source.strip():
+            raise ValueError("Criterion id and source must be nonblank")
+        windows = {"idlh":{1800.},"erpg3":{3600.},"teel3":{900.},"aegl3":{600.,1800.,3600.}}
+        if self.kind in windows and self.exposure_duration_s not in windows[self.kind]:
+            raise ValueError("Criterion duration conflicts with API5812016 exposure windows")
+        return self
+
+
+class ToxicCriterion(Model):
+    fluid_id: str = Field(min_length=1,max_length=100)
+    exposure_duration_s: Positive
+    use_printed_table: bool = True
+    additional_candidates: list[CriterionCandidate] = Field(default_factory=list,max_length=50)
+    excluded_candidate_ids: dict[str,str] = Field(default_factory=dict)
+    selected_criterion_id: str | None = Field(default=None,min_length=1,max_length=100)
+    toxic_mole_fraction: Fraction = 1.
+    candidate_availability_basis: str = Field(min_length=1,max_length=1000)
+
+
+@calculation("consequence/select-toxic-criterion", "Select duration-matched toxic criterion by API581 priority", ToxicCriterion,
+    ["Part3 §5.9.2,Table4.14,eqs(3.189)-(3.190); PDF pp531,565-567"],
+    origin="api581_explicit_toxic_criterion_selection",limitations=[_TABLE_LIMIT,
+        "Only provided candidates and the enabled historical table snapshot are considered, not an external literature/current-limit search. Caller declares candidate availability/applicability; named exclusions require a nonblank basis. Printed probit uses50% fatality and supplied exposure seconds. Same-priority ties require explicit selection, not minimum/maximum of incomparable limits.",
+        "Exposure durations match exactly. Printed IDLH uses1800s, ERPG3600s, AEGL600/1800/3600 only where available. LC50/TEEL/EPA ppm must be owner-qualified candidates; EPA mg/L is not silently converted. A lower-priority selection cannot override an eligible higher-priority candidate without explicit exclusion.",
+        "Mixture threshold divides pure-component ppm by toxic MOLE fraction once. Zero fraction means absent component; mathematically above1e6ppm is unattainable, not capped. Returned threshold is a criterion, not a field exposure duration or validated damage footprint."])
+def select_criterion(x):
+    ensure(x.fluid_id.strip() and x.candidate_availability_basis.strip(),"Fluid and availability bases must be nonblank")
+    external_ids = [c.criterion_id for c in x.additional_candidates]
+    ensure(len(set(external_ids)) == len(external_ids),"Duplicate external criterion id")
+    ensure(all(not key.startswith("printed:") for key in external_ids),"External ids must not use reserved printed: prefix")
+    candidates,unavailable = [],{}
+    def add(identifier,kind,value,source):
+        candidates.append(dict(criterion_id=identifier,kind=kind,concentration_ppm=value,
+            exposure_duration_s=x.exposure_duration_s,source=source))
+    if x.use_printed_table:
+        ensure(x.fluid_id in _ROWS,"Unknown2016 toxic fluid; disable printed table only with qualified external candidates","unsupported_toxic_fluid")
+        row = impact_table(ToxicFluid(fluid=x.fluid_id))
+        if row["probit_available"]:
+            ppm = species_threshold(SpeciesThreshold(fluid=x.fluid_id,exposure_duration_s=x.exposure_duration_s,
+                target_fatality_probability=.5))["concentration_ppm"]
+            add("printed:probit50","probit50",ppm,"2016 Table4.14/Annex3.A probit50; time seconds")
+        else:
+            unavailable["printed:probit50"] = "No printed probit coefficients"
+        for identifier,kind,value,required in (("printed:idlh","idlh",row["idlh_ppm"],1800.),
+                                               ("printed:erpg3","erpg3",row["erpg3_ppm"],3600.)):
+            if value is None:
+                unavailable[identifier] = "No printed value"
+            elif x.exposure_duration_s != required:
+                unavailable[identifier] = f"Requires exposure{required:g}s"
+            else:
+                add(identifier,kind,value,"2016 Table4.14 historical "+kind)
+        aegl = row["aegl3_ppm"].get(str(int(x.exposure_duration_s))) if x.exposure_duration_s.is_integer() else None
+        if aegl is None:
+            unavailable["printed:aegl3"] = "No printed value at selected exposure duration"
+        else:
+            add("printed:aegl3","aegl3",aegl,"2016 Table4.14 AEGL3 at selected duration")
+        if row["epa_toxic_endpoint_mg_l"] is not None:
+            unavailable["printed:epa_endpoint"] = "Published mg/L needs explicit qualified ppm conversion; provide external candidate"
+    for candidate in x.additional_candidates:
+        if candidate.exposure_duration_s == x.exposure_duration_s:
+            candidates.append(candidate.model_dump())
+        else:
+            unavailable[candidate.criterion_id] = "Exposure duration mismatch"
+    ids = [c["criterion_id"] for c in candidates]
+    ensure(len(set(ids)) == len(ids),"Duplicate eligible criterion id")
+    for identifier,basis in x.excluded_candidate_ids.items():
+        ensure(identifier in ids,"Exclusion must name an eligible candidate")
+        ensure(basis.strip(),"Criterion exclusion basis must be nonblank")
+    eligible = [c for c in candidates if c["criterion_id"] not in x.excluded_candidate_ids]
+    ensure(eligible,"No eligible duration-matched toxic criterion","toxic_criterion_unavailable")
+    tier = min(_TIER[c["kind"]] for c in eligible)
+    first = [c for c in eligible if _TIER[c["kind"]] == tier]
+    if x.selected_criterion_id is None:
+        ensure(len(first) == 1,"Same-priority criteria require explicit selected_criterion_id","ambiguous_toxic_criterion")
+        selected = first[0]
+    else:
+        matching = [c for c in eligible if c["criterion_id"] == x.selected_criterion_id]
+        ensure(matching,"Selected criterion must be eligible")
+        selected = matching[0]
+        ensure(_TIER[selected["kind"]] == tier,"Eligible higher-priority criterion must be excluded explicitly","toxic_criterion_priority_conflict")
+    mixture = mixture_limit(MixtureLimit(pure_component_limit_ppm=selected["concentration_ppm"],toxic_mole_fraction=x.toxic_mole_fraction))
+    finite_tree(mixture)
+    fraction = mixture["modified_mixture_limit_ppm"]/1e6 if mixture["component_present"] and mixture["attainable_in_mixture"] else None
+    ensure(fraction is None or fraction > 0,"Toxic volume fraction underflow","numerical_failure")
+    return {"fluid_id":x.fluid_id,"selected_criterion_id":selected["criterion_id"],"selected_kind":selected["kind"],
+        "priority_tier":tier,"pure_component_limit_ppm":selected["concentration_ppm"],
+        "modified_mixture_limit_ppm":mixture["modified_mixture_limit_ppm"],"threshold_volume_fraction":fraction,
+        "component_present":mixture["component_present"],"attainable_in_mixture":mixture["attainable_in_mixture"],
+        "exposure_duration_s":x.exposure_duration_s,"criterion_source":selected["source"],
+        "eligible_candidate_ids":[c["criterion_id"] for c in eligible],"excluded_candidate_ids":x.excluded_candidate_ids,
+        "unavailable_candidate_reasons":unavailable}

api581/toxic_level2.py

@@ -0,0 +1,233 @@
+"""2016 toxic table snapshot, exposure calculations and dispersion-area handoff."""
+import math
+import sys
+from statistics import NormalDist
+from typing import Annotated, Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+
+Fluid = Literal["acrolein","acrylonitrile","aluminum_trichloride","ammonia","benzene","bromine",
+    "carbon_monoxide","carbon_tetrachloride","chlorine","ethylene_glycol_monoethyl_ether","ethylene_oxide",
+    "formaldehyde","hydrogen_chloride","hydrogen_cyanide","hydrogen_fluoride","hydrogen_sulfide","methanol",
+    "methyl_bromide","methyl_isocyanate","nitric_acid","nitrogen_dioxide","phosgene","propylene_oxide",
+    "styrene","sulphur_dioxide","toluene","toluene_diisocyanate"]
+# A,B,N,IDLH ppm,AEGL3(10/30/60min) ppm,EPA mg/L,ERPG3 ppm.
+# Dashes remain None. Historical printed values are not current exposure limits.
+_ROWS={
+    "acrolein":(-9.93,2.05,1,2,None,None,None,.50,None),
+    "acrylonitrile":(-29.42,3.01,1.43,85,None,None,None,.08,75),
+    "aluminum_trichloride":(-14.65,2,1,None,None,None,None,None,None),
+    "ammonia":(-35.90,1.85,2,10,None,None,None,.14,750),
+    "benzene":(-109.8,5.30,2,500,None,None,None,None,1000),
+    "bromine":(-9.04,.92,2,3,None,None,None,.01,5),
+    "carbon_monoxide":(-37.98,3.70,1,1200,1700,600,330,None,500),
+    "carbon_tetrachloride":(-6.29,.41,2.5,200,None,None,None,None,750),
+    "chlorine":(-8.29,.92,2,10,None,28,20,.01,20),
+    "ethylene_glycol_monoethyl_ether":(-15.54,1,2,None,None,None,None,None,None),
+    "ethylene_oxide":(-6.21,1,1,800,None,None,None,None,None),
+    "formaldehyde":(-12.24,1.30,2,20,None,None,None,.01,25),
+    "hydrogen_chloride":(-16.85,2,1,50,620,210,100,.03,150),
+    "hydrogen_cyanide":(-29.42,3.01,1.43,50,27,21,15,None,25),
+    "hydrogen_fluoride":(-48.33,4.853,1,30,170,62,44,None,None),
+    "hydrogen_sulfide":(-31.42,3.01,1.43,100,76,60,50,None,100),
+    "methanol":(None,None,None,None,15000,15000,7900,None,None),
+    "methyl_bromide":(-56.81,5.27,1,None,None,None,None,None,200),
+    "methyl_isocyanate":(-5.64,1.64,.65,None,1.2,.4,.2,None,5),
+    "nitric_acid":(-5.48,1,2,None,None,None,None,None,None),
+    "nitrogen_dioxide":(-13.79,1.40,2,20,None,None,None,None,None),
+    "phosgene":(-19.27,3.69,1,2,3.6,1.5,.75,None,1),
+    "propylene_oxide":(-7.415,.509,2,400,None,None,None,.59,750),
+    "styrene":(None,None,None,700,None,None,None,None,1000),
+    "sulphur_dioxide":(-15.67,2.10,1,100,None,None,None,None,None),
+    "toluene":(-6.79,.41,2.5,500,1600,900,630,None,None),
+    "toluene_diisocyanate":(-4.49,1,2,None,None,None,None,None,None),
+}
+_TABLE_LIMIT="Historical2016 Table4.14 snapshot, not current occupational/emergency exposure guidance. Printed ammonia IDLH10ppm retained. Dashes are unavailable, not zero. Probit concentration ppm and time seconds follow Annex3.A nomenclature; caller must qualify coefficient/species applicability. EPA mg/L is not implicitly converted to ppm."
+
+
+class ToxicFluid(Model):
+    fluid: Fluid
+
+
+@calculation("properties/toxic-impact-table", "2016 Table4.14 toxic criteria and probit parameters", ToxicFluid,
+             ["Part3 Table4.14; PDF p531; Annex3.A nomenclature PDF624"],limitations=[_TABLE_LIMIT])
+def impact_table(x):
+    a,b,n,idlh,a10,a30,a60,epa,erpg=_ROWS[x.fluid]
+    return {"probit_intercept":a,"probit_slope":b,"concentration_exponent":n,"probit_available":a is not None,
+            "probit_concentration_unit":"ppm","probit_duration_unit":"s","idlh_ppm":idlh,
+            "aegl3_ppm":{duration:value for duration,value in [("600",a10),("1800",a30),("3600",a60)] if value is not None},
+            "epa_toxic_endpoint_mg_l":epa,"erpg3_ppm":erpg}
+
+
+def _coefficients(fluid):
+    a,b,n=_ROWS[fluid][:3]
+    ensure(a is not None,"No printed probit parameters for selected fluid","toxic_probit_unavailable")
+    return a,b,n
+
+
+def _effect(fluid,logdose):
+    a,b,_=_coefficients(fluid)
+    if logdose is None:
+        return {"probit":None,"fatality_probability":0}
+    probit=a+b*logdose
+    return {"probit":probit,"fatality_probability":.5*math.erfc(-(probit-5)/math.sqrt(2))}
+
+
+PPM = Annotated[float,Field(ge=0,le=1e6,strict=True,allow_inf_nan=False)]
+
+
+class SpeciesProbit(ToxicFluid):
+    concentration_ppm: PPM
+    exposure_duration_s: NonNegative
+
+
+@calculation("effects/toxic-species-probit", "Table4.14 constant-exposure toxic probit", SpeciesProbit,
+             ["Part3 Table4.14, Annex3.A eq(3.A.5); PDF pp531,620,624"],limitations=[_TABLE_LIMIT,
+                          "Pr=A+B*ln(C^N*t); probability=Phi(Pr-5). Constant species concentration, not whole-mixture concentration. Zero exposure gives zero probability with no finite probit. No dispersion, escape or dose-response validation for a particular installation."])
+def species_probit(x):
+    _,_,n=_coefficients(x.fluid)
+    logdose=None if x.concentration_ppm == 0 or x.exposure_duration_s == 0 else n*math.log(x.concentration_ppm)+math.log(x.exposure_duration_s)
+    return _effect(x.fluid,logdose)
+
+
+class SpeciesThreshold(ToxicFluid):
+    exposure_duration_s: Positive
+    target_fatality_probability: Fraction = .5
+
+
+@calculation("effects/toxic-species-threshold", "Species concentration for target toxic probit probability", SpeciesThreshold,
+             ["Part3 Table4.14, Annex3.A eq(3.A.5) inverse; PDF pp531,620,624"],
+             origin="api581_toxic_probit_inverse",limitations=[_TABLE_LIMIT,
+                          "Default50% fatality corresponds to Pr5. Probability must be strictly between0 and1. Reports whether mathematical threshold is within pure-species1e6ppm limit; values above this are not silently capped."])
+def species_threshold(x):
+    a,b,n=_coefficients(x.fluid)
+    ensure(0 < x.target_fatality_probability < 1,"Target probability must be strictly between0 and1")
+    probit=5+NormalDist().inv_cdf(x.target_fatality_probability)
+    concentration=math.exp(((probit-a)/b-math.log(x.exposure_duration_s))/n)
+    ensure(concentration > 0,"Toxic threshold underflow","numerical_failure")
+    return {"concentration_ppm":concentration,"probit":probit,"within_pure_species_limit":concentration <= 1e6}
+
+
+class ConcentrationPoint(Model):
+    time_s: NonNegative
+    concentration_ppm: PPM
+
+
+class DoseProfile(ToxicFluid):
+    profile: list[ConcentrationPoint] = Field(min_length=2,max_length=10000)
+    interpolation: Literal["previous","linear"]
+    profile_source: str = Field(min_length=1,max_length=1000)
+
+
+@calculation("effects/toxic-dose-profile", "Time-varying species dose and Table4.14 probit", DoseProfile,
+             ["Part3 Annex3.A eq(3.A.5); PDF pp531,620,624"],
+             origin="engineering_transient_extension_of_api581_probit",limitations=[_TABLE_LIMIT,
+                          "Explicit extension: replaces constant C^N*t with integral C(t)^N dt. Previous holds each left concentration; final point only closes last interval. Linear integrates concentration power analytically, not a trapezoid of C^N. Not a printed transient API581 equation or an actual slabx run. No tail outside supplied profile and no automatic exposure cap."])
+def dose_profile(x):
+    _,_,n=_coefficients(x.fluid)
+    ensure(bool(x.profile_source.strip()),"Profile source must be nonblank")
+    ensure(x.profile[0].time_s == 0 and all(b.time_s > a.time_s for a,b in zip(x.profile,x.profile[1:])),
+           "Concentration profile must start at0 with strictly increasing times")
+    logs=[]
+    for a,b in zip(x.profile,x.profile[1:]):
+        dt=b.time_s-a.time_s
+        if x.interpolation == "previous":
+            if a.concentration_ppm == 0:
+                continue
+            average_log=n*math.log(a.concentration_ppm)
+        else:
+            high=max(a.concentration_ppm,b.concentration_ppm)
+            if high == 0:
+                continue
+            ratio=min(a.concentration_ppm,b.concentration_ppm)/high
+            factor=(1 if ratio == 1 else 1/(n+1) if ratio == 0
+                    else -math.expm1((n+1)*math.log(ratio))/((n+1)*(1-ratio)))
+            average_log=n*math.log(high)+math.log(factor)
+        logs.append(math.log(dt)+average_log)
+    duration=x.profile[-1].time_s
+    if not logs:
+        return {**_effect(x.fluid,None),"dose_ppm_power_n_s":0,"log_dose":None,"dose_representable":True,
+                "duration_s":duration,"equivalent_constant_concentration_ppm":0}
+    largest=max(logs)
+    logdose=largest+math.log(math.fsum(math.exp(value-largest) for value in logs))
+    dose=math.exp(logdose) if math.log(math.ulp(0.0)) <= logdose <= math.log(sys.float_info.max) else None
+    return {**_effect(x.fluid,logdose),"dose_ppm_power_n_s":dose,"log_dose":logdose,"dose_representable":dose is not None,
+            "duration_s":duration,"equivalent_constant_concentration_ppm":math.exp((logdose-math.log(duration))/n)}
+
+
+class ToxicDuration(Model):
+    available_mass_kg: NonNegative
+    mixture_release_rate_kg_s: NonNegative
+    detection_maximum_duration_s: NonNegative
+
+
+@calculation("release/level2-toxic-duration", "Level2 toxic release duration bound", ToxicDuration,
+             ["Part3 eq(3.186), §5.9.3; PDF p566"],
+             limitations=["Minimum of3600s, full inventory/full mixture rate, detection/isolation duration. Do not divide full inventory by toxic-component rate. Constant-rate source approximation; no transient depressurization. Release duration is not automatically receptor exposure duration."])
+def toxic_duration(x):
+    if x.mixture_release_rate_kg_s == 0 or x.available_mass_kg == 0:
+        return {"release_duration_s":0,"governing_limit":"no_release" if x.mixture_release_rate_kg_s == 0 else "no_inventory"}
+    values=[(3600,"one_hour"),(x.available_mass_kg/x.mixture_release_rate_kg_s,"inventory"),
+            (x.detection_maximum_duration_s,"detection_isolation")]
+    duration,limit=min(values,key=lambda item:item[0])
+    ensure(duration > 0 or x.detection_maximum_duration_s == 0,
+           "Positive toxic release duration underflow","numerical_failure")
+    return {"release_duration_s":duration,"governing_limit":limit}
+
+
+class MixtureLimit(Model):
+    pure_component_limit_ppm: Positive
+    toxic_mole_fraction: Fraction
+
+
+@calculation("consequence/toxic-mixture-limit", "Homogeneous mixture cloud toxic concentration criterion", MixtureLimit,
+             ["Part3 eqs(3.189)-(3.190); PDF p567"],limitations=["Divides pure-component ppm criterion by toxic mole fraction, not mass fraction. Applies when dispersion concentration represents entire homogeneous mixture using full release rate. Species-resolved concentration must not be divided again. Zero mole fraction means absent component; no finite modified criterion is returned."])
+def mixture_limit(x):
+    if x.toxic_mole_fraction == 0:
+        return {"modified_mixture_limit_ppm":None,"component_present":False,"attainable_in_mixture":False}
+    modified=x.pure_component_limit_ppm/x.toxic_mole_fraction
+    return {"modified_mixture_limit_ppm":modified,"component_present":True,"attainable_in_mixture":modified <= 1e6}
+
+
+class ToxicCloudArea(Model):
+    component_id: str = Field(min_length=1,max_length=100)
+    selected_criterion_source: str = Field(min_length=1,max_length=1000)
+    cloud_area_m2: NonNegative
+
+
+class ToxicCase(Model):
+    components: list[ToxicCloudArea] = Field(min_length=1,max_length=100)
+    non_ignition_probability: Fraction
+
+
+@calculation("consequence/level2-toxic-case", "Selected toxic cloud footprints to conditional toxic consequence", ToxicCase,
+             ["Part3 §§5.9.2,5.9.4-5.9.6 eq(3.188); PDF pp565-567"],
+             limitations=["Caller supplies one chosen criterion and qualified footprint per toxic component. Criteria hierarchy: probit/LC50, then ERPG3/AEGL3/TEEL3, then IDLH/EPA endpoint. Selection within a tier is caller-qualified, not maximum across incomparable exposure criteria. Takes largest component area and applies non-ignition probability once; equipment toxic damage area is0. Does not run dispersion or sum overlapping clouds."])
+def toxic_case(x):
+    ensure(len({c.component_id for c in x.components}) == len(x.components),"Duplicate toxic component")
+    ensure(all(c.component_id.strip() and c.selected_criterion_source.strip() for c in x.components),"Component and criterion source must be nonblank")
+    critical=max(x.components,key=lambda c:c.cloud_area_m2)
+    return {"equipment_area_m2":0,"personnel_area_m2":x.non_ignition_probability*critical.cloud_area_m2,
+            "unweighted_cloud_area_m2":critical.cloud_area_m2,"critical_component_id":critical.component_id,
+            "component_cloud_areas_m2":{c.component_id:c.cloud_area_m2 for c in x.components}}
+
+
+class ToxicFrequencyCase(ToxicCase):
+    hole: Literal["small","medium","large","rupture"]
+    generic_frequency_per_year: NonNegative
+
+
+class ToxicSummary(Model):
+    cases: list[ToxicFrequencyCase] = Field(min_length=4,max_length=4)
+
+
+@calculation("consequence/level2-toxic-summary", "Four-hole GFF-weighted Level2 toxic consequence", ToxicSummary,
+             ["Part3 eqs(3.188),(3.191); PDF p567"],origin="api581_toxic_four_hole_composition",
+             limitations=["Requires all four canonical holes once. Takes component maximum and non-ignition weighting within each hole, then generic-frequency average. No DF-adjusted frequency substitution or financial/individual-risk computation. Cloud footprints and selected exposure criteria remain externally qualified inputs."])
+def toxic_summary(x):
+    ensure({c.hole for c in x.cases} == {"small","medium","large","rupture"},"Require four distinct canonical hole sizes")
+    total=math.fsum(c.generic_frequency_per_year for c in x.cases)
+    ensure(math.isfinite(total) and total > 0,"Total generic frequency must be finite and positive")
+    areas={c.hole:toxic_case(ToxicCase(**c.model_dump(include=set(ToxicCase.model_fields))))["personnel_area_m2"] for c in x.cases}
+    return {"equipment_area_m2":0,"personnel_area_m2":math.fsum(c.generic_frequency_per_year/total*areas[c.hole] for c in x.cases),
+            "total_generic_frequency_per_year":total,"by_hole_personnel_area_m2":areas}

api581/two_phase_events.py

@@ -0,0 +1,120 @@
+"""Explicit two-phase probability weighting and correlated figure event paths."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+from .ignition import (TemperatureReference, SinglePhaseIgnition, single_phase_ignition,
+    TwoPhaseProbability, two_phase_probability, FlammableRates, flammable_rates)
+
+
+class FireballConditional(Model):
+    phase: Literal["liquid","vapor","two_phase"]
+    release_type: Literal["continuous","instantaneous"]
+    case_type: Literal["leakage","rupture"]
+    applicability_basis: Literal["rupture_only_text","figure53_instantaneous"]
+
+
+@calculation("events/fireball-given-immediate", "Fireball conditional applicability from text or figure basis", FireballConditional,
+             ["Part3 eqs(3.123)-(3.124),Figure5.3; PDF pp549,586"],
+             origin="api581_fireball_conditional_with_explicit_applicability",
+             limitations=["Conditional on immediate ignition. Text basis requires instantaneous rupture of vapor/two-phase; explicit figure53 basis also allows instantaneous leakage. Liquid and continuous cases give0. Correlation does not establish thermal-model applicability or certify leakage fireballs."])
+def fireball_given_immediate(x):
+    allowed=(x.phase in {"vapor","two_phase"} and x.release_type == "instantaneous" and (
+        x.case_type == "rupture" or x.applicability_basis == "figure53_instantaneous"))
+    return {"fireball_given_immediate":1 if allowed else 0}
+
+
+class TwoPhaseContext(Model):
+    release_type: Literal["continuous","instantaneous"]
+    case_type: Literal["leakage","rupture"]
+    qualified_rupture_fireball_fraction: Fraction | None = None
+    rupture_fireball_source: str | None = Field(default=None,min_length=1,max_length=1000)
+
+
+class TwoPhaseTree(TwoPhaseContext):
+    ignition_probability: Fraction
+    immediate_given_ignition: Fraction
+    vce_given_delayed: Fraction
+    branch_probability_source: str = Field(min_length=1,max_length=1000)
+
+
+@calculation("events/two-phase-tree", "Two-phase figure paths including one correlated jet/pool event", TwoPhaseTree,
+             ["Part3 Figures5.3/5.4,eqs(3.123)-(3.126); PDF pp549,586-587"],
+             origin="api581_two_phase_printed_figure_event_tree",
+             limitations=["Continuous leakage immediate branch is one jet_pool_max terminal, not independent jet and pool fires. Instantaneous leakage immediate branch is fireball per figure53 despite text conflict. Rupture instantaneous immediate fireball fraction defaults1 per eq3.123; figure54 alternative requires explicit fraction/source, remaining immediate probability goes to pool. Continuous rupture unsupported. Non-ignition still requires toxic/NFNT analysis."])
+def two_phase_tree(x):
+    ensure(x.branch_probability_source.strip(),"Branch probability source must be nonblank")
+    ensure(x.case_type != "rupture" or x.release_type == "instantaneous","Continuous rupture tree unsupported")
+    ensure((x.qualified_rupture_fireball_fraction is None) == (x.rupture_fireball_source is None),
+           "Qualified rupture fireball fraction and source must be supplied together")
+    if x.qualified_rupture_fireball_fraction is not None:
+        ensure(x.case_type == "rupture" and x.rupture_fireball_source.strip(),"Fireball fraction override only for qualified rupture branch")
+    basis="figure53_instantaneous" if x.case_type == "leakage" and x.release_type == "instantaneous" else "rupture_only_text"
+    conditional=fireball_given_immediate(FireballConditional(phase="two_phase",release_type=x.release_type,
+        case_type=x.case_type,applicability_basis=basis))["fireball_given_immediate"]
+    if x.qualified_rupture_fireball_fraction is not None:
+        conditional=x.qualified_rupture_fireball_fraction
+    pi,immediate,vce=x.ignition_probability,x.immediate_given_ignition,x.vce_given_delayed
+    probabilities={event:0.0 for event in ["pool_fire","jet_fire","fireball","vce","flash_fire","jet_pool_max"]}
+    if x.release_type == "continuous":
+        probabilities["jet_pool_max"]=pi*immediate
+    else:
+        probabilities["fireball"]=pi*immediate*conditional
+        probabilities["pool_fire"]=pi*immediate*(1-conditional)
+    probabilities["vce"]=pi*(1-immediate)*vce
+    probabilities["flash_fire"]=pi*(1-immediate)*(1-vce)
+    nonignition=1-pi
+    return {"terminal_probabilities":probabilities,"non_ignition_probability":nonignition,
+            "probability_sum":math.fsum([*probabilities.values(),nonignition]),"fireball_given_immediate":conditional,
+            "fireball_probability_basis":"api581_eq3_123_124" if x.qualified_rupture_fireball_fraction is None else "qualified_figure54_branch",
+            "fireball_applicability_basis":basis}
+
+
+class TwoPhaseIgnition(TwoPhaseContext,TemperatureReference):
+    adjusted_mass_rate_kg_s: NonNegative
+    flammable_mass_fraction: Fraction
+    flash_mass_fraction: Fraction
+    liquid_flash_point_temperature_k: Positive
+    vapor_flash_point_temperature_k: Positive
+    vapor_molecular_weight_kg_kmol: Positive
+    storage_temperature_k: Positive
+    autoignition_temperature_k: Positive
+    correlation_basis_source: str = Field(min_length=1,max_length=1000)
+    mixing_basis: Literal["api581_printed_liquid_weight","qualified_vapor_weight"]
+    weighting_source: str = Field(min_length=1,max_length=1000)
+
+
+@calculation("events/two-phase-ignition", "Phase rates and ignition correlations to two-phase terminal paths", TwoPhaseIgnition,
+             ["Part3 eqs(3.106)-(3.124),Table5.3,Figures5.3/5.4; PDF pp546-549,583,586-587"],
+             origin="api581_two_phase_ignition_composition_with_explicit_bases",
+             limitations=["Requires strictly mixed atmospheric flash fraction0<f<1; endpoints belong to single-phase model. Composes phase-specific flammable rates, flash points, vapor MW, common qualified AIT/reference, Table5.3 and explicit phase weighting. Printed liquid-weight basis is preserved as source interpretation, not validated physical phase weighting. Zero fuel gives zero ignition. No EOS, two-phase hydraulics, effect footprints or LH2 validation; correlated jet_pool_max must remain one area branch."])
+def two_phase_ignition(x):
+    ensure(0 < x.flash_mass_fraction < 1,"Two-phase ignition requires0<flash fraction<1; use single-phase at endpoints")
+    rates=flammable_rates(FlammableRates(adjusted_mass_rate_kg_s=x.adjusted_mass_rate_kg_s,
+        flammable_mass_fraction=x.flammable_mass_fraction,flash_mass_fraction=x.flash_mass_fraction))
+    setup=x.model_dump(include=set(TemperatureReference.model_fields))
+    setup.update(release_type=x.release_type,case_type=x.case_type,storage_temperature_k=x.storage_temperature_k,
+        autoignition_temperature_k=x.autoignition_temperature_k,correlation_basis_source=x.correlation_basis_source)
+    phase_results={}
+    for phase in ["liquid","vapor"]:
+        rate=rates[f"flammable_{phase}_rate_kg_s"]
+        ensure(rate > 0 or rates["flammable_rate_kg_s"] == 0,"Positive phase fuel rate underflow","numerical_failure")
+        phase_results[phase]=single_phase_ignition(SinglePhaseIgnition(**setup,phase=phase,flammable_rate_kg_s=rate,
+            flash_point_temperature_k=x.liquid_flash_point_temperature_k if phase == "liquid" else x.vapor_flash_point_temperature_k,
+            molecular_weight_kg_kmol=x.vapor_molecular_weight_kg_kmol if phase == "vapor" else None))
+    def mix(field):
+        return two_phase_probability(TwoPhaseProbability(liquid_probability=phase_results["liquid"][field],
+            vapor_probability=phase_results["vapor"][field],flash_mass_fraction=x.flash_mass_fraction,
+            mixing_basis=x.mixing_basis,weighting_source=x.weighting_source))["probability"]
+    ignition,immediate,vce=mix("ignition_probability"),mix("immediate_given_ignition"),mix("vce_given_delayed")
+    tree=two_phase_tree(TwoPhaseTree(**x.model_dump(include=set(TwoPhaseContext.model_fields)),
+        ignition_probability=ignition,immediate_given_ignition=immediate,vce_given_delayed=vce,
+        branch_probability_source="Composed phase correlations/Table5.3 and explicit mixing basis"))
+    return {**tree,**rates,"ignition_probability":ignition,"immediate_given_ignition":immediate,
+            "vce_given_delayed":vce,"flash_given_delayed":1-vce,"mixing_basis":x.mixing_basis,
+            "liquid_ignition_probability":phase_results["liquid"]["ignition_probability"],
+            "vapor_ignition_probability":phase_results["vapor"]["ignition_probability"],
+            "liquid_immediate_given_ignition":phase_results["liquid"]["immediate_given_ignition"],
+            "vapor_immediate_given_ignition":phase_results["vapor"]["immediate_given_ignition"],
+            "reference_temperature_k":phase_results["liquid"]["reference_temperature_k"],
+            "temperature_weight":phase_results["liquid"]["temperature_weight"]}

api581/workflow.py

@@ -0,0 +1,42 @@
+"""Bounded declarative composition, with no eval, arbitrary imports or shell commands."""
+from typing import Any
+from pydantic import Field
+from .core import Model, Context, DomainError, evaluate, ensure
+
+
+class Step(Model):
+    step_id: str = Field(pattern=r"^[A-Za-z][A-Za-z0-9_]{0,63}$")
+    calculation_id: str
+    inputs: dict[str, Any]
+
+
+class Workflow(Model):
+    context: Context = Field(default_factory=Context)
+    steps: list[Step] = Field(min_length=1, max_length=50)
+
+
+def run_workflow(workflow: Workflow):
+    """References are {"$ref": "previous_step.outputs.field"}. Forward refs are rejected."""
+    results = {}
+
+    def resolve(value, depth=0):
+        ensure(depth <= 30, "Workflow input nesting exceeds 30", "invalid_workflow")
+        if isinstance(value, dict):
+            if "$ref" in value:
+                ensure(set(value) == {"$ref"} and isinstance(value["$ref"], str), "Invalid reference", "invalid_workflow")
+                path = value["$ref"].split(".")
+                ensure(len(path) >= 3 and path[0] in results and path[1] == "outputs", "References must target outputs of earlier steps", "invalid_workflow")
+                cursor = results[path[0]]
+                for key in path[1:]:
+                    ensure(isinstance(cursor, dict) and key in cursor, "Missing reference field", "invalid_workflow")
+                    cursor = cursor[key]
+                return cursor
+            return {k: resolve(v, depth + 1) for k, v in value.items()}
+        if isinstance(value, list):
+            return [resolve(v, depth + 1) for v in value]
+        return value
+
+    for step in workflow.steps:
+        ensure(step.step_id not in results, "Duplicate step_id", "invalid_workflow")
+        results[step.step_id] = evaluate(step.calculation_id, resolve(step.inputs), workflow.context)
+    return {"status": "succeeded", "scope": "explicit_user_composed_calculations", "steps": results}