cosmopharm 0.0.21__tar.gz → 0.0.23__tar.gz

{cosmopharm-0.0.21/src/cosmopharm.egg-info → cosmopharm-0.0.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cosmopharm
-Version: 0.0.21
+Version: 0.0.23
 Summary: Predictive modeling for drug-polymer compatibility in pharmaceutical formulations using COSMO-SAC.
 Home-page: https://github.com/ivanantolo/cosmopharm,
 Author: Ivan Antolovic
@@ -38,10 +38,15 @@ Requires-Dist: matplotlib>=3.0; extra == "examples"
 
 # COSMOPharm
 
+Welcome to the COSMOPharm package, accompanying [our paper in *J. Chem. Theory Comput.*](https://dx.doi.org/10.1021/acs.jctc.9b01016). This project and its associated publication offer insights and a practical toolkit for researching drug-polymer and drug-solvent systems, aiming to provide the scientific community with the means to reproduce our findings and further the development of COSMO-SAC-based models.
+
 <p align="center">
-  <img src="https://github.com/usnistgov/COSMOSAC/raw/master/JCTC2020.PNG" alt="TOC Figure" width="500">
+  <!-- <img src="https://github.com/usnistgov/COSMOSAC/raw/master/JCTC2020.PNG" alt="TOC Figure" width="500"> -->
+  <img src="https://github.com/usnistgov/COSMOSAC/raw/master/JCTC2020.PNG" alt="TOC Figure">
 </p>
 
+## About 
+
 COSMOPharm is a Python package designed for predictive modeling of drug-polymer compatibility and drug-solubility in common solvents. It leverages the COSMO-SAC (Conductor-like Screening Model Segment Activity Coefficient) model, offering a robust platform for solubility, miscibility, and phase behavior prediction in drug formulation processes.
 
 ## Features
@@ -51,19 +56,13 @@ COSMOPharm is a Python package designed for predictive modeling of drug-polymer
 - **Miscibility and Phase Behavior Analysis**: Understand drug-polymer miscibility and phase behavior under various conditions.
 - **User-friendly Interface**: Facilitate research with easy-to-use functions and comprehensive documentation.
 
-## Associated Research
-
-The development of COSMOPharm is closely tied to ongoing research aimed at enhancing the understanding and application of COSMO-SAC models in drug formulation. A forthcoming manuscript detailing the theoretical foundations and empirical validations of the models used in this package will provide comprehensive insights into the work COSMOPharm supports.
-
-**Note:** A related publication, provided as an example of the research context, can be found [here](https://dx.doi.org/10.1021/acs.jctc.9b01016). This link will be updated to directly point to our specific manuscript upon its publication, enabling users to delve deeper into the scientific basis and applications of COSMOPharm.
-
 ## Installation
 
 Install COSMOPharm with pip:
 
 `pip install cosmopharm`
 
-Ensure you have installed the cCOSMO library as per instructions on the [COSMOSAC GitHub page](https://github.com/usnistgov/COSMOSAC).
+Ensure you have installed the `cCOSMO` library as per instructions on the [COSMOSAC GitHub page](https://github.com/usnistgov/COSMOSAC).
 
 ## Quick Start
 

{cosmopharm-0.0.21 → cosmopharm-0.0.23}/README.md

@@ -23,7 +23,7 @@ COSMOPharm is a Python package designed to streamline the predictive modeling of
 ### Quick Installation
 For most users, the quickest and easiest way to install COSMOPharm is via pip, which will manage all dependencies for you. Ensure you have already installed the `cCOSMO` library by following the instructions on the [COSMOSAC GitHub page](https://github.com/usnistgov/COSMOSAC).
 
-Once cCOSMO is installed, you can install COSMOPharm directly from [PyPI](https://pypi.org/project/cosmopharm/):
+Once `cCOSMO` is installed, you can install COSMOPharm directly from [PyPI](https://pypi.org/project/cosmopharm/):
 
 ```
 pip install cosmopharm
@@ -65,7 +65,7 @@ python setup.py install
 
 While this method is straightforward, using `pip` is generally preferred for its dependency management capabilities.
 
-Please note: Before proceeding with either advanced installation option, ensure the cCOSMO library is installed as described at the beginning of this section.
+Please note: Before proceeding with either advanced installation option, ensure the `cCOSMO` library is installed as described at the beginning of this section.
 
 ## Quick Start
 

{cosmopharm-0.0.21 → cosmopharm-0.0.23}/setup.cfg

@@ -1,12 +1,11 @@
 [metadata]
 name = cosmopharm
-version = 0.0.21
+version = 0.0.23
 author = Ivan Antolovic
 author_email = Ivan.Antolovic@tu-berlin.de
 maintainer = Martin Klajmon
 maintainer_email = Martin.Klajmon@vscht.cz
-description = 
-	Predictive modeling for drug-polymer compatibility in pharmaceutical formulations using COSMO-SAC.
+description = Predictive modeling for drug-polymer compatibility in pharmaceutical formulations using COSMO-SAC.
 keywords = Drug-Polymer Compatibility, Amorphous Solid Dispersions, Pharmaceutical Formulation, COSMO-SAC Model, Solubility Prediction, Miscibility Analysis, Phase Behavior Prediction, Pharmaceutical Sciences, Drug Formulation Research, Polymer Science, Predictive Modeling in Pharma, Drug Development Tools, Biopharmaceuticals
 url = https://github.com/ivanantolo/cosmopharm,
 license = MIT

cosmopharm-0.0.23/src/cosmopharm/actmodels/actmodel.py

@@ -0,0 +1,107 @@
+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
+
+
+# =============================================================================
+# 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-0.0.21 → cosmopharm-0.0.23}/src/cosmopharm/actmodels/cosmo.py

@@ -1,17 +1,25 @@
+
 import numpy as np
+import cCOSMO
+
+from typing import List, Union, Literal
 from .actmodel import ActModel
+from ..components import Component
 
 class COSMOSAC(ActModel):
-    def __init__(self, COSMO, components: list, free_volume=False,
-                 dispersion=False, combinatorial=True):
+    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.mix = components
+        self.mixture = mixture
         # Flexible assignment of 'get_lngamma_comb' and 'get_lngamma_dsp'
-        # that changes dynamically if the values for 'free_volume', 'dispersion'
-        # or "combinatorial" are changed after initialization of an instance.
-        self._free_volume = free_volume
-        self._dispersion = dispersion
+        # 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):
@@ -54,8 +62,8 @@ class COSMOSAC(ActModel):
         (can replace ln_gamma_comb of normal COSMO-SAC) - Kuo2013
         x, v_298, v_hc are 1D arrays (number of elements = number of components)
         """
-        v_298 = np.array([c.v_298 for c in self.mix])
-        v_hc = np.array([c.v_hc for c in self.mix])
+        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
@@ -68,12 +76,12 @@ class COSMOSAC(ActModel):
         return self.COSMO.get_lngamma_resid(T, x)
 
     def get_lngamma_comb(self, x):
-        if not self._combinatorial:
+        if self._combinatorial is False:
             return np.zeros(len(x))
-        elif self._free_volume:
-            return self.get_lngamma_fv(x)
-        else:
+        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:
@@ -81,14 +89,6 @@ class COSMOSAC(ActModel):
         else:
             return np.zeros(len(x))
 
-    @property
-    def free_volume(self):
-        return self._free_volume
-
-    @free_volume.setter
-    def free_volume(self, value):
-        self._free_volume = value
-
     @property
     def dispersion(self):
         return self._dispersion
@@ -102,5 +102,22 @@ class COSMOSAC(ActModel):
         return self._combinatorial
 
     @combinatorial.setter
-    def combinatorial(self, value):
-        self._combinatorial = value
+    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

cosmopharm-0.0.23/src/cosmopharm/equilibrium/lle.py

@@ -0,0 +1,126 @@
+import numpy as np
+import pandas as pd
+from scipy.optimize import least_squares, root
+from typing import Union, Optional, Type, List
+
+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 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, solver='least_squares'):
+        if x0 is None:
+            x0 = [0.1, 0.999]    # 1_N2_Ethan
+
+        if solver == 'least_squares':
+            kwargs = dict(bounds=(0,1), ftol=1e-15, xtol=1e-15)
+            res = least_squares(self.fobj_binodal, x0, args=(T,), **kwargs)
+            # print(res.nfev)
+            return res.x, res.nfev
+        else:
+            kwargs = dict(method='krylov', options={'maxiter': 5})
+            res = root(self.fobj_binodal, x0, args=(T,), **kwargs)
+            # print(res.nit)
+            return res.x, 30
+
+    def spinodal(self, x0=None):
+        if x0 is None:
+            x0 = self.binodal()
+        return least_squares(self.fobj_spinodal, x0).x
+
+# =============================================================================
+# TODO: (1) Add some "approx_initial_values" function based on gmix
+# TODO: (2) Overall improve this code to match the SLE code
+# =============================================================================
+    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 solve_lle(self, T, x0, solver='least_squares', info=True):
+        binodal_x, nfev = self.binodal(T, x0, solver)
+        binodal_w = self.actmodel._convert(binodal_x)
+        formatted_w_binodal = [f"wL{i+1}={value:.4f}" for i, value in enumerate(binodal_w)]
+        formatted_x_binodal = [f"xL{i+1}={value:.6f}" for i, value in enumerate(binodal_x)]
+        msg = ('LLE: ', f"{T=:.2f}", *formatted_w_binodal, *formatted_x_binodal)
+        if info:
+            print(*msg)
+            return binodal_x, binodal_w, nfev
+        return binodal_x, binodal_w, nfev, msg
+
+    def miscibility(self, T, x0=None, max_gap=0.1, max_T=500, dT=25, exponent=2):
+        """ Calculate miscibility """
+        print()
+        print("Calculating LLE...")
+        res = []
+
+        if x0 is None:
+            print("...searching for suitable initial value...")
+            x0 = self.approx_init_x0(T)
+        binodal_x, binodal_w, nfev, msg = self.solve_lle(T, x0, info=False)
+
+        # Check if initial guess is reasonalble - otherwise increase T
+        while binodal_x[0] < x0[0] 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_x, binodal_w, nfev, msg = self.solve_lle(T, x0, info=False)
+        print("Suitable initial value found! Proceed with calculating LLE...")
+        print(*msg)
+        gap = np.diff(binodal_w)[0]
+        res.append((T, *binodal_w, *binodal_x))
+
+        while gap > max_gap and T <= max_T:
+            solver = 'least_squares' if nfev <= 30 else 'root'
+            solver = 'least_squares'
+            # print(solver)
+            T += dT * gap**exponent
+            x0 = binodal_x
+            binodal_x, binodal_w, nfev = self.solve_lle(T, x0, solver)
+            gap = np.diff(binodal_w)[0]
+            res.append((T, *binodal_w, *binodal_x))
+
+        columns = ['T', 'wL1', 'wL2', 'xL1', 'xL2']
+        res = pd.DataFrame(res, columns=columns)
+        return res
+
+# =============================================================================
+# AUXILLIARY FUNCTIONS
+# =============================================================================
+    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)

{cosmopharm-0.0.21 → cosmopharm-0.0.23}/src/cosmopharm/equilibrium/sle.py

@@ -1,35 +1,47 @@
-import pandas as pd
 import numpy as np
+import pandas as pd
 from scipy.optimize import fsolve, root
-from typing import Literal
+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, solute, solvent, actmodel):
-        self.mix = [solute, solvent]
-        self.model = actmodel
-        self.solute, self.solvent = solute, solvent
+    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: Component = None, solvent: Component = None,
-                   args=None, init=None, data=None,
+                   solute: Optional[Component] = None,
+                   solvent: Optional[Component] = None,
                    vary: Literal['T', 'w', 'auto'] = 'auto',
-                   mix: Literal['ideal', 'real'] = 'real',
+                   mix_type: Literal['ideal', 'real'] = 'real',
+                   args: Optional[NumericOrFrame] = None,
+                   init: Optional[NumericOrFrame] = None,
                    solver: Literal['root', 'fsolve'] = 'root',
-                   show_progress=False):
+                   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
+        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
-            if args is None or init is None:
-                args, init = self.initialize(init=init, data=data)
+            args = self.set_args(args)
+            init = self.set_x0(init)
             gen = self.solve_sle(args, init, solver)
         res = [k for k in gen]
         res = pd.DataFrame(res, columns=['T', 'x', 'vary', 'w'])
@@ -40,33 +52,40 @@ class SLE:
 # =============================================================================
 # MATHEMATICS
 # =============================================================================
-    def solve_sle(self, args, init, solver='root'):
-        is_iterable = hasattr(init, "__len__") and len(init) > 1
+    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)
-        x0 = init
         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.model._convert(res['x'])[0]
+            res['w'] = self.actmodel._convert(res['x'])[0]
             text = (f"T={res['T']:.2f}", f"w={res['w']:.4f}", f"x={res['x']:.4f}")
             if self.show_progress:
-                print(f'SLE ({self.mix_type}): ', *text)
+                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.mix_type})...")
+            print(f"Calculating SLE ({self.config})...")
         # Start with varying 'w' until dTdw > THRESHOLD
         self._vary = 'w'
-        args, x0 = self.initialize()
+        args = self.set_args()
+        x0 = self.set_x0()
         gen = self.solve_sle(args, x0, solver)
         previous = None
         for i, current in enumerate(gen):
@@ -77,10 +96,7 @@ class SLE:
         # Switch to varying 'T'
         self._vary = 'T'
         T0, x0 = current['T'], current['x']
-        # # (Deprecated): If last dT>5, make the next dT=5 (from old version)
-        # T1 = previous['T']; dT = T0 - T1
-        # T0 += dT if abs(dT) < 5 else np.sign(dT) * 5
-        args = self.set_args(xmax=T0)[1:]  # exclude initial point (redundant)
+        args = self.set_args(xmax=T0)[1:]  # exclude initial point
         gen = self.solve_sle(args, x0)
         yield from gen
 
@@ -92,7 +108,7 @@ class SLE:
         return np.exp(-self.gibbs_fusion(T))
 
     def real_mix(self, T, x):
-        lngamma = self.model.lngamma(T, x)[0]
+        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:
@@ -115,12 +131,12 @@ class SLE:
 # =============================================================================
 # HELPER FUNCTIONS
 # =============================================================================
-    def initialize(self, xmin=None, xmax=None, dx=None, data=None, init=None):
-        args = self.set_args(xmin, xmax, dx, data)
-        x0 = self.set_x0(init)
-        return args, x0
-
-    def set_args(self, xmin=None, xmax=None, dx=None, data=None):
+    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
@@ -132,7 +148,7 @@ class SLE:
         ma = defaults[vary]['max'] if xmax is None else xmax
         dx = defaults[vary]['step'] if dx is None else dx
 
-        if data is None:
+        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)
@@ -145,17 +161,18 @@ class SLE:
             else:  # vary == 'w'
                 num = 16 if self.mix_type == 'ideal' else 21
                 args = spacing(ma, mi, num, 'quadratic')
-        else:
-            args = data
-        return args if vary != 'w' else self.model._convert(args, to='mole')
+        args = np.asarray(args)
+        args = args if vary != 'w' else self.actmodel._convert(args, to='mole')
+        return args
 
-    def set_x0(self, init=None):
+    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.model._convert(init, to='mole')
+            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'):
@@ -205,3 +222,19 @@ class SLE:
             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-0.0.21 → cosmopharm-0.0.23/src/cosmopharm.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cosmopharm
-Version: 0.0.21
+Version: 0.0.23
 Summary: Predictive modeling for drug-polymer compatibility in pharmaceutical formulations using COSMO-SAC.
 Home-page: https://github.com/ivanantolo/cosmopharm,
 Author: Ivan Antolovic
@@ -38,10 +38,15 @@ Requires-Dist: matplotlib>=3.0; extra == "examples"
 
 # COSMOPharm
 
+Welcome to the COSMOPharm package, accompanying [our paper in *J. Chem. Theory Comput.*](https://dx.doi.org/10.1021/acs.jctc.9b01016). This project and its associated publication offer insights and a practical toolkit for researching drug-polymer and drug-solvent systems, aiming to provide the scientific community with the means to reproduce our findings and further the development of COSMO-SAC-based models.
+
 <p align="center">
-  <img src="https://github.com/usnistgov/COSMOSAC/raw/master/JCTC2020.PNG" alt="TOC Figure" width="500">
+  <!-- <img src="https://github.com/usnistgov/COSMOSAC/raw/master/JCTC2020.PNG" alt="TOC Figure" width="500"> -->
+  <img src="https://github.com/usnistgov/COSMOSAC/raw/master/JCTC2020.PNG" alt="TOC Figure">
 </p>
 
+## About 
+
 COSMOPharm is a Python package designed for predictive modeling of drug-polymer compatibility and drug-solubility in common solvents. It leverages the COSMO-SAC (Conductor-like Screening Model Segment Activity Coefficient) model, offering a robust platform for solubility, miscibility, and phase behavior prediction in drug formulation processes.
 
 ## Features
@@ -51,19 +56,13 @@ COSMOPharm is a Python package designed for predictive modeling of drug-polymer
 - **Miscibility and Phase Behavior Analysis**: Understand drug-polymer miscibility and phase behavior under various conditions.
 - **User-friendly Interface**: Facilitate research with easy-to-use functions and comprehensive documentation.
 
-## Associated Research
-
-The development of COSMOPharm is closely tied to ongoing research aimed at enhancing the understanding and application of COSMO-SAC models in drug formulation. A forthcoming manuscript detailing the theoretical foundations and empirical validations of the models used in this package will provide comprehensive insights into the work COSMOPharm supports.
-
-**Note:** A related publication, provided as an example of the research context, can be found [here](https://dx.doi.org/10.1021/acs.jctc.9b01016). This link will be updated to directly point to our specific manuscript upon its publication, enabling users to delve deeper into the scientific basis and applications of COSMOPharm.
-
 ## Installation
 
 Install COSMOPharm with pip:
 
 `pip install cosmopharm`
 
-Ensure you have installed the cCOSMO library as per instructions on the [COSMOSAC GitHub page](https://github.com/usnistgov/COSMOSAC).
+Ensure you have installed the `cCOSMO` library as per instructions on the [COSMOSAC GitHub page](https://github.com/usnistgov/COSMOSAC).
 
 ## Quick Start
 

cosmopharm-0.0.21/src/cosmopharm/actmodels/actmodel.py

@@ -1,83 +0,0 @@
-import numpy as np
-import numbers
-
-from ..utils.convert import convert
-
-class ActModel:
-
-    def __init__(self, components: list = []):
-        self.mix = components
-
-    def lngamma(self, T, x):
-        pass
-
-    def dlngamma(self, T, x):
-        # Only binary case
-        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)
-        # Revert direction of dy2_dx2 --> dy2_dx1
-        dy[1] = dy[1][::-1]
-        return f(x), dy
-
-    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):
-        # 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(x.shape[1])
-        # Fill gmix with calculated values where the mask is True
-        gmix[mask] = _gmix
-        return gmix
-
-
-# =============================================================================
-# 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.mix):
-            return np.array([x, 1 - x])
-        return x
-
-    def _convert(self, x, to='weight'):
-        Mw = np.array([c.Mw for c in self.mix])
-        return convert(x=np.array([x, 1-x]), Mw=Mw, to=to)[0]

cosmopharm-0.0.21/src/cosmopharm/equilibrium/lle.py

@@ -1,89 +0,0 @@
-import numpy as np
-import pandas as pd
-from scipy.optimize import least_squares
-
-from ..utils import spacing
-from ..utils.lle_scanner import estimate_lle_from_gmix
-
-
-class LLE:
-    def __init__(self, actmodel):
-        self.mix = actmodel.mix
-        self.model  = actmodel
-
-    def fobj_binodal(self, x1, T):
-        # Equilibrium: Isoactivity criterion (aL1 - aL2 = 0)
-        x = np.array([x1, 1-x1])
-        activity = self.model.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.model.thermofac(T, x)
-
-    def binodal(self, T, x0=None):
-        if x0 is None:
-            x0 = [0.1, 0.999]    # 1_N2_Ethan
-        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, x0=None):
-        if x0 is None:
-            x0 = self.binodal()
-        return least_squares(self.fobj_spinodal, x0).x
-
-# =============================================================================
-#
-# =============================================================================
-    def approx_init_x0(self, T):
-        x1 = spacing(0,1,51,'poly',n=3)
-        gmix = self.model.gmix(T, x1)
-        xL, xR, yL, yR = estimate_lle_from_gmix(x1, gmix, rough=True)
-        return xL, xR
-
-    def solve_lle(self, T, x0, info=True):
-        binodal_x = self.binodal(T, x0)
-        binodal_w = self.model._convert(binodal_x)
-        formatted_w_binodal = [f"wL{i+1}={value:.4f}" for i, value in enumerate(binodal_w)]
-        formatted_x_binodal = [f"xL{i+1}={value:.6f}" for i, value in enumerate(binodal_x)]
-        msg = ('LLE: ', f"{T=:.2f}", *formatted_w_binodal, *formatted_x_binodal)
-        if info:
-            print(*msg)
-            return binodal_x, binodal_w
-        return binodal_x, binodal_w, msg
-
-    def miscibility(self, T, x0=None, max_gap=0.1, max_T=500, dT=25):
-        print()
-        print("Calculating LLE...")
-        res = []
-
-        if x0 is None:
-            print("...searching for suitable initial value...")
-            x0 = self.approx_init_x0(T)
-        binodal_x, binodal_w, msg = self.solve_lle(T, x0, info=False)
-
-        # Check if initial guess is reasonalble - otherwise increase T
-        while binodal_x[0] < x0[0] 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_x, binodal_w, msg = self.solve_lle(T, x0, info=False)
-        print("Suitable initial value found! Proceed with calculating LLE...")
-        print(*msg)
-        gap = np.diff(binodal_w)[0]
-        res.append((T, *binodal_w, *binodal_x))
-
-        exponent = 2.1
-        while gap > max_gap and T <= max_T:
-            T += dT * gap**exponent
-            x0 = binodal_x
-            binodal_x, binodal_w = self.solve_lle(T, x0)
-            gap = np.diff(binodal_w)[0]
-            res.append((T, *binodal_w, *binodal_x))
-
-        columns = ['T', 'wL1', 'wL2', 'xL1', 'xL2']
-        res = pd.DataFrame(res, columns=columns)
-        return res