api581-engine 0.1.4__py3-none-any.whl

api581/api520.py

@@ -0,0 +1,205 @@
+"""API RP 520 (7th ed., Jan 2000) pressure-relief sizing primitives.
+
+The public functions intentionally expose the individual sizing steps so they can
+be used by API 581 PRD calculations or by a digital-twin caller.  Inputs use SI
+units unless a field name explicitly says ``psig``/``psia``.  This is a sizing
+calculation aid; valve selection, certified capacity, two-phase DIERS methods,
+and installation hydraulics remain separate engineering checks.
+"""
+from math import sqrt
+from .core import Model, Positive, NonNegative, Fraction, calculation, ensure
+
+
+ATM_KPA = 101.325
+
+
+class CriticalRatio(Model):
+    heat_capacity_ratio: Positive
+
+
+@calculation("api520/critical-pressure-ratio", "API 520 critical-flow pressure ratio", CriticalRatio,
+             ["API RP 520 7th ed. §3.6.1.4, Eq. 3.1"],
+             origin="engineering_utility",
+             limitations=["Ideal-gas relation; use qualified property data for real-gas/high-pressure service."])
+def critical_pressure_ratio(x):
+    k = x.heat_capacity_ratio
+    ensure(k > 1.0, "Heat-capacity ratio must exceed one")
+    return {"critical_pressure_ratio": (2.0 / (k + 1.0)) ** (k / (k - 1.0))}
+
+
+class FlowCoefficient(Model):
+    heat_capacity_ratio: Positive
+
+
+@calculation("api520/flow-coefficient-c", "API 520 gas/vapor flow coefficient C", FlowCoefficient,
+             ["API RP 520 7th ed. §3.6.2, Eq. 3.2-3.4; Fig. 32"],
+             origin="engineering_utility",
+             limitations=["Ideal-gas coefficient; API 520 recommends qualified data or C=315 when k is unavailable."])
+def flow_coefficient_c(x):
+    k = x.heat_capacity_ratio
+    ensure(k > 1.0, "Heat-capacity ratio must exceed one")
+    return {"flow_coefficient_c": 520.0 * sqrt(k * (2.0 / (k + 1.0)) ** ((k + 1.0) / (k - 1.0)))}
+
+
+class RelievingPressure(Model):
+    set_pressure_psig: Positive
+    allowable_overpressure_fraction: Fraction
+    atmospheric_pressure_kpa: Positive = ATM_KPA
+
+
+@calculation("api520/relieving-pressure", "API 520 relieving pressure", RelievingPressure,
+             ["API RP 520 7th ed. §3.5, Tables 1-6"], origin="engineering_utility",
+             limitations=["Overpressure fraction is supplied by the contingency/code basis; no automatic ASME scenario selection."])
+def relieving_pressure(x):
+    gauge = x.set_pressure_psig * (1.0 + x.allowable_overpressure_fraction)
+    return {"relieving_pressure_psig": gauge,
+            "relieving_pressure_kpaa": gauge * 6.894757293168 + x.atmospheric_pressure_kpa}
+
+
+class GasCriticalArea(Model):
+    required_mass_flow_kg_h: Positive
+    relieving_temperature_k: Positive
+    compressibility_factor: Positive = 1.0
+    molecular_weight_kg_kmol: Positive
+    relief_pressure_kpaa: Positive
+    heat_capacity_ratio: Positive
+    discharge_coefficient: Fraction = 0.975
+    back_pressure_factor: Positive = 1.0
+    combination_factor: Positive = 1.0
+
+
+@calculation("api520/gas-critical-area", "API 520 critical gas/vapor effective area", GasCriticalArea,
+             ["API RP 520 7th ed. §3.6.2, Eqs. 3.2-3.4"], origin="engineering_utility",
+             limitations=["SI mass-flow form; assumes critical ideal-gas/nozzle behavior and supplied correction factors."])
+def gas_critical_area(x):
+    ensure(x.compressibility_factor > 0 and x.molecular_weight_kg_kmol > 0, "Invalid gas property")
+    k = x.heat_capacity_ratio
+    ensure(k > 1.0, "Heat-capacity ratio must exceed one")
+    c = 520.0 * sqrt(k * (2.0 / (k + 1.0)) ** ((k + 1.0) / (k - 1.0)))
+    return {"required_area_mm2": 13160.0 * x.required_mass_flow_kg_h * sqrt(x.relieving_temperature_k * x.compressibility_factor / x.molecular_weight_kg_kmol) / (c * x.discharge_coefficient * x.relief_pressure_kpaa * x.back_pressure_factor * x.combination_factor)}
+
+
+class GasSubcriticalArea(GasCriticalArea):
+    downstream_pressure_kpaa: Positive
+
+
+@calculation("api520/gas-subcritical-area", "API 520 subcritical gas/vapor effective area", GasSubcriticalArea,
+             ["API RP 520 7th ed. §3.6.3, Eqs. 3.5-3.7"], origin="engineering_utility",
+             limitations=["SI mass-flow form; conventional/pilot valve route only; use balanced-bellows manufacturer factors where applicable."])
+def gas_subcritical_area(x):
+    k = x.heat_capacity_ratio
+    p1, p2 = x.relief_pressure_kpaa, x.downstream_pressure_kpaa
+    ensure(k > 1.0 and 0 < p2 < p1, "Subcritical flow requires 0 < P2 < P1 and k > 1")
+    r = p2 / p1
+    f2 = sqrt((k / (k - 1.0)) * r ** (2.0 / k) * (1.0 - r ** ((k - 1.0) / k)) / (1.0 - r))
+    area = 17.9 * x.required_mass_flow_kg_h * sqrt(x.relieving_temperature_k * x.compressibility_factor / x.molecular_weight_kg_kmol) / (f2 * x.discharge_coefficient * x.combination_factor * sqrt(p1 * (p1 - p2)))
+    return {"required_area_mm2": area, "back_pressure_ratio": r, "subcritical_flow_factor": f2}
+
+
+class LiquidArea(Model):
+    required_flow_l_min: Positive
+    specific_gravity: Positive
+    set_pressure_kpag: Positive
+    back_pressure_kpag: NonNegative = 0.0
+    discharge_coefficient: Positive = 0.65
+    back_pressure_factor: Positive = 1.0
+    combination_factor: Positive = 1.0
+    viscosity_factor: Positive = 1.0
+    overpressure_factor: Positive = 1.0
+
+
+@calculation("api520/liquid-area", "API 520 liquid relief effective area", LiquidArea,
+             ["API RP 520 7th ed. §3.8-3.9, Eqs. 3.9 and 3.12"], origin="engineering_utility",
+             limitations=["SI form; Kp/Kv/Kw are supplied or separately calculated; certified capacity and two-phase flashing are separate routes."])
+def liquid_area(x):
+    ensure(x.set_pressure_kpag > x.back_pressure_kpag, "Set pressure must exceed back pressure")
+    dp = x.set_pressure_kpag - x.back_pressure_kpag
+    area = 11.78 * x.required_flow_l_min * sqrt(x.specific_gravity) / (x.discharge_coefficient * x.back_pressure_factor * x.combination_factor * x.viscosity_factor * x.overpressure_factor * sqrt(dp))
+    return {"required_area_mm2": area}
+
+
+class ViscosityFactor(Model):
+    reynolds_number: Positive
+
+
+@calculation("api520/liquid-viscosity-factor", "API 520 liquid viscosity correction Kv", ViscosityFactor,
+             ["API RP 520 7th ed. §3.8.1.3, Eqs. 3.10-3.11; Fig. 36"], origin="engineering_utility",
+             limitations=["Correlation is not recommended below 100 SSU when using the alternate viscosity basis."])
+def liquid_viscosity_factor(x):
+    r = x.reynolds_number
+    return {"viscosity_factor": 1.0 / (0.9935 + 2.878 / sqrt(r) + 342.75 / (r ** 1.5))}
+
+
+class GasCriticalCapacity(Model):
+    effective_area_mm2: Positive
+    relieving_temperature_k: Positive
+    compressibility_factor: Positive = 1.0
+    molecular_weight_kg_kmol: Positive
+    relief_pressure_kpaa: Positive
+    heat_capacity_ratio: Positive
+    discharge_coefficient: Fraction = 0.975
+    back_pressure_factor: Positive = 1.0
+    combination_factor: Positive = 1.0
+
+
+@calculation("api520/gas-critical-capacity", "API 520 critical gas/vapor mass capacity", GasCriticalCapacity,
+             ["API RP 520 7th ed. §3.6.2, Eqs. 3.2-3.4 (inverse sizing)"], origin="engineering_utility",
+             limitations=["Inverse of the SI effective-area relation; use certified valve capacity and qualified real-gas data for selection."])
+def gas_critical_capacity(x):
+    ensure(x.compressibility_factor > 0 and x.molecular_weight_kg_kmol > 0, "Invalid gas property")
+    k = x.heat_capacity_ratio
+    ensure(k > 1.0, "Heat-capacity ratio must exceed one")
+    c = 520.0 * sqrt(k * (2.0 / (k + 1.0)) ** ((k + 1.0) / (k - 1.0)))
+    rate = x.effective_area_mm2 * c * x.discharge_coefficient * x.relief_pressure_kpaa * x.back_pressure_factor * x.combination_factor
+    rate /= 13160.0 * sqrt(x.relieving_temperature_k * x.compressibility_factor / x.molecular_weight_kg_kmol)
+    return {"mass_capacity_kg_h": rate}
+
+
+class GasSubcriticalCapacity(Model):
+    effective_area_mm2: Positive
+    relieving_temperature_k: Positive
+    compressibility_factor: Positive = 1.0
+    molecular_weight_kg_kmol: Positive
+    relief_pressure_kpaa: Positive
+    heat_capacity_ratio: Positive
+    discharge_coefficient: Fraction = 0.975
+    combination_factor: Positive = 1.0
+    downstream_pressure_kpaa: Positive
+
+
+@calculation("api520/gas-subcritical-capacity", "API 520 subcritical gas/vapor mass capacity", GasSubcriticalCapacity,
+             ["API RP 520 7th ed. §3.6.3, Eqs. 3.5-3.7 (inverse sizing)"], origin="engineering_utility",
+             limitations=["Inverse of the SI effective-area relation; downstream pressure and manufacturer correction factors remain caller-qualified."])
+def gas_subcritical_capacity(x):
+    k = x.heat_capacity_ratio
+    p1, p2 = x.relief_pressure_kpaa, x.downstream_pressure_kpaa
+    ensure(k > 1.0 and 0 < p2 < p1, "Subcritical flow requires 0 < P2 < P1 and k > 1")
+    r = p2 / p1
+    f2 = sqrt((k / (k - 1.0)) * r ** (2.0 / k) * (1.0 - r ** ((k - 1.0) / k)) / (1.0 - r))
+    rate = x.effective_area_mm2 * f2 * x.discharge_coefficient * x.combination_factor * sqrt(p1 * (p1 - p2))
+    rate /= 17.9 * sqrt(x.relieving_temperature_k * x.compressibility_factor / x.molecular_weight_kg_kmol)
+    return {"mass_capacity_kg_h": rate, "back_pressure_ratio": r, "subcritical_flow_factor": f2}
+
+
+class LiquidCapacity(Model):
+    effective_area_mm2: Positive
+    specific_gravity: Positive
+    set_pressure_kpag: Positive
+    back_pressure_kpag: NonNegative = 0.0
+    discharge_coefficient: Positive = 0.65
+    back_pressure_factor: Positive = 1.0
+    combination_factor: Positive = 1.0
+    viscosity_factor: Positive = 1.0
+    overpressure_factor: Positive = 1.0
+
+
+@calculation("api520/liquid-capacity", "API 520 liquid relief volumetric capacity", LiquidCapacity,
+             ["API RP 520 7th ed. §3.8-3.9, Eqs. 3.9 and 3.12 (inverse sizing)"], origin="engineering_utility",
+             limitations=["Inverse of the SI effective-area relation; flashing/two-phase capacity and certified valve coefficients remain separate routes."])
+def liquid_capacity(x):
+    ensure(x.set_pressure_kpag > x.back_pressure_kpag, "Set pressure must exceed back pressure")
+    dp = x.set_pressure_kpag - x.back_pressure_kpag
+    rate = x.effective_area_mm2 * x.discharge_coefficient * x.back_pressure_factor * x.combination_factor * x.viscosity_factor * x.overpressure_factor * sqrt(dp)
+    rate /= 11.78 * sqrt(x.specific_gravity)
+    return {"flow_capacity_l_min": rate}
+

api581/area_contribution.py

@@ -0,0 +1,72 @@
+"""Selected event/weather area-risk contributions, distinct from full assessment."""
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Fraction, calculation, ensure, REGISTRY
+from .pof import Component, generic, Management, management, Frequency, adjusted
+from .flash_pool import FlashedBoilingPoolFlashFire, flashed_boiling_pool_flash_fire
+
+
+class AreaEventContribution(Model):
+    annual_release_frequency_per_year: NonNegative
+    weather_probability_given_release: Fraction
+    event_probability_given_release_weather: Fraction
+    equipment_area_m2: NonNegative
+    personnel_area_m2: NonNegative
+    probability_source: str = Field(min_length=1,max_length=1000)
+
+
+@calculation('risk/area-event-contribution','Selected conditional event/weather area-risk contribution',AreaEventContribution,
+    ['Part1 §4.3.1 eqs(1.6)-(1.8); Part3 §5.8.7'],
+    origin='explicit_selected_event_weather_risk_contribution',limitations=[
+        'Partial contribution only; does not require or imply complete terminal outcomes/weather/holes. Event probability is conditional on the supplied release AND weather, so multiplying by weather probability is the chain rule, not an independence assertion. Raw event areas must not already be event/weather weighted. Release frequency must not already contain these probabilities. Each probability and annual release frequency is applied once. No financial, individual or societal risk; no zero-consequence assertion for omitted events.'])
+def area_event_contribution(x):
+    ensure(bool(x.probability_source.strip()),'Conditional event/weather probability source required')
+    joint=x.weather_probability_given_release*x.event_probability_given_release_weather
+    equipment=joint*x.equipment_area_m2
+    personnel=joint*x.personnel_area_m2
+    equipment_risk=x.annual_release_frequency_per_year*equipment
+    personnel_risk=x.annual_release_frequency_per_year*personnel
+    return dict(annual_release_frequency_per_year=x.annual_release_frequency_per_year,
+        conditional_joint_probability=joint,annual_selected_event_frequency_per_year=x.annual_release_frequency_per_year*joint,
+        event_weighted_equipment_area_m2=equipment,event_weighted_personnel_area_m2=personnel,
+        equipment_area_risk_contribution_m2_per_year=equipment_risk,
+        personnel_area_risk_contribution_m2_per_year=personnel_risk,
+        area_risk_contribution_m2_per_year=max(equipment_risk,personnel_risk),
+        contribution_scope='selected_event_weather_case')
+
+
+class FlashedPoolRiskContribution(Model):
+    fire: FlashedBoilingPoolFlashFire
+    component_type: str = Field(min_length=1)
+    hole: Literal['small','medium','large','rupture']
+    management_score: NonNegative = Field(le=1000)
+    total_damage_factor: NonNegative
+    damage_factor_source: str = Field(min_length=1,max_length=1000)
+    hole_release_basis: str = Field(min_length=1,max_length=1000)
+    weather_probability_given_release: Fraction
+    event_probability_given_release_weather: Fraction
+    probability_source: str = Field(min_length=1,max_length=1000)
+
+
+@calculation('risk/flashed-pool-flash-fire-contribution','Selected hole/weather EOS-to-flash-fire annual area-risk contribution',FlashedPoolRiskContribution,
+    ['Part1 §4.3.1; Part2 Table3.1,eqs(2.1),(2.9)-(2.10); Part3 §§5.7.4,5.8.6-5.8.7'],
+    origin='selected_hole_eos_native_fire_risk_composition',limitations=[
+        *REGISTRY['risk/area-event-contribution'].limitations,
+        'Uses only the selected non-tank GFF hole, supplied governing DF and management score. Hole-specific adjusted rate/mass and applicability must be qualified externally; this API does not derive hydraulic hole size, isolation/inventory or damage applicability. Probability is for this selected steady pool flash-fire scenario, not total ignition probability.',
+        'EOS/native source scope, constant-property qualification, ground LFL, sampled-grid censoring and LH2 premise restrictions are inherited. No startup/jet/post-release pool or other outcome contribution. Omitted scenarios remain unassessed; this result is not a whole-component or four-hole risk assessment.'])
+def flashed_pool_risk_contribution(x):
+    ensure(all(s.strip() for s in (x.damage_factor_source,x.hole_release_basis,x.probability_source)),
+        'Damage, selected-hole release and probability bases must be nonblank')
+    frequencies=generic(Component(component_type=x.component_type))
+    gff=frequencies['by_hole_per_year'][x.hole]
+    fms=management(Management(score=x.management_score))['management_factor']
+    frequency=adjusted(Frequency(generic_frequency_per_year=gff,total_damage_factor=x.total_damage_factor,
+        management_factor=fms))['annual_failure_frequency']
+    fire=flashed_boiling_pool_flash_fire(x.fire)
+    contribution=area_event_contribution(AreaEventContribution(annual_release_frequency_per_year=frequency,
+        weather_probability_given_release=x.weather_probability_given_release,event_probability_given_release_weather=x.event_probability_given_release_weather,
+        equipment_area_m2=fire['equipment_area_m2'],personnel_area_m2=fire['personnel_area_m2'],probability_source=x.probability_source))
+    return {**fire,**contribution,'generic_hole_frequency_per_year':gff,'management_factor':fms,
+        'total_damage_factor':x.total_damage_factor,'selected_hole':x.hole,
+        'contribution_scope':'selected_hole_weather_steady_pool_flash_fire',
+        'integration_scope':'selected_hole_weather_steady_pool_flash_fire_risk_contribution'}

api581/blast.py

@@ -0,0 +1,232 @@
+"""API581 TNT blast fit, bounded inversion and building-collapse probit.
+
+The source provides no fit validity interval. Caller-supplied intervals are
+checked for mathematical admissibility, which is not engineering validation.
+"""
+import math
+from functools import lru_cache
+from statistics import NormalDist
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+from .effects import TntEquivalence, tnt_equivalence
+
+_A=(-.059965896,1.1288697,-7.9625216,25.106738,-30.396707,
+    19.399862,-6.8853477,1.2825511,-.097705789)
+_Q=tuple(i*_A[i] for i in range(1,len(_A)))
+_FIT_LIMIT=("Printed inverse-log polynomial, not an exponential of the polynomial. "
+    "C26=100 gives kPa; public pressure is Pa. Source specifies no fit validity "
+    "interval. Caller must supply bounds and engineering basis; positive pressure "
+    "and strictly decreasing behavior are checked over that interval. These checks "
+    "do not establish experimental fit validity or LH2 applicability.")
+
+
+class BlastFitDomain(Model):
+    minimum_scaled_distance_m_kg13: Positive
+    maximum_scaled_distance_m_kg13: Positive
+    engineering_basis: str = Field(min_length=1,max_length=1000)
+
+
+def _polynomial(coefficients,u):
+    value=coefficients[-1]
+    for coefficient in reversed(coefficients[:-1]):
+        value=value*u+coefficient
+    return value
+
+
+def _pressure(scaled):
+    return 100000*_polynomial(_A,1/math.log(scaled))
+
+
+def _derivative_interval(a,b):
+    """Outward-rounded interval Horner enclosure of dP_bar/d(1/ln R)."""
+    # Also enclose rounding of integer*A[i] when derivative coefficients form.
+    low=math.nextafter(_Q[-1],-math.inf)
+    high=math.nextafter(_Q[-1],math.inf)
+    for coefficient in reversed(_Q[:-1]):
+        products=(low*a,low*b,high*a,high*b)
+        low=math.nextafter(math.nextafter(min(products),-math.inf)+math.nextafter(coefficient,-math.inf),-math.inf)
+        high=math.nextafter(math.nextafter(max(products),math.inf)+math.nextafter(coefficient,math.inf),math.inf)
+    return low,high
+
+
+@lru_cache(maxsize=128)
+def _certify_decreasing(first,last):
+    # R>1 -> u>0 and du/dR<0: Q(u)>0 proves pressure decreases with R.
+    a=math.nextafter(1/math.log(last),-math.inf)
+    b=math.nextafter(1/math.log(first),math.inf)
+    pending=[(a,b,0)]
+    visits=0
+    while pending:
+        a,b,depth=pending.pop()
+        visits+=1
+        low,high=_derivative_interval(a,b)
+        if low > 0:
+            continue
+        ensure(high > 0 and depth < 24 and visits <= 8192,
+               "Cannot certify strictly decreasing blast pressure over supplied interval","invalid_blast_fit_domain")
+        mid=a+(b-a)/2
+        ensure(a < mid < b,"Blast interval certification reached numerical resolution","invalid_blast_fit_domain")
+        pending.extend(((a,mid,depth+1),(mid,b,depth+1)))
+
+
+def _domain(x):
+    first,last=x.minimum_scaled_distance_m_kg13,x.maximum_scaled_distance_m_kg13
+    ensure(first > 1 and last > first and bool(x.engineering_basis.strip()),
+           "Blast fit requires ordered scaled bounds above1 and nonblank engineering basis","invalid_blast_fit_domain")
+    pfirst,plast=_pressure(first),_pressure(last)
+    ensure(math.isfinite(pfirst) and math.isfinite(plast) and pfirst > plast > 0,
+           "Blast fit must have finite positive decreasing endpoint pressures","invalid_blast_fit_domain")
+    _certify_decreasing(first,last)
+    return first,last,pfirst,plast
+
+
+class ScaledDistance(Model):
+    distance_m: Positive
+    tnt_equivalent_mass_kg: Positive
+
+
+@calculation("effects/vce-scaled-distance", "Hopkinson TNT scaled distance", ScaledDistance,
+             ["Part3 eq(3.171), Annex3.B C27=1; PDF pp558,648"],
+             limitations=["SI distance m and TNT equivalent mass kg; output units m/kg^(1/3). Scaling alone does not establish blast-curve applicability. Zero TNT mass has no defined scaled distance."])
+def scaled_distance(x):
+    result=x.distance_m/math.cbrt(x.tnt_equivalent_mass_kg)
+    ensure(math.isfinite(result) and result > 0,"Scaled distance outside finite positive numerical domain","numerical_failure")
+    return {"scaled_distance_m_kg13":result}
+
+
+class ScaledOverpressure(Model):
+    scaled_distance_m_kg13: Positive
+    fit_domain: BlastFitDomain
+
+
+@calculation("effects/vce-scaled-overpressure", "Hopkinson-scaled blast overpressure fit", ScaledOverpressure,
+             ["Part3 eq(3.170), Annex3.B C26=100; PDF pp558,648"],limitations=[_FIT_LIMIT])
+def scaled_overpressure(x):
+    first,last,_,_=_domain(x.fit_domain)
+    scaled=x.scaled_distance_m_kg13
+    ensure(first <= scaled <= last,"Scaled distance outside caller blast fit interval","outside_blast_fit_domain")
+    pressure=_pressure(scaled)
+    ensure(math.isfinite(pressure) and pressure > 0,"Blast pressure outside numerical domain","numerical_failure")
+    u=1/math.log(scaled)
+    slope=-100000*u*u/scaled*_polynomial(_Q,u)
+    return {"side_on_overpressure_pa":pressure,"slope_pa_per_scaled_distance":slope}
+
+
+class BlastOverpressure(ScaledDistance):
+    fit_domain: BlastFitDomain
+
+
+@calculation("effects/vce-blast-overpressure", "TNT blast pressure at physical distance", BlastOverpressure,
+             ["Part3 eqs(3.170)-(3.171); PDF p558"],limitations=[_FIT_LIMIT,
+                          "Side-on gauge overpressure, not reflected pressure or absolute pressure. Point-source TNT equivalence has near-field limitations."])
+def overpressure(x):
+    scaled=scaled_distance(ScaledDistance(distance_m=x.distance_m,tnt_equivalent_mass_kg=x.tnt_equivalent_mass_kg))
+    result=scaled_overpressure(ScaledOverpressure(**scaled,fit_domain=x.fit_domain))
+    return {**scaled,**result}
+
+
+class BuildingProbit(Model):
+    side_on_overpressure_pa: Positive
+
+
+@calculation("effects/blast-building-probit", "Blast-induced process-building collapse probit", BuildingProbit,
+             ["Part3 eq(3.172), Annex3.B C28=1000/kPa; PDF pp558,648"],
+             limitations=["Probit=-23.8+2.92*ln(overpressure in Pa); probability=Phi(probit-5). Building-collapse mechanism used as a serious-injury proxy, not open-air lung hemorrhage, direct fatality, or a pressure-duration/structural-response model."])
+def building_probit(x):
+    probit=-23.8+2.92*math.log(x.side_on_overpressure_pa)
+    probability=.5*math.erfc(-(probit-5)/math.sqrt(2))
+    return {"probit":probit,"building_collapse_probability":probability}
+
+
+class BuildingPressureThreshold(Model):
+    building_collapse_probability: Fraction
+
+
+@calculation("effects/blast-building-pressure-threshold", "Pressure for target building-collapse probability", BuildingPressureThreshold,
+             ["Part3 eq(3.172) inverse, STEP8.14; PDF pp558,564"],
+             origin="api581_probit_inverse",
+             limitations=["Target probability must be strictly between0 and1. This is the building-collapse proxy, not a universal personnel injury threshold. Part3 STEP8.14 uses probit5 (50%); standalone inverse also supports explicitly selected alternative targets."])
+def building_threshold(x):
+    ensure(0 < x.building_collapse_probability < 1,"Building-collapse target must be strictly between0 and1")
+    probit=5+NormalDist().inv_cdf(x.building_collapse_probability)
+    pressure=math.exp((probit+23.8)/2.92)
+    return {"probit":probit,"side_on_overpressure_pa":pressure}
+
+
+class BlastDistance(Model):
+    tnt_equivalent_mass_kg: NonNegative
+    threshold_overpressure_pa: Positive
+    fit_domain: BlastFitDomain
+    distance_tolerance_m: Positive = 1e-5
+    maximum_iterations: int = Field(default=100,ge=10,le=300,strict=True)
+
+
+@calculation("effects/vce-blast-distance", "TNT blast threshold distance and consequence area", BlastDistance,
+             ["Part3 eqs(3.170)-(3.171),(3.173)-(3.174); PDF p558"],
+             origin="api581_bounded_blast_threshold_iteration",limitations=[_FIT_LIMIT,
+                          "Requires threshold bracket within supplied scaled interval; does not extrapolate to source or beyond bounds. Returns safe upper distance bracket with error bounded by distance tolerance. Zero TNT mass returns no_explosion and zero area. Area=pi*distance^2."])
+def distance(x):
+    first,last,pfirst,plast=_domain(x.fit_domain)
+    if x.tnt_equivalent_mass_kg == 0:
+        return {"safe_distance_m":0,"consequence_area_m2":0,"scaled_distance_m_kg13":None,
+                "status":"no_explosion","iterations":0,"pressure_residual_pa":None}
+    threshold=x.threshold_overpressure_pa
+    ensure(plast <= threshold <= pfirst,"Threshold not bracketed in supplied blast fit interval","unbracketed_threshold")
+    root=math.cbrt(x.tnt_equivalent_mass_kg)
+    low,high=first*root,last*root
+    ensure(math.isfinite(high) and low > 0,"Blast distance bracket outside numerical domain","numerical_failure")
+    iterations=0
+    if threshold == pfirst:
+        high=low
+    elif threshold != plast:
+        while high-low > x.distance_tolerance_m and iterations < x.maximum_iterations:
+            mid=low+(high-low)/2
+            ensure(low < mid < high,"Blast iteration reached floating point resolution","numerical_failure")
+            if _pressure(mid/root) > threshold:
+                low=mid
+            else:
+                high=mid
+            iterations+=1
+        ensure(high-low <= x.distance_tolerance_m,"Blast threshold iteration did not converge","nonconvergent_threshold")
+    scaled=high/root
+    return {"safe_distance_m":high,"consequence_area_m2":math.pi*high**2,
+            "scaled_distance_m_kg13":scaled,"status":"threshold_solved","iterations":iterations,
+            "pressure_residual_pa":_pressure(scaled)-threshold}
+
+
+class BlastConsequence(TntEquivalence):
+    mass_basis: Literal["between_flammability_limits", "total_released_flammable"]
+    yield_engineering_basis: str = Field(min_length=1,max_length=1000)
+    personnel_building_collapse_probability: Fraction = .5
+    equipment_threshold_overpressure_pa: Positive = 34500
+    fit_domain: BlastFitDomain
+    distance_tolerance_m: Positive = 1e-5
+    maximum_iterations: int = Field(default=100,ge=10,le=300,strict=True)
+
+
+@calculation("effects/vce-blast-consequence", "Cloud mass to TNT blast personnel/equipment areas", BlastConsequence,
+             ["Part3 §§5.8.5.3-5.8.5.6 eqs(3.169)-(3.174), STEP8.14; PDF pp557-558,564"],
+             origin="api581_tnt_blast_composition",limitations=[_FIT_LIMIT,
+                          "Caller supplies cloud mass at ignition or total released flammable mass and a consistent qualified yield. Source recommends yield1 for mass between LFL/UFL; typical total-release yields.03-.19 are not automatically assigned by material. Dispersion/ignition timing not solved here.",
+                          "TNT heat is mandatory because printed4648J/kg conflicts with2000Btu/lb; no silent correction. Personnel target defaults to50% building collapse per Part3 STEP8.14 (probit5), with explicit alternative targets supported. This is not direct lethality. No ignition/event weighting, congestion correction or TNO multi-energy model."])
+def consequence(x):
+    ensure(bool(x.yield_engineering_basis.strip()) and bool(x.tnt_heat_source.strip()),
+           "TNT heat and explosion yield require nonblank engineering source/basis")
+    _domain(x.fit_domain)
+    tnt=tnt_equivalence(TntEquivalence(**x.model_dump(include=set(TntEquivalence.model_fields))))["tnt_equivalent_mass_kg"]
+    ensure(math.isfinite(tnt),"TNT equivalent mass outside numerical domain","numerical_failure")
+    ensure(tnt > 0 or x.flammable_cloud_mass_kg == 0 or x.explosion_yield == 0,
+           "TNT equivalent mass underflow","numerical_failure")
+    personnel_pressure=building_threshold(BuildingPressureThreshold(
+        building_collapse_probability=x.personnel_building_collapse_probability))["side_on_overpressure_pa"]
+    setup=dict(tnt_equivalent_mass_kg=tnt,fit_domain=x.fit_domain,
+        distance_tolerance_m=x.distance_tolerance_m,maximum_iterations=x.maximum_iterations)
+    personnel=distance(BlastDistance(**setup,threshold_overpressure_pa=personnel_pressure))
+    equipment=distance(BlastDistance(**setup,threshold_overpressure_pa=x.equipment_threshold_overpressure_pa))
+    return {"tnt_equivalent_mass_kg":tnt,"personnel_threshold_overpressure_pa":personnel_pressure,
+            "personnel_building_collapse_probability":x.personnel_building_collapse_probability,
+            "equipment_threshold_overpressure_pa":x.equipment_threshold_overpressure_pa,
+            "personnel_safe_distance_m":personnel["safe_distance_m"],"equipment_safe_distance_m":equipment["safe_distance_m"],
+            "personnel_area_m2":personnel["consequence_area_m2"],"equipment_area_m2":equipment["consequence_area_m2"],
+            "personnel_status":personnel["status"],"equipment_status":equipment["status"],"mass_basis":x.mass_basis}