flory 0.0.0__py3-none-any.whl

flory/__init__.py

@@ -0,0 +1,18 @@
+"""
+Package :mod:`flory` provides methods and classes for phase separation in multicomponent mixtures based on Flory-Huggins theory.
+"""
+
+try:
+    # try reading version of the automatically generated module
+    from ._version import __version__
+except ImportError:
+    from importlib.metadata import version, PackageNotFoundError
+
+    try:
+        __version__ = version("flory")
+    except PackageNotFoundError:
+        # package is not installed
+        __version__ = "unknown"
+    del PackageNotFoundError, version
+
+from .mcmp import CoexistingPhasesFinder, find_coexisting_phases

flory/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.0.0'
+__version_tuple__ = version_tuple = (0, 0, 0)

flory/detail/mcmp_impl.py

@@ -0,0 +1,524 @@
+""" The implementation details of the module :mod:`~flory.mcmp`. 
+
+:mod:`flory.detail.mcmp_impl` contains the implementation details of the module
+:mod:`~flory.mcmp`. The main components of the module is the function
+:meth:`multicomponent_self_consistent_metastep`, which implements the self consistent
+iterations for minimizing the extended free energy functional, and the function
+:meth:`get_clusters`, which finds the unique phases.
+
+In this module, arguments of functions are always marked by `Const`, `Output` or
+`Mutable`, to indicate whether the arguments will keep invariant, be directly overwritten,
+or reused.
+
+.. codeauthor:: Yicheng Qiang <yicheng.qiang@ds.mpg.de>
+.. codeauthor:: David Zwicker <david.zwicker@ds.mpg.de>
+"""
+
+import numba as nb
+import numpy as np
+from scipy import cluster, spatial
+
+
+@nb.njit()
+def count_valid_compartments(Js: np.ndarray, threshold: float) -> int:
+    """
+    Count how many entries in :paramref:`~count_valid_compartments.Js` are larger than
+    :paramref:`~count_valid_compartments.threshold`.
+
+    Args:
+        Js:
+            Const. 1D array with the size of :math:`M`.
+        threshold:
+            Const. The threshold value.
+
+    Returns:
+        : Number of entries in :paramref:`Js` larger than :paramref:`threshold`.
+    """
+    return (Js > threshold).sum()
+
+
+@nb.njit()
+def make_valid_compartment_masks(Js: np.ndarray, threshold: float) -> np.ndarray:
+    """
+    Create masks for entries in :paramref:`~make_valid_compartment_masks.Js` are larger
+    than :paramref:`~make_valid_compartment_masks.threshold`. Value of 1.0 or 0.0
+    indicates a valid or invalid mask, respectively.
+
+    Args:
+        Js:
+            Const. 1D array with the size of :math:`M`.
+        threshold:
+            Const. The threshold value.
+
+    Returns:
+        : 
+            1D array with the size of :math:`M`, containing masks of entries in
+            :paramref:`Js` larger than :paramref:`threshold`.
+    """
+    return np.sign(Js - threshold).clip(0.0)
+
+
+@nb.njit()
+def revive_compartments_by_random(
+    Js: np.ndarray,
+    targets: np.ndarray,
+    threshold: float,
+    rng: np.random.Generator,
+    scaler: float,
+) -> int:
+    """
+    Randomly revive compartments whose relative volume (element of
+    :paramref:`~revive_compartments_by_random.Js`) is smaller than
+    :paramref:`~revive_compartments_by_random.threshold`. The revived values are randomly
+    and uniformly sampled between the extreme values of :paramref:`targets` across all
+    compartments. The range can be scaled by the parameter :paramref:`scaler`. Note that
+    this function does not conserve the quantities in :paramref:`targets` across all
+    compartments, since the new values are randomly generated.
+
+    Args:
+        Js:
+            Mutable. 1D array with the size of :math:`M`, containing values to determine
+            whether a compartment is dead.
+        targets:
+            Mutable. 2D array with the size of :math:`N_\\mathrm{c} \\times M`, containing
+            the values to be revived. The second dimension has to be the same as that of
+            Js. Note that this is not checked.
+        threshold:
+            Const. The threshold of :paramref:`Js` for a compartment to be considered
+            dead. For each element of :paramref:`Js` smaller than this parameter, the
+            corresponding compartment will be considered as dead, and its targets values
+            will then be randomly drawn between the corresponding minimum and maximum
+            values of :paramref:`targets` across all compartments. Corresponding
+            :paramref:`Js` will be set to be unity.
+        rng:
+            Mutable. Random number generator for reviving.
+        scaler:
+            Const. The scaler for generating random new values.
+
+    Returns:
+        : Number of dead compartments that have been revived.
+    """
+    revive_count = 0
+    num_component, num_compartment = targets.shape
+
+    target_centers = np.full(num_component, 0.0, float)
+    omega_widths = np.full(num_component, 0.0, float)
+    for itr_component in range(num_component):
+        current_target_max = targets[itr_component].max()
+        current_target_min = targets[itr_component].min()
+        target_centers[itr_component] = (current_target_max + current_target_min) * 0.5
+        omega_widths[itr_component] = (current_target_max - current_target_min) * 0.5
+
+    # revive the compartment with random conjugate field
+    for itr_compartment in range(num_compartment):
+        if Js[itr_compartment] <= threshold:
+            Js[itr_compartment] = 1.0
+            revive_count += 1
+            for itr_component in range(num_component):
+                targets[itr_component, itr_compartment] = target_centers[
+                    itr_component
+                ] + omega_widths[itr_component] * scaler * rng.uniform(-1, 1)
+
+    return revive_count
+
+
+@nb.njit()
+def revive_compartments_by_copy(
+    Js: np.ndarray,
+    targets: np.ndarray,
+    threshold: float,
+    rng: np.random.Generator,
+) -> int:
+    """
+    Revive compartments whose relative volume (element of
+    :paramref:`~revive_compartments_by_copy.Js`) is smaller than
+    :paramref:`~revive_compartments_by_copy.threshold`. The revived values are randomly
+    copied from other living compartments. Note that this function conserves the
+    quantities in :paramref:`targets` across all compartments by modifying the volumes
+    :paramref:`Js` accordingly.
+
+    Args:
+        Js:
+            Mutable. 1D array with the size of :math:`M`, containing values to determine
+            whether a compartment is dead.
+        targets:
+            Mutable. 2D array with the size of :math:`N_\\mathrm{c} \\times M`, containing the
+            values to be revived. The second dimension has to be the same as that of Js.
+            Note that this is not checked.
+        threshold:
+            Const. The threshold of :paramref:`Js` for a compartment to be considered
+            dead. For each element of :paramref:`Js` smaller than this parameter, the
+            corresponding compartment will be considered as dead, and its targets values
+            will then be randomly drawn between the corresponding minimum and maximum
+            values of :paramref:`targets` across all compartments. Corresponding
+            :paramref:`Js` will be set to be unity.
+        rng:
+            Mutable. Random number generator for reviving.
+
+    Returns:
+        : Number of revives
+    """
+    revive_count = 0
+    num_components, num_compartments = targets.shape
+
+    dead_indexes = np.full(num_compartments, -1, dtype=np.int32)
+    dead_count = 0
+    living_nicely_indexes = np.full(num_compartments, -1, dtype=np.int32)
+    living_nicely_count = 0
+    for itr_compartment in range(num_compartments):
+        if Js[itr_compartment] > 2.0 * threshold:
+            living_nicely_indexes[living_nicely_count] = itr_compartment
+            living_nicely_count += 1
+        elif Js[itr_compartment] <= threshold:
+            dead_indexes[dead_count] = itr_compartment
+            dead_count += 1
+
+    for itr_dead in dead_indexes[:dead_count]:
+        while True:
+            pos_in_living = rng.integers(0, living_nicely_count)
+            ref_index = living_nicely_indexes[pos_in_living]
+            if Js[int(ref_index)] > 2.0 * threshold:
+                targets[:, itr_dead] = targets[:, ref_index]
+                new_J = 0.5 * Js[ref_index]
+                Js[itr_dead] = new_J
+                Js[ref_index] = new_J
+                living_nicely_indexes[living_nicely_count] = itr_dead
+                living_nicely_count += 1
+                revive_count += 1
+                break
+            else:
+                living_nicely_count -= 1
+                living_nicely_indexes[pos_in_living] = living_nicely_indexes[
+                    living_nicely_count
+                ]
+                living_nicely_indexes[living_nicely_count] = -1
+    return revive_count
+
+
+@nb.njit()
+def calc_volume_fractions(
+    phis: np.ndarray,
+    Js: np.ndarray,
+    sizes: np.ndarray,
+    phi_means: np.ndarray,
+    omegas: np.ndarray,
+    masks: np.ndarray,
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Calculate the volume fractions of components :math:`\\phi_i^{(m)}` from the conjugate
+    fields :math:`\\omega_i^{(m)}`. The single molecular partition functions $Q_i$ and the
+    incompressibility :math:`\\sum_i \\phi_i^{(m)} - 1` are also calculated. Note that the
+    volume fractions :math:`\\phi_i^{(m)}` are returned through the parameter.
+
+    Args:
+        phis:
+            Output. The 2D array with the size of :math:`N_\\mathrm{c} \\times M`,
+            containing the volume fractions :math:`\\phi_i^{(m)}`. The first dimension has
+            to be the same as :paramref:`sizes`. The second dimension has to be the same
+            as that of :paramref:`Js`. Note that these are not checked.
+        Js:
+            Const. The 1D array with the size of :math:`M`, containing the relative
+            volumes of compartments :math:`J_m`. Note that :paramref:`Js` must be
+            invariant under multiplication of :paramref:`masks`.
+        sizes:
+            Const. The 1D array with the size of :math:`M`, containing the relative
+            molecule volumes of the components :math:`l_i`.
+        phi_means:
+            Const. The 1D array with the size of :math:`N_\\mathrm{c}`, containing the
+            mean volume fractions of the components :math:`\\bar{\\phi}_i`.
+        omegas:
+            Const. The 2D array with the size of :math:`N_\\mathrm{c} \\times M`,
+            containing the conjugate field :math:`\\omega_i^{(m)}`. The first dimension
+            has to be the same as :paramref:`sizes`. The second dimension has to be the
+            same as that of :paramref:`Js`. Note that these are not checked.
+        masks:
+            Const. The 1D array with the size of :math:`M`, containing the masks of
+            compartments. See :meth:`make_valid_compartment_masks` for more information.
+
+    Returns:
+        [0]: 
+            1D array with the size of :math:`N_\\mathrm{c}`, containing the single
+            molecular partition functions of components :math:`Q_i`. 
+        [1]: 
+            1D array with the size of :math:`M`, containing the incompressibility
+            :math:`\\sum_i \\phi_i^{(m)} - 1`.
+    """
+
+    num_components, num_compartments = omegas.shape
+    Qs = np.full(num_components, 0.0, float)
+    incomp = np.full(num_compartments, -1.0, float)
+    total_Js = Js.sum()
+    for itr_comp in range(num_components):
+        phis[itr_comp] = np.exp(-omegas[itr_comp] * sizes[itr_comp])
+        Qs[itr_comp] = (phis[itr_comp] * Js).sum()
+        Qs[itr_comp] /= total_Js
+        factor = phi_means[itr_comp] / Qs[itr_comp]
+        phis[itr_comp] = factor * phis[itr_comp] * masks
+        incomp += phis[itr_comp]
+    incomp *= masks
+    return Qs, incomp
+
+
+@nb.njit()
+def multicomponent_self_consistent_metastep(
+    phi_means: np.ndarray,
+    chis: np.ndarray,
+    sizes: np.ndarray,
+    *,
+    omegas: np.ndarray,
+    Js: np.ndarray,
+    phis: np.ndarray,
+    steps_inner: int,
+    acceptance_Js: float,
+    Js_step_upper_bound: float,
+    acceptance_omega: float,
+    kill_threshold: float,
+    revive_tries: int,
+    revive_scaler: float,
+    rng: np.random.Generator,
+) -> tuple[float, float, float, int, bool]:
+    """
+    The core algorithm of finding coexisting states of multicomponent systems with
+    self-consistent iterations.
+
+    Args:
+        phi_means:
+            Const. The interaction matrix. 2D array with size of :math:`N_\\mathrm{c}
+            \\times N_\\mathrm{c}`. This matrix should be the full :math:`\\chi_{ij}`
+            matrix of the system, including the solvent component. Note that the matrix
+            must be symmetric, which is not checked but should be guaranteed externally.
+        chis:
+            Const. The average volume fractions :math:`\\bar{\\phi}_i` of all the
+            components of the system. 1D array with size of :math:`N_\\mathrm{c}`. Note
+            that the volume fraction of the solvent is included as well, therefore the sum
+            of this array must be unity, which is not checked by this function and should
+            be guaranteed externally.
+        sizes:
+            Const. The relative molecule volumes :math:`l_i` of the components. 1D array
+            with size of :math:`N_\\mathrm{c}`. This sizes vector should be the full sizes
+            vector of the system, including the solvent component. An element of one
+            indicates that the corresponding specie has the same volume as the reference.
+            None indicates a all-one vector.
+        omegas:
+            Mutable. The conjugate field :math:`\\omega_i^{(m)}`. 2D array with size of
+            :math:`N_\\mathrm{c} \\times M`. Note that this field is both used as input
+            and output. Note again that this function DO NOT initialize `omegas`, it
+            should be initialized externally, and usually a random initialization will be
+            a reasonable choice.
+        Js:
+            Mutable. The relative volumes of the compartments :math:`J_m`. 1D array with
+            size of :math:`M`. The average value of `Js` will and should be unity. Note
+            that this field is both used as input and output. An all-one array is usually
+            a nice initialization, unless resume of a previous run is intended.
+        phis:
+            Output. The volume fractions :math:`\\phi_i^{(m)}`. 2D array with size of
+            :math:`N_\\mathrm{c} \\times M`.
+        steps_inner:
+            Constant. Number of steps in current routine. Within these steps, convergence
+            is not checked and no output will be generated.
+        acceptance_Js:
+            Constant. The acceptance of :paramref:`Js` (the relative compartment size
+            :math:`J_m`). This value determines the amount of changes accepted in each
+            step for the :math:`J_m` field. Typically this value can take the order of
+            :math:`10^{-3}`, or smaller when the system becomes larger or stiffer.
+        Js_step_upper_bound:
+            Constant. The maximum change of :paramref:`Js` (the relative compartment size
+            :math:`J_m`) per step. This value is designed to reduce the risk that a the
+            volume of a compartment changes too fast before it develops meaningful
+            composition. If the intended change is larger this value, all the changes will
+            be scaled down to guarantee that the maximum changes do not exceed this value.
+            Typically this value can take the order of :math:`10^{-3}`, or smaller when
+            the system becomes larger or stiffer. 
+        acceptance_omega:
+            Constant. The acceptance of :paramref:`omegas`(the conjugate fields
+            :math:`\\omega_i^{(m)}`). This value determines the amount of changes accepted
+            in each step for the :math:`\\omega_i^{(m)}` field. Note that if the iteration
+            of :math:`J_m` is scaled down due to parameter
+            :paramref:`Js_step_upper_bound`, the iteration of :math:`\\omega_i^{(m)}`
+            fields will be scaled down simultaneously. Typically this value can take the
+            order of :math:`10^{-2}`, or smaller when the system becomes larger or
+            stiffer.         
+        kill_threshold:
+            Constant. The threshold of the :math:`J_m` for a compartment to be considered
+            dead and killed afterwards. Should be not less than 0. In each iteration step,
+            the :math:`J_m` array will be checked, for each element smaller than this
+            parameter, the corresponding compartment will be killed and 0 will be assigned
+            to the internal mask. The dead compartment may be revived, depending whether
+            reviving is allowed or whether the number of the revive tries has been
+            exhausted. 
+        revive_tries:
+            Constant. Number of tries left to revive the dead compartment. 0 or negative
+            value indicates no reviving. When this value is exhausted, i.e. the number of
+            revive in current function call exceeds this value, the revive will be turned
+            off. Note that this function does not decrease this value, but returns the number
+            of revives that have happened after completion.
+        revive_scaler:
+            Constant. The scaling factor for the conjugate fields :math:`\\omega_i^{(m)}`
+            when a dead compartment is revived. This value determines the range of the
+            random conjugate field generated by the algorithm. Typically 1.0 or some value
+            slightly larger will be a reasonable choice. See
+            :meth:`revive_compartments_by_random` for more information.
+        rng:
+            Mutable. random number generator for reviving.
+
+    Returns:
+        [0]: Max absolute incompressibility.
+        [1]: Max absolute conjugate field error.
+        [2]: Max absolute relative volumes error.
+        [3]: Number of revives.
+        [4]: Whether no phase is killed in the last step.
+    """
+    num_components, num_compartments = omegas.shape
+    chi_sum_sum = chis.sum()
+
+    n_valid_phase = 0
+
+    revive_count = 0
+    for _ in range(steps_inner):
+        # check if we are still allowed to revive compartments
+        if revive_count < revive_tries:
+            n_valid_phase = count_valid_compartments(Js, kill_threshold)
+            if n_valid_phase != num_compartments:
+                # revive dead compartments
+                revive_count += revive_compartments_by_random(
+                    Js, omegas, kill_threshold, rng, revive_scaler
+                )
+
+        # generate masks for the compartments
+        masks = make_valid_compartment_masks(Js, kill_threshold)
+        n_valid_phase = int(masks.sum())
+        Js *= masks
+
+        # calculate volume fractions, single molecular partition function Q and incompressibility
+        (Qs, incomp) = calc_volume_fractions(phis, Js, sizes, phi_means, omegas, masks)
+        max_abs_incomp = np.abs(incomp).max()
+
+        # temp for omega, namely chi.phi
+        omega_temp = chis @ phis
+
+        # xi, the lagrangian multiplier
+        xi = chi_sum_sum * incomp
+        for itr_comp in range(num_components):
+            xi += omegas[itr_comp] - omega_temp[itr_comp]
+        xi *= masks
+        xi /= num_components
+
+        # local energy. i.e. energy of phases excluding the partition function part
+        local_energy = xi * incomp
+        for itr_comp in range(num_components):
+            local_energy += (
+                -0.5 * omega_temp[itr_comp] - xi - 1.0 / sizes[itr_comp]
+            ) * phis[itr_comp]
+
+        # calculate the difference of Js
+        local_energy_mean = (local_energy * Js).sum() / n_valid_phase
+        Js_diff = (local_energy_mean - local_energy) * masks
+        max_abs_Js_diff = np.abs(Js_diff).max()
+
+        # calculate additional factor to scale down iteration
+        Js_max_change = max_abs_Js_diff * acceptance_Js
+        additional_factor = Js_step_upper_bound / max(Js_max_change, Js_step_upper_bound)
+
+        # update Js
+        Js += additional_factor * acceptance_Js * Js_diff
+        Js *= masks
+        Js += 1 - (Js.sum() / n_valid_phase)
+        Js *= masks
+
+        # calculate difference of omega and update omega directly
+        max_abs_omega_diff = 0
+        for itr_comp in range(num_components):
+            omega_temp[itr_comp] = omega_temp[itr_comp] + xi - omegas[itr_comp]
+            omega_temp[itr_comp] *= masks
+            omega_temp[itr_comp] -= omega_temp[itr_comp].sum() / n_valid_phase
+            max_abs_omega_diff = max(max_abs_omega_diff, omega_temp[itr_comp].max())
+            omegas[itr_comp] += (
+                additional_factor * acceptance_omega * omega_temp[itr_comp]
+            )
+            omegas[itr_comp] *= masks
+            omegas[itr_comp] -= omegas[itr_comp].sum() / n_valid_phase
+
+    # count the valid phases in the last step
+    n_valid_phase_last = count_valid_compartments(Js, kill_threshold)
+
+    return (
+        max_abs_incomp,
+        max_abs_omega_diff,
+        max_abs_Js_diff,
+        revive_count,
+        n_valid_phase == n_valid_phase_last,
+    )
+
+
+def sort_phases(
+    Js_phases: np.ndarray, phis_phases: np.ndarray
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Sort the phases according to the index of most concentrated components. Note that this
+    function uses different data structure from other functions in the module. See
+    :paramref:`phis_phases`.
+
+    Args:
+        Js_phases:
+            Const. 1D array with the size of :math:`N_\\mathrm{p}`, containing the volumes
+            of each phase.
+        phis_phases:
+            Const. 2D array with the size of :math:`N_\\mathrm{p} \\times N_\\mathrm{c}`,
+            containing the volume fractions of the components in each phase. The first
+            dimension must be the same as :paramref:`Js_phases`. Note that this usually
+            corresponds to the transpose of the arrays of :math:`\\phi_i^{(m)}`, for
+            example :attr:`~flory.mcmp.CoexistingPhasesFinder.phis` in class
+            :class:`~flory.mcmp.CoexistingPhasesFinder`.
+
+    Returns:
+        [0]: Sorted :paramref:`Js_phases`.
+        [1]: Sorted :paramref:`phis_phases`.
+    """
+    enrich_indexes = np.argsort(phis_phases)
+    sorting_index = np.lexsort(np.transpose(enrich_indexes))
+    return Js_phases[sorting_index], phis_phases[sorting_index]
+
+
+def get_clusters(
+    Js: np.ndarray, phis: np.ndarray, dist: float = 1e-2
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Find unique phases from compartments by clustering. The returning results are sorted
+    according to the index of most concentrated components.
+
+    Args:
+        Js:
+            Const. 1D array with the size of :math:`M`, containing the volumes of each
+            compartment.
+        phis:
+            Const. 2D array with the size of :math:`N_\\mathrm{c} \\times M`, containing
+            the volume fractions of the components in each phase :math:`\\phi_i^{(m)}`.
+            The second dimension must be the same as :math:`Js`.
+        dist: 
+            Cut-off distance for cluster analysis
+    
+    Returns:
+        [0]: 
+            1D array with the size of :math:`N_\\mathrm{p}`, containing the volumes of the
+            unique phases.
+        [1]: 
+            1D array with the size of :math:`N_\\mathrm{p} \\times  N_\\mathrm{c}`,
+            containing the compositions of all unique phases. Note that the data structure
+            is different from normal, see :meth:`sort_phases` for more information.
+    """
+    # transpose to make the compartment index the first index
+    phis = np.transpose(phis)
+    # calculate distances between compositions
+    if phis.shape[0] == 1:
+        return phis, 1
+    dists = spatial.distance.pdist(phis)
+    # obtain hierarchy structure
+    links = cluster.hierarchy.linkage(dists, method="centroid")
+    # flatten the hierarchy by clustering
+    clusters = cluster.hierarchy.fcluster(links, dist, criterion="distance")
+    cluster_phis = np.array(
+        [phis[clusters == n, :].mean(axis=0) for n in np.unique(clusters)]
+    )
+    cluster_Js = np.array([Js[clusters == n].sum(axis=0) for n in np.unique(clusters)])
+    cluster_Js /= cluster_Js.sum()
+    return sort_phases(cluster_Js, cluster_phis)

flory/mcmp.py

@@ -0,0 +1,641 @@
+"""Module for finding coexisting phases of multicomponent mixtures.
+
+:mod:`flory.mcmp` provides tools for finding equilibrium multiple coexisting phases in
+multicomponent mixtures in the canonical ensemble based on Flory-Huggins theory. The
+module provides both the function API :meth:`find_coexisting_phases` and the class API
+:class:`CoexistingPhasesFinder`. The function :meth:`find_coexisting_phases` aims at
+easing the calculation of the coexisting phases with a single system setting, namely one
+single point in the phase diagram. In contrast, The class :class:`CoexistingPhasesFinder`
+is designed for reuse over systems with the same system sizes such as the number of
+components, which includes generating a coexisting curve or sampling a phase diagram. It
+creates a finder to maintain its internal data, and provides more control and diagnostics
+over the iteration. See :ref:`Examples` for examples.
+
+.. codeauthor:: Yicheng Qiang <yicheng.qiang@ds.mpg.de>
+.. codeauthor:: David Zwicker <david.zwicker@ds.mpg.de>
+"""
+
+import logging
+import numpy as np
+from datetime import datetime
+from typing import Optional
+from tqdm.auto import tqdm
+from .detail.mcmp_impl import *
+
+
+class CoexistingPhasesFinder:
+    """
+    Create a finder for coexisting phases.
+    """
+
+    def __init__(
+        self,
+        chis: np.ndarray,
+        phi_means: np.ndarray,
+        num_compartments: int,
+        *,
+        sizes: Optional[np.ndarray] = None,
+        rng: Optional[np.random.Generator] = None,
+        max_steps: int = 1000000,
+        convergence_criterion: str = "standard",
+        tolerance: float = 1e-5,
+        interval: int = 10000,
+        progress: bool = True,
+        random_std: float = 5.0,
+        acceptance_Js: float = 0.0002,
+        acceptance_omega: float = 0.002,
+        Js_step_upper_bound: float = 0.001,
+        kill_threshold: float = 0.0,
+        revive_scaler: float = 1.0,
+        max_revive_per_compartment: int = 16,
+        additional_chis_shift: float = 1.0,
+    ):
+        """
+        Construct a :class:`CoexistingPhasesFinder` instance for finding coexisting
+        phases. This class is recommended when multiple instances of :paramref:`chis`
+        matrix or :paramref:`phi_means` vector need to be calculated. The class will reuse
+        all the options and the internal resources. Note that reuse the instance of this
+        class is only possible when all the system sizes are not changed, including the
+        number of components :math:`N_\\mathrm{c}` and the number of compartments
+        :math:`M`. The the number of components :math:`N_\\mathrm{c}` is inferred from
+        :paramref:`chis` and :paramref:`phi_means`, while :math:`N_\\mathrm{c}` is set by
+        the parameter :paramref:`num_compartments`. Setting :paramref:`chis` matrix and
+        :paramref:`phi_means` manually by the setters leads to the reset of the internal
+        revive counters.
+
+        Args:
+            chis:
+                The interaction matrix. 2D array with size of :math:`N_\\mathrm{c} \\times
+                N_\\mathrm{c}`. This matrix should be the full :math:`\\chi_{ij}` matrix
+                of the system, including the solvent component. Note that the matrix must
+                be symmetric, which is not checked but should be guaranteed externally.
+            phi_means:
+                The average volume fractions :math:`\\bar{\\phi}_i` of all the components
+                of the system. 1D array with size of :math:`N_\\mathrm{c}`. Note that the
+                volume fraction of the solvent is included as well, therefore the sum of
+                this array must be unity, which is not checked by this function and should
+                be guaranteed externally.
+            num_compartments:
+                Number of compartments :math:`M` in the system.
+            sizes:
+                The relative molecule volumes :math:`l_i` of the components. 1D array with
+                size of :math:`N_\\mathrm{c}`. This sizes vector should be the full sizes
+                vector of the system, including the solvent component. An element of one
+                indicates that the corresponding specie has the same volume as the
+                reference. None indicates a all-one vector.
+            rng:
+                Random number generator for initialization and reviving. None indicates
+                that a new random number generator should be created by the class, seeded
+                by current timestamp.
+            max_steps:
+                The default maximum number of steps in each run to find the coexisting
+                phases. This value can be temporarily overwritten, see :meth:`run` for more
+                information.
+            convergence_criterion:
+                The criterion to determine convergence. Currently "standard" is the only
+                option, which requires checking of incompressibility, field error and the
+                volume error. Note that all these metrics are state functions, namely they
+                are independent of iteration parameters.
+            tolerance:
+                The tolerance to determine convergence. This value can be temporarily
+                overwritten. See :paramref:`convergence_criterion` and :meth:`run` for
+                more information.
+            interval:
+                The interval of steps to check convergence. This value can be temporarily
+                overwritten, see :meth:`run` for more information.
+            progress:
+                Whether to show progress bar when checking convergence. This value can be
+                temporarily overwritten, see :meth:`run` for more information.
+            random_std:
+                The amplitude of the randomly generated conjugate fields internally.
+                During instantiation, the conjugate field is randomly generated according
+                to an normal distribution with standard deviation :paramref:`random_std`.
+            acceptance_Js:
+                The acceptance of the relative compartment size :math:`J_m`. This value
+                determines the amount of changes accepted in each step for the :math:`J_m`
+                field. Typically this value can take the order of :math:`10^{-3}`, or
+                smaller when the system becomes larger or stiffer.
+            Js_step_upper_bound:
+                The maximum change of the relative compartment size :math:`J_m` per step.
+                This value is designed to reduce the risk that a the volume of a
+                compartment changes too fast before it develops meaningful composition. If
+                the intended change is larger this value, all the changes will be scaled
+                down to guarantee that the maximum changes do not exceed this value.
+                Typically this value can take the order of :math:`10^{-3}`, or smaller
+                when the system becomes larger or stiffer.
+            acceptance_omega:
+                The acceptance of the conjugate fields :math:`\\omega_i^{(m)}`. This value
+                determines the amount of changes accepted in each step for the
+                :math:`\\omega_i^{(m)}` field. Note that if the iteration of :math:`J_m` is
+                scaled down due to parameter :paramref:`Js_step_upper_bound`, the
+                iteration of :math:`\\omega_i^{(m)}` fields will be scaled down simultaneously.
+                Typically this value can take the order of :math:`10^{-2}`, or smaller
+                when the system becomes larger or stiffer.
+            kill_threshold:
+                The threshold of the :math:`J_m` for a compartment to be considered dead
+                and killed afterwards. Should be not less than 0. In each iteration step,
+                the :math:`J_m` array will be checked, for each element smaller than this
+                parameter, the corresponding compartment will be killed and 0 will be
+                assigned to the internal mask. The dead compartment may be revived,
+                depending whether reviving is allowed or whether the number of the revive
+                tries has been exhausted.
+            revive_scaler:
+                The scaler for the value of the newly-generated conjugate fields when a
+                dead compartment is revived. The compartment is revived by drawing random
+                numbers for their conjugate fields in the range of the minimum and the
+                maximum of the :math:`\\omega_i^{(m)}` their conjugate fields across all
+                compartments. This value determines whether this range should be enlarged
+                (a value larger than 1) or reduced (a value smaller than 1). Typically 1.0
+                or a value slightly larger than 1.0 will be a reasonable choice.
+            max_revive_per_compartment:
+                Maximum average number of tries per compartment to revive the dead
+                compartments. 0 or negative value indicates no reviving. When this value
+                is exhausted, the revive will be turned off.
+            additional_chis_shift:
+                Shift of the entire chis matrix to improve the convergence by evolving
+                towards incompressible system faster. This value should be larger than 0.
+                Note that with very large value, the convergence will be slowed down,
+                since the algorithm no longer have enough ability to temporarily relax the
+                incompressibility.
+        """
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+        # chis
+        chis = np.array(chis)
+        if chis.shape[0] == chis.shape[1]:
+            self._chis = chis
+            self._num_components = chis.shape[0]
+            self._logger.info(
+                f"We infer that there are {self._num_components} components in the system from the chis matrix."
+            )
+        else:
+            self._logger.error(f"chis matrix with size of {chis.shape} is not square.")
+            raise ValueError("chis matrix must be square.")
+        if (chis != chis.transpose()).any():
+            self._logger.error(f"chis matrix is not symmetric.")
+            raise ValueError("chis matrix must be symmetric.")
+
+        # phi_means
+        phi_means = np.array(phi_means)
+        if phi_means.shape[0] == self._num_components:
+            self._phi_means = phi_means
+            if np.abs(self._phi_means.sum() - 1.0) > 1e-12:
+                self._logger.warning(
+                    f"Total phi_means is not 1.0. Iteration may never converge."
+                )
+        else:
+            self._logger.error(
+                f"phi_means vector with size of {phi_means.shape} is invalid, since {self._num_components} is defined by chis matrix."
+            )
+            raise ValueError(
+                "phi_means vector must imply same component number as chis matrix."
+            )
+
+        self._num_compartments = num_compartments
+
+        ## optional arguments
+
+        # sizes
+        if sizes is None:
+            self._sizes = np.ones(self._num_components)
+        else:
+            sizes = np.array(sizes)
+            if sizes.shape[0] == self._num_components:
+                self._sizes = sizes
+                if np.sum(self._sizes <= 0):
+                    self._logger.warning(
+                        f"Non-positive sizes detected. Iteration will probably fail."
+                    )
+            else:
+                self._logger.error(
+                    f"sizes vector with size of {sizes.shape} is invalid, since {self._num_components} is defined by chis matrix."
+                )
+                raise ValueError(
+                    "sizes vector must imply same component number as chis matrix."
+                )
+
+        # rng
+        if rng is None:
+            self._rng_is_external = False
+            self._rng_seed = int(datetime.now().timestamp())
+            self._rng = np.random.default_rng(self._rng_seed)
+        else:
+            self._rng_is_external = True
+            self._rng_seed = int(0)
+            self._rng = rng
+
+        # other parameters
+        self._max_steps = max_steps
+        self._convergence_criterion = convergence_criterion
+        self._tolerance = tolerance
+        self._interval = interval
+        self._progress = progress
+
+        self._random_std = random_std
+        self._acceptance_Js = acceptance_Js
+        self._acceptance_omega = acceptance_omega
+        self._Js_step_upper_bound = Js_step_upper_bound
+        self._kill_threshold = kill_threshold
+        self._revive_scaler = revive_scaler
+        self._max_revive_per_compartment = max_revive_per_compartment
+        self._additional_chis_shift = additional_chis_shift
+
+        # diagnostics
+        self._diagnostics = {}
+
+        ## initialize derived internal states
+        self._Js = np.full(self._num_compartments, 0.0, float)
+        self._omegas = np.full((self._num_components, self._num_compartments), 0.0, float)
+        self._phis = np.full((self._num_components, self._num_compartments), 0.0, float)
+        self._revive_count_left = (
+            self._max_revive_per_compartment * self._num_compartments
+        )
+        self.reinitialize_random()
+
+    def reinitialize_random(self):
+        """
+        Reinitialize the internal conjugate field :math:`\\omega_i^{(m)}` randomly. See parameter
+        :paramref:`CoexistingPhasesFinder.random_std` for more information.
+        """
+        self._omegas = self._rng.normal(
+            0.0,
+            self._random_std,
+            (self._num_components, self._num_compartments),
+        )
+        self._Js = np.full(self._num_compartments, 1.0, float)
+        self._revive_count_left = (
+            self._max_revive_per_compartment * self._num_compartments
+        )
+
+    def reinitialize_from_omegas(self, omegas: np.ndarray):
+        """
+        Reinitialize the internal conjugate field :math:`\\omega_i^{(m)}` from input.
+
+        Args:
+            omegas:
+                New :math:`\\omega_i^{(m)}` field, must have the same size of
+                :math:`N_\\mathrm{c} \\times M`.
+        """
+        omegas = np.array(omegas)
+        if omegas.shape == self._omegas.shape:
+            self._omegas = omegas
+        else:
+            self._logger.error(
+                f"new omegas with size of {omegas.shape} is invalid. It must have the size of {(self._num_components, self._num_compartments)}."
+            )
+            raise ValueError("New omegas must match the size of the old one.")
+        self._Js = np.ones_like(self._Js)
+        self._revive_count_left = (
+            self._max_revive_per_compartment * self._num_compartments
+        )
+
+    def reinitialize_from_phis(self, phis):
+        """
+        Reinitialize the internal conjugate field :math:`\\omega_i^{(m)}` from volume fraction
+        field :math:`\\phi_i^{(m)}`. Note that it is not guaranteed that the initial volume
+        fraction field :math:`\\phi_i^{(m)}` is fully respected. The input is only considered
+        as a suggestion for the generation of :math:`\\omega_i^{(m)}` field.
+
+        Args:
+            phis:
+                New :math:`\\phi_i^{(m)}` field, must have the same size of :math:`N_\\mathrm{c}
+                \\times M`.
+        """
+        if phis.shape == self._omegas.shape:
+            self._omegas = -np.log(phis)
+            for itr in range(self._num_components):
+                self._omegas[itr] /= self._sizes[itr]
+        else:
+            self._logger.error(
+                f"phis with size of {phis.shape} is invalid. It must have the size of {(self._num_components, self._num_compartments)}."
+            )
+            raise ValueError("phis must match the size of the omegas.")
+        self._Js = np.ones_like(self._Js)
+        self._revive_count_left = (
+            self._max_revive_per_compartment * self._num_compartments
+        )
+
+    @property
+    def chis(self) -> np.ndarray:
+        """
+        The full interaction matrix :math:`\\chi_{ij}`, with the size of
+        :math:`N_\\mathrm{c} \\times N_\\mathrm{c}`. Resetting this property requires
+        that the new matrix has the same size with the internal one. Note that this
+        implies implicit reset of the internal data, the number of revives, but not the
+        others including volume fractions :math:`\\phi_i^{(m)}` and conjugate fields
+        :math:`\\omega_i^{(m)}`. See class parameters
+        :paramref:`~CoexistingPhasesFinder.chis` and
+        :paramref:`~CoexistingPhasesFinder.max_revive_per_compartment` for more
+        information.
+        """
+        return self._chis
+
+    @chis.setter
+    def chis(self, chis_new: np.ndarray):
+        chis_new = np.array(chis_new)
+        if chis_new.shape == self._chis.shape:
+            if (chis_new != chis_new.transpose()).any():
+                self._logger.error(f"chis matrix is not symmetric.")
+                raise ValueError("chis matrix must be symmetric.")
+            self._chis = chis_new
+        else:
+            self._logger.error(
+                f"new chis with size of {chis_new.shape} is invalid. It must have the size of {self._chis.shape}."
+            )
+            raise ValueError("New chis must match the size of the old one.")
+        self._revive_count_left = (
+            self._max_revive_per_compartment * self._num_compartments
+        )
+
+    @property
+    def phi_means(self) -> np.ndarray:
+        """
+        The average volume fractions of all components :math:`\\bar{\\phi}_i`, with the
+        size of :math:`N_\\mathrm{c}`. Resetting this property requires that the new array
+        has the same size with the internal one. Note that this implies implicit reset of
+        the internal data, the number of revives, but not the others including volume
+        fractions :math:`\\phi_i^{(m)}` and conjugate fields :math:`\\omega_i^{(m)}`. See
+        class parameters :paramref:`~CoexistingPhasesFinder.phis_mean` and
+        :paramref:`~CoexistingPhasesFinder.max_revive_per_compartment` for more
+        information.
+        """
+        return self._phi_means
+
+    @phi_means.setter
+    def phi_means(self, phi_means_new):
+        phi_means_new = np.array(phi_means_new)
+        if phi_means_new.shape == self._phi_means.shape:
+            self._phi_means = phi_means_new
+            if np.abs(self._phi_means.sum() - 1.0) > 1e-12:
+                self._logger.warning(
+                    f"Total phi_means is not 1.0. Iteration may never converge."
+                )
+        else:
+            self._logger.error(
+                f"new phi_means with size of {phi_means_new.shape} is invalid. It must have the size of {self._phi_means.shape}."
+            )
+            raise ValueError("New phi_means must match the size of the old one.")
+        self._revive_count_left = (
+            self._max_revive_per_compartment * self._num_compartments
+        )
+
+    @property
+    def sizes(self) -> np.ndarray:
+        """
+        The relative molecule sizes of all components :math:`l_i` with the size of
+        :math:`N_\\mathrm{c}`. Resetting this property requires that the new array has
+        the same size with the internal one. Note that this implies implicit reset of the
+        internal data, the number of revives, but not the others including volume
+        fractions :math:`\\phi_i^{(m)}` and conjugate fields :math:`\\omega_i^{(m)}`. See
+        class parameters :paramref:`~CoexistingPhasesFinder.sizes` and
+        :paramref:`~CoexistingPhasesFinder.max_revive_per_compartment` for more
+        information.
+        """
+        return self._sizes
+
+    @sizes.setter
+    def sizes(self, sizes_new):
+        sizes_new = np.array(sizes_new)
+        if sizes_new.shape == self._sizes.shape:
+            self._sizes = sizes_new
+        else:
+            self._logger.error(
+                f"new sizes with size of {sizes_new.shape} is invalid. It must have the size of {self._sizes.shape}."
+            )
+            raise ValueError("New sizes must match the size of the old one.")
+        self._revive_count_left = (
+            self._max_revive_per_compartment * self._num_compartments
+        )
+
+    @property
+    def phis(self) -> np.ndarray:
+        """
+        The volume fractions field :math:`\\phi_i^{(m)}`, with the size of
+        :math:`N_\\mathrm{c} \\times M`. This property should not be reset in most cases.
+        Resetting this property also takes no effect, since :math:`\\phi_i^{(m)}` is not
+        considered as the master internal state of the algorithm. Any set values will be
+        ignored. If you intend to initialize the system from certain volume fractions,
+        please refer to :meth:`reinitialize_from_phis`.
+        """
+
+        return self._phis
+
+    @property
+    def omegas(self) -> np.ndarray:
+        """
+        The internal conjugate field :math:`\\omega_i^{(m)}`, with the size of
+        :math:`N_\\mathrm{c} \\times M`. This property should not be reset in most cases.
+        Resetting this property will change the state of the system, but skip necessary
+        reset of other internal states. If you intend to initialize the system from a
+        custom conjugate field, please refer to :meth:`reinitialize_from_omegas`.
+        """
+
+        return self._omegas
+
+    @property
+    def diagnostics(self) -> dict:
+        """
+        The diagnostics of the most recent call of :meth:`run`. The diagnostics contain
+        the convergence status and the original volume fractions before the clustering and
+        sorting algorithm is utilized to determine the unique phases.
+        """
+
+        return self._diagnostics
+
+    def run(
+        self,
+        *,
+        max_steps: Optional[float] = None,
+        tolerance: Optional[float] = None,
+        interval: Optional[int] = None,
+        progress: Optional[bool] = None,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Run instance to find coexisting phases. The keywords arguments can be used to
+        temporarily overwrite the provided values during construction of the class. Note
+        that this temporary values will not affect the defaults. See class
+        :class:`CoexistingPhasesFinder` for other tunable parameters. After each call, the
+        diagnostics will be updated, which can be used to, for example, inspecting whether
+        the iteration really converges. See :attr:`diagnostics` for more information.
+
+        Args:
+            max_steps:
+                The maximum number of steps to find the coexisting phases.
+            tolerance:
+                The tolerance to determine convergence. See
+                :paramref:`~CoexistingPhasesFinder.convergence_criterion` for more
+                information.
+            interval:
+                The interval of steps to check convergence.
+            progress:
+                Whether to show progress bar when checking convergence.
+
+        Returns:
+            [0]:
+                Volume fractions of each phase :math:`J_\\alpha`. 1D array with the size of
+                :math:`N_\\mathrm{p}`.
+            [1]:
+                Volume fractions of components in each phase :math:`\\phi_i^{(\\alpha)}`.
+                2D array with the size of :math:`N_\\mathrm{p} \\times N_\\mathrm{c}`.
+        """
+
+        if max_steps is None:
+            max_steps = self._max_steps
+        if tolerance is None:
+            tolerance = self._tolerance
+        if interval is None:
+            interval = self._interval
+        if progress is None:
+            progress = self._progress
+
+        steps_tracker = int(np.ceil(max_steps / interval))
+        steps_inner = max(1, int(np.ceil(max_steps)) // steps_tracker)
+
+        steps = 0
+
+        chis_shifted = self._chis.copy()
+        chis_shifted += -self._chis.min() + self._additional_chis_shift
+
+        bar_max = -np.log10(tolerance)
+        bar_format = "{desc:<20}: {percentage:3.0f}%|{bar}{r_bar}"
+        bar_args = {
+            "total": bar_max,
+            "disable": not progress,
+            "bar_format": bar_format,
+        }
+        bar_text_args = {
+            "total": 1,
+            "disable": not progress,
+            "bar_format": "{desc}",
+        }
+        pbar1 = tqdm(**bar_args, position=0, desc="Incompressibility")
+        pbar2 = tqdm(**bar_args, position=1, desc="Field Error")
+        pbar3 = tqdm(**bar_args, position=2, desc="Volume Error")
+        pbar4 = tqdm(**bar_text_args, position=3, desc="Revive Count Left")
+
+        bar_val_func = lambda a: max(0, min(round(-np.log10(max(a, 1e-100)), 1), bar_max))
+
+        for _ in range(steps_tracker):
+            # do the inner steps
+            (
+                max_abs_incomp,
+                max_abs_omega_diff,
+                max_abs_Js_diff,
+                revive_count,
+                is_last_step_safe,
+            ) = multicomponent_self_consistent_metastep(
+                self._phi_means,
+                chis_shifted,
+                self._sizes,
+                omegas=self._omegas,
+                Js=self._Js,
+                phis=self._phis,
+                steps_inner=steps_inner,
+                acceptance_Js=self._acceptance_Js,
+                Js_step_upper_bound=self._Js_step_upper_bound,
+                acceptance_omega=self._acceptance_omega,
+                kill_threshold=self._kill_threshold,
+                revive_tries=self._revive_count_left,
+                revive_scaler=self._revive_scaler,
+                rng=self._rng,
+            )
+
+            steps += steps_inner
+            self._revive_count_left -= revive_count
+
+            if progress:
+                pbar1.n = bar_val_func(max_abs_incomp)
+                pbar2.n = bar_val_func(max_abs_omega_diff)
+                pbar3.n = bar_val_func(max_abs_Js_diff)
+                pbar4.n = 1
+                pbar1.refresh()
+                pbar2.refresh()
+                pbar3.refresh()
+                pbar4.set_description_str(
+                    "{:<20}: {}".format("Revive Count Left", self._revive_count_left)
+                )
+                pbar4.refresh()
+
+            # check convergence
+            if self._convergence_criterion == "standard":
+                if (
+                    is_last_step_safe
+                    and tolerance > max_abs_incomp
+                    and tolerance > max_abs_omega_diff
+                    and tolerance > max_abs_Js_diff
+                ):
+                    self._logger.info(
+                        f"Composition and volumes reached stationary state after {steps} steps"
+                    )
+                    break
+            else:
+                raise ValueError(
+                    f"Undefined convergence criterion: {self._convergence_criterion}"
+                )
+
+        pbar1.close()
+        pbar2.close()
+        pbar3.close()
+        pbar4.close()
+
+        # get final result
+        final_Js = self._Js.copy()
+        final_phis = self._phis.copy()
+        revive_compartments_by_copy(final_Js, final_phis, self._kill_threshold, self._rng)
+
+        # store diagnostic output
+        self._diagnostics = {
+            "steps": steps,
+            "max_abs_incomp": max_abs_incomp,
+            "max_abs_omega_diff": max_abs_omega_diff,
+            "max_abs_js_diff": max_abs_Js_diff,
+            "revive_count_left": self._revive_count_left,
+            "phis": final_phis,
+            "Js": final_Js,
+        }
+
+        phases_volumes, phases_compositions = get_clusters(final_Js, final_phis)
+
+        return phases_volumes, phases_compositions
+
+
+def find_coexisting_phases(
+    chis: np.ndarray,
+    phi_means: np.ndarray,
+    num_compartments: int,
+    **kwargs,
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    The convenience wrapper for class :class:`CoexistingPhasesFinder`. This function will
+    create the class :class:`CoexistingPhasesFinder` internally, and then conduct the
+    random initialization, finally use self consistent iterations to find coexisting
+    phases. :paramref:`kwargs` is forwarded to :class:`CoexistingPhasesFinder`. See class
+    :class:`CoexistingPhasesFinder` for all the possible options.
+
+    Args:
+        chis:
+            The interaction matrix. 2D array with size of :math:`N_\\mathrm{c} \\times
+            N_\\mathrm{c}`. This matrix should be the full :math:`\\chi_{ij}` matrix of
+            the system, including the solvent component. Note that the matrix must be
+            symmetric, which is not checked but should be guaranteed externally.
+        phi_means:
+            The average volume fractions :math:`\\bar{\\phi}_i` of all the components of
+            the system. 1D array with size of :math:`N_\\mathrm{c}`. Note that the volume
+            fraction of the solvent is included as well, therefore the sum of this array
+            must be unity, which is not checked by this function and should be guaranteed
+            externally.
+        num_compartments:
+            Number of compartments :math:`M` in the system.
+        kwargs:
+            See class :class:`CoexistingPhasesFinder` for all the possible options.
+
+    Returns:
+        [0]:
+            Volume fractions of each phase :math:`J_\\alpha`. 1D array with the size of
+            :math:`N_\\mathrm{p}`.
+        [1]:
+            Volume fractions of components in each phase :math:`\\phi_i^{(\\alpha)}`. 2D
+            array with the size of :math:`N_\\mathrm{p} \\times N_\\mathrm{c}`.
+    """
+    finder = CoexistingPhasesFinder(chis, phi_means, num_compartments, **kwargs)
+    return finder.run()

flory-0.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Yicheng Qiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flory-0.0.0.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.1
+Name: flory
+Version: 0.0.0
+Summary: Python package for finding coexisting phases in multicomponent mixtures
+Author-email: Yicheng Qiang <yicheng.qiang@ds.mpg.de>
+License: MIT License
+Project-URL: homepage, https://github.com/qiangyicheng/flory
+Project-URL: repository, https://github.com/qiangyicheng/flory
+Keywords: physics,phase-separation,free-energy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numba >=0.57
+Requires-Dist: numpy >=1.22
+Requires-Dist: scipy >=1.7
+Requires-Dist: tqdm >=4.60
+Provides-Extra: dev
+Requires-Dist: pytest >=6.2 ; extra == 'dev'
+Requires-Dist: pytest-cov >=4.0 ; extra == 'dev'
+Requires-Dist: Sphinx >=4 ; extra == 'dev'
+Requires-Dist: sphinx-autodoc-typehints >=2.2 ; extra == 'dev'
+Requires-Dist: sphinx-paramlinks >=0.6 ; extra == 'dev'
+Requires-Dist: sphinx-rtd-theme >=2.0 ; extra == 'dev'
+
+# flory
+
+[![Tests](https://github.com/qiangyicheng/flory/actions/workflows/python-package.yml/badge.svg)](https://github.com/qiangyicheng/flory/actions/workflows/python-package.yml)
+[![Codecov](https://codecov.io/github/qiangyicheng/flory/graph/badge.svg?token=YF3K9ST8XQ)](https://codecov.io/github/qiangyicheng/flory)
+[![Documentation Status](https://readthedocs.org/projects/flory/badge/?version=latest)](https://flory.readthedocs.io/en/latest/?badge=latest)
+
+`flory` is a Python package for determining multiple coexisting phases in multicomponent mixtures.
+Although finding coexisting phases of binary mixture is simple, finding multiple coexisting phases in many-component mixtures is challenging, mainly due to the coupling of lots of nolinear equations.
+Currently `flory` supports finding coexisting phases of arbitrary multicomponent system with Flory-Huggins interactions in the canonical ensemble, whose average free energy density reads
+
+$$\bar{f}({N_\mathrm{p}}, \{J_\alpha\}, \{\phi_i^{(\alpha)}\}) = \sum_{\alpha=1}^{{N_\mathrm{p}}} J_\alpha f(\{\phi_i^{(\alpha)}\}) \; ,$$
+
+where $N_\mathrm{c}$ is the number of components, $N_\mathrm{p}$ is the number of phases, $J_\alpha$ is the volume fraction of the phase $\alpha$ and $\phi_i^{(\alpha)}$ is the volume fraction of the component $i$ in the phase $\alpha$.
+Each phase is considered to be homogeneous with a energy density
+
+$$f(\{\phi_i\}) = \frac{1}{2}\sum_{i,j=1}^{N_\mathrm{c}} \chi_{ij} \phi_i \phi_j + \sum_{i=1}^{N_\mathrm{c}} \frac{\phi_i}{l_i} \ln \phi_i \; ,$$
+
+where $\chi_{ij}$ is the Flory-Huggins interaction between component $i$ and $j$, and $l_i$ is the relative molecule size of the component $i$.
+With given interaction matrix $\chi_{ij}$, average volume fractions of all components across the system $\bar{\phi}_i$ and the relative molecule sizes $l_i$, `flory` provides tools to find the coexisting phases in equilibrium.
+
+Installation
+------------
+
+`flory` is available on `pypi`, so you should be able to install it through `pip`:
+
+```bash
+pip install flory
+```
+
+Usage
+-----
+
+A simple example finds the coexisting phases of a binary mixture:
+
+```python
+import flory
+
+chis = [[0, 4.0], [4.0, 0]]     # Set the \chi matrix
+phi_means = [0.5, 0.5]          # Set the average volume fractions
+
+volumes, phis = flory.find_coexisting_phases(chis, phi_means, 16)   # obtain the relative volumes and the compositions of the two coexisting phases
+```
+
+
+More information
+----------------
+* See examples in [examples folder](https://github.com/qiangyicheng/flory/tree/main/examples)
+* [Full documentation on readthedocs](https://flory.readthedocs.io/)
+

flory-0.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+flory/__init__.py,sha256=nJKzfDFUBaQ7iAIMYIzGmG46gK0_qlQjpe1Rr8Q3fIM,582
+flory/_version.py,sha256=Pv9ouMrHW4YJ2RqzWPcojtYRoZtNSgzCzgB3B3Q2FMU,411
+flory/mcmp.py,sha256=rolC1EIChl2BuNUN9Adw3L6pN2qpRIqujf_zo38FKvA,29453
+flory/detail/mcmp_impl.py,sha256=Q-0plKjUwq5byFzyNCrRa8uts5XkSK2NEqMbIAYfh6k,23394
+flory-0.0.0.dist-info/LICENSE,sha256=Avmhj-OrLS-F1uar0j_Z6LllTF0oRBAlAV_JpRlGD6w,1070
+flory-0.0.0.dist-info/METADATA,sha256=XdkhR_kMtxUvH0iiDzIC5MvaB6QdbwVBFhA4Lf6fxZ0,3974
+flory-0.0.0.dist-info/WHEEL,sha256=R0nc6qTxuoLk7ShA2_Y-UWkN8ZdfDBG2B6Eqpz2WXbs,91
+flory-0.0.0.dist-info/top_level.txt,sha256=jtZpdTpD2w3GUbSbuIwh0-DTaWB2Jz_Nqd6up2DxXBU,6
+flory-0.0.0.dist-info/RECORD,,

flory-0.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (72.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flory-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flory