Major Changes

New Electrolyte Engine - phreeqc2026

This release features a new interface to IPHREEQC developed by @vineetbansal of Princeton University's Research Software Engineering group. This new interface "talks" directly to the USGS-provided IPHREEQC libraries, providing a much more robust way of accessing PHREEQC functionality via pyEQL as compared to the legacy engine based on phreeqpython. This new engine can be specified by passing engine='phreeqc2026' to Solution.__init__. Thanks to pyEQL's modular API, no other changes to your script are needed - it is a "drop-in" replacement for the legacy phreeqc engine.

The legacy phreeqc engine is still present and is still used for speciation by the default native engine. However, the native engine will adopt phreeqc2026 for speciation calculations in the next release. You may see a warning about this when you call equilibrate().

Solid-liquid and gas-liquid equilibrium

The equilibrate() method now supports equilibrating a Solution with gas and/or solid phases, thanks to work by @vineetbansal , @SuixiongTay , and @YitongPan1 . In addition to user-specified phases, a convenience argument atmosphere has been added if you simply want to consider the effects of, e.g., atmospheric carbonate on your system:

>>> from pyEQL import Solution

>>> s1 = Solution({}, pH=7.0, volume="1 L", engine="phreeqc2026")
>>> s1.equilibrate(atmosphere=True)
>>> s1.components
{'H2O(aq)': 55.34457593619076,
'O2(aq)': 0.0002675300582572652,
'CO2(aq)': 1.424944456303147e-05,
'H[+1]': 2.51988623743169e-06,
'HCO3[-1]': 2.5169971787125935e-06,
'OH[-1]': 4.007874338794804e-09,
'CO3[-2]': 4.7053998717451746e-11, 
...}

The new equilibrate capabilities work across all engines - native, phreeqc, and phreeqc2026

Performance

Loading times for Solution that contain a large number of solutes have been significantly improved (by a factor of ~10x in some cases) thanks to a caching optimization identified by @vineetbansal .

See additional details in the CHANGELOG.

<!-- Release notes generated using configuration in .github/release.yml at main -->

What's Changed

🐛 Bug Fixes

• Fix behavior of PHREEQC equilibrate when composition contains pure elements by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/282
• Fix incorrect reduction of dimers/polymers in standardize_formula by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/309
• phreeqc2026 engine: ensure unit osmotic coefficient; refactor tests by @rkingsbury in https://github.com/KingsburyLab/pyEQL/pull/333
• from_file: address subtle volume bug by @rkingsbury in https://github.com/KingsburyLab/pyEQL/pull/347
• Use to_file to generate yaml by @SuixiongTay in https://github.com/KingsburyLab/pyEQL/pull/350
• Remove N2 from ATMOSPHERE by @SuixiongTay in https://github.com/KingsburyLab/pyEQL/pull/339
• equilibrate: exclude H and O from missing element check by @rkingsbury in https://github.com/KingsburyLab/pyEQL/pull/355

🛠 Enhancements

• added a nested parameter to 2 methods in the Solution class by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/284
• enable solid-liquid and gas-liquid equilibrium calculations in equilibrate() by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/292
• Speciation calculations in new wrapper by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/306
• Fix the postprocess workflow; refactor PHREEQC2026 wrapper by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/318
• Watching for Phreeqc invocation errors by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/319
• Solution.from_preset: Add representative industrial wastewaters by @SuixiongTay in https://github.com/KingsburyLab/pyEQL/pull/317
• PhreeqcEOS inherits from Phreeqc2026EOS by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/351
• equilibrate: modify total conc check for missing elements by @rkingsbury in https://github.com/KingsburyLab/pyEQL/pull/352
• engines.py: NativeEOS inherits from PhreeqcEOS; eliminate redundant code by @rkingsbury in https://github.com/KingsburyLab/pyEQL/pull/353

📖 Documentation

• migrate docs theme to sphinx-immaterial by @rkingsbury in https://github.com/KingsburyLab/pyEQL/pull/272
• Update Solution.equilibrate()'s docstring with NativeEOS.equilibrate() docstring by @SuixiongTay in https://github.com/KingsburyLab/pyEQL/pull/344
• Phreeqc2026 docs by @SuixiongTay in https://github.com/KingsburyLab/pyEQL/pull/349

🧹 House-Keeping

• Vb/noblack by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/285

🏥 Package Health

• CI run with pinned deps common to all py/platforms by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/314
• Release Workflow for CI by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/320

🤷‍♂️ Other Changes

• Add pqi_pqo_files to tests by @SuixiongTay in https://github.com/KingsburyLab/pyEQL/pull/289
• 'PHREEQC' pytest by @SuixiongTay in https://github.com/KingsburyLab/pyEQL/pull/294
• Phreeqc wrapper by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/291
• Bump actions/checkout from 5 to 6 in the actions group by @dependabot[bot] in https://github.com/KingsburyLab/pyEQL/pull/293
• Bump urllib3 from 2.5.0 to 2.6.0 in /requirements by @dependabot[bot] in https://github.com/KingsburyLab/pyEQL/pull/298
• Bump urllib3 from 2.6.0 to 2.6.3 in /requirements by @dependabot[bot] in https://github.com/KingsburyLab/pyEQL/pull/308
• Bump pynacl from 1.5.0 to 1.6.2 in /requirements by @dependabot[bot] in https://github.com/KingsburyLab/pyEQL/pull/307
• Bump filelock from 3.16.0 to 3.20.1 in /requirements by @dependabot[bot] in https://github.com/KingsburyLab/pyEQL/pull/305
• Bump fonttools from 4.53.1 to 4.60.2 in /requirements by @dependabot[bot] in https://github.com/KingsburyLab/pyEQL/pull/304
• Bump virtualenv from 20.26.4 to 20.36.1 in /requirements by @dependabot[bot] in https://github.com/KingsburyLab/pyEQL/pull/312
• Bump filelock from 3.20.1 to 3.20.3 in /requirements by @dependabot[bot] in https://github.com/KingsburyLab/pyEQL/pull/313
• Diffusion Coefficient from Phreeqc by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/316
• Bump the actions group with 3 updates by @dependabot[bot] in https://github.com/KingsburyLab/pyEQL/pull/321
• Test new release workflow by @rkingsbury in https://github.com/KingsburyLab/pyEQL/pull/322
• Test release workflow, take 2 by @rkingsbury in https://github.com/KingsburyLab/pyEQL/pull/323
• bump the tag in changelog by @rkingsbury in https://github.com/KingsburyLab/pyEQL/pull/324
• Release rc4 by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/325
• Triggering release on published action by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/327
• updating basic tools before twine upload by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/328
• Patch for trusted publishing by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/330
• Bump cryptography from 46.0.3 to 46.0.5 by @dependabot[bot] in https://github.com/KingsburyLab/pyEQL/pull/334
• Fixing warnings on docs generation by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/338
• Bump pillow from 12.1.0 to 12.1.1 by @dependabot[bot] in https://github.com/KingsburyLab/pyEQL/pull/341
• Pulled out lint+docs as its own workflow; Other workflows ignore docs folder by @vineetbansal in https://github.com/KingsburyLab/pyEQL/pull/340
• utils: ensure python floats in FormulaDict by @rkingsbury in https://github.com/KingsburyLab/pyEQL/pull/342
• Adjust DeprecationWarning by @SuixiongTay in https://github.com/KingsburyLab/pyEQL/pull/348
• Add the to_phreeqc() method by @SuixiongTay in https://github.com/KingsburyLab/pyEQL/pull/288
• update CHANGELOG and AUTHORS for v1.4.0 release by @rkingsbury in https://github.com/KingsburyLab/pyEQL/pull/356

New Contributors

• @vineetbansal made their first contribution in https://github.com/KingsburyLab/pyEQL/pull/284

Full Changelog: https://github.com/KingsburyLab/pyEQL/compare/v1.3.2...v1.4.0