flory.free_energy.base

Module for a general free energy of mixture.

Classes

FreeEnergyBase

Base class for a general free energy of mixture.

class FreeEnergyBase(interaction, entropy)[source]

Bases: object

Base class for a general free energy of mixture.

A free energy is constructed by an interactions energy and a entropic energy. Once the energy, Jacobian and Hessian of both interactions energy and entropic energy are implemented, class FreeEnergyBase provides methods such as the chemical potential of the components.

Parameters:

interaction¶ (InteractionBase) – The interaction energy instance.
entropy¶ (EntropyBase) – The entropic energy instance.

Public Methods:

`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:

`_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.

interaction_compiled(**kwargs_full)[source]

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

entropy_compiled(**kwargs_full)[source]

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

_energy_impl(phis)[source]

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

_jacobian_impl(phis)[source]

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

_hessian_impl(phis)[source]

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)[source]

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

check_volume_fractions(phis, axis=-1)[source]

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

free_energy_density(phis)[source]

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

jacobian(phis, index=None)[source]

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

hessian(phis, index=None)[source]

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

chemical_potentials(phis)[source]

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

exchange_chemical_potentials(phis, index)[source]

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

pressure(phis, index)[source]

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

num_unstable_modes(phis, conserved=True)[source]

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

is_stable(phis, conserved=True)[source]

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

equilibration_error(phis, order=None, axis=1)[source]

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