flory.interaction.base

Module for a general interaction energy of mixture.

Classes

`InteractionBase`	Base class for a general interaction energy of mixture.
`InteractionBaseCompiled`	Abstract base class for a general compiled interaction.

class InteractionBase(num_comp)[source]

Bases: object

Base class for a general interaction energy of mixture.

The class InteractionBase is designed to use number of components \(N_\mathrm{C}\) since this is the more physically comprehensive way to describe a mixture, even though there might be redundancies in such definition. For example, in a incompressible canonical mixture of polydispersed components, the system can be uniquely described by volume fractions of features, where one feature can contain multiple components with different molecule sizes. In such cases the interaction be expressed by the interaction between features, giving significant simplification of the numerics. In other words, there exists degeneracy of components. However, the class InteractionBase does not include this directly. Instead, such system-specific things are considered by the compiled interaction classes, which should only be aware of the feature-based description. see FloryHugginsInteractionCompiled for an example.

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

Public Methods:

compiled(**kwargs_full)

Make a compiled interaction instance for CoexistingPhasesFinder.

Private Methods:

`_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(**kwargs)[source]

Implementation of creating a compiled interaction instance (Interface).

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

Return type:: InteractionBaseCompiled

_energy_impl(phis)[source]

Implementation of calculating interaction energy \(f_\mathrm{interaction}\) (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{interaction}/\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{interaction}/\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 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 InteractionBaseCompiled[source]

Bases: object

Abstract base class for a general compiled interaction.

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 InteractionBaseCompiled is in general stateless. In other words, the compiled interaction instance never managers its own data. Note that the methods may change the input arrays inplace to avoid creating them each time.

Public Data Attributes:

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.

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 | ndarray