build_graph

class CrystalGraph(object)

Read structural file and return a graph.

Caution

The constructed crystal graph may be unreasonable for high-entropy materials, if the connections are analyzed by Voronoi method.

Code example:

from Crystal2raph import CrystalGraph
cg = CrystalGraph(cutoff = 6.0, mode_of_NN='distance', adsorbate=True)
cg.get_graph('POSCAR')

Hint

Although we recommend representing atoms with one hot code, you can use the another way with: self.all_atom_feat = get_atomic_features()

Hint

In order to build a reasonable graph, a samll cell should be repeated. One can modify “self._cell_length_cutoff” for special needs.

Hint

We encourage you to use ase module to build crystal graphs. The pymatgen module needs some dependencies that conflict with other modules.

__init__(self, **data_config)

param **data_config:

Configuration file for building database. See https://jzhang-github.github.io/AGAT/Default%20parameters.html#default-data-config for the detailed info.

type **data_config:

str/dict

return:

A DGL.graph.

rtype:

DGL.graph.

Hint

Mode of how to get the neighbors, which can be:

'voronoi': consider Voronoi neighbors only.

'pymatgen_dist': build graph based on a constant distance using pymatgen module.

'ase_dist': build graph based on a constant distance using ase module.

'ase_natural_cutoffs': build graph from ase which has a dynamic cutoff scheme. In this case, the cutoff is deprecated because ase will use the dynamic cutoffs in ase.neighborlist.natural_cutoffs().

Parameters:: adsorbate (bool) – Identify the adsorbate or not.

get_adsorbate_bool(self, element_list)

Identify adsorbates based on elements： H and O.

Parameters:: element_list (list) – a list of element symbols.
Returns:: a list of bool values.
Return type:: torch.tensor

get_crystal(self, crystal_fpath, super_cell=True)

Read structural file and return a pymatgen crystal object.

Parameters:

crystal_fpath (str) – the path to the crystal structural.
super_cell (bool) – repeat the cell or not.

Returns:

a pymatgen structure object.

Return type:

pymatgen.core.structure.

get_1NN_pairs_voronoi(self, crystal)

The get_connections_new() of VoronoiConnectivity object is modified.

Parameters:

crystal (pymatgen.core.structure) – a pymatgen structure object.

Returns:

index of senders
index of receivers
a list of distance between senders and receivers

get_1NN_pairs_distance(self, crystal)

Find the index of senders, receivers, and distance between them based on the distance_matrix of pymargen crystal object.

Parameters:

crystal (pymargen.core.structure) – pymargen crystal object

Returns:

index of senders
index of receivers
a list of distance between senders and receivers

get_1NN_pairs_ase_distance(self, ase_atoms)

Parameters:

ase_atoms (ase.atoms) – ase.atoms object.

Returns:

index of senders
index of receivers
a list of distance between senders and receivers

get_ndata(self, crystal)

Parameters:: crystal (pymargen.core.structure) – a pymatgen crystal object.
Returns:: ndata: the atomic representations of a crystal graph.
Return type:: numpy.ndarray

get_graph_from_ase(self, fname, include_forces=False)

Build graphs with ase.

Parameters:

fname (str/ase.Atoms) – File name or ase.Atoms object.
include_forces (bool) – Include forces into graphs or not.

Returns:

A bidirectional graph with self-loop connection.

get_graph_from_pymatgen(self, crystal_fname, super_cell=True, include_forces=False)

Build graphs with pymatgen.

Parameters:

crystal_fname (str) – File name.
super_cell (bool) – repeat small cell or not.
include_forces (bool) – Include forces into graphs or not.

Returns:

A bidirectional graph with self-loop connection.

get_graph(self, crystal_fname, super_cell=False, include_forces=True)

This method can choose which graph-construction method is used, according to the mode_of_NN attribute.

Hint

You can call this method to build one graph.

Parameters:

crystal_fname (str) – File name.
super_cell (bool) – repeat small cell or not.
include_forces (bool) – Include forces into graphs or not.

Returns:

A bidirectional graph with self-loop connection.

class AseGraphTorch(object)

Build DGL graphs with ASE and Torch module. A GPU card can be used for a large system, or for simulations of geometry optimization and molecular dynamics.

Note

During the geometry optimization or MD simulation, connections among atoms may not change with several ionic steps. Thus, calculating neighboring relationships for every ionic step is high-cost. This class aims to reduce such cost and improve speed.

__init__(self, **data_config)

Parameters:: **data_config (str/dict) – Configuration file for building database. See https://jzhang-github.github.io/AGAT/Default%20parameters.html#default-data-config for the detailed info.

reset(self): Reset parameters for building graph from sctrach.

get_ndata(self, ase_atoms)

Get node data (atomic features)

Parameters:

ase_atoms – ase.Atoms
type – ase.Atoms

Returns:

atomic input features.

Return type:

torch.Tensor

get_adsorbate_bool(self, element_list)

Identify adsorbates based on elements： H and O.

Returns:: a list of bool values.
Return type:: tf.constant

get_scaled_positions_wrap(self, cell_I_tensor, positions)

Get the scaled atomic positions and wrap into the origional cell.

Parameters:

cell_I_tensor (torch.Tensor) – cell array in the torch.Tensor format.
positions (torch.Tensor) – atomic positions.

get_scaled_positions(self, cell_I_tensor, positions)

Get the scaled atomic positions and DO NOT wrap into the origional cell.

Parameters:

cell_I_tensor (torch.Tensor) – cell array in the torch.Tensor format.
positions (torch.Tensor) – atomic positions.

fractional2cartesian(self, cell_tensor, scaled_positions)

Convert scaled (fractional) coordinates to the cartesian coordinates.

Parameters:

cell_tensor (torch.Tensor) – Simulation cell array.
scaled_positions (torch.Tensor) – Scaled atomic positions.

safe_to_use(self, ase_atoms, critical=0.01)

For small simulation cells or non-cubic cells, this class may lead to unwanted results.

Parameters:

ase_atoms (ase.Atoms) – ASE atoms.
critical (float) – Critical value for determing a cubic cell or not.

Returns:

Safe or not.

Return type:

bool

get_pair_distances(self, a, b, ase_atoms)

Get distance between two atoms.

Parameters:

a (int) – The index of first atom.
b (int) – The index of second atom.
ase_atoms (ase.Atoms) – ase atoms in RAM.

Returns:

d

Return type:

float

Returns:

D

Return type:

torch.Tensor

update_pair_distances(self, a, b, b_image, ase_atoms)

Update distance between two atoms.

Parameters:

a (int) – The index of first atom.
b (int) – The index of second atom.
b_image (int) – Clearly, I fogot things.
ase_atoms (ase.Atoms) – ase atoms in RAM.

Returns:

d

Return type:

float

Returns:

D

Return type:

torch.Tensor

get_all_possible_distances(self, ase_atoms)

Note

Get senders and receivers, including inner and skin connections. Torch.from_numpy is memory effcient than torch.tensor, especially for large tensors. No self loop and reverse direction.

Get all possible connections, not every pair of atoms will be calculated in order to improve the efficiency.

Parameters:: ase_atoms (ase.Atoms) – ASE atoms in RAM.

get_init_connections(self, ase_atoms)

Get connection from scratch.

Parameters:: ase_atoms (ase.Atoms) – ASE atoms in RAM.
Returns:: Return connections for both real neighbors and potential neighbors defined by the skin thickness.

update_connections(self, i_i, j_i, j_image_i, i_s, j_s, j_image_s, ase_atoms): Update connections instead of calculating every pair distance. Some skin aotm may become real neighbors, while neighbors can go to the skin region (potential neighbor).

build(self, ase_atoms)

Returns:: a DGL graph.

Build graph from scratch?

update(self, ase_atoms)

Build graph from updated connections, not from scratch.

Returns:: a DGL graph.

get_graph(self, ase_atoms)

Get graph from ASE atoms object.

Hint

This is the high-level API of this class.

Returns:: a DGL graph.

Warning

The owner seems forgot some details. So use AseGraphTorch with caution.