kgcnn.graph package

Submodules

kgcnn.graph.base module

class kgcnn.graph.base.GraphDict(*args, **kwargs)[source]

Bases: dict

Dictionary container to store graph information in tensor-form.

The tensors must be stored as numpy arrays. The naming convention is not restricted. The class is supposed to be handled just as a python dictionary.

In addition, assign_property and obtain_property handles None values and cast into tensor format, when assigning a named value.

Graph operations that modify edges or sort indices can be applied via apply_preprocessor located in kgcnn.graph.preprocessor.

import numpy as np
from kgcnn.graph.base import GraphDict
graph = GraphDict({"edge_indices": np.array([[1, 0], [0, 1]]), "edge_labels": np.array([[-1], [1]])})
graph.set("graph_labels", [0])  # opposite is get()
graph.set("edge_attributes", [[1.0], [2.0]])
graph.apply_preprocessor("add_edge_self_loops")
graph.apply_preprocessor("sort_edge_indices")
print(graph)
__init__(*args, **kwargs)[source]

Initialize a new GraphDict instance.

apply_preprocessor(name, **kwargs)[source]

Apply a preprocessor on self.

Parameters
Returns

self

assert_has_valid_key(key: str, raise_error: bool = True) → bool[source]

Assert the property is found in self.

Parameters

  • key (str) – Name of property that must be defined.

  • raise_error (bool) – Whether to raise error. Default is True.

Returns

Key is valid. Only if raise_error is False.

Return type

bool

assign_property(key: str, value)[source]

Add a named property as key, value pair to self. If the value is None, nothing is done. Similar to assign-item default method __setitem__, but ignores None values and casts to tensor.

Parameters

  • key (str) – Name of the graph tensor to add to self.

  • value – Array or tensor value to add. Can also be None.

Returns

None.

copy() → a shallow copy of D[source]
find_graph_properties(keys: Union[str, list]) → list

Search for properties in self.

This includes a list of possible names or a pattern-matching of a single string.

Parameters

keys (str, list) – Pattern matching string or list of strings to search for.

Returns

List of names in self that match keys.

Return type

list

from_networkx(graph: networkx.classes.graph.Graph, node_number: str = 'node_number', edge_indices: str = 'edge_indices', node_attributes: Optional[Union[str, List[str]]] = None, edge_attributes: Optional[Union[str, List[str]]] = None, graph_attributes: Optional[Union[str, List[str]]] = None, node_labels: Optional[str] = None, reverse_edge_indices: bool = False)[source]

Convert a networkx graph instance into a dictionary of graph-tensors. The networkx graph is always converted into integer node labels. The former node IDs can be hold in node_labels. Furthermore, node or edge data can be cast into attributes via node_attributes and edge_attributes.

Parameters

  • graph (nx.Graph) – A networkx graph instance to convert.

  • node_number (str) – The name that the node numbers are assigned to. Default is “node_number”.

  • edge_indices (str) – The name that the edge indices are assigned to. Default is “edge_indices”.

  • node_attributes (str, list) – Name of node attributes to add from node data. Can also be a list of names. Default is None.

  • edge_attributes (str, list) – Name of edge attributes to add from edge data. Can also be a list of names. Default is None.

  • graph_attributes (str, list) – Name of graph attributes to add from graph data. Can also be a list of names. Default is None.

  • node_labels (str) – Name of the labels of nodes to store former node IDs into. Default is None.

  • reverse_edge_indices (bool) – Whether to reverse edge indices for notation ‘(ij, i<-j)’. Default is False.

Returns

self.

has_valid_key(key: str) → bool[source]

Check if the property is found in self and also is not Noe.

Parameters

key (str) – Name of property that must be defined.

Returns

Key is valid. Only if raise_error is False.

Return type

bool

obtain_property(key: str)[source]

Get tensor item by name. If key is not found, None is returned.

Parameters

key (str) – Name of the key to get value for.

Returns

self[key].

search_properties(keys: Union[str, list]) → list[source]

Search for properties in self.

This includes a list of possible names or a pattern-matching of a single string.

Parameters

keys (str, list) – Pattern matching string or list of strings to search for.

Returns

List of names in self that match keys.

Return type

list

set(key: str, value)

Add a named property as key, value pair to self. If the value is None, nothing is done. Similar to assign-item default method __setitem__, but ignores None values and casts to tensor.

Parameters

  • key (str) – Name of the graph tensor to add to self.

  • value – Array or tensor value to add. Can also be None.

Returns

None.

to_dict() → dict[source]

Returns a python-dictionary of self. Does not copy values.

Returns

Dictionary of graph tensor objects.

Return type

dict

to_networkx(edge_indices: str = 'edge_indices')[source]

Function draft to make a networkx graph. No attributes or data is supported at the moment.

Parameters

edge_indices (str) – Name of edge index tensors to make graph with. Default is “edge_indices”.

Returns

Directed networkx graph instance.

Return type

nx.DiGraph

update([E, ]**F) → None. Update D from dict/iterable E and F.[source]

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

validate()[source]

Routine to check if items are set correctly, i.e. string key and np.ndarray values. Could be done manually.

kgcnn.graph.base.GraphNumpyContainer

alias of kgcnn.graph.base.GraphDict

class kgcnn.graph.base.GraphPostProcessorBase(*, in_place: bool = False, name: Optional[str] = None)[source]

Bases: kgcnn.graph.base.GraphProcessorBase

Base wrapper for a graph postprocessor to use general transformation functions.

This class inherits from GraphProcessorBase and makes use of _obtain_properties and _assign_properties in a predefined __call__ method. The base class __call__ method retrieves graph properties by name, passes them as kwargs to the call method, which must be implemented by subclasses, and assigns the (array-like) output to a GraphDict by name. To specify the kwargs for call and the names that are expected to be set in the graph dictionary, the class attributes self._to_obtain , self._to_assign , self._to_assign , self._call_kwargs , self._search must be set appropriately in the constructor. The design of this class should be similar to ks.layers.Layer . Example implementation for subclass:

from kgcnn.graph.base import GraphDict, GraphPostProcessorBase

class NewProcessor(GraphPostProcessorBase):

    def __init__(self, name="new_processor", node_property_name="node_number", **kwargs)
        super().__init__(name=name, **kwargs):
        self._to_obtain = {"nodes": node_property_name}  # what 'call' needs as properties
        self._to_obtain_pre = {}
        self._to_assign = ["new_nodes"]  # will be the output of call()
        self._call_kwargs = {"do_nothing": True}
        self._config_kwargs.update({"node_property_name": node_property_name})

    def call(self, nodes: np.ndarray, do_nothing: bool):
        # Do nothing but return the same property.
        return nodes

For proper serialization you should update self._config_kwargs . For information on self._search and self._silent see docs of GraphProcessorBase .

Note that for GraphPostProcessorBase one can also set self._to_obtain_pre if information of the input graph or a previous graph is required, which is common for postprocessing.

__call__(graph: kgcnn.graph.base.GraphDict, pre_graph: Optional[kgcnn.graph.base.GraphDict] = None)[source]

Processing the graph with function given in call .

Parameters

  • graph (GraphDict) – Graph dictionary to process.

  • pre_graph (GraphDict) – Additional graph dictionary with properties to include in call . This is the main difference to preprocessor. Defaults to None.

Returns

Dictionary of new properties.

Return type

dict

__init__(*, in_place: bool = False, name: Optional[str] = None)[source]

Initialize class.

Parameters

  • in_place (bool) – Whether to update graph dict. Default is False.

  • name – Name of the preprocessor.

call(**kwargs)[source]
get_config()[source]

Copy config from self._config_kwargs .

class kgcnn.graph.base.GraphPreProcessorBase(*, in_place: bool = False, name: Optional[str] = None)[source]

Bases: kgcnn.graph.base.GraphProcessorBase

Base wrapper for a graph preprocessor to use general transformation functions.

This class inherits from GraphProcessorBase and makes use of _obtain_properties and _assign_properties in a predefined __call__ method. The base class __call__ method retrieves graph properties by name, passes them as kwargs to the call method, which must be implemented by subclasses, and assigns the (array-like) output to a GraphDict by name. To specify the kwargs for call and the names that are expected to be set in the graph dictionary, the class attributes self._to_obtain , self._to_assign , self._to_assign , self._call_kwargs , self._search must be set appropriately in the constructor. The design of this class should be similar to ks.layers.Layer . Example implementation for subclass:

from kgcnn.graph.base import GraphDict, GraphPreProcessorBase

class NewProcessor(GraphPreProcessorBase):

    def __init__(self, name="new_processor", node_property_name="node_number", **kwargs)
        super().__init__(name=name, **kwargs):
        self._to_obtain = {"nodes": node_property_name}  # what 'call' needs as properties
        self._to_assign = ["new_nodes"]  # will be the output of call()
        self._call_kwargs = {"do_nothing": True}
        self._config_kwargs.update({"node_property_name": node_property_name})

    def call(self, nodes: np.ndarray, do_nothing: bool):
        # Do nothing but return the same property.
        return nodes

For proper serialization you should update self._config_kwargs . For information on self._search and self._silent see docs of GraphProcessorBase .

__call__(graph: kgcnn.graph.base.GraphDict)[source]

Processing the graph with function given in call .

Parameters

graph (GraphDict) – Graph dictionary to process.

Returns

Dictionary of new properties.

Return type

dict

__init__(*, in_place: bool = False, name: Optional[str] = None)[source]

Initialize class.

Parameters

  • in_place (bool) – Whether to update graph dict. Default is False.

  • name – Name of the preprocessor.

call(**kwargs)[source]
get_config()[source]

Copy config from self._config_kwargs .

class kgcnn.graph.base.GraphProcessorBase[source]

Bases: object

General base class for graph processors.

A graph processor should be a subclass that implements a call methods and store all relevant information on how to change the graph properties and how they are supposed to be named in the GraphDict .

from kgcnn.graph.base import GraphDict, GraphProcessorBase

class NewProcessor(GraphProcessorBase):

    def __init__(self, name="new_processor", node_property_name="node_number"):
        self.node_property_name = node_property_name
        self.name = name

    def __call__(self, graph: GraphDict) -> GraphDict:
        # Do nothing but return the same property.
        return GraphDict({self.node_property_name: graph[self.node_property_name]})

    def get_config(self):
        return {"name": self.name, "node_property_name": self.node_property_name}

The class provides utility functions to assign and obtain graph properties to or from a GraphDict by name. Since the namespace on how to name properties in a general GraphDict is not restricted, subclasses of GraphProcessorBase must set the property names in class construction and then can use the utility functions _obtain_properties and _assign_properties.

Additionally, _obtain_properties and _assign_properties can contain a flexible list of properties or a search string that will return multiple properties. This is mainly required to extract a flexible list of properties, for example all edge-related properties via the search string ‘^edge_(?!indices$).*’ that starts with ‘edge_*’ but not ‘edge_indices’. Note that you can always cast to a networkx graph, operate your own functions, then transform back into tensor form and wrap it as a GraphProcessorBase .

static _assign_properties(graph: kgcnn.graph.base.GraphDict, graph_properties: Union[list, numpy.ndarray], to_assign, to_search, in_place=False) → Union[dict, kgcnn.graph.base.GraphDict][source]

Assign a list of arrays to a GraphDict by name.

Parameters

  • graph (GraphDict) – Dictionary with of graph properties. That can be changed in place. Also required to resolve search strings.

  • graph_properties (list, np.ndarray) – Array or list of arrays which are new graph properties

  • to_assign (str, list) – Name-keys or list of name-keys for the graph_properties. If to_assign is list, the length must match graph_properties .

  • to_search (list) – A list of strings that should be considered search strings. Note that in this case there must be a list of arrays in place of a single array, since search strings will return a list of matching strings.

  • in_place (bool) – Whether to update graph argument.

Returns

Dictionary of arrays matched with name-keys.

Return type

dict

static _obtain_properties(graph: kgcnn.graph.base.GraphDict, to_obtain: dict, to_search, to_silent) → dict[source]

Extract a dictionary of named properties from a GraphDict.

Parameters

  • graph (GraphDict) – Dictionary with of graph properties.

  • to_obtain (dict) – Dictionary of keys that holds names or a list of names or a search string of graph properties to fetch. The output dictionary will then have the same keys but with arrays in place of the property name(s). The keys can be used as function arguments for some transform function.

  • to_search (list) – A list of strings that should be considered search strings.

  • to_silent (list) – A list of strings that suppress ‘error not found’ messages.

Returns

A dictionary of resolved graph properties in tensor form.

Return type

dict

static has_special_characters(query, pat=re.compile('[@\\\\!#$%^&*()<>?/|}{~:]'))[source]

Whether a query string has special characters.

kgcnn.graph.postprocessor module

class kgcnn.graph.postprocessor.ExtensiveEnergyForceScalerPostprocessor(scaler, energy: str = 'energy', force: str = 'forces', atomic_number: str = 'node_number', name='extensive_energy_force_scaler', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPostProcessorBase

Postprocessor to inverse-transform energies and forces from a graph dictionary. Note that this postprocessor requires the input- or pre-graph in call method as well.

Parameters

  • scaler – Fitted instance of ExtensiveEnergyForceScaler .

  • energy (str) – Name of energy property in graph dict. Default is ‘energy’.

  • force (str) – Name of force property in graph dict. Default is ‘forces’.

  • atomic_number (str) – Name of atomic_number property in pre_graph dict. Default is ‘node_number’. Must be given in additional pre_graph that is passed to call.

call(y, force, atomic_number)[source]

kgcnn.graph.preprocessor module

class kgcnn.graph.preprocessor.AddEdgeSelfLoops(edge_indices: str = 'edge_indices', edge_attributes: str = '^edge_(?!indices$).*', remove_duplicates: bool = True, sort_indices: bool = True, fill_value: int = 0, name='add_edge_self_loops', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Add self loops to each graph property. The function expects the property edge_indices to be defined. By default, the edges are also sorted after adding the self-loops. All other edge properties are filled with fill_value.

Parameters

  • edge_indices (str) – Name of indices in dictionary. Default is “edge_indices”.

  • edge_attributes (str) – Name of related edge values or attributes. This can be a match-string or list of names. Default is “^edge_(?!indices$).*”.

  • remove_duplicates (bool) – Whether to remove duplicates. Default is True.

  • sort_indices (bool) – To sort indices after adding self-loops. Default is True.

  • fill_value (in) – The fill_value for all other edge properties.

call(*, edge_indices: numpy.ndarray, edge_attributes: list, remove_duplicates: bool, sort_indices: bool, fill_value: bool)[source]
class kgcnn.graph.preprocessor.AtomicChargesRepresentation(*, node_number: str = 'node_number', node_attributes: str = 'node_attributes', name='atomic_charge_representation', one_hot: Optional[list] = None, charge_scale: float = 9.0, charge_power: int = 2, **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Generate a node representation based on atomic charges. Multiplies a one-hot representation of charges with multiple powers of the (scaled) charge itself. This has been used by EGNN.

Parameters

  • node_number (str) – Name of atomic charges in dictionary. Default is “node_number”.

  • node_attributes (str) – Name of related attributes to assign output. Defaults to “node_attributes”.

  • one_hot (list) – List of possible charges. Default is [1, 6, 7, 8, 9].

  • charge_scale (float) – Scale by which the charges are scaled for power. Default is 9.0.

  • charge_power (int) – Maximum power up to which compute charge powers. Default is 2.

call(*, node_number: numpy.ndarray, one_hot: list, charge_scale: float, charge_power: int)[source]
class kgcnn.graph.preprocessor.CountNodesAndEdges(*, total_nodes: str = 'total_nodes', total_edges: str = 'total_edges', count_nodes: str = 'node_attributes', count_edges: str = 'edge_indices', name='count_nodes_and_edges', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Count the number of nodes and edges.

Parameters

  • node_attributes (str) – Name for nodes attributes to count nodes.

  • edge_indices (str) – Name for edge_indices to count edges.

  • count_node (str) – Name to assign node count to.

  • count_edge (str) – Name to assign edge count to.

call(*, count_nodes: numpy.ndarray, count_edges: numpy.ndarray)[source]
class kgcnn.graph.preprocessor.ExpandDistanceGaussianBasis(*, range_attributes: str = 'range_attributes', bins: int = 20, distance: float = 4.0, sigma: float = 0.4, offset: float = 0.0, axis: int = - 1, expand_dims: bool = True, name='expand_distance_gaussian_basis', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Expand distance into Gaussian basis a features or attributes.

Parameters

  • range_attributes (str) – Name of distances in dictionary. Default is “range_attributes”.

  • 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.

call(*, range_attributes: numpy.ndarray, bins: int, distance: float, sigma: float, offset: float, axis: int, expand_dims: bool)[source]
class kgcnn.graph.preprocessor.MakeDenseAdjacencyMatrix(*, edge_indices: str = 'edge_indices', edge_attributes: str = 'edge_attributes', adjacency_matrix: str = 'adjacency_matrix', name='make_dense_adjacency_matrix', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Make adjacency matrix based on edge indices.

Parameters

  • edge_indices (str) – Name of adjacency matrix.

  • edge_attributes (str) – Name of edge attributes.

  • adjacency_matrix (str) – Name of adjacency matrix to assign output.

call(*, edge_indices: numpy.ndarray, edge_attributes: numpy.ndarray)[source]
class kgcnn.graph.preprocessor.MakeMask(*, target_property: str = 'node_attributes', mask_name: Optional[str] = None, rank=1, name='make_mask', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Make simple equally sized (dummy) mask for a graph property.

Parameters

  • target_property (str) – Name of the property to make mask for.

  • mask_name (str) – Name of mask to assign output.

  • rank (int) – Rank of mask.

call(*, target_property: numpy.ndarray, rank: int)[source]
class kgcnn.graph.preprocessor.MakeUndirectedEdges(edge_indices: str = 'edge_indices', edge_attributes: str = '^edge_(?!indices$).*', remove_duplicates: bool = True, sort_indices: bool = True, name='make_undirected_edges', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Add edges \((j, i)\) for \((i, j)\) if there is no edge \((j, i)\). With remove_duplicates an edge can be added even though there is already and edge at \((j, i)\). For other edge tensors, like the attributes or labels, the values of edge \((i, j)\) is added in place. Requires that edge_indices property is assigned.

Parameters

  • edge_indices (str) – Name of indices in dictionary. Default is “edge_indices”.

  • edge_attributes (str) – Name of related edge values or attributes. This can be a match-string or list of names. Default is “^edge_(?!indices$).*”.

  • remove_duplicates (bool) – Whether to remove duplicates within the new edges. Default is True.

  • sort_indices (bool) – Sort indices after adding edges. Default is True.

call(edge_indices: numpy.ndarray, edge_attributes: list, remove_duplicates: bool, sort_indices: bool)[source]
class kgcnn.graph.preprocessor.NormalizeEdgeWeightsSymmetric(*, edge_indices: str = 'edge_indices', edge_weights: str = 'edge_weights', name='normalize_edge_weights_sym', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Normalize edge_weights using the node degree of each row or column of the adjacency matrix. 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}\). Requires the property edge_indices. Does not affect other edge-properties and only sets edge_weights.

Parameters

  • edge_indices (str) – Name of indices in dictionary. Default is “edge_indices”.

  • edge_weights (str) – Name of edge weights indices to set in dictionary. Default is “edge_weights”.

call(*, edge_indices: numpy.ndarray, edge_weights: numpy.ndarray)[source]
class kgcnn.graph.preprocessor.PadProperty(*, key: str, pad_width: Union[int, list, tuple, numpy.ndarray], mode: str = 'constant', name='pad_property', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Pad a graph tensor property.

Parameters

  • key (str) – Name of the (tensor) property to pad.

  • pad_width (list, int) – Width to pad tensor.

  • mode (str) – Padding mode.

call(*, key: numpy.ndarray, pad_width: Union[int, list, tuple, numpy.ndarray], mode: str)[source]
class kgcnn.graph.preprocessor.PrincipalMomentsOfInertia(*, node_mass: str = 'node_mass', node_coordinates: str = 'node_coordinates', graph_inertia: str = 'graph_inertia', name='principal_moments_of_inertia', shift_center_of_mass: bool = True, **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Store the principle moments of the matrix of inertia for a set of node coordinates and masses into a graph property defined by graph_inertia.

Parameters

  • node_mass (str) – Name of node mass in dictionary. Default is “node_mass”.

  • node_coordinates (str) – Name of node coordinates. Defaults to “node_coordinates”.

  • graph_inertia (str) – Name of output property to store moments. Default is “graph_inertia”.

  • shift_center_of_mass (bool) – Whether to shift to center of mass. Default is True.

call(*, node_mass: numpy.ndarray, node_coordinates: numpy.ndarray, shift_center_of_mass: bool)[source]
class kgcnn.graph.preprocessor.SetAngle(*, range_indices: str = 'range_indices', node_coordinates: str = 'node_coordinates', angle_indices: str = 'angle_indices', angle_indices_nodes: str = 'angle_indices_nodes', angle_attributes: str = 'angle_attributes', allow_multi_edges: bool = False, allow_self_edges: bool = False, allow_reverse_edges: bool = False, edge_pairing: str = 'kj', check_sorted: bool = True, compute_angles: bool = True, name='set_angle', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Find possible angles between geometric range connections defined by range_indices. Which edges form angles is stored in angle_indices. One can also change range_indices to edge_indices to compute angles between edges instead of range connections.

Warning

Angles are not recomputed if you use set_range or redefine range or edges.

Parameters

  • range_indices (str) – Name of range indices in dictionary. Default is “range_indices”.

  • node_coordinates (str) – Name of coordinates in dictionary. Default is “node_coordinates”.

  • angle_indices (str) – Name of angle (edge) indices to set in dictionary. Default is “angle_indices”.

  • angle_indices_nodes (str) – Name of angle (node) indices to set in dictionary. Index triplets referring to nodes. Default is “angle_indices_nodes”.

  • angle_attributes (str) – Name of angle values to set in dictionary. Default is “angle_attributes”.

  • allow_multi_edges (bool) – Whether to allow angles between ‘i<-j<-i’, which gives 0-degree angle, if the nodes are unique. Default is False.

  • compute_angles (bool) – Whether to also compute angles.

call(*, range_indices: numpy.ndarray, node_coordinates: numpy.ndarray, check_sorted: bool, allow_multi_edges: bool, allow_self_edges: bool, allow_reverse_edges: bool, edge_pairing: str, compute_angles: bool)[source]
class kgcnn.graph.preprocessor.SetEdgeIndicesReverse(*, edge_indices: str = 'edge_indices', edge_indices_reverse: str = 'edge_indices_reverse', name='set_edge_indices_reverse', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

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)\). Does not affect other edge-properties, only creates a map on edge indices. Edges that do not have a reverse pair get a nan as map index. If there are multiple edges, the first encounter is assigned.

Warning

Reverse maps are not recomputed if you use e.g. sort_edge_indices or redefine edges.

Parameters

  • edge_indices (str) – Name of indices in dictionary. Default is “edge_indices”.

  • edge_indices_reverse (str) – Name of reverse indices to store output. Default is “edge_indices_reverse”

call(*, edge_indices: numpy.ndarray)[source]
class kgcnn.graph.preprocessor.SetEdgeWeightsUniform(*, edge_indices: str = 'edge_indices', edge_weights: str = 'edge_weights', value: float = 1.0, name='set_edge_weights_uniform', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Adds or sets edge_weights with uniform values. Requires property edge_indices. Does not affect other edge-properties and only sets edge_weights.

Parameters

  • edge_indices (str) – Name of indices in dictionary. Default is “edge_indices”.

  • edge_weights (str) – Name of edge weights to set in dictionary. Default is “edge_weights”.

  • value (float) – Value to set edge_weights with. Default is 1.0.

call(*, edge_indices: numpy.ndarray, value: float)[source]
class kgcnn.graph.preprocessor.SetRange(*, range_indices: str = 'range_indices', node_coordinates: str = 'node_coordinates', range_attributes: str = 'range_attributes', max_distance: float = 4.0, max_neighbours: int = 15, do_invert_distance: bool = False, self_loops: bool = False, exclusive: bool = True, name='set_range', overwrite: bool = True, **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Define range in euclidean space for interaction or edge-like connections. The number of connection is determines based on a cutoff radius and a maximum number of neighbours or both. Requires node_coordinates to be set. The distance is stored in range_attributes.

Parameters

  • range_indices (str) – Name of range indices to set in dictionary. Default is “range_indices”.

  • node_coordinates (str) – Name of coordinates in dictionary. Default is “node_coordinates”.

  • range_attributes (str) – Name of range distance to set in dictionary. Default is “range_attributes”.

  • max_distance (float) – Maximum distance or cutoff radius for connections. Default is 4.0.

  • max_neighbours (int) – Maximum number of allowed neighbours for a node. Default is 15.

  • do_invert_distance (bool) – Whether to invert the distance. Default is False.

  • self_loops (bool) – If also self-interactions with distance 0 should be considered. Default is False.

  • exclusive (bool) – Whether both max_neighbours and max_distance must be fulfilled. Default is True.

  • overwrite (bool) – Whether to overwrite existing range indices. Default is True.

call(*, node_coordinates: numpy.ndarray, range_indices: numpy.ndarray, max_distance: float, max_neighbours: int, do_invert_distance: bool, self_loops: bool, exclusive: bool, overwrite: bool)[source]
class kgcnn.graph.preprocessor.SetRangeFromEdges(*, edge_indices: str = 'edge_indices', range_indices: str = 'range_indices', node_coordinates: str = 'node_coordinates', range_attributes: str = 'range_attributes', do_invert_distance: bool = False, name='set_range_from_edges', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Assigns range indices and attributes (distance) from the definition of edge indices. These operations require the attributes node_coordinates and edge_indices to be set. That also means that range_indices will be equal to edge_indices.

Parameters

  • edge_indices (str) – Name of indices in dictionary. Default is “edge_indices”.

  • range_indices (str) – Name of range indices to set in dictionary. Default is “range_indices”.

  • node_coordinates (str) – Name of coordinates in dictionary. Default is “node_coordinates”.

  • range_attributes (str) – Name of range distance to set in dictionary. Default is “range_attributes”.

  • do_invert_distance (bool) – Invert distance when computing range_attributes. Default is False.

call(*, edge_indices: numpy.ndarray, node_coordinates: numpy.ndarray, do_invert_distance: bool)[source]
class kgcnn.graph.preprocessor.SetRangePeriodic(*, range_indices: str = 'range_indices', node_coordinates: str = 'node_coordinates', graph_lattice: str = 'graph_lattice', range_image: str = 'range_image', range_attributes: str = 'range_attributes', max_distance: float = 4.0, max_neighbours: Optional[int] = None, exclusive: bool = True, do_invert_distance: bool = False, self_loops: bool = False, overwrite: bool = True, name='set_range_periodic', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Define range in euclidean space for interaction or edge-like connections on a periodic lattice. The number of connection is determines based on a cutoff radius and a maximum number of neighbours or both. Requires node_coordinates, graph_lattice to be set. The distance is stored in range_attributes.

Parameters

  • range_indices (str) – Name of range indices to set in dictionary. Default is “range_indices”.

  • node_coordinates (str) – Name of coordinates in dictionary. Default is “node_coordinates”.

  • graph_lattice (str) – Name of the lattice matrix. Default is “graph_lattice”. The lattice vectors must be given in rows of the matrix!

  • range_attributes (str) – Name of range distance to set in dictionary. Default is “range_attributes”.

  • range_image (str) – Name of range image indices to set in dictionary. Default is “range_image”.

  • max_distance (float) – Maximum distance or cutoff radius for connections. Default is 4.0.

  • max_neighbours (int, optional) – Maximum number of allowed neighbours for each central atom. Default is None.

  • exclusive (bool) – Whether both distance and maximum neighbours must be fulfilled. Default is True.

  • do_invert_distance (bool) – Whether to invert the distance. Default is False.

  • self_loops (bool) – If also self-interactions with distance 0 should be considered. Default is False.

  • overwrite (bool) – Whether to overwrite existing range indices. Default is True.

call(*, node_coordinates: numpy.ndarray, graph_lattice: numpy.ndarray, range_indices: numpy.ndarray, range_image: numpy.ndarray, max_distance: float, max_neighbours: int, self_loops: bool, exclusive: bool, do_invert_distance: bool, overwrite: bool) → tuple[source]
class kgcnn.graph.preprocessor.ShiftToUnitCell(*, node_coordinates: str = 'node_coordinates', graph_lattice: str = 'graph_lattice', name='shift_to_unit_cell', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Shift atomic coordinates into the Unit cell of a periodic lattice.

Parameters

  • node_coordinates (str) – Name of node coordinates. Defaults to “node_coordinates”.

  • graph_lattice (str) – Name of the graph lattice. Defaults to “graph_lattice”.

call(*, node_coordinates: numpy.ndarray, graph_lattice: numpy.ndarray)[source]
class kgcnn.graph.preprocessor.SortEdgeIndices(*, edge_indices: str = 'edge_indices', edge_attributes: str = '^edge_(?!indices$).*', name='sort_edge_indices', **kwargs)[source]

Bases: kgcnn.graph.base.GraphPreProcessorBase

Sort edge indices and all edge-related properties. The index list is sorted for the first entry.

Parameters

  • edge_indices (str) – Name of indices in dictionary. Default is “edge_indices”.

  • edge_attributes (str) – Name of related edge values or attributes. This can be a match-string or list of names. Default is “^edge_(?!indices$).*”.

call(*, edge_indices: numpy.ndarray, edge_attributes: list)[source]

kgcnn.graph.serial module

kgcnn.graph.serial.get_postprocessor(name: Union[str, dict], **kwargs)[source]

Get a postprocessor.

Parameters

  • name (str, dict) – Serialization dictionary of class. This can also be a name of former graph functions for backward compatibility that now coincides with the processor’s default name.

  • kwargs – Kwargs for processor initialization, if name is string.

Returns

Instance of graph postprocessor.

Return type

GraphPostProcessorBase

kgcnn.graph.serial.get_preprocessor(name: Union[str, dict], **kwargs)[source]

Get a preprocessor.

Parameters

  • name (str, dict) – Serialization dictionary of class. This can also be a name of former graph functions for backward compatibility that now coincides with the processor’s default name.

  • kwargs – Kwargs for processor initialization, if name is string.

Returns

Instance of graph preprocessor.

Return type

GraphPreProcessorBase

Module contents