flory.constraint.linear_global

Module for linear global constraint.

Classes

LinearGlobalConstraint	Class for linear global constraints.
LinearGlobalConstraintCompiled	Compiled class for linear global constraint.

class LinearGlobalConstraint(num_feat, Cs, Ts)

Bases: ConstraintBase

Class for linear global constraints.

The linear global constraints require that

\[\sum_r C_{\alpha,r} \sum_m J_m \phi_r^{(m)} = T_\alpha \sum_m J_m,\]

where \(\alpha\) is the index of constraint.

Parameters:

• num_feat (int) – Number of features \(N_\mathrm{S}\).

• Cs (ndarray) – 2D array with the size of \(N_\mathrm{A} \times N_\mathrm{S}\), containing coefficients of features for linear constraints. Note that both number of features \(N_\mathrm{S}\) and number of constraints \(N_\mathrm{A}\) are inferred from this parameter.

• Ts (ndarray) – 1D vector with the size of \(N_\mathrm{A}\), containing the targets of the constraints.

Public Data Attributes:

Cs	Coefficients of features for linear constraints \(C_{\alpha,r}\).
Ts	Targets of features for linear constraints \(T_\alpha\).

Public Methods:

Inherited from ConstraintBase:

compiled(**kwargs_full)

Make a compiled constraint instance for CoexistingPhasesFinder.

Private Methods:

_compiled_impl([...])

Implementation of creating a compiled constraint instance.

Inherited from ConstraintBase:

_compiled_impl(**kwargs)

Implementation of creating a compiled constraint instance (Interface).

---

property Cs: ndarray

Coefficients of features for linear constraints \(C_{\alpha,r}\).

compiled(**kwargs_full)

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

property Ts: ndarray

Targets of features for linear constraints \(T_\alpha\).

_compiled_impl(constraint_acceptance_ratio=1.0, constraint_elasticity=1.0)

Implementation of creating a compiled constraint instance.

This method overwrites the interface _compiled_impl() in ConstraintBase.

Parameters:

• constraint_acceptance_ratio (float, default: 1.0) – Relative acceptance for the evolution of the Lagrange multipliers of the constraints. A value of 1 indicates the multipliers are evolved in the same pace as the conjugate fields \(w_r^{(m)}\).

• constraint_elasticity (float, default: 1.0) – Elasticity \(\kappa\) of the constraints.

Returns:

Instance of LinearGlobalConstraintCompiled.

Return type:

LinearGlobalConstraintCompiled

class LinearGlobalConstraintCompiled(Cs, Ts, acceptance_ratio, elasticity)

Bases: ConstraintBaseCompiled

Compiled class for linear global constraint.

Linear global constraint requires that the certain linear combination of feature average volume fractions \(\bar{\phi}_r\) are constant,

\[\sum_r C_{\alpha,r} \sum_m J_m \phi_r^{(m)} = T_\alpha \sum_m J_m,\]

where \(\alpha\) is the index of constraint. This effectively means an additional term in the free energy,

\[f_\mathrm{constraint} = \sum_\alpha^{N_\mathrm{A}} \xi_\alpha \sum_m^{M} J_m \left(\sum_r C_{\alpha,r} \phi_r^{(m)} - T_\alpha\right).\]

However, such form usually suffers from numerical instability since the Lagrange multiplier only delivers good guidance when the constraint is almost satisfied. We thus extend the term further into,

\[f_\mathrm{constraint} = \sum_\alpha^{N_\mathrm{A}} \xi_\alpha \sum_m^{M} J_m \left(\sum_r C_{\alpha,r} \phi_r^{(m)} - T_\alpha\right) + \sum_\alpha^{N_\mathrm{A}} \kappa \left[ \sum_m^{M} J_m \left(\sum_r C_{\alpha,r} \phi_r^{(m)} - T_\alpha\right) \right]^2\]

where we term \(\kappa\) as the elasticity of constraints. Note that when the constraints are satisfied, these additional terms vanish.

Parameters:

• Cs (ndarray) – 2D array with the size of \(N_\mathrm{A} \times N_\mathrm{S}\), containing coefficients of features for linear constraints. Note that both number of features \(N_\mathrm{S}\) and number of constraints \(N_\mathrm{A}\) are inferred from this parameter.

• Ts (ndarray) – 1D vector with the size of \(N_\mathrm{A}\), containing the targets of the constraints.

• acceptance_ratio (float) – The relative acceptance during evolve().

• elasticity (float) – The additional elastic constant to guide when the Lagrange multiplier is inefficient.

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.

Inherited from ConstraintBaseCompiled:

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.

Inherited from ConstraintBaseCompiled:

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)

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)

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)

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