pyEQL 1.1.1__py3-none-any.whl → 1.1.3__py3-none-any.whl

pyEQL/engines.py

@@ -229,10 +229,7 @@ class NativeEOS(EOS):
                 d[key] = str(mol / solv_mass)
 
             # tell PHREEQC which species to use for charge balance
-            if (
-                solution.balance_charge is not None
-                and solution.balance_charge in solution.get_components_by_element()[el]
-            ):
+            if solution.balance_charge is not None and solution._cb_species in solution.get_components_by_element()[el]:
                 d[key] += " charge"
 
         # create the PHREEQC solution object
@@ -690,26 +687,8 @@ class NativeEOS(EOS):
             )
 
         # 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:
-            logger.warning(
-                "After equilibration, the charge balance of the solution was not electroneutral."
-                f" {charge_adjust} eq of charge were added via {solution.balance_charge}"
-            )
-
-            if solution.balance_charge is None:
-                pass
-            elif solution.balance_charge == "pH":
-                solution.components["H+"] += charge_adjust
-            elif solution.balance_charge == "pE":
-                raise NotImplementedError
-            else:
-                z = solution.get_property(solution.balance_charge, "charge")
-                solution.add_amount(solution.balance_charge, f"{charge_adjust/z} mol")
+        # note that if balance_charge is set, it will have been passed to PHREEQC, so the only reason to re-adjust charge balance here is to account for any missing species.
+        solution._adjust_charge_balance()
 
         # rescale the solvent mass to ensure the total mass of solution does not change
         # this is important because PHREEQC and the pyEQL database may use slightly different molecular

pyEQL/solution.py

@@ -35,6 +35,7 @@ from pyEQL.utils import FormulaDict, create_water_substance, interpret_units, st
 EQUIV_WT_CACO3 = ureg.Quantity(100.09 / 2, "g/mol")
 # string to denote unknown oxidation states
 UNKNOWN_OXI_STATE = "unk"
+K_W = 1e-14  # ion product of water at 25 degC
 
 
 class Solution(MSONable):
@@ -242,7 +243,7 @@ class Solution(MSONable):
 
         # set the pH with H+ and OH-
         self.add_solute("H+", str(10 ** (-1 * pH)) + "mol/L")
-        self.add_solute("OH-", str(10 ** (-1 * (14 - pH))) + "mol/L")
+        self.add_solute("OH-", str(K_W / (10 ** (-1 * pH))) + "mol/L")
 
         # populate the other solutes
         self._solutes = solutes
@@ -261,39 +262,34 @@ class Solution(MSONable):
             for item in self._solutes:
                 self.add_solute(*item)
 
-        # adjust the charge balance, if necessary
+        # determine the species that will be used for charge balancing, when needed.
+        # this is necessary to do even if the composition is already electroneutral,
+        # because the appropriate species also needs to be passed to equilibrate
+        # to keep from distorting the charge balance.
         cb = self.charge_balance
-        if not np.isclose(cb, 0, atol=1e-8) and self.balance_charge is not None:
-            balanced = False
-            self.logger.info(
-                f"Solution is not electroneutral (C.B. = {cb} eq/L). Adding {balance_charge} to compensate."
-            )
-            if self.balance_charge == "pH":
-                self.components["H+"] += (
-                    -1 * cb * self.volume.to("L").magnitude
-                )  # if C.B. is negative, we need to add cations. H+ is 1 eq/mol
-                balanced = True
-            elif self.balance_charge == "pE":
-                raise NotImplementedError("Balancing charge via redox (pE) is not yet implemented!")
-            else:
-                ions = set().union(*[self.cations, self.anions])  # all ions
-                if self.balance_charge == "auto":
-                    # add the most abundant ion of the opposite charge
-                    if cb <= 0:
-                        self.balance_charge = max(self.cations, key=self.cations.get)
-                    elif cb > 0:
-                        self.balance_charge = max(self.anions, key=self.anions.get)
-                if self.balance_charge not in ions:
-                    raise ValueError(
-                        f"Charge balancing species {self.balance_charge} was not found in the solution!. "
-                        f"Species {ions} were found."
-                    )
-                z = self.get_property(self.balance_charge, "charge")
-                self.components[self.balance_charge] += -1 * cb / z * self.volume.to("L").magnitude
-                balanced = True
+        if self.balance_charge is None:
+            self._cb_species = None
+        elif self.balance_charge == "pH":
+            self._cb_species = "H[+1]"
+        elif self.balance_charge == "pE":
+            raise NotImplementedError("Balancing charge via redox (pE) is not yet implemented!")
+        elif self.balance_charge == "auto":
+            # add the most abundant ion of the opposite charge
+            if cb <= 0:
+                self._cb_species = max(self.cations, key=self.cations.get)
+            elif cb > 0:
+                self._cb_species = max(self.anions, key=self.anions.get)
+        else:
+            ions = set().union(*[self.cations, self.anions])  # all ions
+            self._cb_species = self.balance_charge
+            if self._cb_species not in ions:
+                raise ValueError(
+                    f"Charge balancing species {self._cb_species} was not found in the solution!. "
+                    f"Species {ions} were found."
+                )
 
-            if not balanced:
-                warnings.warn(f"Unable to balance charge using species {self.balance_charge}")
+        # adjust charge balance, if necessary
+        self._adjust_charge_balance()
 
     @property
     def mass(self) -> Quantity:
@@ -2288,6 +2284,57 @@ class Solution(MSONable):
 
         return distance.to("nm")
 
+    def _adjust_charge_balance(self, atol=1e-8) -> None:
+        """Helper method to adjust the charge balance of the Solution."""
+        cb = self.charge_balance
+        if not np.isclose(cb, 0, atol=atol):
+            self.logger.info(f"Solution is not electroneutral (C.B. = {cb} eq/L).")
+            if self.balance_charge is None:
+                # Nothing to do.
+                self.logger.info("balance_charge is None, so no charge balancing will be performed.")
+                return
+
+            self.logger.info(
+                f"Solution is not electroneutral (C.B. = {cb} eq/L). Adjusting {self._cb_species} to compensate."
+            )
+
+            if self.balance_charge == "pH":
+                # the charge imbalance associated with the H+ / OH- system can be expressed
+                # as ([H+] - [OH-]) or ([H+] - K_W/[H+]). If we adjust H+, we also have to
+                # adjust OH- to maintain water equilibrium.
+                C_hplus = self.get_amount("H+", "mol/L").magnitude
+                start_imbalance = C_hplus - K_W / C_hplus
+                new_imbalance = start_imbalance - cb
+                # calculate the new concentration of H+ that will balance the charge
+                # solve H^2 - new_imbalance H - K_W  = 0, so a=1, b=-new_imbalance, c=-K_W
+                # check b^2 - 4ac; are there any real roots?
+                if new_imbalance**2 - 4 * 1 * K_W < 0:
+                    self.logger.error("Cannot balance charge by adjusting pH. The imbalance is too large.")
+                    return
+                new_hplus = max(
+                    [
+                        (new_imbalance + np.sqrt(new_imbalance**2 + 4 * 1 * K_W)) / 2,
+                        (new_imbalance - np.sqrt(new_imbalance**2 + 4 * 1 * K_W)) / 2,
+                    ]
+                )
+                self.set_amount("H+", f"{new_hplus} mol/L")
+                self.set_amount("OH-", f"{K_W/new_hplus} mol/L")
+                assert np.isclose(self.charge_balance, 0, atol=atol), f"{self.charge_balance}"
+                return
+
+            z = self.get_property(self._cb_species, "charge")
+            try:
+                self.add_amount(self._cb_species, f"{-1*cb/z} mol")
+                return
+            except ValueError:
+                # if the concentration is negative, it must mean there is not enough present.
+                # remove everything that's present and log an error.
+                self.components[self._cb_species] = 0
+                self.logger.error(
+                    f"There is not enough {self._cb_species} present to balance the charge. Try a different species."
+                )
+                return
+
     def _update_volume(self):
         """Recalculate the solution volume based on composition."""
         self._volume = self._get_solvent_volume() + self._get_solute_volume()

{pyEQL-1.1.1.dist-info → pyEQL-1.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyEQL
-Version: 1.1.1
+Version: 1.1.3
 Summary: A python interface for solution chemistry
 Author-email: Ryan Kingsbury <kingsbury@princeton.edu>
 Project-URL: Docs, https://pyeql.readthedocs.io/

{pyEQL-1.1.1.dist-info → pyEQL-1.1.3.dist-info}/RECORD

@@ -1,11 +1,11 @@
 pyEQL/__init__.py,sha256=OCp_PiQEPyVoi1VX0ursBzHJWN6nDS1Id6bTBOgqCYs,1999
 pyEQL/activity_correction.py,sha256=eOixjgTd5hTrTRD5s6aPCCG12lAIH7-lRN0Z1qHu678,37151
-pyEQL/engines.py,sha256=9Pfo6YATahB9EUdBpUkE3xBAyDQqp1MjG9LO-zD4fAg,35517
+pyEQL/engines.py,sha256=VbdQSPKlNehW96U1XxWYwjTy6k6WDpZZEx_Y4l3qZv4,34686
 pyEQL/equilibrium.py,sha256=YCtoAJSgn1WC9NJnc3H4FTJdKQvogsvCuj7HqlKMtww,8307
 pyEQL/functions.py,sha256=nc-Hc61MmW-ELBR1PByJvQnELxM7PZexMHbU_O5-Bnw,10584
 pyEQL/salt_ion_match.py,sha256=0nCZXmeo67VqcyYWQpPx-81hjSvnsg8HFB3fIyfjW_k,4070
 pyEQL/solute.py,sha256=no00Rc3tRfHmyht4wm2UXA1KZhKC45tWMO5QEkZY6yg,5140
-pyEQL/solution.py,sha256=WET68HPDaleEsIxK2ObtAlNR7oolunNU5mNjxNeGG8U,113696
+pyEQL/solution.py,sha256=LwlfY6Q19QEcY8MJpP_mcJgEw0ohNaGfAqAiqhdPmU8,116022
 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
@@ -17,10 +17,10 @@ pyEQL/presets/rainwater.yaml,sha256=S0WHZNDfCJyjSSFxNFdkypjn2s3P0jJGCiYIxvi1ibA,
 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.1.1.dist-info/AUTHORS.md,sha256=K9ZLhKFwZ2zLlFXwN62VuUYCpr5T6n4mOUCUHlytTUs,415
-pyEQL-1.1.1.dist-info/COPYING,sha256=Ww2oUywfFTn242v9ksCgQdIVSpcMXJiKKePn0GFm25E,7649
-pyEQL-1.1.1.dist-info/LICENSE.txt,sha256=2Zf1F7RzbpeposgIxUydpurqNCMoMgDi2gAB65_GjwQ,969
-pyEQL-1.1.1.dist-info/METADATA,sha256=5EWAVR_RKxcnBz3XHpl-OOCBfUo2sJMMOyJATkAZXIw,6096
-pyEQL-1.1.1.dist-info/WHEEL,sha256=Wyh-_nZ0DJYolHNn1_hMa4lM7uDedD_RGVwbmTjyItk,91
-pyEQL-1.1.1.dist-info/top_level.txt,sha256=QMOaZjCAm_lS4Njsjh4L0B5aWnJFGQMYKhuH88CG1co,6
-pyEQL-1.1.1.dist-info/RECORD,,
+pyEQL-1.1.3.dist-info/AUTHORS.md,sha256=K9ZLhKFwZ2zLlFXwN62VuUYCpr5T6n4mOUCUHlytTUs,415
+pyEQL-1.1.3.dist-info/COPYING,sha256=Ww2oUywfFTn242v9ksCgQdIVSpcMXJiKKePn0GFm25E,7649
+pyEQL-1.1.3.dist-info/LICENSE.txt,sha256=2Zf1F7RzbpeposgIxUydpurqNCMoMgDi2gAB65_GjwQ,969
+pyEQL-1.1.3.dist-info/METADATA,sha256=aDLyZrhXd2laVUiJ6drgt4RFSvlptOPxLEo9xrkaR40,6096
+pyEQL-1.1.3.dist-info/WHEEL,sha256=Wyh-_nZ0DJYolHNn1_hMa4lM7uDedD_RGVwbmTjyItk,91
+pyEQL-1.1.3.dist-info/top_level.txt,sha256=QMOaZjCAm_lS4Njsjh4L0B5aWnJFGQMYKhuH88CG1co,6
+pyEQL-1.1.3.dist-info/RECORD,,