pyEQL 0.5.2__py3-none-any.whl → 1.0.3__py3-none-any.whl

pyEQL/utils.py

@@ -0,0 +1,211 @@
+"""
+pyEQL utilities
+
+:copyright: 2013-2024 by Ryan S. Kingsbury
+:license: LGPL, see LICENSE for more details.
+
+"""
+
+import logging
+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"]):
+        formula = formula.replace(str, rep)
+
+    # replace superscripts with non superscripts
+    for char, rep in zip("⁻⁺⁰¹²³⁴⁵⁶⁷⁸⁹", "-+0123456789"):
+        formula = formula.replace(char, rep)
+
+    # replace subscripts with non subscripts
+    for char, rep in zip("₀₁₂₃₄₅₆₇₈₉", "0123456789"):
+        formula = formula.replace(char, rep)
+
+    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 sform == "H3N(aq)":
+        sform = "NH3(aq)"
+    # phosphoric acid system
+    elif sform == "PH3O4(aq)":
+        sform = "H3PO4(aq)"
+    elif sform == "PHO4[-2]":
+        sform = "HPO4[-2]"
+    elif sform == "P(HO2)2[-1]":
+        sform = "H2PO4[-1]"
+    # thiocyanate
+    elif sform == "CSN[-1]":
+        sform = "SCN[-1]"
+    # 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]"
+
+    # 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.0.3.dist-info/AUTHORS.md

@@ -0,0 +1,13 @@
+# Contributors
+
+pyEQL was originally written by Prof. Ryan Kingsbury (@rkingsbury) and is primarily
+developed and maintained by the Kingsbury Lab at Princeton University.
+
+Other contributors, listed alphabetically, are:
+
+* Kirill Pushkarev (@kirill-push)
+* Dhruv Duseja (@DhruvDuseja)
+* Andrew Rosen (@arosen93)
+* Hernan Grecco (@hgrecco)
+
+(If you think that your name belongs here, please let the maintainer know)

{pyEQL-0.5.2.dist-info → pyEQL-1.0.3.dist-info}/COPYING

@@ -162,4 +162,4 @@ General Public License ever published by the Free Software Foundation.
 whether future versions of the GNU Lesser General Public License shall
 apply, that proxy's public statement of acceptance of any version is
 permanent authorization for you to choose that version for the
-Library.
+Library.

pyEQL-0.5.2.dist-info/LICENSE → pyEQL-1.0.3.dist-info/LICENSE.txt

@@ -1,8 +1,8 @@
-Copyright (c) 2013-2020 Ryan S. Kingsbury
+Copyright (c) 2013-2023 Ryan S. Kingsbury
 
 pyEQL is free software; you can redistribute it and/or modify it under
 the terms of the GNU Lesser General Public License as published by the
-Free Software Foundation; version 3.0 of the License. 
+Free Software Foundation; version 3.0 of the License.
 
 A copy of the GNU Lesser General Public License is included in the
 pyEQL package in the file COPYING. If you did not receive this
@@ -11,13 +11,9 @@ Fifth Floor, Boston, MA 02110-1301, USA.
 
 Data included in pyEQL's databases (/database directory) is used with
 permission of the authors. If you wish to redistribute these databases
-as part of a derived work, you are advised to contact the authors or 
+as part of a derived work, you are advised to contact the authors or
 publishers for copyright information.
 
-pyEQL also includes a copy of `elements.py <http://www.lfd.uci.edu/~gohlke/>`_ 
-- a library of chemical information written by Christoph Gohlke and released 
-under the BSD license.
-
 This program is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

pyEQL-1.0.3.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.1
+Name: pyEQL
+Version: 1.0.3
+Summary: A python interace for solution chemistry
+Author-email: Ryan Kingsbury <kingsbury@princeton.edu>
+Project-URL: Docs, https://pyeql.readthedocs.io/
+Project-URL: Repo, https://github.com/KingsburyLab/pyEQL
+Project-URL: Package, https://pypi.org/project/pyEQL
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+License-File: COPYING
+License-File: AUTHORS.md
+Requires-Dist: pint >=0.19
+Requires-Dist: numpy <2
+Requires-Dist: scipy
+Requires-Dist: pymatgen ==2024.5.1
+Requires-Dist: iapws
+Requires-Dist: monty
+Requires-Dist: maggma >=0.67.0
+Requires-Dist: phreeqpython
+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'
+Provides-Extra: testing
+Requires-Dist: setuptools ; extra == 'testing'
+Requires-Dist: pre-commit ; extra == 'testing'
+Requires-Dist: pytest ; extra == 'testing'
+Requires-Dist: pytest-cov ; extra == 'testing'
+Requires-Dist: pytest-xdist ; extra == 'testing'
+Requires-Dist: black ; extra == 'testing'
+Requires-Dist: mypy ; extra == 'testing'
+Requires-Dist: ruff ; extra == 'testing'
+Requires-Dist: tox <4 ; extra == 'testing'
+
+[![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.9%20%7C%203.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.9+. 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/]().

pyEQL-1.0.3.dist-info/RECORD

@@ -0,0 +1,27 @@
+pyEQL/__init__.py,sha256=JErflmaJVP373dm3-YGHUomFu05dgX0iXWS-Z5AgSTU,2118
+pyEQL/activity_correction.py,sha256=eOixjgTd5hTrTRD5s6aPCCG12lAIH7-lRN0Z1qHu678,37151
+pyEQL/engines.py,sha256=b9ay7FYqmnINmhSMyNpVmENAtZVW-gyBfXUPf1PEUoY,34946
+pyEQL/equilibrium.py,sha256=YCtoAJSgn1WC9NJnc3H4FTJdKQvogsvCuj7HqlKMtww,8307
+pyEQL/functions.py,sha256=nc-Hc61MmW-ELBR1PByJvQnELxM7PZexMHbU_O5-Bnw,10584
+pyEQL/pint_custom_units.txt,sha256=XHmcMlwVvqF9nEW7_e9Xgyq-xWEr-cDYqieas11T3eY,2882
+pyEQL/salt_ion_match.py,sha256=0nCZXmeo67VqcyYWQpPx-81hjSvnsg8HFB3fIyfjW_k,4070
+pyEQL/solute.py,sha256=no00Rc3tRfHmyht4wm2UXA1KZhKC45tWMO5QEkZY6yg,5140
+pyEQL/solution.py,sha256=XwtQmll3gPwdnnkXpQsnO7QebwTjplmlfhbEIU8rHDo,115940
+pyEQL/utils.py,sha256=DWLtNm71qw5j4-jqBp5v3LssEjWgJnVvI6a_H60c5ic,6670
+pyEQL/database/geothermal.dat,sha256=kksnfcBtWdOTpNn4CLXU1Mz16cwas2WuVKpuMU8CaVI,234230
+pyEQL/database/llnl.dat,sha256=jN-a0kfUFbQlYMn2shTVRg1JX_ZhLa-tJ0lLw2YSpLU,751462
+pyEQL/database/phreeqc_license.txt,sha256=8W1r8VxC2kVptIMSU9sDFNASYqN7MdwKEtIWWfjTQuM,2906
+pyEQL/database/pyeql_db.json,sha256=TQKKofds7QBNd-Hw5QQuPwP6rQ8YWh_hHlRAtoQX0m8,1080793
+pyEQL/presets/Ringers lactate.yaml,sha256=vtSnuvgALHR27XEjpDzC0xyw5-E6b2FSsF1EUEBiWpw,413
+pyEQL/presets/normal saline.yaml,sha256=i2znhnIeXfNx1iMFFSif7crMRCFRP6xN1m7Wp7USduM,318
+pyEQL/presets/rainwater.yaml,sha256=S0WHZNDfCJyjSSFxNFdkypjn2s3P0jJGCiYIxvi1ibA,337
+pyEQL/presets/seawater.yaml,sha256=oryc1CkhRz20RpWE6uiGiT93HoZnqlB0s-0PmBWr3-U,843
+pyEQL/presets/urine.yaml,sha256=0Njtc-H1fFRo7UhquHdiSTT4z-8VZJ1utDCk02qk28M,679
+pyEQL/presets/wastewater.yaml,sha256=jTTFBpmKxczaEtkCZb0xUULIPZt7wfC8eAJ6rthGnmw,502
+pyEQL-1.0.3.dist-info/AUTHORS.md,sha256=K9ZLhKFwZ2zLlFXwN62VuUYCpr5T6n4mOUCUHlytTUs,415
+pyEQL-1.0.3.dist-info/COPYING,sha256=Ww2oUywfFTn242v9ksCgQdIVSpcMXJiKKePn0GFm25E,7649
+pyEQL-1.0.3.dist-info/LICENSE.txt,sha256=2Zf1F7RzbpeposgIxUydpurqNCMoMgDi2gAB65_GjwQ,969
+pyEQL-1.0.3.dist-info/METADATA,sha256=Wqt01mnze6MZtohFvUr3W_PXgGxbt1ZGo6akCvivWFI,6083
+pyEQL-1.0.3.dist-info/WHEEL,sha256=rWxmBtp7hEUqVLOnTaDOPpR-cZpCDkzhhcBce-Zyd5k,91
+pyEQL-1.0.3.dist-info/top_level.txt,sha256=QMOaZjCAm_lS4Njsjh4L0B5aWnJFGQMYKhuH88CG1co,6
+pyEQL-1.0.3.dist-info/RECORD,,

{pyEQL-0.5.2.dist-info → pyEQL-1.0.3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.34.2)
+Generator: setuptools (71.0.4)
 Root-Is-Purelib: true
 Tag: py3-none-any