flory.entropy.base

Module for a general entropic energy of mixture.

Classes

`EntropyBase`	Base class for a general entropic energy of mixture.
`EntropyBaseCompiled`	Abstract base class for a general compiled entropy.

class EntropyBase(num_comp)[source]

Bases: object

Base class for a general entropic energy of mixture.

Parameters:: num_comp¶ (int) – Number of components \(N_\mathrm{C}\).

Public Methods:

compiled(**kwargs_full)

Make a compiled entropy instance for CoexistingPhasesFinder.

Private Methods:

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

_compiled_impl(**kwargs)[source]

Implementation of creating a compiled entropy instance (Interface).

This interface is meant to be overridden in derived classes. See compiled() for more information on the compiled entropy instance.

Return type:: EntropyBaseCompiled

_energy_impl(phis)[source]

Implementation of calculating entropic energy \(f_\mathrm{entropy}\) (Interface).

This interface is meant to be overridden in derived classes. Multiple compositions should be allowed. This method is not necessary for the core algorithm.

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

_jacobian_impl(phis)[source]

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

This interface is meant to be overridden in derived classes. Multiple compositions should be allowed. This method is not necessary for the core algorithm.

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{entropy}/\partial \phi_i^2\) (Interface).

This interface is meant to be overridden in derived classes. Multiple compositions should be allowed. This method is not necessary for the core algorithm.

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

Make a compiled entropy instance for CoexistingPhasesFinder.

This function requires the implementation of _compiled_impl(). The entropy instance is a compiled class, which must implement a list of methods or properties. See EntropyBaseCompiled for the list and the detailed information.

Note that the compiled entropy instance acts as the bridge between the component-based description and the feature-based description of the system’s states. In contrast, compiled classes in ensemble should be only aware of component-based description, compiled classes in interaction and constraint should be only aware of feature-based description.

See IdealGasEntropyCompiled for an example.

Parameters:: kwargs_full¶ – The keyword arguments for _compiled_impl() but allowing redundant arguments.
Returns:: The compiled entropy instance.
Return type:: EntropyBaseCompiled

class EntropyBaseCompiled[source]

Bases: object

Abstract base class for a general compiled entropy.

This abstract class defines the necessary members of a compiled constraint instance. This abstract class does not inherit from abc.ABC, since the numba.experimental.jitclass() currently does not support some members of abc.ABC. A compiled class derived from EntropyBaseCompiled is in general stateless. In other words, the compiled entropy instance never managers its own data. Note that the methods may change the input arrays inplace to avoid creating them each time.

Class derived from EntropyBaseCompiled is of important and special role in the core numerical method of the package flory. In principle, many complications of multicomponent systems are expressed by the entropy instance, ranging from simple molecule sizes, polydispersity, to even copolymers. In particular, the entropy instance acts as the bridge between the component-based description and the feature-based description. So for the core algorithm, entropy instance is the only instance that is aware both descriptions.

Public Data Attributes:

`num_comp`	Number of components \(N_\mathrm{C}\).
`num_feat`	Number of features \(N_\mathrm{S}\).

Public Methods:

`partition`(phis_comp, omegas, Js)	Calculate the partition function and Boltzmann factors.
`comp_to_feat`(phis_feat, phis_comp)	Convert the fractions of components into features.
`volume_derivative`(phis_comp)	Calculate the volume derivatives of entropic energy.

property num_comp: int: Number of components \(N_\mathrm{C}\).

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

partition(phis_comp, omegas, Js)[source]

Calculate the partition function and Boltzmann factors.

This method calculates the Boltzmann factors \(p_i^{(m)}\) of the components under the mean fields omegas and stores them in phis_comp as the volume fractions of components before normalization. This method must return the single molecule partition functions of the components \(Q_i\), which is the sum of the Boltzmann factors weighted by the volumes of compartments \(J_m\) in Js. Note that omegas contains the mean fields for the features \(w_r^{(m)}\) instead of components. For example when we have polydispersity of the molecule sizes, all the polydispersed components of the same kind share the same external fields, but with different volume fractions. In such cases the number of features \(N_\mathrm{S}\) can be much smaller than number of components \(N_\mathrm{C}\). This method acts as the mapping from feature-based description of the system to the component-based description of the system. Note that this method should modify phis_comp directly.

Parameters:

phis_comp¶ (ndarray) – Output. The 2D array with the size of \(N_\mathrm{C} \times N_\mathrm{M}\), containing Boltzmann factors \(p_i^{(m)}\), namely the volume fractions of components before normalization.
omegas¶ (ndarray) – Constant. The 2D array with the size of \(N_\mathrm{S} \times N_\mathrm{M}\), containing the mean field felt by the features \(\phi_r^{(m)}\).
Js¶ (ndarray) – Constant. The 1D array with the size of \(N_\mathrm{M}\), containing the relative volumes of compartments \(J_m\).

Returns:

The single molecule partition functions of components \(Q_i\).

Return type:

ndarray

comp_to_feat(phis_feat, phis_comp)[source]

Convert the fractions of components into features.

This method converts the volume fractions of components \(\phi_i^{(m)}\) in phis_comp to the volume fractions of features \(\phi_r^{(m)}\) in phis_feat. Note that this method should modify phis_feat directly.

Parameters:

phis_feat¶ (ndarray) – Output. The 2D array with the size of \(N_\mathrm{S} \times N_\mathrm{M}\), containing the volume fractions of features \(\phi_r^{(m)}\).
phis_comp¶ (ndarray) – Constant. The 2D array with the size of \(N_\mathrm{C} \times N_\mathrm{M}\), containing the volume fractions of components \(\phi_i^{(m)}\).

Return type:

None

volume_derivative(phis_comp)[source]

Calculate the volume derivatives of entropic energy.

This method calculates the partial derivative of partition function part of the free energy with respect to the volumes of the compartments \(\partial f_\mathrm{entropy}/\partial J_m\).

In most of the cases, this is equivalent to the negative sum of the volume fractions of the components \(\phi_i^{(m)}\) divided by the relative volumes of the molecules \(l_i\). Note that this module is separated from the iteration algorithm to remove from it any explicit dependence of the molecule parameters such as \(l_i\).

Returns:: The volume derivatives.
Return type:: ndarray