jarvis.core.graphs
==================

.. py:module:: jarvis.core.graphs

.. autoapi-nested-parse::

   Module to generate networkx graphs.



Classes
-------

.. autoapisummary::

   jarvis.core.graphs.Graph
   jarvis.core.graphs.Standardize
   jarvis.core.graphs.StructureDataset


Functions
---------

.. autoapisummary::

   jarvis.core.graphs.canonize_edge
   jarvis.core.graphs.nearest_neighbor_edges
   jarvis.core.graphs.build_undirected_edgedata
   jarvis.core.graphs.prepare_dgl_batch
   jarvis.core.graphs.prepare_line_graph_batch
   jarvis.core.graphs.compute_bond_cosines


Module Contents
---------------

.. py:function:: canonize_edge(src_id, dst_id, src_image, dst_image)

   Compute canonical edge representation.

   Sort vertex ids
   shift periodic images so the first vertex is in (0,0,0) image


.. py:function:: nearest_neighbor_edges(atoms=None, cutoff=8, max_neighbors=12, id=None, use_canonize=True)

   Construct k-NN edge list.


.. py:function:: build_undirected_edgedata(atoms=None, edges={})

   Build undirected graph data from edge set.

   edges: dictionary mapping (src_id, dst_id) to set of dst_image
   r: cartesian displacement vector from src -> dst


.. py:class:: Graph(nodes=[], node_attributes=[], edges=[], edge_attributes=[], color_map=None, labels=None)

   Bases: :py:obj:`object`


   Generate a graph object.


   .. py:attribute:: nodes
      :value: []



   .. py:attribute:: node_attributes
      :value: []



   .. py:attribute:: edges
      :value: []



   .. py:attribute:: edge_attributes
      :value: []



   .. py:attribute:: color_map
      :value: None



   .. py:attribute:: labels
      :value: None



   .. py:method:: atom_dgl_multigraph(atoms=None, neighbor_strategy='k-nearest', cutoff=8.0, max_neighbors=12, atom_features='cgcnn', max_attempts=3, id: Optional[str] = None, compute_line_graph: bool = True, use_canonize: bool = True)
      :staticmethod:


      Obtain a DGLGraph for Atoms object.



   .. py:method:: from_atoms(atoms=None, get_prim=False, zero_diag=False, node_atomwise_angle_dist=False, node_atomwise_rdf=False, features='basic', enforce_c_size=10.0, max_n=100, max_cut=5.0, verbose=False, make_colormap=True)
      :staticmethod:


      Get Networkx graph. Requires Networkx installation.

      Args:
           atoms: jarvis.core.Atoms object.

           rcut: cut-off after which distance will be set to zero
                 in the adjacency matrix.

           features: Node features.
                     'atomic_number': graph with atomic numbers only.
                     'cfid': 438 chemical descriptors from CFID.
                     'cgcnn': hot encoded 92 features.
                     'basic':10 features
                     'atomic_fraction': graph with atomic fractions
                                       in 103 elements.
                     array: array with CFID chemical descriptor names.
                     See: jarvis/core/specie.py

           enforce_c_size: minimum size of the simulation cell in Angst.



   .. py:method:: to_networkx()

      Get networkx representation.



   .. py:property:: num_nodes

      Return number of nodes in the graph.



   .. py:property:: num_edges

      Return number of edges in the graph.



   .. py:method:: from_dict(d={})
      :classmethod:


      Constuct class from a dictionary.



   .. py:method:: to_dict()

      Provide dictionary representation of the Graph object.



   .. py:method:: __repr__()

      Provide representation during print statements.



   .. py:property:: adjacency_matrix

      Provide adjacency_matrix of graph.



.. py:class:: Standardize(mean: torch.Tensor, std: torch.Tensor)

   Bases: :py:obj:`torch.nn.Module`


   Standardize atom_features: subtract mean and divide by std.


   .. py:attribute:: mean


   .. py:attribute:: std


   .. py:method:: forward(g: dgl.DGLGraph)

      Apply standardization to atom_features.



.. py:function:: prepare_dgl_batch(batch: Tuple[dgl.DGLGraph, torch.Tensor], device=None, non_blocking=False)

   Send batched dgl crystal graph to device.


.. py:function:: prepare_line_graph_batch(batch: Tuple[Tuple[dgl.DGLGraph, dgl.DGLGraph], torch.Tensor], device=None, non_blocking=False)

   Send line graph batch to device.

   Note: the batch is a nested tuple, with the graph and line graph together


.. py:function:: compute_bond_cosines(edges)

   Compute bond angle cosines from bond displacement vectors.


.. py:class:: StructureDataset(df: pandas.DataFrame, graphs: Sequence[dgl.DGLGraph], target: str, atom_features='atomic_number', transform=None, line_graph=False, classification=False, id_tag='jid')

   Bases: :py:obj:`torch.utils.data.Dataset`


   Dataset of crystal DGLGraphs.


   .. py:attribute:: df


   .. py:attribute:: graphs


   .. py:attribute:: target


   .. py:attribute:: line_graph
      :value: False



   .. py:attribute:: labels


   .. py:attribute:: ids


   .. py:attribute:: transform
      :value: None



   .. py:attribute:: prepare_batch


   .. py:method:: _get_attribute_lookup(atom_features: str = 'cgcnn')
      :staticmethod:


      Build a lookup array indexed by atomic number.



   .. py:method:: __len__()

      Get length.



   .. py:method:: __getitem__(idx)

      Get StructureDataset sample.



   .. py:method:: setup_standardizer(ids)

      Atom-wise feature standardization transform.



   .. py:method:: collate(samples: List[Tuple[dgl.DGLGraph, torch.Tensor]])
      :staticmethod:


      Dataloader helper to batch graphs cross `samples`.



   .. py:method:: collate_line_graph(samples: List[Tuple[dgl.DGLGraph, dgl.DGLGraph, torch.Tensor]])
      :staticmethod:


      Dataloader helper to batch graphs cross `samples`.