iapws-if97 2.1.5 → 2.8.0

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

@@ -5,21 +5,21 @@
  * (enthalpy or entropy) using a bracketed Newton method.
  */
 import type { BasicProperties } from '../types.js';
-type PropertyExtractor = (state: BasicProperties) => number;
+/** Property being inverted against pressure at fixed temperature. */
+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.
+ * 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]
  * @param target     - Target property value (enthalpy or entropy)
  * @param lower      - Lower pressure bracket [MPa]
  * @param upper      - Upper pressure bracket [MPa]
- * @param extract    - Function to extract the target property from BasicProperties
+ * @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, extract: PropertyExtractor, solverName: string): BasicProperties;
-export {};
-//# sourceMappingURL=fixed-temperature-solver.d.ts.map
+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,31 +1,78 @@
-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, helmholtzPropertyDerivatives } from '../core/thermodynamic-derivatives.js';
+import { fixedTemperatureRootTolerance } from './tolerances.js';
+function propertyValue(state, property) {
+    return property === 'enthalpy' ? state.enthalpy : state.entropy;
+}
+/**
+ * (∂h/∂p)_T = 1000·v(1 − Tα) or (∂s/∂p)_T = −1000·v·α, both per MPa.
+ *
+ * These are Maxwell-relation identities, so they hold for the Helmholtz-based
+ * Region 3 states as well as the Gibbs-based regions. Returns NaN when a state
+ * carries no cp/α, which makes the caller fall back to a bisection step.
+ */
+function pressureDerivative(state, property) {
+    const derivatives = gibbsPropertyDerivatives(state);
+    return property === 'enthalpy' ? derivatives.dhDp : derivatives.dsDp;
+}
 /**
  * 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.
+ * 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]
  * @param target     - Target property value (enthalpy or entropy)
  * @param lower      - Lower pressure bracket [MPa]
  * @param upper      - Upper pressure bracket [MPa]
- * @param extract    - Function to extract the target property from BasicProperties
+ * @param property   - Which property `target` represents
  * @param solverName - Label used in error messages
  */
-export function solveFixedTemperaturePressure(evaluator, T, target, lower, upper, extract, solverName) {
+export function solveFixedTemperaturePressure(evaluator, T, target, lower, upper, property, solverName, includeLower = true, includeUpper = true) {
     const lowerState = evaluator(lower, T);
     const upperState = evaluator(upper, T);
-    if (Math.abs(extract(lowerState) - target) <= 1e-9)
+    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 cachedInput = Number.NaN;
+    let cachedState = null;
+    const stateAt = (input) => {
+        if (input !== cachedInput || cachedState === null) {
+            cachedInput = input;
+            cachedState = useDensity ? region3ByRhoT(input, T) : evaluator(input, T);
+        }
+        return cachedState;
+    };
+    const rootTolerance = fixedTemperatureRootTolerance(property);
+    if (includeLower && Math.abs(propertyValue(lowerState, property) - target) <= rootTolerance)
         return lowerState;
-    if (Math.abs(extract(upperState) - target) <= 1e-9)
+    if (includeUpper && Math.abs(propertyValue(upperState, property) - target) <= rootTolerance)
         return upperState;
-    const pressure = bracketedNewton((p) => extract(evaluator(p, T)) - target, lower, upper, (lower + upper) / 2);
-    const state = evaluator(pressure, T);
+    // 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`);
     }
     return state;
 }
-//# sourceMappingURL=fixed-temperature-solver.js.map

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;