flory.interaction.flory_huggins

Module for Flory-Huggins interaction energy of mixture.

Classes

`FloryHugginsInteraction`	Class for Flory-Huggins interaction energy of mixture.
`FloryHugginsInteractionBase`	Base Class for Flory-Huggins interaction energy of mixture.
`FloryHugginsInteractionCompiled`	Compiled class for Flory-Huggins interaction energy.

class FloryHugginsInteraction(num_comp, chis)[source]

Bases: FloryHugginsInteractionBase

Class for Flory-Huggins interaction energy of mixture.

The particular form of interaction energy density reads

\[f_\mathrm{interaction}(\{\phi_i\}) = \sum_{i,j=1}^{N_\mathrm{C}} \frac{\chi_{ij}}{2} \phi_i\phi_j\]

where \(\phi_i\) is the fraction of component \(i\).

Parameters:

num_comp¶ (int) – Number of components \(N_\mathrm{C}\).
chis¶ (ndarray | float) – The Flory-Huggins interaction matrix of components \(\chi_{ij}\).

Public Data Attributes:

`chis`	The Flory-Huggins interaction matrix of components \(\chi_{ij}\).
`independent_entries`	Entries of the upper triangle of the \(\chi_{ij}\)

Public Methods:

`from_uniform`(num_comp, chi, *[, ...])	Create Flory-Huggins interaction with uniform \(\chi_{ij}\) matrix.
`from_random_normal`(num_comp[, chi_mean, ...])	Create Flory-Huggins interaction with random \(\chi_{ij}\) matrix.
`set_uniform_chis`(chi, *[, vanishing_diagonal])	Set Flory-Huggins interaction with uniform \(\chi_{ij}\) matrix.
`set_random_chis`([chi_mean, chi_std, ...])	Set Flory-Huggins interaction with random \(\chi_{ij}\) matrix.

Inherited from InteractionBase:

compiled(**kwargs_full)

Make a compiled interaction instance for CoexistingPhasesFinder.

Private Methods:

_compiled_impl(*[, additional_chis_shift])

Implementation of creating a compiled interaction instance.

Inherited from FloryHugginsInteractionBase:

Inherited from InteractionBase:

`_compiled_impl`(**kwargs)	Implementation of creating a compiled interaction instance (Interface).
`_energy_impl`(phis)	Implementation of calculating interaction energy \(f_\mathrm{interaction}\) (Interface).
`_jacobian_impl`(phis)	Implementation of calculating Jacobian \(\partial f_\mathrm{interaction}/\partial \phi_i\) (Interface).
`_hessian_impl`(phis)	Implementation of calculating Hessian \(\partial^2 f_\mathrm{interaction}/\partial \phi_i^2\) (Interface).

property chis: ndarray: The Flory-Huggins interaction matrix of components \(\chi_{ij}\).

property independent_entries: ndarray: Entries of the upper triangle of the \(\chi_{ij}\)

classmethod from_uniform(num_comp, chi, *, vanishing_diagonal=True)[source]

Create Flory-Huggins interaction with uniform \(\chi_{ij}\) matrix.

Parameters:

num_comp¶ (int) – Number of components \(N_\mathrm{C}\).
chi¶ (float) – The value of all non-zero values in the interaction matrix \(\chi{i \ne j}\)
vanishing_diagonal¶ (bool, default: True) – Whether the diagonal elements of the \(\chi_{ij}\) matrix are set to be zero.

classmethod from_random_normal(num_comp, chi_mean=0, chi_std=1, *, vanishing_diagonal=True, rng=None)[source]

Create Flory-Huggins interaction with random \(\chi_{ij}\) matrix.

Parameters:

num_comp¶ (int) – Number of components \(N_\mathrm{C}\).
chi_mean¶ (float, default: 0) – Mean interaction \(\bar{\chi}\).
chi_std¶ (float, default: 1) – Standard deviation of the interactions \(\sigma_{\chi}\).
vanishing_diagonal¶ (bool, default: True) – Whether the diagonal elements of the \(\chi_{ij}\) matrix are set to be zero.
rng¶ (Generator | None, default: None) – The random number generator.

set_uniform_chis(chi, *, vanishing_diagonal=True)[source]

Set Flory-Huggins interaction with uniform \(\chi_{ij}\) matrix.

Parameters:

chi¶ (float) – The value of all non-zero values in the interaction matrix \(\chi{i \ne j}\)
vanishing_diagonal¶ (bool, default: True) – Whether the diagonal elements of the \(\chi_{ij}\) matrix are set to be zero.

set_random_chis(chi_mean=0, chi_std=1, *, vanishing_diagonal=True, rng=None)[source]

Set Flory-Huggins interaction with random \(\chi_{ij}\) matrix.

Parameters:

chi_mean¶ (float, default: 0) – Mean interaction \(\bar{\chi}\).
chi_std¶ (float, default: 1) – Standard deviation of the interactions \(\sigma_{\chi}\).
vanishing_diagonal¶ (bool, default: True) – Whether the diagonal elements of the \(\chi_{ij}\) matrix are set to be zero.
rng¶ (default: None) – The random number generator.

_compiled_impl(*, additional_chis_shift=1.0)[source]

Implementation of creating a compiled interaction instance.

This method overwrites the interface _compiled_impl() in InteractionBase.

Parameters:: additional_chis_shift¶ (float, default: 1.0) – Shift of the entire chis matrix to improve the convergence by evolving towards incompressible system faster. This value should be larger than 0. This value only affects the numerics, not the actual physical system. 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.
Returns:: Instance of FloryHugginsInteractionCompiled.
Return type:: FloryHugginsInteractionCompiled

_energy_impl(phis)

Implementation of calculating interaction energy.

This method overwrites the interface _energy_impl() in InteractionBase.

Parameters:: phis¶ (ndarray) – The volume fractions of the phase(s) \(\phi_{p,i}\). if multiple phases are included, the index of the components must be the last dimension.
Returns:: The interaction energy density
Return type:: ndarray

_hessian_impl(phis)

Implementation of calculating Hessian \(\partial^2 f_\mathrm{interaction}/\partial \phi_i^2\).

This method overwrites the interface _hessian_impl() in InteractionBase.

Parameters:: phis¶ (ndarray) – The volume fractions of the phase(s) \(\phi_{p,i}\). if multiple phases are included, the index of the components must be the last dimension.
Returns:: The full Hessian
Return type:: ndarray

_jacobian_impl(phis)

Implementation of calculating Jacobian \(\partial f_\mathrm{interaction}/\partial \phi_i\).

This method overwrites the interface _jacobian_impl() in InteractionBase.

Parameters:: phis¶ (ndarray) – The volume fractions of the phase(s) \(\phi_{p,i}\). if multiple phases are included, the index of the components must be the last dimension.
Returns:: The full Jacobian
Return type:: ndarray

compiled(**kwargs_full)

Make a compiled interaction instance for CoexistingPhasesFinder.

This function requires the implementation of _compiled_impl(). The interaction instance is a compiled class, which must implement a list of methods or properties. See InteractionBaseCompiled for the list and the detailed information. See also FloryHugginsInteractionCompiled for an example. Note that different from the class InteractionBase itself, the returned compiled class use the feature-based description, and can consider the degeneracy of components.

Parameters:: kwargs_full¶ – The keyword arguments for _compiled_impl() but allowing redundant arguments.
Returns:: The compiler interaction instance.
Return type:: InteractionBaseCompiled

class FloryHugginsInteractionBase(num_comp, chis)[source]

Bases: InteractionBase

Base Class for Flory-Huggins interaction energy of mixture.

The particular form of interaction energy density reads

\[f_\mathrm{interaction}(\{\phi_i\}) = \sum_{i,j=1}^{N_\mathrm{C}} \frac{\chi_{ij}}{2} \phi_i\phi_j\]

where \(\phi_i\) is the fraction of component \(i\). This class only implements the common methods of all Flory-Huggins interaction. Note that _compiled_impl() is not implemented.

Parameters:

num_comp¶ (int) – Number of components \(N_\mathrm{C}\).
chis¶ (ndarray | float) – The Flory-Huggins interaction matrix of components \(\chi_{ij}\).

Public Methods:

Inherited from InteractionBase:

compiled(**kwargs_full)

Make a compiled interaction instance for CoexistingPhasesFinder.

Private Methods:

`_compiled_impl`(*[, additional_chis_shift])	Implementation of creating a compiled interaction instance.
`_energy_impl`(phis)	Implementation of calculating interaction energy.
`_jacobian_impl`(phis)	Implementation of calculating Jacobian \(\partial f_\mathrm{interaction}/\partial \phi_i\).
`_hessian_impl`(phis)	Implementation of calculating Hessian \(\partial^2 f_\mathrm{interaction}/\partial \phi_i^2\).

Inherited from InteractionBase:

`_compiled_impl`(**kwargs)	Implementation of creating a compiled interaction instance (Interface).
`_energy_impl`(phis)	Implementation of calculating interaction energy \(f_\mathrm{interaction}\) (Interface).
`_jacobian_impl`(phis)	Implementation of calculating Jacobian \(\partial f_\mathrm{interaction}/\partial \phi_i\) (Interface).
`_hessian_impl`(phis)	Implementation of calculating Hessian \(\partial^2 f_\mathrm{interaction}/\partial \phi_i^2\) (Interface).

_compiled_impl(*, additional_chis_shift=1.0)[source]

Implementation of creating a compiled interaction instance.

This method overwrites the interface _compiled_impl() in InteractionBase.

Parameters:: additional_chis_shift¶ (float, default: 1.0) – Shift of the entire chis matrix to improve the convergence by evolving towards incompressible system faster. This value should be larger than 0. This value only affects the numerics, not the actual physical system. 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.
Returns:: Instance of FloryHugginsInteractionCompiled.
Return type:: FloryHugginsInteractionCompiled

_energy_impl(phis)[source]

Implementation of calculating interaction energy.

This method overwrites the interface _energy_impl() in InteractionBase.

Parameters:: phis¶ (ndarray) – The volume fractions of the phase(s) \(\phi_{p,i}\). if multiple phases are included, the index of the components must be the last dimension.
Returns:: The interaction energy density
Return type:: ndarray

_jacobian_impl(phis)[source]

Implementation of calculating Jacobian \(\partial f_\mathrm{interaction}/\partial \phi_i\).

This method overwrites the interface _jacobian_impl() in InteractionBase.

Parameters:: phis¶ (ndarray) – The volume fractions of the phase(s) \(\phi_{p,i}\). if multiple phases are included, the index of the components must be the last dimension.
Returns:: The full Jacobian
Return type:: ndarray

_hessian_impl(phis)[source]

Implementation of calculating Hessian \(\partial^2 f_\mathrm{interaction}/\partial \phi_i^2\).

This method overwrites the interface _hessian_impl() in InteractionBase.

Parameters:: phis¶ (ndarray) – The volume fractions of the phase(s) \(\phi_{p,i}\). if multiple phases are included, the index of the components must be the last dimension.
Returns:: The full Hessian
Return type:: ndarray

compiled(**kwargs_full)

Make a compiled interaction instance for CoexistingPhasesFinder.

This function requires the implementation of _compiled_impl(). The interaction instance is a compiled class, which must implement a list of methods or properties. See InteractionBaseCompiled for the list and the detailed information. See also FloryHugginsInteractionCompiled for an example. Note that different from the class InteractionBase itself, the returned compiled class use the feature-based description, and can consider the degeneracy of components.

Parameters:: kwargs_full¶ – The keyword arguments for _compiled_impl() but allowing redundant arguments.
Returns:: The compiler interaction instance.
Return type:: InteractionBaseCompiled

class FloryHugginsInteractionCompiled(chis, chis_shift)[source]

Bases: InteractionBaseCompiled

Compiled class for Flory-Huggins interaction energy.

Flory-Huggins interaction is the second-ordered interaction, whose energy reads,

\[f(\{\phi_r\}) = \sum_{r,s=1}^{N_\mathrm{S}} \frac{\chi_{rs}}{2} \phi_r\phi_s .\]

Note that here we use describe the system by features.

Parameters:

chis¶ (ndarray) – 2D array with the size of \(N_\mathrm{S} \times N_\mathrm{S}\), containing the Flory-Huggins interaction matrix \(\chi_{rs}\) for features. The number of features \(N_\mathrm{S}\) is inferred from this matrix.
chis_shift¶ (float) – The shift of entire Flory-Huggins matrix for the incomp_coef().

Public Data Attributes:

num_feat

Number of features \(N_\mathrm{S}\).

Inherited from InteractionBaseCompiled:

num_feat

Number of features \(N_\mathrm{S}\).

Public Methods:

`volume_derivative`(potential, phis_feat)	Calculate the volume derivatives of interaction energy.
`potential`(phis_feat)	Calculate part of \(w_r^{(m)}\) from interaction.
`incomp_coef`(phis_feat)	Calculate the coefficient for incompressibility.

Inherited from InteractionBaseCompiled:

`volume_derivative`(potential, phis_feat)	Calculate the volume derivatives of interaction energy.
`potential`(phis_feat)	Calculate part of \(w_r^{(m)}\) from interaction.
`incomp_coef`(phis_feat)	Calculate the coefficient for incompressibility.

property num_feat: int: Number of features \(N_\mathrm{S}\).

volume_derivative(potential, phis_feat)[source]

Calculate the volume derivatives of interaction energy.

This method calculates the partial derivative of interaction part of the free energy with respect to the volumes of the compartments \(\partial f_\mathrm{interaction}/\partial J_m\). In most of the cases, this is just the interaction energy density in all compartments.

Parameters:

potential¶ (ndarray) – Constant. 2D array with the size of \(N_\mathrm{S} \times N_\mathrm{M}\), containing the part of the field \(w_r^{(m)}\) contributed by the interaction. Usually this is the returned value of potential(). This parameter is passed in since usually the calculation of interaction energy density can be accelerated by directly using the potential.
phis_feat¶ (ndarray) – Constant. The 2D array with the size of \(N_\mathrm{S} \times N_\mathrm{M}\), containing the volume fractions of features \(\phi_r^{(m)}\).

Returns:

The volume derivatives.

Return type:

ndarray

potential(phis_feat)[source]

Calculate part of \(w_r^{(m)}\) from interaction.

This method calculates the part of mean field \(w_r^{(m)}\) contributed by the interaction. Usually this is just the Jacobian of the interaction energy with respect to the volume fractions of features in each compartment. This method should return the result directly.

Parameters:: phis_feat¶ (ndarray) – Constant. The 2D array with the size of \(N_\mathrm{S} \times N_\mathrm{M}\), containing the volume fractions of features \(\phi_r^{(m)}\).
Returns:: Part of \(w_r^{(m)}\) contributed by the interaction.
Return type:: ndarray

incomp_coef(phis_feat)[source]

Calculate the coefficient for incompressibility.

This method calculates the coefficient for incompressibility during iteration. This coefficient is derived heuristically. The most common way is to partially make use of the incompressibility in the expression of potential(), and then determine the changes of potential() after applying incompressibility. The coefficient can be compartment-dependent. This method should return the result directly.

Parameters:: phis_feat¶ (ndarray) – Constant. The 2D array with the size of \(N_\mathrm{S} \times N_\mathrm{M}\), containing the volume fractions of features \(\phi_r^{(m)}\).
Returns:: The coefficient for incompressibility.
Return type:: float