# AtomGraphs

Documentation for AtomGraphs.

`AtomGraphs.AtomGraph`

`AtomGraphs.AtomGraph`

`AtomGraphs.AtomGraph`

`AtomGraphs.AtomGraph`

`AtomGraphs.build_graph`

`AtomGraphs.build_graph`

`AtomGraphs.build_supercell`

`AtomGraphs.graph_colors`

`AtomGraphs.graph_edgewidths`

`AtomGraphs.lt_edge`

`AtomGraphs.neighbor_list`

`AtomGraphs.normalized_laplacian`

`AtomGraphs.visualize`

`AtomGraphs.weights_cutoff`

`AtomGraphs.weights_voronoi`

`AtomGraphs.AtomGraph`

— Type`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.

`AtomGraphs.AtomGraph`

— Type`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.

`AtomGraphs.AtomGraph`

— Type`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

`AtomGraphs.AtomGraph`

— Method`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.

`AtomGraphs.build_graph`

— MethodBuild 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

`AtomGraphs.build_graph`

— MethodBuild 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

`AtomGraphs.build_supercell`

— Method```
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.
```

`AtomGraphs.graph_colors`

— FunctionGet a list of colors to use for graph visualization.

`AtomGraphs.graph_edgewidths`

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

`AtomGraphs.lt_edge`

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

`AtomGraphs.neighbor_list`

— MethodFind 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.

`AtomGraphs.normalized_laplacian`

— Method`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.

`AtomGraphs.visualize`

— MethodVisualize a given graph.

`AtomGraphs.weights_cutoff`

— MethodBuild graph using neighbor number cutoff method adapted from original CGCNN.

`max_num_nbr`

is a "soft" max, in that if there are more of the same distance as the last, all of those will be added.

`AtomGraphs.weights_voronoi`

— MethodBuild graph using neighbors from faces of Voronoi polyedra and weights from areas. Based on the approach from https://github.com/ulissigroup/uncertainty*benchmarking/blob/aabb407807e35b5fd6ad06b14b440609ae09e6ef/BNN/data*pyro.py#L268