flory


Nameflory JSON
Version 0.3.0 PyPI version JSON
download
home_pageNone
SummaryPython package for finding coexisting phases in multicomponent mixtures
upload_time2025-02-11 16:08:48
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseMIT License
keywords physics phase-separation free-energy
VCS
bugtrack_url
requirements numba numpy scipy tqdm
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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)
[![PyPI version](https://badge.fury.io/py/flory.svg)](https://badge.fury.io/py/flory)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/flory.svg)](https://anaconda.org/conda-forge/flory)

`flory` is a Python package for analyzing field theories of multicomponent mixtures.
In particular, the package provides routines to determine coexisting states numerically, which is a challenging problem since the thermodynamic coexistence conditions are many coupled non-linear equations.
`flory` supports finding coexisting phases with an arbitrary number of components.
The associated average free energy density of the system reads

$$\bar{f}({N_\mathrm{P}}, \{J_p\}, \{\phi_{p,i}\}) = \sum_{p=1}^{{N_\mathrm{P}}} J_p f(\{\phi_{p,i}\}) ,$$

where $N_\mathrm{C}$ is the number of components, $N_\mathrm{P}$ is the number of phases, $J_p$ is the fraction of the system volume occupied by phase $p$, and $\phi_{p,i}$ is the volume fraction of component $i$ in phase $p$.

`flory` supports different forms of interaction, entropy, ensemble, and constraints to describe the free energy of phases.
For example, with the commonly used Flory-Huggins free energy, the free energy density of each homogeneous phase reads

$$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 parameter between component $i$ and $j$, and $l_i$ is the relative molecular size of component $i$.
Given an 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
```

As an alternative, you can install `flory` through [conda](https://docs.conda.io/en/latest/) using the [conda-forge](https://conda-forge.org/) channel:

```bash
conda install -c conda-forge flory
```

### Optional dependencies

By default, only the minimal set of dependencies of `flory` package will be installed. To install all dependencies, run:

```bash
pip install 'flory[dev]'
```

You can also select the optional dependencies, such as `example`, `test` or `doc`. For example, you can install the package with the optional dependencies only for tests:

```bash
pip install 'flory[test]'
```

If you are using conda, consider install the optional dependencies directly:

```bash
conda install -c conda-forge --file https://raw.githubusercontent.com/qiangyicheng/flory/main/examples/requirements.txt
conda install -c conda-forge --file https://raw.githubusercontent.com/qiangyicheng/flory/main/tests/requirements.txt
conda install -c conda-forge --file https://raw.githubusercontent.com/qiangyicheng/flory/main/docs/requirements.txt
```

### Test installation

If the optional dependencies for tests are installed, you can run tests in root directory of the package with `pytest`. By default, some slow tests are skipped. You can run them with the `--runslow` option:

```bash
pytest --runslow
```

## Usage

The following example determines the coexisting phases of a binary mixture with Flory-Huggins free energy:

```python
import flory

num_comp = 2                    # Set number of components
chis = [[0, 4.0], [4.0, 0]]     # Set the \chi matrix
phi_means = [0.5, 0.5]          # Set the average volume fractions

# obtain coexisting phases
phases = flory.find_coexisting_phases(num_comp, chis, phi_means)
```

It is equivalent to a more advanced example:

```python
import flory

num_comp = 2                    # Set number of components
chis = [[0, 4.0], [4.0, 0]]     # Set the \chi matrix
phi_means = [0.5, 0.5]          # Set the average volume fractions

# create a free energy
fh = flory.FloryHuggins(num_comp, chis)
# create a ensemble
ensemble = flory.CanonicalEnsemble(num_comp, phi_means)
# construct a finder from interaction, entropy and ensemble
finder = flory.CoexistingPhasesFinder(fh.interaction, fh.entropy, ensemble)
# obtain phases by clustering compartments 
phases = finder.run().get_clusters()
```

The free energy instance provides more tools for analysis, such as:

```python
# calculate the chemical potentials of the coexisting phases
mus = fh.chemical_potentials(phases.fractions)
```

## More information

* See examples in [examples folder](https://github.com/qiangyicheng/flory/tree/main/examples)
* [Full documentation on readthedocs](https://flory.readthedocs.io/)

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "flory",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "physics, phase-separation, free-energy",
    "author": null,
    "author_email": "Yicheng Qiang <yicheng.qiang@ds.mpg.de>",
    "download_url": "https://files.pythonhosted.org/packages/6a/d1/c795e5555ef55d770e0f40ffeccd12955b5614dfda3bd09c862f18db41bd/flory-0.3.0.tar.gz",
    "platform": null,
    "description": "# flory\n\n[![Tests](https://github.com/qiangyicheng/flory/actions/workflows/python-package.yml/badge.svg)](https://github.com/qiangyicheng/flory/actions/workflows/python-package.yml)\n[![Codecov](https://codecov.io/github/qiangyicheng/flory/graph/badge.svg?token=YF3K9ST8XQ)](https://codecov.io/github/qiangyicheng/flory)\n[![Documentation Status](https://readthedocs.org/projects/flory/badge/?version=latest)](https://flory.readthedocs.io/en/latest/?badge=latest)\n[![PyPI version](https://badge.fury.io/py/flory.svg)](https://badge.fury.io/py/flory)\n[![Conda Version](https://img.shields.io/conda/vn/conda-forge/flory.svg)](https://anaconda.org/conda-forge/flory)\n\n`flory` is a Python package for analyzing field theories of multicomponent mixtures.\nIn particular, the package provides routines to determine coexisting states numerically, which is a challenging problem since the thermodynamic coexistence conditions are many coupled non-linear equations.\n`flory` supports finding coexisting phases with an arbitrary number of components.\nThe associated average free energy density of the system reads\n\n$$\\bar{f}({N_\\mathrm{P}}, \\{J_p\\}, \\{\\phi_{p,i}\\}) = \\sum_{p=1}^{{N_\\mathrm{P}}} J_p f(\\{\\phi_{p,i}\\}) ,$$\n\nwhere $N_\\mathrm{C}$ is the number of components, $N_\\mathrm{P}$ is the number of phases, $J_p$ is the fraction of the system volume occupied by phase $p$, and $\\phi_{p,i}$ is the volume fraction of component $i$ in phase $p$.\n\n`flory` supports different forms of interaction, entropy, ensemble, and constraints to describe the free energy of phases.\nFor example, with the commonly used Flory-Huggins free energy, the free energy density of each homogeneous phase reads\n\n$$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 ,$$\n\nwhere $\\chi_{ij}$ is the Flory-Huggins interaction parameter between component $i$ and $j$, and $l_i$ is the relative molecular size of component $i$.\nGiven an 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.\n\n## Installation\n\n`flory` is available on `pypi`, so you should be able to install it through `pip`:\n\n```bash\npip install flory\n```\n\nAs an alternative, you can install `flory` through [conda](https://docs.conda.io/en/latest/) using the [conda-forge](https://conda-forge.org/) channel:\n\n```bash\nconda install -c conda-forge flory\n```\n\n### Optional dependencies\n\nBy default, only the minimal set of dependencies of `flory` package will be installed. To install all dependencies, run:\n\n```bash\npip install 'flory[dev]'\n```\n\nYou can also select the optional dependencies, such as `example`, `test` or `doc`. For example, you can install the package with the optional dependencies only for tests:\n\n```bash\npip install 'flory[test]'\n```\n\nIf you are using conda, consider install the optional dependencies directly:\n\n```bash\nconda install -c conda-forge --file https://raw.githubusercontent.com/qiangyicheng/flory/main/examples/requirements.txt\nconda install -c conda-forge --file https://raw.githubusercontent.com/qiangyicheng/flory/main/tests/requirements.txt\nconda install -c conda-forge --file https://raw.githubusercontent.com/qiangyicheng/flory/main/docs/requirements.txt\n```\n\n### Test installation\n\nIf the optional dependencies for tests are installed, you can run tests in root directory of the package with `pytest`. By default, some slow tests are skipped. You can run them with the `--runslow` option:\n\n```bash\npytest --runslow\n```\n\n## Usage\n\nThe following example determines the coexisting phases of a binary mixture with Flory-Huggins free energy:\n\n```python\nimport flory\n\nnum_comp = 2                    # Set number of components\nchis = [[0, 4.0], [4.0, 0]]     # Set the \\chi matrix\nphi_means = [0.5, 0.5]          # Set the average volume fractions\n\n# obtain coexisting phases\nphases = flory.find_coexisting_phases(num_comp, chis, phi_means)\n```\n\nIt is equivalent to a more advanced example:\n\n```python\nimport flory\n\nnum_comp = 2                    # Set number of components\nchis = [[0, 4.0], [4.0, 0]]     # Set the \\chi matrix\nphi_means = [0.5, 0.5]          # Set the average volume fractions\n\n# create a free energy\nfh = flory.FloryHuggins(num_comp, chis)\n# create a ensemble\nensemble = flory.CanonicalEnsemble(num_comp, phi_means)\n# construct a finder from interaction, entropy and ensemble\nfinder = flory.CoexistingPhasesFinder(fh.interaction, fh.entropy, ensemble)\n# obtain phases by clustering compartments \nphases = finder.run().get_clusters()\n```\n\nThe free energy instance provides more tools for analysis, such as:\n\n```python\n# calculate the chemical potentials of the coexisting phases\nmus = fh.chemical_potentials(phases.fractions)\n```\n\n## More information\n\n* See examples in [examples folder](https://github.com/qiangyicheng/flory/tree/main/examples)\n* [Full documentation on readthedocs](https://flory.readthedocs.io/)\n",
    "bugtrack_url": null,
    "license": "MIT License",
    "summary": "Python package for finding coexisting phases in multicomponent mixtures",
    "version": "0.3.0",
    "project_urls": {
        "documentation": "https://flory.readthedocs.io",
        "homepage": "https://github.com/qiangyicheng/flory",
        "repository": "https://github.com/qiangyicheng/flory"
    },
    "split_keywords": [
        "physics",
        " phase-separation",
        " free-energy"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "8167e66c17b8fb74e9f9a1f54cc9952d4aa3901d59d0e009ab867be5de97f198",
                "md5": "c5858268d2b17e64e485b5fbdee8b0d4",
                "sha256": "8a1e306b8fca10a930f874c674ee4feae39798268744296a63569b3d67b10970"
            },
            "downloads": -1,
            "filename": "flory-0.3.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c5858268d2b17e64e485b5fbdee8b0d4",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 55566,
            "upload_time": "2025-02-11T16:08:45",
            "upload_time_iso_8601": "2025-02-11T16:08:45.717368Z",
            "url": "https://files.pythonhosted.org/packages/81/67/e66c17b8fb74e9f9a1f54cc9952d4aa3901d59d0e009ab867be5de97f198/flory-0.3.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "6ad1c795e5555ef55d770e0f40ffeccd12955b5614dfda3bd09c862f18db41bd",
                "md5": "dd22b4ad5d7ca866d7a7e00a1d3667b4",
                "sha256": "f2907d70a9f87e969eaec70919a0f53ba2b9b547b0234075d35bf34c87b3eb7f"
            },
            "downloads": -1,
            "filename": "flory-0.3.0.tar.gz",
            "has_sig": false,
            "md5_digest": "dd22b4ad5d7ca866d7a7e00a1d3667b4",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 139738,
            "upload_time": "2025-02-11T16:08:48",
            "upload_time_iso_8601": "2025-02-11T16:08:48.481764Z",
            "url": "https://files.pythonhosted.org/packages/6a/d1/c795e5555ef55d770e0f40ffeccd12955b5614dfda3bd09c862f18db41bd/flory-0.3.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-11 16:08:48",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "qiangyicheng",
    "github_project": "flory",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "numba",
            "specs": [
                [
                    ">=",
                    "0.57"
                ]
            ]
        },
        {
            "name": "numpy",
            "specs": [
                [
                    ">=",
                    "1.22"
                ]
            ]
        },
        {
            "name": "scipy",
            "specs": [
                [
                    ">=",
                    "1.7"
                ]
            ]
        },
        {
            "name": "tqdm",
            "specs": [
                [
                    ">=",
                    "4.60"
                ]
            ]
        }
    ],
    "lcname": "flory"
}
        
Elapsed time: 7.85189s