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

pyEQL/solute.py

@@ -1,228 +1,163 @@
 """
-pyEQL Solute class
+pyEQL Solute class.
 
-This file contains functions and methods for managing properties of 
+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-2020 by Ryan S. Kingsbury
+:copyright: 2013-2024 by Ryan S. Kingsbury
 :license: LGPL, see LICENSE for more details.
 
 """
 
-# the pint unit registry
-from pyEQL import unit
+from __future__ import annotations
 
-# logging system
 import logging
-# add a filter to emit only unique log messages to the handler
-from pyEQL.logging_system import Unique
-# import the parameters database
-from pyEQL import paramsDB as db
+import warnings
+from dataclasses import asdict, dataclass, field
+from typing import Literal
 
-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 Solute:
-    """
-    represent each chemical species as an object containing its formal charge, 
-    transport numbers, concentration, activity, etc. 
-    
-    """
+import numpy as np
+from pymatgen.core.ion import Ion
 
-    def __init__(self, formula, amount, volume, solvent_mass, parameters={}):
-        """
-        Parameters
-        ----------
-        formula : str
-                    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').
-        amount : str
-                    The amount of substance in the specified unit system. The string should contain both a quantity and
-                    a pint-compatible representation of a unit. e.g. '5 mol/kg' or '0.1 g/L'
-        volume : pint Quantity
-                    The volume of the solution
-        solvent_mass : pint Quantity
-                    The mass of solvent in the parent solution.
-        parameters : dictionary, optional
-                    Dictionary of custom parameters, such as diffusion coefficients, transport numbers, etc. Specify 
-                    parameters as key:value pairs separated by commas within curly braces, e.g. 
-                    {diffusion_coeff:5e-10,transport_number:0.8}. The 'key' is the name that will be used to access 
-                    the parameter, the value is its value.
-        """
-        # import the chemical formula interpreter module
-        import pyEQL.chemical_formula as chem
-
-        # check that 'formula' is a valid chemical formula
-        if not chem.is_valid_formula:
-            logger.error("Invalid chemical formula specified.")
-            return None
-        else:
-            self.formula = formula
-
-            # set molecular weight
-            self.mw = chem.get_molecular_weight(formula) * unit("g/mol")
-
-            # set formal charge
-            self.charge = chem.get_formal_charge(formula)
+from pyEQL.utils import standardize_formula
 
-            # translate the 'amount' string into a pint Quantity
-            quantity = unit(amount)
-
-            self.moles = quantity.to(
-                "moles", "chem", mw=self.mw, volume=volume, solvent_mass=solvent_mass
-            )
+logger = logging.getLogger(__name__)
 
-            # trigger the function that checks whether parameters already exist for this species, and if not,
-            # searches the database files and creates them
-            db.search_parameters(self.formula)
 
-    def get_parameter(
-        self, parameter, temperature=None, pressure=None, ionic_strength=None
-    ):
-        """
-        Return the value of the parameter named 'parameter'
-        
-        """
-        # Search for this solute in the database of parameters
+@dataclass
+class Datum:
+    """Document containing data for a single computed or experimental property."""
 
-        # TODO - handle the case where multiple parameters with same name exist. Need function
-        # to compare specified conditions and choose the most appropriate parameter
-        param = db.get_parameter(self.formula, parameter)
+    value: str
+    reference: str | None = None
+    data_type: Literal["computed", "experimental", "fitted", "unknown"] = "unknown"
 
-        return param.get_value(temperature, pressure, ionic_strength)
+    @property
+    def magnitude(self):
+        """Return the numerical value of a Datum."""
+        return float(self.value.split(" ")[0])
 
-    def add_parameter(self, name, magnitude, units="", **kwargs):
-        """
-        Add a parameter to the parameters database for a solute
-        
-        See pyEQL.parameters documentation for a description of the arguments
-        
-        """
-        import pyEQL.parameter as pm
+    @property
+    def unit(self):
+        """Return the unit of a Datum."""
+        return self.value.split(" ")[-1]
 
-        newparam = pm.Parameter(name, magnitude, units, **kwargs)
-        db.add_parameter(self.get_name(), newparam)
+    @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 get_name(self):
-        """
-        Return the name (formula) of the solute
-        
-        Parameters
-        ----------
-        None
-        
-        Returns
-        -------
-        str
-            The chemical formula of the solute
-            
-        """
-        return self.formula
+    def as_dict(self):
+        """Return a dictionary representation of the Datum."""
+        return dict(asdict(self).items())
 
-    def get_formal_charge(self):
-        """
-        Return the formal charge of the solute
-        
-        Parameters
-        ----------
-        None
-        
-        Returns
-        -------
-        int
-            The formal charge of the solute
-            
-        """
-        return self.charge
 
-    def get_molecular_weight(self):
-        """
-        Return the molecular weight of the solute
-        
-        Parameters
-        ----------
-        None
-        
-        Returns
-        -------
-        Quantity
-            The molecular weight of the solute, in g/mol
-        """
-        return self.mw
+@dataclass
+class Solute:
+    """
+    represent each chemical species as an object containing its formal charge,
+    transport numbers, concentration, activity, etc.
 
-    def get_moles(self):
-        """
-        Return the moles of solute in the solution
-        
-        Parameters
-        ----------
-        None
-        
-        Returns
-        -------
-        Quantity
-            The number of moles of solute
-            
-        """
-        return self.moles
+    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').
+    """
 
-    def add_moles(self, amount, volume, solvent_mass):
-        """
-        Increase or decrease the amount of a substance present in the solution
-        
-        Parameters
-        ----------
-        amount: str quantity
-                Amount of substance to add. Must be in mass or substance units.
-                Negative values indicate subtraction of material.
-        
-        """
-        quantity = unit(amount)
-        self.moles += quantity.to(
-            "moles", "chem", mw=self.mw, volume=volume, solvent_mass=solvent_mass
+    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 set_moles(self, amount, volume, solvent_mass):
-        """
-        Set the amount of a substance present in the solution
-        
-        Parameters
-        ----------
-        amount: str quantity
-                Desired amount of substance. Must be greater than or equal to 
-                zero and given in mass or substance units.
-        
-        """
-        quantity = unit(amount)
-        self.moles = quantity.to(
-            "moles", "chem", mw=self.mw, volume=volume, solvent_mass=solvent_mass
-        )
+    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):
+    def __str__(self) -> str:
         return (
             "Species "
-            + str(self.get_name())
+            + str(self.formula)
             + " MW="
-            + str(self.get_molecular_weight())
+            + str(self.mw)
             + " Formal Charge="
-            + str(self.get_formal_charge())
+            + str(self.charge)
             + " Amount= "
-            + str(self.get_moles())
+            + str(self.moles)
         )