flory.mcmp.finder

Module for a general finder for coexisting phases.

flory.mcmp provides the general tool for finding equilibrium multiple coexisting phases in multicomponent mixtures with defined interaction, entropy, ensemble and constraint. The finder is provided through the class CoexistingPhasesFinder, which is designed to be flexible, reusable, independent and efficient:

flexible: CoexistingPhasesFinder can be applied to different interaction, entropy, ensemble and constraint, as soon as the they implement the a minimal set of methods.
reusable: CoexistingPhasesFinder tries every possibility to avoid recreation of objects as soon as the system size is unchanged, making it ideal to be reused for different parameters.
independent: CoexistingPhasesFinder owns all the data it needs once created. Therefore multiple instances can be created and stored freely.
efficient: CoexistingPhasesFinder use numba.jit() to compile all of its core algorithms.

The usage of CoexistingPhasesFinder usually follows the creation-and-run manner for new instance, or reinitialization-and-run for existing instance. The reinitialization might be skipped in the case that the previous result in the existing instance provides good initial guess for next run, which is a typical case when constructing phase diagram.

See Examples for examples.

Classes

CoexistingPhasesFinder

Class for a general finder of coexisting phases.

class CoexistingPhasesFinder(interaction, entropy, ensemble, constraints=None, *, num_part=None, rng=None, max_steps=1000000, convergence_criterion='standard', tolerance=1e-05, interval=10000, progress=True, random_std=5.0, acceptance_Js=0.0002, acceptance_omega=0.002, Js_step_upper_bound=0.001, kill_threshold=0.0, revive_scaler=1.0, max_revive_per_compartment=16, **kwargs)[source]

Bases: object

Class for a general finder of coexisting phases.

This class is recommended when multiple instances of interaction, entropy, ensemble or constraints need to be calculated. The class will reuse all the options and the internal resources. Note that reuse the instance of this class is only possible when all the system sizes are not changed, including the number of components \(N_\mathrm{C}\), the number of features \(N_\mathrm{S}\) and the number of compartments \(N_\mathrm{M}\).

Parameters:

interaction¶ (InteractionBase) – The interaction instance that can provide a compiled interaction instance. See InteractionBase for more information.
entropy¶ (EntropyBase) – The entropy instance that can provide a compiled entropy instance. See EntropyBase for more information.
ensemble¶ (EnsembleBase) – The ensemble instance that can provide a compiled ensemble instance. See EnsembleBase for more information.
constraints¶ (ConstraintBase | tuple[ConstraintBase] | None, default: None) – The constraint instance or a list of constrain instances, each of which can provide a compiled constraint instance. See ConstraintBase for more information.
num_part¶ (int | None, default: None) – Number of compartments \(N_\mathrm{M}\) in the system. By default this is set to be \(8 N_\mathrm{C}\).
rng¶ (Generator | None, default: None) – Random number generator for initialization and reviving. None indicates that a new random number generator should be created by the class, seeded by current timestamp.
max_steps¶ (int, default: 1000000) – The default maximum number of steps in each run to find the coexisting phases. This value can be temporarily overwritten, see run() for more information.
convergence_criterion¶ (str, default: 'standard') – The criterion to determine convergence. Currently “standard” is the only option, which requires checking of incompressibility, field error and the volume error. Note that all these metrics are state functions, namely they are independent of iteration parameters.
tolerance¶ (float, default: 1e-05) – The tolerance to determine convergence. This value can be temporarily overwritten. See convergence_criterion and run() for more information.
interval¶ (int, default: 10000) – The interval of steps to check convergence. This value can be temporarily overwritten, see run() for more information.
progress¶ (bool, default: True) – Whether to show progress bar when checking convergence. This value can be temporarily overwritten, see run() for more information.
random_std¶ (float, default: 5.0) – The amplitude of the randomly generated conjugate fields internally. During instantiation, the conjugate field is randomly generated according to an normal distribution with standard deviation random_std.
acceptance_Js¶ (float, default: 0.0002) – The acceptance of 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, default: 0.001) – The maximum change of 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, default: 0.002) – The acceptance of the conjugate fields \(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. Typically this value can take the order of \(10^{-2}\), or smaller when the system becomes larger or stiffer.
kill_threshold¶ (float, default: 0.0) – 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 whether reviving is allowed or whether the number of the revive tries has been exhausted.
revive_scaler¶ (float, default: 1.0) – The scaler for the value of the newly-generated conjugate fields when a dead compartment is revived. The compartment is revived by drawing random numbers for their conjugate fields in the range of the minimum and the maximum of the their conjugate fields \(w_r^{(m)}\) across all compartments. This value determines whether this range should be enlarged (a value larger than 1) or reduced (a value smaller than 1). Typically 1.0 or a value slightly larger than 1.0 will be a reasonable choice.
max_revive_per_compartment¶ (int, default: 16) – Maximum average number of tries per compartment to revive the dead compartments. 0 or negative value indicates no reviving. When this value is exhausted, the revive will be turned off.
kwargs¶ – Additional keyword arguments that will be forwarded to the compile method in interaction, entropy, ensemble or constraints. Redundant arguments are allowed and ignored.

Public Data Attributes:

`omegas`	Internal conjugate fields \(w_r^{(m)}\).
`diagnostics`	Diagnostic information available after `run()` finished.

Public Methods:

`check_instance`(compiled_instance)	Check the size of the compiled instance.
`check_field`(field)	Check the size of a field.
`set_interaction`(interaction, *[, ...])	Set a new interaction instance.
`set_entropy`(entropy, *[, if_reset_revive])	Set a new entropy instance.
`set_ensemble`(ensemble, *[, if_reset_revive])	Set a new ensemble instance.
`set_constraints`([constraints, ...])	Set a new set of constraint instances.
`reset_revive`()	Reset the internal revive count.
`reinitialize_constraint`()	Reinitialize the constraints
`reinitialize_random`()	Reinitialize \(w_r^{(m)}\) randomly.
`reinitialize_from_omegas`(omegas)	Reinitialize \(w_r^{(m)}\) from input.
`reinitialize_from_phis`(phis)	Reinitialize \(w_r^{(m)}\) from \(\phi_r^{(m)}\).
`run`(*[, max_steps, tolerance, interval, ...])	Run instance to find coexisting phases.

check_instance(compiled_instance)[source]

Check the size of the compiled instance.

This method checks whether the compiled instance from InteractionBase, EntropyBase, EnsembleBase or ConstraintBase has the correct system size with the finder. An exception will be raised on failure.

Parameters:: compiled_instance¶ (InteractionBaseCompiled | EntropyBaseCompiled | EnsembleBaseCompiled | ConstraintBaseCompiled) – The instance to check.
Return type:: None

check_field(field)[source]

Check the size of a field.

This method checks whether the field has the same size as the omegas, which contains the conjugate field of the volume fractions of the features, \(w_r^{(m)}\), which has the size of \(N_\mathrm{S} \times N_\mathrm{M}\). An exception will be raise on failure.

Parameters:: field¶ (ndarray) – The field to check.
Returns:: The field converted to numpy array.
Return type:: ndarray

set_interaction(interaction, *, if_reset_revive=True, **kwargs)[source]

Set a new interaction instance.

This method sets a new interaction instance, using the updated keyword arguments. Note that this method does not change the default.

Parameters:

interaction¶ (InteractionBase) – New interaction instance.
if_reset_revive¶ (bool, default: True) – Whether the revive count is reset.
kwargs¶ – The keyword arguments to update the default.

Return type:

None

set_entropy(entropy, *, if_reset_revive=True, **kwargs)[source]

Set a new entropy instance.

This method sets a new entropy instance, using the updated keyword arguments. Note that this method does not change the default.

Parameters:

entropy¶ (EntropyBase) – New entropy instance.
if_reset_revive¶ (bool, default: True) – Whether the revive count is reset.
kwargs¶ – The keyword arguments to update the default.

Return type:

None

set_ensemble(ensemble, *, if_reset_revive=True, **kwargs)[source]

Set a new ensemble instance.

This method sets a new ensemble instance, using the updated keyword arguments. Note that this method does not change the default.

Parameters:

ensemble¶ (EnsembleBase) – New ensemble instance.
if_reset_revive¶ (bool, default: True) – Whether the revive count is reset.
kwargs¶ – The keyword arguments to update the default.

Return type:

None

set_constraints(constraints=None, *, if_reset_revive=True, kwargs_individual=None, **kwargs)[source]

Set a new set of constraint instances.

This method sets a new set of constraint instances, using the updated keyword arguments. Note that this method does not change the default.

Parameters:

constraints¶ (ConstraintBase | tuple[ConstraintBase] | None, default: None) – New set of constraint instances.
if_reset_revive¶ (bool, default: True) – Whether the revive count is reset.
kwargs_individual¶ (dict | tuple[dict] | None, default: None) – The keyword arguments to update the default for each constraint. This parameter has higher priority than kwargs.
kwargs¶ – The keyword arguments to update the default.

Return type:

None

reset_revive()[source]: Reset the internal revive count.

reinitialize_constraint()[source]: Reinitialize the constraints

reinitialize_random()[source]

Reinitialize \(w_r^{(m)}\) randomly.

See parameter CoexistingPhasesFinder.random_std for more information.

reinitialize_from_omegas(omegas)[source]

Reinitialize \(w_r^{(m)}\) from input.

Parameters:: omegas¶ (ndarray) – New \(w_r^{(m)}\) field, must have the size of \(N_\mathrm{S} \times M\).

reinitialize_from_phis(phis)[source]

Reinitialize \(w_r^{(m)}\) from \(\phi_r^{(m)}\).

The conjugated fields \(w_r^{(m)}\) are initialized from volume fraction fields \(\phi_r^{(m)}\). Note that it is not guaranteed that the initial volume fractions \(\phi_r^{(m)}\) are fully respected. The input is only considered as a suggestion for the generation of \(w_r^{(m)}\) field.

Parameters:: phis¶ (ndarray) – New \(\phi_r^{(m)}\), must have the size of \(N_\mathrm{S} \times M\).

property omegas: ndarray

Internal conjugate fields \(w_r^{(m)}\).

Read-only array of length \(N_\mathrm{S} \times N_\mathrm{M}\). Use reinitialize_from_omegas() to initialize the system from given \(w_r^{(m)}\).

property diagnostics: dict

Diagnostic information available after run() finished.

The diagnostics dictionary contains the convergence status and the original volume fractions before the clustering and sorting algorithm is used to determine the unique phases.

run(*, max_steps=None, tolerance=None, interval=None, progress=None)[source]

Run instance to find coexisting phases.

The keywords arguments can be used to temporarily overwrite the provided values during construction of the class. Note that this temporary values will not affect the defaults. See class CoexistingPhasesFinder for other tunable parameters. After each call, the diagnostics will be updated, which can be used to, for example, inspecting whether the iteration really converges. See diagnostics for more information.

Parameters:

max_steps¶ (float | None, default: None) – The maximum number of steps to find the coexisting phases.
tolerance¶ (float | None, default: None) – The tolerance to determine convergence. See convergence_criterion for more information.
interval¶ (int | None, default: None) – The interval of steps to check convergence.
progress¶ (bool | None, default: None) – Whether to show progress bar when checking convergence.

Returns:

Composition and relative size of the compartments. The member volumes (accessible by .volumes) contains the fraction of volume of each compartment. The member fractions (accessible by .fractions) contains volume fractions of all components. Use method get_clusters() to obtain unique phases.

Return type:

Phases