cosmopharm 0.0.0__py3-none-any.whl

cosmopharm/equilibrium/sle.py

@@ -0,0 +1,244 @@
+import numpy as np
+import pandas as pd
+from scipy.optimize import fsolve, root
+from numpy.typing import NDArray
+from typing import Literal, Optional, Type, Union, List, Tuple, Generator, Dict
+
+from ..components import Component
+from ..actmodels import ActModel
+from ..utils.spacing import spacing
+
+NumericOrFrame = Union[float, List[float], Tuple[float, ...], NDArray[np.float64], pd.DataFrame]
+
+class SLE:
+    def __init__(self,
+                 actmodel: Union[ActModel, Type[ActModel]],
+                 mixture: Optional[List[Component]] = None) -> None:
+        self.actmodel = actmodel
+        self.mixture = mixture
+        self._validate_arguments()
+        # Assign 'solute' and 'solvent' based on order in 'mixture'
+        # Default assignment can be changed in e.g. 'solubility()'
+        self.solute, self.solvent = self.mixture
+
+    def solubility(self,
+                   solute: Optional[Component] = None,
+                   solvent: Optional[Component] = None,
+                   vary: Literal['T', 'w', 'auto'] = 'auto',
+                   mix_type: Literal['ideal', 'real'] = 'real',
+                   args: Optional[NumericOrFrame] = None,
+                   init: Optional[NumericOrFrame] = None,
+                   solver: Literal['root', 'fsolve'] = 'root',
+                   show_progress=False, **kwargs):
+        ''' Calculate solubility curve of solute in solvent.'''
+        self.solute = solute or self.solute
+        self.solvent = solvent or self.solvent
+        self.vary, self.mix_type = vary, mix_type
+        self.show_progress = show_progress
+        self.config = getattr(self.actmodel, 'config', self.mix_type)
+        if self.vary == 'auto':
+            gen = self.auto_solve(solver)
+        else:
+            self._vary = self.vary
+            args = self.set_args(args)
+            init = self.set_x0(init)
+            gen = self.solve_sle(args, init, solver)
+        try:
+            res = [k for k in gen]
+            res = pd.DataFrame(res, columns=['T', 'x', 'vary', 'w'])
+            res = res[['T', 'w', 'x', 'vary']]
+            return res
+        except self.actmodel.InvalidFreeVolumeParametersException as e:
+            print(f"Warning: {e}")  # Inform the user
+            return pd.DataFrame(columns=['T', 'w', 'x', 'vary'])
+
+
+# =============================================================================
+# MATHEMATICS
+# =============================================================================
+    def solve_sle(self, args: NDArray[np.float64], init: NDArray[np.float64],
+                  solver: Literal['root', 'fsolve'] = 'root'
+                  ) -> Generator[Dict[str, Union[float, str]], None, None]:
+        # Check compatibility of the "init" values
+        is_iterable = init.size > 1
+        if is_iterable and not init.size == args.size:
+            msg = 'The length of "init" must be the same as "args".'
+            raise ValueError(msg)
+        x0 = init
+        # Setup solver and handle pure component case
+        key, lock = ['T', 'x'] if self._vary == 'T' else ['x', 'T']
+        solve = self.set_solver(solver=solver)
+        args, pure_component = self._handle_pure_component(args)
+        if pure_component: # no need to calculate pure component
+            yield pure_component
+        for i, arg in enumerate(args):
+            x0 = init[i] if is_iterable else x0
+            out = float(solve(x0, arg))
+            x0 = out if not is_iterable else x0
+            res = {key: arg, lock: out, 'vary': self._vary}
+            res['w'] = self.actmodel._convert(res['x'])[0]
+            text = (f"T={res['T']:.2f}", f"x={res['x']:.4f}", f"w={res['w']:.4f}")
+            if self.show_progress:
+                print(f'SLE ({self.config}): ', *text)
+            yield res
+
+    def auto_solve(self, solver: Literal['root', 'fsolve'] = 'root'):
+        if self.show_progress:
+            print()
+            print(f"Calculating SLE ({self.config})...")
+        # Start with varying 'w' until dTdw > THRESHOLD
+        self._vary = 'w'
+        args = self.set_args()
+        x0 = self.set_x0()
+        gen = self.solve_sle(args, x0, solver)
+        previous = None
+        for i, current in enumerate(gen):
+            yield current
+            if self._should_stop_generator(i, previous, current):
+                break  # This will end the generator
+            previous = current
+        # Switch to varying 'T'
+        self._vary = 'T'
+        T0, x0 = current['T'], current['x']
+        args = self.set_args(xmax=T0)[1:]  # exclude initial point
+        gen = self.solve_sle(args, x0)
+        yield from gen
+
+
+# =============================================================================
+# THERMODYNAMICS
+# =============================================================================
+    def ideal_mix(self, T):
+        return np.exp(-self.gibbs_fusion(T))
+
+    def real_mix(self, T, x):
+        lngamma = self.actmodel.lngamma(T, x)[0]
+        return np.log(x) + lngamma + self.gibbs_fusion(T)
+
+    # Gibbs energy of fusion, i.e., the right-hand side of the solubility equation:
+    def gibbs_fusion(self, T):
+        T_fus = self.solute.T_fus
+        H_fus = self.solute.H_fus
+        Cp_fus_A = self.solute.Cp_fus_A
+        Cp_fus_BT = self.solute.Cp_fus_BT
+
+        R  = 8.314                 # J/(mol K)
+        RT = R*T                   # J/mol
+        A, B = Cp_fus_A, Cp_fus_BT
+        G1 = H_fus*(1-T/T_fus)     # J/mol
+        G2 = A * (T-T_fus) + 0.5*B*(T**2-T_fus**2)
+        G3 = -T * (A * np.log(T/T_fus) + B*(T-T_fus))
+        G_fus = G1 + G2 + G3       # J/mol
+        return G_fus/RT
+
+
+# =============================================================================
+# HELPER FUNCTIONS
+# =============================================================================
+    def set_args(self,
+                 args: Optional[NumericOrFrame] = None,
+                 xmin: Optional[float] = None,
+                 xmax: Optional[float] = None,
+                 dx: Optional[float] = None
+                 ) -> NDArray[np.float64]:
+        vary = self._vary
+        # Determine argument values based on input data or generate
+        # them based on range and type
+        defaults = {
+            'T': {'min': 310, 'max': self.solute.T_fus, 'step': 10},
+            'w': {'min': 0.01, 'max': 1, 'step': 0.08}
+        }
+        mi = defaults[vary]['min'] if xmin is None else xmin
+        ma = defaults[vary]['max'] if xmax is None else xmax
+        dx = defaults[vary]['step'] if dx is None else dx
+
+        if args is None:
+            if self.vary != 'auto':  # auto_vary == False
+                args = np.arange(ma, mi-dx, -dx)
+                args[-1] = np.maximum(args[-1], mi)
+            elif vary == 'T':  # auto_vary == True
+                num, dT = 16, 175  # How many data points in this T-range
+                num = int((ma-mi)/dT*num)  # fraction of points if dT smaller
+                num = max(6, num)
+                kwargs = dict(reverse=True, n=1.5)
+                args = spacing(ma, mi, num, 'poly', **kwargs)
+            else:  # vary == 'w'
+                num = 16 if self.mix_type == 'ideal' else 21
+                args = spacing(ma, mi, num, 'quadratic')
+        args = np.asarray(args)
+        args = args if vary != 'w' else self.actmodel._convert(args, to='mole')
+        return args
+
+    def set_x0(self, init: Optional[NumericOrFrame] = None) -> NDArray[np.float64]:
+        vary = self._vary
+        # Set up initial values based on the type of variable ('T' or 'w')
+        if vary == 'T':
+            x0 = 1. if init is None else self.actmodel._convert(init, to='mole')
+        else:  # vary == 'w'
+            x0 = self.solute.T_fus if init is None else init
+        x0 = np.asarray(x0)
+        return x0
+
+    def set_solver(self, solver: Literal['root', 'fsolve'] = 'root'):
+        vary, mix = self._vary, self.mix_type
+        # Define the objective function (fobj) and the solver function (solve)
+        # based on the mixture type (mix) and the variable type (vary)
+        if mix == 'ideal' and vary == 'T':
+            def fobj(x, T): return self.ideal_mix(T)
+            def solve(x0, args): return fobj(x0, args)
+        else:
+            if mix == 'ideal':
+                def fobj(T, x): return x - self.ideal_mix(T)
+            elif vary == 'T':  # mix != 'ideal'
+                def fobj(x, T): return self.real_mix(T, x)
+            else:  # vary == 'w'
+                def fobj(T, x): return self.real_mix(T, x)
+            kwargs = dict(method='krylov', options={'maxiter': 5, 'xtol': 1e-3})
+            if solver == 'fsolve':
+                def solve(x0, args): return fsolve(fobj, x0, args)
+            else:
+                def solve(x0, args): return root(fobj, x0, args, **kwargs).x
+        # Problem: "fsolve" and "root" return different types of np.arrays
+        # (1) fsolve returns (1,) 1D array
+        # (2) root returns () 0D array
+        # Therefore, it is necessary to use float(solve(...)) to extract the
+        # single value from the array, since solve()[0] does not work for root.
+        return solve
+
+
+# =============================================================================
+# AUXILLIARY FUNCTIONS
+# =============================================================================
+    def _should_stop_generator(self, i, previous, current):
+        THRESHOLD = 60
+        if i > 1:  # ensuring there was a previous result
+            dT = current['T'] - previous['T']
+            dw = current['w'] - previous['w']
+            return (dT / dw) > THRESHOLD
+        return False  # If not enough elements, continue the generator
+
+    def _handle_pure_component(self, args):
+        res = {'T': self.solute.T_fus, 'x': 1, 'vary': self._vary, 'w': 1}
+        if self._vary == 'T' and self.solute.T_fus in args:
+            args = args[args != self.solute.T_fus]
+            return args, res
+        elif self._vary == 'w' and 1 in args:
+            args = args[args != 1]
+            return args, res
+        return args, None
+
+    def _validate_arguments(self):
+        """Validate the arguments for the SLE 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)

cosmopharm/utils/__init__.py

@@ -0,0 +1,3 @@
+from .helpers import read_params, create_components
+from .convert import convert
+from .spacing import spacing

cosmopharm/utils/convert.py

@@ -0,0 +1,58 @@
+import numpy as np
+
+
+def convert(x: np.ndarray, Mw: np.ndarray, to: str = 'weight') -> np.ndarray:
+    """
+    Convert between mole fraction (x) and mass/weight fraction (w) for a mixture.
+
+    Parameters:
+        x (numpy.ndarray): A 1D or 2D NumPy array representing mole fractions of components in the mixture.
+                           - If 1D, it should have the shape (n,) with 'n' as the number of components.
+                           - If 2D, it should have the shape (n, m) where 'n' is the number of components
+                             and 'm' is the number of data points.
+        to (str, optional): The conversion direction. Should be either 'weight' (default) to convert from mole
+                           fraction to weight fraction, or 'mole' to convert from weight fraction to mole fraction.
+
+    Returns:
+        numpy.ndarray: The converted fractions, with the same shape as 'x'.
+
+    Example:
+        >>> sle = SLE(mix=mix)  # Replace with the actual mixture object
+        >>> x = np.array([0.4, 0.6])  # Mole fractions of two components
+        >>> w = mix.convert(x, to='weight')  # Convert to weight fractions
+        >>> print(w)
+        array([[0.01373165],
+               [0.98626835]])
+    """
+
+    # Check if x is a NumPy array
+    if not isinstance(x, np.ndarray):
+        raise ValueError("Input 'x' must be a 1D or 2D NumPy array.")
+
+    # Check if x is a scalar (0-dimensional)
+    if x.shape == ():
+        raise ValueError(
+            "Input 'x' must be a 1D or 2D NumPy array, not a scalar.")
+
+    if to not in ['weight', 'mole']:
+        raise ValueError("Invalid 'to' argument. Use 'weight' or 'mole'.")
+
+    # Check and reshape Mw if needed
+    Mw = Mw[:, np.newaxis] if Mw.ndim == 1 else Mw  # Reshape to (n, 1)
+    # Check and reshape x if needed
+    x = x[:, np.newaxis] if x.ndim == 1 else x  # Reshape to (n, 1)
+
+    # Check if Mw and x have the same number of components
+    if Mw.shape[0] != x.shape[0]:
+        raise ValueError(
+            "Number of components in 'Mw' and 'x' must match.")
+
+    # Calculate the numerator for conversion based on 'to' argument
+    num = x * Mw if to == 'weight' else x / Mw
+    # Calculate the denominator for conversion
+    den = np.sum(num, axis=0)
+    # Calculate the final conversion using the numerator and denominator
+    res = num / den
+    # Replace nan values with 0
+    res = np.nan_to_num(res)
+    return res

cosmopharm/utils/helpers.py

@@ -0,0 +1,36 @@
+import pandas as pd
+import numpy as np
+from ..components import Component
+
+def read_params(params_filepath):
+    params = pd.read_excel(params_filepath)
+    cols = [col.split('/')[0] for col in params.columns]
+    params.rename(columns=dict(zip(params.columns, cols)), inplace=True)
+    return params
+
+def get_params_for_component(component, parameters):
+    """Retrieve the parameters for the given component from the dataframe."""
+    params = parameters[parameters['Component'] == component.name]
+    if params.empty:
+        raise ValueError(f"No data found for component {component.name}")
+    return params.iloc[0]
+
+def add_parameters(c, params):
+    """Add properties of a component based on provided parameters."""
+    KILOJOULE_TO_JOULE = 1e3
+    c.Mw = params['Mw']  # g/mol
+    c.T_fus = params['T_fus'] if params['T_fus'] > 0 else np.nan  # K
+    c.H_fus = params['H_fus'] * KILOJOULE_TO_JOULE  # J/mol
+    c.Cp_fus_A = np.nan_to_num(params['Cp_fus_a_fit'])  # J/(mol K)
+    c.Cp_fus_BT = np.nan_to_num(params['Cp_fus_bT_fit'])  # J/(mol K²)
+    c.v_298 = params['v298']  # cm³/mol
+    c.v_hc = params['v_hc']  # cm³/mol
+
+def create_components(names, parameters):
+    components = []
+    for name in names:
+        component = Component(name)
+        params = get_params_for_component(component, parameters)
+        add_parameters(component, params)
+        components.append(component)
+    return components

cosmopharm/utils/lle_scanner.py

@@ -0,0 +1,188 @@
+import numpy as np
+from scipy.optimize import fsolve, root
+from scipy.signal import argrelextrema
+
+def find_inflection_points(x, y):
+    """
+    Determines the inflection points of the function based on second derivative.
+
+    Parameters:
+    - x, y: data points
+
+    Returns:
+    - x and y values of turning points and their indices.
+    """
+    dy = np.diff(y) / np.diff(x)
+    dx = (x[:-1] + x[1:]) / 2
+    d2y = np.diff(dy) / np.diff(dx)
+    sign_changes = np.diff(np.sign(d2y))
+    i = np.where(sign_changes)[0] + 2
+    return i, x[i], y[i]
+
+def find_common_tangent(f, g, xL_init, xR_init):
+    """
+    Determines the common tangent for two functions.
+
+    Parameters:
+    - f, g: Polynomial functions
+    - xL_init, xR_init: Initial guesses for intersection points
+
+    Returns:
+    - Intersection points and y-values.
+    """
+    def fobj(x):
+        xL, xR = x
+        df = f.deriv()(xL)
+        dg = g.deriv()(xR)
+        dy = (g(xR) - f(xL)) / (xR - xL)
+        return [df - dg, dy - df]
+    xL, xR = fsolve(fobj, x0=[xL_init, xR_init])
+    # [xL, xR], info, *_ = fsolve(fobj, x0=[xL_init, xR_init], full_output=True)
+    # print(info['nfev'])
+    # kwargs = dict(method='krylov', options={
+    #               'maxiter': 20, 'xtol': 1e-3})
+    # res = root(fobj, x0=[xL_init, xR_init], **kwargs)
+    # [xL, xR] = res.x
+    # print(res.nit)
+    return xL, xR, f(xL), g(xR)
+
+def approximate_between_points(x, y, start, end, deg=5):
+    segment_x = x[start:end+1]
+    segment_y = y[start:end+1]
+    midpoint = (segment_x[0] + segment_x[-1]) / 2
+    params = np.polyfit(segment_x, segment_y, deg=deg)
+    func = np.poly1d(params)
+    return func, segment_x, midpoint
+
+def get_segment_border_indices(x, start, end, fraction=0.5, min_values=5):
+    # Calculate the intermediate point using the given fraction
+    intermediate_x = x[start] + fraction * (x[end] - x[start])
+    # Find the index in x that is closest to this intermediate point
+    # closest_index = start + np.argmin(np.abs(x[start:end+1] - intermediate_x))
+    closest_index = np.argmin(np.abs(x - intermediate_x))
+    # Ensure that there are at least min_values between start and closest_index
+    if abs(closest_index - start) < min_values:
+        closest_index = end
+    return sorted([start, closest_index])
+
+def find_binodal(x1, gmix, iL, iR, ax=None):
+    # Approximate segments between pure component and inflection points
+    borderL = get_segment_border_indices(x1, start=iL, end=0)
+    borderR = get_segment_border_indices(x1, start=iR, end=-1)
+    f, xL_range, mL = approximate_between_points(x1, gmix, *borderL, deg=5)
+    g, xR_range, mR = approximate_between_points(x1, gmix, *borderR, deg=5)
+    # Find common tangent
+    xL, xR, yL, yR = find_common_tangent(f, g, mL, mR)
+
+    # Check if results are outside the fitting range
+    adjustL = xL < xL_range[0] or xL > xL_range[-1]
+    adjustR = xR < xR_range[0] or xR > xR_range[-1]
+
+    # If outside, adjust the respective range and recalculate xL and xR
+    if adjustL or adjustR:
+        if adjustL:
+            borderL = get_segment_border_indices(
+                x1, start=iL, end=0, fraction=1)
+            f, xL_range, mL = approximate_between_points(
+                x1, gmix, *borderL, deg=5)
+        if adjustR:
+            borderR = get_segment_border_indices(
+                x1, start=iR, end=-1, fraction=1)
+            g, xR_range, mR = approximate_between_points(
+                x1, gmix, *borderR, deg=10)
+
+        # Find common tangent
+        xL, xR, yL, yR = find_common_tangent(f, g, mL, mR)
+
+    if ax is not None:
+        ax.plot(xL_range, f(xL_range), 'r', lw=1)
+        ax.plot(xR_range, g(xR_range), 'r', lw=1)
+
+    return xL, xR, yL, yR
+
+def find_local_extremum(y, typ='minimum'):
+    kind = np.less if "min" in typ else np.greater
+    return argrelextrema(y, kind)[0]
+
+def approx_binodal(x1, gmix, xS, iL, iR):
+    x, y = x1, gmix
+    local_minima = find_local_extremum(y, 'minimum')
+    min_x = x[local_minima]
+
+    # Initialize return values
+    xL = xR = yL = yR = None
+
+    if len(min_x) == 0:
+        pass
+    # Check the number of local minima found
+    if len(min_x) == 1:
+        # Precompute the boolean condition to avoid redundancy
+        is_greater_than_mid_x = min_x > max(xS)
+        # Select indices based on the precomputed condition
+        i = iL if is_greater_than_mid_x else iR
+        slice_ = slice(None, i+1) if is_greater_than_mid_x else slice(i, None)
+
+        # Slicing the arrays based on the selected indices
+        x1, y1 = x[slice_], y[slice_]
+
+        # Fit a line to the boundary points
+        m, n = np.polyfit(x1[[0, -1]], y1[[0, -1]], 1)
+        f = np.poly1d([m, n])
+
+        # Calculate the difference for finding the local minima
+        diff = y1 - f(x1)
+        local_minima = find_local_extremum(diff, 'minimum')
+
+        # Adjust local_minima index based on the original x array
+        if not is_greater_than_mid_x:
+            local_minima += i  # Adjust index for the slice offset
+
+        # Check if new local minima were found and sort
+        if local_minima.size > 0:
+            # Sort to ensure xL < xR
+            xL, xR = np.sort([min_x[0], x[local_minima][0]])
+            yL, yR = y[np.where((x == xL) | (x == xR))]
+
+    elif len(min_x) == 2:
+        xL, xR = min_x
+        yL, yR = y[local_minima]
+
+    else:
+        pass
+
+    return xL, xR, yL, yR
+
+
+def estimate_lle_from_gmix(x1, gmix, rough=True, ax=None):
+    # Initialize return values
+    xL = xR = yL = yR = None
+
+    # Find inflection points
+    try:
+        idx, xS, yS = find_inflection_points(x1, gmix)
+        iL, iR = idx[:2]
+    except ValueError:
+        # print("Warning: No inflection points found for current iteration.")
+        return xL, xR, yL, yR
+
+    # Find binodal
+    if rough:
+        xL, xR, yL, yR = approx_binodal(x1, gmix, xS, iL, iR)
+    else:
+        xL, xR, yL, yR = find_binodal(x1, gmix, iL, iR, ax=ax)
+
+    # Round xL and xR if they are not None
+    xL = round(xL, 8) if xL is not None else None
+    xR = round(xR, 8) if xR is not None else None
+
+    if ax is not None and None not in (xL, xR, yL, yR):
+        # Plot common tangent
+        m = (yR-yL)/(xR-xL)
+        n = yR - m*xR
+        t = np.poly1d([m, n])
+        ylim = ax.get_ylim()
+        ax.plot([xL, xR], [yL, yR], 'ko', mfc='w', zorder=3)
+        ax.plot(x1, t(x1), 'k:')
+        ax.set_ylim(ylim)
+
+    return xL, xR, yL, yR