MEMO: Example for using ASE's PhaseDiagram for convex hull energies

In reference to this issue: #610 (closed)

The ASE PhaseDiagram code is much faster than the icet convex hull code for large composition spaces. Since ASE is already a dependency, it makes sense to have an example for users with large composition spaces. To get that started, I'll document how I integrated ASE PhaseDiagram into my icet workflow.

from ase.phasediagram import PhaseDiagram

formulas_and_mixing_energies = []
mixing_energies_per_atom = []
for atoms in list_of_structures:

    # normal icet workflow
    energy = atoms.get_potential_energy() 
    reference_energy = compute_reference_energy(atoms, pure_state_energies)
    mixing_energy_per_atom = (energy - reference_energy)/len(atoms)
    mixing_energies_per_atom.append(mixing_energy_per_atom) 

    # ase expects total energy and chemical formulas
    formula = atoms.get_chemical_formula() 
    total_mixing_energy = mixing_energy_per_atom*len(atoms)
    formulas_and_mixing_energies.append((formula, total_mixing_energy))

# it will output a lot of information if verbose=True
pd = PhaseDiagram(formulas_and_mixing_energies, verbose=False)

# loop over structures to get the energies relative to the convex hull
energies_per_atom_above_hull = []
for i in range(len(list_of_structures)):

        formula, total_mixing_energy = formulas_and_mixing_energies[i]
        atoms = list_of_structures[i]

        hull_energy, indices, coeffs = pd.decompose(formula)
        energy_above_hull = total_mixing_energy - hull_energy
        energy_per_atom_above_hull = energy_above_hull/len(atoms)
        energies_per_atom_above_hull.append( energy_per_atom_above_hull)

# for more info see https://gitlab.com/ase/ase/-/blob/master/ase/phasediagram.py