Ground States

Classes to perform ground-state searches.

Solver class for the ground state problem of cluster expansion.

class PeriodicGroundStateSolver(ensemble, charge_balanced=True, initial_occupancy=None, fixed_composition=None, other_constraints=None, term_coefficients_cutoff=0.0, warm_start=False, solver='SCIP', solver_options=None)

Bases: object

Class to solve for the ground state occupancy/structure of a given ensemble.

This implementation solves for the periodic ground-state configuration for a fixed super-cell size stored as the supercell matrix in the ensemble’s processor. Meaning that the solution corresponds only to an upper bound of the global ground state of the corresponding infinitely sized system.

For more details on the nature of the global problem, i.e. finding the upper and the lower bounds, please see:

https://doi.org/10.1103/PhysRevB.94.134424

Warning

The number of terms and constraints in underlying mixed-integer problem grow very rapidly with the size of the supercell, the number of allowed species, and the number of terms in the cluster expansion. As a result, solving for ground-states of large supercells and complex systems can be very time-consuming or even impossible, even using proprietary solvers and many cores. Make sure to check the number of terms and constraints in the problem and benchmark on a smaller supercell.

Initialize PeriodicGroundStateSolver.

Parameters:

• ensemble (Ensemble) – An ensemble to initialize the problem with. If you want to modify sub-lattices, please do that in ensemble before initializing the groundstate. Sub-lattices can not be modified after giving the ensemble!

• charge_balanced (bool) – optional Whether to enforce the charge-balance constraint. Default is True.

• initial_occupancy (ArrayLike) – optional An initial occupancy used to set the occupancy of manually restricted sites that may have more than one allowed species. Also used to set up the initial composition when solving in a canonical ensemble. Must be provided if any site has been manually restricted, or solving canonical ensemble.

• fixed_composition (ArrayLike) – optional An array of floats corresponding to the “counts” format of composition in CompositionSpace. See moca.composition. Unit is per super-cell. If the ensemble is canonical (no chemical potential has been set), will need to constrain the ground-state problem to a fixed composition. If initial_occupancy is provided while fixed_composition is None, composition will be fixed to that of initial_occupancy. Will be ignored in a semi-grand ensemble. If any of initial_occupancy or fixed_composition is provided, you are fully responsible to ensure that they satisfy charge balance and other constraints.

• other_constraints (list) – optional Other constraints to set in composition space. See moca.composition for detailed description. Note that constraints are now to be satisfied with the number of sites in sub-lattices of the supercell instead of the primitive cell.

• term_coefficients_cutoff (float) – optional Minimum cutoff to the coefficient of terms in the final polynomial Boolean objective function. If the absolute value of a term is less than this cutoff, it will not be included in the optimization. If no cutoff is given, will include every term in the optimization.

• solver (str) – optional Specify the groundstate used to solve the problem. SCIP is default because it does not require to linearize the problem before solving a polynomial form pseudo-boolean optimization. See cvxpy and PySciOpt documentations on how to correctly configure SCIP for cvxpy.

• warm_start (bool) – optional Whether to use the previous solution as an initialization of the current problem solve. Default is False.

• solver_options (dict) – optional Options to be passed into the groundstate when calling Problem.solve(). See cvxpy and the specific groundstate documentations for detail.

property auxiliary_variables

Auxiliary variables for linearizing the problem.

Returns:

cp.Variable.

property canonicals

The named tuple containing cvxpy problem details.

Returns:

ProblemCanonicals.

property constraints

Constraints to be satisfied in minimization.

Must include normalization per site. May include charge balance and other constraints to composition. In canonical ensemble, must include a constraint to fix composition.

Returns:

List[cvxpy.Constraint]

property ground_state_energy

Energy per super-cell in the ground-state.

Returns:

float.

property ground_state_occupancy

Encoded occupancy string of the ground-state.

Returns:

np.ndarray

property ground_state_solution

Boolean variable values at the ground state.

Returns:

the solution array in 0 and 1.

Return type:

np.ndarray

property ground_state_structure

The ground state structure.

Returns:

Structure.

property indices_in_auxiliary_products

Indices of variables in cluster terms corresponding to auxiliary variables.

Returns:

list of lists of int

property objective_function

The objective function to be minimized.

Usually total energy per super-cell.

Returns:

cvxpy.Expression.

property problem

The cvxpy problem for solving upper-bound of ground-state.

Returns:

cvxpy.Problem.

reset()

Clear previous solutions and reinitialize the problem.

solve()

Solve the MIP problem.

Returns:

values of boolean variables in the ground-state solution, and the minimized ground-state energy.

Return type:

np.ndarray, float

property structure

Supercell structure of the ensemble without any split.

Returns:

Structure.

property sublattices

Sub-lattices to build the problem on.

Potentially contains split sub-lattices or manually restricted sites. :returns: List of Sublattice.

property variable_indices

Indices of variables on each site if site is active.

Returns:

each sub-list contains variable indices on an active site.

Return type:

list of lists of int

property variables

CVXPY variables for species on each active site.

Returns:

cvxpy.Variable.