pymatgen.entries.compatibility module¶
This module implements Compatibility corrections for mixing runs of different functionals.
-
class
AnionCorrection
(*args, **kwargs)[source]¶ Bases:
pymatgen.entries.compatibility.AnionCorrection
Correct anion energies to obtain the right formation energies. Note that this depends on calculations being run within the same input set.
For old MaterialsProjectCompatibility and MITCompatibility.
Pass through… :param args: :param kwargs: :return:
-
class
AqueousCorrection
(*args, **kwargs)[source]¶ Bases:
pymatgen.entries.compatibility.AqueousCorrection
This class implements aqueous phase compound corrections for elements and H2O.
Pass through… :param args: :param kwargs: :return:
-
class
Compatibility
[source]¶ Bases:
monty.json.MSONable
Abstract Compatibility class, not intended for direct use. Compatibility classes are used to correct the energies of an entry or a set of entries. All Compatibility classes must implement .get_adjustments method.
-
static
explain
(entry)[source]¶ Prints an explanation of the energy adjustments applied by the Compatibility class. Inspired by the “explain” methods in many database methodologies.
- Parameters
entry – A ComputedEntry.
-
abstract
get_adjustments
(entry: pymatgen.entries.computed_entries.ComputedEntry)[source]¶ Get the energy adjustments for a ComputedEntry.
This method must generate a list of EnergyAdjustment objects of the appropriate type (constant, composition-based, or temperature-based) to be applied to the ComputedEntry, and must raise a CompatibilityError if the entry is not compatible.
- Parameters
entry – A ComputedEntry object.
- Returns
- A list of EnergyAdjustment to be applied to the
Entry.
- Return type
- Raises
CompatibilityError if the entry is not compatible –
-
process_entries
(entries: Union[pymatgen.entries.computed_entries.ComputedEntry, list], clean: bool = True)[source]¶ Process a sequence of entries with the chosen Compatibility scheme. Note that this method will change the data of the original entries.
- Parameters
entries – ComputedEntry or [ComputedEntry]
clean – bool, whether to remove any previously-applied energy adjustments. If True, all EnergyAdjustment are removed prior to processing the Entry. Default is True.
- Returns
A list of adjusted entries. Entries in the original list which are not compatible are excluded.
-
static
-
exception
CompatibilityError
[source]¶ Bases:
Exception
Exception class for Compatibility. Raised by attempting correction on incompatible calculation
-
class
Correction
[source]¶ Bases:
object
A Correction class is a pre-defined scheme for correction a computed entry based on the type and chemistry of the structure and the calculation parameters. All Correction classes must implement a correct_entry method.
-
class
CorrectionsList
(corrections: Sequence)[source]¶ Bases:
pymatgen.entries.compatibility.Compatibility
The CorrectionsList class combines a list of corrections to be applied to an entry or a set of entries. Note that some of the Corrections have interdependencies. For example, PotcarCorrection must always be used before any other compatibility. Also, AnionCorrection(“MP”) must be used with PotcarCorrection(“MP”) (similarly with “MIT”). Typically, you should use the specific MaterialsProjectCompatibility and MITCompatibility subclasses instead.
- Parameters
corrections – List of corrections to apply.
-
explain
(entry)[source]¶ Prints an explanation of the corrections that are being applied for a given compatibility scheme. Inspired by the “explain” methods in many database methodologies.
- Parameters
entry – A ComputedEntry.
-
get_corrections_dict
(entry)[source]¶ Returns the corrections applied to a particular entry.
- Parameters
entry – A ComputedEntry object.
- Returns
value})
- Return type
({correction_name
-
get_explanation_dict
(entry)[source]¶ Provides an explanation dict of the corrections that are being applied for a given compatibility scheme. Inspired by the “explain” methods in many database methodologies.
- Parameters
entry – A ComputedEntry.
- Returns
(dict) of the form {“Compatibility”: “string”, “Uncorrected_energy”: float, “Corrected_energy”: float, “correction_uncertainty:” float, “Corrections”: [{“Name of Correction”: { “Value”: float, “Explanation”: “string”, “Uncertainty”: float}]}
-
class
GasCorrection
(*args, **kwargs)[source]¶ Bases:
pymatgen.entries.compatibility.GasCorrection
Correct gas energies to obtain the right formation energies. Note that this depends on calculations being run within the same input set. For old MaterialsProjectCompatibility and MITCompatibility.
Pass through… :param args: :param kwargs: :return:
-
class
MITAqueousCompatibility
(compat_type='Advanced', correct_peroxide=True, check_potcar_hash=False)[source]¶ Bases:
pymatgen.entries.compatibility.CorrectionsList
This class implements the GGA/GGA+U mixing scheme, which allows mixing of entries. Note that this should only be used for VASP calculations using the MIT parameters (see pymatgen.io.vaspio_set MITVaspInputSet). Using this compatibility scheme on runs with different parameters is not valid.
- Parameters
compat_type – Two options, GGA or Advanced. GGA means all GGA+U entries are excluded. Advanced means mixing scheme is implemented to make entries compatible with each other, but entries which are supposed to be done in GGA+U will have the equivalent GGA entries excluded. For example, Fe oxides should have a U value under the Advanced scheme. A GGA Fe oxide run will therefore be excluded under the scheme.
correct_peroxide – Specify whether peroxide/superoxide/ozonide corrections are to be applied or not.
check_potcar_hash (bool) – Use potcar hash to verify potcars are correct.
-
class
MITCompatibility
(compat_type='Advanced', correct_peroxide=True, check_potcar_hash=False)[source]¶ Bases:
pymatgen.entries.compatibility.CorrectionsList
This class implements the GGA/GGA+U mixing scheme, which allows mixing of entries. Note that this should only be used for VASP calculations using the MIT parameters (see pymatgen.io.vaspio_set MITVaspInputSet). Using this compatibility scheme on runs with different parameters is not valid.
- Parameters
compat_type – Two options, GGA or Advanced. GGA means all GGA+U entries are excluded. Advanced means mixing scheme is implemented to make entries compatible with each other, but entries which are supposed to be done in GGA+U will have the equivalent GGA entries excluded. For example, Fe oxides should have a U value under the Advanced scheme. A GGA Fe oxide run will therefore be excluded under the scheme.
correct_peroxide – Specify whether peroxide/superoxide/ozonide corrections are to be applied or not.
check_potcar_hash (bool) – Use potcar hash to verify potcars are correct.
-
class
MaterialsProject2020Compatibility
(compat_type='Advanced', correct_peroxide=True, check_potcar_hash=False)[source]¶ Bases:
pymatgen.entries.compatibility.Compatibility
This class implements the Materials Project 2020 energy correction scheme, which incorporates uncertainty quantification and allows for mixing of GGA and GGA+U entries (see References).
Note that this scheme should only be applied to VASP calculations that use the Materials Project input set parameters (see pymatgen.io.vasp.sets.MPRelaxSet). Using this compatibility scheme on calculations with different parameters is not valid.
- Parameters
compat_type –
Two options, GGA or Advanced. GGA means all GGA+U entries are excluded. Advanced means the GGA/GGA+U mixing scheme of Jain et al. (see References) is implemented. In this case, entries which are supposed to be calculated in GGA+U (i.e., transition metal oxides and fluorides) will have the corresponding GGA entries excluded. For example, Fe oxides should have a U value under the Advanced scheme. An Fe oxide run in GGA will therefore be excluded.
To use the “Advanced” type, Entry.parameters must contain a “hubbards” key which is a dict of all non-zero Hubbard U values used in the calculation. For example, if you ran a Fe2O3 calculation with Materials Project parameters, this would look like entry.parameters[“hubbards”] = {“Fe”: 5.3}. If the “hubbards” key is missing, a GGA run is assumed. Entries obtained from the MaterialsProject database will automatically have these fields populated.
(Default: “Advanced”)
correct_peroxide – Specify whether peroxide/superoxide/ozonide corrections are to be applied or not. If false, all oxygen-containing compounds are assigned the ‘oxide’ correction. (Default: True)
check_potcar_hash (bool) – Use potcar hash to verify POTCAR settings are consistent with MPRelaxSet. If False, only the POTCAR symbols will be used. (Default: False)
References
- Wang, A., et al. A framework for quantifying uncertainty in DFT energy corrections.
Under review.
- Jain, A. et al. Formation enthalpies by mixing GGA and GGA + U calculations.
Phys. Rev. B - Condens. Matter Mater. Phys. 84, 1–10 (2011).
-
get_adjustments
(entry: Union[pymatgen.entries.computed_entries.ComputedEntry, pymatgen.entries.computed_entries.ComputedStructureEntry])[source]¶ Get the energy adjustments for a ComputedEntry or ComputedStructureEntry.
Energy corrections are implemented directly in this method instead of in separate AnionCorrection, GasCorrection, or UCorrection classes which were used in the legacy correction scheme.
- Parameters
entry – A ComputedEntry or ComputedStructureEntry object.
- Returns
- A list of EnergyAdjustment to be applied to the
Entry.
- Return type
- Raises
CompatibilityError if the entry is not compatible –
-
class
MaterialsProjectAqueousCompatibility
(solid_compat: Optional[pymatgen.entries.compatibility.Compatibility] = <class 'pymatgen.entries.compatibility.MaterialsProjectCompatibility'>, o2_energy: Optional[float] = None, h2o_energy: Optional[float] = None, h2o_adjustments: Optional[float] = None)[source]¶ Bases:
pymatgen.entries.compatibility.Compatibility
This class implements the Aqueous energy referencing scheme for constructing Pourbaix diagrams from DFT energies, as described in Persson et al.
This scheme applies various energy adjustments to convert DFT energies into Gibbs free energies of formation at 298 K and to guarantee that the experimental formation free energy of H2O is reproduced. Briefly, the steps are:
Beginning with the DFT energy of O2, adjust the energy of H2 so that the experimental reaction energy of -2.458 eV/H2O is reproduced.
Add entropy to the DFT energy of any compounds that are liquid or gaseous at room temperature
Adjust the energy of H2O for consistency with the adjusted H2 energy.
Adjust the DFT energies of solid hydrate compounds (compounds that contain water, e.g. FeO.nH2O) such that the energies of the embedded H2O molecules are equal to the experimental free energy
The above energy adjustments are computed dynamically based on the input Entries.
References
K.A. Persson, B. Waldwick, P. Lazic, G. Ceder, Prediction of solid-aqueous equilibria: Scheme to combine first-principles calculations of solids with experimental aqueous states, Phys. Rev. B - Condens. Matter Mater. Phys. 85 (2012) 1–12. doi:10.1103/PhysRevB.85.235438.
Initialize the MaterialsProjectAqueousCompatibility class.
Note that this class requires as inputs the ground-state DFT energies of O2 and H2O, plus the value of any energy adjustments applied to an H2O molecule. If these parameters are not provided in __init__, they can be automatically populated by including ComputedEntry for the ground state of O2 and H2O in a list of entries passed to process_entries. process_entries will fail if one or the other is not provided.
- Parameters
solid_compat – Compatiblity scheme used to pre-process solid DFT energies prior to applying aqueous energy adjustments. May be passed as a class (e.g. MaterialsProjectCompatibility) or an instance (e.g., MaterialsProjectCompatibility()). If None, solid DFT energies are used as-is. Default: MaterialsProjectCompatibility
o2_energy – The ground-state DFT energy of oxygen gas, including any adjustments or corrections, in eV/atom. If not set, this value will be determined from any O2 entries passed to process_entries. Default: None
h2o_energy – The ground-state DFT energy of water, including any adjstments or corrections, in eV/atom. If not set, this value will be determined from any H2O entries passed to process_entries. Default: None
h2o_adjustments – Total energy adjustments applied to one water molecule, in eV/atom. If not set, this value will be determined from any H2O entries passed to process_entries. Default: None
-
get_adjustments
(entry: pymatgen.entries.computed_entries.ComputedEntry)[source]¶ Returns the corrections applied to a particular entry.
- Parameters
entry – A ComputedEntry object.
- Returns
Energy adjustments to be applied to entry.
- Return type
- Raises
CompatibilityError if the required O2 and H2O energies have not been provided to –
MaterialsProjectAqueousCompatibility during init or in the list of entries passed to process_entries. –
-
process_entries
(entries: Union[pymatgen.entries.computed_entries.ComputedEntry, list], clean: bool = False)[source]¶ Process a sequence of entries with the chosen Compatibility scheme.
- Parameters
entries – ComputedEntry or [ComputedEntry]
clean – bool, whether to remove any previously-applied energy adjustments. If True, all EnergyAdjustment are removed prior to processing the Entry. Default is False.
- Returns
A list of adjusted entries. Entries in the original list which are not compatible are excluded.
-
class
MaterialsProjectCompatibility
(**kwargs)[source]¶ Bases:
pymatgen.entries.compatibility.CorrectionsList
This class implements the GGA/GGA+U mixing scheme, which allows mixing of entries. Note that this should only be used for VASP calculations using the MaterialsProject parameters (see pymatgen.io.vaspio_set.MPVaspInputSet). Using this compatibility scheme on runs with different parameters is not valid.
-
class
PotcarCorrection
(input_set, check_hash=False)[source]¶ Bases:
pymatgen.entries.compatibility.Correction
Checks that POTCARs are valid within a pre-defined input set. This ensures that calculations performed using different InputSets are not compared against each other.
Entry.parameters must contain a “potcar_symbols” key that is a list of all POTCARs used in the run. Again, using the example of an Fe2O3 run using Materials Project parameters, this would look like entry.parameters[“potcar_symbols”] = [‘PAW_PBE Fe_pv 06Sep2000’, ‘PAW_PBE O 08Apr2002’].
- Parameters
input_set – InputSet object used to generate the runs (used to check for correct potcar symbols)
check_hash (bool) – If true, uses the potcar hash to check for valid potcars. If false, uses the potcar symbol (Less reliable). Defaults to True
- Raises
ValueError if entry do not contain "potcar_symbols" key. –
CombatibilityError if wrong potcar symbols –
-
class
UCorrection
(*args, **kwargs)[source]¶ Bases:
pymatgen.entries.compatibility.UCorrection
This class implements the GGA/GGA+U mixing scheme, which allows mixing of entries. Entry.parameters must contain a “hubbards” key which is a dict of all non-zero Hubbard U values used in the calculation. For example, if you ran a Fe2O3 calculation with Materials Project parameters, this would look like entry.parameters[“hubbards”] = {“Fe”: 5.3} If the “hubbards” key is missing, a GGA run is assumed.
It should be noted that ComputedEntries assimilated using the pymatgen.apps.borg package and obtained via the MaterialsProject REST interface using the pymatgen.matproj.rest package will automatically have these fields populated.
Pass through… :param args: :param kwargs: :return: