flory.free_energy.flory_huggins

Module for Flory-Huggins free energy. Flory-Huggins free energy is a combination of Flory-Huggins interaction energy and ideal gas entropy.

Classes

FloryHuggins

represents the free energy of a multicomponent mixture

class FloryHuggins(num_comp, chis, sizes=None)[source]

Bases: FreeEnergyBase

represents the free energy of a multicomponent mixture

The particular implementation of the free energy density reads

\[f(\{\phi_i\}) = \sum_{i=1}^{N_\mathrm{C}} \frac{\nu}{\nu_i}\phi_i \ln(\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\). All components are assumed to have the same molecular volume \(\nu\) by default and the interactions are quantified by the Flory matrix \(\chi_{ij}\). The relative molecular sizes \(l_i=\nu_i/\nu\) can be changed by setting the optional parameter sizes. Note that no implicit solvent is assumed.

Parameters:

num_comp¶ (int) – Number of components \(N_\mathrm{C}\).
chis¶ (ndarray | float) – The Flory-Huggins interaction matrix of components \(\chi_{ij}\).
sizes¶ (ndarray | None, default: None) – The relative molecule volumes \(l_i = \nu_i/\nu\) with respect to the volume of a reference molecule \(\nu\). It is treated as all-one vector by default.

Public Data Attributes:

`chis`	The Flory-Huggins interaction matrix of components \(\chi_{ij}\).
`sizes`	The relative molecule volumes \(l_i = \nu_i/\nu\).

Public Methods:

`from_uniform`(num_comp, chi, *[, sizes, ...])	Create Flory-Huggins free energy with uniform \(\chi_{ij}\) matrix.
`from_random_normal`(num_comp[, chi_mean, ...])	Create Flory-Huggins free energy with random \(\chi_{ij}\) matrix.

Inherited from FreeEnergyBase:

`interaction_compiled`(**kwargs_full)	Get the compiled instance of the interaction.
`entropy_compiled`(**kwargs_full)	Get the compiled instance of the entropy.
`check_volume_fractions`(phis[, axis])	Check whether volume fractions are valid.
`free_energy_density`(phis)	Calculate the free energy density.
`jacobian`(phis[, index])	Calculate the Jacobian with/without volume conservation.
`hessian`(phis[, index])	Calculate the Hessian with/without volume conservation.
`chemical_potentials`(phis)	Calculate original chemical potentials by unit volume.
`exchange_chemical_potentials`(phis, index)	Calculate exchange chemical potentials.
`pressure`(phis, index)	Calculate osmotic pressure of the solvent.
`num_unstable_modes`(phis[, conserved])	Count the number of unstable modes with/without volume conservation.
`is_stable`(phis[, conserved])	Determine whether the mixture is locally stable.
`equilibration_error`(phis[, order, axis])	Determine how well the phases are in balance with each other.

Private Methods:

Inherited from FreeEnergyBase:

`_energy_impl`(phis)	Implementation of calculating free energy \(f\).
`_jacobian_impl`(phis)	Implementation of calculating Jacobian \(\partial f/\partial \phi_i\).
`_hessian_impl`(phis)	Implementation of calculating Hessian \(\partial^2 f/\partial \phi_i^2\).
`_jacobian_fractions_impl`(phis)	Calculate the Inner Product of Jacobian and Fractions.

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

property sizes: ndarray: The relative molecule volumes \(l_i = \nu_i/\nu\).

_energy_impl(phis)

Implementation of calculating free energy \(f\).

This method is general, thus does not need to be overwritten. The method makes use of _energy_impl() in InteractionBase and _energy_impl() in EntropyBase. Consider define custom interaction or entropy if a custom free energy is needed.

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 free energy density.
Return type:: ndarray

_hessian_impl(phis)

Implementation of calculating Hessian \(\partial^2 f/\partial \phi_i^2\).

This method is general, thus does not need to be overwritten. The method makes use of _hessian_impl() in InteractionBase and _hessian_impl() in EntropyBase. Consider define custom interaction or entropy if a custom free energy is needed.

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_fractions_impl(phis)

Calculate the Inner Product of Jacobian and Fractions.

This function is solely designed the case when the Jacobian diverge, but its inner product with the fractions have finite limits.

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 inner product of Jacobian and fractions
Return type:: ndarray

_jacobian_impl(phis)

Implementation of calculating Jacobian \(\partial f/\partial \phi_i\).

This method is general, thus does not need to be overwritten. The method makes use of _jacobian_impl() in InteractionBase and _jacobian_impl() in EntropyBase. Consider define custom interaction or entropy if a custom free energy is needed.

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 The full Jacobian.
Return type:: ndarray

check_volume_fractions(phis, axis=-1)

Check whether volume fractions are valid.

If the shape of phis or it has non-positive values, an exception will be raised. Note that this method does not forbid volume fractions to be larger than 1.

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.
axis¶ (int, default: -1) – The axis of the index of components. By the default the last dimension of phis is considered as the index of components.

Returns:

The volume fractions phis

Return type:

ndarray

chemical_potentials(phis)

Calculate original chemical potentials by unit volume.

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 original chemical potentials.
Return type:: ndarray

entropy_compiled(**kwargs_full)

Get the compiled instance of the entropy.

Parameters:: kwargs_full¶ – The keyword arguments for method compiled() of the entropy instance but allowing redundant arguments.
Return type:: EntropyBase

equilibration_error(phis, order=None, axis=1)

Determine how well the phases are in balance with each other.

Note that this function do not check whether the coexistence of the providing phases are the equilibrium state. It only checks its necessary condition that all phases must reach chemical potential balance with each other.

Parameters:

phis¶ (ndarray) – The volume fractions of the phase(s) \(\phi_{p,i}\). Multiple phases are expected, the index of the components must be the last dimension. If only one phase is provided, the result will always be zero.
order¶ (int | None, default: None) – The order for calculating norm. See numpy.linalg.norm() for more details.
axis¶ (int | None, default: 1) – Whether to calculate error by component (axis=0), by phase (axis=1), or by both (axis=None, returns a scalar).

Returns:

The equilibration error by component, by phase or by all.

Return type:

float | ndarray

exchange_chemical_potentials(phis, index)

Calculate exchange chemical potentials.

Component index is treated as the solvent. The exchange chemical potentials is obtained by removing chemical potential of the solvent. The exchange chemical potential of the solvent is always zero and kept in the result. The nonzero values are identical to the conserved Jacobian, see jacobian() for more information.

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.
index¶ (int) – Index of the solvent component

Returns:

The exchange chemical potentials of component with respect to the solvent component.

Return type:

ndarray

free_energy_density(phis)

Calculate the free energy density.

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:: Free energy density of each phase.
Return type:: ndarray

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

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

See from_uniform() for parameter details.

hessian(phis, index=None)

Calculate the Hessian with/without volume conservation.

If parameter index is specified, the system will be considered as conserved and the volume fraction of component index is treated to be not independent. Note that different from exchange_chemical_potentials(), hessian() removed the dependent variable completely, while exchange_chemical_potentials() keeps the exchange chemical potential of the component index. Pass None to index indicates the system is not conserved.

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.
index¶ (int | None, default: None) – Index of the dependent component. By default the system is not conserved.

Returns:

The Hessian with/without volume conservation.

Return type:

ndarray

interaction_compiled(**kwargs_full)

Get the compiled instance of the interaction.

Parameters:: kwargs_full¶ – The keyword arguments for method compiled() of the interaction instance but allowing redundant arguments.
Return type:: InteractionBase

is_stable(phis, conserved=True)

Determine whether the mixture is locally stable.

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.
conserved¶ (bool, default: True) – Whether the system conserves volume. If True, the first component is considered as the dependent on when calculating the Hessian. See hessian() for more information.

Returns:

The number of negative eigenvalues of the Hessian.

Return type:

int | ndarray

jacobian(phis, index=None)

Calculate the Jacobian with/without volume conservation.

If parameter index is specified, the system will be considered as conserved and the volume fraction of component index is treated to be not independent. Note that different from exchange_chemical_potentials(), jacobian() removed the dependent variable completely, while exchange_chemical_potentials() keeps the exchange chemical potential of the component index. Pass None to index indicates the system is not conserved.

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.
index¶ (int | None, default: None) – Index of the dependent component. By default the system is not conserved.

Returns:

Jacobian of each phase with/without volume conservation.

Return type:

ndarray

num_unstable_modes(phis, conserved=True)

Count the number of unstable modes with/without volume conservation.

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.
conserved¶ (bool, default: True) – Whether the system conserves volume. If True, the first component is considered as the dependent on when calculating the Hessian. See hessian() for more information.

Returns:

The number of negative eigenvalues of the Hessian.

Return type:

int | ndarray

pressure(phis, index)

Calculate osmotic pressure of the solvent.

Component index is treated as the solvent. The osmotic pressure of the solvent is proportional to the original chemical potential of the solvent.

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.
index¶ (int) – Index of the solvent component

Returns:

The osmotic pressure of the solvent component index.

Return type:

ndarray

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

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

See from_random_normal() for parameter details.