rxn_network.entries#

rxn_network.entries.corrections#

Energy correction classes for entry objects.

class rxn_network.entries.corrections.CarbonateCorrection(num_ions, carbonate_correction=0.83)[source]#

Bases: CompositionEnergyAdjustment

Supplies a carbonate correction due to systematic GGA errors in carbonate formation energies.

See provided jupyter NB for fitting of the correction: data/fit_carbonate_correction.ipynb

Initalizes a carbonate correction object.

Parameters:

num_ions (int) – Number of carbonate ions in the composition object
carbonate_correction (float) – Energy correction, eV per (CO3)2- anion

property num_ions: int#: Number of carbonate ions ion the composition object.

property carbonate_correction: float#: Energy correction for carbonate ion, eV per (CO3)2- anion.

class rxn_network.entries.corrections.CarbonDioxideAtmosphericCorrection(n_atoms, temp, pco2=0.0004)[source]#

Bases: CompositionEnergyAdjustment

Supplies a correction to the energy of CO2 due to its low partial pressure in the standard atmosphere (0.04%).

Initalizes a carbon dioxide correction object.

Parameters:

n_atoms (int) – Number of atoms in the composition object
temp (float) – Temperature at which the correction is applied, in K
pco2 (float) – Partial pressure of CO2 in the atmosphere, in atm

get_dmu()[source]#

Returns the change in chemical potential of CO2 due to the atmospheric pCO2 at a given temperature.

This is calculated by the formula: dmu = (1/3)*kTlnP(CO2).

The factor of 1/3 accounts for the number of atoms in one formula unit of CO2, since the correction must be in eV/atom.

Return type:: float

property temp: float#: Temperature at which the correction is applied, in K.

property pco2: float#: Partial pressure of CO2 in the atmosphere, in atm.

rxn_network.entries.entry_set#

An entry set class for automatically building GibbsComputedEntry objects. Some of this code has been adapted from the EntrySet class in pymatgen.

rxn_network.entries.entry_set.normal(loc=0.0, scale=1.0, size=None)#

Draw random samples from a normal (Gaussian) distribution.

The probability density function of the normal distribution, first derived by De Moivre and 200 years later by both Gauss and Laplace independently [2], is often called the bell curve because of its characteristic shape (see the example below).

The normal distributions occurs often in nature. For example, it describes the commonly occurring distribution of samples influenced by a large number of tiny, random disturbances, each with its own unique distribution [2].

Note

New code should use the ~numpy.random.Generator.normal method of a ~numpy.random.Generator instance instead; please see the random-quick-start.

Parameters:

loc (float or array_like of floats) – Mean (“centre”) of the distribution.
scale (float or array_like of floats) – Standard deviation (spread or “width”) of the distribution. Must be non-negative.
size (int or tuple of ints, optional) – Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. If size is None (default), a single value is returned if loc and scale are both scalars. Otherwise, np.broadcast(loc, scale).size samples are drawn.

Returns:

out – Drawn samples from the parameterized normal distribution.

Return type:

ndarray or scalar

See also

scipy.stats.norm: probability density function, distribution or cumulative density function, etc.
random.Generator.normal: which should be used for new code.

Notes

The probability density for the Gaussian distribution is

\[p(x) = \frac{1}{\sqrt{ 2 \pi \sigma^2 }} e^{ - \frac{ (x - \mu)^2 } {2 \sigma^2} },\]

where $\mu$ is the mean and $\sigma$ the standard deviation. The square of the standard deviation, $\sigma^2$, is called the variance.

The function has its peak at the mean, and its “spread” increases with the standard deviation (the function reaches 0.607 times its maximum at $x + \sigma$ and $x - \sigma$ [2]). This implies that normal is more likely to return samples lying close to the mean, rather than those far away.

References

Examples

Draw samples from the distribution:

>>> mu, sigma = 0, 0.1 # mean and standard deviation
>>> s = np.random.normal(mu, sigma, 1000)

Verify the mean and the variance:

>>> abs(mu - np.mean(s))
0.0  # may vary

>>> abs(sigma - np.std(s, ddof=1))
0.1  # may vary

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 30, density=True)
>>> plt.plot(bins, 1/(sigma * np.sqrt(2 * np.pi)) *
...                np.exp( - (bins - mu)**2 / (2 * sigma**2) ),
...          linewidth=2, color='r')
>>> plt.show()

Two-by-four array of samples from the normal distribution with mean 3 and standard deviation 2.5:

>>> np.random.normal(3, 2.5, size=(2, 4))
array([[-4.49401501,  4.00950034, -1.81814867,  7.29718677],   # random
       [ 0.39924804,  4.68456316,  4.99394529,  4.84057254]])  # random

class rxn_network.entries.entry_set.GibbsEntrySet(entries, calculate_e_above_hulls=False, minimize_obj_size=False)[source]#

Bases: MutableSet, MSONable

This object is based on pymatgen’s EntrySet class and includes factory methods for constructing GibbsComputedEntry objects from “zero-temperature” ComputedStructureEntry objects. It also offers convenient methods for acquiring entries from the entry set, whether that be using composition, stability, chemical system, etc.

The supplied collection of entries will automatically be converted to a set of unique entries.

Parameters:

entries (Iterable[GibbsComputedEntry | ExperimentalReferenceEntry | InterpolatedEntry]) – A collection of entry objects that will make up the entry set.
calculate_e_above_hulls (bool) – Whether to pre-calculate the energy above hull for each entry and store that in that entry’s data. Defaults to False.
minimize_obj_size (bool) – Whether to reduce the size of the entry set by removing metadata from each entry. This may be useful when working with extremely large entry sets (or ComputedReaction sets). Defaults to False.

add(entry)[source]#

Add an entry to the set. This is an IN-PLACE method.

Parameters:: entry (GibbsComputedEntry | ExperimentalReferenceEntry | InterpolatedEntry) – An entry object.
Return type:: None

update(entries)[source]#

Add an iterable of entries to the set. This is an IN-PLACE method.

Parameters:: entries (Iterable[GibbsComputedEntry | ExperimentalReferenceEntry | InterpolatedEntry]) – Iterable of entry objects to add to the set.
Return type:: None

discard(entry)[source]#

Discard an entry. This is an IN-PLACE method.

Parameters:: entry (GibbsComputedEntry | ExperimentalReferenceEntry) – An entry object.
Return type:: None

property pd_dict: dict#: Returns a dictionary of phase diagrams, keyed by the chemical system. This is acquired using the helper method expand_pd() and represents one of the simplest divisions of sub-PDs for large chemical systems. Cached for speed.

get_subset_in_chemsys(chemsys)[source]#

Returns a GibbsEntrySet containing only the set of entries belonging to a particular chemical system (including subsystems). For example, if the entries are from the Li-Fe-P-O system, and chemsys=[“Li”, “O”], only the Li, O, and Li-O entries are returned.

Parameters:: chemsys (list[str] | str) – Chemical system specified as list of elements. E.g., [“Li”, “O”]
Return type:: GibbsEntrySet

Returns: GibbsEntrySet

filter_by_stability(e_above_hull, include_polymorphs=False)[source]#

Filter the entry set by a metastability (energy above hull) cutoff.

Parameters:

e_above_hull (float) – Energy above hull, the cutoff describing the allowed metastability of the entries as determined via phase diagram construction.
include_polymorphs (bool | None) – optional specification of whether to include metastable polymorphs. Defaults to False.

Returns:

A new GibbsEntrySet where the entries have been filtered by an energy cutoff (e_above_hull) via phase diagram construction.

Return type:

GibbsEntrySet

build_indices()[source]#

Builds the indices for the entry set in place. This method is called whenever an entry is added/removed the entry set. The entry indices are useful for querying the entry set for specific entries.

Warning: this internally modifies the entries in the entry set by updating data for each entry to include the index.

Returns:: None
Return type:: None

get_min_entry_by_formula(formula)[source]#

Helper method for acquiring the ground state entry with the specified formula.

Parameters:: formula (str) – The chemical formula of the desired entry.
Returns:: Ground state computed entry object.
Return type:: ComputedEntry

get_stabilized_entry(entry, tol=0.001, force=False)[source]#

Helper method for lowering the energy of a single entry such that it is just stable on the phase diagram. If the entry is already stable, it will be returned unchanged.

Note: if the entry includes the “e_above_hull” data, this value will be used to stabilize the entry. Otherwise, the energy above hull will be calculated via creation of a phase diagram; this can take a long time for repeated calls.

Parameters:

entry (ComputedEntry) – A computed entry object.
tol (float) – The numerical padding added to the energy correction to guarantee that it is determined to be stable during phase diagram construction.
force – due to numerical stability issues, if the entry is very close to the hull (i.e., e_above_hull > 0 but very small), it may not be stabilized. This option forces stabilization even if e_above_hull evalutes to “zero”. This can be crucial for certain edge cases.

Returns:

A new ComputedEntry with energy adjustment making it appear to be stable with the current entry data (i.e., compositional phase diagram).

Return type:

ComputedEntry

get_entries_with_new_temperature(new_temperature)[source]#

Returns a new GibbsEntrySet with entries that have had their energies modified by using a new temperature.

Note: this will clear the “e_above_hull” data for each entry and re-calculate them only if the original entry set had them calculated.

Parameters:: new_temperature (float) –
Return type:: GibbsEntrySet

get_entries_with_jitter()[source]#

Returns a new GibbsEntrySet with entries that have had their energies shifted by randomly sampled noise to account for uncertainty in data. This is done by sampling from a Gaussian distribution using the entry’s “correction_uncertainty” attribute as the scale.

Returns:: A new GibbsEntrySet with entries that have had their energies shifted by random Gaussian noise based on their “correction_uncertainty” values.
Return type:: GibbsEntrySet

get_interpolated_entry(formula, tol_per_atom=0.001)[source]#

Helper method for interpolating an entry from the entry set.

Parameters:

formula (str) – The chemical formula of the desired entry.
tol_per_atom (float) – the energy shift (eV/atom) below the hull energy so that the interpolated entry is guaranteed to be stable. Defaults to 1 meV/atom.

Returns:

An interpolated GibbsComputedEntry object.

Return type:

ComputedEntry

get_e_above_hull(entry)[source]#

Helper method for calculating the energy above hull for a single entry.

Parameters:: entry (ComputedEntry) – A ComputedEntry object.
Returns:: The energy above hull for the entry.
Return type:: float

classmethod from_pd(pd, temperature, include_nist_data=True, include_freed_data=False, apply_carbonate_correction=True, apply_atmospheric_co2_correction=True, ignore_nist_solids=True, calculate_e_above_hulls=False, minimize_obj_size=False)[source]#

Constructor method for building a GibbsEntrySet from an existing phase diagram.

Parameters:

pd (PhaseDiagram) – Phase Diagram object (pymatgen)
temperature (float) – Temperature [K] for determining Gibbs Free Energy of formation, dGf(T)
include_nist_data (bool) – Whether to include NIST data in the entry set. Defaults to True.
include_freed_data (bool) – Whether to include Freed data in the entry set. Defaults to False. Use at your own risk!
apply_carbonate_correction (bool) – Whether to apply the fit energy correction for carbonates. Defaults to True.
apply_atmospheric_co2_correction (bool) – Whether to modify the chemical potential of CO2 by its partial pressure in the atmosphere (0.04%). Defaults to True.
ignore_nist_solids (bool) – Whether to ignore NIST data for the solids specified in the “data/nist/ignore_solids.json” file; these all have melting points Tm >= 1500 ºC. Defaults to Ture.
calculate_e_above_hulls (bool) – Whether to calculate energy above hull for each entry and store in the entry’s data. Defaults to False.
minimize_obj_size (bool) – Whether to minimize the size of the object by removing unnecessary attributes from the entries. Defaults to False.

Returns:

A GibbsEntrySet containing a collection of GibbsComputedEntry and experimental reference entry objects at the specified temperature.

Return type:

GibbsEntrySet

copy()[source]#

Returns a copy of the entry set.

Return type:: GibbsEntrySet

as_dict()[source]#

Returns a JSON serializable dict representation of the entry set.

Return type:: dict

classmethod from_computed_entries(entries, temperature, include_nist_data=True, include_freed_data=False, apply_carbonate_correction=True, apply_atmospheric_co2_correction=True, ignore_nist_solids=True, calculate_e_above_hulls=False, minimize_obj_size=False)[source]#

Constructor method for initializing GibbsEntrySet from T = 0 K ComputedStructureEntry objects, as acquired from a thermochemical database (e.g., The Materials Project).

Automatically expands the phase diagram for large chemical systems (10 or more elements) to avoid limitations of Qhull.

Parameters:

entries (Iterable[ComputedStructureEntry]) – Iterable of ComputedStructureEntry objects. These can be downloaded from The Materials Project API or created manually with pymatgen.
temperature (float) – Temperature [K] for determining Gibbs Free Energy of formation, dGf(T)
include_nist_data (bool) – Whether to include NIST-JANAF data in the entry set. Defaults to True.
include_freed_data (bool) – Whether to include FREED data in the entry set. Defaults to False. WARNING: This dataset has not been thoroughly tested. Use at your own risk!
apply_carbonate_correction (bool) – Whether to apply the fit GGA energy correction for carbonates. Defaults to True.
apply_atmospheric_co2_correction (bool) – Whether to modify the chemical potential of CO2 by its partial pressure in the atmosphere (). Defaults to True.
ignore_nist_solids (bool) – Whether to ignore NIST data for the solids specified in the “data/nist/ignore_solids.json” file; these all have melting points Tm >= 1500 ºC. Defaults to True.
calculate_e_above_hulls (bool) – Whether to calculate energy above hull for each entry and store in the entry’s data. Defaults to False.
minimize_obj_size (bool) – Whether to minimize the size of the object by removing unrequired attributes from the entries. Defaults to False.

Returns:

A GibbsEntrySet containing a collection of GibbsComputedEntry and experimental reference entry objects at the specified temperature.

Return type:

GibbsEntrySet

property entries_list: list[ComputedEntry]#: Returns a list of all entries in the entry set.

property min_entries_by_formula: dict[str, ComputedEntry]#: Returns a dict of minimum energy entries in the entry set, indexed by formula.

property temperature: float#

Returns the temperature of entries in the dataset. More precisely, this is the temperature encountered when iterating over the dataset.

Use at your own risk if mixing GibbsComputedEntry objects calculated at different temperatures – this poses even more theoretical problems!

property chemsys: set[str]#: Returns: Set of symbols representing the chemical system, e.g., {“Li”, “Fe”, “P”, “O”}.

static get_adjusted_entry(entry, adjustment)[source]#

Gets an entry with an energy adjustment applied.

Parameters:

entry (GibbsComputedEntry) – A GibbsComputedEntry object.
adjustment (EnergyAdjustment) – An EnergyAdjustment object to apply to the entry.

Returns:

A new GibbsComputedEntry object with the energy adjustment applied.

Return type:

GibbsComputedEntry

rxn_network.entries.experimental#

Implements an Entry that looks up NIST pre-tabulated Gibbs free energies.

class rxn_network.entries.experimental.ExperimentalReferenceEntry(composition, temperature, energy_adjustments=None, data=None)[source]#

Bases: ComputedEntry

An Entry class for experimental reference data, to be sub-classed for specific data sources. Given a composition, automatically finds the Gibbs free energy of formation, dGf(T) from tabulated reference values.

Parameters:

composition (Composition) – Composition object
temperature (float) – Temperature in Kelvin. If temperature is not selected within the range of the reference data (see self._validate_temperature), then this will raise an error.
energy_adjustments (list[EnergyAdjustment] | None) – A list of EnergyAdjustments to apply to the entry.
data (dict | None) – Optional dictionary containing entry data.

get_new_temperature(new_temperature)[source]#

Return a copy of the NISTReferenceEntry at the new specified temperature.

Parameters:: new_temperature (float) – The new temperature to use [K]
Returns:: A copy of the NISTReferenceEntry at the new specified temperature.
Return type:: ExperimentalReferenceEntry

to_grand_entry(chempots)[source]#

Convert an ExperimentalReferenceEntry to a GrandComputedEntry.

Parameters:: chempots (dict[Element, float]) – A dictionary of {element: chempot} pairs.
Returns:: A GrandComputedEntry.

property temperature: float#: Returns temperature used to calculate entry’s energy.

property is_experimental: bool#: Returns True by default.

property is_element: bool#: Returns True if the entry is an element.

property unique_id: str#: Returns a unique ID for the entry based on its entry-id and temperature. This is useful because the same entry-id can be used for multiple entries at different temperatures.

as_dict()[source]#

Returns: A dict representation of the Entry.

Return type:: dict

classmethod from_dict(d)[source]#

Generate an ExperimentalReferenceEntry object from a dictionary.

Parameters:: d (dict) – dictionary representation of the entry
Returns:: ExperimentalReferenceEntry object initialized with data from the dictionary.
Return type:: ExperimentalReferenceEntry

rxn_network.entries.freed#

Implements an Entry that looks up pre-tabulated Gibbs free energies from the NIST-JANAF tables.

class rxn_network.entries.freed.FREEDReferenceEntry(composition, temperature, energy_adjustments=None, data=None)[source]#

Bases: ExperimentalReferenceEntry

An Entry class for FREED experimental reference data. Given a composition, automatically finds the Gibbs free energy of formation, dGf(T) from tabulated reference values.

Reference:: https://www.thermart.net/freed-thermodynamic-database/

Args: composition: Composition object temperature: Temperature in Kelvin. If temperature is not selected from

one of [300, 400, 500, … 2000 K], then free energies will be interpolated. Defaults to 300 K.

energy_adjustments: A list of EnergyAdjustments to apply to the entry. data: Optional dictionary containing entry data.

Parameters:

composition (Composition) –
temperature (float) –
energy_adjustments (list[EnergyAdjustment] | None) –
data (dict | None) –

rxn_network.entries.gibbs#

A computed entry object for estimating the Gibbs free energy of formation. Note that this is similar to the implementation within pymatgen, but has been refactored here to add extra functionality.

class rxn_network.entries.gibbs.GibbsComputedEntry(composition, formation_energy_per_atom, volume_per_atom, temperature, energy_adjustments=None, parameters=None, data=None, entry_id=None)[source]#

Bases: ComputedEntry

An extension to ComputedEntry which estimates the Gibbs free energy of formation of solids using energy adjustments from the machine-learned SISSO descriptor from Bartel et al. (2018). Note that this is similar to the implementation within pymatgen, but has been refactored here to add extra functionality.

WARNING: This descriptor only applies to solids. See entries.nist.NISTReferenceEntry for common gases (e.g. CO2).

If you use this entry class in your work, please consider citing the following paper:

Bartel, C. J., Millican, S. L., Deml, A. M., Rumptz, J. R., Tumas, W., Weimer, A. W., … Holder, A. M. (2018). Physical descriptor for the Gibbs energy of inorganic crystalline solids and temperature-dependent materials chemistry. Nature Communications, 9(1), 4168. https://doi.org/10.1038/s41467-018-06682-4.

A new computed entry object is returned with a supplied energy correction representing the difference between the formation enthalpy at T=0K and the Gibbs formation energy at the specified temperature.

Parameters:

composition (Composition) – The composition object (pymatgen)
formation_energy_per_atom (float) – Calculated formation enthalpy, dH, at T = 298 K, normalized to the total number of atoms in the composition. NOTE: since this is a _formation_ energy, it must be calculated using a phase diagram construction.
volume_per_atom (float) – The total volume of the associated structure divided by its number of atoms.
temperature (float) – Temperature [K] by which to acquire dGf(T); must be selected from a range of [300, 2000] K. If temperature is not selected from one of [300, 400, 500, … 2000 K], then free energies will be interpolated.
energy_adjustments (list[EnergyAdjustment] | None) – Optional list of energy adjustments.
parameters (dict | None) – Optional list of calculation parameters.
data (dict | None) – Optional dictionary containing entry data.
entry_id (object | None) – An identifying string for the entry, such as the entry’s mpid (e.g., “mp-25025”). While optional, this is recommended to set as several downstream classes depend on its use. If an entry_id is not provided, a combination of the composition and volume will be used (e.g., “Li2O_8.4266”).

get_new_temperature(new_temperature)[source]#

Return a copy of the GibbsComputedEntry at the new specified temperature.

Parameters:: new_temperature (float) – The new temperature to use [K]
Returns:: A copy of the GibbsComputedEntry, initialized at the new specified temperature.
Return type:: GibbsComputedEntry

gibbs_adjustment(temperature)[source]#

Returns the difference between the predicted Gibbs formation energy and the formation enthalpy at 298 K, i.e., dGf(T) - dHf(298 K). Calculated using SISSO descriptor from Bartel et al. (2018) and elemental chemical potentials (FactSage).

Units: eV (not normalized)

Parameters:: temperature (float) – The absolute temperature [K].
Returns:: The correction to Gibbs free energy of formation (eV) from DFT energy.
Return type:: float

to_grand_entry(chempots)[source]#

Convert a GibbsComputedEntry to a GrandComputedEntry.

Parameters:: chempots (dict[Element, float]) – A dictionary of {element: chempot} pairs.
Returns:: A GrandComputedEntry.
Return type:: GrandPotPDEntry

copy()[source]#

Returns a deepcopy of the GibbsComputedEntry object.

Return type:: GibbsComputedEntry

classmethod from_structure(structure, formation_energy_per_atom, temperature, **kwargs)[source]#

Constructor method for building a GibbsComputedEntry from a structure, formation enthalpy, and temperature.

Parameters:

structure (Structure) – Structure object (pymatgen)
formation_energy_per_atom (float) – Formation enthalpy at T = 298 K associated with structure
temperature (float) – Desired temperature [K] for acquiring dGf(T)
**kwargs – Optional kwargs to be passed to GibbsComputedEntry.__init__, such as entry_id, energy_adjustments, parameters, and data.

Returns:

A new GibbsComputedEntry object

Return type:

GibbsComputedEntry

property is_experimental: bool#

False}. If theoretical is not specified but there is greater than 1 icsd_id provided, assumes that the presence of an icsd_id means the entry is experimental.

Type:: Returns True if self.data contains {“theoretical”

property unique_id: str#: Returns a unique ID for the entry based on its entry-id and temperature. This is useful because the same entry-id can be used for multiple entries at different temperatures.

as_dict()[source]#

Returns an MSONable dict.

Return type:: dict

classmethod from_dict(d)[source]#

Returns a GibbsComputedEntry object from MSONable dictionary.

Parameters:: d (dict) –
Return type:: GibbsComputedEntry

rxn_network.entries.interpolated#

Class for intepolated entries.

class rxn_network.entries.interpolated.InterpolatedEntry(composition, energy, correction=0.0, energy_adjustments=None, parameters=None, data=None, entry_id=None)[source]#

Bases: ComputedEntry

Lightweight Entry object for computed data. Contains facilities for applying corrections to the energy attribute and for storing calculation parameters.

Parameters:

composition (Composition) – Composition of the entry. For flexibility, this can take the form of all the typical input taken by a Composition, including a {symbol: amt} dict, a string formula, and others.
energy (float) – Energy of the entry. Usually the final calculated energy from VASP or other electronic structure codes.
correction (float) – Manually set an energy correction, will ignore energy_adjustments if specified. Defaults to 0.
energy_adjustments (list | None) – An optional list of EnergyAdjustment to be applied to the energy. This is used to modify the energy for certain analyses. Defaults to None.
parameters (dict | None) – An optional dict of parameters associated with the entry. Defaults to None.
data (dict | None) – An optional dict of any additional data associated with the entry. Defaults to None.
entry_id (object | None) – An optional id to uniquely identify the entry.

to_grand_entry(chempots)[source]#

Convert a GibbsComputedEntry to a GrandComputedEntry.

Parameters:: chempots (dict[Element, float]) – A dictionary of {element: chempot} pairs.
Returns:: A GrandComputedEntry.
Return type:: GrandPotPDEntry

get_new_temperature(new_temperature)[source]#

Return a copy of the InterpolatedEntry at the new specified temperature.

WARNING: This is not possible for interpolated entries. Instead, this returns a copy of the original entry.

Parameters:: new_temperature (float) – The new temperature to use [K]
Returns:: A copy of the entry.
Return type:: InterpolatedEntry

property unique_id: str#: Returns a unique ID for the entry.

property is_experimental: bool#: Returns True by default.

rxn_network.entries.nist#

Implements an Entry that looks up pre-tabulated Gibbs free energies from the NIST-JANAF tables.

class rxn_network.entries.nist.NISTReferenceEntry(composition, temperature, energy_adjustments=None, data=None)[source]#

Bases: ExperimentalReferenceEntry

An Entry class for NIST-JANAF experimental reference data. Given a composition, automatically finds the Gibbs free energy of formation, dGf(T) from tabulated reference values.

Reference:: Malcolm W. Chase Jr. NIST-JANAF thermochemical tables. Fourth edition. Washington, DC : American Chemical Society; New York : American Institute of Physics for the National Institute of Standards and Technology, 1998.

Args: composition: Composition object (within pymatgen). temperature: Temperature in Kelvin. If temperature is not selected from

one of [300, 400, 500, … 2000 K], then free energies will be interpolated. Defaults to 300 K.

energy_adjustments: A list of EnergyAdjustments to apply to the entry. data: Optional dictionary containing entry data.

Parameters:

composition (Composition) –
temperature (float) –
energy_adjustments (list[EnergyAdjustment] | None) –
data (dict | None) –

rxn_network.entries.utils#

Utility functions for acquiring, processing, or modifiying entries.

rxn_network.entries.utils.process_entries(entries, temperature, e_above_hull, filter_at_temperature=None, include_nist_data=True, include_freed_data=False, include_polymorphs=False, formulas_to_include=None, calculate_e_above_hulls=False, ignore_nist_solids=True)[source]#

Convenience function for processing a set of ComputedStructureEntry objects into a GibbsEntrySet with specified parameters. This is used when building entries in most of the jobs/flows.

Parameters:

entries (Iterable[ComputedStructureEntry]) – Iterable of ComputedStructureEntry objects. These can be downloaded from The Materials Project API or created manually with pymatgen.
temperature (float) – Temperature [K] for determining Gibbs Free Energy of formation, dGf(T).
e_above_hull (float) – Energy above hull (eV/atom) for thermodynamic stability threshold; i.e., include all entries with energies below this value.
filter_at_temperature (int | None) – Temperature (in Kelvin) at which entries are filtered for thermodynamic stability (e.g., room temperature). Generally, this often differs from the synthesis temperature.
include_nist_data (bool) – Whether to include NIST-JANAF data in the entry set. Defaults to True.
include_freed_data (bool) – Whether to include FREED data in the entry set. Defaults to False. WARNING: This dataset has not been thoroughly tested. Use at your own risk!
include_polymorphs (bool) – Whether to include non-ground state polymorphs in the entry set. Defaults to False.
formulas_to_include (Iterable[str] | None) – An iterable of compositional formulas to ensure are included in the processed dataset. Sometimes, entries are filtered out that one would like to include, or entries don’t exist for those compositions.
calculate_e_above_hulls (bool) – Whether to calculate e_above_hull and store as an attribute in the data dictionary for each entry.
ignore_nist_solids (bool) – Whether to ignore NIST data for solids with high melting points (Tm >= 1500 ºC). Defaults to True.

Returns:

A GibbsEntrySet object containing entry objects with the user-specified constraints.

Return type:

GibbsEntrySet

rxn_network.entries.utils.initialize_entry(formula, entry_set, stabilize=False)[source]#

Acquire an entry by user-specified formula. This method attemps to first get the entry; if it is not included in the set, it will create an interpolated entry. Finally, if stabilize=True, the energy will be lowered until it appears on teh hull.

Parameters:

formula (str) – Chemical formula
entry_set (GibbsEntrySet) – Set of entries
stabilize (bool) – Whether or not to stabilize the entry by decreasing its energy such that it is ‘on the hull’.

rxn_network.entries.utils.get_entries(db, chemsys_formula_id_criteria, compatible_only=True, inc_structure=None, property_data=None, use_premade_entries=False, conventional_unit_cell=False, sort_by_e_above_hull=False)[source]#

Warning

This function is legacy code directly adapted from pymatgen.ext.matproj. It is not broadly useful or applicable to other databases. It is only used in jobs interfaced directly with internal databases at the Materials Project. This code is not adequately tested and may not work as expected.

Get a list of ComputedEntries or ComputedStructureEntries corresponding to a chemical system, formula, or materials_id or full criteria.

Parameters:

db (MongoStore) – MongoStore object with database connection
chemsys_formula_id_criteria (str | dict) – A chemical system (e.g., Li-Fe-O), or formula (e.g., Fe2O3) or materials_id (e.g., mp-1234) or full Mongo-style dict criteria.
compatible_only (bool) – Whether to return only “compatible” entries. Compatible entries are entries that have been processed using the MaterialsProjectCompatibility class, which performs adjustments to allow mixing of GGA and GGA+U calculations for more accurate phase diagrams and reaction energies.
inc_structure (str | None) – If None, entries returned are ComputedEntries. If inc_structure=”initial”, ComputedStructureEntries with initial structures are returned. Otherwise, ComputedStructureEntries with final structures are returned.
property_data (list[str] | None) – Specify additional properties to include in entry.data. If None, no data. Should be a subset of supported_properties.
use_premade_entries (bool) – Whether to use entry objects that have already been constructed. Defaults to False.
conventional_unit_cell (bool) – Whether to get the standard conventional unit cell
sort_by_e_above_hull (bool) – Whether to sort the list of entries by e_above_hull (will query e_above_hull as a property_data if True).

Returns:

List of ComputedEntry or ComputedStructureEntry objects.

rxn_network.entries.utils.get_all_entries_in_chemsys(db, elements, compatible_only=True, inc_structure='final', property_data=None, use_premade_entries=False, conventional_unit_cell=False, n=1000)[source]#

Warning

Helper method for getting all entries in a total chemical system by querying database for all sub-chemical systems. Code adadpted from pymatgen.ext.matproj and modified to support very large chemical systems.

Parameters:

db (MongoStore) – MongoStore object with database connection
elements (str or [str]) – Chemical system string comprising element symbols separated by dashes, e.g., “Li-Fe-O” or List of element symbols, e.g., [“Li”, “Fe”, “O”].
compatible_only (bool) – Whether to return only “compatible” entries. Compatible entries are entries that have been processed using the MaterialsProjectCompatibility class, which performs adjustments to allow mixing of GGA and GGA+U calculations for more accurate phase diagrams and reaction energies.
inc_structure (str) – If None, entries returned are ComputedEntries. If inc_structure=”final”, ComputedStructureEntries with final structures are returned. Otherwise, ComputedStructureEntries with initial structures are returned.
property_data (list) – Specify additional properties to include in entry.data. If None, no data. Should be a subset of supported_properties.
use_premade_entries (bool) – Whether to use entry objects that have already been constructed. Defaults to False.
conventional_unit_cell (bool) – Whether to get the standard conventional unit cell
n (int) – Chunk size, i.e., number of sub-chemical systems to consider

Returns:

List of ComputedEntries.

Return type:

list[ComputedEntry]

rxn_network.entries.utils.parse_criteria(criteria_string)[source]#

Parses a powerful and simple string criteria and generates a proper mongo syntax criteria.

Parameters:

criteria_string (str) –

A string representing a search criteria. Also supports wild cards. E.g., something like “*2O” gets converted to {‘pretty_formula’: {‘$in’: [u’B2O’, u’Xe2O’, u”Li2O”, …]}}

Other syntax examples:: mp-1234: Interpreted as a Materials ID. Fe2O3 or *2O3: Interpreted as reduced formulas. Li-Fe-O or *-Fe-O: Interpreted as chemical systems.

You can mix and match with spaces, which are interpreted as “OR”. E.g., “mp-1234 FeO” means query for all compounds with reduced formula FeO or with materials_id mp-1234.

Returns:

A mongo query dict.