iapws-if97 2.2.0 → 2.8.0

package/dist/constants.js

@@ -4,12 +4,9 @@
  * Physical constants, critical point properties, and range limits
  * for the IAPWS Industrial Formulation 1997.
  */
+import { region5 } from './regions/region5.js';
 // ─── Fundamental Constants ──────────────────────────────────────────────────
-/** Specific gas constant for water [kJ/(kg·K)].
- *  IAPWS-IF97, §2 (Table 1). Fixed value for IF97 internal consistency.
- *  Do not replace transport correlations with this value; thermal conductivity
- *  critical enhancement intentionally uses `R_IAPWS_2011_THERMAL`. */
-export const R = 0.461526;
+export { R } from './gas-constant.js';
 /** Specific gas constant used by the IAPWS 2011 thermal conductivity λ₂ correlation [kJ/(kg·K)].
  *  Intentionally differs from IF97's `R`; keep both constants distinct and named. */
 export const R_IAPWS_2011_THERMAL = 0.46151805;
@@ -18,13 +15,13 @@ export const R_IAPWS_2011_THERMAL = 0.46151805;
 export const Tc = 647.096;
 /** Temperature exclusion half-band around the critical point [K] */
 export const CRITICAL_T_EXCLUSION_BAND = 1e-3;
-/** Region 4 endpoint snap tolerance for temperatures [K] */
+/** Region 4 tolerance for outward temperature-boundary roundoff [K] */
 export const REGION4_TEMPERATURE_TOLERANCE = 1e-9;
 /** Safety margin used when clamping Region 4 temperatures below Tc [K] */
 export const REGION4_SUBCRITICAL_TEMPERATURE_MARGIN = 1e-8;
 /** Critical pressure [MPa] */
 export const Pc = 22.064;
-/** Region 4 endpoint snap tolerance for pressures [MPa] */
+/** Relative tolerance for outward Region 4 pressure-boundary roundoff */
 export const REGION4_PRESSURE_TOLERANCE = 1e-9;
 /** Tolerance for identifying the critical h-s endpoint in Region 4 */
 export const REGION4_CRITICAL_HS_TOLERANCE = 1e-6;
@@ -48,14 +45,16 @@ export const P_MAX = 100.0;
 export const T_MIN = 273.15;
 /** Maximum temperature [K] (2273.15 K = 2000 °C) */
 export const T_MAX = 2273.15;
-/** Minimum specific entropy [kJ/(kg·K)] */
-export const S_MIN = -0.00015454959194;
-/** Maximum specific entropy [kJ/(kg·K)] */
-export const S_MAX = 13.904956083429227;
-/** Minimum specific enthalpy [kJ/kg] */
-export const H_MIN = -0.041587825987;
-/** Maximum specific enthalpy [kJ/kg] */
-export const H_MAX = 7376.980263598506;
+// Match the Region 5 equation's rounding in the current runtime.
+const REGION5_UPPER = region5(P_MIN, T_MAX);
+/** Minimum specific entropy [kJ/(kg·K)], at T_MIN and P_MAX in Region 1. */
+export const S_MIN = -0.00858228709261889;
+/** Maximum specific entropy [kJ/(kg·K)], at T_MAX and P_MIN in Region 5. */
+export const S_MAX = REGION5_UPPER.entropy;
+/** Minimum specific enthalpy [kJ/kg], at T_MIN and P_MIN in Region 1. */
+export const H_MIN = -0.041587825987655716;
+/** Maximum specific enthalpy [kJ/kg], at T_MAX and P_MIN in Region 5. */
+export const H_MAX = REGION5_UPPER.enthalpy;
 // ─── Region 2 Boundaries ───────────────────────────────────────────────────
 /** Region 2 minimum temperature for high-P subregions [K] (623.15 K = 350 °C) */
 export const R2_T_MIN = 623.15;

package/dist/core/floating-point.d.ts

@@ -0,0 +1,2 @@
+/** Adjacent IEEE-754 double; value must be positive and finite. */
+export declare function nextPositiveFloat(value: number, direction: 1 | -1): number;

package/dist/core/floating-point.js

@@ -0,0 +1,7 @@
+const bits = new DataView(new ArrayBuffer(8));
+/** Adjacent IEEE-754 double; value must be positive and finite. */
+export function nextPositiveFloat(value, direction) {
+    bits.setFloat64(0, value);
+    bits.setBigUint64(0, bits.getBigUint64(0) + BigInt(direction));
+    return bits.getFloat64(0);
+}

package/dist/core/formulation-seams.d.ts

@@ -0,0 +1,27 @@
+import type { BasicProperties } from '../types.js';
+export type FormulationSeam = '13' | '23' | '25';
+export interface FormulationSeamPair {
+    seam: FormulationSeam;
+    pressure: number;
+    temperature: number;
+    /** Equations on the lower and higher temperature sides at fixed pressure. */
+    lower: BasicProperties;
+    upper: BasicProperties;
+    canonical: BasicProperties;
+}
+export interface FormulationSeamResolution {
+    pair: FormulationSeamPair;
+    kind: 'canonical' | 'gap' | 'overlap';
+    state: BasicProperties;
+    budgets: {
+        enthalpy: number;
+        entropy: number;
+    };
+}
+export declare function formulationSeamAtPressure(p: number, seam: FormulationSeam): FormulationSeamPair | null;
+/** B13/B25 cannot be crossed while retaining an independently supplied temperature. */
+export declare function formulationSeamAtTemperature(T: number): FormulationSeamPair | null;
+export declare function findPressureSeam(p: number, target: number, property: 'enthalpy' | 'entropy'): FormulationSeamResolution | null;
+export declare function matchFixedSeam(pair: FormulationSeamPair, property: 'enthalpy' | 'entropy', target: number, coordinate?: 'pressure' | 'temperature'): FormulationSeamResolution | null;
+/** Locate both constraints on one bounded ribbon between independently fitted EOS. */
+export declare function findHSSeam(h: number, s: number): FormulationSeamResolution | null;

package/dist/core/formulation-seams.js

@@ -0,0 +1,289 @@
+import * as C from '../constants.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 { saturationPressure } from '../regions/region4.js';
+import { bracketedNewton } from '../solvers/bracketed-newton.js';
+import { gibbsPropertyDerivatives } from './thermodynamic-derivatives.js';
+import { solveRegion3PTBasic } from './region3-pt.js';
+import { detectRegionPT, nativeB23TemperatureBracket } from './region-detector.js';
+import { nextPositiveFloat } from './floating-point.js';
+function pairAt(seam, p, T) {
+    const r3 = () => solveRegion3PTBasic(p, T);
+    const lower = seam === '13' ? region1(p, T) : seam === '23' ? r3() : region2(p, T);
+    const upper = seam === '13' ? r3() : seam === '23' ? region2(p, T) : region5(p, T);
+    return {
+        seam, pressure: p, temperature: T,
+        lower, upper, canonical: lower,
+    };
+}
+export function formulationSeamAtPressure(p, seam) {
+    if (!Number.isFinite(p) || p < C.P_MIN || p > C.P_MAX)
+        return null;
+    if (seam === '25')
+        return p <= C.R5_P_MAX ? pairAt(seam, p, C.R2_T_MAX) : null;
+    if (p <= C.B23_P_MIN)
+        return null;
+    if (seam === '13')
+        return p > saturationPressure(C.R2_T_MIN) ? pairAt(seam, p, C.R2_T_MIN) : null;
+    const [T] = nativeB23TemperatureBracket(p);
+    return T <= C.R2_T_MIN || (T < C.Tc && p >= saturationPressure(T)) ? null : pairAt(seam, p, T);
+}
+/** B13/B25 cannot be crossed while retaining an independently supplied temperature. */
+export function formulationSeamAtTemperature(T) {
+    if (!Number.isFinite(T) || T <= C.R2_T_MIN || T >= C.B23_T_MAX)
+        return null;
+    const p = boundary23_T_to_P(T);
+    return p > C.B23_P_MIN && p <= C.P_MAX &&
+        (T >= C.Tc || p < saturationPressure(T)) ? pairAt('23', p, T) : null;
+}
+export function findPressureSeam(p, target, property) {
+    if (!Number.isFinite(p) || !Number.isFinite(target) || p < C.P_MIN || p > C.P_MAX)
+        return null;
+    for (const seam of ['13', '23', '25']) {
+        if (seam === '25' ? p > C.R5_P_MAX : p <= C.B23_P_MIN)
+            continue;
+        let reference;
+        if (seam === '13') {
+            if (p <= saturationPressure(C.R2_T_MIN))
+                continue;
+            reference = region1(p, C.R2_T_MIN);
+        }
+        else if (seam === '23') {
+            const [T] = nativeB23TemperatureBracket(p);
+            if (T < C.Tc && p >= saturationPressure(T))
+                continue;
+            reference = region2(p, T);
+        }
+        else {
+            reference = region2(p, C.R2_T_MAX);
+        }
+        // IF97 Table 43 consistency limits only prefilter; acceptance uses the actual EOS span.
+        if (Math.abs(reference[property] - target) > (property === 'enthalpy' ? 0.2 : 0.0002))
+            continue;
+        const pair = formulationSeamAtPressure(p, seam);
+        const match = pair === null ? null : matchFixedSeam(pair, property, target);
+        if (match !== null)
+            return match;
+    }
+    return null;
+}
+function numericalAllowance(value) {
+    return 128 * Number.EPSILON * Math.max(1, Math.abs(value));
+}
+function resolution(pair, kind, hsReconstruction = false) {
+    return {
+        pair, kind, state: pair.canonical,
+        budgets: {
+            enthalpy: Math.abs(pair.upper.enthalpy - pair.lower.enthalpy) +
+                (hsReconstruction ? 1e-9 : numericalAllowance(pair.canonical.enthalpy)),
+            entropy: Math.abs(pair.upper.entropy - pair.lower.entropy) +
+                (hsReconstruction ? 1e-12 : numericalAllowance(pair.canonical.entropy)),
+        },
+    };
+}
+export function matchFixedSeam(pair, property, target, coordinate = 'pressure') {
+    if (coordinate === 'temperature' && pair.seam !== '23')
+        return null;
+    if (pair.seam === '23' && pair.pressure === C.P_MAX) {
+        const corner = region2(C.P_MAX, C.B23_T_MAX);
+        // The exact PT corner is R2, above the native quadratic's last R3 float.
+        if (target === corner[property])
+            return resolution({ ...pair, canonical: corner }, 'canonical');
+    }
+    const lower = pair.lower[property];
+    const upper = pair.upper[property];
+    if (!Number.isFinite(target) || target < Math.min(lower, upper) || target > Math.max(lower, upper))
+        return null;
+    if (target === pair.canonical[property])
+        return resolution(pair, 'canonical');
+    const interior = coordinate === 'temperature'
+        ? region2(nextPositiveFloat(pair.pressure, -1), pair.temperature)
+        : pair.seam === '13' ? solveRegion3PTBasic(pair.pressure, nextPositiveFloat(pair.temperature, 1))
+            : pair.seam === '23' ? region2(pair.pressure, nextPositiveFloat(pair.temperature, 1))
+                : region5(pair.pressure, nextPositiveFloat(pair.temperature, 1));
+    // EOS rounding can put the first admissible float inside the endpoint's gap.
+    if (coordinate === 'pressure' && detectRegionPT(interior.pressure, interior.temperature) === interior.region &&
+        Math.abs(interior[property] - target) <= (property === 'enthalpy' ? 1e-9 : 1e-12)) {
+        return resolution({ ...pair, canonical: interior }, 'canonical');
+    }
+    if (coordinate === 'temperature') {
+        if (target !== upper && interior[property] === target)
+            return null;
+        const first = gibbsPropertyDerivatives(pair.lower);
+        const second = gibbsPropertyDerivatives(pair.upper);
+        const derivative = property === 'enthalpy' ? 'dhDp' : 'dsDp';
+        if (first[derivative] >= 0 || second[derivative] >= 0)
+            return null;
+    }
+    return resolution(pair, upper > lower ? 'gap' : 'overlap');
+}
+function tangent(pair, state) {
+    const derivatives = gibbsPropertyDerivatives(state);
+    if (pair.seam !== '23')
+        return [derivatives.dhDp, derivatives.dsDp];
+    // Derivative of the native quadratic B23 pressure boundary.
+    const dpDT = -1.1671859879975 + 2 * 0.0010192970039326 * pair.temperature;
+    return [
+        derivatives.dhDT + derivatives.dhDp * dpDT,
+        derivatives.dsDT + derivatives.dsDp * dpDT,
+    ];
+}
+let hsDomains;
+function b23LowerTemperature() {
+    let lower = C.R2_T_MIN;
+    let upper = C.Tc;
+    while (true) {
+        const middle = (lower + upper) / 2;
+        if (middle === lower || middle === upper)
+            return upper;
+        if (boundary23_T_to_P(middle) < saturationPressure(middle))
+            upper = middle;
+        else
+            lower = middle;
+    }
+}
+function pairAtParameter(seam, parameter) {
+    return seam === '23'
+        ? pairAt(seam, boundary23_T_to_P(parameter), parameter)
+        : pairAt(seam, parameter, seam === '13' ? C.R2_T_MIN : C.R2_T_MAX);
+}
+function hsSeamDomains() {
+    if (hsDomains !== undefined)
+        return hsDomains;
+    hsDomains = ['13', '23', '25'].map((seam) => {
+        const lower = seam === '25' ? C.P_MIN : seam === '13'
+            ? nextPositiveFloat(saturationPressure(C.R2_T_MIN), 1) : b23LowerTemperature();
+        const upper = seam === '25' ? C.R5_P_MAX : seam === '13'
+            ? C.P_MAX : nativeB23TemperatureBracket(C.P_MAX)[0];
+        const nodes = [lower, upper];
+        {
+            // Partition both equations at their folds before inverting either property.
+            for (const side of ['lower', 'upper']) {
+                for (const propertyIndex of [0, 1]) {
+                    let previous = lower;
+                    const first = pairAtParameter(seam, previous);
+                    let previousDerivative = tangent(first, first[side])[propertyIndex];
+                    for (let i = 1; i <= 16; i++) {
+                        const current = lower + (upper - lower) * i / 16;
+                        const pair = pairAtParameter(seam, current);
+                        const currentDerivative = tangent(pair, pair[side])[propertyIndex];
+                        if (previousDerivative * currentDerivative < 0) {
+                            nodes.push(bracketedNewton((q) => {
+                                const at = pairAtParameter(seam, q);
+                                return tangent(at, at[side])[propertyIndex];
+                            }, previous, current, undefined, { tolerance: 1e-13 }));
+                        }
+                        previous = current;
+                        previousDerivative = currentDerivative;
+                    }
+                }
+            }
+        }
+        nodes.sort((a, b) => a - b);
+        const states = nodes.flatMap((q) => {
+            const pair = pairAtParameter(seam, q);
+            return [pair.lower, pair.upper];
+        });
+        return {
+            seam, nodes,
+            minimumEntropy: Math.min(...states.map((state) => state.entropy)),
+            maximumEntropy: Math.max(...states.map((state) => state.entropy)),
+            minimumEnthalpy: Math.min(...states.map((state) => state.enthalpy)),
+            maximumEnthalpy: Math.max(...states.map((state) => state.enthalpy)),
+        };
+    });
+    return hsDomains;
+}
+/** Locate both constraints on one bounded ribbon between independently fitted EOS. */
+export function findHSSeam(h, s) {
+    if (!Number.isFinite(h) || !Number.isFinite(s))
+        return null;
+    const corner = region2(C.P_MAX, C.B23_T_MAX);
+    if (h === corner.enthalpy && s === corner.entropy) {
+        return resolution({ ...formulationSeamAtPressure(C.P_MAX, '23'), canonical: corner }, 'canonical');
+    }
+    for (const domain of hsSeamDomains()) {
+        const entropyNoise = numericalAllowance(s);
+        const enthalpyNoise = numericalAllowance(h);
+        if (h < domain.minimumEnthalpy - enthalpyNoise || h > domain.maximumEnthalpy + enthalpyNoise)
+            continue;
+        if (s < domain.minimumEntropy - entropyNoise || s > domain.maximumEntropy + entropyNoise)
+            continue;
+        const cache = new Map();
+        const at = (q) => {
+            let pair = cache.get(q);
+            if (pair === undefined) {
+                pair = pairAtParameter(domain.seam, q);
+                cache.set(q, pair);
+            }
+            return pair;
+        };
+        const bounds = [...domain.nodes];
+        for (let i = 1; i < domain.nodes.length; i++) {
+            const lower = domain.nodes[i - 1];
+            const upper = domain.nodes[i];
+            for (const side of ['lower', 'upper']) {
+                const first = at(lower)[side].entropy - s;
+                const last = at(upper)[side].entropy - s;
+                if (first * last < 0) {
+                    bounds.push(bracketedNewton((q) => at(q)[side].entropy - s, lower, upper, undefined, {
+                        derivative: (q) => { const pair = at(q); return tangent(pair, pair[side])[1]; },
+                        tolerance: 1e-13,
+                    }));
+                }
+            }
+        }
+        bounds.sort((a, b) => a - b);
+        const hScale = Math.max(1, Math.abs(h));
+        const sScale = Math.max(1, Math.abs(s));
+        const crossResidual = (q) => {
+            const pair = at(q);
+            const dh = (pair.upper.enthalpy - pair.lower.enthalpy) / hScale;
+            const ds = (pair.upper.entropy - pair.lower.entropy) / sScale;
+            const length = Math.hypot(dh, ds);
+            return length === 0 ? (pair.lower.entropy - s) / sScale
+                : ((h - pair.lower.enthalpy) / hScale * ds - (s - pair.lower.entropy) / sScale * dh) / length;
+        };
+        const matchAt = (q) => {
+            const pair = at(q);
+            const dh = pair.upper.enthalpy - pair.lower.enthalpy;
+            const ds = pair.upper.entropy - pair.lower.entropy;
+            const scaledH = dh / hScale;
+            const scaledS = ds / sScale;
+            const squareLength = scaledH * scaledH + scaledS * scaledS;
+            const fraction = squareLength === 0 ? 0 : Math.max(0, Math.min(1, (((h - pair.lower.enthalpy) / hScale) * scaledH +
+                ((s - pair.lower.entropy) / sScale) * scaledS) / squareLength));
+            // Region 3 density inversion introduces cancellation beyond machine-noise in h/s.
+            if (Math.abs(pair.lower.enthalpy + fraction * dh - h) > 1e-9 ||
+                Math.abs(pair.lower.entropy + fraction * ds - s) > 1e-12)
+                return null;
+            if (Math.abs(pair.canonical.enthalpy - h) <= numericalAllowance(h) &&
+                Math.abs(pair.canonical.entropy - s) <= numericalAllowance(s))
+                return resolution(pair, 'canonical');
+            const direction = tangent(pair, pair.lower);
+            return resolution(pair, direction[0] * ds - direction[1] * dh > 0 ? 'gap' : 'overlap', true);
+        };
+        for (let i = 0; i < bounds.length; i++) {
+            const exact = matchAt(bounds[i]);
+            if (exact !== null)
+                return exact;
+            if (i === 0 || bounds[i] === bounds[i - 1])
+                continue;
+            const lower = bounds[i - 1];
+            const upper = bounds[i];
+            const middle = at((lower + upper) / 2);
+            if (s < Math.min(middle.lower.entropy, middle.upper.entropy) - entropyNoise ||
+                s > Math.max(middle.lower.entropy, middle.upper.entropy) + entropyNoise)
+                continue;
+            if (crossResidual(lower) * crossResidual(upper) >= 0)
+                continue;
+            const root = bracketedNewton(crossResidual, lower, upper, undefined, { tolerance: 4 * Number.EPSILON });
+            const match = matchAt(root);
+            if (match !== null)
+                return match;
+        }
+    }
+    return null;
+}

package/dist/core/input-validation.d.ts

@@ -1 +1,2 @@
 export declare function assertFiniteNumber(parameter: string, value: unknown): asserts value is number;
+export declare function withinClosedLowerBound(value: number, boundary: number, property: 'enthalpy' | 'entropy'): boolean;

package/dist/core/input-validation.js

@@ -4,3 +4,8 @@ export function assertFiniteNumber(parameter, value) {
         throw new IF97Error(`${parameter} must be a finite number`);
     }
 }
+// shortcut: EOS cancellation floors are empirical; remeasure if the EOS evaluation changes.
+export function withinClosedLowerBound(value, boundary, property) {
+    const floor = property === 'enthalpy' ? 1e-12 : 1e-14;
+    return value >= boundary - Math.max(floor, 8 * Number.EPSILON * Math.max(1, Math.abs(boundary)));
+}

package/dist/core/region-detector.d.ts

@@ -4,43 +4,6 @@ import { Region } from '../types.js';
  * @returns Region number (1–5) or -1 if out of range
  */
 export declare function detectRegionPT(p: number, T: number): Region | -1;
-/**
- * Detect region for P-H inputs.
- */
-export declare function detectRegionPH(p: number, h: number): Region | -1;
-/**
- * Detect region for P-S inputs.
- */
-export declare function detectRegionPS(p: number, s: number): Region | -1;
-/**
- * Detect the IAPWS-IF97 region for given T and H.
- *
- * Uses explicit enthalpy comparisons (including saturation-boundary proximity
- * checks via `isClose`) rather than the generic helper, because enthalpy is
- * not monotonic across regions at some temperatures.
- *
- * @param T - Temperature [K]
- * @param h - Specific enthalpy [kJ/kg]
- * @returns Region number (1–5) or -1 if out of range
- */
-export declare function detectRegionTH(T: number, h: number): Region | -1;
-/**
- * Detect the IAPWS-IF97 region for given T and S.
- *
- * Delegates to the generic temperature-property detector since entropy
- * is monotonic across regions at fixed temperature.
- *
- * @param T - Temperature [K]
- * @param s - Specific entropy [kJ/(kg·K)]
- * @returns Region number (1–5) or -1 if out of range
- */
-export declare function detectRegionTS(T: number, s: number): 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;
+export declare function nativeSaturationTemperatureBracket(p: number): readonly [number, number];
+/** Invert the native B23 boundary; rounded Eq. (6) cannot determine PT ownership. */
+export declare function nativeB23TemperatureBracket(p: number): readonly [number, number];