rxn_network.enumerators#

rxn_network.enumerators.base#

Basic interface for a reaction Enumerator.

class rxn_network.enumerators.base.Enumerator(precursors, targets)[source]#

Bases: MSONable

Base definition for a class that enumerates reactions.

Parameters:

  • precursors (Collection[str | Composition] | None) – Precursor compositions or formulas.

  • targets (Collection[str | Composition] | None) – Target compositions or formulas.

abstract enumerate(entries)[source]#

Enumerates the potential reactions from the list of entries.

Parameters:

entries (GibbsEntrySet) –

rxn_network.enumerators.basic#

This module implements two types of basic (combinatorial) reaction enumerators.

class rxn_network.enumerators.basic.BasicEnumerator(precursors=None, targets=None, n=2, exclusive_precursors=True, exclusive_targets=False, filter_duplicates=False, filter_by_chemsys=None, chunk_size=2500, max_num_jobs=5000, remove_unbalanced=True, remove_changed=True, max_num_constraints=1, quiet=False)[source]#

Bases: Enumerator

Enumerator for finding all simple reactions within a set of entries, up to a maximum reactant/product cardinality (n); i.e., how many phases on either side of the reaction. This approach does not explicitly take into account thermodynamic stability (i.e. phase diagram). This allows for enumeration of reactions where the products may not be stable with respect to each other.

If you use this code in your own work, please consider citing this paper:

McDermott, M. J.; Dwaraknath, S. S.; Persson, K. A. A Graph-Based Network for Predicting Chemical Reaction Pathways in Solid-State Materials Synthesis. Nature Communications 2021, 12 (1), 3097. https://doi.org/10.1038/s41467-021-23339-x.

Initialize a BasicEnumerator object.

Parameters:

  • precursors (list[str] | None) – Optional list of precursor formulas. The only reactions that will be enumerated are those featuring one or more of these compositions as reactants. The “exclusive_precursors” parameter allows one to tune whether the enumerated reactions should include ALL precursors (the default) or just one.

  • targets (list[str] | None) – Optional list of target formulas. The only reactions that will be enumerated are those featuring one or more of these compositions as products. The “exclusive_targets” parameter allows one to tune whether the enumerated reactions should include ALL targets or just one (the default).

  • n (int) – Maximum reactant/product cardinality. This it the largest possible number of entries on either side of the reaction. Defaults to 2.

  • exclusive_precursors (bool) – Whether enumerated reactions are required to have reactants that are a subset of the provided list of precursors. If True (the default), this only identifies reactions with reactants selected from the provided precursors.

  • exclusive_targets (bool) – Whether enumerated reactions are required to have products that are a subset of the provided list of targets. If False, (the default), this identifies all reactions containing at least one composition from the provided list of targets (and any number of byproducts).

  • filter_duplicates (bool) – Whether to remove duplicate reactions. Defaults to False.

  • filter_by_chemsys (str | None) – An optional chemical system for which to filter produced reactions by. This ensures that all output reactions contain at least one element within the provided system.

  • chunk_size (int) – The minimum number of reactions per chunk procssed. Needs to be sufficiently large to make parallelization a cost-effective strategy. Defaults to MIN_CHUNK_SIZE.

  • max_num_jobs (int) – The upper limit for the number of jobs created. Defaults to MAX_NUM_JOBS.

  • remove_unbalanced (bool) – Whether to remove reactions which are unbalanced; this is usually advisable. Defaults to True.

  • remove_changed (bool) – Whether to remove reactions which can only be balanced by removing a reactant/product or having it change sides. This is also advisable for ensuring that only unique reaction sets are produced. Defaults to True.

  • max_num_constraints (int) – The maximum number of allowable constraints enforced by reaction balancing. Defaults to 1 (which is usually advisable).

  • quiet (bool) – Whether to run in quiet mode (no progress bar). Defaults to False.

enumerate(entries)[source]#

Calculate all possible reactions given a set of entries. If the enumerator was initialized with specified precursors or target, the reactions will be filtered by these constraints. Every enumerator follows a standard procedure.

Steps:

  1. Initialize entries, i.e., ensure that precursors and target are considered stable entries within the entry set.

  2. Get a dictionary representing every possible “node”, i.e. phase combination, grouped by chemical system.

  3. Filter the combos dictionary for chemical systems which are not relevant; i.e., don’t contain elements in precursors and/or target.

  4. Iterate through each chemical system, initializing calculators, and computing all possible reactions for reactant/product pair and/or thermodynamically predicted reactions for given reactants.

  5. Add reactions to growing list, repeat Step 4 until combos dict exhausted.

Parameters:

entries (GibbsEntrySet) – the set of all entries to enumerate from

Return type:

ReactionSet

property stabilize: bool#

Whether or not to use only stable entries in analysis.

property build_pd: bool#

Whether or not to build a PhaseDiagram object during reaction enumeration (useful for some analyses).

property build_grand_pd: bool#

Whether or not to build a GrandPotentialPhaseDiagram object during reaction enumeration (useful for some analyses).

class rxn_network.enumerators.basic.BasicOpenEnumerator(open_phases, precursors=None, targets=None, n=2, exclusive_precursors=True, exclusive_targets=False, filter_duplicates=False, filter_by_chemsys=None, chunk_size=2500, max_num_jobs=5000, remove_unbalanced=True, remove_changed=True, max_num_constraints=1, quiet=False)[source]#

Bases: BasicEnumerator

Enumerator for finding all simple reactions within a set of entries, up to a maximum reactant/product cardinality (n), with any number of open phases. Note: this does not return OpenComputedReaction objects (this can be calculated using the ReactionSet class).

If you use this code in your own work, please consider citing this paper:

McDermott, M. J.; Dwaraknath, S. S.; Persson, K. A. A Graph-Based Network for Predicting Chemical Reaction Pathways in Solid-State Materials Synthesis. Nature Communications 2021, 12 (1), 3097. https://doi.org/10.1038/s41467-021-23339-x.

Supplied target and calculator parameters are automatically initialized as objects during enumeration.

Parameters:

  • open_phases (list[str]) – List of formulas of open entries (e.g. [“O2”]).

  • precursors (list[str] | None) – Optional list of precursor formulas. The only reactions that will be enumerated are those featuring one or more of these compositions as reactants. The “exclusive_precursors” parameter allows one to tune whether the enumerated reactions should include ALL precursors (the default) or just one.

  • targets (list[str] | None) – Optional list of target formulas. The only reactions that will be enumerated are those featuring one or more of these compositions as products. The “exclusive_targets” parameter allows one to tune whether the enumerated reactions should include ALL targets or just one (the default).

  • n (int) – Maximum reactant/product cardinality. This it the largest possible number of entries on either side of the reaction. Defaults to 2.

  • exclusive_precursors (bool) – Whether enumerated reactions are required to have reactants that are a subset of the provided list of precursors. If True (the default), this only identifies reactions with reactants selected from the provided precursors.

  • exclusive_targets (bool) – Whether enumerated reactions are required to have products that are a subset of the provided list of targets. If False, (the default), this identifies all reactions containing at least one composition from the provided list of targets (and any number of byproducts).

  • filter_duplicates (bool) – Whether to remove duplicate reactions. Defaults to False.

  • filter_by_chemsys (str | None) – An optional chemical system for which to filter produced reactions by. This ensures that all output reactions contain at least one element within the provided system.

  • chunk_size (int) – The minimum number of reactions per chunk procssed. Needs to be sufficiently large to make parallelization a cost-effective strategy. Defaults to MIN_CHUNK_SIZE.

  • max_num_jobs (int) – The upper limit for the number of jobs created. Defaults to MAX_NUM_JOBS.

  • remove_unbalanced (bool) – Whether to remove reactions which are unbalanced; this is usually advisable. Defaults to True.

  • remove_changed (bool) – Whether to remove reactions which can only be balanced by removing a reactant/product or having it change sides. This is also advisable for ensuring that only unique reaction sets are produced. Defaults to True.

  • max_num_constraints (int) – The maximum number of allowable constraints enforced by reaction balancing. Defaults to 1 (which is usually advisable).

  • quiet (bool) – Whether to run in quiet mode (no progress bar). Defaults to False.

rxn_network.enumerators.minimize#

This module implements two types of reaction enumerators using a free energy minimization technique, with or without the option of an open entry.

class rxn_network.enumerators.minimize.MinimizeGibbsEnumerator(precursors=None, targets=None, exclusive_precursors=True, exclusive_targets=False, filter_duplicates=False, filter_by_chemsys=None, chunk_size=1000, max_num_jobs=1000, remove_unbalanced=True, remove_changed=True, max_num_constraints=1, quiet=False)[source]#

Bases: BasicEnumerator

Enumerator for finding all reactions between two reactants that are predicted by thermodynamics; i.e., they appear when taking the convex hull along a straight line connecting any two phases in G-x phase space. Identity reactions are automatically excluded.

If you use this code in your own work, please consider citing this paper:

McDermott, M. J.; Dwaraknath, S. S.; Persson, K. A. A Graph-Based Network for Predicting Chemical Reaction Pathways in Solid-State Materials Synthesis. Nature Communications 2021, 12 (1), 3097. https://doi.org/10.1038/s41467-021-23339-x.

Initialize a MinimizeGibbsEnumerator.

Parameters:

  • precursors (list[str] | None) – Optional list of precursor formulas. The only reactions that will be enumerated are those featuring one or more of these compositions as reactants. The “exclusive_precursors” parameter allows one to tune whether the enumerated reactions should include ALL precursors (the default) or just one.

  • targets (list[str] | None) – Optional list of target formulas. The only reactions that will be enumerated are those featuring one or more of these compositions as products. The “exclusive_targets” parameter allows one to tune whether the enumerated reactions should include ALL targets or just one (the default).

  • exclusive_precursors (bool) – Whether enumerated reactions are required to have reactants that are a subset of the provided list of precursors. If True (the default), this only identifies reactions with reactants selected from the provided precursors.

  • exclusive_targets (bool) – Whether enumerated reactions are required to have products that are a subset of the provided list of targets. If False, (the default), this identifies all reactions containing at least one composition from the provided list of targets (and any number of byproducts).

  • filter_duplicates (bool) – Whether to remove duplicate reactions. Defaults to False.

  • filter_by_chemsys (str | None) – An optional chemical system for which to filter produced reactions by. This ensures that all output reactions contain at least one element within the provided system.

  • chunk_size (int) – The minimum number of reactions per chunk procssed. Needs to be sufficiently large to make parallelization a cost-effective strategy. Defaults to MIN_CHUNK_SIZE.

  • max_num_jobs (int) – The upper limit for the number of jobs created. Defaults to MAX_NUM_JOBS.

  • remove_unbalanced (bool) – Whether to remove reactions which are unbalanced; this is usually advisable. Defaults to True.

  • remove_changed (bool) – Whether to remove reactions which can only be balanced by removing a reactant/product or having it change sides. This is also advisable for ensuring that only unique reaction sets are produced. Defaults to True.

  • max_num_constraints (int) – The maximum number of allowable constraints enforced by reaction balancing. Defaults to 1 (which is usually advisable).

  • quiet (bool) – Whether to run in quiet mode (no progress bar). Defaults to False.

class rxn_network.enumerators.minimize.MinimizeGrandPotentialEnumerator(open_elem, mu, precursors=None, targets=None, exclusive_precursors=True, exclusive_targets=False, filter_duplicates=False, filter_by_chemsys=None, chunk_size=1000, max_num_jobs=1000, remove_unbalanced=True, remove_changed=True, max_num_constraints=1, quiet=False)[source]#

Bases: MinimizeGibbsEnumerator

Enumerator for finding all reactions between two reactants and an open element that are predicted by thermo; i.e., they appear when taking the convex hull along a straight line connecting any two phases in Phi-x phase space. Identity reactions are excluded.

If you use this code in your own work, please consider citing this paper:

McDermott, M. J.; Dwaraknath, S. S.; Persson, K. A. A Graph-Based Network for Predicting Chemical Reaction Pathways in Solid-State Materials Synthesis. Nature Communications 2021, 12 (1), 3097. https://doi.org/10.1038/s41467-021-23339-x.

Parameters:

  • open_elem (Element) – The element to be considered as open.

  • mu (float) – The chemical potential of the open element (eV).

  • precursors (list[str] | None) – Optional list of precursor formulas. The only reactions that will be enumerated are those featuring one or more of these compositions as reactants. The “exclusive_precursors” parameter allows one to tune whether the enumerated reactions should include ALL precursors (the default) or just one.

  • targets (list[str] | None) – Optional list of target formulas. The only reactions that will be enumerated are those featuring one or more of these compositions as products. The “exclusive_targets” parameter allows one to tune whether the enumerated reactions should include ALL targets or just one (the default).

  • exclusive_precursors (bool) – Whether enumerated reactions are required to have reactants that are a subset of the provided list of precursors. If True (the default), this only identifies reactions with reactants selected from the provided precursors.

  • exclusive_targets (bool) – Whether enumerated reactions are required to have products that are a subset of the provided list of targets. If False, (the default), this identifies all reactions containing at least one composition from the provided list of targets (and any number of byproducts).

  • filter_duplicates (bool) – Whether to remove duplicate reactions. Defaults to False.

  • filter_by_chemsys (str | None) – An optional chemical system for which to filter produced reactions by. This ensures that all output reactions contain at least one element within the provided system.

  • chunk_size (int) – The minimum number of reactions per chunk procssed. Needs to be sufficiently large to make parallelization a cost-effective strategy. Defaults to MIN_CHUNK_SIZE.

  • max_num_jobs (int) – The upper limit for the number of jobs created. Defaults to MAX_NUM_JOBS.

  • remove_unbalanced (bool) – Whether to remove reactions which are unbalanced; this is usually advisable. Defaults to True.

  • remove_changed (bool) – Whether to remove reactions which can only be balanced by removing a reactant/product or having it change sides. This is also advisable for ensuring that only unique reaction sets are produced. Defaults to True.

  • max_num_constraints (int) – The maximum number of allowable constraints enforced by reaction balancing. Defaults to 1 (which is usually advisable).

  • quiet (bool) – Whether to run in quiet mode (no progress bar). Defaults to False.

rxn_network.enumerators.utils#

Utility functions used by the reaction enumerator classes.

rxn_network.enumerators.utils.get_computed_rxn(rxn, entries, chempots=None)[source]#

Provided with a Reaction object and a list of possible entries, this function returns a new ComputedReaction object containing a selection of those entries.

Parameters:

  • rxn (Reaction) – Reaction object

  • entries (GibbsEntrySet) – Iterable of entries

  • chempots (dict[Element, float] | None) – Optional dictionary of chemical potentials (will return an OpenComputedReaction if supplied).

Returns:

A ComputedReaction object transformed from a normal Reaction object

Return type:

ComputedReaction | OpenComputedReaction

rxn_network.enumerators.utils.react_interface(r1, r2, filtered_entries, pd, grand_pd=None)[source]#

Simple API for InterfacialReactivity module from pymatgen.

Parameters:
rxn_network.enumerators.utils.get_elems_set(entries)[source]#

Returns chemical system as a set of element names, for set of entries.

Parameters:

entries (Iterable[Entry]) – An iterable of entry-like objects

Returns:

Set of element names (strings).

Return type:

set[str]

rxn_network.enumerators.utils.get_total_chemsys_str(entries, open_elems=None)[source]#

Returns chemical system string for set of entries, with optional open element.

Parameters:

  • entries (Iterable[Entry]) – An iterable of entry-like objects

  • open_elems (Iterable[Element] | None) – optional open elements to include in chemical system

Return type:

str

rxn_network.enumerators.utils.group_by_chemsys(combos, open_elems=None)[source]#

Groups entry combinations by chemical system, with optional open element.

Parameters:

  • combos (Iterable[tuple[Entry, ...]]) – Iterable of entry combinations

  • open_elems (Iterable[Element] | None) – optional open elements to include in chemical system grouping

Returns:

Dictionary of entry combos grouped by chemical system

Return type:

dict

rxn_network.enumerators.utils.stabilize_entries(pd, entries_to_adjust, tol=1e-06)[source]#

Simple method for stabilizing entries by decreasing their energy to be on the hull.

WARNING: This method is not guaranteed to work simultaneously for all entries due to the fact that stabilization of one entry may destabilize others. Use with caution.

Parameters:

  • pd (PhaseDiagram) – PhaseDiagram object

  • entries_to_adjust (Iterable[Entry]) – Iterable of entries requiring energies to be adjusted

  • tol (float) – Numerical tolerance to ensure that the energy of the entry is below the hull

Returns:

A list of new entries with energies adjusted to be on the hull

Return type:

list[Entry]

rxn_network.enumerators.utils.run_enumerators(enumerators, entries)[source]#

Utility method for calling enumerate() for a list of enumerators on a particular set of entries. Reaction sets are automatically combined and duplicates are filtered.

Parameters:

  • enumerators (Iterable[Enumerator]) – an iterable of enumerators to use for reaction enumeration

  • entries (GibbsEntrySet) – an entry set to provide to the enumerate() function.