AtomGraphs

AtomGraph(input_file_path, id = splitext(input_file_path)[begin]; output_file_path = nothing, overwrite_file = false, use_voronoi = false, cutoff_radius = 8.0, max_num_nbr = 12, dist_decay_func = inverse_square)

Construct an AtomGraph object from a structure file.

Required Arguments

• input_file_path::String: path to file containing structure (must be readable by ASE.io.read)

Optional Arguments

• id::String: ID associated with structure (e.g. identifier from online database). Defaults to name of input file if undefined.
• output_file_path = nothing: If provided, structure will be serialized to file at this location
• overwrite_file::Bool = false: whether to overwrite an existing file at output_file_path
• use_voronoi::Bool = false: Whether to build neighbor lists using Voronoi decompositions
• cutoff_radius::Real = 8.0: If not using Voronoi neighbor lists, longest allowable distance to a neighbor, in Angstroms
• max_num_nbr::Integer = 12: If not using Voronoi neighbor lists, largest allowable number of neighbors
• dist_decay_func = inverse_square: Function by which to assign edge weights according to distance between neighbors

Note

max_num_nbr is a "soft" limit – if multiple neighbors are at the same distance, the full neighbor list may be longer.

AtomGraph(mol::GraphMol, id="")

Build an AtomGraph from a GraphMol object. Currently does not have access to any 3D structure, so resulting graph is unweighted.

Eventually, could have a version of this that connects to e.g. PubChem or ChemSpider to try to fetch 3D structures, in which case other kwargs for actual graph-building will become relevant.

AtomGraph{A}

A type representing an atomic structure as a graph (gr).

Fields

• graph::SimpleWeightedGraph{<:Integer,<:Real}: the graph representing the structure. See build_graph for more on generating the weights.
• elements::Vector{String}: list of elemental symbols corresponding to each node of the graph
• laplacian::Matrix{<:Real}: Normalized graph Laplacian matrix, stored to speed up convolution operations by avoiding recomputing it every pass.
• id::String: Optional, an identifier, e.g. to correspond with tags/labels of an imported dataset.
• structure::A: the original representation from which this AtomGraph was created

AtomGraph(sys; id="", cutoff_radius = 8.0, max_num_nbr = 12, dist_decay_func = inverse_square)

Construct an AtomGraph object from a Crystal object (defined in Xtals.jl). For now, only supports cutoff-based graph building.

Required Arguments

• sys: Either an Xtals.Crystal object or any AtomsBase AbstractSystem object from which to build the graph

Optional Arguments

• id::String: ID associated with structure (e.g. identifier from online database). Defaults to the empty string.
• cutoff_radius::Real = 8.0: Longest allowable distance to a neighbor, in Angstroms
• max_num_nbr::Integer = 12: Largest allowable number of neighbors
• dist_decay_func = inverse_square: Function by which to assign edge weights according to distance between neighbors

Note

max_num_nbr is a "soft" limit – if multiple neighbors are at the same distance, the full neighbor list may be longer.

Build graph from an object. Currently only supports the "cutoff" method of neighbor list/weight calculation (not Voronoi). This dispatch exists to support autodiff of graph-building.

Arguments

Required Arguments

• sys: either an Xtals Crystal object or an AtomsBase AbstractSystem representing the atomic geometry from which to build a graph

Keyword Arguments

• cutoff_radius::Real=8.0: cutoff radius for atoms to be considered neighbors (in angstroms)
• max_num_nbr::Integer=12: maximum number of neighbors to include (even if more fall within cutoff radius)
• dist_decay_func::Function=inverse_square: function to determine falloff of graph edge weights with neighbor distance

Build graph from a file storing a crystal structure (will be read in using AtomsIO, which in turn calls ASE). Returns the weight matrix and elements used for constructing an AtomGraph.

Arguments

Required Arguments

• file_path::String: Path to ASE-readable file containing a molecule/crystal structure

Keyword Arguments

• use_voronoi::bool: if true, use Voronoi method for neighbor lists, if false use cutoff method

  (The rest of these parameters are only used if use_voronoi==false)

• cutoff_radius::Real=8.0: cutoff radius for atoms to be considered neighbors (in angstroms)

• max_num_nbr::Integer=12: maximum number of neighbors to include (even if more fall within cutoff radius)

• dist_decay_func::Function=inverse_square: function to determine falloff of graph edge weights with neighbor distance

Build a supercell from the provided AbstractSystem object. `repfactors` specifies the multiplier on each lattice vector.

This is adapted from the implementation in Xtals.jl but should work in arbitrary dimensions.

For now, returns the new bounding box, list of atomic symbols, and list of positions. Eventually, we probably want a more general way to use propertynames(sys) or similar to get all the arguments one would need to actually just return a new object of the same type with velocities, etc. if present. Basically, we would need a set of rules that tell us how to scale up different types of properties and maybe some interface functions for doing so.

Get a list of colors to use for graph visualization.

Compute edge widths (proportional to weights on graph) for graph visualization.

Helper function for sorting because edge ordering isn't preserved when converting to SimpleGraph.

Find all lists of pairs of atoms in sys (which can be an Xtals.Crystal or any AtomsBase AbstractSystem object) that are within a distance of cutoff_radius of each other, respecting periodic boundary conditions.

Returns as is, js, dists to be compatible with ASE's output format for the analogous function.

normalized_laplacian(graph)

Compute the normalized graph Laplacian matrix of the input graph, defined as

$I - D^{-1/2} A D^{-1/2}$

where $A$ is the adjacency matrix and $D$ is the degree matrix.

Visualize a given graph.

Build graph using neighbor number cutoff method adapted from original CGCNN.

Build graph using neighbors from faces of Voronoi polyedra and weights from areas. Based on the approach from https://github.com/ulissigroup/uncertaintybenchmarking/blob/aabb407807e35b5fd6ad06b14b440609ae09e6ef/BNN/datapyro.py#L268