iapws-if97 2.2.0 → 2.8.0

package/dist/backward/fixed-temperature-candidates.js

@@ -0,0 +1,188 @@
+import * as C from '../constants.js';
+import { solveRegion3PTBasic } from '../core/region3-pt.js';
+import { nextPositiveFloat } from '../core/floating-point.js';
+import { NumericalStateError } from '../errors.js';
+import { formulationSeamAtTemperature, matchFixedSeam } from '../core/formulation-seams.js';
+import { boundary23_T_to_P } from '../regions/boundaries.js';
+import { region1 } from '../regions/region1.js';
+import { region2 } from '../regions/region2.js';
+import { region5 } from '../regions/region5.js';
+import { mixSaturationState, qualityFromSaturationProperty, saturationEndpointsAtTemperature, } from '../saturation/common.js';
+import { AmbiguousStateError, OutOfRangeError } from '../types.js';
+import { createFixedTemperatureStationaryPressureFinder } from './fixed-temperature-stationary.js';
+import { solveFixedTemperaturePressure } from './fixed-temperature-solver.js';
+import { backwardCandidateError, validateBackwardState } from './solution-validation.js';
+import { fixedTemperatureRootTolerance } from './tolerances.js';
+/** Return the only physical TH/TS state, or null if unresolved; proven envelope violations throw. */
+export function uniqueFixedTemperatureState(T, target, property) {
+    if (!Number.isFinite(T) || !Number.isFinite(target) || T < C.T_MIN || T > C.T_MAX) {
+        return null;
+    }
+    const solverName = property === 'enthalpy' ? 'solveTH' : 'solveTS';
+    const rootTolerance = fixedTemperatureRootTolerance(property);
+    const constraints = [
+        { label: 'temperature', expected: T },
+        { label: property, expected: target },
+    ];
+    const candidates = [];
+    let propertyMin = Infinity;
+    let propertyMax = -Infinity;
+    let finiteEnvelope = true;
+    const seamPair = formulationSeamAtTemperature(T);
+    const seam = seamPair === null ? null : matchFixedSeam(seamPair, property, target, 'temperature');
+    const incidentCandidates = new Set();
+    const stationaryPressures = createFixedTemperatureStationaryPressureFinder(T, property);
+    const sameState = (first, second) => Math.abs(first.pressure - second.pressure) <= 1e-9 * Math.max(1, Math.abs(second.pressure)) &&
+        Math.abs(first.specificVolume - second.specificVolume) <=
+            1e-9 * Math.max(first.specificVolume, second.specificVolume);
+    const add = (state, incident = false) => {
+        if (state !== seam?.state) {
+            const error = backwardCandidateError(state, constraints, { solverName });
+            if (error instanceof NumericalStateError)
+                throw error;
+            if (error !== null)
+                return;
+        }
+        // The same saturation endpoint or stationary point can bound two intervals.
+        let existing = candidates.find((other) => sameState(other, state));
+        if (existing !== undefined && incident && seam?.kind === 'overlap' &&
+            state.region === seam.state.region && existing.region !== state.region) {
+            candidates[candidates.indexOf(existing)] = state;
+            incidentCandidates.delete(existing);
+            existing = state;
+        }
+        if (existing === undefined) {
+            candidates.push(state);
+        }
+        if (incident)
+            incidentCandidates.add(existing ?? state);
+    };
+    const addInterval = (evaluator, lower, upper, includeLower = true, includeUpper = true) => {
+        if (upper.pressure < lower.pressure ||
+            ((!includeLower || !includeUpper) && upper.pressure === lower.pressure))
+            return;
+        const stateAt = (p, temperature) => {
+            if (p === lower.pressure)
+                return lower;
+            if (p === upper.pressure)
+                return upper;
+            return evaluator(p, temperature);
+        };
+        const points = [
+            lower,
+            ...stationaryPressures(lower, upper)
+                .map((p) => stateAt(p, T)),
+            upper,
+        ];
+        const lowerIncident = seamPair !== null && lower.pressure === seamPair.pressure;
+        const upperIncident = seamPair !== null && upper.pressure === seamPair.pressure;
+        for (let i = 0; i < points.length; i++) {
+            const current = points[i];
+            if (Number.isFinite(current[property])) {
+                propertyMin = Math.min(propertyMin, current[property]);
+                propertyMax = Math.max(propertyMax, current[property]);
+            }
+            else {
+                finiteEnvelope = false;
+            }
+            const residual = current[property] - target;
+            const currentIncluded = (i > 0 || includeLower) && (i < points.length - 1 || includeUpper);
+            const currentMatches = Math.abs(residual) <= rootTolerance &&
+                (currentIncluded || candidates.some((other) => sameState(other, current)));
+            if (currentMatches && currentIncluded) {
+                add(current, (i === 0 && lowerIncident) || (i === points.length - 1 && upperIncident));
+            }
+            if (!currentIncluded && Math.abs(residual) <= rootTolerance && !currentMatches) {
+                // The closest admissible float is the endpoint of the supported pressure domain.
+                const pressure = nextPositiveFloat(current.pressure, i === 0 ? 1 : -1);
+                if (pressure > lower.pressure && pressure < upper.pressure) {
+                    const interior = stateAt(pressure, T);
+                    if (Math.abs(interior[property] - target) <= rootTolerance) {
+                        add(interior, (i === 0 && lowerIncident) || (i === points.length - 1 && upperIncident));
+                    }
+                }
+            }
+            if (i === 0)
+                continue;
+            const previous = points[i - 1];
+            const previousResidual = previous[property] - target;
+            const previousIncluded = i > 1 || includeLower;
+            const previousMatches = Math.abs(previousResidual) <= rootTolerance &&
+                (previousIncluded || candidates.some((other) => sameState(other, previous)));
+            // An excluded endpoint cannot hide a root just inside its open interval.
+            if (currentMatches || previousMatches ||
+                previousResidual * residual >= 0)
+                continue;
+            add(solveFixedTemperaturePressure(stateAt, T, target, previous.pressure, current.pressure, property, solverName, previousIncluded, currentIncluded), (i === 1 && lowerIncident) || (i === points.length - 1 && upperIncident));
+        }
+    };
+    if (T > C.R5_T_MIN) {
+        addInterval(region5, region5(C.P_MIN, T), region5(C.R5_P_MAX, T));
+    }
+    else if (T >= C.B23_T_MAX) {
+        addInterval(region2, region2(C.P_MIN, T), region2(C.P_MAX, T));
+    }
+    else if (T >= C.Tc) {
+        const p23 = Math.min(C.P_MAX, boundary23_T_to_P(T));
+        addInterval(region2, region2(C.P_MIN, T), region2(p23, T), true, false);
+        addInterval(solveRegion3PTBasic, solveRegion3PTBasic(p23, T), solveRegion3PTBasic(C.P_MAX, T));
+    }
+    else {
+        const endpoints = saturationEndpointsAtTemperature(T);
+        if (T >= C.Tt &&
+            target >= endpoints.liquid[property] - rootTolerance &&
+            target <= endpoints.vapor[property] + rootTolerance) {
+            add(mixSaturationState(endpoints, qualityFromSaturationProperty(endpoints.liquid[property], endpoints.vapor[property], target)));
+        }
+        if (T <= C.R2_T_MIN) {
+            addInterval(region1, region1(endpoints.pressure, T), region1(C.P_MAX, T));
+            addInterval(region2, region2(C.P_MIN, T), region2(endpoints.pressure, T), true, false);
+        }
+        else {
+            const p23 = boundary23_T_to_P(T);
+            addInterval(region2, region2(C.P_MIN, T), region2(Math.min(p23, endpoints.pressure), T), true, false);
+            // Keep the vapor and liquid Region 3 branches separate at saturation.
+            addInterval(solveRegion3PTBasic, solveRegion3PTBasic(p23, T), endpoints.vapor);
+            addInterval(solveRegion3PTBasic, endpoints.liquid, solveRegion3PTBasic(C.P_MAX, T));
+        }
+    }
+    if (seam !== null) {
+        if (seam.kind === 'canonical') {
+            for (let i = candidates.length - 1; i >= 0; i--) {
+                if (incidentCandidates.has(candidates[i]))
+                    candidates.splice(i, 1);
+            }
+            add(seam.state);
+        }
+        else if (seam.kind === 'overlap') {
+            const canonical = candidates.find((state) => incidentCandidates.has(state) &&
+                state.region === seam.pair.canonical.region);
+            if (canonical !== undefined) {
+                for (let i = candidates.length - 1; i >= 0; i--) {
+                    if (candidates[i] !== canonical && incidentCandidates.has(candidates[i]))
+                        candidates.splice(i, 1);
+                }
+            }
+        }
+        else if (candidates.length === 0) {
+            add(seam.state);
+        }
+    }
+    // Only the hull exterior proves a range error; an interior gap can be numerical.
+    if (candidates.length === 0 && finiteEnvelope &&
+        Number.isFinite(propertyMin) && Number.isFinite(propertyMax) &&
+        (target < propertyMin - rootTolerance || target > propertyMax + rootTolerance)) {
+        throw new OutOfRangeError(`${property === 'enthalpy' ? 'Enthalpy' : 'Entropy'} at T=${T} K`, target, propertyMin, propertyMax);
+    }
+    const validate = (state) => validateBackwardState(state, constraints, {
+        solverName,
+        expectedRegion: state.region,
+        ...(seam !== null && state === seam.state ? { seam } : {}),
+    });
+    if (candidates.length > 1) {
+        const validated = candidates.map(validate);
+        validated.sort((first, second) => first.pressure - second.pressure);
+        throw new AmbiguousStateError(T, target, property, validated);
+    }
+    return candidates.length === 0 ? null : validate(candidates[0]);
+}

package/dist/backward/fixed-temperature-solver.d.ts

@@ -11,8 +11,8 @@ export type FixedTemperatureProperty = 'enthalpy' | 'entropy';
  * Solve for pressure at fixed temperature by matching a target property value.
  *
  * Evaluates the region equation at the bracket endpoints first (short-circuit
- * if either already matches), then runs a bracketed Newton iteration driven by
- * the analytic pressure derivative.
+ * if an included endpoint matches), then runs a bracketed Newton iteration driven by
+ * the analytic pressure derivative (density derivative for Region 3).
  *
  * @param evaluator  - Region-specific equation returning BasicProperties from (p, T)
  * @param T          - Fixed temperature [K]
@@ -22,4 +22,4 @@ export type FixedTemperatureProperty = 'enthalpy' | 'entropy';
  * @param property   - Which property `target` represents
  * @param solverName - Label used in error messages
  */
-export declare function solveFixedTemperaturePressure(evaluator: (p: number, T: number) => BasicProperties, T: number, target: number, lower: number, upper: number, property: FixedTemperatureProperty, solverName: string): BasicProperties;
+export declare function solveFixedTemperaturePressure(evaluator: (p: number, T: number) => BasicProperties, T: number, target: number, lower: number, upper: number, property: FixedTemperatureProperty, solverName: string, includeLower?: boolean, includeUpper?: boolean): BasicProperties;

package/dist/backward/fixed-temperature-solver.js

@@ -1,6 +1,8 @@
-import { IF97Error } from '../types.js';
+import { IF97Error, Region } from '../types.js';
+import { region3ByRhoT } from '../regions/region3.js';
 import { bracketedNewton } from '../solvers/bracketed-newton.js';
-import { gibbsPropertyDerivatives } from './thermodynamic-derivatives.js';
+import { gibbsPropertyDerivatives, helmholtzPropertyDerivatives } from '../core/thermodynamic-derivatives.js';
+import { fixedTemperatureRootTolerance } from './tolerances.js';
 function propertyValue(state, property) {
     return property === 'enthalpy' ? state.enthalpy : state.entropy;
 }
@@ -19,8 +21,8 @@ function pressureDerivative(state, property) {
  * Solve for pressure at fixed temperature by matching a target property value.
  *
  * Evaluates the region equation at the bracket endpoints first (short-circuit
- * if either already matches), then runs a bracketed Newton iteration driven by
- * the analytic pressure derivative.
+ * if an included endpoint matches), then runs a bracketed Newton iteration driven by
+ * the analytic pressure derivative (density derivative for Region 3).
  *
  * @param evaluator  - Region-specific equation returning BasicProperties from (p, T)
  * @param T          - Fixed temperature [K]
@@ -30,26 +32,45 @@ function pressureDerivative(state, property) {
  * @param property   - Which property `target` represents
  * @param solverName - Label used in error messages
  */
-export function solveFixedTemperaturePressure(evaluator, T, target, lower, upper, property, solverName) {
-    // Keyed by p, so the residual and its derivative at the same point share one
+export function solveFixedTemperaturePressure(evaluator, T, target, lower, upper, property, solverName, includeLower = true, includeUpper = true) {
+    const lowerState = evaluator(lower, T);
+    const upperState = evaluator(upper, T);
+    const useDensity = lowerState.region === Region.Region3;
+    // Density bounds keep Region 3 iteration on the same saturation branch.
+    const lowerBound = useDensity ? 1 / lowerState.specificVolume : lower;
+    const upperBound = useDensity ? 1 / upperState.specificVolume : upper;
+    // Keyed by p or ρ, so the residual and its derivative at the same point share one
     // equation evaluation regardless of the order the solver calls them in.
-    let cachedPressure = Number.NaN;
+    let cachedInput = Number.NaN;
     let cachedState = null;
-    const stateAt = (p) => {
-        if (p !== cachedPressure || cachedState === null) {
-            cachedPressure = p;
-            cachedState = evaluator(p, T);
+    const stateAt = (input) => {
+        if (input !== cachedInput || cachedState === null) {
+            cachedInput = input;
+            cachedState = useDensity ? region3ByRhoT(input, T) : evaluator(input, T);
         }
         return cachedState;
     };
-    const lowerState = evaluator(lower, T);
-    const upperState = evaluator(upper, T);
-    if (Math.abs(propertyValue(lowerState, property) - target) <= 1e-9)
+    const rootTolerance = fixedTemperatureRootTolerance(property);
+    if (includeLower && Math.abs(propertyValue(lowerState, property) - target) <= rootTolerance)
         return lowerState;
-    if (Math.abs(propertyValue(upperState, property) - target) <= 1e-9)
+    if (includeUpper && Math.abs(propertyValue(upperState, property) - target) <= rootTolerance)
         return upperState;
-    const pressure = bracketedNewton((p) => propertyValue(stateAt(p), property) - target, lower, upper, (lower + upper) / 2, { derivative: (p) => pressureDerivative(stateAt(p), property) });
-    const state = stateAt(pressure);
+    // Resolve open endpoints below their matching tolerance instead of snapping to them.
+    const residualScale = includeLower && includeUpper ? 1 : rootTolerance;
+    const root = bracketedNewton((input) => (propertyValue(stateAt(input), property) - target) / residualScale, lowerBound, upperBound, (lowerBound + upperBound) / 2, {
+        derivative: (input) => {
+            if (useDensity) {
+                const derivatives = helmholtzPropertyDerivatives(stateAt(input), input);
+                return (property === 'enthalpy' ? derivatives.dhDrho : derivatives.dsDrho) / residualScale;
+            }
+            return pressureDerivative(stateAt(input), property) / residualScale;
+        },
+        // Near-critical properties need a tighter bracket before termination.
+        tolerance: residualScale === 1 ? 1e-12 : Number.EPSILON,
+        // Flat isotherms require convergence in pressure or density.
+        residualTolerance: 0,
+    });
+    const state = stateAt(root);
     if (!Number.isFinite(state.pressure)) {
         throw new IF97Error(`${solverName} failed to recover a valid pressure`);
     }

package/dist/backward/fixed-temperature-stationary.d.ts

@@ -0,0 +1,4 @@
+import { type BasicProperties } from '../types.js';
+import type { FixedTemperatureProperty } from './fixed-temperature-solver.js';
+/** Share one isotherm's coefficients while keeping each pressure interval separate. */
+export declare function createFixedTemperatureStationaryPressureFinder(T: number, property: FixedTemperatureProperty): (lowerState: BasicProperties, upperState: BasicProperties) => number[];

package/dist/backward/fixed-temperature-stationary.js

@@ -0,0 +1,146 @@
+import { RHOc, Tc } from '../constants.js';
+import { COEFFICIENTS as R1_COEFFICIENTS } from '../regions/region1.js';
+import { RESIDUAL_COEFFICIENTS as R2_COEFFICIENTS } from '../regions/region2.js';
+import { COEFFICIENTS as R3_COEFFICIENTS, region3ByRhoT } from '../regions/region3.js';
+import { RESIDUAL_COEFFICIENTS as R5_COEFFICIENTS } from '../regions/region5.js';
+import { Region } from '../types.js';
+function evaluate(coefficients, x) {
+    let value = 0;
+    for (let i = coefficients.length - 1; i >= 0; i--)
+        value = value * x + coefficients[i];
+    return value;
+}
+// Derivative roots partition a polynomial into monotone intervals (Rolle's theorem).
+function polynomialRoots(coefficients, lower, upper) {
+    while (coefficients.length > 1 && coefficients[coefficients.length - 1] === 0)
+        coefficients.pop();
+    if (coefficients.length < 2)
+        return [];
+    const scale = Math.max(...coefficients.map(Math.abs));
+    const normalized = coefficients.map((value) => value / scale);
+    // Interval Horner bounds can exclude zero before constructing derivative roots.
+    let minimum = 0;
+    let maximum = 0;
+    let magnitude = 0;
+    for (let i = normalized.length - 1; i >= 0; i--) {
+        minimum = normalized[i] + minimum * (minimum < 0 ? upper : lower);
+        maximum = normalized[i] + maximum * (maximum < 0 ? lower : upper);
+        magnitude += Math.abs(normalized[i]);
+    }
+    // With x in [0, 1], allow roundoff before excluding endpoint or tangent zeros.
+    const roundingMargin = 4 * Number.EPSILON * normalized.length * magnitude;
+    if (minimum > roundingMargin || maximum < -roundingMargin)
+        return [];
+    const derivative = normalized.slice(1).map((value, i) => value * (i + 1));
+    const points = [lower, ...polynomialRoots(derivative, lower, upper), upper];
+    const roots = [];
+    for (let i = 0; i < points.length; i++) {
+        let a = points[i];
+        let fa = evaluate(normalized, a);
+        if (fa === 0)
+            roots.push(a);
+        if (i === points.length - 1)
+            break;
+        let b = points[i + 1];
+        const fb = evaluate(normalized, b);
+        if (fa === 0 || fb === 0 || Math.sign(fa) === Math.sign(fb))
+            continue;
+        for (let step = 0; step < 64; step++) {
+            const midpoint = (a + b) / 2;
+            if (midpoint === a || midpoint === b)
+                break;
+            const fm = evaluate(normalized, midpoint);
+            if (fm === 0) {
+                a = midpoint;
+                b = midpoint;
+                break;
+            }
+            if (Math.sign(fa) === Math.sign(fm)) {
+                a = midpoint;
+                fa = fm;
+            }
+            else
+                b = midpoint;
+        }
+        roots.push((a + b) / 2);
+    }
+    return roots.filter((root, i) => i === 0 || root !== roots[i - 1]);
+}
+function stationaryCoefficients(T, region, property) {
+    let table;
+    let tau;
+    switch (region) {
+        case Region.Region1:
+            table = R1_COEFFICIENTS;
+            tau = 1386 / T - 1.222;
+            break;
+        case Region.Region2:
+            table = R2_COEFFICIENTS;
+            tau = 540 / T - 0.5;
+            break;
+        case Region.Region3:
+            table = R3_COEFFICIENTS;
+            tau = Tc / T;
+            break;
+        case Region.Region5:
+            table = R5_COEFFICIENTS;
+            tau = 1000 / T;
+            break;
+        case Region.Region4: return [];
+    }
+    const logarithmicEntropy = property === 'entropy' && region !== Region.Region1;
+    const coefficients = Array(Math.max(...table.map(([I]) => I)) +
+        (logarithmicEntropy ? 1 : 0)).fill(0);
+    if (logarithmicEntropy) {
+        // Multiplying ds/dp (or ds/dδ) by its positive native variable clears 1/p (1/δ).
+        coefficients[0] = region === Region.Region3 ? -R3_COEFFICIENTS[0][2] : -1;
+    }
+    for (const [I, J, N] of table) {
+        if (I === 0)
+            continue;
+        // Constant nonzero factors do not affect the derivative's zeros.
+        let coefficient;
+        if (region === Region.Region3) {
+            coefficient = N * I * (property === 'enthalpy' ? I + J : J - 1) * Math.pow(tau, J);
+        }
+        else {
+            const tauDerivative = J === 0 ? 0 : J * Math.pow(tau, J - 1);
+            const physicalTau = tau + (region === Region.Region1 ? 1.222 : region === Region.Region2 ? 0.5 : 0);
+            coefficient = property === 'enthalpy'
+                ? N * I * tauDerivative
+                : N * I * (physicalTau * tauDerivative - Math.pow(tau, J));
+        }
+        coefficients[I - (logarithmicEntropy ? 0 : 1)] += coefficient;
+    }
+    return coefficients;
+}
+/** Share one isotherm's coefficients while keeping each pressure interval separate. */
+export function createFixedTemperatureStationaryPressureFinder(T, property) {
+    const coefficientsByRegion = new Map();
+    return (lowerState, upperState) => {
+        const region = lowerState.region;
+        let coefficients = coefficientsByRegion.get(region);
+        if (coefficients === undefined) {
+            coefficients = stationaryCoefficients(T, region, property);
+            coefficientsByRegion.set(region, coefficients);
+        }
+        if (coefficients.length === 0)
+            return [];
+        const nativeValue = (state) => region === Region.Region1
+            ? 7.1 - state.pressure / 16.53
+            : region === Region.Region3 ? 1 / (state.specificVolume * RHOc) : state.pressure;
+        const lower = Math.min(nativeValue(lowerState), nativeValue(upperState));
+        const upper = Math.max(nativeValue(lowerState), nativeValue(upperState));
+        // Scaling the native variable to [0, 1] avoids powers of pressures up to 100 MPa.
+        const scaled = coefficients.map((value, i) => value * Math.pow(upper, i));
+        return polynomialRoots(scaled, lower / upper, 1).map((root) => {
+            const native = root * upper;
+            if (region === Region.Region1)
+                return (7.1 - native) * 16.53;
+            if (region === Region.Region3)
+                return region3ByRhoT(native * RHOc, T).pressure;
+            return native;
+        }).filter((pressure) => pressure > lowerState.pressure && pressure < upperState.pressure)
+            .sort((a, b) => a - b);
+    };
+}

package/dist/backward/hs-region.d.ts

@@ -0,0 +1,50 @@
+import type { BasicProperties } from '../types.js';
+import { Region } from '../types.js';
+export interface HSClassificationCandidate {
+    state?: BasicProperties;
+}
+/**
+ * Saturated liquid enthalpy boundary for Region 1 (Eq. 3).
+ * h'_1(s)
+ */
+export declare function h1Sat(s: number): number;
+/**
+ * Region 1 / Region 3 boundary enthalpy (Eq. 1, B13).
+ * h_13(s)
+ */
+export declare function h13Boundary(s: number): number;
+/**
+ * Region 3a / Region 4 saturation boundary (Eq. 4).
+ * h'_3a(s)
+ */
+export declare function h3aSat(s: number): number;
+/**
+ * Region 2ab / Region 4 saturation boundary (Eq. 5).
+ * h"_2ab(s)
+ */
+export declare function h2abSat(s: number): number;
+/**
+ * Region 2c / Region 3b saturation boundary (Eq. 6).
+ * h"_2c3b(s)
+ */
+export declare function h2c3bSat(s: number): number;
+/**
+ * Region 2/3 boundary temperature from h,s (Eq. 8).
+ * T_B23(h,s)
+ */
+export declare function tB23hs(h: number, s: number): number;
+/**
+ * Backward equation P(h,s) for Region 2c (used for R2/R3 discrimination).
+ */
+export declare function backward2cPhs(h: number, s: number): number;
+/** Share HS classification, throwing range errors only for proven envelope violations. */
+export declare function classifyRegionHS(h: number, s: number, solved?: HSClassificationCandidate): Region | -1;
+/**
+ * Detect the IAPWS-IF97 region for given H and S.
+ * Implements the zone-based detection from the IAPWS supplementary release.
+ *
+ * @param h - Specific enthalpy [kJ/kg]
+ * @param s - Specific entropy [kJ/(kg·K)]
+ * @returns Region number (1–5) or -1 if out of range
+ */
+export declare function detectRegionHS(h: number, s: number): Region | -1;