iapws-if97 2.2.0 → 2.8.0

package/dist/backward/ph.js

@@ -7,18 +7,20 @@
  * Reference: IAPWS-IF97 Supplementary Release on Backward Equations
  */
 import { Region, IF97Error, OutOfRangeError } from '../types.js';
+import { SaturationEndpointError } from '../errors.js';
 import * as C from '../constants.js';
 import { region1 } from '../regions/region1.js';
 import { region2 } from '../regions/region2.js';
-import { region3ByRhoT } from '../regions/region3.js';
+import { region3ByRhoT, region3PressureResidual } from '../regions/region3.js';
 import { region5 } from '../regions/region5.js';
 import { saturationTemperature } from '../regions/region4.js';
-import { assertFiniteNumber } from '../core/input-validation.js';
-import { detectRegionPH } from '../core/region-detector.js';
+import { assertFiniteNumber, withinClosedLowerBound } from '../core/input-validation.js';
+import { assertPressurePropertyEnvelope, detectRegionPH, pressurePropertyBoundaryState, pressurePropertySeam } from './pressure-property-region.js';
 import { newtonRaphson } from '../solvers/newton-raphson.js';
+import { bracketedNewton } from '../solvers/bracketed-newton.js';
 import { dampedNewton2D } from '../solvers/damped-newton-2d.js';
-import { validateBackwardState } from './solution-validation.js';
-import { helmholtzPropertyDerivatives } from './thermodynamic-derivatives.js';
+import { validateBackwardState, validateRegion3PTReconstruction } from './solution-validation.js';
+import { helmholtzPropertyDerivatives } from '../core/thermodynamic-derivatives.js';
 import { mixSaturationState, qualityFromSaturationProperty, saturationEndpointsAtPressure, } from '../saturation/common.js';
 import { assertCriticalRegion4PHInput, assertRegion4StateAllowed, } from '../saturation/region4-boundaries.js';
 // ─── Backward Polynomial Evaluator ─────────────────────────────────────────
@@ -60,7 +62,7 @@ const R2A_PH = [
     [2, 2, -0.31078046629583], [2, 7, 11.670873077107], [2, 36, 128127984.04046], [2, 38, -985549096.23276],
     [2, 40, 2822454697.3002], [2, 42, -3594897141.0703], [2, 44, 1722734991.3197], [3, 24, -13551.334240775],
     [3, 44, 12848734.66465], [4, 12, 1.3865724283226], [4, 32, 235988.32556514], [4, 44, -13105236.545054],
-    [5, 32, 7399.9835474766], [5, 36, -551966.9703006], [5, 42, 3715408.5996233], [6, 34, 19127.7292396],
+    [5, 32, 7399.9835474766], [5, 36, -551966.9703006], [5, 42, 3715408.5996233], [6, 34, 19127.729239660],
     [6, 44, -415351.64835634], [7, 28, -62.459855192507],
 ];
 function r2aBackwardT(p, h) {
@@ -119,7 +121,7 @@ export function r2BackwardT(p, h) {
 }
 // ─── Region 3 Backward T(P,H) and v(P,H) ──────────────────────────────────
 /** B3ab boundary: P → H */
-function b3ab_P_to_H(p) {
+export function b3ab_P_to_H(p) {
     return 2014.64004206875 + 3.74696550136983 * p - 0.0219921901054187 * p * p + 0.000087513168600995 * p * p * p;
 }
 const R3A_PH_T = [
@@ -183,15 +185,16 @@ export function r3BackwardPHInitial(p, h) {
     const v = 0.0088 * evalPoly(R3B_PH_V, -0.0661, 0.720, p / 100, h / 2800);
     return { rho: 1 / v, T };
 }
-function solveRegion3PH(p, h, rho0, T0) {
-    const pScale = Math.max(1, Math.abs(p));
+function solveRegion3PH(p, h, rho0, T0, refinePressure = false) {
+    // Scaling the 1e-13 solver tolerance by 1e-4 resolves pressure below one ULP before PT reconstruction.
+    const pScale = Math.max(1, Math.abs(p)) * (refinePressure ? 1e-4 : 1);
     const hScale = Math.max(1, Math.abs(h));
     const [rho, T] = dampedNewton2D(([candidateRho, candidateT]) => {
         const state = region3ByRhoT(candidateRho, candidateT);
         const derivatives = helmholtzPropertyDerivatives(state, candidateRho);
         return {
             residual: [
-                (state.pressure - p) / pScale,
+                (refinePressure ? region3PressureResidual(candidateRho, candidateT, p) : state.pressure - p) / pScale,
                 (state.enthalpy - h) / hScale,
             ],
             jacobian: [
@@ -200,6 +203,8 @@ function solveRegion3PH(p, h, rho0, T0) {
             ],
         };
     }, [rho0, T0], {
+        // Near critical pressure, the default residual can cross a stability boundary.
+        tolerance: 1e-13,
         isValid: ([candidateRho, candidateT]) => candidateRho > 0 && candidateT > 0,
     });
     return region3ByRhoT(rho, T);
@@ -216,11 +221,35 @@ export function solvePH(p, h) {
     if (p < C.P_MIN || p > C.P_MAX) {
         throw new OutOfRangeError('Pressure', p, C.P_MIN, C.P_MAX);
     }
-    if (h < C.H_MIN || h > C.H_MAX) {
+    if (!withinClosedLowerBound(h, C.H_MIN, 'enthalpy') || h > C.H_MAX) {
         throw new OutOfRangeError('Enthalpy', h, C.H_MIN, C.H_MAX);
     }
     assertCriticalRegion4PHInput(p, h, 'solvePH');
-    const region = detectRegionPH(p, h);
+    assertPressurePropertyEnvelope(p, h, 'enthalpy');
+    const seam = pressurePropertySeam(p, h, 'enthalpy');
+    if (seam !== null && seam.kind !== 'overlap') {
+        return validateBackwardState(seam.state, [
+            { label: 'pressure', expected: p },
+            { label: 'enthalpy', expected: h },
+        ], { solverName: 'solvePH', expectedRegion: seam.state.region, seam });
+    }
+    if (seam === null) {
+        const boundary = pressurePropertyBoundaryState(p, h, 'enthalpy');
+        if (boundary !== null)
+            return boundary;
+    }
+    let region;
+    let saturationFailure = null;
+    try {
+        region = seam?.state.region ?? detectRegionPH(p, h);
+    }
+    catch (error) {
+        if (!(error instanceof SaturationEndpointError)) {
+            throw error;
+        }
+        saturationFailure = error;
+        region = Region.Region3;
+    }
     switch (region) {
         case Region.Region1: {
             const T0 = r1BackwardT(p, h);
@@ -231,21 +260,42 @@ export function solvePH(p, h) {
             ], { solverName: 'solvePH', expectedRegion: Region.Region1 });
         }
         case Region.Region2: {
+            const targetH = Math.min(h, region2(p, C.R2_T_MAX).enthalpy);
             const T0 = r2BackwardT(p, h);
-            const T = newtonRaphson((T_x) => region2(p, T_x).enthalpy - h, T0, (T_x) => region2(p, T_x).cp ?? Number.NaN);
+            const T = newtonRaphson((T_x) => region2(p, T_x).enthalpy - targetH, T0, (T_x) => region2(p, T_x).cp ?? Number.NaN);
             return validateBackwardState(region2(p, T), [
                 { label: 'pressure', expected: p },
                 { label: 'enthalpy', expected: h },
             ], { solverName: 'solvePH', expectedRegion: Region.Region2 });
         }
         case Region.Region3: {
-            const pressureTolerance = 1e-5 * Math.max(1, Math.abs(p));
-            const initial = r3BackwardPHInitial(p, h);
-            const state = solveRegion3PH(p, h, initial.rho, initial.T);
-            return validateBackwardState(state, [
-                { label: 'pressure', expected: p, tolerance: pressureTolerance },
-                { label: 'enthalpy', expected: h },
-            ], { solverName: 'solvePH', expectedRegion: Region.Region3 });
+            try {
+                const initial = r3BackwardPHInitial(p, h);
+                const validate = (state) => validateBackwardState(state, [
+                    { label: 'pressure', expected: p },
+                    { label: 'enthalpy', expected: h },
+                ], { solverName: 'solvePH', expectedRegion: Region.Region3 });
+                const validated = validate(solveRegion3PH(p, h, initial.rho, initial.T));
+                // Compressibility can amplify an accepted pressure residual beyond PT's density accuracy.
+                const relativeDensityError = Math.abs(region3PressureResidual(1 / validated.specificVolume, validated.temperature, p)) * validated.isothermalCompressibility;
+                if (saturationFailure === null && relativeDensityError <= 1e-12)
+                    return validated;
+                try {
+                    const refined = validate(solveRegion3PH(p, h, 1 / validated.specificVolume, validated.temperature, true));
+                    validateRegion3PTReconstruction(refined, 'solvePH');
+                    return refined;
+                }
+                catch (error) {
+                    if (!(error instanceof IF97Error))
+                        throw error;
+                    return saturationFailure === null ? validated : validateRegion3PTReconstruction(validated, 'solvePH');
+                }
+            }
+            catch (error) {
+                if (saturationFailure !== null && error instanceof IF97Error)
+                    throw saturationFailure;
+                throw error;
+            }
         }
         case Region.Region4: {
             const endpoints = saturationEndpointsAtPressure(p);
@@ -257,7 +307,8 @@ export function solvePH(p, h) {
             ], { solverName: 'solvePH', expectedRegion: Region.Region4 });
         }
         case Region.Region5: {
-            const T = newtonRaphson((T_x) => region5(p, T_x).enthalpy - h, 1500, (T_x) => region5(p, T_x).cp ?? Number.NaN);
+            const targetH = Math.min(h, region5(p, C.R5_T_MAX).enthalpy);
+            const T = bracketedNewton((T_x) => region5(p, T_x).enthalpy - targetH, C.R5_T_MIN + Number.EPSILON * C.R5_T_MIN, C.R5_T_MAX, 1500, { derivative: (T_x) => region5(p, T_x).cp ?? Number.NaN, tolerance: 1e-12 });
             return validateBackwardState(region5(p, T), [
                 { label: 'pressure', expected: p },
                 { label: 'enthalpy', expected: h },

package/dist/backward/pressure-property-region.d.ts

@@ -0,0 +1,13 @@
+import { Region } from '../types.js';
+import type { BasicProperties } from '../types.js';
+import { type FormulationSeamResolution } from '../core/formulation-seams.js';
+/** Resolve the native saturation/B23 intersection before choosing one inverse region. */
+export declare function pressurePropertyBoundaryState(p: number, target: number, property: 'enthalpy' | 'entropy'): BasicProperties | null;
+/** Reject proven fixed-pressure envelope violations without classifying interior gaps. */
+export declare function assertPressurePropertyEnvelope(p: number, target: number, property: 'enthalpy' | 'entropy'): void;
+/** Share the fixed-pressure seam policy between detectors and backward solvers. */
+export declare function pressurePropertySeam(p: number, target: number, property: 'enthalpy' | 'entropy'): FormulationSeamResolution | null;
+/** 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;

package/dist/backward/pressure-property-region.js

@@ -0,0 +1,262 @@
+import * as C from '../constants.js';
+import { SaturationEndpointError } from '../errors.js';
+import { region1 } from '../regions/region1.js';
+import { region2 } from '../regions/region2.js';
+import { region5 } from '../regions/region5.js';
+import { boundary23_T_to_P } from '../regions/boundaries.js';
+import { saturationPressure } from '../regions/region4.js';
+import { saturationEndpointsAtPressure } from '../saturation/common.js';
+import { OutOfRangeError, Region } from '../types.js';
+import { detectRegionPT, nativeB23TemperatureBracket, nativeSaturationTemperatureBracket } from '../core/region-detector.js';
+import { withinClosedLowerBound } from '../core/input-validation.js';
+import { findPressureSeam } from '../core/formulation-seams.js';
+import { nextPositiveFloat } from '../core/floating-point.js';
+import { solveRegion3PTBasic } from '../core/region3-pt.js';
+import { bracketedNewton } from '../solvers/bracketed-newton.js';
+import { resolveBackwardCandidates } from './candidate-resolution.js';
+import { BACKWARD_PRESSURE_PROPERTY_TEMPERATURE_TOLERANCE } from './tolerances.js';
+const P13 = saturationPressure(C.R2_T_MIN);
+const B23_P_AT_T13 = boundary23_T_to_P(C.R2_T_MIN);
+/** Resolve the native saturation/B23 intersection before choosing one inverse region. */
+export function pressurePropertyBoundaryState(p, target, property) {
+    if (p < C.B23_P_MIN || p > B23_P_AT_T13)
+        return null;
+    const references = [region1(p, C.R2_T_MIN), region2(p, C.R2_T_MIN)];
+    if (!references.some((state) => Math.abs(state[property] - target) <=
+        (property === 'enthalpy' ? 0.2 : 0.0002)))
+        return null;
+    const endpoints = saturationEndpointsAtPressure(p);
+    if (endpoints.liquid[property] <= target && target <= endpoints.vapor[property])
+        return null;
+    const tolerance = 128 * Number.EPSILON * Math.max(1, Math.abs(target));
+    const temperatures = new Set([
+        C.R2_T_MIN,
+        nextPositiveFloat(C.R2_T_MIN, -1),
+        nextPositiveFloat(C.R2_T_MIN, 1),
+        ...nativeSaturationTemperatureBracket(p),
+    ]);
+    const stateAt = (T) => {
+        const region = detectRegionPT(p, T);
+        return region === Region.Region1 ? region1(p, T)
+            : region === Region.Region2 ? region2(p, T)
+                : region === Region.Region3 ? solveRegion3PTBasic(p, T) : null;
+    };
+    return resolveBackwardCandidates([...temperatures].map((T) => () => {
+        const state = stateAt(T);
+        if (state === null)
+            return null;
+        if (Math.abs(state[property] - target) <= tolerance)
+            return state;
+        const slope = property === 'enthalpy' ? state.cp : state.cp / T;
+        const temperature = T + (target - state[property]) / slope;
+        if (detectRegionPT(p, temperature) !== state.region)
+            return null;
+        const corrected = stateAt(temperature);
+        return corrected !== null && Math.abs(corrected[property] - target) <= tolerance ? corrected : null;
+    }), [
+        { label: 'pressure', expected: p, tolerance: 0 },
+        { label: property, expected: target, tolerance },
+    ], { solverName: property === 'enthalpy' ? 'solvePH' : 'solvePS' });
+}
+/** Reject proven fixed-pressure envelope violations without classifying interior gaps. */
+export function assertPressurePropertyEnvelope(p, target, property) {
+    const minimum = region1(p, C.T_MIN)[property];
+    const maximum = (p <= C.R5_P_MAX ? region5(p, C.R5_T_MAX) : region2(p, C.R2_T_MAX))[property];
+    const aboveMinimum = property === 'enthalpy'
+        ? target >= minimum || isClose(target, minimum)
+        : withinClosedLowerBound(target, minimum, 'entropy');
+    if (!aboveMinimum || !withinClosedUpperBound(target, maximum)) {
+        throw new OutOfRangeError(`${property === 'enthalpy' ? 'Enthalpy' : 'Entropy'} at p=${p} MPa`, target, minimum, maximum);
+    }
+}
+/** Share the fixed-pressure seam policy between detectors and backward solvers. */
+export function pressurePropertySeam(p, target, property) {
+    const match = findPressureSeam(p, target, property);
+    if (match === null)
+        return null;
+    if (p >= C.Pt && p < C.Pc) {
+        try {
+            const endpoints = saturationEndpointsAtPressure(p);
+            if (target >= endpoints.liquid[property] && target <= endpoints.vapor[property])
+                return null;
+        }
+        catch (error) {
+            if (!(error instanceof SaturationEndpointError))
+                throw error;
+        }
+    }
+    const solverName = property === 'enthalpy' ? 'solvePH' : 'solvePS';
+    const constraints = [{ label: 'pressure', expected: p }, { label: property, expected: target }];
+    const state = resolveBackwardCandidates([
+        () => match.state[property] === target ? match.state : null,
+        () => pressureSeamRoot(p, target, property, match, match.pair.lower.region),
+        () => pressureSeamRoot(p, target, property, match, match.pair.upper.region),
+    ], constraints, { solverName, seam: match });
+    const resolved = state ?? (match.kind === 'canonical'
+        ? resolveBackwardCandidates([() => match.state], constraints, { solverName }) : null);
+    return resolved === null ? null : resolved === match.state ? match : { ...match, kind: 'canonical', state: resolved };
+}
+function pressureSeamRoot(p, target, property, seam, region) {
+    let lower;
+    let upper;
+    let evaluate;
+    if (region === Region.Region1) {
+        lower = C.T_MIN;
+        upper = C.R2_T_MIN;
+        evaluate = (T) => region1(p, T);
+    }
+    else if (region === Region.Region2) {
+        lower = p > C.B23_P_MIN ? nativeB23TemperatureBracket(p)[1] : C.T_MIN;
+        if (p < C.Pc)
+            lower = Math.max(lower, nativeSaturationTemperatureBracket(p)[1]);
+        upper = C.R2_T_MAX;
+        evaluate = (T) => region2(p, T);
+    }
+    else if (region === Region.Region3) {
+        lower = nextPositiveFloat(C.R2_T_MIN, 1);
+        upper = nativeB23TemperatureBracket(p)[0];
+        if (p < C.Pc) {
+            const [liquidT, vaporT] = nativeSaturationTemperatureBracket(p);
+            if (seam.pair.seam === '13')
+                upper = Math.min(upper, liquidT);
+            else
+                lower = Math.max(lower, vaporT);
+        }
+        evaluate = (T) => solveRegion3PTBasic(p, T);
+    }
+    else if (region === Region.Region5) {
+        lower = nextPositiveFloat(C.R5_T_MIN, 1);
+        upper = C.R5_T_MAX;
+        evaluate = (T) => region5(p, T);
+    }
+    else {
+        return null;
+    }
+    if (lower > upper)
+        return null;
+    const direction = region === seam.pair.lower.region ? -1 : 1;
+    const boundary = direction < 0 ? upper : lower;
+    const first = evaluate(boundary);
+    if (direction * (target - first[property]) < 0)
+        return null;
+    if (target === first[property])
+        return first;
+    if (lower === upper)
+        return null;
+    const slope = property === 'enthalpy' ? first.cp : first.cp / boundary;
+    let distance = Math.abs(target - first[property]) / slope;
+    let bracket;
+    while (true) {
+        bracket = Math.max(lower, Math.min(upper, boundary + direction * distance));
+        if (bracket === boundary)
+            bracket = nextPositiveFloat(boundary, direction);
+        const last = evaluate(bracket);
+        if (direction * (last[property] - target) >= 0)
+            break;
+        if (bracket === lower || bracket === upper)
+            return null;
+        distance *= 2;
+    }
+    lower = Math.min(boundary, bracket);
+    upper = Math.max(boundary, bracket);
+    const temperature = bracketedNewton((T) => evaluate(T)[property] - target, lower, upper, undefined, {
+        derivative: (T) => {
+            const state = evaluate(T);
+            return property === 'enthalpy' ? state.cp : state.cp / T;
+        },
+        tolerance: BACKWARD_PRESSURE_PROPERTY_TEMPERATURE_TOLERANCE,
+        residualTolerance: 0,
+    });
+    return evaluate(temperature);
+}
+/** Detect region for P-H inputs. */
+export function detectRegionPH(p, h) {
+    return detectRegionPressureProperty(p, h, 'enthalpy');
+}
+/** Detect region for P-S inputs. */
+export function detectRegionPS(p, s) {
+    return detectRegionPressureProperty(p, s, 'entropy');
+}
+function detectRegionPressureProperty(p, target, property) {
+    if (!Number.isFinite(p) || !Number.isFinite(target))
+        return -1;
+    const seam = pressurePropertySeam(p, target, property);
+    if (seam !== null)
+        return seam.state.region;
+    const boundary = pressurePropertyBoundaryState(p, target, property);
+    if (boundary !== null)
+        return boundary.region;
+    // Preserve PH's existing lower-bound tolerance; PS absorbs EOS rounding noise.
+    const aboveMinimum = (minimum) => property === 'enthalpy'
+        ? minimum <= target || isClose(target, minimum)
+        : withinClosedLowerBound(target, minimum, 'entropy');
+    if (p >= C.P_MIN && p <= P13) {
+        const endpoints = p >= C.Pt ? saturationEndpointsAtPressure(p) : null;
+        if (endpoints !== null && endpoints.liquid[property] <= target && target <= endpoints.vapor[property]) {
+            return Region.Region4;
+        }
+        const [liquidT, vaporT] = endpoints === null ? nativeSaturationTemperatureBracket(p)
+            : [endpoints.temperature, endpoints.temperature];
+        const lower = region1(p, C.T_MIN)[property];
+        const boundary14 = endpoints?.liquid[property] ?? region1(p, liquidT)[property];
+        const boundary24 = endpoints?.vapor[property] ?? region2(p, vaporT)[property];
+        const boundary25 = region2(p, C.R2_T_MAX)[property];
+        if (aboveMinimum(lower) && target <= boundary14)
+            return Region.Region1;
+        if (withinClosedLowerBound(target, boundary24, property) && withinClosedUpperBound(target, boundary25))
+            return Region.Region2;
+        if (p <= C.R5_P_MAX && region5(p, C.R5_T_MIN)[property] < target &&
+            withinClosedUpperBound(target, region5(p, C.R5_T_MAX)[property]))
+            return Region.Region5;
+    }
+    else if (p > P13 && p <= C.P_MAX) {
+        const lower = region1(p, C.T_MIN)[property];
+        const boundary13 = region1(p, C.R2_T_MIN)[property];
+        const [, region2T] = nativeB23TemperatureBracket(p);
+        const boundary32 = region2(p, region2T)[property];
+        const boundary25 = region2(p, C.R2_T_MAX)[property];
+        if (p < C.Pc) {
+            try {
+                const endpoints = saturationEndpointsAtPressure(p);
+                if (endpoints.liquid[property] <= target && target <= endpoints.vapor[property]) {
+                    return Region.Region4;
+                }
+            }
+            catch (error) {
+                if (!(error instanceof SaturationEndpointError) ||
+                    (target > boundary13 && target < boundary32))
+                    throw error;
+            }
+        }
+        if (aboveMinimum(lower) && target <= boundary13)
+            return Region.Region1;
+        if (withinClosedLowerBound(target, boundary32, property) && withinClosedUpperBound(target, boundary25))
+            return Region.Region2;
+        if (p <= C.R5_P_MAX && region5(p, C.R5_T_MIN)[property] < target &&
+            withinClosedUpperBound(target, region5(p, C.R5_T_MAX)[property]))
+            return Region.Region5;
+        if (p < C.Pc) {
+            const endpoints = saturationEndpointsAtPressure(p);
+            const liquid = endpoints.liquid[property];
+            const vapor = endpoints.vapor[property];
+            if (boundary13 < target && target < liquid)
+                return Region.Region3;
+            if (liquid < target && target < vapor)
+                return Region.Region4;
+            if (vapor < target && target < boundary32)
+                return Region.Region3;
+        }
+        else if (boundary13 < target && target < boundary32) {
+            return Region.Region3;
+        }
+    }
+    return -1;
+}
+// Accept floating-point residue only at closed upper bounds.
+function withinClosedUpperBound(value, boundary) {
+    return value <= boundary + 8 * Number.EPSILON * Math.max(1, Math.abs(boundary));
+}
+/** Check approximate equality with relative tolerance. */
+function isClose(a, b) {
+    return Math.abs(a - b) <= 1e-9 * Math.max(1, Math.abs(a), Math.abs(b));
+}

package/dist/backward/ps.d.ts

@@ -4,6 +4,12 @@
  * Reference: IAPWS-IF97 Supplementary Release on Backward Equations
  */
 import type { BasicProperties } from '../types.js';
+export declare function r1BackwardT(p: number, s: number): number;
+export declare function r2BackwardT(p: number, s: number): number;
+export declare function r3BackwardPSInitial(p: number, s: number): {
+    rho: number;
+    T: number;
+};
 /**
  * Solve for thermodynamic state given P and S.
  * @param p - Pressure [MPa]

package/dist/backward/ps.js

@@ -4,17 +4,19 @@
  * Reference: IAPWS-IF97 Supplementary Release on Backward Equations
  */
 import { Region, IF97Error, OutOfRangeError } from '../types.js';
+import { SaturationEndpointError } from '../errors.js';
 import * as C from '../constants.js';
 import { region1 } from '../regions/region1.js';
 import { region2 } from '../regions/region2.js';
-import { region3ByRhoT } from '../regions/region3.js';
+import { region3ByRhoT, region3PressureResidual } from '../regions/region3.js';
 import { region5 } from '../regions/region5.js';
-import { assertFiniteNumber } from '../core/input-validation.js';
-import { detectRegionPS } from '../core/region-detector.js';
+import { assertFiniteNumber, withinClosedLowerBound } from '../core/input-validation.js';
+import { assertPressurePropertyEnvelope, detectRegionPS, pressurePropertyBoundaryState, pressurePropertySeam } from './pressure-property-region.js';
 import { newtonRaphson } from '../solvers/newton-raphson.js';
+import { bracketedNewton } from '../solvers/bracketed-newton.js';
 import { dampedNewton2D } from '../solvers/damped-newton-2d.js';
-import { validateBackwardState } from './solution-validation.js';
-import { helmholtzPropertyDerivatives } from './thermodynamic-derivatives.js';
+import { validateBackwardState, validateRegion3PTReconstruction } from './solution-validation.js';
+import { helmholtzPropertyDerivatives } from '../core/thermodynamic-derivatives.js';
 import { mixSaturationState, qualityFromSaturationProperty, saturationEndpointsAtPressure, } from '../saturation/common.js';
 import { assertCriticalRegion4PSInput, assertRegion4StateAllowed, } from '../saturation/region4-boundaries.js';
 function evalPoly(table, piShift, sigShift, pi, sig) {
@@ -33,7 +35,7 @@ const R1_PS = [
     [2, 31, -4.2522657042207e-26], [3, 10, 2.6400441360689e-13], [3, 32, 7.8124600459723e-29],
     [4, 32, -3.0732199903668e-31],
 ];
-function r1BackwardT(p, s) {
+export function r1BackwardT(p, s) {
     return evalPoly(R1_PS, 0, -2, p, s);
 }
 // ─── Region 2 Backward T(P,S) — Subregions 2a/2b/2c ───────────────────────
@@ -41,7 +43,7 @@ const R2A_PS = [
     [-1.5, -24, -392359.83861984], [-1.5, -23, 515265.7382727], [-1.5, -19, 40482.443161048],
     [-1.5, -13, -321.93790923902], [-1.5, -11, 96.961424218694], [-1.5, -10, -22.867846371773],
     [-1.25, -19, -449429.14124357], [-1.25, -15, -5011.8336020166], [-1.25, -6, 0.35684463560015],
-    [-1, -26, 44235.33584819], [-1, -21, -13673.388811708], [-1, -17, 421632.6027864],
+    [-1, -26, 44235.33584819], [-1, -21, -13673.388811708], [-1, -17, 421632.60207864],
     [-1, -16, 22516.925837475], [-1, -9, 474.42144865646], [-1, -8, -149.31130797647],
     [-0.75, -15, -197811.26320452], [-0.75, -14, -23554.39947076], [-0.5, -26, -19070.616302076],
     [-0.5, -13, 55375.669883164], [-0.5, -9, 3829.3691437363], [-0.5, -7, -603.91860580567],
@@ -84,7 +86,7 @@ const R2C_PS = [
     [6, 1, 1.0136618529763e-8], [7, 0, 5.9925719692351e-12], [7, 1, -2.0677870105164e-11],
     [7, 3, -2.0874278181886e-11], [7, 4, 1.0162166825089e-10], [7, 5, -1.6429828281347e-10],
 ];
-function r2BackwardT(p, s) {
+export function r2BackwardT(p, s) {
     if (p <= C.R2_P_CRT) {
         return evalPoly(R2A_PS, 0, 2, p, s / 2);
     }
@@ -144,15 +146,26 @@ const R3B_PS_V_TABLE = [
     [0, 2, -19.1449143716586], [1, 0, -0.0150448002905284], [1, 2, 14.6407900162154],
     [2, 2, -3.2747778718823],
 ];
-function solveRegion3PS(p, s, rho0, T0) {
-    const pScale = Math.max(1, Math.abs(p));
+export function r3BackwardPSInitial(p, s) {
+    if (s <= C.R3_S_CRT) {
+        const T = 760 * evalPoly(R3A_PS_T_TABLE, -0.240, 0.703, p / 100, s / 4.4);
+        const v = 0.0028 * evalPoly(R3A_PS_V_TABLE, -0.187, 0.755, p / 100, s / 4.4);
+        return { rho: 1 / v, T };
+    }
+    const T = 860 * evalPoly(R3B_PS_T_TABLE, -0.760, 0.818, p / 100, s / 5.3);
+    const v = 0.0088 * evalPoly(R3B_PS_V_TABLE, -0.298, 0.816, p / 100, s / 5.3);
+    return { rho: 1 / v, T };
+}
+function solveRegion3PS(p, s, rho0, T0, refinePressure = false) {
+    // Scaling the 1e-13 solver tolerance by 1e-4 resolves pressure below one ULP before PT reconstruction.
+    const pScale = Math.max(1, Math.abs(p)) * (refinePressure ? 1e-4 : 1);
     const sScale = Math.max(1, Math.abs(s));
     const [rho, T] = dampedNewton2D(([candidateRho, candidateT]) => {
         const state = region3ByRhoT(candidateRho, candidateT);
         const derivatives = helmholtzPropertyDerivatives(state, candidateRho);
         return {
             residual: [
-                (state.pressure - p) / pScale,
+                (refinePressure ? region3PressureResidual(candidateRho, candidateT, p) : state.pressure - p) / pScale,
                 (state.entropy - s) / sScale,
             ],
             jacobian: [
@@ -161,6 +174,8 @@ function solveRegion3PS(p, s, rho0, T0) {
             ],
         };
     }, [rho0, T0], {
+        // Near saturation, the default residual can put the liquid root across Tsat.
+        tolerance: 1e-13,
         isValid: ([candidateRho, candidateT]) => candidateRho > 0 && candidateT > 0,
     });
     return region3ByRhoT(rho, T);
@@ -177,11 +192,35 @@ export function solvePS(p, s) {
     if (p < C.P_MIN || p > C.P_MAX) {
         throw new OutOfRangeError('Pressure', p, C.P_MIN, C.P_MAX);
     }
-    if (s < C.S_MIN || s > C.S_MAX) {
+    if (!withinClosedLowerBound(s, C.S_MIN, 'entropy') || s > C.S_MAX) {
         throw new OutOfRangeError('Entropy', s, C.S_MIN, C.S_MAX);
     }
     assertCriticalRegion4PSInput(p, s, 'solvePS');
-    const region = detectRegionPS(p, s);
+    assertPressurePropertyEnvelope(p, s, 'entropy');
+    const seam = pressurePropertySeam(p, s, 'entropy');
+    if (seam !== null && seam.kind !== 'overlap') {
+        return validateBackwardState(seam.state, [
+            { label: 'pressure', expected: p },
+            { label: 'entropy', expected: s },
+        ], { solverName: 'solvePS', expectedRegion: seam.state.region, seam });
+    }
+    if (seam === null) {
+        const boundary = pressurePropertyBoundaryState(p, s, 'entropy');
+        if (boundary !== null)
+            return boundary;
+    }
+    let region;
+    let saturationFailure = null;
+    try {
+        region = seam?.state.region ?? detectRegionPS(p, s);
+    }
+    catch (error) {
+        if (!(error instanceof SaturationEndpointError)) {
+            throw error;
+        }
+        saturationFailure = error;
+        region = Region.Region3;
+    }
     switch (region) {
         case Region.Region1: {
             const T0 = r1BackwardT(p, s);
@@ -192,29 +231,42 @@ export function solvePS(p, s) {
             ], { solverName: 'solvePS', expectedRegion: Region.Region1 });
         }
         case Region.Region2: {
+            const targetS = Math.min(s, region2(p, C.R2_T_MAX).entropy);
             const T0 = r2BackwardT(p, s);
-            const T = newtonRaphson((T_x) => region2(p, T_x).entropy - s, T0, (T_x) => (region2(p, T_x).cp ?? Number.NaN) / T_x);
+            const T = newtonRaphson((T_x) => region2(p, T_x).entropy - targetS, T0, (T_x) => (region2(p, T_x).cp ?? Number.NaN) / T_x);
             return validateBackwardState(region2(p, T), [
                 { label: 'pressure', expected: p },
                 { label: 'entropy', expected: s },
             ], { solverName: 'solvePS', expectedRegion: Region.Region2 });
         }
         case Region.Region3: {
-            const pressureTolerance = 1e-5 * Math.max(1, Math.abs(p));
-            let T0, v0;
-            if (s <= C.R3_S_CRT) {
-                T0 = 760 * evalPoly(R3A_PS_T_TABLE, -0.240, 0.703, p / 100, s / 4.4);
-                v0 = 0.0028 * evalPoly(R3A_PS_V_TABLE, -0.187, 0.755, p / 100, s / 4.4);
+            try {
+                const initial = r3BackwardPSInitial(p, s);
+                const validate = (state) => validateBackwardState(state, [
+                    { label: 'pressure', expected: p },
+                    { label: 'entropy', expected: s },
+                ], { solverName: 'solvePS', expectedRegion: Region.Region3 });
+                const validated = validate(solveRegion3PS(p, s, initial.rho, initial.T));
+                // Compressibility can amplify an accepted pressure residual beyond PT's density accuracy.
+                const relativeDensityError = Math.abs(region3PressureResidual(1 / validated.specificVolume, validated.temperature, p)) * validated.isothermalCompressibility;
+                if (saturationFailure === null && relativeDensityError <= 1e-12)
+                    return validated;
+                try {
+                    const refined = validate(solveRegion3PS(p, s, 1 / validated.specificVolume, validated.temperature, true));
+                    validateRegion3PTReconstruction(refined, 'solvePS');
+                    return refined;
+                }
+                catch (error) {
+                    if (!(error instanceof IF97Error))
+                        throw error;
+                    return saturationFailure === null ? validated : validateRegion3PTReconstruction(validated, 'solvePS');
+                }
             }
-            else {
-                T0 = 860 * evalPoly(R3B_PS_T_TABLE, -0.760, 0.818, p / 100, s / 5.3);
-                v0 = 0.0088 * evalPoly(R3B_PS_V_TABLE, -0.298, 0.816, p / 100, s / 5.3);
+            catch (error) {
+                if (saturationFailure !== null && error instanceof IF97Error)
+                    throw saturationFailure;
+                throw error;
             }
-            const state = solveRegion3PS(p, s, 1 / v0, T0);
-            return validateBackwardState(state, [
-                { label: 'pressure', expected: p, tolerance: pressureTolerance },
-                { label: 'entropy', expected: s },
-            ], { solverName: 'solvePS', expectedRegion: Region.Region3 });
         }
         case Region.Region4: {
             const endpoints = saturationEndpointsAtPressure(p);
@@ -226,7 +278,8 @@ export function solvePS(p, s) {
             ], { solverName: 'solvePS', expectedRegion: Region.Region4 });
         }
         case Region.Region5: {
-            const T = newtonRaphson((T_x) => region5(p, T_x).entropy - s, 1500, (T_x) => (region5(p, T_x).cp ?? Number.NaN) / T_x);
+            const targetS = Math.min(s, region5(p, C.R5_T_MAX).entropy);
+            const T = bracketedNewton((T_x) => region5(p, T_x).entropy - targetS, C.R5_T_MIN + Number.EPSILON * C.R5_T_MIN, C.R5_T_MAX, 1500, { derivative: (T_x) => (region5(p, T_x).cp ?? Number.NaN) / T_x, tolerance: 1e-12 });
             return validateBackwardState(region5(p, T), [
                 { label: 'pressure', expected: p },
                 { label: 'entropy', expected: s },