pychnosz 1.1.12__cp310-cp310-macosx_15_0_x86_64.whl

pychnosz/models/water.py

@@ -0,0 +1,480 @@
+"""
+Water properties calculation module.
+
+This module provides Python equivalents of the R functions in water.R:
+- water(): Calculate thermodynamic and electrostatic properties of H2O
+- Support for multiple water models (SUPCRT92, IAPWS95, DEW)
+- Automatic model selection and property calculation
+
+Author: CHNOSZ Python port
+"""
+
+import pandas as pd
+import numpy as np
+import warnings
+from typing import Union, List, Optional, Dict, Any
+
+from ..core.thermo import thermo
+from .supcrt92_fortran import water_SUPCRT92
+from .iapws95 import water_IAPWS95
+from .dew import water_DEW
+
+
+class WaterModelError(Exception):
+    """Exception raised for water model calculation errors."""
+    pass
+
+
+def water(property: Optional[Union[str, List[str]]] = None,
+          T: Union[float, np.ndarray, List[float]] = 298.15,
+          P: Union[float, np.ndarray, List[float], str] = 1.0,
+          Psat_floor: Union[float, None] = 1.0,
+          model: Optional[str] = None,
+          messages: bool = True) -> Union[str, float, np.ndarray, Dict[str, Any]]:
+    """
+    Calculate thermodynamic and electrostatic properties of liquid H2O.
+    
+    This is the main water function that provides the same interface as the
+    R CHNOSZ water() function, with support for multiple water models.
+    
+    Parameters
+    ----------
+    property : str, list of str, or None
+        Properties to calculate. If None, returns current water model.
+        If water model name (SUPCRT92, IAPWS95, DEW), sets the water model.
+        Available properties depend on the water model used.
+    T : float or array-like
+        Temperature in Kelvin
+    P : float, array-like, or "Psat"
+        Pressure in bar, or "Psat" for saturation pressure
+    Psat_floor : float or None
+        Minimum pressure floor for Psat calculations (SUPCRT92 only)
+    model : str, optional
+        Override the default water model for this calculation
+    messages : bool, default True
+        Whether to print informational messages
+
+    Returns
+    -------
+    str, float, array, or dict
+        Current water model name, single property value, array of values,
+        or dictionary with calculated properties
+        
+    Examples
+    --------
+    >>> import pychnosz
+    >>> pychnosz.reset()
+    >>> 
+    >>> # Get current water model
+    >>> model = pychnosz.water()
+    >>> print(model)  # 'SUPCRT92'
+    >>> 
+    >>> # Set water model
+    >>> old_model = pychnosz.water('IAPWS95')
+    >>> 
+    >>> # Calculate single property
+    >>> density = pychnosz.water('rho', T=298.15, P=1.0)
+    >>> 
+    >>> # Calculate multiple properties
+    >>> props = pychnosz.water(['rho', 'epsilon'], T=298.15, P=1.0)
+    >>> 
+    >>> # Temperature array
+    >>> temps = np.array([273.15, 298.15, 373.15])
+    >>> densities = pychnosz.water('rho', T=temps, P=1.0)
+    >>> 
+    >>> # Saturation pressure
+    >>> psat = pychnosz.water('Psat', T=373.15)
+    """
+    
+    # Get thermo system
+    thermo_system = thermo()
+
+    # Ensure thermo is initialized before accessing/setting options
+    # This prevents reset() from clearing options later
+    if not thermo_system.is_initialized():
+        thermo_system.reset(messages=False)
+
+    # Case 1: Query current water model
+    if property is None:
+        return thermo_system.get_option('water', 'SUPCRT92')
+
+    # Case 2: Set water model
+    if isinstance(property, str) and property.upper() in ['SUPCRT92', 'SUPCRT', 'IAPWS95', 'IAPWS', 'DEW']:
+        old_model = thermo_system.get_option('water', 'SUPCRT92')
+
+        # Normalize model name
+        if property.upper() in ['SUPCRT92', 'SUPCRT']:
+            new_model = 'SUPCRT92'
+        elif property.upper() in ['IAPWS95', 'IAPWS']:
+            new_model = 'IAPWS95'
+        elif property.upper() == 'DEW':
+            new_model = 'DEW'
+
+        thermo_system.set_option('water', new_model)
+        if messages:
+            print(f"water: setting water model to {new_model}")
+        return  # Return None instead of the old model
+    
+    # Case 3: Calculate properties
+    # Determine which model to use
+    if model is not None:
+        water_model = model.upper()
+    else:
+        water_model = thermo_system.get_option('water', 'SUPCRT92').upper()
+    
+    # Normalize model names
+    if water_model in ['SUPCRT92', 'SUPCRT']:
+        water_model = 'SUPCRT92'
+    elif water_model in ['IAPWS95', 'IAPWS']:
+        water_model = 'IAPWS95'
+    elif water_model == 'DEW':
+        water_model = 'DEW'
+    else:
+        warnings.warn(f"Unknown water model '{water_model}', using SUPCRT92")
+        water_model = 'SUPCRT92'
+    
+    # Convert inputs
+    T = np.atleast_1d(np.asarray(T, dtype=float))
+    
+    if isinstance(P, str):
+        P_input = P
+    else:
+        P_input = np.atleast_1d(np.asarray(P, dtype=float))
+        # Make T and P same length
+        if len(P_input) < len(T):
+            P_input = np.resize(P_input, len(T))
+        elif len(T) < len(P_input):
+            T = np.resize(T, len(P_input))
+    
+    # Call appropriate water model
+    try:
+        if water_model == 'SUPCRT92':
+            result = _call_supcrt92(property, T, P_input, Psat_floor)
+        elif water_model == 'IAPWS95':
+            result = _call_iapws95(property, T, P_input, Psat_floor)  
+        elif water_model == 'DEW':
+            result = _call_dew(property, T, P_input)
+        else:
+            raise ValueError(f"Unsupported water model: {water_model}")
+            
+    except Exception as e:
+        raise WaterModelError(f"Error calculating water properties with {water_model} model: {e}")
+    
+    # Apply Psat rounding to match R CHNOSZ behavior
+    # Round Psat values to 4 decimal places (round up to ensure liquid phase)
+    result = _apply_psat_rounding(result, property)
+    
+    return result
+
+
+def _call_supcrt92(property: Union[str, List[str]], 
+                   T: np.ndarray, 
+                   P: Union[np.ndarray, str], 
+                   Psat_floor: Union[float, None]) -> Union[float, np.ndarray, Dict[str, Any]]:
+    """Call SUPCRT92 water model."""
+    
+    # Check if Psat property is requested - if so, automatically set P="Psat"
+    # This matches R CHNOSZ behavior where water("Psat", T=298.15) works
+    properties_list = property if isinstance(property, list) else [property]
+    if "Psat" in properties_list:
+        P_converted = "Psat"
+    elif isinstance(P, str) and P == "Psat":
+        P_converted = "Psat"
+    else:
+        P_converted = P  # Already in bar
+    
+    # Handle Psat_floor
+    kwargs = {}
+    if Psat_floor is not None:
+        kwargs['Psat_floor'] = Psat_floor
+    
+    return water_SUPCRT92(property, T, P_converted, **kwargs)
+
+
+def _call_iapws95(property: Union[str, List[str]], 
+                  T: np.ndarray, 
+                  P: Union[np.ndarray, str], 
+                  Psat_floor: Union[float, None]) -> Union[float, np.ndarray, Dict[str, Any]]:
+    """Call IAPWS95 water model using accurate implementation."""
+    
+    # Use the accurate IAPWS95 implementation that matches R CHNOSZ exactly
+    from .iapws95 import water_IAPWS95_accurate
+    
+    # Check if Psat property is requested - if so, automatically set P="Psat"
+    # This matches R CHNOSZ behavior where water("Psat", T=298.15) works
+    properties_list = property if isinstance(property, list) else [property]
+    if "Psat" in properties_list:
+        P = "Psat"
+    
+    # Handle Psat calculation
+    if isinstance(P, str) and P == "Psat":
+        # For Psat requests, we need to calculate saturation pressure
+        # This is not directly implemented yet, so we'll fall back to SUPCRT92
+        try:
+            # Use the FORTRAN SUPCRT92 implementation for Psat calculation
+            kwargs = {}
+            if Psat_floor is not None:
+                kwargs['Psat_floor'] = Psat_floor
+            return water_SUPCRT92(property, T, P, **kwargs)
+        except Exception:
+            raise NotImplementedError("Psat calculation not yet implemented for IAPWS95")
+    
+    # Use accurate IAPWS95 implementation
+    # P is already in bar, which is what the accurate implementation expects
+    result = water_IAPWS95_accurate(property, T=T, P=P)
+    
+    # Check if any properties returned NaN and fall back to SUPCRT92 for those
+    if isinstance(result, dict):
+        # Multiple properties case
+        fallback_needed = {}
+        for prop, value in result.items():
+            if isinstance(value, np.ndarray):
+                if np.any(np.isnan(value)):
+                    fallback_needed[prop] = value
+            elif np.isnan(value):
+                fallback_needed[prop] = value
+        
+        if fallback_needed:
+            # Get fallback values from SUPCRT92
+            fallback_props = list(fallback_needed.keys())
+            kwargs = {}
+            if Psat_floor is not None:
+                kwargs['Psat_floor'] = Psat_floor
+            fallback_result = water_SUPCRT92(fallback_props, T, P, **kwargs)
+            
+            # Replace NaN values with SUPCRT92 results
+            if isinstance(fallback_result, dict):
+                for prop in fallback_props:
+                    if prop in fallback_result:
+                        result[prop] = fallback_result[prop]
+            elif len(fallback_props) == 1:
+                result[fallback_props[0]] = fallback_result
+    
+    elif isinstance(result, np.ndarray) and np.any(np.isnan(result)):
+        # Single property array case with NaN values
+        kwargs = {}
+        if Psat_floor is not None:
+            kwargs['Psat_floor'] = Psat_floor
+        result = water_SUPCRT92(property, T, P, **kwargs)
+    
+    elif np.isscalar(result) and np.isnan(result):
+        # Single property scalar case with NaN
+        kwargs = {}
+        if Psat_floor is not None:
+            kwargs['Psat_floor'] = Psat_floor
+        result = water_SUPCRT92(property, T, P, **kwargs)
+    
+    return result
+
+
+def _call_dew(property: Union[str, List[str]], 
+              T: np.ndarray, 
+              P: Union[np.ndarray, str]) -> Union[float, np.ndarray, Dict[str, Any]]:
+    """Call DEW water model."""
+    # DEW uses bar, same as input
+    return water_DEW(property, T, P)
+
+
+def _apply_psat_rounding(result: Union[float, np.ndarray, Dict[str, Any]], 
+                        property: Union[str, List[str]]) -> Union[float, np.ndarray, Dict[str, Any]]:
+    """
+    Apply Psat rounding to match R CHNOSZ behavior.
+    
+    R CHNOSZ rounds Psat to 4 decimal places. This ensures we get the same
+    pressure values and helps maintain water in liquid phase at saturation.
+    
+    Examples:
+    - 165.21128856501093 -> 165.2113 (rounds up, stays in liquid phase)
+    """
+    import math
+    
+    if isinstance(result, dict):
+        # Multiple properties - check if Psat is among them
+        if 'Psat' in result:
+            psat_val = result['Psat']
+            if isinstance(psat_val, np.ndarray):
+                # Round up each element to 4 decimal places, handle NaN values
+                result['Psat'] = np.where(np.isnan(psat_val), psat_val, np.ceil(psat_val * 10000) / 10000)
+            else:
+                # Single value - round up to 4 decimal places, handle NaN
+                if not np.isnan(psat_val):
+                    result['Psat'] = math.ceil(psat_val * 10000) / 10000
+    
+    elif isinstance(property, str) and property == 'Psat':
+        # Single Psat property
+        if isinstance(result, np.ndarray):
+            # Round up each element to 4 decimal places, handle NaN values
+            result = np.where(np.isnan(result), result, np.ceil(result * 10000) / 10000)
+        else:
+            # Single value - round up to 4 decimal places, handle NaN  
+            if not np.isnan(result):
+                result = math.ceil(result * 10000) / 10000
+    
+    elif isinstance(property, list) and 'Psat' in property:
+        # Property list containing Psat - this shouldn't happen with current structure
+        # but handle it for completeness
+        pass
+    
+    return result
+
+
+def available_properties(model: str = 'SUPCRT92') -> List[str]:
+    """
+    Get list of available properties for a water model.
+    
+    Parameters
+    ----------
+    model : str
+        Water model name ('SUPCRT92', 'IAPWS95', or 'DEW')
+        
+    Returns
+    -------
+    List[str]
+        List of available property names
+    """
+    model = model.upper()
+    
+    if model in ['SUPCRT92', 'SUPCRT']:
+        from .supcrt92 import supcrt92_water
+        return supcrt92_water.available_properties()
+    elif model in ['IAPWS95', 'IAPWS']:
+        from .iapws95 import iapws95_water
+        return iapws95_water.available_properties()
+    elif model == 'DEW':
+        from .dew import dew_water
+        return dew_water.available_properties()
+    else:
+        raise ValueError(f"Unknown water model: {model}")
+
+
+def get_water_models() -> List[str]:
+    """
+    Get list of available water models.
+    
+    Returns
+    -------
+    List[str]
+        List of available water model names
+    """
+    return ['SUPCRT92', 'IAPWS95', 'DEW']
+
+
+def compare_models(property: str, 
+                   T: Union[float, np.ndarray] = 298.15,
+                   P: Union[float, np.ndarray] = 1.0) -> pd.DataFrame:
+    """
+    Compare water property calculations across different models.
+    
+    Parameters
+    ----------
+    property : str
+        Property to compare
+    T : float or array
+        Temperature in Kelvin
+    P : float or array
+        Pressure in bar
+        
+    Returns
+    -------
+    pd.DataFrame
+        Comparison of property values from different models
+    """
+    T = np.atleast_1d(np.asarray(T, dtype=float))
+    P = np.atleast_1d(np.asarray(P, dtype=float))
+    
+    results = {}
+    models = ['SUPCRT92', 'IAPWS95', 'DEW']
+    
+    for model in models:
+        try:
+            if model == 'SUPCRT92':
+                result = water_SUPCRT92(property, T, P)
+            elif model == 'IAPWS95':
+                # Convert bar to kPa for IAPWS95
+                result = water_IAPWS95(property, T, P * 100.0)
+                # Convert units back if needed
+                if property == 'rho':
+                    result = result / 1000.0  # kg/m³ to g/cm³
+            elif model == 'DEW':
+                result = water_DEW(property, T, P)
+            
+            results[model] = result
+            
+        except Exception as e:
+            print(f"Error with {model}: {e}")
+            results[model] = np.full_like(T, np.nan)
+    
+    # Create DataFrame
+    if len(T) == 1 and len(P) == 1:
+        # Single point
+        data = {model: [results[model]] if np.isscalar(results[model]) else results[model] 
+                for model in models}
+        df = pd.DataFrame(data, index=[f"T={T[0]:.1f}K, P={P[0]:.1f}bar"])
+    else:
+        # Multiple points
+        data = {model: results[model] for model in models}
+        index = [f"T={t:.1f}K, P={p:.1f}bar" for t, p in zip(T, P)]
+        df = pd.DataFrame(data, index=index)
+    
+    return df
+
+
+if __name__ == "__main__":
+    # Quick test of water models
+    print("CHNOSZ Water Models Test")
+    print("=" * 30)
+    
+    # Test basic functionality
+    T_test = 298.15
+    P_test = 1.0
+    
+    print(f"Water at {T_test} K, {P_test} bar:")
+    
+    # Test each model
+    for model in ['SUPCRT92', 'IAPWS95', 'DEW']:
+        try:
+            if model == 'SUPCRT92':
+                rho = water_SUPCRT92('rho', T_test, P_test)
+                epsilon = water_SUPCRT92('epsilon', T_test, P_test)
+            elif model == 'IAPWS95':
+                rho = water_IAPWS95('rho', T_test, P_test * 100) / 1000.0  # Convert to g/cm³
+                epsilon = water_IAPWS95('epsilon', T_test, P_test * 100)
+            elif model == 'DEW':
+                rho = water_DEW('rho', T_test, P_test)
+                epsilon = water_DEW('epsilon', T_test, P_test)
+            
+            print(f"  {model}: ρ = {rho:.3f} g/cm³, ε = {epsilon:.1f}")
+            
+        except Exception as e:
+            print(f"  {model}: Error - {e}")
+    
+    # Test unified interface
+    print("\nTesting unified water() interface:")
+    
+    # This would require the thermo system to be initialized
+    try:
+        from ..core.thermo import thermo
+        from ..utils.reset import reset
+        
+        reset()  # Initialize system
+        
+        # Test model switching
+        old_model = water('IAPWS95')
+        current_model = water()
+        print(f"Switched from {old_model} to {current_model}")
+        
+        # Test property calculation
+        density = water('rho', T=298.15, P=1.0)
+        print(f"Density: {density:.3f}")
+        
+    except Exception as e:
+        print(f"Unified interface test failed: {e}")
+        print("(This is expected if run standalone)")
+    
+    # Test comparison
+    print("\nModel comparison:")
+    try:
+        comp = compare_models('rho', T=298.15, P=1.0)
+        print(comp)
+    except Exception as e:
+        print(f"Comparison failed: {e}")

pychnosz/utils/__init__.py

@@ -0,0 +1,27 @@
+"""Utility functions for CHNOSZ calculations."""
+
+from .reset import reset
+from .formula import makeup, get_formula, as_chemical_formula, mass, entropy, species_basis, calculate_ghs, ZC, i2A, FormulaError
+
+# Optional imports for modules that may not exist yet
+try:
+    from .units import convert_units
+except ImportError:
+    convert_units = None
+
+try:
+    from .data import load_data
+except ImportError:
+    load_data = None
+
+__all__ = [
+    'reset',
+    'makeup', 'get_formula', 'as_chemical_formula', 'mass', 'entropy',
+    'species_basis', 'calculate_ghs', 'ZC', 'i2A', 'FormulaError'
+]
+
+# Add optional functions if they exist
+if convert_units is not None:
+    __all__.append('convert_units')
+if load_data is not None:
+    __all__.append('load_data')