pymatgen.analysis.graphs module¶

class
ConnectedSite
(site, jimage, index, weight, dist)¶ Bases:
tuple
Create new instance of ConnectedSite(site, jimage, index, weight, dist)

dist
¶ Alias for field number 4

index
¶ Alias for field number 2

jimage
¶ Alias for field number 1

site
¶ Alias for field number 0

weight
¶ Alias for field number 3


class
MoleculeGraph
(molecule, graph_data=None)[source]¶ Bases:
monty.json.MSONable
This is a class for annotating a Molecule with bond information, stored in the form of a graph. A “bond” does not necessarily have to be a chemical bond, but can store any kind of information that connects two Sites.
If constructing this class manually, use the with_empty_graph method or with_local_env_strategy method (using an algorithm provided by the local_env module, such as O’Keeffe).
This class that contains connection information: relationships between sites represented by a Graph structure, and an associated structure object.
This class uses the NetworkX package to store and operate on the graph itself, but contains a lot of helper methods to make associating a graph with a given molecule easier.
Use cases for this include storing bonding information, NMR Jcouplings, Heisenberg exchange parameters, etc.
Parameters:  molecule – Molecule object
 graph_data – dict containing graph information in
dict format (not intended to be constructed manually, see as_dict method for format)

add_edge
(from_index, to_index, weight=None, warn_duplicates=True, edge_properties=None)[source]¶ Add edge to graph.
Since physically a ‘bond’ (or other connection between sites) doesn’t have a direction, from_index, from_jimage can be swapped with to_index, to_jimage.
However, images will always always be shifted so that from_index < to_index and from_jimage becomes (0, 0, 0).
Parameters:  from_index – index of site connecting from
 to_index – index of site connecting to
 (float) (weight) – e.g. bond length
 (bool) (warn_duplicates) – if True, will warn if
trying to add duplicate edges (duplicate edges will not be added in either case) :param edge_properties (dict): any other information to store on graph edges, similar to Structure’s site_properties :return:

alter_edge
(from_index, to_index, new_weight=None, new_edge_properties=None)[source]¶ Alters either the weight or the edge_properties of an edge in the MoleculeGraph.
Parameters:  from_index – int
 to_index – int
 new_weight – alter_edge does not require
that weight be altered. As such, by default, this is None. If weight is to be changed, it should be a float. :param new_edge_properties: alter_edge does not require that edge_properties be altered. As such, by default, this is None. If any edge properties are to be changed, it should be a dictionary of edge properties to be changed. :return:

as_dict
()[source]¶ As in :Class: pymatgen.core.Molecule except with using to_dict_of_dicts from NetworkX to store graph information.

break_edge
(from_index, to_index, allow_reverse=False)[source]¶ Remove an edge from the MoleculeGraph
Parameters:  from_index – int
 to_index – int
 allow_reverse – If allow_reverse is True, then break_edge will
attempt to break both (from_index, to_index) and, failing that, will attempt to break (to_index, from_index). :return:

diff
(other, strict=True)[source]¶ Compares two MoleculeGraphs. Returns dict with keys ‘self’, ‘other’, ‘both’ with edges that are present in only one MoleculeGraph (‘self’ and ‘other’), and edges that are present in both.
The Jaccard distance is a simple measure of the dissimilarity between two MoleculeGraphs (ignoring edge weights), and is defined by 1  (size of the intersection / size of the union) of the sets of edges. This is returned with key ‘dist’.
Important note: all node indices are in terms of the MoleculeGraph this method is called from, not the ‘other’ MoleculeGraph: there is no guarantee the node indices will be the same if the underlying Molecules are ordered differently.
Parameters:  other – MoleculeGraph
 strict – if False, will compare bonds
from different Molecules, with node indices replaced by Specie strings, will not count number of occurrences of bonds :return:

draw_graph_to_file
(filename='graph', diff=None, hide_unconnected_nodes=False, hide_image_edges=True, edge_colors=False, node_labels=False, weight_labels=False, image_labels=False, color_scheme='VESTA', keep_dot=False, algo='fdp')[source]¶ Draws graph using GraphViz.
The networkx graph object itself can also be drawn with networkx’s inbuilt graph drawing methods, but note that this might give misleading results for multigraphs (edges are superimposed on each other).
If visualization is difficult to interpret, hide_image_edges can help, especially in larger graphs.
Parameters: filename – filename to output, will detect filetype from extension (any graphviz filetype supported, such as pdf or png) :param diff (StructureGraph): an additional graph to compare with, will color edges red that do not exist in diff and edges green that are in diff graph but not in the reference graph :param hide_unconnected_nodes: if True, hide unconnected nodes :param hide_image_edges: if True, do not draw edges that go through periodic boundaries :param edge_colors (bool): if True, use node colors to color edges :param node_labels (bool): if True, label nodes with species and site index :param weight_labels (bool): if True, label edges with weights :param image_labels (bool): if True, label edges with their periodic images (usually only used for debugging, edges to periodic images always appear as dashed lines) :param color_scheme (str): “VESTA” or “JMOL” :param keep_dot (bool): keep GraphViz .dot file for later visualization :param algo: any graphviz algo, “neato” (for simple graphs) or “fdp” (for more crowded graphs) usually give good outputs :return:

edge_weight_name
¶ return – Name of the edge weight property of graph

edge_weight_unit
¶ return – Units of the edge weight property of graph

equivalent_to
(other)[source]¶ A weaker equality function that evaluates isomorphisms between two MoleculeGraphs. If there is an isomorphism where the species are identical for each pair, then the MoleculeGraphs are considered “equivalent”.
Parameters: other – The MoleculeGraph to be compared to this MoleculeGraph Returns: Bool

find_rings
(including=None)[source]¶ Find ring structures in the MoleculeGraph.
NOTE: Currently, this function behaves as expected for single rings, but fails (miserably) on molecules with more than one ring.
Parameters: including – list of site indices. If including is not None, then find_rings will only return those rings including the specified sites. By default, this parameter is None, and all rings will be returned. :return: dict {index:cycle}. Each entry will be a ring (cycle, in graph theory terms) including the index found in the Molecule. If there is no cycle including an index, the value will be an empty list.

classmethod
from_dict
(d)[source]¶ As in :Class: pymatgen.core.Molecule except restoring graphs using from_dict_of_dicts from NetworkX to restore graph information.

get_connected_sites
(n)[source]¶ Returns a named tuple of neighbors of site n: periodic_site, jimage, index, weight. Index is the index of the corresponding site in the original structure, weight can be None if not defined. :param n: index of Site in Molecule :param jimage: lattice vector of site :return: list of ConnectedSite tuples, sorted by closest first

get_coordination_of_site
(n)[source]¶ Returns the number of neighbors of site n. In graph terms, simply returns degree of node corresponding to site n. :param n: index of site :return (int):

name
¶ return – Name of graph

set_node_attributes
()[source]¶ Gives each node a “specie” and a “coords” attribute, updated with the current species and coordinates.
Returns:

sort
(key=None, reverse=False)[source]¶ Same as Molecule.sort(), also remaps nodes in graph. :param key: :param reverse: :return:

split_molecule_subgraphs
(bonds, allow_reverse=False, alterations=None)[source]¶ Split MoleculeGraph into two MoleculeGraphs by breaking a set of bonds. This function uses MoleculeGraph.break_edge repeatedly to create disjoint graphs (two or more separate molecules). This function does not only alter the graph information, but also changes the underlying Moledules. If the bonds parameter does not include sufficient bonds to separate two bonds, then this function will fail. Currently, this function naively assigns the charge of the total molecule to a single submolecule. A later effort will be to actually accurately assign charge. NOTE: This function does not modify the original MoleculeGraph. It creates a copy, modifies that, and returns two or more new MoleculeGraph objects.
Parameters: bonds – list of tuples (from_index, to_index) representing bonds to be broken to split the MoleculeGraph. :param alterations: a dict {(from_index, to_index): alt}, where alt is a dictionary including weight and/or edge properties to be changed following the split. :param allow_reverse: If allow_reverse is True, then break_edge will attempt to break both (from_index, to_index) and, failing that, will attempt to break (to_index, from_index). :return: list of MoleculeGraphs

substitute_group
(index, func_grp, strategy, bond_order=1, graph_dict=None, strategy_params=None)[source]¶ Builds off of Molecule.substitute to replace an atom in self.molecule with a functional group. This method also amends self.graph to incorporate the new functional group.
NOTE: using a MoleculeGraph will generally produce a different graph compared with using a Molecule or str (when not using graph_dict). This is because of the reordering that occurs when using some of the local_env strategies.
Parameters:  index – Index of atom to substitute.
 func_grp –
Substituent molecule. There are three options:
 Providing an actual molecule as the input. The first atom must be a DummySpecie X, indicating the position of nearest neighbor. The second atom must be the next nearest atom. For example, for a methyl group substitution, func_grp should be XCH3, where X is the first site and C is the second site. What the code will do is to remove the index site, and connect the nearest neighbor to the C atom in CH3. The XC bond indicates the directionality to connect the atoms.
 A string name. The molecule will be obtained from the relevant template in func_groups.json.
 A MoleculeGraph object.
 strategy – Class from pymatgen.analysis.local_env.
 bond_order – A specified bond order to calculate the bond length between the attached functional group and the nearest neighbor site. Defaults to 1.
 grp_graph – Dictionary representing the bonds of the functional group (format: {(u, v): props}, where props is a dictionary of properties, including weight. If None, then the algorithm will attempt to automatically determine bonds using one of a list of strategies defined in pymatgen.analysis.local_env.
 strategy_params – dictionary of keyword arguments for strategy. If None, default parameters will be used.
Returns:

classmethod
with_empty_graph
(molecule, name='bonds', edge_weight_name=None, edge_weight_units=None)[source]¶ Constructor for MoleculeGraph, returns a MoleculeGraph object with an empty graph (no edges, only nodes defined that correspond to Sites in Molecule).
Parameters:  (Molecule) (molecule) –
 (str) (edge_weight_name) – name of graph, e.g. “bonds”
 (str) – name of edge weights,
e.g. “bond_length” or “exchange_constant” :param edge_weight_units (str): name of edge weight units e.g. “Å” or “eV” :return (MoleculeGraph):

static
with_local_env_strategy
(molecule, strategy, reorder=True)[source]¶ Constructor for MoleculeGraph, using a strategy from :Class: pymatgen.analysis.local_env.
Molecules will be put into a large artificial box for calculation of bonds using a NearNeighbor strategy, since some strategies assume periodic boundary conditions.
Parameters:  molecule – Molecule object
 strategy – an instance of a :Class: pymatgen.analysis.local_env.NearNeighbors object
 reorder – bool, representing if graph nodes need to be reordered
following the application of the local_env strategy :return: mg, a MoleculeGraph

class
StructureGraph
(structure, graph_data=None)[source]¶ Bases:
monty.json.MSONable
This is a class for annotating a Structure with bond information, stored in the form of a graph. A “bond” does not necessarily have to be a chemical bond, but can store any kind of information that connects two Sites.
If constructing this class manually, use the with_empty_graph method or with_local_env_strategy method (using an algorithm provided by the local_env module, such as O’Keeffe).
This class that contains connection information: relationships between sites represented by a Graph structure, and an associated structure object.
This class uses the NetworkX package to store and operate on the graph itself, but contains a lot of helper methods to make associating a graph with a given crystallographic structure easier.
Use cases for this include storing bonding information, NMR Jcouplings, Heisenberg exchange parameters, etc.
For periodic graphs, class stores information on the graph edges of what lattice image the edge belongs to.
Parameters:  structure – a Structure object
 graph_data – dict containing graph information in
dict format (not intended to be constructed manually, see as_dict method for format)

add_edge
(from_index, to_index, from_jimage=(0, 0, 0), to_jimage=None, weight=None, warn_duplicates=True, edge_properties=None)[source]¶ Add edge to graph.
Since physically a ‘bond’ (or other connection between sites) doesn’t have a direction, from_index, from_jimage can be swapped with to_index, to_jimage.
However, images will always always be shifted so that from_index < to_index and from_jimage becomes (0, 0, 0).
Parameters:  from_index – index of site connecting from
 to_index – index of site connecting to
 (tuple of ints) (from_jimage) – lattice vector of periodic
image, e.g. (1, 0, 0) for periodic image in +x direction :param to_jimage (tuple of ints): lattice vector of image :param weight (float): e.g. bond length :param warn_duplicates (bool): if True, will warn if trying to add duplicate edges (duplicate edges will not be added in either case) :param edge_properties (dict): any other information to store on graph edges, similar to Structure’s site_properties :return:

as_dict
()[source]¶ As in :Class: pymatgen.core.Structure except with using to_dict_of_dicts from NetworkX to store graph information.

diff
(other, strict=True)[source]¶ Compares two StructureGraphs. Returns dict with keys ‘self’, ‘other’, ‘both’ with edges that are present in only one StructureGraph (‘self’ and ‘other’), and edges that are present in both.
The Jaccard distance is a simple measure of the dissimilarity between two StructureGraphs (ignoring edge weights), and is defined by 1  (size of the intersection / size of the union) of the sets of edges. This is returned with key ‘dist’.
Important note: all node indices are in terms of the StructureGraph this method is called from, not the ‘other’ StructureGraph: there is no guarantee the node indices will be the same if the underlying Structures are ordered differently.
Parameters:  other – StructureGraph
 strict – if False, will compare bonds
from different Structures, with node indices replaced by Specie strings, will not count number of occurrences of bonds :return:

draw_graph_to_file
(filename='graph', diff=None, hide_unconnected_nodes=False, hide_image_edges=True, edge_colors=False, node_labels=False, weight_labels=False, image_labels=False, color_scheme='VESTA', keep_dot=False, algo='fdp')[source]¶ Draws graph using GraphViz.
The networkx graph object itself can also be drawn with networkx’s inbuilt graph drawing methods, but note that this might give misleading results for multigraphs (edges are superimposed on each other).
If visualization is difficult to interpret, hide_image_edges can help, especially in larger graphs.
Parameters: filename – filename to output, will detect filetype from extension (any graphviz filetype supported, such as pdf or png) :param diff (StructureGraph): an additional graph to compare with, will color edges red that do not exist in diff and edges green that are in diff graph but not in the reference graph :param hide_unconnected_nodes: if True, hide unconnected nodes :param hide_image_edges: if True, do not draw edges that go through periodic boundaries :param edge_colors (bool): if True, use node colors to color edges :param node_labels (bool): if True, label nodes with species and site index :param weight_labels (bool): if True, label edges with weights :param image_labels (bool): if True, label edges with their periodic images (usually only used for debugging, edges to periodic images always appear as dashed lines) :param color_scheme (str): “VESTA” or “JMOL” :param keep_dot (bool): keep GraphViz .dot file for later visualization :param algo: any graphviz algo, “neato” (for simple graphs) or “fdp” (for more crowded graphs) usually give good outputs :return:

edge_weight_name
¶ return – Name of the edge weight property of graph

edge_weight_unit
¶ return – Units of the edge weight property of graph

classmethod
from_dict
(d)[source]¶ As in :Class: pymatgen.core.Structure except restoring graphs using from_dict_of_dicts from NetworkX to restore graph information.

get_connected_sites
(n, jimage=(0, 0, 0))[source]¶ Returns a named tuple of neighbors of site n: periodic_site, jimage, index, weight. Index is the index of the corresponding site in the original structure, weight can be None if not defined. :param n: index of Site in Structure :param jimage: lattice vector of site :return: list of ConnectedSite tuples, sorted by closest first

get_coordination_of_site
(n)[source]¶ Returns the number of neighbors of site n. In graph terms, simply returns degree of node corresponding to site n. :param n: index of site :return (int):

get_subgraphs_as_molecules
(use_weights=False)[source]¶ Retrieve subgraphs as molecules, useful for extracting molecules from periodic crystals.
Will only return unique molecules, not any duplicates present in the crystal (a duplicate defined as an isomorphic subgraph).
Parameters: (bool) (use_weights) – If True, only treat subgraphs as isomorphic if edges have the same weights. Typically, this means molecules will need to have the same bond lengths to be defined as duplicates, otherwise bond lengths can differ. This is a fairly robust approach, but will treat e.g. enantiomers as being duplicates.
Returns: list of unique Molecules in Structure

name
¶ return – Name of graph

sort
(key=None, reverse=False)[source]¶ Same as Structure.sort(), also remaps nodes in graph. :param key: :param reverse: :return:

classmethod
with_empty_graph
(structure, name='bonds', edge_weight_name=None, edge_weight_units=None)[source]¶ Constructor for StructureGraph, returns a StructureGraph object with an empty graph (no edges, only nodes defined that correspond to Sites in Structure).
Parameters:  (Structure) (structure) –
 (str) (edge_weight_name) – name of graph, e.g. “bonds”
 (str) – name of edge weights,
e.g. “bond_length” or “exchange_constant” :param edge_weight_units (str): name of edge weight units e.g. “Å” or “eV” :return (StructureGraph):