flory.mcmp._finder_impl

The implementation details of the core algorithm for finder.

_finder_impl contains the implementation details of the module finder. The main components of the module is the function multicomponent_self_consistent_metastep(), which implements the self consistent iterations for minimizing the extended free energy functional, and the function get_clusters(), which finds the unique phases.

In this module, arguments of functions are always marked by Constant, Output or Mutable, to indicate whether the arguments will be kept invariant, directly overwritten, or reused.

Functions

`count_valid_compartments`	Count valid compartments.
`make_valid_compartment_masks`	Create masks for valid compartments.
`multicomponent_self_consistent_metastep`	The core algorithm of finding coexisting states of multicomponent systems with self-consistent iterations.
`revive_compartments_by_copy`	Revive dead compartments by copying living ones.
`revive_compartments_by_random`	Revive dead compartments randomly.

count_valid_compartments(Js, threshold)[source]

Count valid compartments.

Count how many entries in Js are larger than threshold.

Parameters:

Js¶ (ndarray) – Constant. The 1D array with the size of \(N_\mathrm{M}\), containing the relative volumes of compartments \(J_m\).
threshold¶ (float) – Constant. The threshold below which the corresponding compartment is considered dead.

Returns:

Number of entries in Js larger than threshold.

Return type:

int

make_valid_compartment_masks(Js, threshold)[source]

Create masks for valid compartments.

Create masks for entries in Js are larger than threshold. Value of 1.0 or 0.0 indicates a valid or invalid mask, respectively.

Parameters:

Js¶ (ndarray) – Constant. The 1D array with the size of \(N_\mathrm{M}\), containing the relative volumes of compartments \(J_m\).
threshold¶ (float) – Constant. The threshold below which the corresponding compartment is considered dead.

Returns:

1D array with the size of \(N_\mathrm{M}\), containing masks of entries in Js larger than threshold.

Return type:

ndarray

multicomponent_self_consistent_metastep(interaction, entropy, ensemble, constraints, *, omegas, Js, phis_comp, phis_feat, steps_inner, acceptance_Js, Js_step_upper_bound, acceptance_omega, kill_threshold, revive_tries, revive_scaler, rng)[source]

The core algorithm of finding coexisting states of multicomponent systems with self-consistent iterations.

Parameters:

interaction¶ (InteractionBaseCompiled) – Constant. The compiled interaction instance. See InteractionBaseCompiled for more information.
entropy¶ (EntropyBaseCompiled) – Constant. The compiled entropy instance. See EntropyBaseCompiled for more information.
ensemble¶ (EnsembleBaseCompiled) – Constant. The compiled ensemble instance. See EnsembleBaseCompiled for more information.
constraints¶ (tuple[ConstraintBaseCompiled]) – Constant. The tuple of compiled constraint instance. Note that constraint instances are usually stateful, therefore the internal states of constraints are actually mutable. See constraintBaseCompiled for more information.
omegas¶ (ndarray) – Mutable. 2D array with size of \(N_\mathrm{S} \times N_\mathrm{M}\), containing the conjugate field \(w_r^{(m)}\) of features. Note that this field is both used as input and output. Note again that this function DO NOT initialize omegas, it should be initialized externally, and usually a random initialization will be a reasonable choice.
Js¶ (ndarray) – Mutable. 1D array with size of \(N_\mathrm{M}\), containing the relative volumes of the compartments \(J_m\). The average value of Js will and should be unity, in order to keep the values invariant for different \(N_\mathrm{M}\). Note that this field is both used as input and output. An all-one array is usually a nice initialization, unless resume of a previous run is intended.
phis_comp¶ (ndarray) – Output. 2D array with size of \(N_\mathrm{C} \times N_\mathrm{M}\), containing the volume fractions of components \(\phi_i^{(m)}\).
phis_feat¶ (ndarray) – Output. 2D array with size of \(N_\mathrm{S} \times N_\mathrm{M}\), containing the volume fractions of features \(\phi_r^{(m)}\).
steps_inner¶ (int) – Constant. Number of steps in current routine. Within these steps, convergence is not checked and no output will be generated.
acceptance_Js¶ (float) – Constant. The acceptance of Js (the relative compartment size \(J_m\)). This value determines the amount of changes accepted in each step for the \(J_m\) field. Typically this value can take the order of \(10^{-3}\), or smaller when the system becomes larger or stiffer.
Js_step_upper_bound¶ (float) – Constant. The maximum change of Js (the relative compartment size \(J_m\)) per step. This value is designed to reduce the risk that a the volume of a compartment changes too fast before it develops meaningful composition. If the intended change is larger this value, all the changes will be scaled down to guarantee that the maximum changes do not exceed this value. Typically this value can take the order of \(10^{-3}\), or smaller when the system becomes larger or stiffer.
acceptance_omega¶ (float) – Constant. The acceptance of omegas`(the conjugate fields :math:`w_r^{(m)}). This value determines the amount of changes accepted in each step for the \(w_r^{(m)}\) field. Note that if the iteration of \(J_m\) is scaled down due to parameter Js_step_upper_bound, the iteration of \(w_r^{(m)}\) fields will be scaled down simultaneously. Note that this value also scales the evolution of the internal states (Lagrange multipliers) of the constraints. See the documentation of actual constraint class for additional acceptances for constraints. Typically this value can take the order of \(10^{-2}\), or smaller when the system becomes larger or stiffer.
kill_threshold¶ (float) – Constant. The threshold of the \(J_m\) for a compartment to be considered dead and killed afterwards. Should be not less than 0. In each iteration step, the \(J_m\) array will be checked, for each element smaller than this parameter, the corresponding compartment will be killed and 0 will be assigned to the internal mask. The dead compartment may be revived, depending on whether reviving is allowed or whether the number of the revive tries has been exhausted.
revive_tries¶ (int) – Constant. Number of tries left to revive the dead compartment. 0 or negative value indicates no reviving. When this value is exhausted, i.e. the number of revive in current function call exceeds this value, the revive will be turned off. Note that this function does not decrease this value, but returns the number of revives that have happened after completion.
revive_scaler¶ (float) – Constant. The scaling factor for the conjugate fields \(w_r^{(m)}\) when a dead compartment is revived. This value determines the range of the random conjugate field generated by the algorithm. Typically 1.0 or some value slightly larger will be a reasonable choice. See revive_compartments_by_random() for more information.
rng¶ (Generator) – Mutable. random number generator for reviving.

Returns:

[0] – Max absolute incompressibility.
[1] – Max absolute conjugate field error.
[2] – Max absolute relative volumes error.
[3] – Max absolute constraints error.
[4] – Number of revives.
[5] – Whether no phase is killed in the last step.

Return type:

tuple[float, float, float, float, int, bool]

revive_compartments_by_copy(Js, targets, threshold, rng)[source]

Revive dead compartments by copying living ones.

Revive compartments whose relative volume (element of Js) is smaller than threshold. The revived values are randomly copied from other living compartments. Note that this function conserves the quantities in targets across all compartments by modifying the volumes Js accordingly.

Parameters:

Js¶ (ndarray) – Constant. The 1D array with the size of \(N_\mathrm{M}\), containing the relative volumes of compartments \(J_m\).
targets¶ (ndarray) – Mutable. 2D array with the size of \(N_* \times N_\mathrm{M}\), containing the values to be revived. The second dimension has to be the same as that of Js. Note that this is not checked.
threshold¶ (float) – Constant. The threshold below which the corresponding compartment is considered dead. For each element of Js smaller than this parameter, the corresponding compartment will be considered as dead, and its targets values will then be copied from that of a living compartment. At the same time, the corresponding elements (both the dead and the copied living one) in Js will be redistributed to ensure conservation of Js.
rng¶ (Generator) – Mutable. Random number generator for reviving.

Returns:

Number of revives

Return type:

int

revive_compartments_by_random(Js, targets, threshold, rng, scaler)[source]

Revive dead compartments randomly.

Randomly revive compartments whose relative volume (element of Js) is smaller than threshold. The revived values are randomly and uniformly sampled between the extreme values of targets across all compartments. The range can be scaled by the parameter scaler. Note that this function does not conserve the quantities in targets across all compartments, since the new values are randomly generated.

Parameters:

Js¶ (ndarray) – Constant. The 1D array with the size of \(N_\mathrm{M}\), containing the relative volumes of compartments \(J_m\).
targets¶ (ndarray) – Mutable. 2D array with the size of \(N_* \times N_\mathrm{M}\), containing the values to be revived. The second dimension has to be the same as that of Js. Note that this is not checked.
threshold¶ (float) – Constant. The threshold below which the corresponding compartment is considered dead. For each element of Js smaller than this parameter, the corresponding compartment will be considered as dead, and its targets values will then be randomly drawn between the corresponding minimum and maximum values of targets across all compartments. Corresponding Js will be set to be unity.
rng¶ (Generator) – Mutable. Random number generator for reviving.
scaler¶ (float) – Constant. The scaler for generating random new values.

Returns:

Number of dead compartments that have been revived.

Return type:

int