graph2mat.core.data.table

Storage of global basis information for a group of configurations.

In a dataset, different point types are represented by an integer that is the type index. However, there are moments in which information of what that type means is required. E.g. to know what’s the size of the basis for that point or what are its irreps.

All the data for the types that a model might see is stored in an object that we call a “Table”.

In a typical matrix, there will be elements that belong to connections between different points. Therefore, these tables also need to keep track of edge types.

Classes

`AtomicTableWithEdges`(atoms)	Variant of `BasisTableWithEdges` for the case in which points are atoms.
`BasisTableWithEdges`(basis[, get_point_matrix])	Stores the unique types of points in the system, with their basis and the possible edges.

class graph2mat.core.data.table.AtomicTableWithEdges(atoms: Sequence[Atom])[source]

Bases: BasisTableWithEdges

Variant of BasisTableWithEdges for the case in which points are atoms.

This class mostly just adds a few aliases to the methods of BasisTableWithEdges by replacing “point” to “atom” in the method names. It also provides some methods to create a table from atomic basis.

See also

BasisTableWithEdges: The class that actually does the work.

R: ndarray: Shape (n_point_types,). The reach of each point type.

__init__(atoms: Sequence[Atom])[source]

atom_block_pointer(atom_types: Sequence[int])[source]

property atom_block_shape

property atom_block_size

atom_type_to_edge_type(atom_type: ndarray)[source]

property atomic_DM

atoms: List[Atom]

basis: List[PointBasis]: List of PointBasis objects that this table knows about.

basis_convention: str | Literal['cartesian', 'spherical', 'siesta_spherical', 'qe_spherical']: The spherical harmonics convention used for the basis (same for all PointBasis).

basis_size: ndarray: Shape (n_point_types,). The number of basis functions for each point type.

change_of_basis: ndarray: Shape (3, 3). The change of basis matrix from cartesian to the convention of the basis.

change_of_basis_inv: ndarray: Shape (3, 3). The change of basis matrix from the convention of the basis to cartesian.

edge_block_shape: ndarray: Shape (n_edge_types, 2). The shape of interaction matrix blocks of each edge type.

edge_block_size: ndarray: Shape (n_edge_types,). The number of elements for interaction matrix blocks of each edge type.

edge_type: ndarray: The edge type for each pair of point types. Array of shape (n_point_types, n_point_types).

edge_type_to_point_types: ndarray: Shape (n_edge_types, 2). For each (positive) edge index, returns the pair of point types that make it. This performs the inverse operation of edge_type.

file_contents: List[str] | None: If the basis was read from files, this might store the contents of the files. For saving/loading purposes.

file_names: List[str] | None: If the basis was read from files, this might store the names of the files. For saving/loading purposes.

classmethod from_basis_dir(basis_dir: str, basis_ext: str = 'ion.xml', no_basis_atoms: dict | None = None) → AtomicTableWithEdges[source]

Generates a table from a directory containing basis files.

Parameters:

basis_dir – The directory containing the basis files.
basis_ext – The extension of the basis files.

classmethod from_basis_glob(basis_glob: str | Generator, no_basis_atoms: dict | None = None) → AtomicTableWithEdges[source]

Generates a table from basis files that match a glob pattern.

Parameters:: basis_glob – The glob pattern to match the basis files.

point_block_shape: ndarray: Shape (n_point_types, 2). The shape of self-interacting matrix blocks of each point type.

point_block_size: ndarray: Shape (n_point_types,). The number of elements for self-interacting matrix blocks of each point type.

point_matrix: List[ndarray] | None: The matrix that is constant for each type of point.

types: List[str | int]: Type identifier for each point basis.

property zs

class graph2mat.core.data.table.BasisTableWithEdges(basis: Sequence[PointBasis], get_point_matrix: Callable | None = None)[source]

Bases: object

Stores the unique types of points in the system, with their basis and the possible edges.

It also knows the size of the blocks, and other type dependent variables.

Its function is to assist in pre and post processing data by providing a centralized source of truth for the basis that a model should be able to deal with.

Parameters:

basis (List[graph2mat.core.data.basis.PointBasis]) – List of PointBasis objects for types that are (possibly) present in the systems of interest.
get_point_matrix –
A function that takes a PointBasis object and returns the matrix that is a constant for that type of point.

The constant matrix can be substracted from the training examples so that the models only need to learn the part that is different.

A sensible choice for this constant matrix would be the matrix of the point if it was isolated in the system, because then what the models learn is the result of the interaction with other points.

However, this might not make any sense for your particular problem. In that case just don’t use this argument.

R: ndarray: Shape (n_point_types,). The reach of each point type.

__init__(basis: Sequence[PointBasis], get_point_matrix: Callable | None = None)[source]

basis: List[PointBasis]: List of PointBasis objects that this table knows about.

basis_convention: str | Literal['cartesian', 'spherical', 'siesta_spherical', 'qe_spherical']: The spherical harmonics convention used for the basis (same for all PointBasis).

basis_size: ndarray: Shape (n_point_types,). The number of basis functions for each point type.

change_of_basis: ndarray: Shape (3, 3). The change of basis matrix from cartesian to the convention of the basis.

change_of_basis_inv: ndarray: Shape (3, 3). The change of basis matrix from the convention of the basis to cartesian.

edge_block_pointer(edge_types: Sequence[int])[source]

Pointers to the beggining of edge blocks in a flattened matrix.

Given a flat array that contains all the elements of the matrix corresponing to matrix blocks of interactions between two different points, the indices returned here point to the beggining of the values for each block.

These pointers are useful to recreate the full matrix, for example.

Parameters:: edge_types – The type indices for the edges in the system, in the order in which they appear in the flattened matrix.

edge_block_shape: ndarray: Shape (n_edge_types, 2). The shape of interaction matrix blocks of each edge type.

edge_block_size: ndarray: Shape (n_edge_types,). The number of elements for interaction matrix blocks of each edge type.

edge_type: ndarray: The edge type for each pair of point types. Array of shape (n_point_types, n_point_types).

edge_type_to_point_types: ndarray: Shape (n_edge_types, 2). For each (positive) edge index, returns the pair of point types that make it. This performs the inverse operation of edge_type.

file_contents: List[str] | None: If the basis was read from files, this might store the contents of the files. For saving/loading purposes.

file_names: List[str] | None: If the basis was read from files, this might store the names of the files. For saving/loading purposes.

get_sisl_atoms() → List[Atom][source]

Returns a list of sisl atoms corresponding to the basis.

If the basis does not contain atoms, PointBasis objects are converted to atoms.

group(grouping: Literal['basis_shape', 'point_type', 'max']) → tuple[BasisTableWithEdges, ndarray, ndarray, ndarray | None][source]

Groups the basis in this table and creates a new table.

It also returns useful objects to convert between the ungrouped and the grouped basis tables.

Parameters:

grouping –

Method to group point types. The options are:

"point_type": No grouping.

"basis_shape": Groups all point types that have the same basis shape. In a basis of spherical harmonics, “same basis shape” means that the number of basis functions for each angular momentum \(\ell\) is the same. Note that the radial functions might differ, but they are not considered when grouping.

"max": Groups all point types into a single group.

Returns:

new_table – The new table with the grouped point types.
point_type_conversion – Array of shape (n_point_types,) that maps the point types in the old table to the point types in the new table. E.g. if one has the original point types they can be converted to the new point types by doing:
```
new_point_types = point_type_conversion[old_point_types]
```
To save memory, point_type_conversion is not a real array when grouping == "point_type". It is just a dummy object that returns the key when indexed: point_type_conversion[key] == key.
edge_type_conversion – Array of shape (n_edge_types,) that maps the edge types in the old table to the edge types in the new table. E.g. if one has the original edge types they can be converted to the new edge types by doing:
```
new_edge_types = edge_type_conversion[old_edge_types]
```
To save memory, edge_type_conversion is not a real array when grouping == "point_type". It is just a dummy object that returns the key when indexed: edge_type_conversion[key] == key.
filters – This is None unless grouping == "max".

In that case, it is an array of shape (n_point_types, dim_new_basis). For each original point type (first dimension), it contains a mask to select the values of the new basis that correspond to it. E.g.:
```
values = ... # some computation with the grouped basis (dim_new_basis, )
type0_values = values[filters[0]]
```

index_to_type(index: int) → str | int[source]

Converts from the index of the point type to the type ID.

Parameters:: index – The index of the point type in the table for which the ID is desired.

maxR() → float[source]: Maximum cutoff radius in the basis.

point_block_pointer(point_types: Sequence[int]) → ndarray[source]

Pointers to the beggining of node blocks in a flattened matrix.

Given a flat array that contains all the elements of the matrix corresponing to self-interacting matrix blocks, the indices returned here point to the beggining of the values for each block.

These pointers are useful to recreate the full matrix, for example.

Parameters:: point_types – The type indices for the points in the system, in the order in which they appear in the flattened matrix.

point_block_shape: ndarray: Shape (n_point_types, 2). The shape of self-interacting matrix blocks of each point type.

point_block_size: ndarray: Shape (n_point_types,). The number of elements for self-interacting matrix blocks of each point type.

point_matrix: List[ndarray] | None: The matrix that is constant for each type of point.

point_type_to_edge_type(point_type: ndarray) → int | ndarray[source]

Converts pairs of point types to edge types.

Parameters:: point_type – Shape (2, n_edges) Pair of point types for each edge.

type_to_index(point_type: str | int) → int[source]

Converts from the type ID to the index of the point type in the table.

Parameters:: point_type – The type ID of the point type for which the index in the table is desired.

types: List[str | int]: Type identifier for each point basis.

types_to_indices(types: Sequence) → ndarray[source]

Converts from an array of types IDs to their indices in the basis table.

Parameters:: types – The array of types to convert.