FormationEnergyMaker¶

class atomate2.common.flows.defect.FormationEnergyMaker(defect_relax_maker, bulk_relax_maker=None, uc_bulk=False, name='formation energy', relax_radius=None, perturb=None, validate_charge=True, collect_defect_entry_data=False)[source]¶

Bases: Maker, ABC

Maker class to help calculate of the formation energy diagram.

Maker class to calculate formation energy diagrams. The main settings for this maker is the defect_relax_maker which contains the settings for the atomic relaxations that each defect supercell will undergo.

This maker can be used as a stand-alone maker to calculate all of the data needed to populate the DefectEntry object. However, for you can also use this maker with uc_bulk set to True (also set collect_defect_entry_data to False and bulk_relax_maker to None). This will skip the bulk supercell calculations assuming that bulk unit cell calculations are of high enough quality to be used directly. In these cases, the bulk SC electrostatic potentials need to be constructed without running a separate bulk SC calculation. This is currently implemented through the grid re-sampling tools in mp-pyrho.

Variables:

defect_relax_maker (Maker) – A maker to perform a atomic-position-only relaxation on the defect charge states. Since these calculations are expensive and the settings might get messy, it is recommended for each implementation of this maker to check some of the most important settings in the relax_maker. Please see FormationEnergyMaker.validate_maker for more details.
bulk_relax_maker (Maker) –
If None, the same defect_relax_maker will be used for the bulk supercell. A maker to used to perform the bulk supercell calculation. For marginally converged calculations, it might be desirable to perform an additional lattice relaxation on the bulk supercell to make sure the energies are more reliable. However, if you do relax the bulk supercell, you can inadvertently change the grid size used in the calculation and thus the representation of the electrostatic potential which will affect calculation of the Freysoldt finite-size correction. Therefore, if you do want to perform a bulk supercell lattice relaxation, you should manually set the grid size.
```
relax_set = MPRelaxSet(defect.get_supercell_structure())
ng, ngf = relax_set.calculate_ng()
params = ["NGX", "NGY", "NGZ", "NGXF", "NGYF", "NGZF"]
ng_settings = dict(zip(params, ng + ngf))
relax_maker = update_user_incar_settings(relax_maker, ng_settings)
```
uc_bulk (bool) – If True, skip the bulk supercell calculation and only perform the defect supercell calculations. This is useful for large-scale defect databases.
name (str) – The name of the flow created by this maker.
relax_radius (float | str | None) – The radius to include around the defect site for the relaxation. If “auto”, the radius will be set to the maximum that will fit inside a periodic cell. If None, all atoms will be relaxed.
perturb (float | None) – The amount to perturb the sites in the supercell. Only perturb the sites with selective dynamics set to True. So this setting only works with relax_radius.
validate_charge (bool) – Whether to validate the charge of the defect. If True (default), the charge of the output structure will have to match the charge of the input defect. This helps catch situations where the charge of the output defect is either improperly set or improperly parsed before the data is stored in the database.

collect_defect_entry_data (bool) –

Whether to collect the defect entry data at the end of the flow. If True, the output of all the charge states for each symmetry distinct defect will be collected into a list of dictionaries that can be used to create a DefectEntry. The data here can be trivially combined with phase diagram data from the materials project API to create the formation energy diagrams.

Note

Once we remove the requirement for explicit bulk supercell calculations, this setting will be removed. It is only needed because the bulk supercell locpot is currently needed for the finite-size correction calculation.

Output format for the DefectEntry data:

[
    {
        "bulk_dir_name": "computer1:/folder1",
        "bulk_locpot": {...},
        "bulk_uuid": "48fb6da7-dc2b-4dcb-b1c8-1203c0f72ce3",
        "defect_dir_name": "computer1:/folder2",
        "defect_entry": {...},
        "defect_locpot": {...},
        "defect_uuid": "e9af2725-d63c-49b8-a01f-391540211750",
    },
    {
        "bulk_dir_name": "computer1:/folder3",
        "bulk_locpot": {...},
        "bulk_uuid": "48fb6da7-dc2b-4dcb-b1c8-1203c0f72ce3",
        "defect_dir_name": "computer1:/folder4",
        "defect_entry": {...},
        "defect_locpot": {...},
        "defect_uuid": "a1c31095-0494-4eed-9862-95311f80a993",
    },
]

Parameters:

defect_relax_maker (Maker)
bulk_relax_maker (Maker | None)
uc_bulk (bool)
name (str)
relax_radius (float | str | None)
perturb (float | None)
validate_charge (bool)
collect_defect_entry_data (bool)

make(defect, bulk_supercell_dir=None, supercell_matrix=None, defect_index='')[source]¶

Make a flow to calculate the formation energy diagram.

Start a series of charged supercell relaxations from a single defect structure.

Parameters:

defect (Defect) – A Defect object representing the Defect we are calculating the formation energy diagram for.
bulk_supercell_dir (str | Path | None) – If provided, the bulk supercell calculation will be skipped.
supercell_matrix (NDArray | None) – The supercell transformation matrix. If None, the supercell matrix will be computed automatically. If bulk_supercell_dir is provided, this parameter will be ignored.
defect_index (int | str) – Additional index to give unique names to the defect calculations. Useful for external bookkeeping of symmetry distinct defects.

Returns:

flow – The workflow to calculate the formation energy diagram.

Return type:

Flow

abstract sc_entry_and_locpot_from_prv(previous_dir)[source]¶

Copy the output ComputedStructureEntry and Locpot from previous directory.

Parameters:: previous_dir (str) – The directory to copy from.
Returns:: entry
Return type:: ComputedStructureEntry

abstract get_planar_locpot(task_doc)[source]¶

Get the Planar Locpot from the TaskDoc.

This is needed just in case the planar average locpot is stored in different part of the TaskDoc for different codes.

Parameters:: task_doc (TaskDoc) – The task document.
Returns:: planar_locpot – The planar average locpot.
Return type:: dict

abstract validate_maker()[source]¶

Check some key settings in the relax maker.

Since this workflow is pretty complex but allows you to use any relax maker, it can be easy to make mistakes in the settings. This method should check the most important settings and raise an error if something is wrong.

Example: For VASP, the relax maker should have:: ISIF = 2 and use_structure_charge = True

Return type:: None