waterEoS 0.6.0

Overview

waterEoS is a Rust-accelerated Python package for computing thermodynamic and transport properties of supercooled water. It implements six supercooled-water equation-of-state models — Holten (2014), Caupin (2019), Duška (2020), Shi & Tanaka (2020), Grenke (2025), and Singh (2017) — and provides pass-through access to SeaFreeze water1 and IAPWS-95, all under a single SeaFreeze-compatible API.

Two-state equations of state

Liquid water's thermodynamic anomalies (density maximum, diverging compressibility and heat capacity upon supercooling) can be explained by treating water as a mixture of two interconvertible local structures: a high-density, disordered structure (state A) and a low-density, tetrahedral structure (state B). These "two-state" models predict a liquid-liquid critical point (LLCP) deep in the supercooled regime, below which water can separate into two distinct liquid phases (HDL-rich and LDL-rich). waterEoS implements four such models:

• Holten, Sengers & Anisimov (2014) -- The foundational two-state EOS for supercooled water. Uses a Gibbs-energy (pressure-additive) mixing rule, fitted to experimental data at positive pressures up to 400 MPa. Places the LLCP at 228 K, 0 MPa.
• Caupin & Anisimov (2019) -- Extends the two-state framework to negative pressures (stretched water), connecting the liquid-liquid spinodal to the liquid-vapor spinodal in a unified description. Places the LLCP at 218 K, 72 MPa. An optional caupin2019_kim variant uses the with-Kim parameter set from Table II of the same paper, which incorporates the Kim et al. (2017) X-ray scattering data and places the LLCP at 219 K, 59 MPa.
• Duska (2020) -- Uses a volume-additive mixing rule (rather than Gibbs-energy mixing), yielding an explicit equation of state in volume and temperature ("EOS-VaT"). Fitted over a broader temperature range up to 370 K. Places the LLCP at 221 K, 54 MPa.
• Shi & Tanaka (2020) -- A hierarchical two-state EOS in which the order parameter is built from a coarse-grained "locally favored structure" fraction. Reproduces the IAPWS-95 liquid surface to ~0.05% in density and places the LLCP well below experimentally accessible temperatures, at 184 K, 173 MPa, so that the observed anomalies are attributed to the two-state feature itself rather than proximity to the critical point.

All four return 43 thermodynamic properties: 15 mixture properties, 14 per state (A and B), plus the tetrahedral fraction x.

Additional models

• Grenke & Elliott (2025) -- An empirical Tait-Tammann correlation for supercooled water (not a two-state model). Returns standard thermodynamic properties without per-state decomposition.
• Singh, Issenmann & Caupin (2017) -- A two-state transport model that predicts viscosity, self-diffusion coefficient, and rotational correlation time. Uses Holten (2014) as its thermodynamic backbone.
• Shi & Tanaka (2020) transport -- A companion transport model (shi_tanaka2020_transport) for viscosity, self-diffusion, and rotational relaxation, coupled to the same hierarchical two-state framework as shi_tanaka2020 rather than to Holten. Returns all shi_tanaka2020 thermodynamic outputs plus eta, D, and tau_r.
• SeaFreeze water1 -- A pass-through to SeaFreeze's GLBF tensor-product B-spline representation of liquid water (Journaux et al., 2020). Valid 240–501 K, 0–2300 MPa.
• IAPWS-95 -- A pass-through to the IAPWS-95 reference equation of state for ordinary water (Wagner & Pruß, 2002), accessed via the same SeaFreeze GLBF spline machinery. Provides the canonical reference values that the supercooled-water models above are aligned to.

Web App

Try waterEoS interactively at watereos-visualizer.up.railway.app

The web app includes a Property Explorer, an EoS phase diagram viewer (per model: spinodals, binodal, LLCP, TMD, Widom line, Kauzmann, ice liquidus, homogeneous nucleation), an H₂O solid-liquid-vapor phase diagram with T–V, T–P, and 3-D P–T–V projections (Liquid + Ice Ih, II, III, V, VI, VII/X + Vapor, with L–V saturation and Ih–V sublimation curves), a model comparison tool, and a point calculator.

The waterEoS web app — a unified toolkit for ten equation-of-state models.

3D density surface for Duska (2020) with phase boundaries and interactive hover.

Specific volume isobars with spinodal, binodal, and LLCP for Duska (2020).

3D P-T-V phase diagram of H₂O showing stability fields for liquid water, Ice Ih, II, III, V, and VI.

Installation

pip install waterEoS

Pre-built wheels for Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), and Windows include the compiled Rust backend automatically. On other platforms, pip installs from source with a pure Python fallback.

Quick Start

import numpy as np
from watereos import getProp

# Single point: 0.1 MPa, 300 K
PT = np.array([[0.1], [300.0]], dtype=object)
out = getProp(PT, 'duska2020')
print(f"Density: {out.rho[0,0]:.2f} kg/m³")
print(f"Cp:      {out.Cp[0,0]:.1f} J/(kg·K)")
print(f"x:       {out.x[0,0]:.4f}")

Simple API

For quick calculations without constructing SeaFreeze-style arrays, use compute():

from watereos import compute

out = compute(T_K=300, P_MPa=0.1, model='caupin2019')
print(f"Density: {out.rho[0,0]:.2f} kg/m³")

# Also accepts arrays (evaluates on the full P x T grid)
out = compute(T_K=[250, 275, 300], P_MPa=[0.1, 50, 100], model='holten2014')
# out.rho has shape (3, 3)

Available Models

Validity Ranges

The three two-state models accept any (T, P) input without raising errors, but results are only physically meaningful within the ranges below. The "paper-stated" range is where each model was validated by its authors; the "code-accessible" range is where the code runs without numerical failure (though results outside the paper range may be unphysical).

Notes:

• T_H(P) is the homogeneous ice nucleation temperature (~235 K at 0.1 MPa, ~181 K at 200 MPa).
• Duska (2020) was fitted to data at positive pressures only; negative-pressure extrapolation is unvalidated.
• Caupin (2019) is the only model explicitly validated at negative pressures (stretched water).
• Grenke (2025) is a direct empirical Tait-Tammann correlation, not a two-state model. It has no x, _A, or _B outputs.
• Singh (2017) is a transport properties model that uses Holten (2014) as its thermodynamic backbone. It returns all Holten thermodynamic properties plus eta, D, and tau_r. Its validity range matches Holten (2014).
• Shi & Tanaka (2020) is the only two-state model in waterEoS that places the LLCP well below experimentally accessible temperatures (184 K vs ~220 K for Holten/Caupin/Duska); the paper argues that the LLCP has negligible impact on observed anomalies in the liquid regime, which are instead driven by the two-state feature itself.
• shi_tanaka2020_transport uses the same hierarchical two-state framework as shi_tanaka2020 for its dynamic order parameter, so its transport predictions (viscosity, self-diffusion, rotational relaxation) are internally consistent with its own thermodynamics — distinct from singh2017, which couples Singh's Arrhenius law to a Holten (2014) thermo backbone.
• getProp() and compute() issue a UserWarning when inputs fall outside the suggested validity range. Results outside these ranges may be unphysical (e.g., negative compressibility or heat capacity).

Key Concepts

Usage

Grid Mode

Evaluate on a pressure x temperature grid (like SeaFreeze):

import numpy as np
from watereos import getProp

P = np.arange(0.1, 200, 10)    # pressures in MPa
T = np.arange(250, 370, 1)     # temperatures in K
PT = np.array([P, T], dtype=object)

out = getProp(PT, 'holten2014')
# out.rho has shape (len(P), len(T))

Scatter Mode

Evaluate at specific (P, T) pairs:

import numpy as np
from watereos import getProp

PT = np.empty(3, dtype=object)
PT[0] = (0.1, 273.15)    # 0.1 MPa, 273.15 K
PT[1] = (0.1, 298.15)    # 0.1 MPa, 298.15 K
PT[2] = (100.0, 250.0)   # 100 MPa, 250 K

out = getProp(PT, 'caupin2019')
# out.rho has shape (3,)

Individual Model Access

Each model can also be imported directly:

from duska_eos import getProp
from caupin_eos import getProp
from holten_eos import getProp
from grenke_eos import getProp
from singh_viscosity import getProp

List Available Models

from watereos import list_models
print(list_models())
# ['water1', 'IAPWS95', 'holten2014', 'caupin2019', 'caupin2019_kim', 'duska2020',
#  'grenke2025', 'singh2017', 'shi_tanaka2020', 'shi_tanaka2020_transport']

Output Properties

All models return an object with the following attributes (the three two-state models also include x, _A, and _B suffixed properties; grenke2025 returns only the mixture properties):

Mixture (equilibrium) properties

Per-state properties

Each property above (except x) is also available for the individual states with _A and _B suffixes:

• rho_A, Cp_A, vel_A, ... (State A: high-density / disordered)
• rho_B, Cp_B, vel_B, ... (State B: low-density / tetrahedral)

Total: 43 output properties (15 mixture + 14 state A + 14 state B).

All thermodynamic potentials (S, G, H, U, A) are aligned to the IAPWS-95 reference state.

Transport properties (singh2017 only)

The singh2017 model also returns all Holten (2014) thermodynamic properties listed above.

Phase Diagram

Each model provides functions to compute the liquid-liquid phase diagram:

from duska_eos import compute_phase_diagram

result = compute_phase_diagram()
# result contains: T_LLCP, p_LLCP, T_spin_upper, p_spin_upper,
#                  T_spin_lower, p_spin_lower, T_binodal, p_binodal, ...

Available functions: find_LLCP(), compute_spinodal_curve(), compute_binodal_curve(), compute_phase_diagram().

H₂O solid-liquid-vapor phase diagram

The package also computes the full H₂O solid-liquid-vapor phase diagram (Liquid + Ice Ih, II, III, V, VI, VII/X + Vapor) and emits ready-to-render Plotly figures for the T–V, T–P, and 3-D P–T–V projections:

from watereos.tv_phase_diagram import (
    compute_tv_phase_diagram,
    plot_tv_phase_diagram_plotly,
    plot_tp_phase_diagram_plotly,
    plot_ptv_phase_diagram_plotly,
)

diagram = compute_tv_phase_diagram(T_min=190, T_max=353.5, dT=1.0)
# diagram contains: phase_fields (per-phase V_min/V_max vs T),
#                   two_phase_bounds (coexistence curves),
#                   invariants (triple points),
#                   saturation (IAPWS-95 L-V), sublimation (IAPWS R14-08 Ih-V).

fig_tv  = plot_tv_phase_diagram_plotly(diagram, V_min=7e-4, V_max=1.1e-3)
fig_tp  = plot_tp_phase_diagram_plotly(diagram, T_min=190, T_max=300,
                                        P_min=1e-4, P_max=1000)
fig_3d  = plot_ptv_phase_diagram_plotly(diagram, V_min=7e-4, V_max=1.1e-3,
                                         P_max=1000)

The diagram is built by isothermal convex-hull sweeps in (V, A) space across the SeaFreeze ice phases, water1, and an ideal-gas vapor branch anchored at IAPWS-95 saturation. Each common-tangent point is then Newton-refined to the exact analytical condition G_A(T, P) = G_B(T, P), so the boundary curves are smooth and free of EoS-discretisation kinks. Three-phase invariants (triple points) are detected from topology changes between adjacent T-slices and rendered as 3-phase coexistence lines.

Troubleshooting

import warnings
warnings.filterwarnings('ignore', message='waterEoS')

from watereos import compute
out = compute(273.15, 0.1, 'duska2020')
# If using Rust, computation is 2-5x faster; no visible difference in output

References

1. V. Holten, J. V. Sengers, and M. A. Anisimov, "Equation of state for supercooled water at pressures up to 400 MPa," J. Phys. Chem. Ref. Data 43, 014101 (2014). doi:10.1063/1.4895593

2. F. Caupin and M. A. Anisimov, "Thermodynamics of supercooled and stretched water: Unifying two-structure description and liquid-vapor spinodal," J. Chem. Phys. 151, 034503 (2019). doi:10.1063/1.5100228

   • Erratum: J. Chem. Phys. 163, 039902 (2025). doi:10.1063/5.0239673

3. M. Duska, "Water above the spinodal," J. Chem. Phys. 152, 174501 (2020). doi:10.1063/5.0006431

4. R. Shi and H. Tanaka, "The anomalies and criticality of liquid water," Proc. Natl. Acad. Sci. U.S.A. 117, 26591-26599 (2020). doi:10.1073/pnas.2008426117 -- Source of both shi_tanaka2020 (thermodynamic EoS, Table S2 of the SI) and shi_tanaka2020_transport (viscosity / self-diffusion / rotational relaxation, Table S3 of the SI).

5. J. C. Grenke and J. R. Elliott, "Empirical fundamental equation of state for the metastable state of water based on the Tait-Tammann equation," J. Phys. Chem. B 129, 1997-2012 (2025). doi:10.1021/acs.jpcb.4c06847

   • Correction: J. Phys. Chem. B 129, 9850-9853 (2025). doi:10.1021/acs.jpcb.5c04618

6. L. P. Singh, B. Issenmann, and F. Caupin, "Pressure dependence of viscosity in supercooled water and a unified approach for thermodynamic and dynamic anomalies of water," Proc. Natl. Acad. Sci. U.S.A. 114, 4312-4317 (2017). doi:10.1073/pnas.1619501114

7. B. Journaux, J. M. Brown, A. Pacheco, S. D. Vance, A. Cochrane, T. Bollengier, et al., "Holistic approach for studying planetary hydrospheres: Gibbs representations, ices thermodynamics, transport, and the example of Europa," J. Geophys. Res.: Planets 125, e2019JE006176 (2020). doi:10.1029/2019JE006176 -- Source of the SeaFreeze GLBF tensor-product B-spline coefficients used for water1, IAPWS95, and the ice phases (Ih, II, III, V, VI, VII/X) in the H₂O solid-liquid-vapor phase diagram.

8. W. Wagner and A. Pruß, "The IAPWS Formulation 1995 for the Thermodynamic Properties of Ordinary Water Substance for General and Scientific Use," J. Phys. Chem. Ref. Data 31, 387 (2002). doi:10.1063/1.1461829 -- Cited as IAPWS-95 throughout; reference EoS for water/vapor used for reference-state alignment and the saturation/triple-point lines in the H₂O phase diagram.

9. W. Wagner, T. Riethmann, R. Feistel, and A. H. Harvey, "New Equations for the Sublimation Pressure and Melting Pressure of H₂O Ice Ih," J. Phys. Chem. Ref. Data 40, 043103 (2011). doi:10.1063/1.3657937 -- IAPWS R14-08 sublimation pressure correlation used for the Ice Ih/vapor boundary below 273.16 K in the H₂O phase diagram.

Authors

• Anthony Consiglio <aconsiglio4@berkeley.edu>

Citing waterEoS

If you use waterEoS in your research, please cite both this package and the underlying EoS papers. Each model implemented in waterEoS has its own published reference (Holten 2014, Caupin 2019, Duska 2020, Shi & Tanaka 2020, Grenke 2025, Singh 2017, Journaux 2020, Wagner & Pruß 2002) listed in the References section above; please cite the original papers for the specific models you use, in addition to this software package.

BibTeX entry for the software package:

@software{consiglio_watereos_2026,
  author       = {Consiglio, Anthony},
  title        = {{waterEoS}: Thermodynamic equations of state for supercooled water},
  year         = {2026},
  url          = {https://github.com/anthony-consiglio/waterEoS},
  version      = {0.6.0},
  license      = {GPL-3.0-only},
}

A machine-readable citation in Citation File Format is also provided in CITATION.cff.

License

This project is licensed under the GNU General Public License v3.0.