kgcnn.graph.methods package¶

Module contents¶

kgcnn.graph.methods.add_edges_reverse_indices(edge_indices, *args, remove_duplicates: bool = True, sort_indices: bool = True, return_nested: bool = False)[source]¶

Add matching edges for (i, j) as (j, i) with the same edge values. If they do already exist, no edge is added. By default, all indices are sorted. Sorting is done for the first index at position index[:, 0].

Parameters

edge_indices (np.ndarray) – Index-list of edges referring to nodes of shape (N, 2).
args (np.ndarray) – Edge related value arrays to be changed accordingly of shape (N, …).
remove_duplicates (bool) – Remove duplicate edge indices. Default is True.
sort_indices (bool) – Sort final edge indices. Default is True.
return_nested (bool) – Whether to return nested args in addition to indices.

Returns

edge_indices or (edge_indices, *args). Or (edge_indices, args) if return_nested.

Return type

np.ndarray

kgcnn.graph.methods.add_self_loops_to_edge_indices(edge_indices, *args, remove_duplicates: bool = True, sort_indices: bool = True, fill_value: int = 0, return_nested: bool = False)[source]¶

Add self-loops to edge index list, i.e. [0, 0], [1, 1], …]. Edge values are filled up with ones or zeros. Default mode is to remove duplicates in the added list. Edge indices are sorted by default. Sorting is done for the first index at position index[:, 0].

Parameters

edge_indices (np.ndarray) – Index-list for edges referring to nodes of shape (N, 2).
args (np.ndarray) – Edge related value arrays to be changed accordingly of shape (N, …).
remove_duplicates (bool) – Remove duplicate edge indices. Default is True.
sort_indices (bool) – Sort final edge indices. Default is True.
fill_value (int) – Value to initialize edge values with.
return_nested (bool) – Whether to return nested args in addition to indices.

Returns

edge_indices or (edge_indices, *args). Or (edge_indices, args) if return_nested.

Return type

np.ndarray

kgcnn.graph.methods.compute_reverse_edges_index_map(edge_idx: numpy.ndarray)[source]¶

Computes the index map of the reverse edge for each of the edges if available. This can be used by a model to directly select the corresponding edge of \((j, i)\) which is \((i, j)\).

Edges that do not have a reverse pair get a -2147483648 as map index. If there are multiple edges, the first encounter is assigned.

Parameters: edge_idx (np.ndarray) – Array of edge indices of shape (N, 2).
Returns: Map of reverse indices of shape (N, ).
Return type: np.ndarray

kgcnn.graph.methods.convert_scaled_adjacency_to_list(adj_scaled)[source]¶

Map adjacency matrix to index list plus edge weights. In case of a standard adjacency matrix the edge weights will be one. For a pre-scaled adjacency matrix they become the entries of \(A_{s}\).

Parameters

adj_scaled (np.ndarray, scipy.sparse) – Normal or scaled adjacency matrix \(A\) of shape (N, N).

Returns

[tensor_index, edge_weight]

tensor_index (np.ndarray): Index-list referring to nodes of shape (N, 2).

edge_weight (np.ndarray): Entries of Adjacency matrix of shape (N, ).

Return type

list

kgcnn.graph.methods.coordinates_from_distance_matrix(distance: numpy.ndarray, use_center: Optional[bool] = None, dim: int = 3)[source]¶

Compute list of coordinates from a distance matrix of shape (N, N). May also work for input of shape (…, N, N) but is not tested. Uses vectorized Alogrithm: http://scripts.iucr.org/cgi-bin/paper?S0567739478000522 https://www.researchgate.net/publication/252396528_Stable_calculation_of_coordinates_from_distance_information no check of positive semi-definite or possible k-dim >= 3 is done here performs svd from numpy

Parameters

distance (np.ndarray) – distance matrix of shape (N,N) with Dij = abs(ri-rj)
use_center (int) – which atom should be the center, dafault = None means center of mass
dim (int) – the dimension of embedding, 3 is default

Returns

List of Atom coordinates [[x_1,x_2,x_3],[x_1,x_2,x_3],…]

Return type

np.ndarray

kgcnn.graph.methods.coordinates_to_distancematrix(coord3d: numpy.ndarray)[source]¶

Transform coordinates to distance matrix. Will apply transformation on last dimension. Changing of shape from (…, N, 3) to (…, N, N). This also works for more than 3 coordinates. Note: We could extend this to other metrics.

Arg:

coord3d (np.ndarray): Coordinates of shape (…, N, 3) for cartesian coordinates (x, y, z): and N the number of nodes or points. Coordinates are stored in the last dimension.

Returns: Distance matrix as numpy array with shape (…, N, N) where N is the number of nodes.
Return type: np.ndarray

kgcnn.graph.methods.coulomb_matrix_to_inverse_distance_proton(coulomb_mat: numpy.ndarray, unit_conversion: float = 1.0, exponent: float = 2.4)[source]¶

Convert a Coulomb matrix back to inverse distancematrix plus atomic number.

Parameters

coulomb_mat (np.ndarray) – Coulomb matrix of shape (…,N,N)
unit_conversion (float) – Whether to scale units for distance. Default is 1.0.
exponent (float) – Exponent for diagonal elements. Default is 2.4.

Returns

[inv_dist, z]

inv_dist (np.ndarray): Inverse distance Matrix of shape (…,N,N).

z (np.ndarray): Atom Number corresponding diagonal as proton number (…, N).

Return type

tuple

kgcnn.graph.methods.define_adjacency_from_distance(distance_matrix, max_distance=inf, max_neighbours=inf, exclusive=True, self_loops=False)[source]¶

Construct adjacency matrix from a distance matrix by distance and number of neighbours. Operates on last axis. Tries to connect nearest neighbours.

Parameters

distance_matrix (np.array) – Distance Matrix of shape (…, N, N)
max_distance (float, optional) – Maximum distance to allow connections, can also be None. Defaults to np.inf.
max_neighbours (int, optional) – Maximum number of neighbours, can also be None. Defaults to np.inf.
exclusive (bool, optional) – Whether both max distance and Neighbours must be fulfilled. Defaults to True.
self_loops (bool, optional) – Allow self-loops on diagonal. Defaults to False.

Returns

graph_adjacency, graph_indices

graph_adjacency (np.array): Adjacency Matrix of shape (…, N, N) of type bool.

graph_indices (np.array): Flatten indices from former array that have True as entry in the
returned adjacency matrix.

Return type

tuple

kgcnn.graph.methods.distance_for_range_indices(coordinates: numpy.ndarray, indices: numpy.ndarray, require_distance_dimension: bool = True)[source]¶

Simple helper function to compute distances for indices.

Parameters

coordinates (np.ndarray) – Positions of shape (N, 3) .
indices (np.ndarray) – Pair-wise indices of shape (M, 2) .
require_distance_dimension (bool) – Whether to return distances of shape (M, 1) .

Returns

Distances of shape (M, ) or (M, 1) if require_distance_dimension .

Return type

np.ndarray

kgcnn.graph.methods.distance_for_range_indices_periodic(coordinates: numpy.ndarray, indices: numpy.ndarray, images: numpy.ndarray, lattice: numpy.ndarray, require_distance_dimension: bool = True)[source]¶

Simple helper function to compute distances for indices for a periodic system.

Parameters

coordinates (np.ndarray) – Positions of shape (N, 3) within the unit-cell.
indices (np.ndarray) – Pair-wise indices of shape (M, 2) .
images (np.ndarray) – Image translation of the second index of shape (M, 3) .
lattice (np.ndarray) – Lattice matrix of real space lattice vectors of shape (3, 3) . The lattice vectors must be given in rows of the matrix!
require_distance_dimension (bool) – Whether to return distances of shape (M, 1) .

Returns

Distances of shape (M, ) or (M, 1) if require_distance_dimension .

Return type

np.ndarray

kgcnn.graph.methods.distance_to_gauss_basis(inputs, bins: int = 20, distance: float = 4.0, sigma: float = 0.4, offset: float = 0.0, axis: int = - 1, expand_dims: bool = True)[source]¶

Convert distance array to smooth one-hot representation using Gaussian functions. Changes shape for Gaussian distance expansion from (…, ) to (…, bins) by default.

Note: The default values match realistic units in Angstrom for atoms or molecules.

Parameters

inputs (np.ndarray) – Array of distances of shape (…, ).
bins (int) – Number of bins to sample distance from. Default is 20.
distance (value) – Maximum distance to be captured by bins. Default is 4.0.
sigma (value) – Sigma of the Gaussian function, determining the width/sharpness. Default is 0.4.
offset (float) – Possible offset to center Gaussian. Default is 0.0.
axis (int) – Axis to expand distance. Defaults to -1.
expand_dims (bool) – Whether to expand dims. Default to True.

Returns

Array of Gaussian distance with expanded last axis (…, #bins)

Return type

np.ndarray

kgcnn.graph.methods.get_angle(coord, indices)[source]¶

Compute angle between three points defined by the indices for points i, j, k. Requires mode coordinates. With the definition of vector directions \(\vec{x}_{ij} = \vec{x}_{i}-\vec{x}_{j}\) and \(\vec{x}_{jk} = \vec{x}_{j}-\vec{x}_{k}\), the angle between for \(\vec{x}_{ij}\), \(\vec{x}_{jk}\) is calculated.

Parameters

coord (np.ndarray) – List of coordinates of shape (N, 3).
indices (np.ndarray) – List of indices of shape (M, 3).

Returns

List of angles matching indices (M, 1).

Return type

np.ndarray

kgcnn.graph.methods.get_angle_between_edges(coord, edge_indices, angle_indices)[source]¶

Compute angle between two edges that do not necessarily need to be connected by a node. However, with the correct choice of angle_indices this can be assured. Node coordinates must be provided. The geometric direction of an edge with indices \((i, j)\) is given by \(\vec{x}_i - \vec{x}_j\).

Parameters

coord (np.ndarray) – List of coordinates of shape (N, 3).
edge_indices (np.ndarray) – List of edge indices referring to node coordinates of shape (M, 2).
angle_indices (np.ndarray) – List of angle indices referring edges of shape (K, 2).

Returns

List of angles matching angle indices of shape (K, 1).

Return type

np.ndarray

kgcnn.graph.methods.get_angle_indices(idx, check_sorted: bool = True, allow_multi_edges: bool = False, allow_self_edges: bool = False, allow_reverse_edges: bool = False, edge_pairing: str = 'jk')[source]¶

Compute index list for edge-pairs forming an angle. Not for batches, only for single instance.

Parameters

idx (np.ndarray) – List of edge indices referring to nodes of shape (N, 2)
check_sorted (bool) – Whether to sort for new angle indices. Default is True.
allow_self_edges (bool) – Whether to allow the exact same edge in an angle pairing. Overrides multi and reverse edge checking.
allow_multi_edges (bool) – Whether to keep angle pairs with same node indices, such as angle pairings of sort ij, ij.
allow_reverse_edges (bool) – Whether to keep angle pairs with reverse node indices, such as angle pairings of sort ij, ji.
edge_pairing (str) – Determines which edge pairs for angle computation are chosen. Default is ‘jk’. Alternatives are for example: ‘ik’, ‘kj’, ‘ki’, where ‘k’ denotes the variable index as ‘i’, ‘j’ are fixed.

Returns

idx, idx_ijk, idx_ijk_ij

idx (np.ndarray): Original edge indices referring to nodes of shape (N, 2).
idx_ijk (np.ndarray): Indices of nodes forming an angle as (i ,j, k) of shape (M, 3).
idx_ij_jk (np.ndarray): Indices for edge pairs referring to angles of shape (M, 2).

Return type

tuple

kgcnn.graph.methods.get_principal_moments_of_inertia(masses: numpy.ndarray, coordinates: numpy.ndarray, shift_center_of_mass: bool = True)[source]¶

Compute principle moments of inertia for a point-cloud with given mass.

Parameters

masses (np.ndarray) – Array of mass values.
coordinates (np.ndarray) – Coordinates of point-cloud.
shift_center_of_mass (bool) – Whether to shift to center of mass for inertia matrix.

Returns

Eigenvalues of inertia matrix. Shape is (3, ).

Return type

np.ndarray

kgcnn.graph.methods.invert_distance(d, nan=0, pos_inf=0, neg_inf=0)[source]¶

Invert distance array, e.g. distance matrix. Inversion is done for all entries. Keeps the shape of input distance array, since operation is done element-wise.

Parameters

d (np.ndarray) – Array of distance values of arbitrary shape.
nan (float) – Replacement for np.nan after division. Default is 0.
pos_inf (float) – Replacement for np.inf after division. Default is 0.
neg_inf (float) – Replacement for -np.inf after division. Default is 0.

Returns

Inverted distance array as np.array of identical shape and: replaces np.nan and np.inf with e.g. 0.0.

Return type

np.array

kgcnn.graph.methods.range_neighbour_lattice(coordinates: numpy.ndarray, lattice: numpy.ndarray, max_distance: Optional[float] = 4.0, max_neighbours: Optional[int] = None, self_loops: bool = False, exclusive: bool = True, limit_only_max_neighbours: bool = False, numerical_tol: float = 1e-08, manual_super_cell_radius: Optional[float] = None, super_cell_tol_factor: float = 0.25) → list [source]¶

Generate range connections for a primitive unit cell in a periodic lattice (vectorized).

import numpy as np
from kgcnn.graph.methods import range_neighbour_lattice

artificial_lattice = np.array([[1.0, 0.0, 0.0], [1.0, 1.0, 0.0], [0.0, 0.0, 1.0]])
artificial_atoms = np.array([[0.1, 0.0, 0.0], [0.5, 0.5, 0.5]])
out = range_neighbour_lattice(artificial_atoms, artificial_lattice)

real_lattice = np.array([[-8.71172704, -0., -5.02971843],
                         [-10.97279872, -0.01635133, 8.94600922],
                         [-6.5538005, 12.48246168, 1.29207947]])
real_atoms = np.array([[-24.14652308, 12.46611035, 6.41607351],
                       [-2.09180318, 0., -1.20770325],
                       [0., 0., 0.],
                       [-4.35586352, 0., -2.51485921]])
out_real = range_neighbour_lattice(real_atoms, real_lattice)

Parameters

coordinates (np.ndarray) – Coordinate of nodes in the central primitive unit cell.
lattice (np.ndarray) – Lattice matrix of real space lattice vectors of shape (3, 3). The lattice vectors must be given in rows of the matrix!
max_distance (float, optional) – Maximum distance to allow connections, can also be None. Defaults to 4.0.
max_neighbours (int, optional) – Maximum number of allowed neighbours for each central atom. Default is None.
self_loops (bool, optional) – Allow self-loops between the same central node. Defaults to False.
exclusive (bool) – Whether both distance and maximum neighbours must be fulfilled. Default is True.
limit_only_max_neighbours (bool) – Not used.
numerical_tol (float) – Numerical tolerance for distance cut-off. Default is 1e-8.
manual_super_cell_radius (float) – Not used.
super_cell_tol_factor (float) – Tolerance to increase for search for neighbours. Default is 0.5.

Returns

[indices, images, dist]

Return type

list

kgcnn.graph.methods.rescale_edge_weights_degree_sym(edge_indices, edge_weights)[source]¶

Normalize edge weights as \(\tilde(e)_{i,j} = d_{i,i}^{-0.5} e_{i,j} d_{j,j}^{-0.5}\). The node degree is defined as \(D_{i,i} = \sum_{j} A_{i, j}\).

Parameters

edge_indices (np.ndarray) – Index-list referring to nodes of shape (N, 2)
edge_weights (np.ndarray) – Edge weights matching indices of shape (N, 1)

Returns

Rescaled edge weights of shape

Return type

edge_weights (np.ndarray)

kgcnn.graph.methods.shift_coordinates_to_unit_cell(coordinates: numpy.ndarray, lattice: numpy.ndarray)[source]¶

Shift a set of coordinates into the unit cell of a periodic system.

Parameters

coordinates (np.ndarray) – Coordinate of nodes in the central primitive unit cell.
lattice (np.ndarray) – Lattice matrix of real space lattice vectors of shape (3, 3) . The lattice vectors must be given in rows of the matrix!

Returns

Coordinates shifted into unit cell defined by lattice.

Return type

np.ndarray

kgcnn.graph.methods.sort_edge_indices(edge_indices, *args, return_nested: bool = False)[source]¶

Sort edge index list of np.ndarray for the first index and then for the second index. Edge values are rearranged accordingly if passed to the function call.

Parameters

edge_indices (np.ndarray) – Edge indices referring to nodes of shape (N, 2).
args (np.ndarray) – Edge related value arrays to be sorted accordingly of shape (N, …).
return_nested (bool) – Whether to return nested args in addition to indices.

Returns

edge_indices or (edge_indices, *args). Or (edge_indices, args) if return_nested.

Return type

np.ndarray