pyEQL 0.15.1__py2.py3-none-any.whl → 1.0.1__py2.py3-none-any.whl

pyEQL/__init__.py

@@ -5,6 +5,8 @@ and performing chemical thermodynamics computations.
 :copyright: 2013-2024 by Ryan S. Kingsbury
 :license: LGPL, see LICENSE for more details.
 """
+
+import logging
 from importlib.metadata import PackageNotFoundError, version  # pragma: no cover
 from importlib.resources import files
 
@@ -20,6 +22,12 @@ except PackageNotFoundError:  # pragma: no cover
 finally:
     del version, PackageNotFoundError
 
+# logging
+logger = logging.getLogger("pyEQL")
+logger.setLevel(logging.WARNING)
+logger.addHandler(logging.NullHandler())
+
+
 # Units handling
 # per the pint documentation, it's important that pint and its associated Unit
 # Registry are only instantiated once.
@@ -39,7 +47,7 @@ ureg.default_format = "P~"
 
 # create a Store for the default database
 json_db_file = files("pyEQL") / "database" / "pyeql_db.json"
-IonDB = JSONStore(str(json_db_file), key="formula")
+IonDB = JSONStore(str(json_db_file), key="formula", encoding="utf8")
 # By calling connect on init, we get the expensive JSON reading operation out
 # of the way. Subsequent calls to connect will bypass this and access the already-
 # instantiated Store in memory, which should speed up instantiation of Solution objects.

pyEQL/activity_correction.py

@@ -12,14 +12,17 @@ are called from within the get_activity_coefficient method of the Solution class
 :license: LGPL, see LICENSE for more details.
 
 """
-import math
 
+import logging
+
+import numpy as np
 from pint import Quantity
 
 from pyEQL import ureg
-from pyEQL.logging_system import logger
 from pyEQL.utils import create_water_substance
 
+logger = logging.getLogger(f"pyEQL.{__name__}")
+
 
 def _debye_parameter_B(temperature: str = "25 degC") -> Quantity:
     r"""
@@ -111,11 +114,11 @@ def _debye_parameter_activity(temperature: str = "25 degC") -> "Quantity":
 
     debyeparam = (
         ureg.elementary_charge**3
-        * (2 * math.pi * ureg.N_A * ureg.Quantity(water_substance.rho, "g/L")) ** 0.5
-        / (4 * math.pi * ureg.epsilon_0 * water_substance.epsilon * ureg.boltzmann_constant * T) ** 1.5
+        * (2 * np.pi * ureg.N_A * ureg.Quantity(water_substance.rho, "g/L")) ** 0.5
+        / (4 * np.pi * ureg.epsilon_0 * water_substance.epsilon * ureg.boltzmann_constant * T) ** 1.5
     )
 
-    logger.info(rf"Computed Debye-Huckel Limiting Law Constant A^{{\gamma}} = {debyeparam} at {temperature}")
+    logger.debug(rf"Computed Debye-Huckel Limiting Law Constant A^{{\gamma}} = {debyeparam} at {temperature}")
     return debyeparam.to("kg ** 0.5 / mol ** 0.5")
 
 
@@ -149,7 +152,7 @@ def _debye_parameter_osmotic(temperature="25 degC"):
 
     """
     output = 1 / 3 * _debye_parameter_activity(temperature)
-    logger.info(f"Computed Debye-Huckel Limiting slope for osmotic coefficient A^phi = {output} at {temperature}")
+    logger.debug(f"Computed Debye-Huckel Limiting slope for osmotic coefficient A^phi = {output} at {temperature}")
     return output.to("kg ** 0.5 /mol ** 0.5")
 
 
@@ -206,7 +209,7 @@ def _debye_parameter_volume(temperature="25 degC"):
     if T.to("degC").magnitude != 25:
         logger.warning("Debye-Huckel limiting slope for volume is approximate when T is not equal to 25 degC")
 
-    logger.info(f"Computed Debye-Huckel Limiting Slope for volume A^V = {result} at {temperature}")
+    logger.debug(f"Computed Debye-Huckel Limiting Slope for volume A^V = {result} at {temperature}")
 
     return result.to("cm ** 3 * kg ** 0.5 /  mol ** 1.5")
 
@@ -245,7 +248,7 @@ def get_activity_coefficient_debyehuckel(ionic_strength, z=1, temperature="25 de
 
     log_f = -_debye_parameter_activity(temperature) * z**2 * ionic_strength**0.5
 
-    return math.exp(log_f) * ureg.Quantity(1, "dimensionless")
+    return np.exp(log_f) * ureg.Quantity(1, "dimensionless")
 
 
 def get_activity_coefficient_guntelberg(ionic_strength, z=1, temperature="25 degC"):
@@ -280,11 +283,9 @@ def get_activity_coefficient_guntelberg(ionic_strength, z=1, temperature="25 deg
     if not ionic_strength.magnitude <= 0.1:
         logger.warning("Ionic strength exceeds valid range of the Guntelberg approximation")
 
-    log_f = (
-        -_debye_parameter_activity(temperature) * z**2 * ionic_strength**0.5 / (1 + ionic_strength.magnitude**0.5)
-    )
+    log_f = -_debye_parameter_activity(temperature) * z**2 * ionic_strength**0.5 / (1 + ionic_strength.magnitude**0.5)
 
-    return math.exp(log_f) * ureg.Quantity(1, "dimensionless")
+    return np.exp(log_f) * ureg.Quantity(1, "dimensionless")
 
 
 def get_activity_coefficient_davies(ionic_strength, z=1, temperature="25 degC"):
@@ -326,7 +327,7 @@ def get_activity_coefficient_davies(ionic_strength, z=1, temperature="25 degC"):
         * (ionic_strength.magnitude**0.5 / (1 + ionic_strength.magnitude**0.5) - 0.2 * ionic_strength.magnitude)
     )
 
-    return math.exp(log_f) * ureg.Quantity(1, "dimensionless")
+    return np.exp(log_f) * ureg.Quantity(1, "dimensionless")
 
 
 def get_activity_coefficient_pitzer(
@@ -436,7 +437,7 @@ def get_activity_coefficient_pitzer(
         b,
     )
 
-    return math.exp(loggamma) * ureg.Quantity(1, "dimensionless")
+    return np.exp(loggamma) * ureg.Quantity(1, "dimensionless")
 
 
 def get_apparent_volume_pitzer(
@@ -532,7 +533,7 @@ def get_apparent_volume_pitzer(
         (nu_cation + nu_anion)
         * abs(z_cation * z_anion)
         * (_debye_parameter_volume(temperature) / 2 / b)
-        * math.log(1 + b * ionic_strength**0.5)
+        * np.log(1 + b * ionic_strength**0.5)
     )
 
     third_term = (
@@ -565,7 +566,7 @@ def _pitzer_f1(x):
     # return 0 if the input is 0
     if x == 0:
         return 0
-    return 2 * (1 - (1 + x) * math.exp(-x)) / x**2
+    return 2 * (1 - (1 + x) * np.exp(-x)) / x**2
 
 
 def _pitzer_f2(x):
@@ -585,7 +586,7 @@ def _pitzer_f2(x):
     # return 0 if the input is 0
     if x == 0:
         return 0
-    return -2 * (1 - (1 + x + x**2 / 2) * math.exp(-x)) / x**2
+    return -2 * (1 - (1 + x + x**2 / 2) * np.exp(-x)) / x**2
 
 
 def _pitzer_B_MX(ionic_strength, alpha1, alpha2, beta0, beta1, beta2):
@@ -615,9 +616,7 @@ def _pitzer_B_MX(ionic_strength, alpha1, alpha2, beta0, beta1, beta2):
         :func:`_pitzer_f1`
 
     """
-    coeff = (
-        beta0 + beta1 * _pitzer_f1(alpha1 * ionic_strength**0.5) + beta2 * _pitzer_f1(alpha2 * ionic_strength**0.5)
-    )
+    coeff = beta0 + beta1 * _pitzer_f1(alpha1 * ionic_strength**0.5) + beta2 * _pitzer_f1(alpha2 * ionic_strength**0.5)
     return coeff.magnitude
 
 
@@ -693,6 +692,10 @@ def _pitzer_B_phi(ionic_strength, alpha1, alpha2, beta0, beta1, beta2):
         and Representation with an Ion Interaction (Pitzer) Model.
         Journal of Chemical & Engineering Data, 55(2), 830-838. doi:10.1021/je900487a
     """
+    import math
+
+    # TODO - for some reason this specific method requires the use of math.exp rather than np.exp. Using np.exp raises
+    # a dimensionalityerror.
     return beta0 + beta1 * math.exp(-alpha1 * ionic_strength**0.5) + beta2 * math.exp(-alpha2 * ionic_strength**0.5)
 
 
@@ -773,7 +776,7 @@ def _pitzer_log_gamma(
         -1
         * abs(z_cation * z_anion)
         * _debye_parameter_osmotic(temperature)
-        * (ionic_strength**0.5 / (1 + b * ionic_strength**0.5) + 2 / b * math.log(1 + b * ionic_strength**0.5))
+        * (ionic_strength**0.5 / (1 + b * ionic_strength**0.5) + 2 / b * np.log(1 + b * ionic_strength**0.5))
     )
     second_term = 2 * molality * nu_cation * nu_anion / (nu_cation + nu_anion) * (B_MX + B_phi)
     third_term = 3 * molality**2 * (nu_cation * nu_anion) ** 1.5 / (nu_cation + nu_anion) * C_phi

pyEQL/engines.py

@@ -6,6 +6,7 @@ pyEQL engines for computing aqueous equilibria (e.g., speciation, redox, etc.).
 
 """
 
+import logging
 import os
 import warnings
 from abc import ABC, abstractmethod
@@ -14,13 +15,8 @@ from typing import Literal
 
 from phreeqpython import PhreeqPython
 
-# internal pyEQL imports
 import pyEQL.activity_correction as ac
-
-# import the parameters database
-# the pint unit registry
 from pyEQL import ureg
-from pyEQL.logging_system import logger
 from pyEQL.salt_ion_match import Salt
 from pyEQL.utils import standardize_formula
 
@@ -28,6 +24,8 @@ from pyEQL.utils import standardize_formula
 # PHREEQC will ignore others (e.g., 'Na(1)')
 SPECIAL_ELEMENTS = ["S", "C", "N", "Cu", "Fe", "Mn"]
 
+logger = logging.getLogger(__name__)
+
 
 class EOS(ABC):
     """
@@ -49,7 +47,7 @@ class EOS(ABC):
             solution: pyEQL Solution object
             solute: str identifying the solute of interest
 
-        Returns
+        Returns:
             Quantity: dimensionless quantity object
 
         Raises:
@@ -64,7 +62,7 @@ class EOS(ABC):
         Args:
             solution: pyEQL Solution object
 
-        Returns
+        Returns:
             Quantity: dimensionless molal scale osmotic coefficient
 
         Raises:
@@ -79,7 +77,7 @@ class EOS(ABC):
         Args:
             solution: pyEQL Solution object
 
-        Returns
+        Returns:
             Quantity: solute volume in L
 
         Raises:
@@ -96,7 +94,7 @@ class EOS(ABC):
         Args:
             solution: pyEQL Solution object
 
-        Returns
+        Returns:
             Nothing. The speciation of the Solution is modified in-place.
 
         Raises:
@@ -175,9 +173,7 @@ class NativeEOS(EOS):
         self._stored_comp = None
 
     def _setup_ppsol(self, solution):
-        """
-        Helper method to set up a PhreeqPython solution for subsequent analysis.
-        """
+        """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
         # inherit bulk solution properties
@@ -199,6 +195,16 @@ class NativeEOS(EOS):
         # add the composition to the dict
         # also, skip H and O
         for el, mol in solution.get_el_amt_dict().items():
+            # CAUTION - care must be taken to avoid unintended behavior here. get_el_amt_dict() will return
+            # all distinct oxi states of each element present. If there are elements present whose oxi states
+            # are NOT recognized by PHREEQC (via SPECIAL_ELEMENTS) then the amount of only 1 oxi state will be
+            # entered into the composition dict. This can especially cause problems after equilibrate() has already
+            # been called once. For example, equilibrating a simple NaCl solution generates Cl species that are assigned
+            # various oxidations states, -1 mostly, but also 1, 2, and 3. Since the concentrations of everything
+            # except the -1 oxi state are tiny, this can result in Cl "disappearing" from the solution if
+            # equlibrate is called again. It also causes non-determinism, because the amount is taken from whatever
+            # oxi state happens to be iterated through last.
+
             # strip off the oxi state
             bare_el = el.split("(")[0]
             if bare_el in SPECIAL_ELEMENTS:
@@ -210,7 +216,12 @@ class NativeEOS(EOS):
             else:
                 key = bare_el
 
-            d[key] = str(mol / solv_mass)
+            if key in d:
+                # when multiple oxi states for the same (non-SPECIAL) element are present, make sure to
+                # add all their amounts together
+                d[key] += str(mol / solv_mass)
+            else:
+                d[key] = str(mol / solv_mass)
 
             # tell PHREEQC which species to use for charge balance
             if (
@@ -318,7 +329,7 @@ class NativeEOS(EOS):
 
         # show an error if no salt can be found that contains the solute
         if salt is None:
-            logger.warning("No salts found that contain solute %s. Returning unit activity coefficient." % solute)
+            logger.error("No salts found that contain solute %s. Returning unit activity coefficient." % solute)
             return ureg.Quantity(1, "dimensionless")
 
         # use the Pitzer model for higher ionic strength, if the parameters are available
@@ -367,15 +378,16 @@ class NativeEOS(EOS):
                 str(solution.temperature),
             )
 
-            logger.info(
-                f"Calculated activity coefficient of species {solute} as {activity_coefficient} based on salt {salt} using Pitzer model"
+            logger.debug(
+                f"Calculated activity coefficient of species {solute} as {activity_coefficient} based on salt"
+                f" {salt} using Pitzer model"
             )
             molal = activity_coefficient
 
         # for very low ionic strength, use the Debye-Huckel limiting law
         elif solution.ionic_strength.magnitude <= 0.005:
-            logger.info(
-                "Ionic strength = %s. Using Debye-Huckel to calculate activity coefficient." % solution.ionic_strength
+            logger.debug(
+                f"Ionic strength = {solution.ionic_strength}. Using Debye-Huckel to calculate activity coefficient."
             )
             molal = ac.get_activity_coefficient_debyehuckel(
                 solution.ionic_strength,
@@ -385,8 +397,8 @@ class NativeEOS(EOS):
 
         # use the Guntelberg approximation for 0.005 < I < 0.1
         elif solution.ionic_strength.magnitude <= 0.1:
-            logger.info(
-                "Ionic strength = %s. Using Guntelberg to calculate activity coefficient." % solution.ionic_strength
+            logger.debug(
+                f"Ionic strength = {solution.ionic_strength}. Using Guntelberg to calculate activity coefficient."
             )
             molal = ac.get_activity_coefficient_guntelberg(
                 solution.ionic_strength,
@@ -396,9 +408,8 @@ class NativeEOS(EOS):
 
         # use the Davies equation for 0.1 < I < 0.5
         elif solution.ionic_strength.magnitude <= 0.5:
-            logger.info(
-                "Ionic strength = %s. Using Davies equation to calculate activity coefficient."
-                % solution.ionic_strength
+            logger.debug(
+                f"Ionic strength = {solution.ionic_strength}. Using Davies equation to calculate activity coefficient."
             )
             molal = ac.get_activity_coefficient_davies(
                 solution.ionic_strength,
@@ -407,9 +418,9 @@ class NativeEOS(EOS):
             )
 
         else:
-            logger.warning(
-                "Ionic strength too high to estimate activity for species %s. Specify parameters for Pitzer model. Returning unit activity coefficient"
-                % solute
+            logger.error(
+                f"Ionic strength too high to estimate activity for species {solute}. Specify parameters for Pitzer "
+                "model. Returning unit activity coefficient"
             )
 
             molal = ureg.Quantity(1, "dimensionless")
@@ -479,11 +490,11 @@ class NativeEOS(EOS):
                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 = pyEQL.Solution({'Na+': '0.2 mol/kg', 'Cl-': '0.2 mol/kg'})
             >>> s1.get_osmotic_coefficient()
             <Quantity(0.923715281, 'dimensionless')>
 
-            >>> s1 = pyEQL.Solution([['Mg+2','0.3 mol/kg'],['Cl-','0.6 mol/kg']],temperature='30 degC')
+            >>> s1 = pyEQL.Solution({'Mg+2': '0.3 mol/kg', 'Cl-': '0.6 mol/kg'},temperature='30 degC')
             >>> s1.get_osmotic_coefficient()
             <Quantity(0.891409618, 'dimensionless')>
 
@@ -494,7 +505,7 @@ class NativeEOS(EOS):
         molality_sum = 0
 
         # loop through all the salts in the solution, calculate the osmotic
-        # coefficint for reach, and average them into an effective osmotic
+        # 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"])
@@ -544,17 +555,18 @@ class NativeEOS(EOS):
                     str(solution.temperature),
                 )
 
-                logger.info(
-                    f"Calculated osmotic coefficient of water as {osmotic_coefficient} based on salt {item.formula} using Pitzer model"
+                logger.debug(
+                    f"Calculated osmotic coefficient of water as {osmotic_coefficient} based on salt "
+                    f"{item.formula} using Pitzer model"
                 )
                 effective_osmotic_sum += concentration * osmotic_coefficient
 
             else:
-                logger.warning(
-                    "Cannot calculate osmotic coefficient because Pitzer parameters for salt %s are not specified. Returning unit osmotic coefficient"
-                    % item.formula
+                logger.debug(
+                    f"Returning unit osmotic coefficient for salt {item.formula} because Pitzer parameters are not"
+                    "available in database."
                 )
-                effective_osmotic_sum += concentration * osmotic_coefficient
+                effective_osmotic_sum += concentration * 1
 
         try:
             return effective_osmotic_sum / molality_sum
@@ -621,7 +633,7 @@ class NativeEOS(EOS):
 
             pitzer_calc = True
 
-            logger.info("Updated solution volume using Pitzer model for solute %s" % salt.formula)
+            logger.debug("Updated solution volume using Pitzer model for solute %s" % salt.formula)
 
         # add the partial molar volume of any other solutes, except for water
         # or the parent salt, which is already accounted for by the Pitzer parameters
@@ -637,12 +649,11 @@ class NativeEOS(EOS):
             part_vol = solution.get_property(solute, "size.molar_volume")
             if part_vol is not None:
                 solute_vol += part_vol * ureg.Quantity(mol, "mol")
-                logger.info("Updated solution volume using direct partial molar volume for solute %s" % solute)
+                logger.debug("Updated solution volume using direct partial molar volume for solute %s" % solute)
 
             else:
                 logger.warning(
-                    "Partial molar volume data not available for solute %s. Solution volume will not be corrected."
-                    % solute
+                    f"Volume of solute {solute} will be ignored because partial molar volume data are not available."
                 )
 
         return solute_vol.to("L")
@@ -662,7 +673,6 @@ class NativeEOS(EOS):
             solution.components[s] = mol
 
         # make sure all species are accounted for
-        charge_adjust = 0
         assert set(self._stored_comp.keys()) - set(solution.components.keys()) == set()
 
         # log a message if any components were not touched by PHREEQC
@@ -673,6 +683,11 @@ class NativeEOS(EOS):
                 f"After equilibration, the amounts of species {missing_species} were not modified "
                 "by PHREEQC. These species are likely absent from its database."
             )
+
+        # re-adjust charge balance for any missing species
+        # note that if balance_charge is set, it will have been passed to PHREEQC, so we only need to adjust
+        # for any missing species here.
+        charge_adjust = 0
         for s in missing_species:
             charge_adjust += -1 * solution.get_amount(s, "eq").magnitude
         if charge_adjust != 0:
@@ -681,11 +696,10 @@ class NativeEOS(EOS):
                 f" {charge_adjust} eq of charge were added via {solution.balance_charge}"
             )
 
-            # re-adjust charge balance
             if solution.balance_charge is None:
                 pass
             elif solution.balance_charge == "pH":
-                solution.components["H+"] += charge_adjust
+                solution.components["H+"] += charge_adjust.magnitude
             elif solution.balance_charge == "pE":
                 raise NotImplementedError
             else:

pyEQL/equilibrium.py

@@ -8,12 +8,15 @@ NOTE: these methods are not currently used but are here for the future.
 :license: LGPL, see LICENSE for more details.
 
 """
+
 # import libraries for scientific functions
-import math
+import logging
+
+import numpy as np
 
-# the pint unit registry
 from pyEQL import ureg
-from pyEQL.logging_system import logger
+
+logger = logging.getLogger(__name__)
 
 # TODO - not used. Remove?
 SPECIES_ALIAISES = {
@@ -49,7 +52,7 @@ def adjust_temp_pitzer(c1, c2, c3, c4, c5, temp, temp_ref=ureg.Quantity("298.15
     return (
         c1
         + c2 * (1 / temp + 1 / temp_ref)
-        + c2 * math.log(temp / temp_ref)
+        + c2 * np.log(temp / temp_ref)
         + c3 * (temp - temp_ref)
         + c4 * (temp**2 - temp_ref**2)
         + c5 * (temp**-2 - temp_ref**-2)
@@ -89,15 +92,17 @@ def adjust_temp_vanthoff(equilibrium_constant, enthalpy, temperature, reference_
         >>> adjust_temp_vanthoff(0.15,ureg.Quantity('-197.6 kJ/mol'),ureg.Quantity('42 degC')) #doctest: +ELLIPSIS
         0.00203566...
     """
-    output = equilibrium_constant * math.exp(
+    output = equilibrium_constant * np.exp(
         enthalpy / ureg.R * (1 / reference_temperature.to("K") - 1 / temperature.to("K"))
     )
 
-    logger.info(
+    logger.debug(
         "Adjusted equilibrium constant K=%s from %s to %s degrees Celsius with Delta H = %s. Adjusted K = %s % equilibrium_constant,reference_temperature,temperature,enthalpy,output"
     )
 
-    logger.warning("Van't Hoff equation assumes enthalpy is independent of temperature over the range of interest")
+    logger.info(
+        "Note that the Van't Hoff equation assumes enthalpy is independent of temperature over the range of interest"
+    )
     return output
 
 
@@ -124,7 +129,7 @@ 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(\frac{K2}{K1}) = \frac{E_a}{R} ( \frac{1}{T_{1}} - {\frac{1}{T_2}} )
 
     References:
         http://chemwiki.ucdavis.edu/Physical_Chemistry/Kinetics/Reaction_Rates/Temperature_Dependence_of_Reaction_Rates/Arrhenius_Equation
@@ -133,12 +138,13 @@ def adjust_temp_arrhenius(
         >>> adjust_temp_arrhenius(7,900*ureg.Quantity('kJ/mol'),37*ureg.Quantity('degC'),97*ureg.Quantity('degC')) #doctest: +ELLIPSIS
         1.8867225...e-24
     """
-    output = rate_constant * math.exp(
+    output = rate_constant * np.exp(
         activation_energy / ureg.R * (1 / reference_temperature.to("K") - 1 / temperature.to("K"))
     )
 
-    logger.info(
-        "Adjusted parameter %s from %s to %s degrees Celsius with Activation Energy = %s kJ/mol. Adjusted value = %s % rate_constant,reference_temperature,temperature,activation_energy,output"
+    logger.debug(
+        f"Adjusted parameter {rate_constant} from {reference_temperature} to {temperature} degrees Celsius with"
+        f"Activation Energy = {activation_energy}s kJ/mol. Adjusted value = {output}"
     )
 
     return output
@@ -215,7 +221,7 @@ def alpha(n, pH, pKa_list):
 
     # return the desired distribution factor
     alpha = terms_list[n] / sum(terms_list)
-    logger.info(
+    logger.debug(
         "Calculated %s-deprotonated acid distribution coefficient of %s for pKa=%s at pH %s % n,alpha,pKa_list,pH"
     )
     return alpha