pychnosz 1.1.11__cp312-cp312-win_amd64.whl

pychnosz/utils/formula_ox.py

@@ -0,0 +1,227 @@
+"""
+Formula oxidation state utilities for CHNOSZ.
+
+This module provides functions for working with chemical formulas that include
+element oxidation states, specifically for use with the WORM thermodynamic database.
+"""
+
+from typing import Union, Dict, List
+import pandas as pd
+
+from ..core.thermo import thermo
+from ..core.info import info
+
+
+def get_formula_ox(name: Union[str, int]) -> Dict[str, float]:
+    """
+    Get quantities of elements and their oxidation states in a chemical compound.
+
+    This function only works when a thermodynamic database with the 'formula_ox'
+    column is loaded (e.g., the WORM database). For example, an input of "magnetite"
+    would return the following: {'Fe+3': 2.0, 'Fe+2': 1.0, 'O-2': 4.0}.
+
+    Parameters
+    ----------
+    name : str or int
+        The name or database index of the chemical species of interest. Example:
+        "magnetite" or 738.
+
+    Returns
+    -------
+    dict
+        A dictionary where each key represents an element in a specific
+        oxidation state, and its value is the number of that element in the
+        chemical species' formula.
+
+    Raises
+    ------
+    TypeError
+        If input is not a string or integer.
+    AttributeError
+        If the WORM thermodynamic database is not loaded (no formula_ox attribute).
+    ValueError
+        If the species is not found in the database or does not have oxidation
+        state information.
+
+    Examples
+    --------
+    >>> import pychnosz
+    >>> # Load the WORM database
+    >>> pychnosz.thermo("WORM")
+    >>> # Get formula with oxidation states for magnetite
+    >>> pychnosz.get_formula_ox("magnetite")
+    {'Fe+3': 2.0, 'Fe+2': 1.0, 'O-2': 4.0}
+    >>> # Can also use species index
+    >>> pychnosz.get_formula_ox(738)
+    {'Fe+3': 2.0, 'Fe+2': 1.0, 'O-2': 4.0}
+
+    Notes
+    -----
+    This function requires the wormutils package to be installed for parsing
+    the formula_ox strings. Install it with: pip install wormutils
+    """
+
+    # Import parse_formula_ox from wormutils
+    try:
+        from wormutils import parse_formula_ox
+    except ImportError:
+        raise ImportError(
+            "The wormutils package is required to use get_formula_ox(). "
+            "Install it with: pip install wormutils"
+        )
+
+    # Validate input type
+    if not isinstance(name, str) and not isinstance(name, int):
+        raise TypeError(
+            "Must provide input as a string (chemical species name) or "
+            "an integer (chemical species index)."
+        )
+
+    # Get the thermo system
+    thermo_sys = thermo()
+
+    # Convert index to name if necessary
+    if isinstance(name, int):
+        species_info = info(name, messages=False)
+        if species_info is None or len(species_info) == 0:
+            raise ValueError(f"Species index {name} not found in the database.")
+        name = species_info.name.iloc[0]
+
+    # Check if formula_ox exists in thermo()
+    if not hasattr(thermo_sys, 'formula_ox') or thermo_sys.formula_ox is None:
+        raise AttributeError(
+            "The 'formula_ox' attribute is not available. "
+            "This function only works when the WORM thermodynamic database "
+            "is loaded. Load it with: pychnosz.thermo('WORM')"
+        )
+
+    df = thermo_sys.formula_ox
+
+    # Check if the species name exists in the database
+    if name not in list(df["name"]):
+        raise ValueError(
+            f"The species '{name}' was not found in the loaded thermodynamic database."
+        )
+
+    # Get the formula_ox string for this species
+    try:
+        formula_ox_str = df[df["name"] == name]["formula_ox"].iloc[0]
+    except (KeyError, IndexError):
+        raise ValueError(
+            f"The species '{name}' does not have elemental oxidation states "
+            "given in the 'formula_ox' column of the loaded thermodynamic database."
+        )
+
+    # Check if formula_ox is valid (not NaN or empty)
+    if formula_ox_str is None or (isinstance(formula_ox_str, float) and pd.isna(formula_ox_str)) or formula_ox_str == "":
+        raise ValueError(
+            f"The species '{name}' does not have elemental oxidation states "
+            "given in the 'formula_ox' column of the loaded thermodynamic database."
+        )
+
+    # Parse the formula_ox string and return
+    return parse_formula_ox(formula_ox_str)
+
+
+def get_n_element_ox(names: Union[str, int, List[Union[str, int]], pd.Series],
+                     element_ox: str,
+                     binary: bool = False) -> List[Union[float, bool]]:
+    """
+    Get the number of an element of a chosen oxidation state in chemical species formulas.
+
+    This function only works when a thermodynamic database with the 'formula_ox'
+    column is loaded (e.g., the WORM database).
+
+    If binary is False, returns a list containing the number of the chosen
+    element and oxidation state in the chemical species. For example, how many
+    ferrous irons are in the formulae of hematite, fayalite, and magnetite,
+    respectively?
+
+    >>> get_n_element_ox(names=["hematite", "fayalite", "magnetite"],
+    ...                  element_ox="Fe+2",
+    ...                  binary=False)
+    [0, 2.0, 1.0]
+
+    If binary is True, returns a list of whether or not ferrous iron is in their
+    formulas:
+
+    >>> get_n_element_ox(names=["hematite", "fayalite", "magnetite"],
+    ...                  element_ox="Fe+2",
+    ...                  binary=True)
+    [False, True, True]
+
+    Parameters
+    ----------
+    names : str, int, list of str/int, or pd.Series
+        The name or database index of a chemical species, or a list of
+        names or indices. Can also be a pandas Series (e.g., from retrieve()).
+        Example: ["hematite", "fayalite", "magnetite"] or [788, 782, 798].
+    element_ox : str
+        An element with a specific oxidation state. For example: "Fe+2" for
+        ferrous iron.
+    binary : bool, default False
+        Should the output list show True/False for presence or absence of the
+        element defined by `element_ox`? By default, this parameter is set to
+        False so the output list shows quantities of the element instead.
+
+    Returns
+    -------
+    list of float or list of bool
+        A list containing quantities of the chosen element oxidation state in
+        the formulas of the chemical species (if `binary=False`) or whether the
+        chosen element oxidation state is present in the formulae (if `binary=True`).
+
+    Raises
+    ------
+    AttributeError
+        If the WORM thermodynamic database is not loaded (no formula_ox attribute).
+    ValueError
+        If a species is not found in the database or does not have oxidation
+        state information.
+
+    Examples
+    --------
+    >>> import pychnosz
+    >>> # Load the WORM database
+    >>> pychnosz.thermo("WORM")
+    >>> # Get counts of Fe+2 in several minerals
+    >>> pychnosz.get_n_element_ox(["hematite", "fayalite", "magnetite"], "Fe+2")
+    [0, 2.0, 1.0]
+    >>> # Get binary presence/absence
+    >>> pychnosz.get_n_element_ox(["hematite", "fayalite", "magnetite"], "Fe+2", binary=True)
+    [False, True, True]
+    >>> # Can also use with retrieve()
+    >>> r = pychnosz.retrieve("Fe", ["Si", "O", "H"], state=["cr"])
+    >>> pychnosz.get_n_element_ox(r, "Fe+2")
+    [1, 0, 0, 2.0, 1, 0, 1, 3.0, 1, 3.0, 0, 7.0]
+
+    Notes
+    -----
+    This function requires the wormutils package to be installed for parsing
+    the formula_ox strings. Install it with: pip install wormutils
+    """
+
+    # Handle pandas Series (e.g., from retrieve())
+    if isinstance(names, pd.Series):
+        # Convert Series to list of indices
+        names = names.values.tolist()
+    # Handle single name/index
+    elif not isinstance(names, list):
+        names = [names]
+
+    # Get the count of element_ox for each species
+    n_list = []
+    for name in names:
+        # Get the formula_ox dictionary for this species
+        formula_ox_dict = get_formula_ox(name)
+        # Get the count of element_ox (default to 0 if not present)
+        count = formula_ox_dict.get(element_ox, 0)
+        n_list.append(count)
+
+    # Convert to binary if requested
+    if binary:
+        out_list = [True if n != 0 else False for n in n_list]
+    else:
+        out_list = n_list
+
+    return out_list

pychnosz/utils/reset.py

@@ -0,0 +1,33 @@
+"""
+Reset function for initializing the CHNOSZ thermodynamic system.
+
+This provides the reset() function that initializes/resets the global
+thermodynamic system, equivalent to reset() in the R version.
+"""
+
+from ..core.thermo import get_thermo_system
+
+
+def reset(messages: bool = True):
+    """
+    Initialize or reset the CHNOSZ thermodynamic system.
+
+    This function initializes the global thermodynamic system by loading
+    all thermodynamic data files, setting up the OBIGT database, and
+    preparing the system for calculations.
+
+    This is equivalent to the reset() function in the R version of CHNOSZ.
+
+    Parameters
+    ----------
+    messages : bool, default True
+        Whether to print informational messages
+
+    Examples
+    --------
+    >>> import pychnosz
+    >>> pychnosz.reset()  # Initialize the system
+    reset: thermodynamic system initialized
+    """
+    thermo_system = get_thermo_system()
+    thermo_system.reset(messages=messages)

pychnosz/utils/units.py

@@ -0,0 +1,259 @@
+"""
+Unit conversion utilities for CHNOSZ.
+
+This module provides functions for converting between different units commonly
+used in geochemical thermodynamics, such as temperature (C/K), pressure (bar/MPa),
+energy (cal/J), and electrochemical potentials (Eh/pe).
+
+Based on R CHNOSZ util.units.R
+"""
+
+import numpy as np
+from typing import Union, List, Optional
+import warnings
+
+from ..core.thermo import thermo
+from ..core.subcrt import subcrt
+
+
+def convert(value: Union[float, np.ndarray, List[float]],
+            units: str,
+            T: Union[float, np.ndarray] = 298.15,
+            P: Union[float, np.ndarray] = 1,
+            pH: Union[float, np.ndarray] = 7,
+            logaH2O: Union[float, np.ndarray] = 0,
+            messages: bool = True) -> Union[float, np.ndarray]:
+    """
+    Convert values to the specified units.
+
+    This function converts thermodynamic values between different units commonly
+    used in geochemistry.
+
+    Parameters
+    ----------
+    value : float, ndarray, or list
+        Value(s) to convert
+    units : str
+        Target units. Options include:
+        - Temperature: 'C', 'K'
+        - Energy: 'J', 'cal'
+        - Pressure: 'bar', 'MPa'
+        - Thermodynamic: 'G', 'logK'
+        - Electrochemical: 'Eh', 'pe', 'E0', 'logfO2'
+        - Volume: 'cm3bar', 'joules'
+    T : float or ndarray, default 298.15
+        Temperature in K (for Eh/pe/logK conversions)
+    P : float or ndarray, default 1
+        Pressure in bar (for E0/logfO2 conversions)
+    pH : float or ndarray, default 7
+        pH value (for E0/logfO2 conversions)
+    logaH2O : float or ndarray, default 0
+        Log activity of water (for E0/logfO2 conversions)
+    messages : bool, default True
+        Whether to print informational messages
+
+    Returns
+    -------
+    float or ndarray
+        Converted value(s)
+
+    Examples
+    --------
+    >>> convert(25, 'K')  # Convert 25°C to K
+    298.15
+    >>> convert(1.0, 'pe', T=298.15)  # Convert 1V Eh to pe
+    16.9
+    """
+
+    if value is None:
+        return None
+
+    # Convert to numpy array for uniform handling
+    value = np.asarray(value)
+    T = np.asarray(T)
+    P = np.asarray(P)
+    pH = np.asarray(pH)
+    logaH2O = np.asarray(logaH2O)
+
+    units = units.lower()
+
+    # Temperature conversions (C <-> K)
+    if units in ['c', 'k']:
+        CK = 273.15
+        if units == 'k':
+            return value + CK
+        if units == 'c':
+            return value - CK
+
+    # Energy conversions (J <-> cal)
+    elif units in ['j', 'cal']:
+        Jcal = 4.184
+        if units == 'j':
+            return value * Jcal
+        if units == 'cal':
+            return value / Jcal
+
+    # Gibbs energy <-> logK conversions
+    elif units in ['g', 'logk']:
+        # Gas constant (J K^-1 mol^-1)
+        R = 8.314463  # NIST value
+        if units == 'logk':
+            return value / (-np.log(10) * R * T)
+        if units == 'g':
+            return value * (-np.log(10) * R * T)
+
+    # Volume conversions (cm3bar <-> joules)
+    elif units in ['cm3bar', 'joules']:
+        if units == 'cm3bar':
+            return value * 10
+        if units == 'joules':
+            return value / 10
+
+    # Electrochemical potential conversions (Eh <-> pe)
+    elif units in ['eh', 'pe']:
+        R = 0.00831470  # Gas constant in kJ K^-1 mol^-1
+        F = 96.4935     # Faraday constant in kJ V^-1 mol^-1
+        if units == 'pe':
+            return value * F / (np.log(10) * R * T)
+        if units == 'eh':
+            return value * (np.log(10) * R * T) / F
+
+    # Pressure conversions (bar <-> MPa)
+    elif units in ['bar', 'mpa']:
+        barmpa = 10
+        if units == 'mpa':
+            return value / barmpa
+        if units == 'bar':
+            return value * barmpa
+
+    # Eh <-> logfO2 conversions
+    elif units in ['e0', 'logfo2']:
+        # Calculate equilibrium constant for: H2O = 1/2 O2 + 2 H+ + 2 e-
+        # Handle P="Psat" case (pass it directly to subcrt)
+        # Check if P is a string (including numpy string types)
+        P_is_psat = False
+        if isinstance(P, (str, np.str_)):
+            P_is_psat = str(P).lower() == 'psat'
+        elif isinstance(P, (list, tuple)):
+            # P is a list/tuple - check if it's a single-element string
+            if len(P) == 1 and isinstance(P[0], (str, np.str_)):
+                P_is_psat = str(P[0]).lower() == 'psat'
+        elif isinstance(P, np.ndarray):
+            # P is a numpy array
+            if P.ndim == 0:
+                # Scalar array - check if it's a string
+                try:
+                    if isinstance(P.item(), (str, np.str_)):
+                        P_is_psat = str(P.item()).lower() == 'psat'
+                except (ValueError, AttributeError):
+                    pass
+            elif P.size == 1:
+                # Single-element array - check if it's a string
+                try:
+                    if isinstance(P.flat[0], (str, np.str_)):
+                        P_is_psat = str(P.flat[0]).lower() == 'psat'
+                except (ValueError, AttributeError, IndexError):
+                    pass
+
+        if P_is_psat:
+            P_arg = 'Psat'
+            T_arg = np.atleast_1d(T)
+            if len(T_arg) == 1:
+                T_arg = float(T_arg[0])
+            else:
+                T_arg = T_arg.tolist()
+        else:
+            # Convert T and P to proper format for subcrt
+            T_vals = np.atleast_1d(T)
+            P_vals = np.atleast_1d(P)
+
+            # subcrt needs lists for multiple T/P values
+            if len(T_vals) > 1 or len(P_vals) > 1:
+                T_arg = T_vals.tolist() if len(T_vals) > 1 else float(T_vals[0])
+                P_arg = P_vals.tolist() if len(P_vals) > 1 else float(P_vals[0])
+            else:
+                T_arg = float(T_vals[0])
+                P_arg = float(P_vals[0])
+
+        supcrt_out = subcrt(['H2O', 'oxygen', 'H+', 'e-'],
+                           [-1, 0.5, 2, 2],
+                           T=T_arg, P=P_arg, convert=False, messages=messages, show=False)
+
+        # Extract logK values
+        if hasattr(supcrt_out.out, 'logK'):
+            logK = supcrt_out.out.logK
+        else:
+            logK = supcrt_out.out['logK']
+
+        # Convert to numpy array
+        logK = np.asarray(logK)
+
+        if units == 'logfo2':
+            # Convert Eh to logfO2
+            pe_value = convert(value, 'pe', T=T, messages=messages)
+            return 2 * (logK + logaH2O + 2*pH + 2*pe_value)
+        if units == 'e0':
+            # Convert logfO2 to Eh
+            pe_value = (-logK - 2*pH + value/2 - logaH2O) / 2
+            return convert(pe_value, 'Eh', T=T, messages=messages)
+
+    else:
+        warnings.warn(f"convert: no conversion to {units} found")
+        return value
+
+
+def envert(value: Union[float, np.ndarray, List[float]],
+           units: str) -> Union[float, np.ndarray]:
+    """
+    Convert values to the specified units from those given in thermo()$opt.
+
+    This function is used internally to convert from the user's preferred units
+    (stored in thermo().opt) to standard internal units.
+
+    Parameters
+    ----------
+    value : float, ndarray, or list
+        Value(s) to convert
+    units : str
+        Target units ('C', 'K', 'bar', 'MPa', 'J', 'cal')
+
+    Returns
+    -------
+    float or ndarray
+        Converted value(s)
+    """
+
+    if not isinstance(value, (int, float, np.ndarray, list)):
+        return value
+
+    value = np.asarray(value)
+
+    # Check if first element is numeric
+    if value.size > 0 and not np.issubdtype(value.dtype, np.number):
+        return value
+
+    units = units.lower()
+    opt = thermo().opt
+
+    # Temperature conversions
+    if units in ['c', 'k', 't.units']:
+        if units == 'c' and opt['T.units'] == 'K':
+            return convert(value, 'c')
+        if units == 'k' and opt['T.units'] == 'C':
+            return convert(value, 'k')
+
+    # Energy conversions
+    if units in ['j', 'cal', 'e.units']:
+        if units == 'j' and opt['E.units'] == 'cal':
+            return convert(value, 'j')
+        if units == 'cal' and opt['E.units'] == 'J':
+            return convert(value, 'cal')
+
+    # Pressure conversions
+    if units in ['bar', 'mpa', 'p.units']:
+        if units == 'mpa' and opt['P.units'] == 'bar':
+            return convert(value, 'mpa')
+        if units == 'bar' and opt['P.units'] == 'MPa':
+            return convert(value, 'bar')
+
+    return value