pyEQL 1.4.0rc9__cp311-cp311-macosx_10_9_x86_64.whl

pyEQL/utils.py

@@ -0,0 +1,237 @@
+"""
+pyEQL utilities
+
+:copyright: 2013-2024 by Ryan S. Kingsbury
+:license: LGPL, see LICENSE for more details.
+
+"""
+
+import logging
+import re
+from collections import UserDict
+from functools import lru_cache
+from typing import Any
+
+from iapws import IAPWS95, IAPWS97
+from pymatgen.core.ion import Ion
+
+from pyEQL import ureg
+
+logger = logging.getLogger(__name__)
+
+
+def interpret_units(unit: str) -> str:
+    """
+    Translate commonly used environmental units such as 'ppm' into strings that `pint` can understand.
+
+    Args:
+        unit: string representing the unit to translate
+
+    Returns: a unit that pint can understand
+    """
+    if unit == "m":  # molal
+        return "mol/kg"
+    if unit == "ppm":
+        return "mg/L"
+    if unit == "ppb":
+        return "ug/L"
+    if unit == "ppt":
+        return "ng/L"
+    # if all else fails, return the unit we were provided
+    return unit
+
+
+@lru_cache
+def standardize_formula(formula: str):
+    """
+    Convert a chemical formula into standard form.
+
+    Args:
+        formula: the chemical formula to standardize.
+
+    Returns:
+        A standardized chemical formula
+
+    Raises:
+        ValueError if `formula` cannot be processed or is invalid.
+
+    Notes:
+        Currently this method standardizes formulae by passing them through `pymatgen.core.ion.Ion.reduced_formula()`.
+        For ions, this means that 1) the charge number will always be listed explicitly and 2) the charge number will
+        be enclosed in square brackets to remove any ambiguity in the meaning of the formula. For example, 'Na+',
+        'Na+1', and 'Na[+]' will all standardize to "Na[+1]"
+    """
+    # fix permuted sign and charge number (e.g. Co2+)
+    for str, rep in zip(["²⁺", "³⁺", "⁴⁺", "²⁻", "³⁻", "⁴⁻"], ["+2", "+3", "+4", "-2", "-3", "-4"], strict=False):
+        formula = formula.replace(str, rep)
+
+    # replace superscripts with non superscripts
+    for char, rep in zip("⁻⁺⁰¹²³⁴⁵⁶⁷⁸⁹", "-+0123456789", strict=False):
+        formula = formula.replace(char, rep)
+
+    # replace subscripts with non subscripts
+    for char, rep in zip("₀₁₂₃₄₅₆₇₈₉", "0123456789", strict=False):
+        formula = formula.replace(char, rep)
+
+    # replace different types of dashes with a minus sign
+    for char in [r"‑", r"‐", r"‒", r"–", r"—", r"−"]:  # noqa: RUF001
+        formula = formula.replace(char, "-")
+
+    # Do not modify any dimers etc (Phreeqc reports a small amount of
+    # "(CO2)2" in a water solution with C(4), for example.
+    _POLYMER_RE = re.compile(r"^\([A-Za-z0-9+-]+\)\d+$")
+    if _POLYMER_RE.match(formula):
+        return formula
+
+    sform = Ion.from_formula(formula).reduced_formula
+
+    # TODO - manual formula adjustments. May be implemented upstream in pymatgen in the future
+    # thanks to @xiaoxiaozhu123 for pointing out these issues in
+    # https://github.com/KingsburyLab/pyEQL/issues/136
+
+    # ammonia
+    if sform == "H4N[+1]":
+        sform = "NH4[+1]"
+    elif "H4NCl" in sform:
+        sform = sform.replace("H4NCl", "NH4Cl")
+    elif sform == "SO3[-1]":
+        sform = "S2O6[-2]"
+    elif sform == "SO4[-1]":
+        sform = "S2O8[-2]"
+    elif sform == "H3N(aq)":
+        sform = "NH3(aq)"
+    # phosphoric acid system
+    elif sform == "PH3O4(aq)":
+        sform = "H3PO4(aq)"
+    elif "PHO4" in sform:
+        sform = sform.replace("PHO4", "HPO4")
+    elif "P(HO2)2" in sform:
+        sform = sform.replace("P(HO2)2", "H2PO4")
+    # thiocyanate
+    elif "CSN" in sform:
+        sform = sform.replace("CSN", "SCN")
+    # triiodide, nitride, an phosphide
+    elif sform == "I[-0.33333333]":
+        sform = "I3[-1]"
+    elif sform == "N[-0.33333333]":
+        sform = "N3[-1]"
+    elif sform == "P[-0.33333333]":
+        sform = "P3[-1]"
+    # formate
+    elif sform == "HCOO[-1]":
+        sform = "HCO2[-1]"
+    # oxalate
+    elif sform == "CO2[-1]":
+        sform = "C2O4[-2]"
+    # triflate
+    elif sform == "CS(OF)3[-1]":
+        sform = "CF3SO3[-1]"
+    # haloacetic acids of F, Cl, Br, I
+    elif sform == "C2Cl3O2[-1]":
+        sform = "CCl3COO[-1]"
+    elif sform == "C2O2F3[-1]":
+        sform = "CF3COO[-1]"
+    elif sform == "C2I3O2[-1]":
+        sform = "CI3COO[-1]"
+    elif sform == "C2Br3O2[-1]":
+        sform = "CBr3COO[-1]"
+
+    # Cl+F
+    elif sform == "C2Cl2O2F[-1]":
+        sform = "CFCl2COO[-1]"
+    elif sform == "C2Cl(OF)2[-1]":
+        sform = "CF2ClCOO[-1]"
+
+    # Cl+Br
+    elif sform == "C2Br(ClO)2[-1]":
+        sform = "CBrCl2COO[-1]"
+    elif sform == "C2Br2ClO2[-1]":
+        sform = "CBr2ClCOO[-1]"
+
+    # Cl+I
+    elif sform == "C2I(ClO)2[-1]":
+        sform = "CICl2COO[-1]"
+    elif sform == "C2I2ClO2[-1]":
+        sform = "CI2ClCOO[-1]"
+
+    # ammonium nitrate salts
+    elif sform == "H4N2O3(aq)":
+        sform = "NH4NO3(aq)"
+    # ammonium sulfate salts
+    elif sform == "H8S(NO2)2(aq)":
+        sform = "(NH4)2SO4(aq)"
+    elif sform == "H4SNO4[-1]":
+        sform = "NH4SO4[-1]"
+
+    # TODO - consider adding recognition of special formulas like MeOH for methanol or Cit for citrate
+    return sform
+
+
+def format_solutes_dict(solute_dict: dict, units: str):
+    """
+    Formats a dictionary of solutes by converting the amount to a string with the provided units suitable for passing to
+    use with the Solution class. Note that all solutes must be given in the same units.
+
+    Args:
+        solute_dict: The dictionary to format. This must be of the form dict{str: Number}
+            e.g. {"Na+": 0.5, "Cl-": 0.9}
+        units: The units to use for the solute. e.g. "mol/kg"
+
+    Returns:
+        A formatted solute dictionary.
+
+    Raises:
+        TypeError if `solute_dict` is not a dictionary.
+    """
+    if not isinstance(solute_dict, dict):
+        raise TypeError("solute_dict must be a dictionary. Refer to the doc for proper formatting.")
+
+    return {key: f"{value!s} {units}" for key, value in solute_dict.items()}
+
+
+@lru_cache
+@ureg.wraps(ret=None, args=["K", "MPa"], strict=False)
+def create_water_substance(temperature: float, pressure: float):
+    """
+    Instantiate a water substance model from IAPWS.
+
+    Args:
+        temperature: the desired temperature in K
+        pressure: the desired pressure in MPa
+
+    Notes:
+        The IAPWS97 model is much faster than IAPWS95, but the latter can do temp
+        below zero. See https://github.com/jjgomera/iapws/issues/14. Hence,
+        IAPWS97 will be used except when `temperature` is less than 0 degC.
+
+    Returns:
+        A IAPWS97 or IAPWS95 instance
+    """
+    if temperature >= 273.15:
+        return IAPWS97(T=temperature, P=pressure)
+    return IAPWS95(T=temperature, P=pressure)
+
+
+class FormulaDict(UserDict):
+    """
+    Automatically converts keys on get/set using pymatgen.core.Ion.from_formula(key).reduced_formula.
+
+    This allows getting/setting/updating of Solution.components using flexible
+    formula notation (e.g., "Na+", "Na+1", "Na[+]" all have the same effect)
+    """
+
+    def __getitem__(self, key) -> Any:
+        return super().__getitem__(standardize_formula(key))
+
+    def __setitem__(self, key, value) -> None:
+        super().__setitem__(standardize_formula(key), value)
+        # sort contents anytime an item is set
+        self.data = dict(sorted(self.items(), key=lambda x: x[1], reverse=True))
+
+    # Necessary to define this so that .get() works properly in python 3.12+
+    # see https://github.com/python/cpython/issues/105524
+    def __contains__(self, key) -> bool:
+        return standardize_formula(key) in self.data
+
+    def __delitem__(self, key) -> None:
+        super().__delitem__(standardize_formula(key))

pyeql-1.4.0rc9.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: pyEQL
+Version: 1.4.0rc9
+Summary: A python interface for solution chemistry
+Author-Email: Ryan Kingsbury <kingsbury@princeton.edu>
+License-Expression: LGPL-3.0-or-later
+License-File: AUTHORS.md
+License-File: LICENSE.txt
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Project-URL: Docs, https://pyeql.readthedocs.io/
+Project-URL: Repo, https://github.com/KingsburyLab/pyEQL
+Project-URL: Package, https://pypi.org/project/pyEQL
+Requires-Python: >=3.10
+Requires-Dist: pint>=0.24.4
+Requires-Dist: numpy>1.26
+Requires-Dist: scipy>=1.12
+Requires-Dist: pymatgen>=2025.1.9
+Requires-Dist: iapws>=1.5.3
+Requires-Dist: monty>=2024.12.10
+Requires-Dist: maggma>=0.71.4
+Requires-Dist: phreeqpython>=1.5.2
+Provides-Extra: testing
+Requires-Dist: setuptools>=68; extra == "testing"
+Requires-Dist: pre-commit>=2; extra == "testing"
+Requires-Dist: pytest>=7; extra == "testing"
+Requires-Dist: pytest-cov>=2.11; extra == "testing"
+Requires-Dist: pytest-xdist>2; extra == "testing"
+Requires-Dist: black; extra == "testing"
+Requires-Dist: mypy>1; extra == "testing"
+Requires-Dist: ruff>0.0.100; extra == "testing"
+Requires-Dist: tox<4; extra == "testing"
+Provides-Extra: docs
+Requires-Dist: sphinx>=3.2.1; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: myst-parser[linkify]; extra == "docs"
+Provides-Extra: full
+Requires-Dist: rich; extra == "full"
+Description-Content-Type: text/markdown
+
+[![Read the Docs](https://img.shields.io/readthedocs/pyeql)](https://pyeql.readthedocs.io/en/latest/)
+[![testing](https://github.com/KingsburyLab/pyeql/workflows/testing/badge.svg)](https://github.com/KingsburyLab/pyeql/actions?query=workflow%3Atesting)
+[![codecov](https://codecov.io/gh/KingsburyLab/pyeql/branch/main/graph/badge.svg?token=I7RP0QML6S)](https://codecov.io/gh/KingsburyLab/pyeql)
+![Supported python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8332915.svg)](https://doi.org/10.5281/zenodo.8332915)
+[![PyPI version](https://badge.fury.io/py/pyEQL.svg)](https://badge.fury.io/py/pyEQL)
+[![status](https://joss.theoj.org/papers/bdd9e247ea9736a0fdbbd5fe12bef7a6/status.svg)](https://joss.theoj.org/papers/bdd9e247ea9736a0fdbbd5fe12bef7a6)
+
+<img src="pyeql-logo.png" alt="pyEQL logo" style="width:600px;"/>
+
+# A python interface for water chemistry
+
+## Description
+
+**The goal of `pyEQL` is to provide a stable, intuitive, easy to learn python interface
+for water chemistry that can be connected to a variety of different modeling engines**
+
+Specifically, `pyEQL` defines a `Solution` class to represent an aqueous
+electrolyte solution. The `Solution` class allows the user to manipulate solutions as
+Python objects, providing methods to populate them with solutes, calculate
+species-specific properties (such as activity and diffusion coefficients),
+and retrieve bulk properties (such as density, conductivity, or volume).
+
+```python
+>>> from pyEQL import Solution
+>>> s1=Solution({"Na+":"1 mol/L", "Cl-": "1 mol/L"})
+>>> s1.density
+<Quantity(1.03710384, 'kilogram / liter')>
+>>> s1.conductivity
+<Quantity(8.09523295, 'siemens / meter')>
+>>> s1.osmotic_pressure.to('atm')
+<Quantity(46.7798197, 'standard_atmosphere')>
+>>> s1.get_amount('Na+', 'ug/L')
+<Quantity(22989769.3, 'microgram / liter')>
+```
+
+`pyEQL` also includes a number of other utilities to support water chemistry analysis,
+including a **built-in property database** of diffusion coefficients, activity correction
+parameters, and other data on a variety of common electrolytes.
+
+It is designed to be customizable and easy to integrate into projects
+that require modeling of chemical thermodyanmics of aqueous solutions.
+It aspires to provide a flexible, extensible framework for the user, with a
+high level of transparency about data sources and calculation methods.
+
+### Key Features
+
+- Build accurate solution properties using a minimum of inputs. Just specify
+  the identity and quantity of a solute and pyEQL will do the rest.
+
+- "Graceful Decay" from more sophisticated, data-intensive modeling approaches
+  to simpler, less accurate ones depending on the amount of data supplied.
+
+- Not limited to dilute solutions. pyEQL contains out of the box support for
+  the Pitzer Model and other methods for modeling concentrated solutions.
+
+- Built in [database](https://pyeql.readthedocs.io/en/latest/database.html) containing hundreds of model
+  parameters and physicochemical properties for different ions.
+
+- Units-aware calculations (by means of the [pint](https://github.com/hgrecco/pint) library)
+
+### Documentation
+
+Detailed documentation is available at [https://pyeql.readthedocs.io/](https://pyeql.readthedocs.io/)
+
+### Dependencies
+
+- Python 3.10+. This project will attempt to adhere to NumPy's
+  [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) deprecation policy
+  for older version of Python.
+- [pint](https://github.com/hgrecco/pint) - for units-aware calculations
+- [pymatgen](https://github.com/materialsproject/pymatgen) - periodic table and chemical formula information
+- [phreeqpython](https://github.com/Vitens/phreeqpython) - for PHREEQC-based speciation calculations
+- [iapws](https://github.com/jjgomera/iapws/) - equations of state for water
+- [monty](https://github.com/materialsvirtuallab/monty) - serialization and deserialization utilities
+- [maggma](https://materialsproject.github.io/maggma/) - interface for accessing the property database
+- [scipy](https://www.scipy.org/) - for certain nonlinear equation solvers
+
+## <!-- pyscaffold-notes -->
+
+pyEQL is licensed under LGPL.
+
+This project has been set up using PyScaffold 4.5. For details and usage
+information on PyScaffold see [https://pyscaffold.org/]().