api581-engine 0.1.4__py3-none-any.whl

api581/representative_fluids.py

@@ -0,0 +1,172 @@
+"""API 581 Part 3 Table 4.2/4.2M representative-fluid properties.
+
+The table is intentionally kept as source data rather than hidden inside a
+consequence calculation.  This makes the selection reusable by release,
+phase, flash and consequence APIs.  The printed Table 4.2M heat-capacity
+polynomials and the printed note 2 hyperbolic form are evaluated directly
+from the table. No silently substituted property package is used.
+"""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, Positive, Fraction, calculation, ensure
+
+FluidId = Literal[
+    "C1-C2", "C3-C4", "C5", "C6-C8", "C9-C12", "C13-C16", "C17-C25", "C25+",
+    "Water", "Steam", "Acid", "H2", "H2S", "HF", "CO", "DEE", "HCL",
+    "Nitric Acid", "ALCL3", "NO2", "Phosgene", "TDI", "Methanol", "PO",
+    "Styrene", "EEA", "EE", "EG", "EO", "Pyrophoric"
+]
+
+
+class AcidCausticSelection(Model):
+    """Table 4.1.3 decision for acid/caustic nonflammable releases."""
+    is_acid_or_caustic: bool
+    is_flammable: bool
+    is_toxic: bool
+    personnel_contact_hazard: bool
+
+
+@calculation(
+    "properties/acid-caustic-representative-fluid",
+    "API 581 acid/caustic representative-fluid selection",
+    AcidCausticSelection,
+    ["Part 3 §4.1.3, §4.1.6; PDF p483-484"],
+    limitations=[
+        "Implements only the printed screening rule: ACID is selected for a nonflammable, nontoxic acid/caustic that still presents personnel contact hazard. It does not determine chemistry, concentration, toxicity, flammability or splash hazard from plant data."
+    ],
+)
+def acid_caustic_representative_fluid(x):
+    selected = x.is_acid_or_caustic and not x.is_flammable and not x.is_toxic and x.personnel_contact_hazard
+    return {
+        "selection": "acid_reference" if selected else "not_applicable",
+        "representative_fluid": "Acid" if selected else None,
+        "release_phase": "liquid" if selected else None,
+        "consequence_model": "acid_splash" if selected else None,
+        "selection_basis": "Part 3 §4.1.3 printed ACID rule" if selected else "caller must select another representative fluid or consequence route",
+    }
+
+
+class MixturePropertyComponent(Model):
+    fluid: FluidId
+    mole_fraction: Fraction
+    consequence_relevant: bool = True
+
+
+class MixtureRepresentativeFluid(Model):
+    components: list[MixturePropertyComponent] = Field(min_length=1, max_length=100)
+
+
+@calculation(
+    "properties/mixture-representative-fluid",
+    "Annex 3.A mole-weighted representative-fluid selection",
+    MixtureRepresentativeFluid,
+    ["Part 3 Annex A §3.1.2.1, §3.1.2.3-§3.1.2.4, eq (3.A.1); PDF pp614-615"],
+    limitations=[
+        "Uses Table 4.2M properties and mole-fraction weighting for MW, NBP, density and AIT. Inert/non-consequence-relevant components are excluded as the printed conservative Level 1 rule directs. Hydrocarbon pseudo-components are selected only from the hydrocarbon rows; selection then prioritizes the highest candidate NBP that does not exceed the weighted NBP. Chemistry outside the table remains Level 2 recommended and is not silently mapped."
+    ],
+)
+def mixture_representative_fluid(x):
+    ensure(abs(math.fsum(c.mole_fraction for c in x.components) - 1.0) <= 1e-9, "Mixture mole fractions must sum to 1")
+    relevant = [c for c in x.components if c.consequence_relevant and c.mole_fraction > 0]
+    ensure(relevant, "At least one consequence-relevant mixture component is required")
+    relevant_total = math.fsum(c.mole_fraction for c in relevant)
+    weighted = {
+        "molecular_weight_kg_kmol": math.fsum(c.mole_fraction * TABLE_4_2M[c.fluid][0] for c in relevant) / relevant_total,
+        "normal_boiling_point_k": 273.15 + math.fsum(c.mole_fraction * TABLE_4_2M[c.fluid][2] for c in relevant) / relevant_total,
+        "liquid_density_kg_m3": math.fsum(c.mole_fraction * TABLE_4_2M[c.fluid][1] for c in relevant) / relevant_total,
+    }
+    ait_values = [(c, TABLE_4_2M[c.fluid][6]) for c in relevant]
+    ensure(all(value is not None for _, value in ait_values), "AIT is unavailable for a relevant mixture component")
+    weighted["autoignition_temperature_k"] = 273.15 + math.fsum(c.mole_fraction * value for c, value in ait_values) / relevant_total
+    weighted_nbp_c = weighted["normal_boiling_point_k"] - 273.15
+    # Annex 3.A examples are pseudo-component mixtures.  Do not select an
+    # unrelated chemical merely because its boiling point happens to be close.
+    hydrocarbon_rows = {"C1-C2", "C3-C4", "C5", "C6-C8", "C9-C12", "C13-C16", "C17-C25", "C25+"}
+    relevant_fluids = {c.fluid for c in relevant}
+    if relevant_fluids <= hydrocarbon_rows:
+        candidate_fluids = hydrocarbon_rows
+    elif len(relevant_fluids) == 1:
+        candidate_fluids = relevant_fluids
+    else:
+        candidate_fluids = set(TABLE_4_2M)
+    candidates = [(fluid, TABLE_4_2M[fluid]) for fluid in candidate_fluids if TABLE_4_2M[fluid][2] <= weighted_nbp_c]
+    ensure(candidates, "No Table 4.2M representative fluid has NBP at or below the weighted mixture NBP", "unsupported_representative_fluid")
+    selected, _ = max(candidates, key=lambda item: (item[1][2], -abs(item[1][0] - weighted["molecular_weight_kg_kmol"])))
+    return {**weighted, "selected_fluid": selected,
+            "relevant_mole_fraction": relevant_total,
+            "selection_basis": "highest_same_family_table_NBP_not_exceeding_weighted_NBP",
+            "level2_recommended": False}
+
+# MW kg/kmol, liquid density kg/m3, NBP °C, ambient state, Cp note,
+# A..E as printed, AIT °C.  N/A is represented by None.
+TABLE_4_2M = {
+    "C1-C2": (23, 250.512, -125, "Gas", 1, (12.3, .115, -2.87e-5, -1.30e-9, None), 558),
+    "C3-C4": (51, 538.379, -21, "Gas", 1, (2.632, .3188, -1.35e-4, 1.47e-8, None), 369),
+    "C5": (72, 625.199, 36, "Liquid", 1, (-3.626, .4873, -2.60e-4, 5.30e-8, None), 284),
+    "C6-C8": (100, 684.018, 99, "Liquid", 1, (-5.146, .676, -3.65e-4, 7.66e-8, None), 223),
+    "C9-C12": (149, 734.012, 184, "Liquid", 1, (-8.5, 1.01, -5.56e-4, 1.18e-7, None), 208),
+    "C13-C16": (205, 764.527, 261, "Liquid", 1, (-11.7, 1.39, -7.72e-4, 1.67e-7, None), 202),
+    "C17-C25": (280, 775.019, 344, "Liquid", 1, (-22.4, 1.94, -1.12e-3, -2.53e-7, None), 202),
+    "C25+": (422, 900.026, 527, "Liquid", 1, (-22.4, 1.94, -1.12e-3, -2.53e-7, None), 202),
+    "Water": (18, 997.947, 100, "Liquid", 3, (2.76e5, -2.09e3, 8.125, -1.41e-2, 9.37e-6), None),
+    "Steam": (18, 997.947, 100, "Gas", 3, (3.34e4, 2.68e4, 2.61e3, 8.90e3, 1.17e3), None),
+    "Acid": (18, 997.947, 100, "Liquid", 3, (2.76e5, -2.09e3, 8.125, -1.41e-2, 9.37e-6), None),
+    "H2": (2, 71.010, -253, "Gas", 1, (27.1, 9.27e-3, -1.38e-5, 7.65e-9, None), 400),
+    "H2S": (34, 993.029, -59, "Gas", 1, (31.9, 1.44e-3, 2.43e-5, -1.18e-8, None), 260),
+    "HF": (20, 967.031, 20, "Gas", 1, (29.1, 6.61e-4, -2.03e-6, 2.50e-9, None), 17760),
+    "CO": (28, 800.920, -191, "Gas", 2, (2.91e4, 8.77e3, 3.09e3, 8.46e3, 1.54e3), 609),
+    "DEE": (74, 720.828, 35, "Liquid", 2, (8.62e4, 2.55e5, 1.54e3, 1.44e5, -6.89e2), 160),
+    "HCL": (36, 1185.362, -85, "Gas", None, None, None),
+    "Nitric Acid": (63, 1521.749, 121, "Liquid", None, None, None),
+    "ALCL3": (133.5, 2434.798, 194, "Powder", 1, (4.34e4, 3.97e4, 4.17e2, 2.40e4, None), 558),
+    "NO2": (90, 929.068, 135, "Liquid", None, None, None),
+    "Phosgene": (99, 1377.583, 83, "Liquid", None, None, None),
+    "TDI": (174, 1217.399, 251, "Liquid", None, None, 620),
+    "Methanol": (32, 800.920, 65, "Liquid", 2, (3.93e4, 8.79e4, 1.92e3, 5.37e4, 8.97e2), 464),
+    "PO": (58, 832.957, 34, "Liquid", 2, (4.95e4, 1.74e5, 1.56e3, 1.15e5, 7.02e2), 449),
+    "Styrene": (104, 683.986, 145, "Liquid", 2, (8.93e4, 2.15e5, 7.72e2, 9.99e4, 2.44e3), 490),
+    "EEA": (132, 977.123, 156, "Liquid", 2, (1.06e5, 2.40e5, 6.59e2, 1.50e5, 1.97e3), 379),
+    "EE": (90, 929.068, 135, "Liquid", 2, (3.25e4, 3.00e5, 1.17e3, 2.08e5, 4.73e2), 235),
+    "EG": (62, 1105.270, 197, "Liquid", 2, (6.30e4, 1.46e5, 1.67e3, 9.73e4, 7.74e2), 396),
+    "EO": (44, 881.013, 11, "Gas", 2, (3.35e4, 1.21e5, 1.61e3, 8.24e4, 7.37e2), 429),
+    "Pyrophoric": (149, 734.012, 184, "Liquid", 1, (-8.5, 1.01, -5.56e-4, 1.18e-7, None), None),
+}
+
+
+class RepresentativeFluid(Model):
+    fluid: FluidId
+    temperature_k: Positive
+
+
+@calculation(
+    "properties/representative-fluid",
+    "API 581 Table 4.2M representative-fluid properties",
+    RepresentativeFluid,
+    ["Part 3 §4.1.1-§4.1.2, Table 4.2/Table 4.2M; PDF pp515-517"],
+    limitations=[
+        "Returns tabulated representative properties, not a real-fluid property package. Cp note 1 and note 3 are evaluated as printed polynomials; note 2 uses Cp=A+B((C/T)/sinh(C/T))²+D((E/T)/cosh(E/T))². Rows with --- have no tabulated Cp or AIT. Ambient-state and phase-selection rules remain a separate Table 4.3 decision."
+    ],
+)
+def representative_fluid(x):
+    mw, density, nbp_c, ambient_state, note, coefficients, ait_c = TABLE_4_2M[x.fluid]
+    cp = None
+    cp_basis = "not_available"
+    t = x.temperature_k
+    if coefficients is not None and note in (1, 3):
+        a, b, c, d, e = coefficients
+        cp = a + b*t + c*t*t + d*t*t*t + ((e or 0.0)*t*t*t*t if note == 3 else 0.0)
+        cp_basis = f"table_note_{note}_polynomial"
+    elif coefficients is not None and note == 2:
+        a, b, c, d, e = coefficients
+        cp = a + b*((c/t)/math.sinh(c/t))**2 + d*((e/t)/math.cosh(e/t))**2
+        cp_basis = "table_note_2_hyperbolic"
+    ensure(cp is None or cp == cp and abs(cp) < 1e12, "Representative-fluid Cp is non-finite or outside supported range")
+    return {
+        "fluid": x.fluid, "molecular_weight_kg_kmol": mw,
+        "liquid_density_kg_m3": density, "normal_boiling_point_k": nbp_c + 273.15,
+        "ambient_state": ambient_state, "cp_note": note,
+        "cp_value_table_units": cp, "cp_basis": cp_basis,
+        "autoignition_temperature_k": None if ait_c is None else ait_c + 273.15,
+        "source_table": "Table 4.2M",
+    }

api581/result.py

@@ -0,0 +1,50 @@
+"""Typed calculation results and the shared Python execution boundary."""
+from typing import Any, Generic, TypeVar
+from pydantic import Field
+from .core import Context, Model, REGISTRY, ensure, evaluate
+from .evidence import ValidationEvidence
+
+OutputT = TypeVar("OutputT", bound=Model)
+
+
+class CalculationResult(Model, Generic[OutputT]):
+    run_id: str
+    calculation_id: str
+    engine_version: str
+    standard_edition: str
+    code_fingerprint: str
+    calculated_at: str
+    context: Context
+    input_hash: str
+    normalized_inputs: dict[str, Any]
+    outputs: OutputT
+    method_origin: str
+    references: list[str]
+    limitations: list[str]
+    validation_evidence: list[ValidationEvidence] = Field(default_factory=list)
+    software_test_modules: list[str] = Field(default_factory=list)
+    direct_public_test_modules: list[str] = Field(default_factory=list)
+    validation_level: str = Field(
+        default="software_tested_only",
+        pattern=r"^(software_tested_only|native_engine_fixture_verified)$",
+    )
+    validation_status: str
+
+
+def calculate(identifier: str, inputs: Model, *, output_type: type[OutputT],
+              context: Context | None = None) -> CalculationResult[OutputT]:
+    """Execute without I/O. Domain functions supply the matching output type."""
+    ensure(identifier in REGISTRY, f"Unknown calculation: {identifier}", "unknown_calculation")
+    if not isinstance(inputs, REGISTRY[identifier].model):
+        raise TypeError(f"{identifier} requires {REGISTRY[identifier].model.__name__}")
+    from .outputs import OUTPUT_MODELS
+    if OUTPUT_MODELS[identifier] is not output_type:
+        raise TypeError("output_type must match the registered calculation")
+    payload = evaluate(identifier, inputs.model_dump(mode="python"), context)
+    from .catalog import calculation_evidence
+    evidence = calculation_evidence(identifier)
+    payload["validation_evidence"] = evidence["validation_evidence"]
+    payload["software_test_modules"] = evidence["software_test_modules"]
+    payload["direct_public_test_modules"] = evidence["direct_public_test_modules"]
+    payload["validation_level"] = evidence["validation_level"]
+    return CalculationResult[output_type].model_validate(payload)

api581/risk.py

@@ -0,0 +1,191 @@
+"""Consequence aggregation, risk and planning utilities with explicit units."""
+import math
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+from .pof import Component, generic, Management, management, GoverningDamage, combine
+
+
+class Outcome(Model):
+    event_id: str = Field(min_length=1, max_length=100)
+    probability: Fraction
+    equipment_area_m2: NonNegative
+    personnel_area_m2: NonNegative
+    financial_consequence: NonNegative
+
+
+class Consequences(Model):
+    outcomes: list[Outcome] = Field(min_length=1, max_length=100)
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+
+
+@calculation("consequence/expected", "Conditional event-weighted consequence", Consequences,
+             ["Part 3 §5.8.7, §5.11"], limitations=["Inputs must be mutually exclusive complete terminal outcomes, already conditional on the same release/weather case."])
+def expected(x):
+    ensure(len({o.event_id for o in x.outcomes}) == len(x.outcomes), "Duplicate event_id")
+    ensure(math.isclose(math.fsum(o.probability for o in x.outcomes), 1, abs_tol=1e-9), "Terminal probabilities must sum to 1")
+    return {"equipment_area_m2": math.fsum(o.probability * o.equipment_area_m2 for o in x.outcomes),
+            "personnel_area_m2": math.fsum(o.probability * o.personnel_area_m2 for o in x.outcomes),
+            "financial_consequence": math.fsum(o.probability * o.financial_consequence for o in x.outcomes), "currency": x.currency}
+
+
+class RiskScenario(Model):
+    scenario_id: str = Field(min_length=1, max_length=100)
+    annual_failure_frequency: NonNegative
+    equipment_area_m2: NonNegative
+    personnel_area_m2: NonNegative
+    financial_consequence: NonNegative
+
+
+class Risk(Model):
+    scenarios: list[RiskScenario] = Field(min_length=1, max_length=1000)
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+
+
+@calculation("risk/aggregate", "Aggregate disjoint release-scenario risks", Risk,
+             ["Part 1 §4.3.1 eqs (1.6)-(1.8)"],
+             limitations=["Scenarios must be disjoint; each consequence is conditional and already event/weather weighted. No individual/societal risk calculation."])
+def aggregate(x):
+    ensure(len({s.scenario_id for s in x.scenarios}) == len(x.scenarios), "Duplicate scenario_id")
+    total = math.fsum(s.annual_failure_frequency for s in x.scenarios)
+    equip = math.fsum(s.annual_failure_frequency * s.equipment_area_m2 for s in x.scenarios)
+    person = math.fsum(s.annual_failure_frequency * s.personnel_area_m2 for s in x.scenarios)
+    financial = math.fsum(s.annual_failure_frequency * s.financial_consequence for s in x.scenarios)
+    return {"annual_failure_frequency": total, "equipment_area_risk_m2_per_year": equip,
+            "personnel_area_risk_m2_per_year": person, "area_risk_m2_per_year": max(equip, person),
+            "financial_risk_per_year": financial, "currency": x.currency,
+            "frequency_weighted_equipment_area_m2": equip / total if total else None,
+            "frequency_weighted_personnel_area_m2": person / total if total else None}
+
+
+class HoleConsequence(Model):
+    hole: Literal["small", "medium", "large", "rupture"]
+    equipment_area_m2: NonNegative
+    personnel_area_m2: NonNegative
+    financial_consequence: NonNegative
+
+
+class Assessment(Model):
+    component_type: str
+    management_score: NonNegative = Field(le=1000)
+    total_damage_factor: NonNegative
+    damage_factor_source: str = Field(min_length=1, max_length=500)
+    consequences: list[HoleConsequence] = Field(min_length=4, max_length=4)
+    consequence_source: str = Field(min_length=1, max_length=500)
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+
+
+@calculation("risk/assessment", "Compose GFF, Fms, supplied DF and supplied hole consequences", Assessment,
+             ["Part 1 §4.1, §4.3; Part 2 §3.3, §3.5.4"],
+             limitations=["Integration boundary: DF and COF supplied externally; not a complete asset damage/COF assessment. All four holes required."])
+def assessment(x):
+    ensure({c.hole for c in x.consequences} == {"small", "medium", "large", "rupture"}, "Exactly one consequence for each of the four holes is required")
+    g = generic(Component(component_type=x.component_type))
+    fms = management(Management(score=x.management_score))["management_factor"]
+    scenarios = [RiskScenario(scenario_id=c.hole, annual_failure_frequency=g["by_hole_per_year"][c.hole] * x.total_damage_factor * fms,
+                             equipment_area_m2=c.equipment_area_m2, personnel_area_m2=c.personnel_area_m2,
+                             financial_consequence=c.financial_consequence) for c in x.consequences]
+    return {"integration_scope": "supplied_damage_and_consequences", "management_factor": fms,
+            "generic_frequencies": g, "scenarios": [s.model_dump() for s in scenarios],
+            "risk": aggregate(Risk(scenarios=scenarios, currency=x.currency))}
+
+
+class DamageAssessment(Model):
+    component_type: str
+    management_score: NonNegative = Field(le=1000)
+    damage: GoverningDamage
+    damage_factor_source: str = Field(min_length=1, max_length=500)
+    consequences: list[HoleConsequence] = Field(min_length=4, max_length=4)
+    consequence_source: str = Field(min_length=1, max_length=500)
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+
+
+@calculation(
+    "risk/assessment-from-damage",
+    "Compose damage mechanisms, GFF, management factor and hole consequences",
+    DamageAssessment,
+    ["Part 1 §§4.1,4.3; Part 2 §§3.4.2,3.5.4; Part 3 consequence inputs"],
+    limitations=[
+        "Damage mechanism inputs are still owner-qualified outputs from the individual Part 2 APIs. This composition performs the governing/total damage-factor combination and risk weighting; it does not infer applicability, inspection effectiveness, consequence areas or currency assumptions."
+    ],
+)
+def assessment_from_damage(x):
+    combined = combine(x.damage)
+    result = assessment(
+        Assessment(
+            component_type=x.component_type,
+            management_score=x.management_score,
+            total_damage_factor=combined["total_damage_factor"],
+            damage_factor_source=x.damage_factor_source,
+            consequences=x.consequences,
+            consequence_source=x.consequence_source,
+            currency=x.currency,
+        )
+    )
+    return {**result, "integration_scope": "combined_damage_and_supplied_consequences",
+            "damage_factor": combined}
+
+
+class Financial(Model):
+    component_repair_cost: NonNegative
+    surrounding_equipment_cost: NonNegative
+    business_interruption_cost: NonNegative
+    injury_cost: NonNegative
+    environmental_cost: NonNegative
+    currency: str = Field(pattern=r"^[A-Z]{3}$")
+    cost_basis_year: int = Field(ge=1900, le=2200)
+
+
+@calculation("consequence/financial-total", "Sum non-overlapping financial consequence categories", Financial,
+             ["Part 3 §4.12"], origin="engineering_utility",
+             limitations=["Category costs supplied by caller; repair/downtime/cleanup submodels not yet implemented."])
+def financial(x):
+    return {"financial_consequence": math.fsum([x.component_repair_cost, x.surrounding_equipment_cost,
+            x.business_interruption_cost, x.injury_cost, x.environmental_cost]), "currency": x.currency,
+            "cost_basis_year": x.cost_basis_year}
+
+
+class Matrix(Model):
+    frequency_per_year: NonNegative
+    consequence: NonNegative
+    frequency_boundaries: list[Positive] = Field(min_length=1, max_length=20)
+    consequence_boundaries: list[Positive] = Field(min_length=1, max_length=20)
+    risk_cells: list[list[str]]
+    policy_id: str = Field(min_length=1, max_length=200)
+
+
+@calculation("risk/matrix", "Owner-defined risk matrix classification", Matrix,
+             ["Part 1 §4.3.2"], limitations=["No built-in universal acceptance limits; equality is assigned to the higher category."])
+def matrix(x):
+    for bounds in (x.frequency_boundaries, x.consequence_boundaries):
+        ensure(all(b > a for a, b in zip(bounds, bounds[1:])), "Boundaries must strictly increase")
+    ensure(len(x.risk_cells) == len(x.frequency_boundaries) + 1 and
+           all(len(row) == len(x.consequence_boundaries) + 1 for row in x.risk_cells), "risk_cells dimensions must match boundaries")
+    i = sum(x.frequency_per_year >= b for b in x.frequency_boundaries)
+    j = sum(x.consequence >= b for b in x.consequence_boundaries)
+    return {"frequency_category": i + 1, "consequence_category": j + 1, "risk_label": x.risk_cells[i][j], "policy_id": x.policy_id}
+
+
+class RiskPoint(Model):
+    time_years: NonNegative
+    value: NonNegative
+
+
+class Crossing(Model):
+    points: list[RiskPoint] = Field(min_length=2, max_length=10000)
+    target: Positive
+    metric: Literal["financial_per_year", "area_m2_per_year", "frequency_per_year", "damage_factor"]
+
+
+@calculation("planning/target-crossing", "First target crossing on a supplied risk curve", Crossing,
+             ["Part 1 §4.4"], origin="engineering_utility",
+             limitations=["Linear interpolation between supplied points; does not generate DF forecasts or select NDE effectiveness. Unresolved crossings between samples remain possible."])
+def crossing(x):
+    ensure(all(b.time_years > a.time_years for a, b in zip(x.points, x.points[1:])), "Curve times must strictly increase")
+    if x.points[0].value >= x.target:
+        return {"status": "already_exceeded", "crossing_years": x.points[0].time_years}
+    for a, b in zip(x.points, x.points[1:]):
+        if b.value >= x.target:
+            time = a.time_years + (b.time_years - a.time_years) * (x.target - a.value) / (b.value - a.value)
+            return {"status": "crossing", "crossing_years": time}
+    return {"status": "not_crossed_within_horizon", "crossing_years": None, "horizon_years": x.points[-1].time_years}

api581/saturation.py

@@ -0,0 +1,66 @@
+"""Optional pure-fluid equilibrium properties for Level2 pool source calculations."""
+import math
+from pydantic import Field
+from .core import Model, Positive, DomainError, calculation, ensure
+
+
+class PureFluidIdentity(Model):
+    fluid: str = Field(pattern=r'^[A-Za-z][A-Za-z0-9_-]{0,79}$')
+    qualification_basis: str = Field(min_length=1)
+
+
+class SaturationPressure(PureFluidIdentity):
+    pressure_pa_abs: Positive
+
+
+class SaturationTemperature(PureFluidIdentity):
+    temperature_k: Positive
+
+
+def _saturation(inputs, coordinate):
+    ensure(bool(inputs.qualification_basis.strip()),'Fluid identity and EOS applicability qualification required')
+    try:
+        import CoolProp
+        from CoolProp.CoolProp import PropsSI, get_fluid_param_string
+    except ImportError:
+        ensure(False,'Pure-fluid saturation requires optional CoolProp8.0.0','optional_engine_missing')
+    ensure(CoolProp.__version__=='8.0.0','Saturation backend requires tested CoolProp8.0.0','engine_version_mismatch')
+    fluid=inputs.fluid
+    try:
+        ensure(get_fluid_param_string(fluid,'pure')=='true','Pseudopure fluids and mixtures are outside pure-fluid saturation scope','unsupported_saturation_fluid')
+        value=inputs.pressure_pa_abs if coordinate=='P' else inputs.temperature_k
+        lower=PropsSI('ptriple' if coordinate=='P' else 'Ttriple',fluid)
+        upper=PropsSI('pcrit' if coordinate=='P' else 'Tcrit',fluid)
+        ensure(lower<=value<upper,'Saturation coordinate must be at/above triple point and below critical point','unsupported_saturation_state')
+        def prop(name, quality):
+            return PropsSI(name,coordinate,value,'Q',quality,fluid)
+        temperature=prop('T',0.)
+        latent=prop('Hmass',1.)-prop('Hmass',0.)
+        output=dict(saturation_pressure_pa_abs=prop('P',0.),bubble_temperature_k=temperature,
+            dew_temperature_k=prop('T',1.),liquid_density_kg_m3=prop('Dmass',0.),vapor_density_kg_m3=prop('Dmass',1.),
+            liquid_specific_heat_j_kg_k=prop('Cpmass',0.),latent_heat_j_kg=latent,
+            vapor_specific_heat_j_kg_k=prop('Cpmass',1.),
+            molecular_weight_kg_kmol=PropsSI('molar_mass',fluid)*1000.)
+        ensure(all(math.isfinite(v) and v>0 for v in output.values()),'Nonfinite or nonpositive saturation property','invalid_engine_result')
+        return {**output,'engine_version':CoolProp.__version__}
+    except ValueError as exc:
+        if isinstance(exc,DomainError):
+            raise
+        ensure(False,'CoolProp could not solve supplied pure-fluid saturation state','saturation_solver_failure')
+
+
+_LIMITS=['Optional CoolProp8.0.0 HEOS pure fluids only. Triple-point to subcritical equilibrium saturation; no metastable, solid, pseudopure or mixture states. Saturated liquid cp/densities and latent heat are evaluated on the coexistence curve, not at storage or arbitrary flash temperature. Pure-fluid bubble/dew temperatures coincide. No heat of combustion, flammability, transient evaporation or fluid-wide/LH2 validation. Caller qualifies EOS and physical applicability.']
+
+
+@calculation('properties/pure-fluid-saturation-pressure','Pure-fluid bubble/dew and saturated properties at pressure',SaturationPressure,
+    ['Part3 §5.1.3-5.1.4 STEP1.4; §5.7.4.2; PDF pp540-541,544'],
+    origin='optional_coolprop_8_0_0_pure_fluid_saturation',limitations=_LIMITS)
+def saturation_pressure(inputs):
+    return _saturation(inputs,'P')
+
+
+@calculation('properties/pure-fluid-saturation-temperature','Pure-fluid vapor pressure and saturated properties at temperature',SaturationTemperature,
+    ['Part3 §5.7.4.3 eq(3.105); PDF p544'],
+    origin='optional_coolprop_8_0_0_pure_fluid_saturation',limitations=_LIMITS)
+def saturation_temperature(inputs):
+    return _saturation(inputs,'T')