cosmopharm 0.0.0__py3-none-any.whl

cosmopharm/__init__.py

@@ -0,0 +1,2 @@
+from .equilibrium import SLE, LLE
+from .actmodels import COSMOSAC

cosmopharm/actmodels/__init__.py

@@ -0,0 +1,2 @@
+from .actmodel import ActModel
+from .cosmo import COSMOSAC

cosmopharm/actmodels/actmodel.py

@@ -0,0 +1,118 @@
+import numpy as np
+import numbers
+from numpy.typing import NDArray
+from typing import List, Literal
+
+from ..components import Component
+from ..utils.convert import convert
+
+class ActModel:
+
+    def __init__(self, components: List[Component]):
+        self.mixture = components
+
+    def lngamma(self, T, x):
+        raise NotImplementedError("lngamma() hasn't been implemented yet.")
+
+    def activity(self, T, x):
+        act = np.log(x) + self.lngamma(T, x)
+        act[(act == np.inf) | (act == -np.inf)] = np.nan
+        return act
+
+    def gmix(self, T, x):
+        is_scalar = np.isscalar(x)
+        # Convert input as needed
+        x = self._convert_input(x)
+        # Create mask to identify columns that don't contain 0 or 1
+        mask = np.any((x != 0) & (x != 1), axis=0)
+        # Apply the mask to filter x
+        _x = x[:, mask]
+        # Calculate gmix for the  x values
+        _gmix = _x * (np.log(_x) + self.lngamma(T, _x))
+        _gmix = np.sum(_gmix, axis=0)
+        # Initialize gmix array with zeros
+        gmix = np.zeros(1 if x.ndim==1 else x.shape[1])
+        # Fill gmix with calculated values where the mask is True
+        gmix[mask] = _gmix
+        return gmix[0] if is_scalar else gmix
+    
+    def thermofac(self, T, x):
+        """ Approximate thermodynamic factor
+        Simple derivative form, when no analytical equation is available. 
+        """
+        def f(x1):
+            x = np.array([x1, 1-x1])
+            return self.lngamma(T, x)[0]
+        h, x = 0.0001, x[0]
+        dy = (f(x+h)-f(x-h))/(2*h)
+        return 1 + x * dy
+
+
+# =============================================================================
+# Wrapper functions (Decorators)
+# =============================================================================
+    @staticmethod
+    def vectorize(func):
+        ''' Intended vor ActModels where only single mole fractions can be
+        handled, like e.g. COSMO-SAC. This function vectorizes the lngamma()
+        to make it work with arrays of mole fractions.
+        '''
+        def wrapper(self, T, x):
+            # Convert input to appropriate format
+            x = self._convert_input(x)
+            # Process based on the dimensionality of x
+            if x.ndim == 1:
+                return func(self, T, x)
+            elif x.ndim == 2:
+                results = [func(self, T, x[:, col]) for col in range(x.shape[1])]
+                return np.array(results).T
+            else:
+                raise ValueError("Input must be either a scalar, 0D, 1D or 2D array")
+        return wrapper
+
+
+# =============================================================================
+# Auxilliary functions
+# =============================================================================
+    def _convert_input(self, x):
+        """Converts input to a 1-dim ndarray if it's a number or 0-dim ndarray."""
+        if isinstance(x, numbers.Number) or (isinstance(x, np.ndarray) and x.ndim == 0):
+            return np.array([float(x), 1 - float(x)])
+        elif isinstance(x, np.ndarray) and x.ndim == 1 and len(x) != len(self.mixture):
+            return np.array([x, 1 - x])
+        return x
+
+    def _convert(self, 
+                 x : NDArray[np.float64], 
+                 to : Literal['weight', 'mole'] ='weight'
+                 ) -> NDArray[np.float64]:
+        """
+        Convert the fraction of a binary mixture between mole fraction and weight fraction.
+
+        This method is designed for internal use with binary mixtures, where the mixture is defined by two components. 
+        It uses the 'convert' function to perform the conversion by creating an array with the fractions of both 
+        components and the molecular weights from the mixture's attributes.
+
+        Parameters:
+            x (NDArray[np.float64]): The mole or weight fraction of the first component of the mixture. 
+                                    If converting 'to' weight, 'x' represents mole fractions; if converting 'to' mole, 
+                                    'x' represents weight fractions. This should be a single value or a 1D array of values.
+            to (Literal['weight', 'mole'], optional): The target type for the conversion. Defaults to 'weight'.
+                                                    Use 'weight' to convert mole fractions to weight fractions,
+                                                    and 'mole' to convert weight fractions to mole fractions.
+
+        Returns:
+            NDArray[np.float64]: The converted fraction(s) of the first component in the same shape as 'x'.
+                                If 'x' is a single value, the return will be a single converted value;
+                                if 'x' is a 1D array, the return will be a 1D array of converted values.
+
+        Example:
+            >>> mixture = Mixture(components=[component1, component2], Mw=np.array([18.01528, 46.06844]))
+            >>> sle = SLE(mix=mixture)
+            >>> x_mole_fraction = np.array([0.4])  # Mole fraction of the first component
+            >>> x_weight_fraction = sle._convert(x_mole_fraction, to='weight')
+            >>> print(x_weight_fraction)
+            array([0.01373165])
+        """
+        Mw = np.array([c.Mw for c in self.mixture])
+        return convert(x=np.array([x, 1-x], dtype=np.float64), Mw=Mw, to=to)[0]

cosmopharm/actmodels/cosmo.py

@@ -0,0 +1,152 @@
+import numpy as np
+import cCOSMO
+
+from typing import List, Union, Literal
+from .actmodel import ActModel
+from ..components import Component
+
+class COSMOSAC(ActModel):
+
+    # Handle invalid values for free volume calculation
+    class InvalidFreeVolumeParametersException(Exception):
+        pass
+
+    def __init__(self,
+                 COSMO: Union[cCOSMO.COSMO1, cCOSMO.COSMO3],
+                 mixture: List[Component],
+                 combinatorial: Union[Literal['sg', 'fv'], bool] = 'sg',
+                 dispersion: bool = False,
+                 ) -> None:
+        self.COSMO = COSMO
+        self.mixture = mixture
+        # Flexible assignment of 'get_lngamma_comb' and 'get_lngamma_dsp'
+        # that changes dynamically if the values for 'combinatorial' or
+        # 'dispersion' are changed after initialization of an instance.
+        self._combinatorial = combinatorial
+        self._dispersion = dispersion
+
+    @ActModel.vectorize
+    def lngamma(self, T, x):
+        resid = self.get_lngamma_resid(T, x)
+        comb  = self.get_lngamma_comb(x)
+        disp  = self.get_lngamma_disp(x)
+        lngamma = resid + comb + disp
+        return lngamma
+
+    def get_lngamma_fv(self, x):
+        """
+        Calculates the free-volume term of the activity coefficient for a mixture.
+
+        This implementation uses a formula to avoid numerical instability when
+        `x_i` approaches zero, which is important in asymmetric API-polymer
+        mixtures. The formula used is:
+
+        ```
+        phi_i^FV / x_i = v_i^F / sum_j(x_j * v_j^F)
+        ```
+
+        where
+        - `phi_i^FV` is the free-volume fraction of component `i`,
+        - `x_i` is the mole fraction of component `i`,
+        - `v_i^F` is the free volume of component `i`,
+        and the summation is over all components `j` in the mixture.
+
+        Parameters
+        ----------
+        x : array_like
+            Mole fractions of the components in the mixture.
+
+        Returns
+        -------
+        np.ndarray
+            Logarithm of the free-volume term of the activity coefficient.
+
+        Note:
+        Free-volume term of the activity coefficient according to Elbro et al.
+        (can replace ln_gamma_comb of normal COSMO-SAC) - Kuo2013
+        x, v_298, v_hc are 1D arrays (number of elements = number of components)
+        """
+        self.validate_free_volume_parameters()  # Ensure components are valid before proceeding
+        v_298 = np.array([comp.v_298 for comp in self.mixture])
+        v_hc = np.array([comp.v_hc for comp in self.mixture])
+        vf = v_298-v_hc
+        sum_vf = np.sum(x*vf)
+        phix = vf/sum_vf
+        return np.log(phix) + 1 - phix
+
+    def get_lngamma_sg(self, x):
+        return self.COSMO.get_lngamma_comb(0, x)
+
+    def get_lngamma_resid(self, T, x):
+        return self.COSMO.get_lngamma_resid(T, x)
+
+    def get_lngamma_comb(self, x):
+        if self._combinatorial is False:
+            return np.zeros(len(x))
+        elif self._combinatorial.lower() == 'sg':
+            return self.get_lngamma_sg(x)
+        elif self._combinatorial.lower() == 'fv':
+            return self.get_lngamma_fv(x)
+
+    def get_lngamma_disp(self, x):
+        if self._dispersion:
+            return self.COSMO.get_lngamma_disp(x)
+        else:
+            return np.zeros(len(x))
+
+    @property
+    def dispersion(self):
+        return self._dispersion
+
+    @dispersion.setter
+    def dispersion(self, value):
+        self._dispersion = value
+
+    @property
+    def combinatorial(self):
+        return self._combinatorial
+
+    @combinatorial.setter
+    def combinatorial(self, value: Union[str, bool]):
+        is_valid_string = isinstance(value, str) and value.lower() in ('sg', 'fv')
+        is_False = value is False
+        if is_valid_string or is_False:
+            self._combinatorial = value
+        else:
+            msg = "Invalid value for combinatorial term. Please choose 'sg', 'fv', or set to False."
+            raise ValueError(msg)
+
+# =============================================================================
+# Auxilliary functions
+# =============================================================================
+    def configuration(self,
+                      comb: Union[Literal['sg', 'fv'], bool] = 'sg',
+                      dsp: bool = False, **kwargs
+                      ):
+        """ Convenience function to quickly configure COSMO parameters """
+        self._combinatorial = comb
+        self._dispersion = dsp
+
+
+    def validate_free_volume_parameters(self):
+        # List of parameters to validate
+        parameters_to_check = ["v_298", "v_hc"]
+
+        for comp in self.mixture:
+            invalid_params = []  # List to accumulate names of invalid parameters for this component
+            for param in parameters_to_check:
+                value = getattr(comp, param, None)
+                # Check if value is None, not a number (np.nan), less than or equal to 0
+                if value is None or np.isnan(value) or value <= 0:
+                    invalid_params.append((param, value))  # Append parameter name and value tuple
+
+            # Check if any errors were found for this component
+            if invalid_params:
+                # If errors were found, construct the warning message
+                error_message = f"Invalid FV parameters for component {comp}: {invalid_params}"
+                raise self.InvalidFreeVolumeParametersException(error_message)
+
+            # Additionally check if v_298 and v_hc are equal
+            if comp.v_298 == comp.v_hc:
+                msg = f"v_298 and v_hc are equal for component {comp}: v_298={comp.v_298}, v_hc={comp.v_hc}"
+                raise self.InvalidFreeVolumeParametersException(msg)

cosmopharm/components.py

@@ -0,0 +1,31 @@
+from typing import Optional
+from numbers import Number
+
+class Component:
+    def __init__(self,
+                 name: Optional[str] = None,
+                 Mw: Optional[Number] = None,  # Positive number expected
+                 T_fus: Optional[Number] = None,  # Positive number expected
+                 H_fus: Number = 0,
+                 Cp_fus_a_fit: Number = 0,
+                 Cp_fus_bT_fit: Number = 0,
+                 v_298: Optional[Number] = None,
+                 v_hc: Optional[Number] = None,
+                 ):
+
+        self.name = name
+        self.Mw = Mw  # molar weight in g/mol
+
+        # for SLE calculations
+        self.T_fus = T_fus
+        self.H_fus = H_fus
+        self.Cp_fus_a_fit = Cp_fus_a_fit
+        self.Cp_fus_bT_fit = Cp_fus_bT_fit
+        self.v_298 = v_298
+        self.v_hc = v_hc
+
+    def __repr__(self):
+        return f"<Component('{self.name}')>"
+
+    def __str__(self):
+        return f"{self.name}"

cosmopharm/equilibrium/__init__.py

@@ -0,0 +1,2 @@
+from .sle import SLE
+from .lle import LLE

cosmopharm/equilibrium/lle.py

@@ -0,0 +1,178 @@
+import numpy as np
+import pandas as pd
+from scipy.optimize import least_squares, root
+from typing import Union, Optional, Type, List, Dict
+
+from ..components import Component
+from ..actmodels import ActModel
+from ..utils.spacing import spacing
+from ..utils.lle_scanner import estimate_lle_from_gmix
+
+
+class LLE:
+    def __init__(self,
+                 actmodel: Union[ActModel, Type[ActModel]],
+                 mixture: Optional[List[Component]] = None) -> None:
+        self.actmodel = actmodel
+        self.mixture = mixture
+        self._validate_arguments()
+
+    def miscibility(self,
+                    T: float,
+                    x0: np.ndarray = None,
+                    x0_type: str = 'mole',
+                    max_gap: float = 0.1,
+                    max_gap_type: str = 'mole',
+                    max_T: float = 1000,
+                    dT: float = 10,
+                    exponent: float = 1
+                    ) -> pd.DataFrame:
+        """ Calculate miscibility """
+        self.config = getattr(self.actmodel, 'config', '')
+        Mw = np.array([c.Mw for c in self.mixture])
+        self.is_valid_Mw = self.is_valid_numpy_array(Mw)
+        res = {'binodal':[], 'spinodal':[]}
+        var = 'x' if max_gap_type == 'mole' else 'w'
+        print()
+        print("Calculating LLE...")
+
+        # Define column names
+        binodal_columns = ['T', 'xL1', 'xL2']
+        if self.is_valid_Mw:
+            binodal_columns += ['wL1', 'wL2']
+
+        # Check for valid molar masses
+        if x0_type == 'weight':
+            if self.is_valid_Mw:
+                x0 = self.convert_to_mole_fractions(x0, self.mixture.Mw)
+            else:
+                raise ValueError("Molar masses are not available for conversion from weight to mole fraction.")
+# =============================================================================
+# TODO: Implement all edge cases (no LLE, bad approximation, ....)
+# TODO: Improve code structure
+        # Approximate initial value for LLE
+        if x0 is None:
+            print("...searching for suitable initial value...")
+            x0 = self.approx_init_x0(T)
+
+            if any(x is None for x in x0):
+                print("...no initial value at T0 was found. Try another T0.")
+                return pd.DataFrame(columns=binodal_columns)
+
+            # Check if initial guess is reasonable - otherwise increase T
+            # TODO: Check whether it might be an LCST if isLower
+            binodal = self.solve_lle(T, x0, show_output=False)
+            isEqual = np.diff(binodal['x'])[0] < 1e-8 # check if both phases have equal composition
+            if isEqual:
+                print("...no initial value at T0 was found. Try another T0.")
+                return pd.DataFrame(columns=binodal_columns)
+            isLower = min(binodal['x']) < min(x0) # lower bound below min(x0)
+            while isLower and T <= max_T:
+                print('LLE: ', f"{T=:.2f}", "...no feasbible initial value found.")
+                T += 10  # Increase T by 10
+                x0 = self.approx_init_x0(T)
+                binodal = self.solve_lle(T, x0, show_output=False)
+            print("Suitable initial value found! Proceed with calculating LLE...")
+# =============================================================================
+        # First iteration step
+        binodal = self.solve_lle(T, x0)
+        gap = np.diff(binodal[var])[0]
+        res['binodal'].append((T, *[val for vals in binodal.values() for val in vals]))
+
+        # Subsequent iteration steps
+        while gap > max_gap and T <= max_T:
+            T += dT * gap**exponent
+            x0 = binodal['x']
+            binodal = self.solve_lle(T, x0)
+            gap = np.diff(binodal[var])[0]
+            res['binodal'].append((T, *[val for vals in binodal.values() for val in vals]))
+
+        # Convert lists to DataFrames
+        res = pd.DataFrame(res['binodal'], columns=binodal_columns)
+        return res
+
+# =============================================================================
+# MATHEMATICS
+# =============================================================================
+
+    def solve_lle(self, T: float, x0: np.ndarray, show_output=True) -> Dict[str, np.ndarray]:
+        """ Solve for liquid-liquid equilibrium (LLE) at a given temperature and initial composition. """
+        binodal = {'x': self.binodal(T, x0)}
+        output = [f"{k}={v:.4f}" for k,v in zip(['xL1', 'xL2'], binodal['x'])]
+
+        if self.is_valid_Mw:
+            binodal['w'] = self.actmodel._convert(binodal['x'])
+            output += [f"{k}={v:.4f}" for k,v in zip(['wL1', 'wL2'], binodal['w'])]
+
+        if show_output:
+            prefix = f'LLE ({self.config})' if self.config else 'LLE'
+            print(f'{prefix}: ', f"{T=:.2f}", *output)
+        return binodal
+
+
+
+
+# =============================================================================
+# THERMODYNAMICS
+# =============================================================================
+    def fobj_binodal(self, x1, T):
+        # Equilibrium: Isoactivity criterion (aL1 - aL2 = 0)
+        x = np.array([x1, 1-x1])
+        activity = self.actmodel.activity(T, x)
+        equilibrium = np.diff(activity, axis=1)
+        return equilibrium.ravel() # reshape from (2,1) --> (2,)
+
+    def fobj_spinodal(self, x1):
+        T = 0
+        x = np.array([x1, 1-x1])
+        return self.actmodel.thermofac(T, x)
+
+    def binodal(self, T, x0=None):
+        if x0 is None:
+            x0 = [0.1, 0.999]
+        kwargs = dict(bounds=(0,1), ftol=1e-15, xtol=1e-15)
+        res = least_squares(self.fobj_binodal, x0, args=(T,), **kwargs)
+        return res.x
+
+    def spinodal(self, T, x0=None):
+        if x0 is None:
+            x0 = self.binodal(T, x0)
+        kwargs = dict(bounds=(0,1), ftol=1e-15, xtol=1e-15)
+        res = least_squares(self.fobj_spinodal, x0, args=(T,), **kwargs)
+        return res.x
+
+
+# =============================================================================
+# AUXILLIARY FUNCTIONS
+# =============================================================================
+    def approx_init_x0(self, T):
+        x1 = spacing(0,1,51,'poly',n=3)
+        gmix = self.actmodel.gmix(T, x1)
+        xL, xR, yL, yR = estimate_lle_from_gmix(x1, gmix, rough=True)
+        return xL, xR
+
+    def _validate_arguments(self):
+        """Validate the arguments for the LLE class."""
+        # TODO: Insert case where both actmodel and mixture are provided
+        # (check if acmodel.mixture == mixture, if not raise warning)
+        if isinstance(self.actmodel, ActModel):
+            # If actmodel is an instance of ActModel
+            self.mixture: List[Component] = self.mixture or self.actmodel.mixture
+        elif isinstance(self.actmodel, type) and issubclass(self.actmodel, ActModel):
+            # If actmodel is a class (subclass of ActModel)
+            if self.mixture is None:
+                raise ValueError("Please provide a valid mixture:Mixture.")
+            self.actmodel: ActModel = self.actmodel(self.mixture)
+        else:
+            # If actmodel is neither an instance nor a subclass of ActModel
+            err = "'actmodel' must be an instance or a subclass of 'ActModel'"
+            raise ValueError(err)
+
+    def is_valid_numpy_array(self, arr: np.ndarray) -> bool:
+        """Check if a numpy array contains only numbers and no None values."""
+        if not isinstance(arr, np.ndarray):
+            return False
+        if arr.dtype == object:  # Check if the array contains objects (which could include None)
+            return not np.any(arr == None)
+        else:
+            return np.issubdtype(arr.dtype, np.number)