rxn_network.network#

rxn_network.network.base#

Basic interface for a reaction network and its graph.

class rxn_network.network.base.Network(rxns, cost_function)[source]#

Bases: MSONable

Base definition for a reaction network.

Parameters:

rxns (ReactionSet) – A ReactionSet object containing the reactions that form the network edges.
cost_function (CostFunction) – A CostFunction object used to evaluate reaction properties and assign edge weights.

abstract build()[source]#

Construct the network in-place from the supplied enumerators.

Return type:: None

abstract find_pathways(target, k)[source]#

Find reaction pathways.

Return type:: list[Pathway]

abstract set_precursors(precursors)[source]#

Set the phases used as precursors in the network (in-place).

Parameters:: precursors (Iterable[Entry | str]) –
Return type:: None

abstract set_target(target)[source]#

Set the phase used as a target in the network (in-place).

Parameters:: target (Entry | str) –
Return type:: None

as_dict()[source]#

Returns MSONable dict for serialization. See monty package for more information.

Return type:: dict

classmethod from_dict(d)[source]#

Instantiate object from MSONable dict. See monty package for more information.

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

property precursors: set[Entry] | None#: The phases used as precursors in the network.

property target: Entry | None#: The phase used as a target in the network.

property graph#: Returns the network’s Graph object.

property chemsys: str#: A string representing the chemical system (elements) of the network.

class rxn_network.network.base.Graph(check_cycle=False, multigraph=True, attrs=None, /)[source]#

Bases: PyDiGraph

Thin wrapper around rx.PyDiGraph to allow for serialization and optimized database storage.

as_dict()[source]#

Represents the PyDiGraph object as a serializable dictionary.

See monty package (MSONable) for more information.

Return type:: dict

classmethod from_dict(d)[source]#

Instantiates a Graph object from a dictionary.

See as_dict() and monty package (MSONable) for more information.

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

rxn_network.network.entry#

Entry objects used in a Network. These network entry objects hold multiple entries and can be used as data for a node in the graph.

class rxn_network.network.entry.NetworkEntryType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Describes the Network Entry Type.

class rxn_network.network.entry.NetworkEntry(entries, description)[source]#

Bases: MSONable

Helper class for describing combinations of ComputedEntry-like objects in context of a reaction network. This entry will represent a node in the network.

Args: entries: Collection of Entry-like objects description: Node type (e.g., Precursors, Target… see NetworkEntryType class).

Parameters:

entries (Collection[Entry]) –
description (NetworkEntryType) –

property entries: set[Entry]#: Entries contained in this NetworkEntry.

property elements: list[Element]#: Elements contained in this NetworkEntry.

property chemsys: str#: Chemical system of this NetworkEntry.

property dim: int#: Number of elements in this NetworkEntry.

property description: NetworkEntryType#: A description of the NetworkEntry (given as NetworkEntryType).

as_dict()[source]#

MSONable dict representation.

Return type:: dict

classmethod from_dict(d)[source]#

Load from MSONable dict.

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

class rxn_network.network.entry.DummyEntry[source]#

Bases: NetworkEntry

A Dummy Entry that doesn’t hold any info. This maybe useful for serving as an empty node to facilitate pathfinding to all nodes, etc.

Dummy node doesn’t need any parameters.

rxn_network.network.network#

Implementation of reaction network and graph classes.

class rxn_network.network.network.ReactionNetwork(rxns, cost_function=None)[source]#

Bases: Network

Main reaction network class for building graph networks and performing pathfinding. Graphs are built using the rustworkx package (a NetworkX equivalent implemented in Rust).

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 ReactionNetwork object for a reaction set and cost function.

To build the graph network, call the build() method in-place.

Parameters:

rxns (ReactionSet) – Set of reactions used to construct the network.
cost_function (CostFunction | None) – The function used to calculate the cost of each reaction edge. Defaults to a Softplus function with default settings (i.e. energy_per_atom only).

build()[source]#

In-place method. Construct the reaction network graph object and store under the “graph” attribute.

WARNING: This does NOT initialize the precursors or target attributes; you must call set_precursors() or set_target() to do so.

Returns:: None
Return type:: None

find_pathways(targets, k=15)[source]#

Find the k-shortest paths to a provided list of one or more targets.

Parameters:

targets (list[Entry | str]) – List of the formulas or entry objects of each target.
k (int) – Number of k-shortest paths to find for each target. Defaults to 15.

Returns:

List of BasicPathway objects to all provided targets.

Return type:

list[BasicPathway]

set_precursors(precursors)[source]#

In-place method. Sets the precursors of the network. Removes all references to previous precursors.

If entries are provided, will use the entries to set the precursors. If strings are provided, will automatically find the lowest-energy entries with matching reduced_formula.

Parameters:: precursors (Iterable[Entry | str]) – iterable of entries/formulas of precursor phases.
Returns:: None

set_target(target)[source]#

In-place method. Can only provide one target entry or formula at a time.

If entry is provided, will use that entry to set the target. If string is provided, will automatically find minimum-energy entry with matching reduced_formula.

Parameters:: target (Entry | str) – Entry, or string of reduced formula, of target phase.
Returns:: None
Return type:: None

rxn_network.network.network.get_rxn_nodes_and_edges(rxns)[source]#

Given a reaction set, return a list of nodes and edges for constructing the reaction network.

Parameters:: rxns (ReactionSet) – a list of enumerated ComputedReaction objects to build a network from.
Returns:: A tuple consisting of (nodes, edges) where nodes is a list of NetworkEntry objects and edges is a list of tuples of the form (source_idx, target_idx, reaction).
Return type:: tuple[list[NetworkEntry], list[tuple[int, int, Reaction]]]

rxn_network.network.network.get_loopback_edges(nodes)[source]#

Given a list of nodes to check, this function finds and returns loopback edges (i.e., edges that connect a product node to its equivalent reactant node).

Parameters:: nodes (list[NetworkEntry]) – List of vertices from which to find loopback edges
Returns:: A list of tuples of the form (source_idx, target_idx, reaction)
Return type:: list[tuple[int, int, str]]

rxn_network.network.network.get_edge_weight(edge_obj, cf)[source]#

Given an edge of a reaction network, calculates the cost/weight of that edge. Corresponds to zero for loopback & precursor/target edges. Evaluates cost function for all reaction edges.

Parameters:

edge_obj (object) – An edge in the reaction network
cf (CostFunction) – Cost function for evaluating edge weights

rxn_network.network.network.yens_ksp(g, cf, num_k, precursors_node, target_node)[source]#

Yen’s Algorithm for k-shortest paths, adopted for rustworkx.

This implementation was inspired by the igraph implementation by Antonin Lenfant.

Reference (original Yen’s KSP paper):: Jin Y. Yen, “Finding the K Shortest Loopless Paths n a Network”, Management Science, Vol. 17, No. 11, Theory Series (Jul., 1971), pp. 712-716.

Parameters:

g (rx.PyGraph) – the rustworkx PyGraph object.
cf (CostFunction) – A cost function for evaluating the edge weights.
num_k (int) – number of k shortest paths that should be found.
precursors_node (int) – the index of the node representing the precursors.
target_node (int) – the index of the node representing the targets.

Returns:

List of lists of graph vertices corresponding to each shortest path: (sorted in increasing order by cost).

Return type:

list[list[int]]

rxn_network.network.visualize#

Functions for visualizing/plotting reaction networks.

rxn_network.network.visualize.plot_network(graph, vertex_cmap_name='jet', **kwargs)[source]#

Plots a reaction network using rustworkx visualization tools (i.e., mpl_draw).

Parameters:

graph (PyGraph) – a rustworkx PyGraph object
vertex_cmap_name (str) – the name of . Defaults to “jet”.
**kwargs – keyword arguments to pass to mpl_draw