rxn_network.jobs

rxn_network.jobs.core

Core jobs for reaction network creation and analysis.

class rxn_network.jobs.core.GetEntrySetMaker(name='get_and_process_entries', temperature=300, e_above_hull=0.0, filter_at_temperature=None, include_nist_data=True, include_freed_data=False, include_polymorphs=False, formulas_to_include=<factory>, calculate_e_above_hulls=True, ignore_nist_solids=True, custom_entries=<factory>, MP_API_KEY=None, entry_db_name=None, property_data=None)

Bases: Maker

Maker to create job for acquiring and processing entries to be used in reaction enumeration or network building. See GibbsEntrySet for more information about how these are constructed.

Parameters:

• name (str) – Name of the job.

• temperature (int) – 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!

• formulas_to_include (list[str]) – 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. Defaults to True.

• ignore_nist_solids (bool) – Whether to ignore NIST data for solids with high melting points (Tm >= 1500 ºC). Defaults to True.

• custom_entries (list) – An optional list of user-created entries that will be added to the final entry set.

• MP_API_KEY (str | None) – The Materials Project API key to use for querying MP using mp-api. If not provided, this will default to whatever is stored through configuration settings on the user’s machine.

• entry_db_name (for internal use only) – if not None, then this method will use an internal materials databse using the get_all_entries_in_chemsys() method. If you wish to use this approach, you may need to reconfigure that method.

• property_data (list[str] | None) – a list of attributes to ensure are included in each entry’s data, if available. This currently only applies to those using a custom entry DB (see above).

• include_polymorphs (bool) –

make(chemsys)

Returns a job that acquires a GibbsEntrySet for the desired chemical system.

NOTE: This job stores the entry set in an additional store called “entries”. This needs to be configured through a user’s jobflow.yaml file. See “additional_stores”.

Parameters:

chemsys (str) – The chemical system of the entry set to be acquired.

class rxn_network.jobs.core.ReactionEnumerationMaker(name='enumerate_reactions')

Bases: Maker

Maker to create a job for enumerating reactions from a set of entries. This is effectively a wrapper to the run_enumerators() function (see enumerators.utils) with a defined output document.

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:

name (str) – The name of the job. This is automatically created if not provided.

make(enumerators, entries)

Returns a job that enumerates reactions from a set of entries.

NOTE: This job stores the reaction set in an additional store called “rxns”. This needs to be configured through a user’s jobflow.yaml file. See “additional_stores”.

Parameters:

• enumerators (Iterable[Enumerator]) – An iterable of enumerators to perform enumeration (e.g., [BasicEnumerator, BasicOpenEnumerator])

• entries (GibbsEntrySet) – An entry set provided to each of the enumerators

class rxn_network.jobs.core.CalculateCompetitionMaker(name='calculate_competition', open_elem=None, chempot=0.0, calculate_competition=True, calculate_chempot_distances=True, chunk_size=100, cpd_kwargs=<factory>)

Bases: Maker

Maker to create job for calculating selectivities of a set of reactions given a provided target formula. This is a component of the SynthesisPlanningFlowMaker.

If you use this code in your work, please cite the following work:

McDermott, M. J. et al. Assessing Thermodynamic Selectivity of Solid-State Reactions for the Predictive Synthesis of Inorganic Materials. ACS Cent. Sci. (2023) doi:10.1021/acscentsci.3c01051.

Parameters:

• name (str) – The name of the job. Automatically created if not provided.

• open_elem (Element | None) – An optional open element for performing selectivity calculations

• chempot (float) – A (relative) chemical potential of the open element, if any. Defaults to 0 eV/atom.

• calculate_competition (bool) – Whether or not to calculate competition scores for reactions. See PrimaryCompetitionCalculator and SecondaryCompetitionCalculator. Defaults to True.

• calculate_chempot_distances (bool) – Whether or not to calculate chemical potential distances for reactions. See ChempotDistanceCalculator. Defaults to True.

• chunk_size (int) – The number of reactions to put into each parallelized chunk. See class variable, CHUNK_SIZE. This will automatically be re-computed if out-of-memory issues are anticipated.

• cpd_kwargs (dict) – Optional keyword arguments passed to ChempotDistanceCalculator.

make(rxn_sets, entries, target_formula)

Returns a job that calculates competition scores and/or chemical potential distances for all synthesis reactions to a target phase given a provided list of reaction sets.

NOTE: This job stores the reaction set in an additional store called “rxns”. This needs to be configured through a user’s jobflow.yaml file. See “additional_stores”.

Parameters:

• rxn_sets (list[ReactionSet]) – a list of reaction sets making up all enumerated reactions in the chemical reaction network of interest. These will automatically be combined and reprocessed to match the specified conditions (open_elem + chempot).

• entries (GibbsEntrySet) – The entry set used to enumerate all provided reactions. This will be used to facilitate selectivity calculations and ensure all reaction sets can be easily combined.

• target_formula (str) – The formula of the desired target phase. This will be used to identify all synthesis reactions (i.e., those that produce the target).

Returns:

A job that returns synthesis reactions to the target phase, decorated with the relevant selectivity metrics.

class rxn_network.jobs.core.NetworkMaker(name='build_and_analyze_network', cost_function=<factory>, precursors=None, targets=None, calculate_pathways=10, open_elem=None, chempot=0.0)

Bases: Maker

Maker for generating reaction networks and performing pathfinding from a set of previously enumerated reactions. This is a component of the NetworkFlowMaker.

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:

• name (str) – The name of the job. Automatically selected if not provided.

• cost_function (CostFunction) – The cost function used to calculate the edge weights in the network.

• precursors (list[str] | None) – An optional list of precursor formulas used in call to set_precursors().

• targets (list[str] | None) – An optional list of target formulas used in calls to set_target() as part of pathfinding.

• calculate_pathways (int | None) – If integer is provided, basic pathfinding is performed using the find_pathways() function up to the provided number of paths (k). Defaults to k=10. Provide a value of None if no pathfinding is to be performed.

• open_elem (Element | None) – An optional open element used to re-initialize the total reaction set.

• chempot (float) – The chemical potential of the open element, if any. Defaults to 0.

make(rxn_sets)

Returns a job that creates a reaction network from an iterable of reaction sets (coming from reaction enumeration).

NOTE: This job stores the network object in an additional store called “network”. This needs to be configured through a user’s jobflow.yaml file. See “additional_stores”.

Parameters:

rxn_sets (Iterable[ReactionSet]) – An iterable of reaction sets produced by reaction enumeration. These are combined, re-initialized according to provided environmental conditions, and then used to build the network.

Returns:

A job that builds and stores the reaction network for enumerated reactions. Also performs basic pathfinding (but no balancing; see PathwaySolverMaker).

class rxn_network.jobs.core.PathwaySolverMaker(name='solve pathways', cost_function=<factory>, precursors=<factory>, targets=<factory>, open_elem=None, chempot=0.0, max_num_combos=4, find_intermediate_rxns=True, intermediate_rxn_energy_cutoff=0.0, use_basic_enumerator=True, use_minimize_enumerator=False, filter_interdependent=True)

Bases: Maker

Maker for solving balanced reaction pathways from a set of (unbalanced) pathways returned as part of reaction network analysis.

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:

• name (str) – The name of the job. Automatically selected if not provided.

• cost_function (CostFunction) – The cost function used to calculate the weights of any new edges identified during solving (e.g., for intermediate reactions).

• precursors (list[str]) – The precursor formulas for the overall net reaction. These must be provided and result in a valid net reaction (together with the targets).

• targets (list[str]) – The target formulas for the overall net reaction. These must be provided and result in a valid net reaction (together with the precursors).

• open_elem (Element | None) – An optional open element used by PathwaySolver.

• chempot (float) – The chemical potential of the open element, if any. Defaults to 0.

• max_num_combos (int) – The maximum allowable size of the balanced reaction pathway. At values <=5, the solver will start to take a significant amount of time to run.

• find_intermediate_rxns (bool) – Whether to find intermediate reactions; crucial for finding pathways where intermediates react together, as these reactions may not occur in the graph-derived pathways. Defaults to True.

• intermediate_rxn_energy_cutoff (float) – An energy cutoff by which to filter down intermediate reactions. This can be useful when there are a large number of possible intermediates. < 0 means allow only exergonic reactions.

• use_basic_enumerator (bool) – Whether to use the BasicEnumerator to find intermediate reactions. Defaults to True.

• use_minimize_enumerator (bool) – Whether to use the MinimizeGibbsEnumerator to find intermediate reactions. Defaults to False.

• filter_interdependent (bool) – Whether or not to filter out pathways where reaction steps are interdependent. Defaults to True.

make(pathways, entries)

Returns a job that produces balanced pathways from raw pathways coming out of network pathfinding.

NOTE: This job stores the network object in an additional store called “paths”. This needs to be configured through a user’s jobflow.yaml file. See “additional_stores”.

Parameters:

• pathways (PathwaySet) – A set of pathways (as returned by find_pathways()).

• entries (GibbsEntrySet) – The entry set to use in path solving.

rxn_network.jobs.schema

Core definition for various task and synthesis recipe documents.

pydantic model rxn_network.jobs.schema.EntrySetDocument

Bases: BaseModel

A single entry set object as produced by the GetEntrySet job.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

field task_label: str | None = None

The name of the task.

field last_updated: str [Optional]

Timestamp of when the document was last updated.

field entries: GibbsEntrySet [Required]

The entry set object.

field e_above_hull: float | None = None

The e_above_hull cutoff.

field include_polymorphs: bool = False

Whether to include metastable polymorphs in the entry set.

field formulas_to_include: list[str] | None = None

The required formulas to include during construciton.

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

pydantic model rxn_network.jobs.schema.EnumeratorTaskDocument

Bases: BaseModel

A single task object from the reaction enumerator workflow.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

field task_label: str | None = None

The name of the task.

field last_updated: str [Optional]

Timestamp of when the document was last updated.

field rxns: ReactionSet [Required]

The reaction set.

field targets: list[str] | None = None

The target formulas used in the enumerator(s).

field elements: list[Element] | None = None

The elements of the total chemical system

field chemsys: str | None = None

The total chemical system string (e.g., Fe-Li-O).

field added_elements: list[Element] | None = None

The elements added beyond the elements of the target(s).

field added_chemsys: str | None = None

The chemical system of the added elements

field enumerators: list[Enumerator] | None = None

A list of the enumerator objects used to calculate the reactions.

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

pydantic model rxn_network.jobs.schema.CompetitionTaskDocument

Bases: BaseModel

A document containing the reactions and their selectivities as created by the CalculateCompetitionMaker job.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

field task_label: str | None = None

The name of the task.

field last_updated: str [Optional]

Timestamp of when the document was last updated.

field rxns: ReactionSet [Required]

The reaction set, where thereactions have calculated competition information stored in their data attribute.

field target_formula: str [Required]

The reduced chemical formula of the target material.

field open_elem: Element | None = None

The open element (if any).

field chempot: float | None = None

The chemical potential of the open element.

field added_elements: list[Element] | None = None

The elements added beyond the elements of the target(s).

field added_chemsys: str | None = None

The chemical system of the added elements.

field calculate_competition: bool | None = None

Whether to calculate competition scores.

field calculate_chempot_distances: bool | None = None

Whether to calculate chemical potential distances.

field temp: float | None = None

The temperature in K used to determine the primary competition weightings.

field batch_size: int | None = None

The batch size for the reaction set

field cpd_kwargs: dict[str, Any] | None = None

The kwargs for ChempotDistanceCalculator.

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

pydantic model rxn_network.jobs.schema.NetworkTaskDocument

Bases: BaseModel

The calculation output from the NetworkMaker workflow.

Optionally includes unbalanced paths found during pathfinding.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

field task_label: str | None = None

The name of the task.

field last_updated: str [Optional]

Timestamp of when the document was last updated.

field network: Network [Required]

The reaction network

field paths: PathwaySet | None = None

The (simple/unbalanced) reaction pathways

field k: int | None = None

The number of paths solved for, if any.

field precursors: list[str] | None = None

The precursor formulas.

field targets: list[str] | None = None

The target formulas.

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

pydantic model rxn_network.jobs.schema.PathwaySolverTaskDocument

Bases: BaseModel

The calculation output from the PathwaySolverMaker workflow. Contains the pathway solver object and its calculated balanced pathways.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

field task_label: str | None = None

The name of the task.

field last_updated: str [Optional]

Timestamp of when the document was last updated.

field solver: Solver [Required]

The pathway solver used to calculate pathways.

field balanced_paths: PathwaySet [Required]

The balanced reaction pathways.

field precursors: list[str] [Required]

The precursor compositions.

field targets: list[str] [Required]

The target compositions.

field net_rxn: ComputedReaction [Required]

The net reaction used for pathway solving.

field max_num_combos: int [Required]

The maximum number of combinations to consider in the pathway solver.

field find_intermediate_rxns: bool [Required]

Whether to find reactions from intermediate compositions.

field intermediate_rxn_energy_cutoff: float [Required]

The mximum energy cutoff for filtering intermediate reactions.

field use_basic_enumerator: bool [Required]

Whether to use the basic enumerators in path solving.

field use_minimize_enumerator: bool [Required]

Whether to use the minimize enumerators in path solving.

field filter_interdependent: bool [Required]

Whether to filter out interdependent pathway.s

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

rxn_network.jobs.utils

Definitions of common job functions.

rxn_network.jobs.utils.get_added_elem_data(entries, targets)

Given a provided entry set and targets, this identifies which elements in the entry set are “additional” (not found in the target).

Parameters:

• entries (GibbsEntrySet) – the full entry set

• targets (Iterable[Composition | str]) – the target phase compositions

Returns:

A tuple of the additional elements and their chemical system string.

Return type:

tuple[list[Element], str]