Contents

API documentation

Analysis

Helpers for analysing structure graphs.

get_structure_graph_dimensionality(structure_graph)[source]

Use Larsen’s algorithm to compute the dimensionality.

Parameters:

structure_graph (StructureGraph) – pymatgen StructureGraph

Returns:

Dimensionality of the StructureGraph

Return type:

int

Example

>>> from structuregraph_helpers import get_structure_graph_dimensionality
>>> get_structure_graph_dimensionality(structure_graph)
3

References

[Larsen] `Larsen, P. M.; Pandey, M.; Strange, M.; Jacobsen,

K. W. Definition of a Scoring Parameter to Identify Low-Dimensional Materials Components. Physical Review Materials, 2019, 3. <https://doi.org/10.1103/physrevmaterials.3.034003>`_

get_leaf_nodes(graph)[source]

For a graph, return the indices of the leaf nodes.

Parameters:

graph (nx.Graph) – networkx graph

Returns:

indices of leaf nodes

Return type:

List[int]

Create

Helpers for creating graphs.

get_nx_graph_from_edge_tuples(edge_tuples)[source]

Create a undirected graph from a list of edge tuples.

Parameters:

edge_tuples (Iterable[Tuple[int, int]]) – List of edge tuples.

Returns:

Undirected graph.

Return type:

nx.Graph

Example

>>> from structuregraph_helpers import get_nx_graph_from_edge_tuples
>>> get_nx_graph_from_edge_tuples([(0, 0), (0, 1), (1, 0), (1, 1)])
Graph(2 nodes, 3 edges)
VestaCutoffDictNN = <pymatgen.analysis.local_env.CutOffDictNN object>

CutOffDictNN: Hand-tuned cutoff values for based on the original ones in pymatgen.

ATRCutoffDictNN = <pymatgen.analysis.local_env.CutOffDictNN object>

CutOffDictNN: Atomic typing radii.

LICutoffDictNN = <pymatgen.analysis.local_env.CutOffDictNN object>

CutOffDictNN: Lennard-Jones cutoff radii.

get_local_env_method(method)[source]

Get a local environment method based on its name.

Parameters:

method (str) – Name of the method.

Returns:

Local environment method.

Return type:

NearNeighbors

Example

>>> from structuregraph_helpers import get_local_env_method
>>> get_local_env_method("voronoi")
<pymatgen.analysis.local_env.VoronoiNN object at 0x...>
get_structure_graph(structure, method='vesta')[source]

Get a structure graph for a structure.

Return type:

StructureGraph

construct_clean_graph(structure_graph, multigraph=False, directed=False)[source]

Create a networkx graph with atom numbers and coordination numbers as node attributes.

Warning

If you choose directed=True, but multigraph=False, there might be fewer edges than you intuitively expec as we do not flip the direction based on the edge data.

Parameters:

  • structure_graph (StructureGraph) – StructureGraph to convert.

  • multigraph (bool) – Whether to use return a multigraph.

  • directed (bool) – Whether to use return adirected graph.

Returns:

Networkx graph.

Return type:

nx.Graph

Delete

Helpers for deleting parts of graphs.

remove_all_nodes_not_in_indices(graph, indices)[source]

Remove all nodes that are not in the given indices from the StructureGraph.

Note

The StructureGraph is modified in place.

Parameters:

  • graph (StructureGraph) – pymatgen StructureGraph

  • indices (Iterable[int]) – Indices of nodes to keep

Return type:

None

Plotting

Plotting helpers.

plotly_plot_structure_graph(structure_graph, show_edges=True, show_nodes=True)[source]

Plot a StructureGraph using Plotly.

Subgraph

Extract subgraphs from structure graphs.

get_subgraphs_as_molecules(structure_graph, use_weights=False, return_unique=True, disable_boundary_crossing_check=False, filter_in_cell=True, prune_long_edges=False)[source]

Isolates connected components as molecules from a StructureGraph.

Copied from http://pymatgen.org/_modules/pymatgen/analysis/graphs.html#StructureGraph.get_subgraphs_as_molecules and removed the duplicate check and added pruning of long edges that seem to cause issues in some cases.

This function also returns more info than the original function.

Warning

This edge pruning is a hack and should be removed when the underlying issue is fixed.

Parameters:

  • structure_graph (StructureGraph) – Structuregraph

  • use_weights (bool) – If True, use weights for the edge matching

  • return_unique (bool) – If true, it only returns the unique molecules. If False, it will return all molecules that are completely included in the unit cell and fragments of the ones that are only partly in the cell

  • disable_boundary_crossing_check (bool) – If true, it will not check if the molecules are crossing the boundary of the unit cell. Default is False.

  • filter_in_cell (bool) – If True, it will only return molecules that have at least one atom in the cell

  • prune_long_edges (bool) – If True, it will remove long edges. This is somewhat of a hack to workaround a bug i suspect in the __mul__ method of StructureGraph.

Returns:

A tuple of (molecules, graphs, indices, centers, coordinates)

Return type:

Tuple[List[Molecule], List[MoleculeGraph], List[List[int]], List[np.ndarray], List[np.ndarray]]

Hash ——- - .. automodule:: structuregraph_helpers.hash

members:

Logging

structuregraph_helpers uses the loguru for logging. By default, logging from structuregraph_helpers is disabled to not interfere with your logs.

However, you can easily customize the logging:

import sys
from loguru import logger

# enable structuregraph_helpers logging
logger.enable("structuregraph_helpers")

# define the logging level
LEVEL = "INFO || DEBUG || WARNING || etc."

# set the handler
# for logging to stdout
logger.add(sys.stdout, level=LEVEL)
# or for logging to a file
logger.add("my_log_file.log", level=LEVEL, enqueue=True)

In many cases, however, you might find it convenient to simply call enable_logging()

from structuregraph_helpers.utils import enable_logging

enable_logging()

which will enable logging with sane defaults (i.e. logging to stderr for INFO and WARNING levels).

Installation