flory.constraint.base

Module for a general constraint.

Classes

`ConstraintBase`	Base class for a general constraint.
`ConstraintBaseCompiled`	Abstract base class for a general compiled constraint.

class ConstraintBase(num_feat)[source]

Bases: object

Base class for a general constraint.

A constraint can be either local or global. Local constraint means that it needs be satisfied in all compartments. For example, the charge balance is a local constraint. Global constraint means that it only needs to be satisfied by the mean value. For example, the volume conservation is a global constraint. Note that we expect that constraints always act on feature, in stead of components.

Parameters:: num_feat¶ (int) – Number of features \(N_\mathrm{S}\).

Public Methods:

compiled(**kwargs_full)

Make a compiled constraint instance for CoexistingPhasesFinder.

Private Methods:

_compiled_impl(**kwargs)

Implementation of creating a compiled constraint instance (Interface).

_compiled_impl(**kwargs)[source]

Implementation of creating a compiled constraint instance (Interface).

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

Return type:: ConstraintBaseCompiled

compiled(**kwargs_full)[source]

Make a compiled constraint instance for CoexistingPhasesFinder.

This function requires the implementation of _compiled_impl(). The constraint instance is a compiled class, which must implement a list of methods or properties. See ConstraintBaseCompiled for the list and the detailed information. Also see CanonicalEnsembleCompiled for an example of the implementation.

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

class ConstraintBaseCompiled[source]

Bases: object

Abstract base class for a general compiled constraint.

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. Due to the variety of constraints, a compiled class derived from ConstraintBaseCompiled is in general stateful. In other words, the compiled constraint instance must manage its own data such as the Lagrange multiplier. Besides, it can also keep other data to avoid repeating certain calculation. Therefore, the class CoexistingPhasesFinder uses the constraint instances in the manner of a prepare-access-evolve triplet.

Public Data Attributes:

`num_feat`	Number of features \(N_\mathrm{S}\).
`potential`	The potential for features generated by the constraint.
`volume_derivative`	The volume derivatives of the constraint part of entropic energy.

Public Methods:

`initialize`(num_part)	Initialize the internal data of the constraint.
`prepare`(phis_feat, Js, masks)	Prepare the constraint.
`evolve`(step, masks)	Evolve the internal state of the constraint.

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

property potential: ndarray

The potential for features generated by the constraint.

This property typically contains the Jacobian of the constraint part of the free energy with respect to the volume fractions of the features, which is an array with the size of \(N_\mathrm{S} \times N_\mathrm{M}\). Note that this property should be used after prepare() is called.

property volume_derivative: ndarray

The volume derivatives of the constraint part of entropic energy.

This property typically contains the Jacobian of the constraint part of the free energy with respect to the volumes of the compartments, which is an array with the size of \(N_\mathrm{M}\). Note that this property should be used after prepare() is called.

initialize(num_part)[source]

Initialize the internal data of the constraint.

Typically this function initialize the Lagrange multiplier according to the number of compartments.

Parameters:: num_part¶ (int) – Constant. Number of compartments \(N_\mathrm{M}\).
Return type:: None

prepare(phis_feat, Js, masks)[source]

Prepare the constraint.

This function prepares the constraint according to the volume fractions of features and the masks of the compartments. Usually this includes the calculation of potential and volume_derivative.

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)}\).
Js¶ (ndarray) – Constant. The 1D array with the size of \(N_\mathrm{M}\), containing the relative volumes of compartments \(J_m\).
masks¶ (ndarray) – Constant. The 1D array with the size of \(N_\mathrm{M}\), containing the masks to mark whether the compartment is living or not.

Return type:

None

evolve(step, masks)[source]

Evolve the internal state of the constraint.

Parameters:

step¶ (float) – Constant. The step size of the evolution.
masks¶ (ndarray) – Constant. The 1D array with the size of \(N_\mathrm{M}\), containing the masks to mark whether the compartment is living or not.

Returns:

the max absolute residue.

Return type:

float