api581-engine 0.1.4__py3-none-any.whl

api581/level1.py

@@ -0,0 +1,311 @@
+"""Level 1 release controls and flammable-area tables, explicitly bounded by support."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, Positive, NonNegative, Fraction, calculation, ensure
+from .release import Gas, Liquid, gas, liquid, AvailableInventory, inventory, ReleaseType, release_type, ReleaseMagnitude, magnitude
+from .consequences import Acid, acid, Steam, steam
+from .level1_toxic import ToxicComponent, MitigationCredits, toxic_component
+
+# Four (a,b) pairs in order: continuous AINL, continuous AIL, instantaneous AINL, instantaneous AIL.
+# SI Tables 4.8M / 4.9M, PDF pp522,524. None represents a blank, never zero.
+COEFFICIENTS = {
+    "C1-C2": {"gas": [(8.669,.98),(55.13,.95),(6.469,.67),(163.7,.62), (21.83,.96),(143.2,.92),(12.46,.67),(473.9,.63)]},
+    "C3-C4": {"gas": [(10.13,1),(64.23,1),(4.590,.72),(79.94,.63), (25.64,1),(171.4,1),(9.702,.75),(270.4,.63)]},
+    "C5": {"gas": [(5.115,.99),(62.41,1),(2.214,.73),(41.38,.61), (12.71,1),(166.1,1),(4.820,.76),(146.7,.63)],
+           "liquid": [(100.6,.89),None,(.271,.85),None, (290.1,.89),None,(.790,.85),None]},
+    "C6-C8": {"gas": [(5.846,.98),(63.98,1),(2.188,.66),(41.49,.61), (13.49,.96),(169.7,1),(4.216,.67),(147.2,.63)],
+              "liquid": [(34.17,.89),(103.4,.95),(.749,.78),(8.180,.55), (96.88,.89),(252.8,.92),(2.186,.78),(31.89,.54)]},
+    "C9-C12": {"gas": [(2.419,.98),(76.98,.95),(1.111,.66),(42.28,.61), (5.755,.96),(188.6,.92),(2.035,.66),(151.0,.63)],
+               "liquid": [(24.60,.90),(110.3,.95),(.559,.76),(.848,.53), (70.03,.89),(269.4,.92),(1.609,.76),(2.847,.54)]},
+    "C13-C16": {"liquid": [(12.11,.90),(196.7,.92),(.086,.88),(1.714,.88), (34.36,.89),(539.4,.90),(.242,.88),(4.843,.88)]},
+    "C17-C25": {"liquid": [(3.785,.90),(165.5,.92),(.021,.91),(1.068,.91), (10.70,.89),(458.0,.90),(.061,.91),(3.052,.91)]},
+    "C25+": {"liquid": [(2.098,.91),(103.0,.90),(.006,.99),(.284,.99), (6.196,.89),(303.6,.90),(.016,.99),(.833,.99)]},
+    "H2": {"gas": [(13.13,.992),(86.02,1),(9.605,.657),(216.5,.618), (32.05,.933),(228.8,1),(18.43,.652),(636.5,.621)]},
+    "H2S": {"gas": [(6.554,1),(38.11,.89),(22.63,.63),(53.72,.61), (10.65,1),(73.25,.94),(41.43,.63),(191.5,.63)]},
+}
+COEFFICIENTS["Pyrophoric"] = {phase:list(rows) for phase,rows in COEFFICIENTS["C9-C12"].items()}
+COEFFICIENTS["HF"] = {"gas":[None]*8,"liquid":[None]*8}
+
+
+class Coefficients(Model):
+    fluid: str
+    release_phase: Literal["gas", "liquid"]
+    effect: Literal["equipment", "personnel"]
+    release_type: Literal["continuous", "instantaneous"]
+    autoignition: Literal["not_likely", "likely"]
+
+
+@calculation("level1/flammable-coefficients", "SI flammable consequence coefficients", Coefficients,
+             ["Part 3 Tables 4.8M, 4.9M; PDF pp522,524"],
+             limitations=["Type0 and Type1 table lookup only; blank cells are unsupported while printed zero coefficients are valid. Coefficients include original event weighting; do not multiply ignition probability again. Type1 areas must use the separate unblended calculation."])
+def coefficients(x):
+    table = COEFFICIENTS
+    if x.fluid not in table:
+        from .level1_type1 import TYPE1_COEFFICIENTS
+        table = TYPE1_COEFFICIENTS
+    ensure(x.fluid in table and x.release_phase in table[x.fluid], "Unsupported reference fluid/phase")
+    offset = (4 if x.effect == "personnel" else 0) + (2 if x.release_type == "instantaneous" else 0) + (1 if x.autoignition == "likely" else 0)
+    cell = table[x.fluid][x.release_phase][offset]
+    ensure(cell is not None, "Selected coefficient cell is blank in the source table", "unsupported_table_cell")
+    return {"a": cell[0], "b": cell[1], "magnitude_unit": "kg/s" if x.release_type == "continuous" else "kg", "area_unit": "m2"}
+
+
+class Detection(Model):
+    detection: Literal["A", "B", "C"]
+    isolation: Literal["A", "B", "C"]
+
+
+@calculation("release/detection-reduction", "Detection/isolation reduction factor", Detection,
+             ["Part 3 Table 4.6; PDF p519"], limitations=["All nine A/B/C detection-isolation combinations are represented explicitly from Table 4.6; ratings themselves remain qualified inputs."])
+def detection_reduction(x):
+    # Table 4.6 lists B/A with the same 10% reduction as B/C, and C with
+    # any isolation rating as no adjustment.  Keep every printed cell
+    # explicit rather than rejecting valid combinations as "unlisted".
+    factors = {("A","A"):.25, ("A","B"):.20, ("A","C"):.10,
+               ("B","A"):.10, ("B","B"):.15, ("B","C"):.10,
+               ("C","A"):0., ("C","B"):0., ("C","C"):0.}
+    return {"reduction_fraction": factors[x.detection,x.isolation]}
+
+
+class LeakDuration(Detection):
+    hole: Literal["small", "medium", "large"]
+
+
+@calculation("release/detection-duration", "Detection/isolation maximum duration", LeakDuration,
+             ["Part 3 Table 4.7; PDF p520"], limitations=["No rupture-duration entry in this table; returned duration is seconds."])
+def detection_duration(x):
+    if x.detection == "A":
+        values = {"A": (20,10,5), "B": (30,20,10), "C": (40,30,20)}[x.isolation]
+    elif x.detection == "B":
+        values = (60,30,20) if x.isolation == "C" else (40,30,20)
+    else:
+        values = (60,40,20)
+    return {"maximum_duration_s": values[("small","medium","large").index(x.hole)] * 60}
+
+
+class FinalPhase(Model):
+    stored_phase: Literal["gas", "liquid"]
+    ambient_phase: Literal["gas", "liquid"]
+    normal_boiling_point_k: Positive
+
+
+@calculation("level1/release-phase", "Level 1 final consequence phase", FinalPhase,
+             ["Part 3 Table 4.3; PDF p518"], limitations=["Level 1 approximation only; steam/acid overrides must be selected separately. No two-phase flash calculation."])
+def final_phase(x):
+    phase = "gas" if x.stored_phase == "gas" else ("liquid" if x.ambient_phase == "liquid" or x.normal_boiling_point_k > (80-32)*5/9+273.15 else "gas")
+    return {"release_phase": phase}
+
+
+class Energy(Model):
+    released_mass_kg: NonNegative
+
+
+@calculation("level1/energy-efficiency", "Instantaneous energy efficiency correction", Energy,
+             ["Part 3 eq (3.18), Annex 3.B C4A"], limitations=["Applied to instantaneous-release area only; below 4536 kg the correction is 1."])
+def energy(x):
+    return {"energy_efficiency_factor": 4 * math.log10(2.205 * x.released_mass_kg) - 15 if x.released_mass_kg > 4536 else 1}
+
+
+class Blending(Model):
+    release_type: Literal["continuous", "instantaneous"]
+    adjusted_rate_kg_s: NonNegative
+    instantaneous_coefficients_available: bool
+    operating_temperature_k: Positive
+    autoignition_temperature_k: Positive
+
+
+@calculation("level1/blending-factors", "Type 0 release/AIT blending factors", Blending,
+             ["Part 3 eqs (3.19)-(3.26), Annex 3.B C5,C6"], limitations=["Type 0 fluids only. Type 1 correlations already incorporate smoothing."])
+def blending(x):
+    ic = (1 if x.release_type == "instantaneous" else min(x.adjusted_rate_kg_s / 25.2, 1)) if x.instantaneous_coefficients_available else 0
+    ait = min(1, max(0, (x.operating_temperature_k - x.autoignition_temperature_k + 55.6) / (2 * 55.6)))
+    return {"instantaneous_weight": ic, "autoignition_likely_weight": ait}
+
+
+class Area(Model):
+    fluid: str
+    release_phase: Literal["gas", "liquid"]
+    release_type: Literal["continuous", "instantaneous"]
+    adjusted_rate_kg_s: NonNegative
+    released_mass_kg: NonNegative
+    operating_temperature_k: Positive
+    autoignition_temperature_k: Positive
+    mitigation_fraction: Fraction
+
+
+@calculation("level1/flammable-area", "Type 0 per-hole blended flammable consequence", Area,
+             ["Part 3 §4.8.8 eqs (3.29)-(3.58), Tables 4.8M/4.9M"],
+             limitations=["Per-hole flammable consequence only; no toxic/NFNT/financial or hole-frequency weighting. Initial Type 0 set. Caller supplies final phase/AIT/mitigation; LH2 Level 2 behavior is not represented."])
+def flammable_area(x):
+    ensure(x.fluid in COEFFICIENTS and x.release_phase in COEFFICIENTS[x.fluid], "Unsupported fluid/phase")
+    rows = COEFFICIENTS[x.fluid][x.release_phase]
+    factors = blending(Blending(**{k:getattr(x,k) for k in ["release_type","adjusted_rate_kg_s","operating_temperature_k","autoignition_temperature_k"]}, instantaneous_coefficients_available=rows[2] is not None))
+    ic, ait = factors["instantaneous_weight"], factors["autoignition_likely_weight"]
+    correction = energy(Energy(released_mass_kg=x.released_mass_kg))["energy_efficiency_factor"]
+    weights = [(1-ic)*(1-ait),(1-ic)*ait,ic*(1-ait),ic*ait]
+    outputs = {}
+    for effect, offset in [("equipment",0),("personnel",4)]:
+        terms = []
+        for i,w in enumerate(weights):
+            if w == 0:
+                terms.append(0)
+                continue
+            cell = rows[offset+i]
+            ensure(cell is not None, f"Required {effect} coefficient cell is blank", "unsupported_table_cell")
+            magnitude = x.adjusted_rate_kg_s if i < 2 else x.released_mass_kg
+            terms.append(w * cell[0] * magnitude ** cell[1] / (correction if i >= 2 else 1) * (1-x.mitigation_fraction))
+        outputs[effect+"_area_m2"] = math.fsum(terms)
+    return {**outputs, **factors, "energy_efficiency_factor": correction}
+
+
+class ControlledRelease(Model):
+    source: Gas | Liquid
+    operating_temperature_k: Positive
+    component_mass_kg: NonNegative
+    inventory_group_mass_kg: NonNegative
+    detection: Literal["A", "B", "C"]
+    isolation: Literal["A", "B", "C"]
+    duration_hole: Literal["small", "medium", "large", "rupture"]
+    rupture_maximum_duration_s: Positive | None = None
+
+
+@calculation("release/controlled-scenario", "Per-hole source, inventory, detection/isolation and release magnitude", ControlledRelease,
+             ["Part 3 §§4.3-4.7"],
+             limitations=["Single qualified representative hole. Constant ideal-gas/incompressible-liquid source; caller supplies controls and inventory. Rupture duration must be explicit. Adjusted flammable rate is not the toxic source rate."])
+def controlled_release(x):
+    if x.duration_hole != "rupture":
+        sizes = {"small":(.00635,.0064),"medium":(.025,.0254),"large":(.1016,.102)}[x.duration_hole]
+        ensure(any(math.isclose(x.source.diameter_m,d,rel_tol=0,abs_tol=1e-9) for d in sizes),
+               "Duration table category must match a standard representative hole diameter")
+    if isinstance(x.source, Gas):
+        ensure(x.source.temperature_k == x.operating_temperature_k, "Gas source and operating temperatures must match")
+    calculator = gas if isinstance(x.source, Gas) else liquid
+    flow = calculator(x.source)
+    eight_inch = x.source.model_copy(update={"diameter_m": math.sqrt(4*.03245/math.pi)})
+    maximum_supply = calculator(eight_inch)["mass_rate_kg_s"]
+    mass = inventory(AvailableInventory(component_mass_kg=x.component_mass_kg,inventory_group_mass_kg=x.inventory_group_mass_kg,
+                     release_rate_kg_s=flow["mass_rate_kg_s"],eight_inch_rate_kg_s=maximum_supply))
+    kind = release_type(ReleaseType(diameter_m=x.source.diameter_m,theoretical_rate_kg_s=flow["mass_rate_kg_s"],available_mass_kg=mass["available_mass_kg"]))
+    controls = detection_reduction(Detection(detection=x.detection,isolation=x.isolation))
+    if x.duration_hole == "rupture":
+        ensure(x.rupture_maximum_duration_s is not None,"Rupture maximum duration must be explicitly supplied")
+        duration = x.rupture_maximum_duration_s
+    else:
+        ensure(x.rupture_maximum_duration_s is None,"Rupture duration is only valid for rupture")
+        duration = detection_duration(LeakDuration(detection=x.detection,isolation=x.isolation,hole=x.duration_hole))["maximum_duration_s"]
+    released = magnitude(ReleaseMagnitude(theoretical_rate_kg_s=flow["mass_rate_kg_s"],reduction_fraction=controls["reduction_fraction"],
+                          available_mass_kg=mass["available_mass_kg"],maximum_duration_s=duration))
+    return {"theoretical_rate_kg_s":flow["mass_rate_kg_s"],"available_mass_kg":mass["available_mass_kg"],
+            "release_type":kind["release_type"],"reduction_fraction":controls["reduction_fraction"],
+            "maximum_duration_s":duration,**released}
+
+
+class ReleaseToFlammable(ControlledRelease):
+    fluid: str
+    final_release_phase: Literal["gas", "liquid"]
+    autoignition_temperature_k: Positive
+    mitigation_fraction: Fraction
+
+
+@calculation("level1/release-to-flammable", "Compose source, inventory, controls and per-hole flammable area", ReleaseToFlammable,
+             ["Part 3 §§4.3-4.8"],
+             limitations=["Type0 only, single selected hole; caller selects fluid, phase, AIT and mitigation. No toxic/NFNT/cost assessment. Rupture duration must be explicit; Type1 uses release-to-type1-flammable."])
+def release_to_flammable(x):
+    released = controlled_release(x)
+    consequence = flammable_area(Area(fluid=x.fluid,release_phase=x.final_release_phase,release_type=released["release_type"],
+                                  adjusted_rate_kg_s=released["adjusted_rate_kg_s"],released_mass_kg=released["released_mass_kg"],
+                                  operating_temperature_k=x.operating_temperature_k,autoignition_temperature_k=x.autoignition_temperature_k,
+                                  mitigation_fraction=x.mitigation_fraction))
+    return {**released,**consequence}
+
+
+class ReleaseToAcid(ControlledRelease):
+    differential_pressure_pa: NonNegative
+
+
+@calculation(
+    "level1/release-to-acid",
+    "Compose controlled release and ACID splash consequence",
+    ReleaseToAcid,
+    ["Part 3 §§4.1.3,4.3-4.7,4.10.3; PDF pp483-484,490,502"],
+    limitations=[
+        "ACID representative-fluid route only. The caller must qualify the nonflammable/nontoxic acid-or-caustic selection and the differential pressure. The splash correlation is valid only for the documented 103.4-413.7 kPa range; no toxic, flammable or Level 2 dispersion consequence is inferred."
+    ],
+)
+def release_to_acid(x):
+    released = controlled_release(x)
+    consequence = acid(
+        Acid(
+            adjusted_rate_kg_s=released["adjusted_rate_kg_s"],
+            differential_pressure_pa=x.differential_pressure_pa,
+        )
+    )
+    return {**released, **consequence, "representative_fluid": "Acid", "release_phase": "liquid"}
+
+
+class ReleaseToSteam(ControlledRelease):
+    """Controlled steam release routed to the Level 1 steam correlation."""
+    pass
+
+
+@calculation(
+    "level1/release-to-steam",
+    "Compose controlled release and Level 1 steam consequence",
+    ReleaseToSteam,
+    ["Part 3 §§4.3-4.7,4.10.2; PDF pp485-490,501-502"],
+    limitations=[
+        "Steam NFNT correlation only. Steam is treated as gas/vapor; the source must be qualified as steam and the returned area is personnel-only with equipment area zero. No condensation, jet dispersion, two-phase flash or Level 2 consequence is inferred."
+    ],
+)
+def release_to_steam(x):
+    released = controlled_release(x)
+    consequence = steam(
+        Steam(
+            adjusted_rate_kg_s=released["adjusted_rate_kg_s"],
+            released_mass_kg=released["released_mass_kg"],
+        )
+    )
+    return {**released, **consequence, "representative_fluid": "Steam", "release_phase": "gas"}
+
+
+class ReleaseToToxic(ControlledRelease):
+    fluid: Literal["hf", "h2s", "ammonia", "chlorine", "alcl3", "co", "hcl", "nitric_acid", "no2", "phosgene", "tdi", "ee", "eo", "po"]
+    release_phase: Literal["gas", "liquid", "powder"]
+    toxic_mass_fraction: Fraction
+    nonignition_probability: Fraction
+    mitigation: MitigationCredits = Field(default_factory=MitigationCredits)
+    concentration_ppm_on_idlh_basis: NonNegative | None = None
+    hf_instantaneous_intercept: float | None = None
+    intercept_qualification: str | None = Field(default=None, min_length=1, max_length=1000)
+
+
+@calculation(
+    "level1/release-to-toxic",
+    "Compose controlled release and Level 1 toxic consequence",
+    ReleaseToToxic,
+    ["Part 3 §§4.3-4.7,4.9; PDF pp485-500"],
+    limitations=[
+        "Uses the controlled source for one representative hole and passes the theoretical rate (not flammable-adjusted rate) to the toxic component calculation. Single toxic component only; mixture maximum, four-hole aggregation, dispersion and Level 2 source partition remain separate."
+    ],
+)
+def release_to_toxic(x):
+    released = controlled_release(x)
+    toxic = toxic_component(
+        ToxicComponent(
+            fluid=x.fluid,
+            release_phase=x.release_phase,
+            release_type=released["release_type"],
+            theoretical_rate_kg_s=released["theoretical_rate_kg_s"],
+            released_mass_kg=released["released_mass_kg"],
+            toxic_mass_fraction=x.toxic_mass_fraction,
+            available_mass_kg=released["available_mass_kg"],
+            detection_maximum_duration_s=released["maximum_duration_s"],
+            nonignition_probability=x.nonignition_probability,
+            mitigation=x.mitigation,
+            concentration_ppm_on_idlh_basis=x.concentration_ppm_on_idlh_basis,
+            hf_instantaneous_intercept=x.hf_instantaneous_intercept,
+            intercept_qualification=x.intercept_qualification,
+        )
+    )
+    return {**released, **toxic}

api581/level1_summary.py

@@ -0,0 +1,35 @@
+"""Four-hole Level 1 aggregation with mechanism selection after frequency weighting."""
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, calculation, ensure
+from .pof import Component, generic
+from .consequences import HoleValue, Weighted, hole_weighted, FinalArea, final_area
+
+
+class HoleAreas(Model):
+    hole: Literal["small","medium","large","rupture"]
+    flammable_equipment_area_m2: NonNegative
+    flammable_personnel_area_m2: NonNegative
+    toxic_personnel_area_m2: NonNegative
+    nfnt_personnel_area_m2: NonNegative
+
+
+class Summary(Model):
+    component_type: str
+    holes: list[HoleAreas] = Field(min_length=4,max_length=4)
+
+
+@calculation("level1/consequence-summary", "Four-hole mechanism-weighted final consequence areas", Summary,
+             ["Part 3 eqs (3.27)-(3.28),(3.68),(3.78),(3.81)-(3.84)"],
+             limitations=["Caller supplies complete per-hole mechanism consequences, already event-weighted. GFF table supports non-tank components. Mechanism areas are frequency-weighted before final maximum selection."])
+def summary(x):
+    ensure({h.hole for h in x.holes}=={"small","medium","large","rupture"},"Exactly one consequence per hole is required")
+    frequencies=generic(Component(component_type=x.component_type))
+    values={}
+    for name in ["flammable_equipment_area_m2","flammable_personnel_area_m2","toxic_personnel_area_m2","nfnt_personnel_area_m2"]:
+        weighted=hole_weighted(Weighted(value_unit="m2",holes=[HoleValue(hole=h.hole,generic_frequency_per_year=frequencies["by_hole_per_year"][h.hole],value=getattr(h,name)) for h in x.holes]))
+        values[name]=weighted["weighted_value"]
+    result=final_area(FinalArea(flammable_equipment_area_m2=values["flammable_equipment_area_m2"],
+                     flammable_personnel_area_m2=values["flammable_personnel_area_m2"],
+                     toxic_personnel_areas_m2=[values["toxic_personnel_area_m2"]],nfnt_personnel_area_m2=values["nfnt_personnel_area_m2"]))
+    return {**values,**result,"generic_frequency_per_year":frequencies["total_per_year"]}

api581/level1_toxic.py

@@ -0,0 +1,313 @@
+"""Level1 HF/H2S and miscellaneous toxic tables, explicit units and mitigation."""
+from bisect import bisect_left
+import math
+from typing import Annotated, Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+from .consequences import ToxicSource, toxic_source, ToxicDuration, toxic_duration, ToxicArea, toxic_area
+
+Finite = Annotated[float,Field(strict=True,allow_inf_nan=False)]
+LB_PER_KG = 2.205
+M2_PER_FT2 = .0929
+HF_H2S_TIMES = (300,600,1200,2400,3600)
+HF_H2S = {
+    "hf":((1.1401,3.5683),(1.1031,3.8431),(1.0816,4.1040),(1.0942,4.3295),(1.1031,4.4576)),
+    "h2s":((1.2411,3.9686),(1.2410,4.0948),(1.2370,4.238),(1.2297,4.3626),(1.2266,4.4365)),
+}
+
+
+def _bracket(times,value):
+    for i,node in enumerate(times):
+        if math.isclose(value,node,rel_tol=0,abs_tol=1e-9):
+            return ((i,1.0),)
+    ensure(times[0] < value < times[-1],"Toxic exposure duration outside tabulated range; no extrapolation")
+    upper=bisect_left(times,value)
+    w=(value-times[upper-1])/(times[upper]-times[upper-1])
+    return ((upper-1,1-w),(upper,w))
+
+
+class HfH2sCoefficients(Model):
+    fluid: Literal["hf","h2s"]
+    release_type: Literal["continuous","instantaneous"]
+    duration_s: NonNegative = 0
+    hf_instantaneous_intercept: Finite | None = None
+    intercept_qualification: str | None = Field(default=None,min_length=1,max_length=1000)
+
+
+def _check_override(x):
+    ensure((x.hf_instantaneous_intercept is None) == (x.intercept_qualification is None),"HF intercept override and qualification must be supplied together")
+    ensure(x.hf_instantaneous_intercept is None or (x.fluid == "hf" and x.release_type == "instantaneous"),
+           "Intercept override is only for instantaneous HF")
+    if x.intercept_qualification is not None:
+        ensure(bool(x.intercept_qualification.strip()),"Intercept qualification must not be blank")
+
+
+@calculation("level1/hf-h2s-toxic-coefficients", "HF/H2S native toxic log-correlation coefficients", HfH2sCoefficients,
+             ["Part3 Table4.11; eqs(3.63)-(3.64); PDF pp497-498,525"],
+             limitations=["Native log10 correlation uses lb/s or lb and ft2; conversion factors2.205 and.0929 returned. Continuous lookup requires a printed duration node. HF instantaneous d is printed33,606: returned as33606 with ambiguous_print status, never silently changed to3.3606. Qualified caller override is explicit and traceable."])
+def hf_h2s_coefficients(x):
+    _check_override(x)
+    status="clear"
+    if x.release_type == "instantaneous":
+        c,d=(.9674,2.7840) if x.fluid == "h2s" else (1.4056,33606)
+        if x.fluid == "hf":
+            status="ambiguous_print"
+            if x.hf_instantaneous_intercept is not None:
+                d,status=x.hf_instantaneous_intercept,"qualified_override"
+    else:
+        bracket=_bracket(HF_H2S_TIMES,x.duration_s)
+        ensure(len(bracket)==1,"Coefficient lookup requires printed duration; area function interpolates curves", "interpolation_required")
+        c,d=HF_H2S[x.fluid][bracket[0][0]]
+    return {"c":c,"d":d,"native_magnitude_unit":"lb/s" if x.release_type == "continuous" else "lb",
+            "native_area_unit":"ft2","si_mass_multiplier":LB_PER_KG,"si_area_multiplier":M2_PER_FT2,
+            "source_cell_status":status}
+
+
+class HfH2sArea(HfH2sCoefficients):
+    toxic_rate_kg_s: NonNegative
+    toxic_mass_kg: NonNegative
+    nonignition_probability: Fraction
+
+
+@calculation("level1/hf-h2s-toxic-area", "HF/H2S duration-dependent toxic consequence area", HfH2sArea,
+             ["Part3 §4.9.6,§4.9.11; eqs(3.63)-(3.64); Table4.11; PDF pp497-499,525"],
+             origin="api581_equations_with_explicit_qualified_override_support",
+             limitations=["Gas/vapor toxic consequence assumption. Continuous 5-60minute curves interpolate areas, not coefficients. Nonignition weighting applies once. Positive instantaneous HF mass requires qualified intercept override because printed33,606 is unresolved. No extrapolation or automatic spray/IDLH credit."])
+def hf_h2s_area(x):
+    _check_override(x)
+    value=x.toxic_rate_kg_s if x.release_type == "continuous" else x.toxic_mass_kg
+    if value == 0 or (x.release_type == "continuous" and x.duration_s == 0):
+        return {"unweighted_personnel_area_m2":0,"personnel_area_m2":0}
+    if x.release_type == "instantaneous":
+        cell=hf_h2s_coefficients(x)
+        ensure(cell["source_cell_status"] != "ambiguous_print","Instantaneous HF source intercept unresolved; qualified override required", "unsupported_table_cell")
+        pairs=((cell["c"],cell["d"],1.0),)
+    else:
+        pairs=tuple((*HF_H2S[x.fluid][i],w) for i,w in _bracket(HF_H2S_TIMES,x.duration_s))
+    logmag=math.log10(LB_PER_KG*value)
+    area=math.fsum(w*M2_PER_FT2*10**(c*logmag+d) for c,d,w in pairs)
+    return {"unweighted_personnel_area_m2":area,"personnel_area_m2":area*x.nonignition_probability}
+
+
+TIMES=(180,300,600,1200,2400,3600)
+LONG_TIMES=(90,*TIMES)
+# Printed SI Table4.13M, kg/s and m2. None preserves N/A cells.
+MISC = {
+    "alcl3":{"powder":((),((3.4531,.9411),))},
+    "co":{"gas":(TIMES,((9.55,1.15),(60.09,1.06),(189.42,1.13),(651.49,1.11),(1252.67,1.17),(1521.89,1.21)))},
+    "hcl":{"gas":(TIMES,((47.39,1.09),(123.67,1.15),(531.45,1.10),(950.02,1.18),(1851.8,1.20),(2118.87,1.23)))},
+    "nitric_acid":{
+        "gas":(TIMES,((13230.9,1.25),(17146,1.25),(23851.3,1.24),(31185,1.23),(35813.7,1.22),(38105.8,1.22))),
+        "liquid":(TIMES,((1114.96,1.08),(2006.1,1.02),(2674.47,1.06),(4112.65,1.06),(6688.99,1.06),(9458.29,1.12)))},
+    "no2":{
+        "gas":(TIMES,((1071.74,.70),(1466.57,.68),(1902.9,.68),(2338.76,.72),(3621.1,.70),(4070.48,.71))),
+        "liquid":(TIMES,((430,.98),(610.31,1.04),(1340.93,1.07),(3020.54,1.08),(6110.67,1.12),(9455.68,1.13)))},
+    "phosgene":{
+        "gas":(TIMES,((3095.33,1.20),(5918.49,1.29),(12129.3,1.24),(27459.6,1.27),(63526.4,1.30),(96274.2,1.31))),
+        "liquid":(TIMES,((733.39,1.06),(1520.02,1.10),(4777.72,1.12),(14727.5,1.16),(42905,1.20),(77287.7,1.23)))},
+    "tdi":{"liquid":(TIMES,((793.04,1.06),(846.54,1.09),(1011.9,1.10),(1026.06,1.06),(1063.8,1.06),(1252.57,1.03)))},
+    "ee":{
+        "gas":(LONG_TIMES,((.8954,1.171),(1.7578,1.181),(4.0002,1.122),(7.5400,1.111),(24.56,.971),(31.22,.995),(59.67,.899))),
+        "liquid":(LONG_TIMES,(None,None,None,(.6857,1.105),(3.6389,1.065),(9.8422,1.132),(23.513,1.104)))},
+    "eo":{"gas":(LONG_TIMES,((.5085,1.222),(2.9720,1.207),(7.9931,1.271),(47.69,1.2909),(237.57,1.2849),(1088.4,1.1927),(1767.5,1.203)))},
+    "po":{
+        "gas":(TIMES,((.0008,1.913),(.0864,1.217),(.1768,1.2203),(.4172,1.2164),(.9537,1.2097),(1.2289,1.2522))),
+        "liquid":(TIMES,(None,(2.4084,1.198),(9.0397,1.111),(17.425,1.114),(34.255,1.118),(367.06,.9855)))},
+}
+MiscFluid=Literal["alcl3","co","hcl","nitric_acid","no2","phosgene","tdi","ee","eo","po"]
+
+
+class MiscCoefficients(Model):
+    fluid: MiscFluid
+    release_phase: Literal["gas","liquid","powder"]
+    duration_s: NonNegative
+
+
+def _misc_rows(x):
+    ensure(x.release_phase in MISC[x.fluid],"Unsupported toxic fluid/phase", "unsupported_table_cell")
+    return MISC[x.fluid][x.release_phase]
+
+
+@calculation("level1/misc-toxic-coefficients", "Miscellaneous continuous toxic SI coefficients", MiscCoefficients,
+             ["Part3 §4.9.8; Table4.13M; PDF pp498-499,529-530"],
+             limitations=["Ten chemicals, printed SI kg/s and m2 coefficients. Exact printed duration nodes only. AlCl3 powder uses gas-column coefficients for all positive durations per §4.9.8. N/A cells never become zero. Uses SI table directly rather than guessing inconsistent US punctuation/exponents or reconverting US coefficients."])
+def misc_coefficients(x):
+    times,rows=_misc_rows(x)
+    bracket=((0,1),) if not times else _bracket(times,x.duration_s)
+    ensure(len(bracket)==1,"Coefficient lookup requires a printed duration node", "interpolation_required")
+    pair=rows[bracket[0][0]]
+    ensure(pair is not None,"Source toxic coefficient cell is N/A or unresolved", "unsupported_table_cell")
+    return {"e":pair[0],"f":pair[1],"native_rate_unit":"kg/s","native_area_unit":"m2",
+            "si_mass_multiplier":1,"si_area_multiplier":1}
+
+
+class MiscArea(MiscCoefficients):
+    release_type: Literal["continuous"] = "continuous"
+    toxic_rate_kg_s: NonNegative
+    nonignition_probability: Fraction
+
+
+@calculation("level1/misc-toxic-area", "Ten additional chemical continuous toxic consequence areas", MiscArea,
+             ["Part3 §4.9.8,§4.9.11; eq(3.65); Table4.13M; PDF pp498-499,529-530"],
+             limitations=["Continuous only; no invented instantaneous correlation. Printed SI coefficients used directly; no additional unit conversion. N/A cells block interpolation that touches them. AlCl3 powder is duration-independent for positive duration. Caller qualifies phase and nonignition probability; no automatic spray credit."])
+def misc_area(x):
+    times,rows=_misc_rows(x)
+    if x.toxic_rate_kg_s == 0 or x.duration_s == 0:
+        return {"unweighted_personnel_area_m2":0,"personnel_area_m2":0}
+    bracket=((0,1),) if not times else _bracket(times,x.duration_s)
+    area=0.0
+    for i,w in bracket:
+        ensure(rows[i] is not None,"Toxic interpolation touches N/A or unresolved coefficient", "unsupported_table_cell")
+        e,f=rows[i]
+        area+=w*e*x.toxic_rate_kg_s**f
+    return {"unweighted_personnel_area_m2":area,"personnel_area_m2":area*x.nonignition_probability}
+
+
+class ToxicCutoff(Model):
+    fluid: Literal["hf","h2s","ammonia","chlorine"]
+    concentration_ppm_on_idlh_basis: NonNegative
+
+
+@calculation("level1/toxic-cutoff", "Historical Level1 toxic concentration screening", ToxicCutoff,
+             ["Part3 §4.9.9; PDF p499"],
+             limitations=["2016 printed IDLH values: HF30,H2S100,NH3 300,Cl10ppm. Stored-fluid concentration must be on matching IDLH ppm basis, not silently inferred from mass fraction. At or below cutoff evaluation is not required by this source rule. Not a current occupational exposure limit or an atmospheric dispersion safety claim."])
+def toxic_cutoff(x):
+    value={"hf":30,"h2s":100,"ammonia":300,"chlorine":10}[x.fluid]
+    return {"idlh_ppm":value,"requires_toxic_evaluation":x.concentration_ppm_on_idlh_basis > value}
+
+
+class MitigationCredits(Model):
+    rate_reduction_fraction: Fraction = 0
+    duration_reduction_fraction: Fraction = 0
+    mass_reduction_fraction: Fraction = 0
+
+
+class ToxicMitigation(MitigationCredits):
+    toxic_rate_kg_s: NonNegative
+    toxic_mass_kg: NonNegative
+    duration_s: NonNegative
+
+
+@calculation("level1/toxic-mitigation", "Apply explicit toxic source mitigation credits", ToxicMitigation,
+             ["Part3 §4.9.13; PDF pp499-500"],
+             limitations=["Owner-qualified reductions only; no fixed default water-spray efficiency. Rate/duration apply to continuous release, mass to instantaneous. These are not the flammable Table4.6 detection magnitude credit. The caller controls the explicit credit basis and avoids applying the same measure twice."])
+def toxic_mitigation(x):
+    return {"toxic_rate_kg_s":x.toxic_rate_kg_s*(1-x.rate_reduction_fraction),
+            "toxic_mass_kg":x.toxic_mass_kg*(1-x.mass_reduction_fraction),
+            "duration_s":x.duration_s*(1-x.duration_reduction_fraction)}
+
+
+class ToxicComponent(Model):
+    fluid: Literal["hf","h2s","ammonia","chlorine","alcl3","co","hcl","nitric_acid","no2","phosgene","tdi","ee","eo","po"]
+    release_phase: Literal["gas","liquid","powder"]
+    release_type: Literal["continuous","instantaneous"]
+    theoretical_rate_kg_s: NonNegative
+    released_mass_kg: NonNegative
+    toxic_mass_fraction: Fraction
+    available_mass_kg: NonNegative
+    detection_maximum_duration_s: NonNegative
+    nonignition_probability: Fraction
+    mitigation: MitigationCredits = Field(default_factory=MitigationCredits)
+    concentration_ppm_on_idlh_basis: NonNegative | None = None
+    hf_instantaneous_intercept: Finite | None = None
+    intercept_qualification: str | None = Field(default=None,min_length=1,max_length=1000)
+
+
+class ToxicMixtureComponentArea(Model):
+    component_id: str = Field(min_length=1, max_length=100)
+    personnel_area_m2: NonNegative
+
+
+class ToxicMixtureAreas(Model):
+    components: list[ToxicMixtureComponentArea] = Field(min_length=1, max_length=100)
+
+
+@calculation("level1/toxic-component-consequence", "Compose toxic source/duration/mitigation and per-component area", ToxicComponent,
+             ["Part3 §4.9; eqs(3.61)-(3.67); Tables4.11-4.13"],
+             origin="api581_equations_with_explicit_qualified_mitigation",
+             limitations=["Single toxic component; mixture maximum and four-hole aggregation are separate. Uses theoretical total leak rate without flammable magnitude reduction. HF/H2S/NH3/Cl use gas/vapor exposure assumptions; miscellaneous phases follow Table4.13. Optional printed IDLH screening only supports four refinery toxins. All interpolation domains and HF ambiguity still apply; mitigation may shorten duration below a supported table range and then evaluation is rejected."])
+def toxic_component(x):
+    common=x.fluid in ("hf","h2s","ammonia","chlorine")
+    ensure(not common or x.release_phase == "gas","Common refinery toxic correlations assume gas/vapor consequence phase")
+    ensure(x.fluid in ("hf","h2s") or x.hf_instantaneous_intercept is None and x.intercept_qualification is None,
+           "HF intercept parameters apply only to HF instantaneous releases")
+    if x.fluid in ("hf","h2s"):
+        _check_override(x)
+    if not common:
+        ensure(x.release_type == "continuous","Miscellaneous toxic correlations support continuous releases only")
+        _misc_rows(x)
+    screening=x.concentration_ppm_on_idlh_basis is not None
+    if screening:
+        ensure(common,"Built-in IDLH cutoff is not provided for this chemical")
+        required=toxic_cutoff(ToxicCutoff(fluid=x.fluid,concentration_ppm_on_idlh_basis=x.concentration_ppm_on_idlh_basis))["requires_toxic_evaluation"]
+    else:
+        required=True
+    source=toxic_source(ToxicSource(theoretical_rate_kg_s=x.theoretical_rate_kg_s,released_mass_kg=x.released_mass_kg,toxic_mass_fraction=x.toxic_mass_fraction))
+    duration=toxic_duration(ToxicDuration(available_mass_kg=x.available_mass_kg,theoretical_rate_kg_s=x.theoretical_rate_kg_s,
+        detection_maximum_duration_s=x.detection_maximum_duration_s))["duration_s"]
+    mitigated=toxic_mitigation(ToxicMitigation(**source,duration_s=duration,**x.mitigation.model_dump()))
+    if not required:
+        area={"unweighted_personnel_area_m2":0,"personnel_area_m2":0}
+    elif x.fluid in ("hf","h2s"):
+        area=hf_h2s_area(HfH2sArea(fluid=x.fluid,release_type=x.release_type,**mitigated,
+            nonignition_probability=x.nonignition_probability,hf_instantaneous_intercept=x.hf_instantaneous_intercept,
+            intercept_qualification=x.intercept_qualification))
+    elif common:
+        area=toxic_area(ToxicArea(fluid=x.fluid,release_type=x.release_type,**mitigated,nonignition_probability=x.nonignition_probability))
+    else:
+        area=misc_area(MiscArea(fluid=x.fluid,release_phase=x.release_phase,duration_s=mitigated["duration_s"],
+            toxic_rate_kg_s=mitigated["toxic_rate_kg_s"],nonignition_probability=x.nonignition_probability))
+    return {**mitigated,**area,"unmitigated_duration_s":duration,"screening_applied":screening,
+            "requires_toxic_evaluation":required}
+
+
+@calculation(
+    "level1/toxic-mixture-consequence",
+    "Largest individual Level 1 toxic consequence area for a mixture",
+    ToxicMixtureAreas,
+    ["Part 3 §4.9.12, §4.9.15(f), eq (3.68); PDF pp500-501"],
+    limitations=[
+        "Takes already calculated individual toxic component areas and returns the largest; it does not add overlapping clouds, recalculate species release rates, or perform dispersion. For four-hole weighting use the separate hole-weighted/Level 2 composition API."
+    ],
+)
+def toxic_mixture_consequence(x):
+    ensure(len({c.component_id for c in x.components}) == len(x.components), "Duplicate toxic component id")
+    critical = max(x.components, key=lambda c: c.personnel_area_m2)
+    return {
+        "personnel_area_m2": critical.personnel_area_m2,
+        "critical_component_id": critical.component_id,
+        "component_areas_m2": {c.component_id: c.personnel_area_m2 for c in x.components},
+        "component_count": len(x.components),
+    }
+
+
+class ToxicHoleCase(Model):
+    hole: Literal["small", "medium", "large", "rupture"]
+    generic_frequency_per_year: NonNegative
+    components: list[ToxicMixtureComponentArea] = Field(min_length=1, max_length=100)
+
+
+class ToxicHoleSummary(Model):
+    cases: list[ToxicHoleCase] = Field(min_length=4, max_length=4)
+
+
+@calculation(
+    "level1/toxic-hole-summary",
+    "Four-hole GFF-weighted Level 1 toxic consequence",
+    ToxicHoleSummary,
+    ["Part 3 §4.9.14-§4.9.15(f), eq (3.68); PDF pp500-501"],
+    limitations=[
+        "Requires one case for each canonical hole. Within each hole the largest individual toxic-component area is used, then areas are weighted by the supplied generic failure frequencies. Detection/DF-adjusted frequencies, dispersion and financial risk are outside this consequence-area API."
+    ],
+)
+def toxic_hole_summary(x):
+    ensure({c.hole for c in x.cases} == {"small", "medium", "large", "rupture"}, "Require four canonical hole cases")
+    areas = {}
+    for case in x.cases:
+        ensure(len({c.component_id for c in case.components}) == len(case.components), "Duplicate toxic component id in hole case")
+        areas[case.hole] = max(c.personnel_area_m2 for c in case.components)
+    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")
+    weighted = math.fsum(c.generic_frequency_per_year / total * areas[c.hole] for c in x.cases)
+    return {"personnel_area_m2": weighted, "total_generic_frequency_per_year": total,
+            "by_hole_personnel_area_m2": areas}