pyEQL 1.2.0__py3-none-any.whl → 1.3.1__py3-none-any.whl

pyEQL/engines.py

@@ -6,6 +6,7 @@ pyEQL engines for computing aqueous equilibria (e.g., speciation, redox, etc.).
 
 """
 
+import copy
 import logging
 import os
 import warnings
@@ -17,7 +18,6 @@ from phreeqpython import PhreeqPython
 
 import pyEQL.activity_correction as ac
 from pyEQL import ureg
-from pyEQL.salt_ion_match import Salt
 from pyEQL.utils import standardize_formula
 
 # These are the only elements that are allowed to have parenthetical oxidation states
@@ -27,7 +27,7 @@ SPECIAL_ELEMENTS = ["S", "C", "N", "Cu", "Fe", "Mn"]
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
-    from pyEQL import Solution
+    from pyEQL import solution
 
 
 class EOS(ABC):
@@ -41,7 +41,7 @@ class EOS(ABC):
     """
 
     @abstractmethod
-    def get_activity_coefficient(self, solution: "Solution", solute: str) -> ureg.Quantity:
+    def get_activity_coefficient(self, solution: "solution.Solution", solute: str) -> ureg.Quantity:
         """
         Return the *molal scale* activity coefficient of solute, given a Solution
         object.
@@ -58,7 +58,7 @@ class EOS(ABC):
         """
 
     @abstractmethod
-    def get_osmotic_coefficient(self, solution: "Solution") -> ureg.Quantity:
+    def get_osmotic_coefficient(self, solution: "solution.Solution") -> ureg.Quantity:
         """
         Return the *molal scale* osmotic coefficient of a Solution.
 
@@ -73,7 +73,7 @@ class EOS(ABC):
         """
 
     @abstractmethod
-    def get_solute_volume(self, solution: "Solution") -> ureg.Quantity:
+    def get_solute_volume(self, solution: "solution.Solution") -> ureg.Quantity:
         """
         Return the volume of only the solutes.
 
@@ -88,7 +88,7 @@ class EOS(ABC):
         """
 
     @abstractmethod
-    def equilibrate(self, solution: "Solution") -> None:
+    def equilibrate(self, solution: "solution.Solution") -> None:
         """
         Adjust the speciation and pH of a Solution object to achieve chemical equilibrium.
 
@@ -108,25 +108,25 @@ class EOS(ABC):
 class IdealEOS(EOS):
     """Ideal solution equation of state engine."""
 
-    def get_activity_coefficient(self, solution: "Solution", solute: str) -> ureg.Quantity:
+    def get_activity_coefficient(self, solution: "solution.Solution", solute: str) -> ureg.Quantity:
         """
         Return the *molal scale* activity coefficient of solute, given a Solution
         object.
         """
         return ureg.Quantity(1, "dimensionless")
 
-    def get_osmotic_coefficient(self, solution: "Solution") -> ureg.Quantity:
+    def get_osmotic_coefficient(self, solution: "solution.Solution") -> ureg.Quantity:
         """
         Return the *molal scale* osmotic coefficient of solute, given a Solution
         object.
         """
         return ureg.Quantity(1, "dimensionless")
 
-    def get_solute_volume(self, solution: "Solution") -> ureg.Quantity:
+    def get_solute_volume(self, solution: "solution.Solution") -> ureg.Quantity:
         """Return the volume of the solutes."""
         return ureg.Quantity(0, "L")
 
-    def equilibrate(self, solution: "Solution") -> None:
+    def equilibrate(self, solution: "solution.Solution") -> None:
         """Adjust the speciation of a Solution object to achieve chemical equilibrium."""
         warnings.warn("equilibrate() has no effect in IdealEOS!")
         return
@@ -177,7 +177,7 @@ class NativeEOS(EOS):
         # store the solution composition to see whether we need to re-instantiate the solution
         self._stored_comp = None
 
-    def _setup_ppsol(self, solution: "Solution") -> None:
+    def _setup_ppsol(self, solution: "solution.Solution") -> None:
         """Helper method to set up a PhreeqPython solution for subsequent analysis."""
         self._stored_comp = solution.components.copy()
         solv_mass = solution.solvent_mass.to("kg").magnitude
@@ -215,7 +215,7 @@ class NativeEOS(EOS):
             if bare_el in SPECIAL_ELEMENTS:
                 # PHREEQC will ignore float-formatted oxi states. Need to make sure we are
                 # passing, e.g. 'C(4)' and not 'C(4.0)'
-                key = f'{bare_el}({int(float(el.split("(")[-1].split(")")[0]))})'
+                key = f"{bare_el}({int(float(el.split('(')[-1].split(')')[0]))})"
             elif bare_el in ["H", "O"]:
                 continue
             else:
@@ -252,11 +252,11 @@ class NativeEOS(EOS):
             self.ppsol.forget()
             self.ppsol = None
 
-    def get_activity_coefficient(self, solution: "Solution", solute: str):
+    def get_activity_coefficient(self, solution: "solution.Solution", solute: str):
         r"""
-        Whenever the appropriate parameters are available, the Pitzer model [may]_ is used.
+        Whenever the appropriate parameters are available, the Pitzer model [may11]_ is used.
         If no Pitzer parameters are available, then the appropriate equations are selected
-        according to the following logic: [stumm]_.
+        according to the following logic: [stumm96]_.
 
         I <= 0.0005: Debye-Huckel equation
         0.005 < I <= 0.1:  Guntelberg approximation
@@ -266,7 +266,7 @@ class NativeEOS(EOS):
         The ionic strength, activity coefficients, and activities are all
         calculated based on the molal (mol/kg) concentration scale. If a different
         scale is given as input, then the molal-scale activity coefficient :math:`\gamma_\pm` is
-        converted according to [rbs]_
+        converted according to [rbs68]_
 
         .. math:: f_\pm = \gamma_\pm * (1 + M_w \sum_i \nu_i m_i)
 
@@ -287,10 +287,9 @@ class NativeEOS(EOS):
         Returns:
             The mean ion activity coefficient of the solute in question on  the selected scale.
 
-
         Notes:
             For multicomponent mixtures, pyEQL implements the "effective Pitzer model"
-            presented by Mistry et al. [mistry]_. In this model, the activity coefficient
+            presented by Mistry et al. [mistry13]_. In this model, the activity coefficient
             of a salt in a multicomponent mixture is calculated using an "effective
             molality," which is the molality that would result in a single-salt
             mixture with the same total ionic strength as the multicomponent solution.
@@ -298,18 +297,15 @@ class NativeEOS(EOS):
             .. math:: m_{effective} = \frac{2 I}{(\nu_{+} z_{+}^2 + \nu_{-}- z_{-}^2)}
 
         References:
-            .. [may] May, P. M., Rowland, D., Hefter, G., & Königsberger, E. (2011).
-                A Generic and Updatable Pitzer Characterization of Aqueous Binary Electrolyte Solutions at 1 bar and 25 °C.
-               *Journal of Chemical & Engineering Data*, 56(12), 5066-5077. doi:10.1021/je2009329
-
-        .. [stumm] Stumm, Werner and Morgan, James J. *Aquatic Chemistry*, 3rd ed,
-               pp 165. Wiley Interscience, 1996.
+            .. [may11] May, P. M., Rowland, D., Hefter, G., & Königsberger, E. (2011).
+                     A Generic and Updatable Pitzer Characterization of Aqueous Binary Electrolyte Solutions at 1 bar
+                     and 25 °C. *Journal of Chemical & Engineering Data*, 56(12), 5066-5077. doi:10.1021/je2009329
 
-        .. [rbs] Robinson, R. A.; Stokes, R. H. Electrolyte Solutions: Second Revised
-               Edition; Butterworths: London, 1968, p.32.
+            .. [stumm96] Stumm, Werner and Morgan, James J. *Aquatic Chemistry*, 3rd ed,
+                       pp 165. Wiley Interscience, 1996.
 
-        .. [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.
+            .. [rbs68] Robinson, R. A.; Stokes, R. H. Electrolyte Solutions: Second Revised
+                     Edition; Butterworths: London, 1968, p.32.
 
         See Also:
             :attr:`pyEQL.solution.Solution.ionic_strength`
@@ -321,12 +317,9 @@ class NativeEOS(EOS):
         # identify the predominant salt that this ion is a member of
         salt = None
         rform = standardize_formula(solute)
-        for v in solution.get_salt_dict().values():
-            if v == "HOH":
-                continue
-            if rform == v["cation"] or rform == v["anion"]:
-                del v["mol"]
-                salt = Salt.from_dict(v)
+        for d in solution.get_salt_dict().values():
+            if rform == d["salt"].cation or rform == d["salt"].anion:
+                salt = d["salt"]
                 break
 
         # show an error if no salt can be found that contains the solute
@@ -344,8 +337,8 @@ class NativeEOS(EOS):
             # determine alpha1 and alpha2 based on the type of salt
             # see the May reference for the rules used to determine
             # alpha1 and alpha2 based on charge
-            if salt.nu_cation >= 2 and salt.nu_anion <= -2:
-                if salt.nu_cation >= 3 or salt.nu_anion <= -3:
+            if salt.z_cation >= 2 and salt.z_anion <= -2:
+                if salt.z_cation >= 3 or salt.z_anion <= -3:
                     alpha1 = 2.0
                     alpha2 = 50.0
                 else:
@@ -429,17 +422,17 @@ class NativeEOS(EOS):
 
         return molal
 
-    def get_osmotic_coefficient(self, solution: "Solution") -> ureg.Quantity:
+    def get_osmotic_coefficient(self, solution: "solution.Solution") -> ureg.Quantity:
         r"""
         Return the *molal scale* osmotic coefficient of solute, given a Solution
         object.
 
-        Osmotic coefficient is calculated using the Pitzer model. [may]_ If appropriate parameters for
+        Osmotic coefficient is calculated using the Pitzer model. [may11]_ If appropriate parameters for
         the model are not available, then pyEQL raises a WARNING and returns an osmotic
         coefficient of 1.
 
         If the 'rational' scale is given as input, then the molal-scale osmotic
-        coefficient :math:`\phi` is converted according to [rbs]_
+        coefficient :math:`\phi` is converted according to [rbs68]_
 
         .. math:: g = - \phi M_{w} \frac{\sum_{i} \nu_{i} m_{i}}{\ln x_{w}}
 
@@ -463,7 +456,7 @@ class NativeEOS(EOS):
 
         Notes:
             For multicomponent mixtures, pyEQL adopts the "effective Pitzer model"
-            presented by Mistry et al. [mstry]_. In this approach, the osmotic coefficient of
+            presented by Mistry et al. [mistry13]_. In this approach, the osmotic coefficient of
             each individual salt is calculated using the normal Pitzer model based
             on its respective concentration. Then, an effective osmotic coefficient
             is calculated as the concentration-weighted average of the individual
@@ -480,17 +473,6 @@ class NativeEOS(EOS):
             the author confirmed that the weight factor should be the true molality, and that is what is implemented
             in pyEQL.)
 
-        References:
-            .. [may] May, P. M., Rowland, D., Hefter, G., & Königsberger, E. (2011).
-                A Generic and Updatable Pitzer Characterization of Aqueous Binary Electrolyte Solutions at 1 bar and
-                25 °C. Journal of Chemical & Engineering Data, 56(12), 5066-5077. doi:10.1021/je2009329
-
-            .. [rbs] Robinson, R. A.; Stokes, R. H. Electrolyte Solutions: Second Revised
-                Edition; Butterworths: London, 1968, p.32.
-
-            .. [mstry] 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.
-
         Examples:
             >>> s1 = pyEQL.Solution({'Na+': '0.2 mol/kg', 'Cl-': '0.2 mol/kg'})
             >>> s1.get_osmotic_coefficient()
@@ -500,6 +482,24 @@ class NativeEOS(EOS):
             >>> s1.get_osmotic_coefficient()
             <Quantity(0.891409618, 'dimensionless')>
 
+        References:
+            [may11]
+
+            May, P. M., Rowland, D., Hefter, G., & Königsberger, E. (2011).
+            A Generic and Updatable Pitzer Characterization of Aqueous Binary Electrolyte Solutions at 1 bar
+            and 25 °C. Journal of Chemical & Engineering Data, 56(12), 5066-5077. doi:10.1021/je2009329
+
+            [rbs68]
+
+            Robinson, R. A.; Stokes, R. H. Electrolyte Solutions: Second Revised Edition; Butterworths: London, 1968,
+            p.32.
+
+            [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.
+
         """
         ionic_strength = solution.ionic_strength
 
@@ -510,11 +510,7 @@ class NativeEOS(EOS):
         # coefficint for each, and average them into an effective osmotic
         # coefficient
         for d in solution.get_salt_dict().values():
-            item = Salt(d["cation"], d["anion"])
-            # ignore HOH in the salt list
-            if item.formula == "HOH":
-                continue
-
+            item = d["salt"]
             # determine alpha1 and alpha2 based on the type of salt
             # see the May reference for the rules used to determine
             # alpha1 and alpha2 based on charge
@@ -574,9 +570,9 @@ class NativeEOS(EOS):
             return effective_osmotic_sum / molality_sum
         except ZeroDivisionError:
             # this means the solution is empty
-            return 1
+            return ureg.Quantity(1.0)
 
-    def get_solute_volume(self, solution: "Solution") -> ureg.Quantity:
+    def get_solute_volume(self, solution: "solution.Solution") -> ureg.Quantity:
         """Return the volume of the solutes."""
         # identify the predominant salt in the solution
         salt = solution.get_salt()
@@ -584,8 +580,8 @@ class NativeEOS(EOS):
 
         # use the pitzer approach if parameters are available
         pitzer_calc = False
+        param = None if salt is None else solution.get_property(salt.formula, "model_parameters.molar_volume_pitzer")
 
-        param = solution.get_property(salt.formula, "model_parameters.molar_volume_pitzer")
         if param is not None:
             # determine the average molality of the salt
             # this is necessary for solutions inside e.g. an ion exchange
@@ -596,8 +592,8 @@ class NativeEOS(EOS):
             # determine alpha1 and alpha2 based on the type of salt
             # see the May reference for the rules used to determine
             # alpha1 and alpha2 based on charge
-            if salt.nu_cation >= 2 and salt.nu_anion >= 2:
-                if salt.nu_cation >= 3 or salt.nu_anion >= 3:
+            if salt.z_cation >= 2 and salt.z_anion <= -2:
+                if salt.z_cation >= 3 or salt.z_anion <= -3:
                     alpha1 = 2.0
                     alpha2 = 50.0
                 else:
@@ -660,7 +656,7 @@ class NativeEOS(EOS):
 
         return solute_vol.to("L")
 
-    def equilibrate(self, solution: "Solution") -> None:
+    def equilibrate(self, solution: "solution.Solution") -> None:
         """Adjust the speciation of a Solution object to achieve chemical equilibrium."""
         if self.ppsol is not None:
             self.ppsol.forget()
@@ -699,7 +695,6 @@ class NativeEOS(EOS):
     def __deepcopy__(self, memo) -> "NativeEOS":
         # custom deepcopy required because the PhreeqPython instance used by the Native and Phreeqc engines
         # is not pickle-able.
-        import copy
 
         cls = self.__class__
         result = cls.__new__(cls)
@@ -735,7 +730,7 @@ class PhreeqcEOS(NativeEOS):
         """
         super().__init__(phreeqc_db=phreeqc_db)
 
-    def get_activity_coefficient(self, solution: "Solution", solute: str) -> ureg.Quantity:
+    def get_activity_coefficient(self, solution: "solution.Solution", solute: str) -> ureg.Quantity:
         """
         Return the *molal scale* activity coefficient of solute, given a Solution
         object.
@@ -759,7 +754,7 @@ class PhreeqcEOS(NativeEOS):
 
         return ureg.Quantity(act, "dimensionless")
 
-    def get_osmotic_coefficient(self, solution: "Solution") -> ureg.Quantity:
+    def get_osmotic_coefficient(self, solution: "solution.Solution") -> ureg.Quantity:
         """
         Return the *molal scale* osmotic coefficient of solute, given a Solution
         object.
@@ -771,7 +766,7 @@ class PhreeqcEOS(NativeEOS):
         # TODO - find a way to access or calculate osmotic coefficient
         return ureg.Quantity(1, "dimensionless")
 
-    def get_solute_volume(self, solution: "Solution") -> ureg.Quantity:
+    def get_solute_volume(self, solution: "solution.Solution") -> ureg.Quantity:
         """Return the volume of the solutes."""
         # TODO - phreeqc seems to have no concept of volume, but it does calculate density
         return ureg.Quantity(0, "L")

pyEQL/equilibrium.py

@@ -129,10 +129,10 @@ def adjust_temp_arrhenius(
         TODO - add better reference
 
         .. math::
-            ln(\frac{K2}{K1}) = \frac{E_a}{R} ( \frac{1}{T_{1}} - {\frac{1}{T_2}} )
+            \ln\left((\frac{K_2}{K_1}\right) = \frac{E_a}{R} \left( \frac{1}{T_{1}} - {\frac{1}{T_2}} \right)
 
     References:
-        http://chemwiki.ucdavis.edu/Physical_Chemistry/Kinetics/Reaction_Rates/Temperature_Dependence_of_Reaction_Rates/Arrhenius_Equation
+        https://chem.libretexts.org/Bookshelves/Physical_and_Theoretical_Chemistry_Textbook_Maps/Physical_Chemistry_(LibreTexts)/28%3A_Chemical_Kinetics_I_-_Rate_Laws/28.07%3A_Rate_Constants_Are_Usually_Strongly_Temperature_Dependent
 
     Examples:
         >>> adjust_temp_arrhenius(7,900*ureg.Quantity('kJ/mol'),37*ureg.Quantity('degC'),97*ureg.Quantity('degC')) #doctest: +ELLIPSIS

pyEQL/functions.py

@@ -97,17 +97,17 @@ def entropy_mix(solution1: Solution, solution2: Solution):
 
             \Delta_{mix} S = \sum_i {(n_c + n_d) R \ln x_b} - \sum_i {n_c R \ln x_c} - \sum_i {n_d R \ln x_d}
 
-        Where :math:`n` is the number of moles of substance, :math:`T` is the temperature in kelvin, :math:`x` is the mole fraction of solute :math:`i`,
-        and  subscripts :math:`b`, :math:`c`, and :math:`d` refer to the concentrated, dilute, and blended
-        Solutions, respectively.
+        Where :math:`n` is the number of moles of substance, :math:`T` is the temperature in kelvin, :math:`x` is the
+        mole fraction of solute :math:`i`, and  subscripts :math:`b`, :math:`c`, and :math:`d` refer to the
+        concentrated, dilute, and blended Solutions, respectively.
 
         Note that dissociated ions must be counted as separate components,
         so a simple salt dissolved in water is a three component solution (cation,
         anion, and water).
 
     References:
-        Koga, Yoshikata, 2007. *Solution Thermodynamics and its Application to Aqueous Solutions:
-            A differential approach.* Elsevier, 2007, pp. 23-37.
+        Koga, Yoshikata, 2007. *Solution Thermodynamics and its Application to Aqueous Solutions: *
+        *A differential approach.* Elsevier, 2007, pp. 23-37.
 
     """
     concentrate = solution1

pyEQL/salt_ion_match.py

@@ -91,7 +91,7 @@ class Salt(MSONable):
     # 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 [mistry]_.
+        r"""Calculate the effective molality according to [mistry13]_.
 
         .. math:: 2 I \over (\nu_+ z_+^2 + \nu_- z_- ^2)
 
@@ -103,7 +103,7 @@ class Salt(MSONable):
             Quantity: the effective molality of the salt in the parent solution
 
         References:
-            .. [mistry] Mistry, K. H.; Hunter, H. a.; Lienhard V, J. H. Effect of composition and nonideal solution behavior
+            .. [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.
         """