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

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/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

@@ -1,5 +1,5 @@
 """
-pyEQL salt matching library
+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
@@ -7,72 +7,51 @@ 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-2020 by Ryan S. Kingsbury
+:copyright: 2013-2024 by Ryan S. Kingsbury
 :license: LGPL, see LICENSE for more details.
 
 """
-# logging system
-import logging
 
-# add a filter to emit only unique log messages to the handler
-from pyEQL.logging_system import Unique
+from monty.json import MSONable
+from pymatgen.core.ion import Ion
 
-import pyEQL.chemical_formula as chem
+from pyEQL.utils import standardize_formula
 
-logger = logging.getLogger(__name__)
 
-unique = Unique()
-logger.addFilter(unique)
-
-# add a handler for console output, since pyEQL is meant to be used interactively
-ch = logging.StreamHandler()
-
-# create formatter for the log
-formatter = logging.Formatter("(%(name)s) - %(levelname)s - %(message)s")
-
-# add formatter to the handler
-ch.setFormatter(formatter)
-logger.addHandler(ch)
-
-
-class Salt:
-    """
-    Class to represent a salt.
-    """
-
-    def __init__(self, cation, anion):
-        self.cation = cation
-        self.anion = anion
+class Salt(MSONable):
+    """Class to represent a salt."""
 
+    def __init__(self, cation, anion) -> None:
         """
-        Create a salt object based on its component ions
-        
+        Create a Salt object based on its component ions.
+
         Parameters:
-        ----------
-        cation, anion : str
-                Chemical formula of the cation and anion, respectively
-        
+            cation, anion: (str) Chemical formula of the cation and anion, respectively.
+
         Returns:
-        -------
-        Salt : An object representing the properties of the salt
-        
+            Salt : An object representing the properties of the salt
+
         Examples:
-        --------
-        >>> Salt('Na+','Cl-').formula
-        'NaCl'
-        
-        >>> Salt('Mg++','Cl-').formula
-        'MgCl2'
-        
+            >>> 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 = chem.get_formal_charge(cation)
-        self.z_anion = chem.get_formal_charge(anion)
+        self.z_cation = pmg_cat.charge
+        self.z_anion = pmg_an.charge
 
         # assign stoichiometric coefficients by finding a common multiple
-        self.nu_cation = abs(self.z_anion)
-        self.nu_anion = abs(self.z_cation)
+        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:
@@ -83,261 +62,51 @@ class Salt:
         salt_formula = ""
         if self.nu_cation > 1:
             # add parentheses if the cation is a polyatomic ion
-            if len(chem.get_elements(cation)) > 1:
+            if len(pmg_cat.elements) > 1:
                 salt_formula += "("
-                salt_formula += _trim_formal_charge(cation)
+                salt_formula += self.cation.split("[")[0]
                 salt_formula += ")"
             else:
-                salt_formula += _trim_formal_charge(cation)
+                salt_formula += self.cation.split("[")[0]
             salt_formula += str(self.nu_cation)
         else:
-            salt_formula += _trim_formal_charge(cation)
+            salt_formula += self.cation.split("[")[0]
 
         if self.nu_anion > 1:
             # add parentheses if the anion is a polyatomic ion
-            if len(chem.get_elements(anion)) > 1:
+            if len(pmg_an.elements) > 1:
                 salt_formula += "("
-                salt_formula += _trim_formal_charge(anion)
+                salt_formula += self.anion.split("[")[0]
                 salt_formula += ")"
             else:
-                salt_formula += _trim_formal_charge(anion)
+                salt_formula += self.anion.split("[")[0]
             salt_formula += str(self.nu_anion)
         else:
-            salt_formula += _trim_formal_charge(anion)
+            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):
-        """ Calculate the effective molality according to [#]_
+        r"""Calculate the effective molality according to [mistry]_.
 
-        .. math:: 2 I \\over (\\nu_+ z_+^2 + \\nu_- z_- ^2)
+        .. math:: 2 I \over (\nu_+ z_+^2 + \nu_- z_- ^2)
 
-        Parameters
-        ----------
-        ionic_strength: Quantity
-                        The ionic strength of the parent solution, mol/kg
+        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
+        Returns:
+            Quantity: the effective molality of the salt in the parent solution
 
-        References
-        ----------
-        .. [#] 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.
+        References:
+            .. [mistry] 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)
-        )
+        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")
-
-
-def _sort_components(Solution, type="all"):
-    """
-    Sort the components of a solution in descending order (by mol).
-
-    Parameters:
-    ----------
-    Solution : Solution object
-    type     : The type of component to be sorted. Defaults to 'all' for all
-                solutes. Other valid arguments are 'cations' and 'anions' which
-                return sorted lists of cations and anions, respectively.
-
-    Returns:
-    -------
-    A list whose keys are the component names (formulas) and whose
-    values are the component objects themselves
-    
-    
-    """
-    formula_list = []
-
-    # populate a list with component names
-    for item in Solution.components:
-        if type == "all":
-            formula_list.append(item)
-        elif type == "cations":
-            if Solution.get_solute(item).get_formal_charge() > 0:
-                formula_list.append(item)
-        elif type == "anions":
-            if Solution.get_solute(item).get_formal_charge() < 0:
-                formula_list.append(item)
-
-    # populate a dictionary with formula:concentration pairs
-    mol_list = {}
-    for item in formula_list:
-        mol_list.update({item: Solution.get_amount(item, "mol")})
-
-    return sorted(formula_list, key=mol_list.__getitem__, reverse=True)
-
-
-def identify_salt(Solution):
-    """
-    Analyze the components of a solution and identify the salt that most closely
-    approximates it.
-    (e.g., if a solution contains 0.5 mol/kg of Na+ and Cl-, plus traces of H+
-    and OH-, the matched salt is 0.5 mol/kg NaCl)
-    
-    Create a Salt object for this salt.
-    
-    Returns:
-    -------
-    A Salt object.
-    """
-    # sort the components by moles
-    sort_list = _sort_components(Solution)
-
-    # default to returning water as the salt
-    cation = "H+"
-    anion = "OH-"
-
-    # return water if there are no solutes
-    if len(sort_list) < 3 and sort_list[0] == "H2O":
-        logger.info("Salt matching aborted because there are not enough solutes.")
-        return Salt(cation, anion)
-
-    # warn if something other than water is the predominant component
-    if sort_list[0] != "H2O":
-        logger.warning("H2O is not the most prominent component")
-
-    # take the dominant cation and anion and assemble a salt from them
-    for item in sort_list:
-        if chem.get_formal_charge(item) > 0 and cation == "H+":
-            cation = item
-        elif chem.get_formal_charge(item) < 0 and anion == "OH-":
-            anion = item
-        else:
-            pass
-
-    # assemble the salt
-    return Salt(cation, anion)
-
-
-def generate_salt_list(Solution, unit="mol/kg"):
-    """
-    Generate a list of salts that represents the ionic composition of a
-    solution.
-
-    Returns:
-    -------
-    dict
-        A dictionary of Salt objects, keyed to the formula of the salt.
-
-    """
-    salt_list = {}
-
-    # sort the cations and anions by moles
-    cation_list = _sort_components(Solution, type="cations")
-    anion_list = _sort_components(Solution, type="anions")
-
-    # iterate through the lists of ions
-    # create salts by matching the equivalent concentrations of cations
-    # and anions along the way
-    len_cat = len(cation_list)
-    len_an = len(anion_list)
-
-    # start with the first cation and anion
-    index_cat = 0
-    index_an = 0
-
-    # calculate the equivalent concentrations of each ion
-    c1 = Solution.get_amount(cation_list[index_cat], unit) * chem.get_formal_charge(
-        cation_list[index_cat]
-    )
-    a1 = Solution.get_amount(anion_list[index_an], unit) * abs(
-        chem.get_formal_charge(anion_list[index_an])
-    )
-
-    while index_cat < len_cat and index_an < len_an:
-        # if the cation concentration is greater, there will be leftover cations
-        if c1 > a1:
-            # create the salt
-            x = Salt(cation_list[index_cat], anion_list[index_an])
-            # there will be leftover cation, so use the anion amount
-            amount = a1 / abs(x.z_anion)
-            # add it to the list
-            salt_list.update({x: amount})
-            # adjust the amounts of the respective ions
-            c1 = c1 - a1
-            # move to the next anion
-            index_an += 1
-            try:
-                a1 = Solution.get_amount(anion_list[index_an], unit) * abs(
-                    chem.get_formal_charge(anion_list[index_an])
-                )
-            except IndexError:
-                continue
-        # if the anion concentration is greater, there will be leftover anions
-        if c1 < a1:
-            # create the salt
-            x = Salt(cation_list[index_cat], anion_list[index_an])
-            # there will be leftover anion, so use the cation amount
-            amount = c1 / x.z_cation
-            # add it to the list
-            salt_list.update({x: amount})
-            # calculate the leftover cation amount
-            a1 = a1 - c1
-            # move to the next cation
-            index_cat += 1
-            try:
-                c1 = Solution.get_amount(
-                    cation_list[index_cat], unit
-                ) * chem.get_formal_charge(cation_list[index_cat])
-            except IndexError:
-                continue
-        if c1 == a1:
-            # create the salt
-            x = Salt(cation_list[index_cat], anion_list[index_an])
-            # there will be nothing leftover, so it doesn't matter which ion you use
-            amount = c1 / x.z_cation
-            # add it to the list
-            salt_list.update({x: amount})
-            # move to the next cation and anion
-            index_an += 1
-            index_cat += 1
-            try:
-                c1 = Solution.get_amount(
-                    cation_list[index_cat], unit
-                ) * chem.get_formal_charge(cation_list[index_cat])
-                a1 = Solution.get_amount(anion_list[index_an], unit) * abs(
-                    chem.get_formal_charge(anion_list[index_an])
-                )
-            except IndexError:
-                continue
-
-    return salt_list
-
-
-def _trim_formal_charge(formula):
-    """
-    remove the formal charge from a chemical formula
-    
-    Examples:
-    --------
-    >>> _trim_formal_charge('Fe+++')
-    'Fe'
-    >>> _trim_formal_charge('SO4-2')
-    'SO4'
-    >>> _trim_formal_charge('Na+')
-    'Na'
-    
-    """
-    charge = chem.get_formal_charge(formula)
-    output = ""
-    if charge > 0:
-        output = formula.split("+")[0]
-    elif charge < 0:
-        output = formula.split("-")[0]
-
-    return output
-
-
-# TODO - turn doctest back on when the nosigint error is gone
-# if __name__ == "__main__":
-#   import doctest
-#  doctest.testmod()