pyEQL 1.4.0rc9__cp311-cp311-macosx_11_0_arm64.whl

pyEQL/phreeqc/solution.py

@@ -0,0 +1,74 @@
+from copy import deepcopy
+from typing import Any
+
+
+class PHRQSol:
+    def __init__(self, props, phreeqc=None):
+        self._phreeqc = phreeqc
+        self._number = -1
+        self._input_props = props
+        self._calculated_props = {}
+
+    def __str__(self):
+        return "\n".join(f"{k} {v}" for k, v in self._input_props.items())
+
+    def _set_calculated_props(self, props: dict[Any, Any]):
+        self._calculated_props = deepcopy(props)
+
+    def _get_calculated_props(self):
+        return self._calculated_props
+
+    def _get_calculated_prop(self, which, species: str | None = None, eq_species: str | None = None):
+        if species is not None:
+            species_props = self._calculated_props["species"].get(species)
+            return species_props[which] if species_props is not None else None
+        if eq_species is not None:
+            eq_species_props = self._calculated_props["eq_species"].get(eq_species)
+            return eq_species_props[which] if eq_species_props is not None else None
+        return self._calculated_props[which]
+
+    def get_activity(self, species) -> float:
+        return self._get_calculated_prop("ACT", species=species)
+
+    def get_molality(self, species) -> float:
+        return self._get_calculated_prop("MOL", species=species)
+
+    def get_diffusion_coefficient(self, species) -> float:
+        return self._get_calculated_prop("DIFF_C", species=species)
+
+    def get_osmotic_coefficient(self) -> float:
+        return self._get_calculated_prop("OSMOTIC")
+
+    def get_species_list(self) -> list[str]:
+        return list(self._calculated_props["species"])
+
+    def get_kgw(self) -> float:
+        return self._get_calculated_prop("TOT['water']")
+
+    def get_moles(self, species) -> float:
+        return self.get_molality(species) * self.get_kgw()
+
+    def equalize(self, phases: list[str], saturation_indices: list[float], amounts: list[float]) -> None:
+        if self._phreeqc is not None:
+            self._phreeqc().equalize(self._number, phases, saturation_indices, amounts)
+
+    def si(self, eq_species) -> float:
+        return self._get_calculated_prop("SI", eq_species=eq_species)
+
+    """
+    The following properties are somewhat redundant, but included in here
+    so we can act as a drop-in replacement for PhreeqPython as far as its
+    usage in pyEQL.
+    """
+
+    @property
+    def species(self) -> list[str]:
+        return self.get_species_list()
+
+    @property
+    def species_moles(self) -> dict[str, float]:
+        return {species: self.get_moles(species) for species in self.species}
+
+    def forget(self) -> None:
+        if self._phreeqc is not None:
+            self._phreeqc().remove_solution(self._number)

pyEQL/phreeqc/var.py

@@ -0,0 +1,50 @@
+from typing import Any
+
+from pyEQL._phreeqc import PY_VAR_TYPE, PY_VRESULT, PyVar
+
+
+class Var:
+    def __init__(self, value: Any | None = None):
+        self._var = PyVar()
+        self._var.var.type = PY_VAR_TYPE.TT_EMPTY
+        self.value = value  # will invoke setter
+
+    @property
+    def value(self) -> Any:
+        match self._var.var.type:
+            case PY_VAR_TYPE.TT_EMPTY:
+                return None
+            case PY_VAR_TYPE.TT_ERROR:
+                return self._var.var.vresult
+            case PY_VAR_TYPE.TT_LONG:
+                return self._var.var.lVal
+            case PY_VAR_TYPE.TT_DOUBLE:
+                return self._var.var.dVal
+            case PY_VAR_TYPE.TT_STRING:
+                return self._var.var.sVal
+            case _:
+                raise RuntimeError("Unknown type")
+
+    @value.setter
+    def value(self, value) -> None:
+        # If we were previously holding a string, we need to free it by
+        # creating a new PyVar
+        if self._var.var.type == PY_VAR_TYPE.TT_STRING:
+            self._var = PyVar()
+
+        if isinstance(value, PY_VRESULT):
+            self._var.var.type = PY_VAR_TYPE.TT_ERROR
+            self._var.var.vresult = value
+        elif isinstance(value, int):
+            self._var.var.type = PY_VAR_TYPE.TT_LONG
+            self._var.var.lVal = value
+        elif isinstance(value, float):
+            self._var.var.type = PY_VAR_TYPE.TT_DOUBLE
+            self._var.var.dVal = value
+        elif isinstance(value, str):
+            self._var.var.type = PY_VAR_TYPE.TT_STRING
+            self._var.var.sVal = value
+        elif value is None:
+            self._var.var.type = PY_VAR_TYPE.TT_EMPTY
+        else:
+            raise RuntimeError("Unknown type")

pyEQL/presets/Ringers lactate.yaml

@@ -0,0 +1,20 @@
+"@module": pyEQL.solution
+"@class": Solution
+"@version": 0.0.post1.dev699+g0764b1c
+solutes:
+  H2O(aq): 55.2313771443148 mol
+  Na[+1]: 0.13 mol
+  Cl[-1]: 0.109 mol
+  H5(CO)3[-1]: 0.028 mol
+  K[+1]: 0.004 mol
+  Ca[+2]: 0.0015 mol
+  H[+1]: 3.162277660168379e-07 mol
+  OH[-1]: 3.162277660168379e-08 mol
+volume: 1 l
+temperature: 298.15 K
+pressure: 1 atm
+pH: 6.5
+pE: 8.5
+balance_charge:
+solvent: H2O(aq)
+engine: native

pyEQL/presets/__init__.py

@@ -0,0 +1,17 @@
+# Partial pressures of reactive gases in atmosphere
+# Obtained from https://www.noaa.gov/jetstream/atmosphere on 12/15/25
+# (N2=78.084%, O2=20.946%, CO2=0.042%)
+ATMOSPHERE = {"N2": -0.1074379, "CO2": -3.3767507, "O2": -0.6788989}
+
+# The amount, in moles, of an assemblage of pure phases that can react
+# reversibly with the aqueous phase.
+
+# See:
+#   https://wwwbrr.cr.usgs.gov/projects/GWC_coupled/phreeqc/html/final-38.html
+# ".. This number of moles defines the maximum amount of the mineral or gas
+#  that can dissolve. It may be possible to dissolve the entire amount without
+#  reaching the target saturation index, in which case the solution will have a
+#  smaller saturation index for this phase than the target saturation index.".
+
+# We set it to 100 moles to approximate an "infinite" supply mineral/gas.
+EQUILIBRIUM_PHASE_AMOUNT = 100

pyEQL/presets/normal saline.yaml

@@ -0,0 +1,17 @@
+"@module": pyEQL.solution
+"@class": Solution
+"@version": 0.0.post1.dev699+g0764b1c
+solutes:
+  H2O(aq): 55.19703719794332 mol
+  Na[+1]: 0.154 mol
+  Cl[-1]: 0.154 mol
+  H[+1]: 1e-07 mol
+  OH[-1]: 1e-07 mol
+volume: 1 l
+temperature: 298.15 K
+pressure: 1 atm
+pH: 7.0
+pE: 8.5
+balance_charge:
+solvent: H2O(aq)
+engine: native

pyEQL/presets/rainwater.yaml

@@ -0,0 +1,17 @@
+"@module": pyEQL.solution
+"@class": Solution
+"@version": 0.0.post1.dev699+g0764b1c
+solutes:
+  H2O(aq): 55.34454944845822 mol
+  HCO3[-1]: 3.162277660168379e-06 mol
+  H[+1]: 1e-06 mol
+  OH[-1]: 1e-08 mol
+  CO3[-2]: 1e-09 mol
+volume: 1 l
+temperature: 298.15 K
+pressure: 1 atm
+pH: 6.0
+pE: 8.5
+balance_charge:
+solvent: H2O(aq)
+engine: native

pyEQL/presets/seawater.yaml

@@ -0,0 +1,29 @@
+"@module": pyEQL.solution
+"@class": Solution
+"@version": 0.0.post1.dev699+g0764b1c
+solutes:
+  H2O(aq): 55.34455401423017 mol
+  Cl[-1]: 0.54425785619973 mol
+  Na[+1]: 0.4675827371496296 mol
+  Mg[+2]: 0.05266118052346798 mol
+  SO4[-2]: 0.02815187344845402 mol
+  Ca[+2]: 0.010251594148212317 mol
+  K[+1]: 0.010177468379526855 mol
+  HCO3[-1]: 0.0017126511769261989 mol
+  Br[-1]: 0.0008395244921424561 mol
+  B(OH)3(aq): 0.0003134669156396757 mol
+  CO3[-2]: 0.00023825904349479544 mol
+  B(OH)4(aq): 0.0001005389715937341 mol
+  Sr[+2]: 9.046483353663284e-05 mol
+  F[-1]: 6.822478260456777e-05 mol
+  CO2(aq): 9.515218476861173e-06 mol
+  OH[-1]: 8.207436858780224e-06 mol
+  H[+1]: 7.943282347242822e-09 mol
+volume: 1.0080615264452506 l
+temperature: 298.15 K
+pressure: 1 atm
+pH: 8.103487039827968
+pE: 8.5
+balance_charge:
+solvent: H2O(aq)
+engine: native

pyEQL/presets/urine.yaml

@@ -0,0 +1,26 @@
+"@module": pyEQL.solution
+"@class": Solution
+"@version": 0.0.post1.dev699+g0764b1c
+solutes:
+  H2O(aq): 55.135679438263864 mol
+  H4CN2O(aq): 0.333026615820163 mol
+  Na[+1]: 0.26098565526795925 mol
+  Cl[-1]: 0.05359207965475418 mol
+  K[+1]: 0.038364839391994025 mol
+  H4N[+1]: 0.027718552470665455 mol
+  SO4[-2]: 0.018737781405042127 mol
+  PO4[-3]: 0.012635387918307416 mol
+  H7C4N3O(aq): 0.008840335409397701 mol
+  HCO3[-1]: 0.004916675462052772 mol
+  Mg[+2]: 0.004114379757251594 mol
+  H4C5N4O3(aq): 0.0017845430730997621 mol
+  H[+1]: 1e-07 mol
+  OH[-1]: 1e-07 mol
+volume: 1 l
+temperature: 298.15 K
+pressure: 1 atm
+pH: 7.0
+pE: 8.5
+balance_charge:
+solvent: H2O(aq)
+engine: native

pyEQL/presets/wastewater.yaml

@@ -0,0 +1,21 @@
+"@module": pyEQL.solution
+"@class": Solution
+"@version": 0.0.post1.dev699+g0764b1c
+solutes:
+  H2O(aq): 55.342123269143364 mol
+  CH3COOH(aq): 0.006827420786931851 mol
+  Cl[-1]: 0.0016641751050686824 mol
+  H3N(aq): 0.0014268501490265714 mol
+  K[+1]: 0.0004092249535146029 mol
+  SO4[-2]: 0.00027065684251727516 mol
+  PO4[-3]: 8.002412348261364e-05 mol
+  H[+1]: 1e-07 mol
+  OH[-1]: 1e-07 mol
+volume: 1 l
+temperature: 298.15 K
+pressure: 1 atm
+pH: 7.0
+pE: 8.5
+balance_charge:
+solvent: H2O(aq)
+engine: native

pyEQL/salt_ion_match.py

@@ -0,0 +1,112 @@
+"""
+pyEQL salt matching library.
+
+This file contains functions that allow a pyEQL Solution object composed of
+individual species (usually ions) to be mapped to a solution of one or more
+salts. This mapping is necessary because some parameters (such as activity
+coefficient data) can only be determined for salts (e.g. NaCl) and not individual
+species (e.g. Na+)
+
+:copyright: 2013-2024 by Ryan S. Kingsbury
+:license: LGPL, see LICENSE for more details.
+
+"""
+
+from monty.json import MSONable
+from pymatgen.core.ion import Ion
+
+from pyEQL.utils import standardize_formula
+
+
+class Salt(MSONable):
+    """Class to represent a salt."""
+
+    def __init__(self, cation, anion) -> None:
+        """
+        Create a Salt object based on its component ions.
+
+        Parameters:
+            cation, anion: (str) Chemical formula of the cation and anion, respectively.
+
+        Returns:
+            Salt : An object representing the properties of the salt
+
+        Examples:
+            >>> Salt('Na+','Cl-').formula
+            'NaCl'
+
+            >>> Salt('Mg++','Cl-').formula
+            'MgCl2'
+        """
+        # create pymatgen Ion objects
+        pmg_cat = Ion.from_formula(cation)
+        pmg_an = Ion.from_formula(anion)
+        # standardize the cation and anion formulas
+        self.cation = standardize_formula(cation)
+        self.anion = standardize_formula(anion)
+
+        # get the charges on cation and anion
+        self.z_cation = pmg_cat.charge
+        self.z_anion = pmg_an.charge
+
+        # assign stoichiometric coefficients by finding a common multiple
+        self.nu_cation = int(abs(self.z_anion))
+        self.nu_anion = int(abs(self.z_cation))
+
+        # if both coefficients are the same, set each to one
+        if self.nu_cation == self.nu_anion:
+            self.nu_cation = 1
+            self.nu_anion = 1
+
+        # start building the formula, cation first
+        salt_formula = ""
+        if self.nu_cation > 1:
+            # add parentheses if the cation is a polyatomic ion
+            if len(pmg_cat.elements) > 1:
+                salt_formula += "("
+                salt_formula += self.cation.split("[")[0]
+                salt_formula += ")"
+            else:
+                salt_formula += self.cation.split("[")[0]
+            salt_formula += str(self.nu_cation)
+        else:
+            salt_formula += self.cation.split("[")[0]
+
+        if self.nu_anion > 1:
+            # add parentheses if the anion is a polyatomic ion
+            if len(pmg_an.elements) > 1:
+                salt_formula += "("
+                salt_formula += self.anion.split("[")[0]
+                salt_formula += ")"
+            else:
+                salt_formula += self.anion.split("[")[0]
+            salt_formula += str(self.nu_anion)
+        else:
+            salt_formula += self.anion.split("[")[0]
+
+        self.formula = salt_formula
+
+    # TODO - consider whether this should be adjusted to be based on total concentrations or not
+    # NOTE: speciating the solution results in a decrease in the overall ionic strength, because some of the
+    # Mg+2 is converted to monovalent complexes like MgOH+. Hence, the activity coefficients deviate a bit from
+    # the published values.
+    def get_effective_molality(self, ionic_strength):
+        r"""Calculate the effective molality according to [mistry13]_.
+
+        .. math:: 2 I \over (\nu_+ z_+^2 + \nu_- z_- ^2)
+
+        Args:
+            ionic_strength: Quantity
+                The ionic strength of the parent solution, mol/kg
+
+        Returns:
+            Quantity: the effective molality of the salt in the parent solution
+
+        References:
+            .. [mistry13] Mistry, K. H.; Hunter, H. a.; Lienhard V, J. H. Effect of composition and nonideal solution behavior
+                on desalination calculations for mixed electrolyte solutions with comparison to seawater. Desalination
+                2013, 318, 34-47.
+        """
+        m_effective = 2 * ionic_strength / (self.nu_cation * self.z_cation**2 + self.nu_anion * self.z_anion**2)
+
+        return m_effective.to("mol/kg")

pyEQL/solute.py

@@ -0,0 +1,163 @@
+"""
+pyEQL Solute class.
+
+This file contains functions and methods for managing properties of
+individual solutes. The Solute class contains methods for accessing
+ONLY those properties that DO NOT depend on solution composition.
+Solute properties such as activity coefficient or concentration
+that do depend on compsition are accessed via Solution class methods.
+
+:copyright: 2013-2024 by Ryan S. Kingsbury
+:license: LGPL, see LICENSE for more details.
+
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+from dataclasses import asdict, dataclass, field
+from typing import Literal
+
+import numpy as np
+from pymatgen.core.ion import Ion
+
+from pyEQL.utils import standardize_formula
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Datum:
+    """Document containing data for a single computed or experimental property."""
+
+    value: str
+    reference: str | None = None
+    data_type: Literal["computed", "experimental", "fitted", "unknown"] = "unknown"
+
+    @property
+    def magnitude(self):
+        """Return the numerical value of a Datum."""
+        return float(self.value.split(" ")[0])
+
+    @property
+    def unit(self):
+        """Return the unit of a Datum."""
+        return self.value.split(" ")[-1]
+
+    @property
+    def uncertainty(self):
+        """Return the uncertainty of a Datum."""
+        if len(self.value.split(" ")) > 3:
+            return float(self.value.split(" ")[2])
+        return np.nan
+
+    def as_dict(self):
+        """Return a dictionary representation of the Datum."""
+        return dict(asdict(self).items())
+
+
+@dataclass
+class Solute:
+    """
+    represent each chemical species as an object containing its formal charge,
+    transport numbers, concentration, activity, etc.
+
+    Args:
+        formula: Chemical formula for the solute. Charged species must contain a + or - and (for polyvalent solutes)
+            a number representing the net charge (e.g. 'SO4-2').
+    """
+
+    formula: str
+    charge: int
+    molecular_weight: str
+    elements: list
+    chemsys: str
+    pmg_ion: Ion
+    formula_html: str
+    formula_latex: str
+    formula_hill: str
+    formula_pretty: str
+    oxi_state_guesses: dict[str, float]
+    n_atoms: int
+    n_elements: int
+    size: dict = field(
+        default_factory=lambda: {
+            "radius_ionic": None,
+            "radius_hydrated": None,
+            "radius_vdw": None,
+            "molar_volume": None,
+        }
+    )
+    thermo: dict = field(default_factory=lambda: {"ΔG_hydration": None, "ΔG_formation": None})
+    transport: dict = field(default_factory=lambda: {"diffusion_coefficient": None})
+    model_parameters: dict = field(
+        default_factory=lambda: {
+            "activity_pitzer": {"Beta0": None, "Beta1": None, "Beta2": None, "Cphi": None, "Max_C": None},
+            "molar_volume_pitzer": {
+                "Beta0": None,
+                "Beta1": None,
+                "Beta2": None,
+                "Cphi": None,
+                "V_o": None,
+                "Max_C": None,
+            },
+            "viscosity_jones_dole": {"B": None},
+            "diffusion_temp_smolyakov": {"a1": None, "a2": None, "d": None},
+        }
+    )
+
+    @classmethod
+    def from_formula(cls, formula: str):
+        """
+        Create an Ion document from a chemical formula. The formula is passed to
+        pymatgen.core.Ion.from_formula() and used to populate the basic chemical
+        informatics fields (e.g., formula, charge, molecular weight, elements, etc.)
+        of the IonDoc.
+        """
+        pmg_ion = Ion.from_formula(formula)
+        f, factor = pmg_ion.get_reduced_formula_and_factor()
+        rform = standardize_formula(formula)
+        charge = int(pmg_ion.charge)
+        els = [str(el) for el in pmg_ion.elements]
+        mw = f"{float(pmg_ion.weight / factor)} g/mol"  # weight is a FloatWithUnit
+        chemsys = pmg_ion.chemical_system
+        # store only the most likely oxi_state guesses
+        try:
+            oxi_states = pmg_ion.oxi_state_guesses(all_oxi_states=True)[0]
+        except (IndexError, ValueError):
+            warnings.warn(f"Guessing oxi states failed for {formula}")
+            oxi_states = {}
+
+        return cls(
+            rform,
+            charge=charge,
+            molecular_weight=mw,
+            elements=els,
+            chemsys=chemsys,
+            pmg_ion=pmg_ion,
+            formula_html=pmg_ion.to_html_string(),
+            formula_latex=pmg_ion.to_latex_string(),
+            formula_hill=pmg_ion.hill_formula,
+            formula_pretty=pmg_ion.to_pretty_string(),
+            oxi_state_guesses=oxi_states,
+            n_atoms=int(pmg_ion.num_atoms),
+            n_elements=len(els),
+        )
+
+    def as_dict(self):
+        """Return a dictionary representation of the Solute."""
+        return dict(asdict(self).items())
+
+    # set output of the print() statement
+    def __str__(self) -> str:
+        return (
+            "Species "
+            + str(self.formula)
+            + " MW="
+            + str(self.mw)
+            + " Formal Charge="
+            + str(self.charge)
+            + " Amount= "
+            + str(self.moles)
+        )