iapws-if97 2.1.5 → 2.8.0

package/dist/backward/ps.js

@@ -4,18 +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 { nelderMead } from '../solvers/nelder-mead.js';
-import { validateBackwardState } from './solution-validation.js';
-import { backwardConstraintTolerance } from './tolerances.js';
-import { sumNormalizedResiduals } from './objective-normalization.js';
+import { bracketedNewton } from '../solvers/bracketed-newton.js';
+import { dampedNewton2D } from '../solvers/damped-newton-2d.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) {
@@ -34,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 ───────────────────────
@@ -42,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],
@@ -85,14 +86,14 @@ 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);
     }
     if (s >= C.R2_S_CRT) {
-        return evalPoly(R2B_PS, 0, 10, p, s / 0.7853);
+        return evalPoly(R2B_PS, 0, -10, p, -s / 0.7853);
     }
-    return evalPoly(R2C_PS, 0, 2, p, s / 2.9251);
+    return evalPoly(R2C_PS, 0, -2, p, -s / 2.9251);
 }
 // ─── Region 3 Backward T(P,S) and v(P,S) ──────────────────────────────────
 const R3A_PS_T_TABLE = [
@@ -145,6 +146,40 @@ const R3B_PS_V_TABLE = [
     [0, 2, -19.1449143716586], [1, 0, -0.0150448002905284], [1, 2, 14.6407900162154],
     [2, 2, -3.2747778718823],
 ];
+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: [
+                (refinePressure ? region3PressureResidual(candidateRho, candidateT, p) : state.pressure - p) / pScale,
+                (state.entropy - s) / sScale,
+            ],
+            jacobian: [
+                [derivatives.dpDrho / pScale, derivatives.dpDT / pScale],
+                [derivatives.dsDrho / sScale, derivatives.dsDT / sScale],
+            ],
+        };
+    }, [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);
+}
 // ─── Main PS Solver ────────────────────────────────────────────────────────
 /**
  * Solve for thermodynamic state given P and S.
@@ -157,51 +192,81 @@ 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);
-            const T = newtonRaphson((T_x) => region1(p, T_x).entropy - s, T0);
+            const T = newtonRaphson((T_x) => region1(p, T_x).entropy - s, T0, (T_x) => (region1(p, T_x).cp ?? Number.NaN) / T_x);
             return validateBackwardState(region1(p, T), [
                 { label: 'pressure', expected: p },
                 { label: 'entropy', expected: 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);
+            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));
-            const entropyTolerance = backwardConstraintTolerance('entropy', s);
-            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 sol = nelderMead((pair) => {
-                const state = region3ByRhoT(1 / pair[0], pair[1]);
-                return sumNormalizedResiduals([
-                    { actual: state.entropy, expected: s, tolerance: entropyTolerance },
-                    { actual: state.pressure, expected: p, tolerance: pressureTolerance },
-                ]);
-            }, [v0, T0], { maxIterations: 1000, minErrorDelta: 1e-8, minTolerance: 1e-9 });
-            return validateBackwardState(region3ByRhoT(1 / sol.x[0], sol.x[1]), [
-                { label: 'pressure', expected: p, tolerance: pressureTolerance },
-                { label: 'entropy', expected: s },
-            ], { solverName: 'solvePS', expectedRegion: Region.Region3 });
         }
         case Region.Region4: {
             const endpoints = saturationEndpointsAtPressure(p);
@@ -213,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);
+            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 },
@@ -223,4 +289,3 @@ export function solvePS(p, s) {
             throw new IF97Error(`Cannot determine region for P=${p} MPa, s=${s} kJ/(kg·K)`);
     }
 }
-//# sourceMappingURL=ps.js.map

package/dist/backward/solution-validation.d.ts

@@ -1,5 +1,6 @@
+import type { FormulationSeamResolution } from '../core/formulation-seams.js';
 import type { BasicProperties } from '../types.js';
-import { Region } from '../types.js';
+import { IF97Error, Region } from '../types.js';
 export interface BackwardConstraint {
     label: 'pressure' | 'temperature' | 'enthalpy' | 'entropy';
     expected: number;
@@ -8,6 +9,10 @@ export interface BackwardConstraint {
 export interface BackwardValidationOptions {
     solverName: string;
     expectedRegion?: Region;
+    seam?: FormulationSeamResolution;
 }
+/** Inspect a candidate without moving it across a formulation or domain boundary. */
+export declare function backwardCandidateError(state: BasicProperties, constraints: readonly BackwardConstraint[], options: BackwardValidationOptions): IF97Error | null;
+export declare function normalizeBackwardState(state: BasicProperties, constraints: readonly BackwardConstraint[], solverName: string): BasicProperties;
 export declare function validateBackwardState(state: BasicProperties, constraints: readonly BackwardConstraint[], options: BackwardValidationOptions): BasicProperties;
-//# sourceMappingURL=solution-validation.d.ts.map
+export declare function validateRegion3PTReconstruction(state: BasicProperties, solverName: string): BasicProperties;

package/dist/backward/solution-validation.js

@@ -1,7 +1,13 @@
 import * as C from '../constants.js';
-import { detectRegionPT } from '../core/region-detector.js';
+import { detectRegionPT, nativeB23TemperatureBracket, nativeSaturationTemperatureBracket } from '../core/region-detector.js';
+import { solveRegion3PTBasic } from '../core/region3-pt.js';
+import { nextPositiveFloat } from '../core/floating-point.js';
+import { region2 } from '../regions/region2.js';
+import { region1 } from '../regions/region1.js';
 import { saturationPressure } from '../regions/region4.js';
+import { region5 } from '../regions/region5.js';
 import { IF97Error, Region } from '../types.js';
+import { NumericalStateError, RegionMismatchError } from '../errors.js';
 import { backwardConstraintTolerance, region4SaturationPressureTolerance, } from './tolerances.js';
 function propertyValue(state, label) {
     switch (label) {
@@ -17,69 +23,188 @@ function propertyValue(state, label) {
             return Number.NaN;
     }
 }
-function validateBasicEnvelope(state, solverName) {
+function boundaryTolerance(value, boundary) {
+    return 1e-9 * Math.max(1, Math.abs(value), Math.abs(boundary));
+}
+function snapUpFromBelow(value, boundary) {
+    return value < boundary && boundary - value <= boundaryTolerance(value, boundary)
+        ? boundary
+        : value;
+}
+function snapDownFromAbove(value, boundary) {
+    return value > boundary && value - boundary <= boundaryTolerance(value, boundary)
+        ? boundary
+        : value;
+}
+function normalizeComputedPT(state) {
+    if (state.region === Region.Region4)
+        return state;
+    let pressure = state.pressure < C.P_MIN &&
+        C.P_MIN - state.pressure <= backwardConstraintTolerance('pressure', C.P_MIN)
+        ? C.P_MIN
+        : state.pressure;
+    pressure = snapDownFromAbove(pressure, state.region === Region.Region5 ? C.R5_P_MAX : C.P_MAX);
+    let temperature = snapUpFromBelow(state.temperature, C.T_MIN);
+    if (state.region === Region.Region1) {
+        temperature = snapDownFromAbove(temperature, C.R2_T_MIN);
+    }
+    else if (state.region === Region.Region2) {
+        temperature = snapDownFromAbove(temperature, C.R2_T_MAX);
+    }
+    temperature = snapDownFromAbove(temperature, C.T_MAX);
+    if (pressure === state.pressure && temperature === state.temperature)
+        return state;
+    switch (state.region) {
+        case Region.Region1: return region1(pressure, temperature);
+        case Region.Region2: return region2(pressure, temperature);
+        case Region.Region3: return solveRegion3PTBasic(pressure, temperature);
+        case Region.Region5: return region5(pressure, temperature);
+    }
+}
+function normalizeB23State(state) {
+    if ((state.region !== Region.Region2 && state.region !== Region.Region3) ||
+        state.pressure <= C.B23_P_MIN || state.pressure > C.P_MAX ||
+        (state.temperature <= C.R2_T_MIN &&
+            (state.region !== Region.Region2 || state.pressure <= saturationPressure(C.R2_T_MIN))) ||
+        state.temperature >= C.B23_T_MAX ||
+        detectRegionPT(state.pressure, state.temperature) === state.region) {
+        return state;
+    }
+    const [lower, upper] = nativeB23TemperatureBracket(state.pressure);
+    const vaporT = state.region === Region.Region2 && state.pressure < C.Pc
+        ? nativeSaturationTemperatureBracket(state.pressure)[1] : upper;
+    const temperature = state.region === Region.Region3 ? lower : Math.max(upper, vaporT);
+    if (Math.abs(temperature - state.temperature) > boundaryTolerance(temperature, state.temperature)) {
+        return state;
+    }
+    return state.region === Region.Region3
+        ? solveRegion3PTBasic(state.pressure, temperature)
+        : region2(state.pressure, temperature);
+}
+function normalizeRegion3LowerState(state) {
+    if (state.region !== Region.Region3 || !(state.temperature <= C.R2_T_MIN) ||
+        C.R2_T_MIN - state.temperature > boundaryTolerance(state.temperature, C.R2_T_MIN))
+        return state;
+    return solveRegion3PTBasic(state.pressure, nextPositiveFloat(C.R2_T_MIN, 1));
+}
+function normalizeSaturationState(state, constraints, solverName) {
+    if ((state.region !== Region.Region1 && state.region !== Region.Region2) ||
+        state.pressure > saturationPressure(C.R2_T_MIN) ||
+        state.temperature < C.T_MIN || state.temperature > C.R2_T_MIN ||
+        detectRegionPT(state.pressure, state.temperature) === state.region) {
+        return state;
+    }
+    if (!constraints.some(({ label }) => label === 'pressure')) {
+        const psat = saturationPressure(state.temperature);
+        const pressure = state.region === Region.Region1 ? psat : nextPositiveFloat(psat, -1);
+        const projected = state.region === Region.Region1
+            ? region1(pressure, state.temperature)
+            : region2(pressure, state.temperature);
+        if (Math.abs(pressure - state.pressure) <= backwardConstraintTolerance('pressure', psat) &&
+            backwardCandidateError(projected, constraints, { solverName }) === null)
+            return projected;
+    }
+    const [liquidT, vaporT] = nativeSaturationTemperatureBracket(state.pressure);
+    const temperature = state.region === Region.Region1 ? liquidT : vaporT;
+    if (Math.abs(temperature - state.temperature) > boundaryTolerance(temperature, state.temperature)) {
+        return state;
+    }
+    return state.region === Region.Region1
+        ? region1(state.pressure, temperature)
+        : region2(state.pressure, temperature);
+}
+function basicEnvelopeError(state, solverName) {
     if (!Number.isFinite(state.pressure) || !Number.isFinite(state.temperature) ||
-        !Number.isFinite(state.specificVolume) || state.specificVolume <= 0) {
-        throw new IF97Error(`${solverName} produced an invalid thermodynamic state`);
+        !Number.isFinite(state.specificVolume)) {
+        return new NumericalStateError(`${solverName} produced an invalid thermodynamic state`);
     }
+    if (state.specificVolume <= 0)
+        return new IF97Error(`${solverName} produced an invalid thermodynamic state`);
     if (state.pressure < C.P_MIN || state.pressure > C.P_MAX ||
         state.temperature < C.T_MIN || state.temperature > C.T_MAX) {
-        throw new IF97Error(`${solverName} produced a state outside the IF97 PT envelope`);
+        return new IF97Error(`${solverName} produced a state outside the IF97 PT envelope`);
     }
+    if (state.region === Region.Region3) {
+        const stability = [state.cp, state.cv, state.isothermalCompressibility, state.speedOfSound];
+        if (!stability.every((value) => value !== null && Number.isFinite(value) && value > 0)) {
+            const ErrorType = stability.some((value) => value === null || !Number.isFinite(value))
+                ? NumericalStateError : IF97Error;
+            return new ErrorType(`${solverName}: Region 3 numerical inconsistency: computed EOS state at p=${state.pressure} MPa, T=${state.temperature} K failed stability checks`);
+        }
+    }
+    return null;
 }
-function validateRegionConsistency(state, solverName, expectedRegion) {
+function regionConsistencyError(state, solverName, expectedRegion) {
     if (expectedRegion !== undefined && state.region !== expectedRegion) {
-        throw new IF97Error(`${solverName} returned Region ${state.region}, expected Region ${expectedRegion}`);
+        return new IF97Error(`${solverName} returned Region ${state.region}, expected Region ${expectedRegion}`);
     }
     if (state.region === Region.Region4) {
         if (state.quality === null || !Number.isFinite(state.quality) || state.quality < 0 || state.quality > 1) {
-            throw new IF97Error(`${solverName} produced an invalid Region 4 quality`);
+            return new IF97Error(`${solverName} produced an invalid Region 4 quality`);
         }
         const psat = saturationPressure(state.temperature);
         const pTolerance = region4SaturationPressureTolerance(state.pressure);
         if (Math.abs(psat - state.pressure) > pTolerance) {
-            throw new IF97Error(`${solverName} produced a Region 4 state off the saturation curve`);
+            return new IF97Error(`${solverName} produced a Region 4 state off the saturation curve`);
         }
-        return;
+        return null;
     }
     const detectedRegion = detectRegionPT(state.pressure, state.temperature);
     if (detectedRegion !== state.region) {
-        throw new IF97Error(`${solverName} produced a PT state in Region ${detectedRegion}, not Region ${state.region}`);
+        return new RegionMismatchError(solverName, detectedRegion, state.region);
     }
+    return null;
 }
-function validateConstraints(state, constraints, solverName) {
+function constraintError(state, constraints, solverName) {
     for (const constraint of constraints) {
         const actual = propertyValue(state, constraint.label);
         const tolerance = constraint.tolerance ?? backwardConstraintTolerance(constraint.label, constraint.expected);
-        if (Math.abs(actual - constraint.expected) > tolerance) {
-            throw new IF97Error(`${solverName} failed to match ${constraint.label}: expected ${constraint.expected}, got ${actual}`);
+        if (!Number.isFinite(actual)) {
+            return new NumericalStateError(`${solverName} failed to match ${constraint.label}: expected ${constraint.expected}, got ${actual}`);
+        }
+        if (!Number.isFinite(constraint.expected) || !Number.isFinite(tolerance) ||
+            tolerance < 0 || Math.abs(actual - constraint.expected) > tolerance) {
+            return new IF97Error(`${solverName} failed to match ${constraint.label}: expected ${constraint.expected}, got ${actual}`);
         }
     }
+    return null;
 }
-function withExactConstraints(state, constraints) {
-    const normalized = { ...state };
-    for (const constraint of constraints) {
-        switch (constraint.label) {
-            case 'pressure':
-                normalized.pressure = Object.is(constraint.expected, -0) ? 0 : constraint.expected;
-                break;
-            case 'temperature':
-                normalized.temperature = Object.is(constraint.expected, -0) ? 0 : constraint.expected;
-                break;
-            case 'enthalpy':
-                normalized.enthalpy = Object.is(constraint.expected, -0) ? 0 : constraint.expected;
-                break;
-            case 'entropy':
-                normalized.entropy = Object.is(constraint.expected, -0) ? 0 : constraint.expected;
-                break;
-        }
+/** Inspect a candidate without moving it across a formulation or domain boundary. */
+export function backwardCandidateError(state, constraints, options) {
+    return basicEnvelopeError(state, options.solverName) ??
+        constraintError(state, constraints, options.solverName) ??
+        regionConsistencyError(state, options.solverName, options.expectedRegion);
+}
+export function normalizeBackwardState(state, constraints, solverName) {
+    const computed = normalizeComputedPT(state);
+    return constraints.some(({ label }) => label === 'temperature')
+        ? computed
+        : normalizeSaturationState(normalizeB23State(normalizeRegion3LowerState(computed)), constraints, solverName);
+}
+export function validateBackwardState(state, constraints, options) {
+    const seam = options.seam;
+    if (seam !== undefined && state !== seam.state) {
+        throw new IF97Error(`${options.solverName} supplied an unrelated formulation seam state`);
     }
+    const checkedConstraints = seam?.kind === 'gap'
+        ? constraints.map((constraint) => constraint.label === 'enthalpy' || constraint.label === 'entropy'
+            ? { ...constraint, tolerance: seam.budgets[constraint.label] }
+            : constraint)
+        : constraints;
+    const initialError = constraintError(state, checkedConstraints, options.solverName);
+    if (initialError !== null)
+        throw initialError;
+    const normalized = normalizeBackwardState(state, checkedConstraints, options.solverName);
+    const error = backwardCandidateError(normalized, checkedConstraints, options);
+    if (error !== null)
+        throw error;
     return normalized;
 }
-export function validateBackwardState(state, constraints, options) {
-    validateBasicEnvelope(state, options.solverName);
-    validateRegionConsistency(state, options.solverName, options.expectedRegion);
-    validateConstraints(state, constraints, options.solverName);
-    return withExactConstraints(state, constraints);
+export function validateRegion3PTReconstruction(state, solverName) {
+    return validateBackwardState(solveRegion3PTBasic(state.pressure, state.temperature), [
+        { label: 'pressure', expected: state.pressure },
+        { label: 'temperature', expected: state.temperature },
+        { label: 'enthalpy', expected: state.enthalpy },
+        { label: 'entropy', expected: state.entropy },
+    ], { solverName, expectedRegion: Region.Region3 });
 }
-//# sourceMappingURL=solution-validation.js.map

package/dist/backward/th.d.ts

@@ -1,16 +1,13 @@
 /**
  * Backward equation T,H → state.
  *
- * Given temperature and specific enthalpy, determines the IAPWS-IF97 region
- * and solves for pressure using a bracketed Newton method, then returns
- * the full set of basic thermodynamic properties.
+ * Returns a state only when temperature and enthalpy determine it uniquely.
  */
 import type { BasicProperties } from '../types.js';
 /**
  * Solve for full basic thermodynamic state from temperature and enthalpy.
  *
- * Detects the IAPWS-IF97 region, then inverts h(p, T) to recover pressure
- * within the appropriate bracket for that region.
+ * Searches every valid isotherm branch and rejects ambiguous inputs.
  *
  * Temperatures within ±CRITICAL_T_EXCLUSION_BAND of Tc are rejected because
  * the enthalpy surface is nearly flat there, making pressure recovery unreliable.
@@ -20,6 +17,6 @@ import type { BasicProperties } from '../types.js';
  * @returns Basic thermodynamic properties (without transport)
  * @throws {OutOfRangeError} if T is outside [T_MIN, T_MAX]
  * @throws {IF97Error} if T is within the critical exclusion band
+ * @throws {AmbiguousStateError} if multiple physical states match T and h
  */
 export declare function solveTH(T: number, h: number): BasicProperties;
-//# sourceMappingURL=th.d.ts.map

package/dist/backward/th.js

@@ -1,23 +1,11 @@
 import * as C from '../constants.js';
-import { IF97Error, OutOfRangeError, Region } from '../types.js';
-import { assertFiniteNumber } from '../core/input-validation.js';
-import { detectRegionTH } from '../core/region-detector.js';
-import { solveRegion3PTBasic } from '../core/region3-pt.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 { mixSaturationState, qualityFromSaturationProperty, saturationEndpointsAtTemperature, } from '../saturation/common.js';
-import { assertRegion4StateAllowed } from '../saturation/region4-boundaries.js';
-import { solveFixedTemperaturePressure } from './fixed-temperature-solver.js';
-import { validateBackwardState } from './solution-validation.js';
-const extractH = (s) => s.enthalpy;
+import { IF97Error, OutOfRangeError } from '../types.js';
+import { assertFiniteNumber, withinClosedLowerBound } from '../core/input-validation.js';
+import { uniqueFixedTemperatureState } from './fixed-temperature-candidates.js';
 /**
  * Solve for full basic thermodynamic state from temperature and enthalpy.
  *
- * Detects the IAPWS-IF97 region, then inverts h(p, T) to recover pressure
- * within the appropriate bracket for that region.
+ * Searches every valid isotherm branch and rejects ambiguous inputs.
  *
  * Temperatures within ±CRITICAL_T_EXCLUSION_BAND of Tc are rejected because
  * the enthalpy surface is nearly flat there, making pressure recovery unreliable.
@@ -27,6 +15,7 @@ const extractH = (s) => s.enthalpy;
  * @returns Basic thermodynamic properties (without transport)
  * @throws {OutOfRangeError} if T is outside [T_MIN, T_MAX]
  * @throws {IF97Error} if T is within the critical exclusion band
+ * @throws {AmbiguousStateError} if multiple physical states match T and h
  */
 export function solveTH(T, h) {
     assertFiniteNumber('Temperature', T);
@@ -34,67 +23,15 @@ export function solveTH(T, h) {
     if (T < C.T_MIN || T > C.T_MAX) {
         throw new OutOfRangeError('Temperature', T, C.T_MIN, C.T_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);
     }
     if (Math.abs(T - C.Tc) < C.CRITICAL_T_EXCLUSION_BAND) {
         throw new IF97Error(`solveTH does not support temperatures within ${C.CRITICAL_T_EXCLUSION_BAND} K of the critical-point temperature Tc=${C.Tc} K; received T=${T} K`);
     }
-    const region = detectRegionTH(T, h);
-    switch (region) {
-        case Region.Region1:
-            return validateBackwardState(solveFixedTemperaturePressure(region1, T, h, saturationPressure(T), C.P_MAX, extractH, 'solveTH'), [
-                { label: 'temperature', expected: T },
-                { label: 'enthalpy', expected: h },
-            ], {
-                solverName: 'solveTH',
-                expectedRegion: Region.Region1,
-            });
-        case Region.Region2: {
-            const upper = T <= C.Tc
-                ? saturationPressure(T)
-                : T <= C.B23_T_MAX
-                    ? boundary23_T_to_P(T)
-                    : C.P_MAX;
-            return validateBackwardState(solveFixedTemperaturePressure(region2, T, h, C.P_MIN, upper, extractH, 'solveTH'), [
-                { label: 'temperature', expected: T },
-                { label: 'enthalpy', expected: h },
-            ], {
-                solverName: 'solveTH',
-                expectedRegion: Region.Region2,
-            });
-        }
-        case Region.Region3: {
-            const lower = T <= C.Tc
-                ? saturationPressure(T)
-                : boundary23_T_to_P(T);
-            return validateBackwardState(solveFixedTemperaturePressure(solveRegion3PTBasic, T, h, lower, C.P_MAX, extractH, 'solveTH'), [
-                { label: 'temperature', expected: T },
-                { label: 'enthalpy', expected: h },
-            ], {
-                solverName: 'solveTH',
-                expectedRegion: Region.Region3,
-            });
-        }
-        case Region.Region4: {
-            const endpoints = saturationEndpointsAtTemperature(T);
-            assertRegion4StateAllowed(endpoints.pressure, endpoints.temperature, 'solveTH');
-            const x = qualityFromSaturationProperty(endpoints.liquid.enthalpy, endpoints.vapor.enthalpy, h);
-            return validateBackwardState(mixSaturationState(endpoints, x), [
-                { label: 'temperature', expected: T },
-                { label: 'enthalpy', expected: h },
-            ], { solverName: 'solveTH', expectedRegion: Region.Region4 });
-        }
-        case Region.Region5:
-            return validateBackwardState(solveFixedTemperaturePressure(region5, T, h, C.P_MIN, C.R5_P_MAX, extractH, 'solveTH'), [
-                { label: 'temperature', expected: T },
-                { label: 'enthalpy', expected: h },
-            ], {
-                solverName: 'solveTH',
-                expectedRegion: Region.Region5,
-            });
-        default:
-            throw new IF97Error(`solveTH cannot determine a valid IF97 state for T=${T} K, h=${h} kJ/kg`);
+    const state = uniqueFixedTemperatureState(T, h, 'enthalpy');
+    if (state === null) {
+        throw new IF97Error(`solveTH cannot determine a valid IF97 state for T=${T} K, h=${h} kJ/kg`);
     }
+    return state;
 }
-//# sourceMappingURL=th.js.map

package/dist/backward/tolerances.d.ts

@@ -1,6 +1,8 @@
 export type BackwardToleranceLabel = 'pressure' | 'temperature' | 'enthalpy' | 'entropy';
 export declare const BACKWARD_REGION4_QUALITY_TOLERANCE = 0.000001;
+export declare const BACKWARD_HS_NEWTON_TOLERANCE = 1e-12;
+export declare const BACKWARD_PRESSURE_PROPERTY_TEMPERATURE_TOLERANCE = 1e-13;
+export declare function fixedTemperatureRootTolerance(property: 'enthalpy' | 'entropy'): number;
 export declare function backwardConstraintTolerance(label: BackwardToleranceLabel, expected: number): number;
 export declare function region4SaturationPressureTolerance(pressure: number): number;
 export declare function backwardSpecificVolumeTolerance(expected: number): number;
-//# sourceMappingURL=tolerances.d.ts.map