iapws-if97 2.1.2 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## 2.2.0
+
+### Fixed
+
+- Improved backward-solver accuracy, robustness, and performance.
+- Fixed saturation-region detection and package validation.
+- Requires Node.js `>=20.19.0`.
+
+## 2.1.5
+
+- fix some issues
+
 ## 2.1.2
 
 - fix some issues

package/README.md

@@ -1,8 +1,10 @@
 # `iapws-if97`
 
-Calculate industrial water and steam properties in Node.js and TypeScript, based on the [IAPWS-IF97](https://www.iapws.org/) standard (International Association for the Properties of Water and Steam — Industrial Formulation 1997).
+[![CI](https://github.com/jltonghui/iapws-if97/actions/workflows/ci.yml/badge.svg)](https://github.com/jltonghui/iapws-if97/actions/workflows/ci.yml)
 
-This library provides forward and backward state solvers, saturation solvers, and transport-property helpers for engineering calculations involving water and steam.
+`iapws-if97` calculates industrial water and steam properties in Node.js and TypeScript using the [IAPWS-IF97](https://www.iapws.org/) standard published by the International Association for the Properties of Water and Steam.
+
+It includes forward and backward state solvers, saturation solvers, and transport-property helpers.
 
 ## Features
 
@@ -11,21 +13,19 @@ This library provides forward and backward state solvers, saturation solvers, an
 - Transport properties: viscosity, thermal conductivity, surface tension, dielectric constant, and ionization constant
 - Verified against official IAPWS tables and published engineering references
 
-## Project Origin
-
-> `iapws-if97` is the core calculation engine behind the WeChat Mini Program "汽水计算器" (`wxid: wx7201fd1713b524e5`). Since its launch in 2019, it has served nearly 20,000 users. With the help of AI, this edition has been updated to incorporate `R11-24 (2024)`. I am open-sourcing it in the hope that it will help others with similar engineering needs.
-
-<p align="right">-- Retired Thermodynamic Engineer, Shuping</p>
-
 ## Installation
 
+Requires Node.js `>=20.19.0`. The package publishes ESM, and all documented examples use `import`. CommonJS is not part of the tested API.
+
 ```bash
 npm install iapws-if97
 ```
 
-## Quick Start
+## Quick start
 
-```ts
+Save the following as `example.mjs` and run it with `node example.mjs`:
+
+```js
 import { solve, solvePT, solvePx } from 'iapws-if97';
 
 const a = solvePT(3, 300);
@@ -39,15 +39,20 @@ console.log(c.quality);     // 0.5
 
 ## Main API
 
-- `solvePT(p, T)` // `MPa`, `K`
-- `solvePH(p, h)` // `MPa`, `kJ/kg`
-- `solvePS(p, s)` // `MPa`, `kJ/(kg·K)`
-- `solveHS(h, s)` // `kJ/kg`, `kJ/(kg·K)`
-- `solveTH(T, h)` // `K`, `kJ/kg`
-- `solveTS(T, s)` // `K`, `kJ/(kg·K)`
-- `solvePx(p, x)` // `MPa`, quality `[0, 1]`
-- `solveTx(T, x)` // `K`, quality `[0, 1]`
-- `solve(input)` // same units as the selected `mode`
+| Function | Input pair | Units |
+| --- | --- | --- |
+| `solvePT(p, T)` | pressure, temperature | `MPa`, `K` |
+| `solvePH(p, h)` | pressure, enthalpy | `MPa`, `kJ/kg` |
+| `solvePS(p, s)` | pressure, entropy | `MPa`, `kJ/(kg·K)` |
+| `solveHS(h, s)` | enthalpy, entropy | `kJ/kg`, `kJ/(kg·K)` |
+| `solveTH(T, h)` | temperature, enthalpy | `K`, `kJ/kg` |
+| `solveTS(T, s)` | temperature, entropy | `K`, `kJ/(kg·K)` |
+| `solvePx(p, x)` | pressure, vapor quality | `MPa`, dimensionless `[0, 1]` |
+| `solveTx(T, x)` | temperature, vapor quality | `K`, dimensionless `[0, 1]` |
+
+All numeric inputs must be finite numbers.
+
+### Unified `solve()`
 
 Use `solve({ mode, ... })` when the input pair is determined at runtime:
 
@@ -57,30 +62,33 @@ import { solve } from 'iapws-if97';
 const state = solve({ mode: 'PT', p: 16, T: 823.15 });
 ```
 
-`solve` accepts both short-form and long-form property names:
+Each mode accepts canonical short fields or their long aliases:
+
+| Mode | Short fields | Long aliases |
+| --- | --- | --- |
+| `PT` | `p`, `T` | `pressure`, `temperature` |
+| `PH` | `p`, `h` | `pressure`, `enthalpy` |
+| `PS` | `p`, `s` | `pressure`, `entropy` |
+| `HS` | `h`, `s` | `enthalpy`, `entropy` |
+| `Px` | `p`, `x` | `pressure`, `quality` |
+| `Tx` | `T`, `x` | `temperature`, `quality` |
+| `TH` | `T`, `h` | `temperature`, `enthalpy` |
+| `TS` | `T`, `s` | `temperature`, `entropy` |
 
 ```ts
-const a = solve({ mode: 'PT', p: 16, T: 823.15 });
-const b = solve({ mode: 'PT', pressure: 16, temperature: 823.15 });
-```
+import type { SolveInput } from 'iapws-if97';
+import { solve } from 'iapws-if97';
 
-Supported modes:
+const shortForm: SolveInput = { mode: 'PT', p: 16, T: 823.15 };
+const longForm: SolveInput = { mode: 'PT', pressure: 16, temperature: 823.15 };
 
-```ts
-type SolveInput =
-  | { mode: 'PT'; p: number; T: number }
-  | { mode: 'PH'; p: number; h: number }
-  | { mode: 'PS'; p: number; s: number }
-  | { mode: 'HS'; h: number; s: number }
-  | { mode: 'Px'; p: number; x: number }
-  | { mode: 'Tx'; T: number; x: number }
-  | { mode: 'TH'; T: number; h: number }
-  | { mode: 'TS'; T: number; s: number };
+const a = solve(shortForm);
+const b = solve(longForm);
 ```
 
-You can use either form for each property. If you provide both, their values must match.
+You can mix short and long names within one input. If both aliases for the same property are present, their values must match exactly. The exported `SolveInput` type is the source of truth for accepted combinations.
 
-## Solver Return Value
+## Solver return value
 
 All solvers return a `SteamState` object containing both thermodynamic and transport properties:
 
@@ -108,16 +116,16 @@ type SteamState = {
 };
 ```
 
-`SteamState` always uses canonical property names. 
+`SteamState` always uses canonical property names.
 
 **Notes:**
 
-- `quality` is `null` for single-phase states — it is only defined on the saturation line.
+- `quality` is `null` for single-phase states; it is only defined on the saturation line.
 - In two-phase mixtures (`0 < x < 1`), `cp`, `cv`, `speedOfSound`, `isobaricExpansion`, `isothermalCompressibility`, `viscosity`, `thermalConductivity`, `dielectricConstant`, and `ionizationConstant` are `null`.
 - Saturation endpoints (`x = 0` or `x = 1`) still expose single-phase transport properties even though they carry Region 4 metadata.
 - `solvePT(p, T)` is a single-phase solver. On the subcritical saturation boundary it resolves to the liquid side.
 - `surfaceTension` is only available for Region 4 saturation states below the critical point; otherwise `null`.
-- `density` is provided directly — no need to invert `specificVolume`.
+- `density` is provided directly, so there is no need to invert `specificVolume`.
 - `ionizationConstant` is `null` outside the IAPWS validity range for that correlation.
 
 ## Units
@@ -140,19 +148,59 @@ type SteamState = {
 
 Any field typed as `number | null` returns `null` when the property is undefined for the given state.
 
-## Saturation Endpoint
+## Advanced imports
+
+The package root is limited to the main solvers, `SteamState`, `SolveInput`, `Region`, and the public error classes. Lower-level helpers are available from explicit subpaths:
+
+| Subpath | Exports |
+| --- | --- |
+| `iapws-if97/transport` | `viscosity`, `thermalConductivity`, `surfaceTension`, `dielectricConstant`, `ionizationConstant` |
+| `iapws-if97/regions` | `region1`, `region2`, `region3ByRhoT`, `region5` |
+| `iapws-if97/saturation` | `saturationPressure`, `saturationTemperature` |
+| `iapws-if97/boundaries` | `boundary23_T_to_P`, `boundary23_P_to_T`, `region3Volume`, `region3SatVolume` |
+| `iapws-if97/detect` | `detectRegionPT`, `detectRegionPH`, `detectRegionPS`, `detectRegionHS`, `detectRegionTH`, `detectRegionTS` |
+
+```ts
+import { viscosity } from 'iapws-if97/transport';
+import { region1 } from 'iapws-if97/regions';
+import { saturationTemperature } from 'iapws-if97/saturation';
+import { detectRegionPT } from 'iapws-if97/detect';
+```
+
+These are low-level mathematical interfaces:
+
+- Region functions return core thermodynamic properties without `density` or transport-property enrichment.
+- Region, boundary, and detection helpers expect callers to respect the corresponding equation domains. Detection helpers return a `Region` value or `-1` when no valid region is found.
+- `thermalConductivity(T, rho)` calculates the base contribution. Pass `cp`, `cv`, `drhodP_T`, and `mu` to include the IAPWS 2011 critical-enhancement term.
+- `surfaceTension(T)` is a saturation-line property. `saturationPressure(T)` and `saturationTemperature(p)` expose the mathematical Region 4 boundary and are more permissive at endpoints than `solveTx` and `solvePx`.
 
-- Low-level Region 4 helpers stay mathematically permissive and high-level saturation state solvers are stricter:
+## Transport correlation limits
+
+Transport correlations have validity ranges independent of the IF97 thermodynamic envelope. The library may return extrapolated values where noted:
+
+| Property | Implemented behavior |
+| --- | --- |
+| Viscosity | Uses the IAPWS 2008 dilute-gas and finite-density terms. The near-critical enhancement is omitted, as permitted for industrial use by the release. |
+| Thermal conductivity | Full `SteamState` calculations include the IAPWS 2011 critical enhancement. The two-argument low-level call does not. Values above the release's temperature range are extrapolations. |
+| Surface tension | Defined for saturation states below the critical point. The low-level helper permits `273.15 K ≤ T ≤ Tc`; values below the triple point `Tt = 273.16 K` are extrapolations. |
+| Dielectric constant | The IAPWS 1997 release is valid through `873 K`. The low-level helper does not enforce that upper bound, so higher-temperature results are extrapolations. |
+| Ionization constant (`pKw`) | Returns `null` outside `273.15 K ≤ T ≤ 1273.15 K`. The release's `1000 MPa` pressure limit describes the correlation, not the state-solver pressure range. |
+
+## Saturation endpoints
+
+The triple and critical points are `Pt = 0.000611657 MPa`, `Tt = 273.16 K`, `Pc = 22.064 MPa`, and `Tc = 647.096 K`.
+
+- Low-level Region 4 helpers accept a wider endpoint range. The saturation state solvers use these stricter bounds:
   - `solvePx(p, x)` accepts `Pt ≤ p < Pc`
   - `solveTx(T, x)` accepts `Tt = 273.16 K ≤ T < Tc`
-- The true triple point is supported as a saturation-state boundary:
+- The triple point is supported as a saturation-state boundary:
   - `solvePx(Pt, x)` is valid
   - `solveTx(Tt, x)` is valid
 - `273.15 K` is treated as a low-level extrapolation boundary only.
-- The exact critical point is never returned as a Region 4 state.
-- `solveTH(T, h)` and `solveTS(T, s)` keep a small exclusion band around `Tc` and reject inputs within `0.001 K` of the critical temperature.
+- The solvers do not return the exact critical point as a Region 4 state.
+- `solveTH(T, h)` and `solveTS(T, s)` reject inputs within `0.001 K` of the critical temperature.
 
-## Errors and Limits
+## Errors and limits
 
 The library throws typed errors:
 
@@ -160,14 +208,18 @@ The library throws typed errors:
 | --- | --- |
 | `OutOfRangeError` | Input is outside the supported IF97 range |
 | `ConvergenceError` | An internal iterative solve failed to converge |
-| `IF97Error` | Base class for all library-specific errors |
+| `IF97Error` | Base class; root solvers also use it directly for non-numeric or non-finite inputs, conflicting aliases, unsupported modes, and unsupported critical-point states |
 
-## Validity Notes
+Numeric inputs to root solvers and transport helpers must be finite. Low-level region, boundary, and detection helpers rely on callers to respect their equation domains. `solvePT(Pc, Tc)`, exact critical Region 4 states, and `solveTH`/`solveTS` inputs within `0.001 K` of `Tc` are rejected because the required derivative properties or inverse solution are singular or ill-conditioned.
 
-- Thermodynamic properties follow IF97 validity ranges: up to `100 MPa` and `2273.15 K` (including Region 5).
-- Surface tension applies only along the saturation line below the critical point.
-- Thermal conductivity follows the IAPWS 2011 release.
-- Ionization constant follows the IAPWS 2024 revised release, valid for stable fluid states from `273.15 K` to `1273.15 K` and up to `1000 MPa`.
+## Thermodynamic validity
+
+The thermodynamic solvers follow the piecewise IF97 industrial range:
+
+- `273.15 K ≤ T ≤ 1073.15 K`: pressure up to `100 MPa`.
+- `1073.15 K < T ≤ 2273.15 K` (Region 5): pressure up to `50 MPa`.
+
+Transport-property limits are separate; see [Transport correlation limits](#transport-correlation-limits).
 
 ## Verification
 
@@ -181,60 +233,39 @@ The test suite covers:
 - Coverage thresholds enforced locally
 - ASME and GB/T steam-table comparisons against published values
 
-To run locally:
+For a clean local verification run:
 
 ```bash
-npm run build
+npm ci
+npm run test:package
 npm test
+```
+
+`test:package` performs a clean build and checks that the dry-run npm tarball has no dangling source-map references. Coverage and published-table comparisons are available separately:
+
+```bash
 npm run test:coverage
 npm run test:standards
 ```
 
-## Integration Validation
+## Integration validation
 
 ![Mollier h-s diagram generated with iapws-if97](https://raw.githubusercontent.com/jltonghui/iapws-if97/main/assets/pics/mollier-hs-diagram.svg)
 
-This Mollier `h-s` diagram was generated with `iapws-if97` as a practical end-to-end validation artifact.
-
-### ASME Validation Snapshot
-
-Compares saturation states against *ASME International Steam Tables for Industrial Use*, 3rd ed., Table S-2 ("Properties of Saturated Water and Steam — Pressure").
-Each case checks 7 values: saturation temperature, liquid/vapor specific volume, enthalpy, and entropy.
-The snapshot below reflects the current `tests/standards-asme` regression run.
-
-| ASME case | Pressure (MPa) | Points checked | Max relative error |
-| --- | ---: | ---: | ---: |
-| Table S-2 @ 0.01 MPa | 0.01 | 7 | 0.0257993% |
-| Table S-2 @ 0.10 MPa | 0.10 | 7 | 0.0141744% |
-| Table S-2 @ 1.00 MPa | 1.00 | 7 | 0.0207405% |
-| Table S-2 @ 5.0 MPa | 5.0 | 7 | 0.0315405% |
-| Table S-2 @ 10.0 MPa | 10.0 | 7 | 0.0261599% |
-| Table S-2 @ 20.0 MPa | 20.0 | 7 | 0.0173004% |
-| Overall worst case | - | 42 | 0.0315405% |
+This Mollier `h-s` diagram was generated with `iapws-if97` as an end-to-end check of the calculation pipeline.
 
-The current ASME regression threshold is `maxRelativeError < 5e-4` (less than `0.05%`).
+The standards tests check the published tables below. Both suites enforce `maxRelativeError < 5e-4` (less than `0.05%`).
 
-### GB/T Validation Snapshot
+| Reference | Coverage | Points checked | Worst relative error |
+| --- | --- | ---: | ---: |
+| *ASME International Steam Tables for Industrial Use*, 3rd ed., Table S-2 | Saturation states at 6 pressures | 42 | `0.0315405%` |
+| *GB/T 34060-2017*, Table A.3(续), page 55 | Superheated steam at `10 MPa` and 6 temperatures | 24 | `0.0007020%` |
 
-Compares superheated-steam states against *GB/T 34060-2017*, Table A.3(续), page 55.
-Each case checks 4 values at `10 MPa`: specific volume, enthalpy, entropy, and speed of sound.
-The snapshot below reflects the current `tests/standards-cn` regression run.
-
-| GB/T case | Pressure (MPa) | Temperature (°C) | Points checked | Max relative error |
-| --- | ---: | ---: | ---: | ---: |
-| Table A.3 @ 10 MPa, 350 C | 10 | 350 | 4 | 0.0007020% |
-| Table A.3 @ 10 MPa, 400 C | 10 | 400 | 4 | 0.0004650% |
-| Table A.3 @ 10 MPa, 500 C | 10 | 500 | 4 | 0.0006808% |
-| Table A.3 @ 10 MPa, 600 C | 10 | 600 | 4 | 0.0005630% |
-| Table A.3 @ 10 MPa, 700 C | 10 | 700 | 4 | 0.0004072% |
-| Table A.3 @ 10 MPa, 800 C | 10 | 800 | 4 | 0.0004146% |
-| Overall worst case | - | - | 24 | 0.0007020% |
-
-The current GB/T regression threshold is `maxRelativeError < 5e-4` (less than `0.05%`).
+See [`tests/standards-asme`](tests/standards-asme) and [`tests/standards-cn`](tests/standards-cn) for the source values and per-case comparisons.
 
 ## TypeScript
 
-The package ships with bundled TypeScript declarations and ESM exports.
+The package ships with generated TypeScript declarations for the root and every public subpath.
 
 ```ts
 import type { SolveInput, SteamState } from 'iapws-if97';
@@ -251,11 +282,20 @@ if (state.region === Region.Region1) {
 ## References
 
 - [IAPWS official website](https://www.iapws.org/)
-- IAPWS R7-97(2012), Revised Release on the IAPWS Industrial Formulation 1997 for the Thermodynamic Properties of Water and Steam
-- IAPWS supplementary releases for backward equations `T(p,h)`, `T(p,s)`, and `p(h,s)`
-- IAPWS R15-11, Thermal Conductivity of Ordinary Water Substance
-- IAPWS R1-76(2014), Surface Tension of Ordinary Water Substance
-- IAPWS R11-24, Revised Release on the Ionization Constant of H2O
+- [IAPWS R7-97(2012), Industrial Formulation 1997](https://www.iapws.org/relguide/IF97-Rev.html)
+- [IAPWS supplementary releases](https://www.iapws.org/release.html) for `T(p,h)`, `T(p,s)`, `p(h,s)`, Region 3 boundary equations, `Tsat(h,s)`, and `v(p,T)`
+- [IAPWS SR4-04(2014), Region 3 `p(h,s)` and Region 4 `Tsat(h,s)`](https://iapws.org/documents/release/Supp-phs3-2014)
+- [IAPWS R12-08, Viscosity of Ordinary Water Substance](https://www.iapws.org/relguide/viscosity.html)
+- [IAPWS R15-11, Thermal Conductivity of Ordinary Water Substance](https://www.iapws.org/relguide/ThCond.html)
+- [IAPWS R8-97, Static Dielectric Constant of Ordinary Water Substance](https://www.iapws.org/relguide/dielec.pdf)
+- [IAPWS R1-76(2014), Surface Tension of Ordinary Water Substance](https://www.iapws.org/relguide/Surf-H2O.html)
+- [IAPWS R11-24, Ionization Constant of H2O](https://www.iapws.org/relguide/Ionization.html)
+
+## Project origin
+
+> `iapws-if97` began as the calculation engine behind the WeChat Mini Program "汽水计算器" (`wxid: wx7201fd1713b524e5`). Since its 2019 launch, it has served more than 20,000 users. AI-assisted review helped bring this open-source edition up to date with IAPWS `R11-24 (2024)`. I am sharing the engine so it can reach engineers far beyond the original program.
+
+<p align="right">Shuping, retired thermodynamic engineer</p>
 
 ## License
 

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

@@ -5,21 +5,21 @@
  * (enthalpy or entropy) using a bracketed Newton method.
  */
 import type { BasicProperties } from '../types.js';
-type PropertyExtractor = (state: BasicProperties) => number;
+/** Property being inverted against pressure at fixed temperature. */
+export type FixedTemperatureProperty = 'enthalpy' | 'entropy';
 /**
  * Solve for pressure at fixed temperature by matching a target property value.
  *
  * Evaluates the region equation at the bracket endpoints first (short-circuit
- * if either already matches), then runs a bracketed Newton iteration.
+ * if either already matches), then runs a bracketed Newton iteration driven by
+ * the analytic pressure derivative.
  *
  * @param evaluator  - Region-specific equation returning BasicProperties from (p, T)
  * @param T          - Fixed temperature [K]
  * @param target     - Target property value (enthalpy or entropy)
  * @param lower      - Lower pressure bracket [MPa]
  * @param upper      - Upper pressure bracket [MPa]
- * @param extract    - Function to extract the target property from BasicProperties
+ * @param property   - Which property `target` represents
  * @param solverName - Label used in error messages
  */
-export declare function solveFixedTemperaturePressure(evaluator: (p: number, T: number) => BasicProperties, T: number, target: number, lower: number, upper: number, extract: PropertyExtractor, solverName: string): BasicProperties;
-export {};
-//# sourceMappingURL=fixed-temperature-solver.d.ts.map
+export declare function solveFixedTemperaturePressure(evaluator: (p: number, T: number) => BasicProperties, T: number, target: number, lower: number, upper: number, property: FixedTemperatureProperty, solverName: string): BasicProperties;

package/dist/backward/fixed-temperature-solver.js

@@ -1,31 +1,57 @@
 import { IF97Error } from '../types.js';
 import { bracketedNewton } from '../solvers/bracketed-newton.js';
+import { gibbsPropertyDerivatives } from './thermodynamic-derivatives.js';
+function propertyValue(state, property) {
+    return property === 'enthalpy' ? state.enthalpy : state.entropy;
+}
+/**
+ * (∂h/∂p)_T = 1000·v(1 − Tα) or (∂s/∂p)_T = −1000·v·α, both per MPa.
+ *
+ * These are Maxwell-relation identities, so they hold for the Helmholtz-based
+ * Region 3 states as well as the Gibbs-based regions. Returns NaN when a state
+ * carries no cp/α, which makes the caller fall back to a bisection step.
+ */
+function pressureDerivative(state, property) {
+    const derivatives = gibbsPropertyDerivatives(state);
+    return property === 'enthalpy' ? derivatives.dhDp : derivatives.dsDp;
+}
 /**
  * Solve for pressure at fixed temperature by matching a target property value.
  *
  * Evaluates the region equation at the bracket endpoints first (short-circuit
- * if either already matches), then runs a bracketed Newton iteration.
+ * if either already matches), then runs a bracketed Newton iteration driven by
+ * the analytic pressure derivative.
  *
  * @param evaluator  - Region-specific equation returning BasicProperties from (p, T)
  * @param T          - Fixed temperature [K]
  * @param target     - Target property value (enthalpy or entropy)
  * @param lower      - Lower pressure bracket [MPa]
  * @param upper      - Upper pressure bracket [MPa]
- * @param extract    - Function to extract the target property from BasicProperties
+ * @param property   - Which property `target` represents
  * @param solverName - Label used in error messages
  */
-export function solveFixedTemperaturePressure(evaluator, T, target, lower, upper, extract, solverName) {
+export function solveFixedTemperaturePressure(evaluator, T, target, lower, upper, property, solverName) {
+    // Keyed by p, so the residual and its derivative at the same point share one
+    // equation evaluation regardless of the order the solver calls them in.
+    let cachedPressure = Number.NaN;
+    let cachedState = null;
+    const stateAt = (p) => {
+        if (p !== cachedPressure || cachedState === null) {
+            cachedPressure = p;
+            cachedState = evaluator(p, T);
+        }
+        return cachedState;
+    };
     const lowerState = evaluator(lower, T);
     const upperState = evaluator(upper, T);
-    if (Math.abs(extract(lowerState) - target) <= 1e-9)
+    if (Math.abs(propertyValue(lowerState, property) - target) <= 1e-9)
         return lowerState;
-    if (Math.abs(extract(upperState) - target) <= 1e-9)
+    if (Math.abs(propertyValue(upperState, property) - target) <= 1e-9)
         return upperState;
-    const pressure = bracketedNewton((p) => extract(evaluator(p, T)) - target, lower, upper, (lower + upper) / 2);
-    const state = evaluator(pressure, T);
+    const pressure = bracketedNewton((p) => propertyValue(stateAt(p), property) - target, lower, upper, (lower + upper) / 2, { derivative: (p) => pressureDerivative(stateAt(p), property) });
+    const state = stateAt(pressure);
     if (!Number.isFinite(state.pressure)) {
         throw new IF97Error(`${solverName} failed to recover a valid pressure`);
     }
     return state;
 }
-//# sourceMappingURL=fixed-temperature-solver.js.map

package/dist/backward/hs.d.ts

@@ -2,7 +2,7 @@
  * IAPWS-IF97 Backward Equations: H-S -> P, T
  *
  * Given specific enthalpy and entropy, compute pressure and temperature.
- * Uses backward P(h,s) equations for initial guess + Nelder-Mead refinement.
+ * Uses backward P(h,s) equations for initial guesses + damped Newton refinement.
  *
  * Reference: IAPWS-IF97 Supplementary Release on Backward Equations p(h,s)
  */
@@ -13,4 +13,3 @@ import type { BasicProperties } from '../types.js';
  * @param s - Specific entropy [kJ/(kg·K)]
  */
 export declare function solveHS(h: number, s: number): BasicProperties;
-//# sourceMappingURL=hs.d.ts.map

package/dist/backward/hs.js

@@ -2,7 +2,7 @@
  * IAPWS-IF97 Backward Equations: H-S -> P, T
  *
  * Given specific enthalpy and entropy, compute pressure and temperature.
- * Uses backward P(h,s) equations for initial guess + Nelder-Mead refinement.
+ * Uses backward P(h,s) equations for initial guesses + damped Newton refinement.
  *
  * Reference: IAPWS-IF97 Supplementary Release on Backward Equations p(h,s)
  */
@@ -14,12 +14,10 @@ import { region3ByRhoT } from '../regions/region3.js';
 import { region5 } from '../regions/region5.js';
 import { assertFiniteNumber } from '../core/input-validation.js';
 import { detectRegionHS } from '../core/region-detector.js';
-import { newtonRaphson } from '../solvers/newton-raphson.js';
-import { nelderMead } from '../solvers/nelder-mead.js';
-import { solvePH } from './ph.js';
+import { dampedNewton2D } from '../solvers/damped-newton-2d.js';
+import { r1BackwardT, r2BackwardT, r3BackwardPHInitial } from './ph.js';
 import { validateBackwardState } from './solution-validation.js';
-import { sumNormalizedResiduals } from './objective-normalization.js';
-import { backwardConstraintTolerance } from './tolerances.js';
+import { gibbsPropertyDerivatives, helmholtzPropertyDerivatives, } from './thermodynamic-derivatives.js';
 import { tryRegion4HSState, } from '../saturation/region4-hs.js';
 import { assertCriticalRegion4HSInput, } from '../saturation/region4-boundaries.js';
 // ─── Backward Polynomial Evaluator ─────────────────────────────────────────
@@ -159,21 +157,52 @@ function r3Phs(h, s) {
         return r3aPhs(h, s);
     return r3bPhs(h, s);
 }
-const REGION5_HS_OUT_OF_DOMAIN_PENALTY = 1e18;
-function normalizedRegion5HsObjective(h, s) {
-    const enthalpyTolerance = backwardConstraintTolerance('enthalpy', h);
-    const entropyTolerance = backwardConstraintTolerance('entropy', s);
-    return (pair) => {
-        const [p, T] = pair;
-        if (p <= 0 || p > C.R5_P_MAX || T <= C.R5_T_MIN || T > C.R5_T_MAX) {
-            return REGION5_HS_OUT_OF_DOMAIN_PENALTY;
-        }
-        const state = region5(p, T);
-        return sumNormalizedResiduals([
-            { actual: state.enthalpy, expected: h, tolerance: enthalpyTolerance },
-            { actual: state.entropy, expected: s, tolerance: entropyTolerance },
-        ]);
-    };
+function solveGibbsHS(h, s, initial, stateAt) {
+    const hScale = Math.max(1, Math.abs(h));
+    const sScale = Math.max(1, Math.abs(s));
+    const [p, T] = dampedNewton2D(([candidateP, candidateT]) => {
+        const state = stateAt(candidateP, candidateT);
+        const derivatives = gibbsPropertyDerivatives(state);
+        return {
+            residual: [
+                (state.enthalpy - h) / hScale,
+                (state.entropy - s) / sScale,
+            ],
+            jacobian: [
+                [derivatives.dhDp / hScale, derivatives.dhDT / hScale],
+                [derivatives.dsDp / sScale, derivatives.dsDT / sScale],
+            ],
+        };
+    }, initial, {
+        isValid: ([candidateP, candidateT]) => candidateP > 0 && candidateT > 0,
+    });
+    return stateAt(p, T);
+}
+function solveRegion3HS(h, s, rho0, T0) {
+    const hScale = Math.max(1, Math.abs(h));
+    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.enthalpy - h) / hScale,
+                (state.entropy - s) / sScale,
+            ],
+            jacobian: [
+                [derivatives.dhDrho / hScale, derivatives.dhDT / hScale],
+                [derivatives.dsDrho / sScale, derivatives.dsDT / sScale],
+            ],
+        };
+    }, [rho0, T0], {
+        // Tighter than the 1e-10 default and load-bearing: near the 100 MPa ceiling
+        // Region 3 is nearly incompressible, so a residual the default would accept
+        // still lands p far enough outside [P_MIN, P_MAX] to fail envelope
+        // validation. Covered by the p=100 MPa cases in newton-regressions.test.ts.
+        tolerance: 1e-12,
+        isValid: ([candidateRho, candidateT]) => candidateRho > 0 && candidateT > 0,
+    });
+    return region3ByRhoT(rho, T);
 }
 // ─── Main HS Solver ─────────────────────────────────────────────────────────
 /**
@@ -191,53 +220,46 @@ export function solveHS(h, s) {
         throw new OutOfRangeError('Entropy', s, C.S_MIN, C.S_MAX);
     }
     assertCriticalRegion4HSInput(h, s, 'solveHS');
-    const region4State = tryRegion4HSState(h, s);
-    if (region4State !== null) {
-        return validateBackwardState(region4State, [
-            { label: 'enthalpy', expected: h },
-            { label: 'entropy', expected: s },
-        ], { solverName: 'solveHS', expectedRegion: Region.Region4 });
-    }
     const region = detectRegionHS(h, s);
     switch (region) {
         case Region.Region1: {
             const P0 = r1Phs(h, s);
-            const sol = nelderMead((pair) => Math.abs(region1(pair[0], pair[1]).enthalpy - h) +
-                Math.abs(region1(pair[0], pair[1]).entropy - s), [P0, 400]);
-            return validateBackwardState(region1(sol.x[0], sol.x[1]), [
+            const state = solveGibbsHS(h, s, [P0, r1BackwardT(P0, h)], region1);
+            return validateBackwardState(state, [
                 { label: 'enthalpy', expected: h },
                 { label: 'entropy', expected: s },
             ], { solverName: 'solveHS', expectedRegion: Region.Region1 });
         }
         case Region.Region2: {
             const P0 = r2Phs(h, s);
-            const T0 = newtonRaphson((T) => region2(P0, T).enthalpy - h, 500);
-            const sol = nelderMead((pair) => Math.abs(region2(pair[0], pair[1]).enthalpy - h) +
-                Math.abs(region2(pair[0], pair[1]).entropy - s), [P0, T0]);
-            return validateBackwardState(region2(sol.x[0], sol.x[1]), [
+            const state = solveGibbsHS(h, s, [P0, r2BackwardT(P0, h)], region2);
+            return validateBackwardState(state, [
                 { label: 'enthalpy', expected: h },
                 { label: 'entropy', expected: s },
             ], { solverName: 'solveHS', expectedRegion: Region.Region2 });
         }
         case Region.Region3: {
             const P0 = r3Phs(h, s);
-            const init = solvePH(P0, h);
-            const rho0 = 1 / init.specificVolume;
-            const T0 = init.temperature;
-            const sol = nelderMead((pair) => Math.abs(region3ByRhoT(pair[0], pair[1]).enthalpy - h) +
-                Math.abs(region3ByRhoT(pair[0], pair[1]).entropy - s), [rho0, T0]);
-            return validateBackwardState(region3ByRhoT(sol.x[0], sol.x[1]), [
+            const initial = r3BackwardPHInitial(P0, h);
+            const state = solveRegion3HS(h, s, initial.rho, initial.T);
+            return validateBackwardState(state, [
                 { label: 'enthalpy', expected: h },
                 { label: 'entropy', expected: s },
             ], { solverName: 'solveHS', expectedRegion: Region.Region3 });
         }
         case Region.Region4: {
-            throw new IF97Error('solveHS identified Region 4 but failed to construct a valid saturation state');
+            const state = tryRegion4HSState(h, s);
+            if (state === null) {
+                throw new IF97Error('solveHS identified Region 4 but failed to construct a valid saturation state');
+            }
+            return validateBackwardState(state, [
+                { label: 'enthalpy', expected: h },
+                { label: 'entropy', expected: s },
+            ], { solverName: 'solveHS', expectedRegion: Region.Region4 });
         }
         case Region.Region5: {
-            const objective = normalizedRegion5HsObjective(h, s);
-            const sol = nelderMead(objective, [1, 1400], { maxIterations: 1000, minErrorDelta: 1e-8, minTolerance: 1e-9 });
-            return validateBackwardState(region5(sol.x[0], sol.x[1]), [
+            const state = solveGibbsHS(h, s, [1, 1400], region5);
+            return validateBackwardState(state, [
                 { label: 'enthalpy', expected: h },
                 { label: 'entropy', expected: s },
             ], { solverName: 'solveHS', expectedRegion: Region.Region5 });
@@ -246,4 +268,3 @@ export function solveHS(h, s) {
             throw new IF97Error(`Cannot determine region for h=${h} kJ/kg, s=${s} kJ/(kg·K)`);
     }
 }
-//# sourceMappingURL=hs.js.map