api581-engine 0.1.4__py3-none-any.whl

api581/prd_consequences.py

@@ -0,0 +1,245 @@
+"""Part 1 §§7.4-7.6 PRD leakage consequences and risk integration."""
+import math
+from typing import Literal
+from pydantic import Field, StrictBool
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+
+Discharge = Literal["atmosphere", "flare", "closed_system"]
+LeakModel = Literal["two_case_equations", "three_case_table_7_15"]
+LeakRiskBasis = Literal["annual_frequency", "source_cumulative_probability"]
+
+
+class MoneyBasis(Model):
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+    cost_basis_year: int = Field(strict=True,ge=1900,le=2200)
+
+
+def _money(x):
+    return {"currency":x.currency,"cost_basis_year":x.cost_basis_year}
+
+
+class LeakageRates(Model):
+    operating_capacity_kg_s: Positive
+
+
+@calculation("prd/leakage-rates", "PRD minor/moderate/combined/stuck-open leakage rates", LeakageRates,
+             ["Part 1 §7.5.2; eqs(1.40)-(1.41); Table7.15; PDF pp66,88"],
+             limitations=["Capacity must be evaluated at normal operating conditions, not silently copied from a relief-condition rating. Eq(1.40) uses 1% for combined mild/moderate; Table7.15 uses 1% minor and 10% moderate. Both are returned explicitly. API520 capacity sizing is not implemented here."])
+def leakage_rates(x):
+    return {"minor_rate_kg_s":.01*x.operating_capacity_kg_s,
+            "moderate_table_rate_kg_s":.1*x.operating_capacity_kg_s,
+            "mild_moderate_equation_rate_kg_s":.01*x.operating_capacity_kg_s,
+            "stuck_open_rate_kg_s":.25*x.operating_capacity_kg_s}
+
+
+class LeakageDuration(Model):
+    inlet_size_nps: Positive
+    discharge: Discharge
+
+
+@calculation("prd/leakage-duration", "PRD size/discharge leakage duration", LeakageDuration,
+             ["Part 1 Table7.14; eq(1.42); PDF pp67,88"],
+             limitations=["NPS is a nominal inlet designation, not a measured diameter in metres. Table duration days are converted exactly to seconds (including printed .33 days). Stuck-open duration uses exact30 minutes=1800s, not rounded .021 days."])
+def leakage_duration(x):
+    row = sum(x.inlet_size_nps > b for b in (.75,1.5,3,6))
+    days = ((8,4,2,1,.33) if x.discharge == "atmosphere" else (60,30,15,7,2))[row]
+    return {"mild_moderate_duration_s":days*86400,"stuck_open_duration_s":1800}
+
+
+class InventoryRecovery(Model):
+    discharge: Discharge
+    flare_recovery_installed: StrictBool = False
+
+
+@calculation("prd/inventory-loss-factor", "PRD residual inventory loss factor after recovery", InventoryRecovery,
+             ["Part 1 §7.5.4; PDF p67"],
+             limitations=["Factor Fr multiplies lost-inventory cost: closed system0, flare with recovery .5, otherwise1. It does not reduce physical leaked mass or environmental/repair/production costs."])
+def inventory_recovery(x):
+    ensure(not x.flare_recovery_installed or x.discharge == "flare", "Flare recovery is only applicable to flare discharge")
+    return {"inventory_loss_factor":0 if x.discharge == "closed_system" else (.5 if x.flare_recovery_installed else 1)}
+
+
+class InventoryLoss(MoneyBasis):
+    leakage_rate_kg_s: NonNegative
+    duration_s: NonNegative
+    fluid_cost_per_kg: NonNegative
+    inventory_loss_factor: Fraction
+
+
+@calculation("prd/inventory-loss", "PRD leakage inventory mass and financial loss", InventoryLoss,
+             ["Part 1 §7.5.5; eqs(1.43)-(1.44); PDF p67"],
+             limitations=["SI mass rate kg/s times seconds replaces source hourly-rate/day factor24. Fluid value must correspond to the protected equipment at the PRD location. Constant supplied operating-capacity leak; no automatic finite inventory/supply limit."])
+def inventory_loss(x):
+    mass = x.leakage_rate_kg_s*x.duration_s
+    residual = mass*x.inventory_loss_factor
+    return {"leaked_mass_kg":mass,"inventory_loss_equivalent_mass_kg":residual,
+            "inventory_loss_cost":residual*x.fluid_cost_per_kg,**_money(x)}
+
+
+class ReferenceRepair(MoneyBasis):
+    inlet_size_nps: Positive
+    price_index_multiplier: Positive
+    output_currency_per_usd: Positive
+
+
+@calculation("prd/repair-cost", "PRD reference repair quote adjusted to declared price basis", ReferenceRepair,
+             ["Part 1 §7.5.7; PDF p67"],
+             limitations=["Printed reference USD1000 below NPS6, USD2000 at/above NPS6. Price quote year is not inferred from edition year; explicit owner-qualified price index and FX required. Actual work-order cost is preferred and can be supplied directly to leakage-consequence."])
+def repair_cost(x):
+    reference = 1000 if x.inlet_size_nps < 6 else 2000
+    return {"reference_cost_usd":reference,"repair_cost":reference*x.price_index_multiplier*x.output_currency_per_usd,**_money(x)}
+
+
+class ProductionLoss(MoneyBasis):
+    daily_production_margin: NonNegative
+    shutdown_duration_days: NonNegative
+    leak_case: Literal["mild_moderate", "stuck_open"]
+    mild_leak_tolerated_or_online_repair: StrictBool
+
+
+@calculation("prd/production-loss", "PRD leakage shutdown production loss", ProductionLoss,
+             ["Part 1 §7.5.8; eqs(1.45)-(1.47); PDF pp67-68"],
+             limitations=["Mild/moderate leak tolerated or isolated/repaired online has zero production loss. Stuck-open case uses shutdown loss per eq(1.47). Caller supplies actual shutdown duration and production margin, including any qualified zero-duration repair."])
+def production_loss(x):
+    required = x.leak_case == "stuck_open" or not x.mild_leak_tolerated_or_online_repair
+    return {"production_loss_cost":x.daily_production_margin*x.shutdown_duration_days if required else 0,
+            "shutdown_loss_applied":required,**_money(x)}
+
+
+class LeakageConsequence(MoneyBasis):
+    operating_capacity_kg_s: Positive
+    inlet_size_nps: Positive
+    discharge: Discharge
+    flare_recovery_installed: StrictBool = False
+    fluid_cost_per_kg: NonNegative
+    environmental_cost: NonNegative
+    repair_cost: NonNegative
+    daily_production_margin: NonNegative
+    shutdown_duration_days: NonNegative
+    mild_leak_tolerated_or_online_repair: StrictBool
+    model_basis: LeakModel
+
+
+@calculation("prd/leakage-consequence", "PRD two/three-case leakage financial consequence", LeakageConsequence,
+             ["Part 1 §7.5.10; eqs(1.39)-(1.50); Tables7.14,7.15; PDF pp66-69,88"],
+             origin="api581_equations_with_explicit_source_discrepancy_choice",
+             limitations=["Caller explicitly selects two_case_equations (.9 at1% capacity + .1 stuck at25%) or three_case_table_7_15 (.5 at1%, .4 at10%, .1 at25%) because source rates conflict. Non-stuck cases share Table7.14 duration. Environmental and repair costs are common conditional case costs as printed. All monetary inputs share declared currency/year; no automatic price-year inference or supply/inventory cap."])
+def leakage_consequence(x):
+    rates = leakage_rates(LeakageRates(operating_capacity_kg_s=x.operating_capacity_kg_s))
+    duration = leakage_duration(LeakageDuration(inlet_size_nps=x.inlet_size_nps,discharge=x.discharge))
+    recovery = inventory_recovery(InventoryRecovery(discharge=x.discharge,flare_recovery_installed=x.flare_recovery_installed))["inventory_loss_factor"]
+    cases = ({"mild_moderate":(.9,rates["mild_moderate_equation_rate_kg_s"]),"stuck_open":(.1,rates["stuck_open_rate_kg_s"])}
+             if x.model_basis == "two_case_equations" else
+             {"minor":(.5,rates["minor_rate_kg_s"]),"moderate":(.4,rates["moderate_table_rate_kg_s"]),"stuck_open":(.1,rates["stuck_open_rate_kg_s"])})
+    costs,weights = {},{}
+    for name,(weight,rate) in cases.items():
+        stuck = name == "stuck_open"
+        seconds = duration["stuck_open_duration_s" if stuck else "mild_moderate_duration_s"]
+        inv = inventory_loss(InventoryLoss(leakage_rate_kg_s=rate,duration_s=seconds,fluid_cost_per_kg=x.fluid_cost_per_kg,
+            inventory_loss_factor=recovery,**_money(x)))
+        prod = production_loss(ProductionLoss(daily_production_margin=x.daily_production_margin,
+            shutdown_duration_days=x.shutdown_duration_days,leak_case="stuck_open" if stuck else "mild_moderate",
+            mild_leak_tolerated_or_online_repair=x.mild_leak_tolerated_or_online_repair,**_money(x)))
+        total = inv["inventory_loss_cost"]+prod["production_loss_cost"]+x.environmental_cost+x.repair_cost
+        costs[name] = {"leakage_rate_kg_s":rate,"duration_s":seconds,"leaked_mass_kg":inv["leaked_mass_kg"],
+                       "inventory_loss_cost":inv["inventory_loss_cost"],"production_loss_cost":prod["production_loss_cost"],
+                       "environmental_cost":x.environmental_cost,"repair_cost":x.repair_cost,"financial_consequence":total}
+        weights[name] = weight
+    return {"financial_consequence":math.fsum(weights[k]*v["financial_consequence"] for k,v in costs.items()),
+            "case_weights":weights,"costs_by_case":costs,"inventory_loss_factor":recovery,"model_basis":x.model_basis,**_money(x)}
+
+
+class MultipleDevicePressure(Model):
+    analyzed_orifice_area_m2: Positive
+    total_installed_orifice_area_m2: Positive
+    scenario_pressure_pa_gauge: NonNegative
+
+
+@calculation("prd/multiple-device-pressure", "Multiple PRD area-based protected-equipment pressure adjustment", MultipleDevicePressure,
+             ["Part 1 §7.4.4; eqs(1.37)-(1.38); PDF pp64-65"],
+             limitations=["Total installed area includes analyzed PRD. Fa=max(.25,sqrt(Aprd/Atotal)). Reduced pressure is used for protected-equipment LOC and consequence calculations only; original scenario pressure must be retained for Fop (PRD POFOD). Source square-root approximation is not an independent parallel-failure probability or a capacity-design verification."])
+def multiple_device_pressure(x):
+    ensure(x.analyzed_orifice_area_m2 <= x.total_installed_orifice_area_m2, "Total installed orifice area must include analyzed device")
+    factor = max(.25,math.sqrt(x.analyzed_orifice_area_m2/x.total_installed_orifice_area_m2))
+    return {"multiple_device_factor":factor,"protected_equipment_pressure_pa_gauge":factor*x.scenario_pressure_pa_gauge,
+            "unreduced_pressure_for_fop_pa_gauge":x.scenario_pressure_pa_gauge}
+
+
+class FailRiskCase(Model):
+    case_id: str = Field(min_length=1,max_length=100)
+    annual_failure_frequency: NonNegative
+    financial_consequence: NonNegative
+
+
+class ProtectedRisk(Model):
+    equipment_id: str = Field(min_length=1,max_length=200)
+    cases: list[FailRiskCase] = Field(min_length=1,max_length=100)
+
+
+class FailRisk(MoneyBasis):
+    protected_equipment: list[ProtectedRisk] = Field(min_length=1,max_length=100)
+
+
+@calculation("prd/fail-risk", "PRD fail-to-open case sum and protected-equipment maximum risk", FailRisk,
+             ["Part 1 §7.6.1; eqs(1.51)-(1.52); PDF p69"],
+             limitations=["Within each protected item, sum distinct demand-case frequency*conditional consequence. Then take maximum across protected items as prescribed, not their sum. Caller supplies qualified case frequencies and pressure-dependent COF; currency/year must be common."])
+def fail_risk(x):
+    ensure(len({e.equipment_id for e in x.protected_equipment}) == len(x.protected_equipment), "Duplicate protected equipment ID")
+    values = {}
+    for equipment in x.protected_equipment:
+        ensure(len({c.case_id for c in equipment.cases}) == len(equipment.cases), "Duplicate demand case ID within protected equipment")
+        values[equipment.equipment_id] = math.fsum(c.annual_failure_frequency*c.financial_consequence for c in equipment.cases)
+    maximum = max(values.values())
+    return {"protected_equipment_risks_per_year":values,"maximum_fail_risk_per_year":maximum,
+            "governing_equipment_ids":[k for k,v in values.items() if v == maximum],**_money(x)}
+
+
+class LeakageRisk(MoneyBasis):
+    leakage_measure: NonNegative
+    financial_consequence: NonNegative
+    measure_basis: LeakRiskBasis
+
+
+@calculation("prd/leakage-risk", "PRD leakage consequence weighted by declared probability/frequency basis", LeakageRisk,
+             ["Part 1 §7.6.2; eq(1.53); PDF p69"],
+             limitations=["Source multiplies leakage Weibull cumulative probability by consequence but uses annual-risk terminology. Basis must be explicit: source_cumulative_probability gives monetary probability-weighted consequence; annual_frequency requires an independently qualified annual event frequency. No silent CDF annualization."])
+def leakage_risk(x):
+    ensure(x.measure_basis != "source_cumulative_probability" or x.leakage_measure <= 1, "Cumulative leakage probability must not exceed1")
+    return {"leakage_risk_value":x.leakage_measure*x.financial_consequence,
+            "measure_basis":x.measure_basis,"risk_unit":"currency/year" if x.measure_basis == "annual_frequency" else "currency",**_money(x)}
+
+
+class TotalRisk(MoneyBasis):
+    fail_risk_per_year: NonNegative
+    leakage_risk_value: NonNegative
+    leakage_measure_basis: LeakRiskBasis
+
+
+@calculation("prd/total-risk", "PRD combined risk with explicit dimensional basis", TotalRisk,
+             ["Part 1 §7.6.3; eq(1.54); PDF p69"],
+             origin="api581_aggregation_with_explicit_measure_basis",
+             limitations=["Annual leakage-frequency basis permits an annual total. Source cumulative-probability basis reproduces printed addition only as source_total_risk_index and leaves annual_financial_risk unset, because summands have inconsistent dimensions. Source index must not be presented as a certified monetary annual rate."])
+def total_risk(x):
+    combined = x.fail_risk_per_year+x.leakage_risk_value
+    annual = x.leakage_measure_basis == "annual_frequency"
+    return {"annual_financial_risk":combined if annual else None,"source_total_risk_index":None if annual else combined,
+            "leakage_measure_basis":x.leakage_measure_basis,**_money(x)}
+
+
+class RiskAssessment(FailRisk):
+    leakage_measure: NonNegative
+    leakage_financial_consequence: NonNegative
+    leakage_measure_basis: LeakRiskBasis
+
+
+@calculation("prd/risk-assessment", "Compose protected-item fail risk and PRD leakage risk", RiskAssessment,
+             ["Part 1 §7.6.4; eqs(1.51)-(1.54); PDF pp69-70"],
+             origin="api581_aggregation_with_explicit_measure_basis",
+             limitations=["Integration over supplied case frequencies, protected-item conditional consequences and leakage measure/consequence. It does not automatically derive complete relief design or COF. Fail risk takes max across protected items. Cumulative leakage basis yields source index only; annual total requires qualified leakage annual frequency."])
+def risk_assessment(x):
+    failed = fail_risk(FailRisk(protected_equipment=x.protected_equipment,**_money(x)))
+    leak = leakage_risk(LeakageRisk(leakage_measure=x.leakage_measure,financial_consequence=x.leakage_financial_consequence,
+        measure_basis=x.leakage_measure_basis,**_money(x)))
+    total = total_risk(TotalRisk(fail_risk_per_year=failed["maximum_fail_risk_per_year"],leakage_risk_value=leak["leakage_risk_value"],
+        leakage_measure_basis=x.leakage_measure_basis,**_money(x)))
+    return {**failed,**total,"leakage_risk_value":leak["leakage_risk_value"],"leakage_risk_unit":leak["risk_unit"]}

api581/prd_history.py

@@ -0,0 +1,44 @@
+"""Explicit PRD service-age and inspection-history boundary calculations."""
+from datetime import date
+from typing import Literal
+from pydantic import Field
+from .core import Model, Positive, calculation, ensure
+
+
+class ServiceEvent(Model):
+    event_date: date
+    event_type: Literal["test", "overhaul", "replacement", "design_change"]
+
+
+class ServiceAge(Model):
+    installation_date: date
+    evaluation_date: date
+    events: list[ServiceEvent] = Field(default_factory=list,max_length=10000)
+    days_per_year: Positive = 365.25
+
+
+@calculation("prd/service-age", "PRD as-new service age and valid-history start boundary", ServiceAge,
+             ["Part 1 §7.1.6, §7.2.4(i)(5), §7.7.2-7.7.3; PDF pp48,57,70"],
+             origin="api581_lifecycle_rules_with_explicit_calendar_convention",
+             limitations=["Overhaul/replacement reset effective age; test alone does not. Replacement/design change invalidate earlier parameter-updating history. Inspection update window starts at later of last as-new reset and parameter-history validity boundary per §7.2.6 STEP6.4. Design change alone does not assert an as-new condition. Dates/age only, not automatic test/eta updating or new-curve qualification. Default365.25-day year is an explicit engineering calendar convention, not a claimed source mandate. Same-day ordered events are allowed."])
+def service_age(x):
+    ensure(x.evaluation_date >= x.installation_date,"Evaluation precedes original installation")
+    reset,history = x.installation_date,x.installation_date
+    last_test = None
+    kind = "installation"
+    previous = x.installation_date
+    for event in x.events:
+        ensure(previous <= event.event_date <= x.evaluation_date,"Service events must be chronological and within installation/evaluation dates")
+        previous = event.event_date
+        if event.event_type == "test":
+            last_test = event.event_date
+        elif event.event_type in ("overhaul","replacement"):
+            reset,kind = event.event_date,event.event_type
+        if event.event_type in ("replacement","design_change"):
+            history = event.event_date
+    return {"effective_age_years":(x.evaluation_date-reset).days/x.days_per_year,
+            "elapsed_since_original_installation_years":(x.evaluation_date-x.installation_date).days/x.days_per_year,
+            "last_age_reset_date":reset.isoformat(),"last_age_reset_type":kind,
+            "parameter_history_valid_from_date":history.isoformat(),
+            "inspection_update_start_date":max(reset,history).isoformat(),
+            "last_test_date":None if last_test is None else last_test.isoformat(),"days_per_year":x.days_per_year}

api581/release.py

@@ -0,0 +1,307 @@
+"""Single-phase source calculations. Internal units: SI, absolute pressures."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+
+R = 8.31446261815324  # J/(mol K); molecular weight API uses kg/kmol, hence R*1000
+
+
+class HoleSizeSelection(Model):
+    """Actual opening to API 581 Table 4.4/4.4M release-hole class."""
+    hole_diameter_m: NonNegative
+    component_diameter_m: Positive
+    diameter_basis: Literal["printed_si", "printed_us_converted"]
+
+
+@calculation("release/hole-size-selection", "Release hole class and representative diameter",
+             HoleSizeSelection,
+             ["Part 3 §4.2, Table 4.4/Table 4.4M; PDF p518"],
+             limitations=[
+                 "The measured opening is supplied in metres; diameter_basis selects the printed SI millimetre or US inch boundaries. Exact upper boundaries belong to the lower class. Rupture representative diameter is min(component diameter, 406 mm/16 in); this class selection does not calculate an orifice rate or infer component geometry."])
+def hole_size_selection(x):
+    if x.diameter_basis == "printed_si":
+        small, medium, large = .0064, .025, .102
+        upper_small, upper_medium, upper_large = .0064, .051, .152
+        basis_name = "Table 4.4M"
+    else:
+        small, medium, large = .00635, .0254, .1016
+        upper_small, upper_medium, upper_large = .00635, .0508, .1524
+        basis_name = "Table 4.4"
+    d = x.hole_diameter_m
+    if d <= upper_small:
+        hole, representative = "small", small
+        lower, upper = 0., upper_small
+    elif d <= upper_medium:
+        hole, representative = "medium", medium
+        lower, upper = upper_small, upper_medium
+    elif d <= upper_large:
+        hole, representative = "large", large
+        lower, upper = upper_medium, upper_large
+    else:
+        hole, representative = "rupture", min(x.component_diameter_m, .4064)
+        lower, upper = upper_large, None
+    return {"selected_hole": hole, "representative_diameter_m": representative,
+            "lower_bound_m": lower, "upper_bound_m": upper,
+            "diameter_basis": x.diameter_basis, "source_table": basis_name}
+
+
+class DetectionIsolationRating(Model):
+    """Qualitative Table 4.5 detection and isolation classification."""
+    detection_type: Literal[
+        "process_instrumentation",
+        "outside_envelope_detector",
+        "visual_or_marginal"]
+    isolation_type: Literal[
+        "automatic_instrument_or_detector",
+        "remote_operator",
+        "manual_valve"]
+    qualification_basis: str = Field(min_length=1, max_length=1000)
+
+
+@calculation("release/detection-isolation-rating", "Table 4.5 detection and isolation system classification",
+             DetectionIsolationRating,
+             ["Part 3 Table 4.5; PDF p519"],
+             limitations=[
+                 "Maps only the printed qualitative descriptions to A/B/C. It does not inspect plant instrumentation, coverage, response time or proof-test data; those remain owner-qualified evidence in qualification_basis."])
+def detection_isolation_rating(x):
+    ensure(x.qualification_basis.strip(), "Detection/isolation qualification basis must be nonblank")
+    detection = {
+        "process_instrumentation": "A",
+        "outside_envelope_detector": "B",
+        "visual_or_marginal": "C",
+    }[x.detection_type]
+    isolation = {
+        "automatic_instrument_or_detector": "A",
+        "remote_operator": "B",
+        "manual_valve": "C",
+    }[x.isolation_type]
+    return {"detection_rating": detection, "isolation_rating": isolation,
+            "detection_type": x.detection_type, "isolation_type": x.isolation_type,
+            "qualification_basis": x.qualification_basis}
+
+
+class Orifice(Model):
+    diameter_m: NonNegative
+
+
+@calculation("release/orifice-area", "Circular release area", Orifice, ["Part 3 eq (3.8)"])
+def orifice(x):
+    return {"area_m2": math.pi * x.diameter_m ** 2 / 4}
+
+
+class Viscosity(Model):
+    reynolds_number: Positive
+
+
+@calculation("release/viscosity-factor", "Liquid viscosity correction", Viscosity,
+             ["Part 3 eq (3.4); PDF p485"])
+def viscosity(x):
+    re = x.reynolds_number
+    return {"viscosity_factor": 1 / (.9935 + 2.878 / math.sqrt(re) + 342.75 / re ** 1.5)}
+
+
+class Liquid(Model):
+    diameter_m: NonNegative
+    upstream_pressure_pa_abs: Positive
+    downstream_pressure_pa_abs: Positive = 101325
+    density_kg_m3: Positive
+    discharge_coefficient: Fraction = .61
+    viscosity_factor: Positive = 1
+
+
+@calculation("release/liquid", "Liquid orifice mass release rate", Liquid,
+             ["Part 3 §4.3.2 eq (3.3); PDF p485"],
+             limitations=["Steady upstream state; no line friction, flash fraction or pool evaporation calculation."])
+def liquid(x):
+    ensure(x.upstream_pressure_pa_abs >= x.downstream_pressure_pa_abs, "Upstream pressure must be >= downstream pressure")
+    area = orifice(Orifice(diameter_m=x.diameter_m))["area_m2"]
+    rate = x.discharge_coefficient * x.viscosity_factor * area * math.sqrt(
+        2 * x.density_kg_m3 * (x.upstream_pressure_pa_abs - x.downstream_pressure_pa_abs))
+    return {"mass_rate_kg_s": rate, "area_m2": area, "regime": "liquid"}
+
+
+class Gas(Model):
+    diameter_m: NonNegative
+    upstream_pressure_pa_abs: Positive
+    downstream_pressure_pa_abs: Positive = 101325
+    temperature_k: Positive
+    molecular_weight_kg_kmol: Positive
+    heat_capacity_ratio: Positive = Field(gt=1)
+    discharge_coefficient: Fraction = .9
+
+
+@calculation("release/gas", "Sonic or subsonic ideal-gas release", Gas,
+             ["Part 3 §4.3.3 eqs (3.5)-(3.7); PDF p486"],
+             limitations=["Ideal gas, constant upstream state; not a two-phase or real-gas near-critical model."])
+def gas(x):
+    p, back, k = x.upstream_pressure_pa_abs, x.downstream_pressure_pa_abs, x.heat_capacity_ratio
+    ensure(p >= back, "Upstream pressure must be >= downstream pressure")
+    ratio = back / p
+    critical = (2 / (k + 1)) ** (k / (k - 1))
+    area = orifice(Orifice(diameter_m=x.diameter_m))["area_m2"]
+    specific_r = R * 1000 / x.molecular_weight_kg_kmol
+    if ratio <= critical:
+        factor = k * (2 / (k + 1)) ** ((k + 1) / (k - 1))
+        regime = "sonic"
+    else:
+        # expm1 avoids cancellation as upstream approaches downstream pressure.
+        factor = 2 * k / (k - 1) * ratio ** (2 / k) * (-math.expm1((k - 1) / k * math.log(ratio)))
+        regime = "subsonic"
+    rate = x.discharge_coefficient * area * p * math.sqrt(max(0, factor) / (specific_r * x.temperature_k))
+    return {"mass_rate_kg_s": rate, "area_m2": area, "regime": regime,
+            "critical_downstream_upstream_ratio": critical, "transition_pressure_pa_abs": back / critical}
+
+
+class HeatCapacity(Model):
+    cp_j_mol_k: Positive
+
+
+@calculation("properties/heat-capacity-ratio", "Ideal-gas specific heat ratio", HeatCapacity,
+             ["Part 3 eq (3.1)"])
+def heat_capacity(x):
+    ensure(x.cp_j_mol_k > R, "Molar Cp must exceed R")
+    return {"heat_capacity_ratio": x.cp_j_mol_k / (x.cp_j_mol_k - R)}
+
+
+class AvailableInventory(Model):
+    component_mass_kg: NonNegative
+    inventory_group_mass_kg: NonNegative
+    release_rate_kg_s: NonNegative
+    eight_inch_rate_kg_s: NonNegative
+
+
+@calculation("release/available-inventory", "Maximum available mass", AvailableInventory,
+             ["Part 3 §4.4.2 eqs (3.10)-(3.11); PDF p487"])
+def inventory(x):
+    ensure(x.inventory_group_mass_kg >= x.component_mass_kg, "Inventory group must include component mass")
+    added = 180 * min(x.release_rate_kg_s, x.eight_inch_rate_kg_s)
+    return {"added_mass_kg": added, "available_mass_kg": min(x.component_mass_kg + added, x.inventory_group_mass_kg)}
+
+
+class ReleaseType(Model):
+    diameter_m: NonNegative
+    theoretical_rate_kg_s: NonNegative
+    available_mass_kg: NonNegative
+
+
+@calculation("release/type", "Continuous or instantaneous release classification", ReleaseType,
+             ["Part 3 §4.5.2 eq (3.12); PDF p488"], limitations=["Uses the text's rounded 4536 kg threshold."])
+def release_type(x):
+    time = 4536 / x.theoretical_rate_kg_s if x.theoretical_rate_kg_s else None
+    instant = x.diameter_m > .00635 and time is not None and time <= 180 and x.available_mass_kg > 4536
+    return {"release_type": "instantaneous" if instant else "continuous", "time_to_4536kg_s": time}
+
+
+class ReleaseMagnitude(Model):
+    theoretical_rate_kg_s: NonNegative
+    reduction_fraction: Fraction
+    available_mass_kg: NonNegative
+    maximum_duration_s: NonNegative
+
+
+@calculation("release/magnitude", "Adjusted release rate, duration and mass", ReleaseMagnitude,
+             ["Part 3 §4.7 eqs (3.13)-(3.15); PDF p490"],
+             limitations=["Detection reduction and maximum duration supplied by caller, not yet selected from Tables 4.6/4.7."])
+def magnitude(x):
+    rate = x.theoretical_rate_kg_s * (1 - x.reduction_fraction)
+    duration = min(x.maximum_duration_s, x.available_mass_kg / rate) if rate else 0
+    return {"adjusted_rate_kg_s": rate, "duration_s": duration,
+            "released_mass_kg": min(x.available_mass_kg, rate * duration)}
+
+
+class DetectionIsolation(Model):
+    """API 581 Table 4.6/4.7M detection and isolation selection."""
+    detection_rating: Literal["A", "B", "C"]
+    isolation_rating: Literal["A", "B", "C"]
+    hole_size: Literal["small", "medium", "large", "rupture"]
+    theoretical_rate_kg_s: NonNegative
+    available_mass_kg: NonNegative
+
+
+@calculation("release/detection-isolation", "Detection/isolation release reduction and maximum leak duration",
+             DetectionIsolation,
+             ["Part 3 §4.6.2-§4.6.6, Tables 4.6/4.7M; PDF pp488-490,520"],
+             limitations=[
+                 "Uses the printed SI Table 4.7M hole classes (6.4, 25 and 102 mm). A rupture hole has no maximum duration in Table 4.7M, so its instantaneous released mass is the available mass and duration is null. Ratings are supplied after the qualitative Table 4.5 screening; no detector/isolation hardware classification is inferred."])
+def detection_isolation(x):
+    d, i = x.detection_rating, x.isolation_rating
+    # Table 4.6: release magnitude reduction factor fact_di.
+    reduction = {
+        ("A", "A"): .25, ("A", "B"): .20, ("A", "C"): .10,
+        ("B", "A"): .10, ("B", "B"): .15, ("B", "C"): .10,
+        ("C", "A"): .00, ("C", "B"): .00, ("C", "C"): .00,
+    }[(d, i)]
+    # Table 4.7M, seconds; the rupture row intentionally has no duration.
+    duration_by_rating = {
+        ("A", "A"): {"small": 20*60, "medium": 10*60, "large": 5*60},
+        ("A", "B"): {"small": 30*60, "medium": 20*60, "large": 10*60},
+        ("A", "C"): {"small": 40*60, "medium": 30*60, "large": 20*60},
+        ("B", "A"): {"small": 40*60, "medium": 30*60, "large": 20*60},
+        ("B", "B"): {"small": 40*60, "medium": 30*60, "large": 20*60},
+        ("B", "C"): {"small": 60*60, "medium": 30*60, "large": 20*60},
+        ("C", "A"): {"small": 40*60, "medium": 20*60},
+        ("C", "B"): {"small": 40*60, "medium": 20*60},
+        ("C", "C"): {"small": 40*60, "medium": 20*60},
+    }
+    maximum_duration = duration_by_rating[(d, i)].get(x.hole_size)
+    adjusted_rate = x.theoretical_rate_kg_s * (1 - reduction)
+    if x.hole_size == "rupture":
+        duration = None
+        released = x.available_mass_kg
+    elif adjusted_rate == 0:
+        duration = 0.
+        released = 0.
+    else:
+        duration = min(maximum_duration, x.available_mass_kg / adjusted_rate)
+        released = min(x.available_mass_kg, adjusted_rate * duration)
+    return {"release_reduction_fraction": reduction,
+            "adjusted_rate_kg_s": adjusted_rate,
+            "maximum_leak_duration_s": maximum_duration,
+            "duration_s": duration,
+            "released_mass_kg": released,
+            "detection_rating": d, "isolation_rating": i, "hole_size": x.hole_size}
+
+
+class TimePoint(Model):
+    time_s: NonNegative
+    rate_kg_s: NonNegative
+
+
+class Transient(Model):
+    points: list[TimePoint] = Field(min_length=2, max_length=10000)
+    available_mass_kg: NonNegative
+
+
+@calculation("release/integrate-profile", "Integrate a piecewise-linear release profile", Transient,
+             ["Part 3 §4.7.3 Calculation of Release Rate and Mass", "Part 3 §5.7.3 Calculation of Jet Release Rate and Pool Release Rate"],
+             origin="engineering_utility", limitations=["Profile supplied externally; not a vessel blowdown solver. Inventory exceedance is rejected, not clipped."])
+def integrate_profile(x):
+    ensure(x.points[0].time_s == 0, "Profile must start at time 0")
+    intervals = []
+    for left, right in zip(x.points, x.points[1:]):
+        ensure(right.time_s > left.time_s, "Profile times must strictly increase")
+        intervals.append((right.time_s - left.time_s) * (left.rate_kg_s + right.rate_kg_s) / 2)
+    mass = math.fsum(intervals)
+    ensure(mass <= x.available_mass_kg + max(1e-9, 1e-9 * x.available_mass_kg), "Profile exceeds available inventory")
+    return {"released_mass_kg": mass, "duration_s": x.points[-1].time_s}
+
+
+class MixtureComponent(Model):
+    mole_fraction: Fraction
+    molecular_weight_kg_kmol: Positive
+
+
+class Mixture(Model):
+    components: list[MixtureComponent] = Field(min_length=1, max_length=100)
+
+
+@calculation("properties/mixture-molecular-weight", "Mole-weighted mixture and mass fractions", Mixture,
+             ["Part 3 §4.1.2, §4.9.4; mixture molecular-weight and mass-fraction inputs"],
+             origin="api581_input_preparation",
+             limitations=["Mole fractions and component molecular weights are supplied by the caller; this does not select a representative fluid or perform Level 2 thermodynamic flash."])
+def mixture(x):
+    ensure(math.isclose(math.fsum(c.mole_fraction for c in x.components), 1, abs_tol=1e-9), "Mole fractions must sum to 1")
+    mw = math.fsum(c.mole_fraction * c.molecular_weight_kg_kmol for c in x.components)
+    return {"molecular_weight_kg_kmol": mw,
+            "mass_fractions": [c.mole_fraction * c.molecular_weight_kg_kmol / mw for c in x.components]}