iapws-if97 2.2.0 → 2.8.0

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,5 +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;
+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) {
@@ -31,7 +37,12 @@ function snapDownFromAbove(value, boundary) {
         : value;
 }
 function normalizeComputedPT(state) {
-    let pressure = snapUpFromBelow(state.pressure, C.P_MIN);
+    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) {
@@ -41,73 +52,159 @@ function normalizeComputedPT(state) {
         temperature = snapDownFromAbove(temperature, C.R2_T_MAX);
     }
     temperature = snapDownFromAbove(temperature, C.T_MAX);
-    return pressure === state.pressure && temperature === state.temperature
-        ? state
-        : { ...state, pressure, temperature };
+    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 validateBasicEnvelope(state, solverName) {
+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) {
-    const normalized = normalizeComputedPT(state);
-    validateBasicEnvelope(normalized, options.solverName);
-    validateRegionConsistency(normalized, options.solverName, options.expectedRegion);
-    validateConstraints(normalized, constraints, options.solverName);
-    return withExactConstraints(normalized, 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 });
 }

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,5 +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;

package/dist/backward/th.js

@@ -1,22 +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';
+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.
@@ -26,6 +15,7 @@ import { validateBackwardState } from './solution-validation.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 function solveTH(T, h) {
     assertFiniteNumber('Temperature', T);
@@ -33,66 +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, 'enthalpy', '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, 'enthalpy', '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, 'enthalpy', '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, 'enthalpy', '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;
 }

package/dist/backward/tolerances.d.ts

@@ -1,5 +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;

package/dist/backward/tolerances.js

@@ -1,19 +1,25 @@
 export const BACKWARD_REGION4_QUALITY_TOLERANCE = 1e-6;
+export const BACKWARD_HS_NEWTON_TOLERANCE = 1e-12;
+export const BACKWARD_PRESSURE_PROPERTY_TEMPERATURE_TOLERANCE = 1e-13;
+export function fixedTemperatureRootTolerance(property) {
+    return property === 'enthalpy' ? 1e-9 : 1e-12;
+}
 export function backwardConstraintTolerance(label, expected) {
     switch (label) {
         case 'pressure':
+            return 1e-9 * Math.abs(expected);
         case 'temperature':
             return 1e-9 * Math.max(1, Math.abs(expected));
         case 'enthalpy':
-            return 1e-6 * Math.max(1, Math.abs(expected));
+            return 1e-9 * Math.max(1, Math.abs(expected));
         case 'entropy':
-            return 1e-6 * Math.max(1, Math.abs(expected));
+            return 1e-9 * Math.max(1, Math.abs(expected));
         default:
             return 1e-9;
     }
 }
 export function region4SaturationPressureTolerance(pressure) {
-    return 1e-8 * Math.max(1, Math.abs(pressure));
+    return 1e-8 * Math.abs(pressure);
 }
 export function backwardSpecificVolumeTolerance(expected) {
     return 1e-6 * Math.max(1, Math.abs(expected));

package/dist/backward/ts.d.ts

@@ -1,16 +1,13 @@
 /**
  * Backward equation T,S → state.
  *
- * Given temperature and specific entropy, 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 entropy determine it uniquely.
  */
 import type { BasicProperties } from '../types.js';
 /**
  * Solve for full basic thermodynamic state from temperature and entropy.
  *
- * Detects the IAPWS-IF97 region, then inverts s(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 entropy surface is nearly flat there, making pressure recovery unreliable.
@@ -20,5 +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 s
  */
 export declare function solveTS(T: number, s: number): BasicProperties;

package/dist/backward/ts.js

@@ -1,22 +1,11 @@
 import * as C from '../constants.js';
-import { IF97Error, OutOfRangeError, Region } from '../types.js';
-import { assertFiniteNumber } from '../core/input-validation.js';
-import { detectRegionTS } 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';
+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 entropy.
  *
- * Detects the IAPWS-IF97 region, then inverts s(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 entropy surface is nearly flat there, making pressure recovery unreliable.
@@ -26,6 +15,7 @@ import { validateBackwardState } from './solution-validation.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 s
  */
 export function solveTS(T, s) {
     assertFiniteNumber('Temperature', T);
@@ -33,66 +23,15 @@ export function solveTS(T, s) {
     if (T < C.T_MIN || T > C.T_MAX) {
         throw new OutOfRangeError('Temperature', T, C.T_MIN, C.T_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);
     }
     if (Math.abs(T - C.Tc) < C.CRITICAL_T_EXCLUSION_BAND) {
         throw new IF97Error(`solveTS 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 = detectRegionTS(T, s);
-    switch (region) {
-        case Region.Region1:
-            return validateBackwardState(solveFixedTemperaturePressure(region1, T, s, saturationPressure(T), C.P_MAX, 'entropy', 'solveTS'), [
-                { label: 'temperature', expected: T },
-                { label: 'entropy', expected: s },
-            ], {
-                solverName: 'solveTS',
-                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, s, C.P_MIN, upper, 'entropy', 'solveTS'), [
-                { label: 'temperature', expected: T },
-                { label: 'entropy', expected: s },
-            ], {
-                solverName: 'solveTS',
-                expectedRegion: Region.Region2,
-            });
-        }
-        case Region.Region3: {
-            const lower = T <= C.Tc
-                ? saturationPressure(T)
-                : boundary23_T_to_P(T);
-            return validateBackwardState(solveFixedTemperaturePressure(solveRegion3PTBasic, T, s, lower, C.P_MAX, 'entropy', 'solveTS'), [
-                { label: 'temperature', expected: T },
-                { label: 'entropy', expected: s },
-            ], {
-                solverName: 'solveTS',
-                expectedRegion: Region.Region3,
-            });
-        }
-        case Region.Region4: {
-            const endpoints = saturationEndpointsAtTemperature(T);
-            assertRegion4StateAllowed(endpoints.pressure, endpoints.temperature, 'solveTS');
-            const x = qualityFromSaturationProperty(endpoints.liquid.entropy, endpoints.vapor.entropy, s);
-            return validateBackwardState(mixSaturationState(endpoints, x), [
-                { label: 'temperature', expected: T },
-                { label: 'entropy', expected: s },
-            ], { solverName: 'solveTS', expectedRegion: Region.Region4 });
-        }
-        case Region.Region5:
-            return validateBackwardState(solveFixedTemperaturePressure(region5, T, s, C.P_MIN, C.R5_P_MAX, 'entropy', 'solveTS'), [
-                { label: 'temperature', expected: T },
-                { label: 'entropy', expected: s },
-            ], {
-                solverName: 'solveTS',
-                expectedRegion: Region.Region5,
-            });
-        default:
-            throw new IF97Error(`solveTS cannot determine a valid IF97 state for T=${T} K, s=${s} kJ/(kg·K)`);
+    const state = uniqueFixedTemperatureState(T, s, 'entropy');
+    if (state === null) {
+        throw new IF97Error(`solveTS cannot determine a valid IF97 state for T=${T} K, s=${s} kJ/(kg·K)`);
     }
+    return state;
 }

package/dist/constants.d.ts

@@ -4,11 +4,7 @@
  * Physical constants, critical point properties, and range limits
  * for the IAPWS Industrial Formulation 1997.
  */
-/** 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 declare 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 declare const R_IAPWS_2011_THERMAL = 0.46151805;
@@ -16,13 +12,13 @@ export declare const R_IAPWS_2011_THERMAL = 0.46151805;
 export declare const Tc = 647.096;
 /** Temperature exclusion half-band around the critical point [K] */
 export declare const CRITICAL_T_EXCLUSION_BAND = 0.001;
-/** Region 4 endpoint snap tolerance for temperatures [K] */
+/** Region 4 tolerance for outward temperature-boundary roundoff [K] */
 export declare const REGION4_TEMPERATURE_TOLERANCE = 1e-9;
 /** Safety margin used when clamping Region 4 temperatures below Tc [K] */
 export declare const REGION4_SUBCRITICAL_TEMPERATURE_MARGIN = 1e-8;
 /** Critical pressure [MPa] */
 export declare const Pc = 22.064;
-/** Region 4 endpoint snap tolerance for pressures [MPa] */
+/** Relative tolerance for outward Region 4 pressure-boundary roundoff */
 export declare const REGION4_PRESSURE_TOLERANCE = 1e-9;
 /** Tolerance for identifying the critical h-s endpoint in Region 4 */
 export declare const REGION4_CRITICAL_HS_TOLERANCE = 0.000001;
@@ -44,14 +40,14 @@ export declare const P_MAX = 100;
 export declare const T_MIN = 273.15;
 /** Maximum temperature [K] (2273.15 K = 2000 °C) */
 export declare const T_MAX = 2273.15;
-/** Minimum specific entropy [kJ/(kg·K)] */
-export declare const S_MIN = -0.00015454959194;
-/** Maximum specific entropy [kJ/(kg·K)] */
-export declare const S_MAX = 13.904956083429227;
-/** Minimum specific enthalpy [kJ/kg] */
-export declare const H_MIN = -0.041587825987;
-/** Maximum specific enthalpy [kJ/kg] */
-export declare const H_MAX = 7376.980263598506;
+/** Minimum specific entropy [kJ/(kg·K)], at T_MIN and P_MAX in Region 1. */
+export declare const S_MIN = -0.00858228709261889;
+/** Maximum specific entropy [kJ/(kg·K)], at T_MAX and P_MIN in Region 5. */
+export declare const S_MAX: number;
+/** Minimum specific enthalpy [kJ/kg], at T_MIN and P_MIN in Region 1. */
+export declare const H_MIN = -0.041587825987655716;
+/** Maximum specific enthalpy [kJ/kg], at T_MAX and P_MIN in Region 5. */
+export declare const H_MAX: number;
 /** Region 2 minimum temperature for high-P subregions [K] (623.15 K = 350 °C) */
 export declare const R2_T_MIN = 623.15;
 /** Region 2 maximum temperature for backward eqs [K] (1073.15 K = 800 °C) */