m3gnet.graph package

Module contents

Graph package

class m3gnet.graph.BaseGraphConverter(*args, **kwargs)

Bases: keras.engine.base_layer.Layer

Basic graph converter that uses the atomic number as the node feature

abstract convert(structure: Union[pymatgen.core.structure.Structure, pymatgen.core.structure.Molecule, ase.atoms.Atoms], **kwargs) → m3gnet.graph._types.MaterialGraph

Convert the structure into a graph Args:

structure: **kwargs:

Returns:

convert_many(structures: List[Union[pymatgen.core.structure.Structure, pymatgen.core.structure.Molecule, ase.atoms.Atoms]], **kwargs) → m3gnet.graph._types.MaterialGraph

Convert many structures into one single graph Args:

structures: List of structures **kwargs:

Returns: MaterialGraph

static get_atom_features(structure) → numpy.ndarray

Get atom features from structure, may be overwritten Args:

structure: (Pymatgen.Structure) pymatgen structure

Returns:

List of atomic numbers

get_states(structure: Union[pymatgen.core.structure.Structure, pymatgen.core.structure.Molecule, ase.atoms.Atoms])

Get the state attributes from a structure Args:

structure (StructureOrMolecule): structure to compute the states

Returns: tf.Tensor or np.ndarray

set_default_states(states=None)

set the default states for MaterialGraph Args:

states (np.ndarray or tf.Tensor): the state attributes

Returns:

class m3gnet.graph.Index

Bases: object

Get integer indices for each field in MaterialGraph

ATOMS = 0

ATOM_POSITIONS = 3

BONDS = 1

BOND_ATOM_INDICES = 4

BOND_WEIGHTS = 8

LATTICES = 9

N_ATOMS = 6

N_BONDS = 7

N_TRIPLE_I = 15

N_TRIPLE_IJ = 14

N_TRIPLE_S = 16

PBC_OFFSETS = 5

PHI = 13

STATES = 2

THETA = 12

TRIPLE_BOND_INDICES = 10

TRIPLE_BOND_LENGTHS = 11

class m3gnet.graph.MaterialGraph(atoms: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, bonds: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, states: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, bond_atom_indices: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, n_atoms: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, n_bonds: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, atom_positions: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, bond_weights: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, pbc_offsets: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, lattices: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, triple_bond_indices: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, triple_bond_lengths: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, theta: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, phi: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, n_triple_ij: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, n_triple_i: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None, n_triple_s: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None)

Bases: m3gnet.graph._types.AttributeUpdateMixin

Material graph by an edge list graph representation. In this representation, no padding of atoms or bonds are needed.

Full available data names are the following, assuming the number of atoms is n_atom, number of bonds is n_bond and number of structure is n_struct.

The attributes are as follows

• atoms (np.ndarray): atom attributes with shape [n_atom, None]

• bonds (np.ndarray): bond attributes with shape [n_bond, None]

  states (np.ndarray): state attributes with shape [n_struct, None] bond_atom_indices (np.ndarray): int indices for pairs of atoms, shape [n_bond, 2]

• n_atoms (np.ndarray): int array, number of atoms in each structure,

  [n_struct]

• n_bonds (np.ndarray): int array, number of bonds in each structure,

  [n_struct]

• atom_positions (np.ndarray): float type, atom position array, shape

  [n_atom, 3]

• bond_weights (np.ndarray): float type, bond lengths, shape [n_bond]

• pbc_offsets (np.ndarray): int type, periodic boundary offset

  vectors, shape [n_bond, 3].

• lattices (np.ndarray): float type, lattice matrices for all

  structures, shape [n_struct, 3, 3]

• triple_bond_indices (np.ndarray): int type, the bond indices for

  forming triple bonds

• triple_bond_lengths (np.ndarray): float type, the triple bond

  lengths

• theta (np.ndarray): float type,the azimuthal angle of the triple

  bond

• phi (np.ndarray): float type, the polar angle of the triple bond

• n_triple_ij (np.ndarray): int type, the number of triple bonds for

  each bond

• n_triple_i (np.ndarray): int type, the number of triple bonds for

  each atom

• n_triple_s (np.ndarray): int type, the number of triple bonds

  for each structure

as_list() → List

Convert the MaterialGraph to list representation Returns:

as_tf() → m3gnet.graph._types.MaterialGraph

Convert each field to tensorflow tensors Returns: tf.Tensor

atom_positions: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

atoms: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

base_attributes: ClassVar[List[str]] = ['atoms', 'bonds', 'bond_atom_indices', 'n_atoms', 'n_bonds']

bond_atom_indices: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

bond_weights: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

bonds: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

copy() → m3gnet.graph._types.MaterialGraph

Copy the MaterialGraph to a new one Returns: MaterialGraph

classmethod from_list(graph_list)

Construct the MaterialGraph object from a list representation Args:

graph_list (list): list representation of a MaterialGraph

Returns: MaterialGraph instance

graph_with_position_attributes: ClassVar[List[str]] = ['atoms', 'bond_atom_indices', 'atom_positions', 'bond_weights', 'n_atoms', 'n_bonds', 'pbc_offsets', 'lattices']

property has_threebody: bool

Whether the graph has threebody indices Returns: boolean value indicator

lattices: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

property n_atom: Optional[int]

number of atoms in the graph Returns: int or None

n_atoms: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

property n_bond: Optional[int]

number of bonds Returns: int or None

n_bonds: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

property n_struct: Optional[int]

number of structures Returns: int or None

n_triple_i: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

n_triple_ij: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

n_triple_s: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

pbc_offsets: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

phi: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

states: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

theta: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

three_body_attributes: ClassVar[List[str]] = ['triple_bond_indices', 'triple_bond_lengths', 'theta', 'phi', 'n_triple_ij', 'n_triple_i', 'n_triple_s']

triple_bond_indices: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

triple_bond_lengths: Optional[Union[numpy.ndarray, tensorflow.python.framework.ops.Tensor]] = None

class m3gnet.graph.MaterialGraphBatch(graphs: List[m3gnet.graph._types.MaterialGraph], targets: Optional[numpy.ndarray] = None, batch_size: int = 128, shuffle: bool = True)

Bases: keras.utils.data_utils.Sequence

MaterialGraphBatch for generating batches of MaterialGraphs

on_epoch_end() → None

Operations at the end of each training epoch

class m3gnet.graph.MaterialGraphBatchEnergyForceStress(graphs: List[m3gnet.graph._types.MaterialGraph], energies: Optional[Union[List, numpy.ndarray]] = None, forces: Optional[List[numpy.ndarray]] = None, stresses: Optional[List[numpy.ndarray]] = None, batch_size: int = 128, shuffle: bool = True)

Bases: m3gnet.graph._batch.MaterialGraphBatch

MaterialGraphBatch for generating batches of MaterialGraphs

class m3gnet.graph.RadiusCutoffGraphConverter(*args, **kwargs)

Bases: m3gnet.graph._converters.BaseGraphConverter

Constructing a material graph with fixed radius cutoff

convert(structure: Union[pymatgen.core.structure.Structure, pymatgen.core.structure.Molecule, ase.atoms.Atoms], **kwargs) → m3gnet.graph._types.MaterialGraph

Convert the structure into graph Args:

structure: Structure or Molecule

Returns

MaterialGraph

get_config() → Dict

Get serialized dictionary Returns: Dict

m3gnet.graph.assemble_material_graph(graphs)

Collate a list of MaterialGraph and form a single MaterialGraph

Args:

graphs: list of MaterialGraph

Returns: a single MaterialGraph

m3gnet.graph.get_fixed_radius_bonding(structure: Union[pymatgen.core.structure.Structure, pymatgen.core.structure.Molecule, ase.atoms.Atoms], cutoff: float = 5.0, numerical_tol: float = 1e-08) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

Get graph representations from structure within cutoff Args:

structure (pymatgen Structure or molecule) cutoff (float): cutoff radius numerical_tol (float): numerical tolerance

Returns:

center_indices, neighbor_indices, images, distances

m3gnet.graph.get_pair_vector_from_graph(graph: List)

Given a graph list return pair vectors that form the bonds Args:

graph (List): graph list, obtained by MaterialGraph.as_list()

Returns: pair vector tf.Tensor

m3gnet.graph.include_threebody_indices(graph: Union[m3gnet.graph._types.MaterialGraph, List], threebody_cutoff: Optional[float] = None)

Given a graph without threebody indices, add the threebody indices according to a threebody cutoff radius Args:

graph: MaterialGraph threebody_cutoff: float, threebody cutoff radius

Returns: new graph with added threebody indices

m3gnet.graph.tf_compute_distance_angle(graph: List)

Given a graph with pair, triplet indices, calculate the pair distance, triplet angles, etc. Args:

graph: MaterialGraph in List format

Returns: MaterialGraph in List format