class_docstr: Crystal Graph Convolutional Neural Network (CGCNN).
  
  This model takes arbitary crystal structures as an input, and predict material properties
  using the element information and connection of atoms in the crystal. If you want to get
  some material properties which has a high computational cost like band gap in the case
  of DFT, this model may be useful. This model is one of variants of Graph Convolutional
  Networks. The main differences between other GCN models are how to construct graphs and
  how to update node representations. This model defines the crystal graph from structures
  using distances between atoms. The crystal graph is an undirected multigraph which is defined
  by nodes representing atom properties and edges representing connections between atoms
  in a crystal. And, this model updates the node representations using both neighbor node
  and edge representations. Please confirm the detail algorithms from [1]_.
  
  Examples
  --------
  >>> import deepchem as dc
  >>> from pymatgen.core import Lattice, Structure
  >>> lattice = Lattice.cubic(4.2)
  >>> structure = Structure(lattice, ["Cs", "Cl"], [[0, 0, 0], [0.5, 0.5, 0.5]])
  >>> featurizer = dc.feat.CGCNNFeaturizer()
  >>> cgcnn_feat = featurizer.featurize([structure])[0]
  >>> print(type(cgcnn_feat))
  <class 'deepchem.feat.graph_data.GraphData'>
  >>> cgcnn_dgl_feat = cgcnn_feat.to_dgl_graph()
  >>> print(type(cgcnn_dgl_feat))
  <class 'dgl.heterograph.DGLGraph'>
  >>> model = dc.models.CGCNN(mode='regression', n_tasks=2)
  >>> out = model(cgcnn_dgl_feat)
  >>> print(type(out))
  <class 'torch.Tensor'>
  >>> out.shape == (1, 2)
  True
  
  References
  ----------
  .. [1] Xie, Tian, and Jeffrey C. Grossman. "Crystal graph convolutional neural networks
      for an accurate and interpretable prediction of material properties." Physical review letters
      120.14 (2018): 145301.
  
  Notes
  -----
  This class requires DGL and PyTorch to be installed.
class_docstr_tok: ["Crystal","Graph","Convolutional","Neural","Network","(","CGCNN",")",".","This","model","takes","arbitary","crystal","structures","as","an","input",",","and","predict","material","properties","using","the","element","information","and","connection","of","atoms","in","the","crystal",".","If","you","want","to","get","some","material","properties","which","has","a","high","computational","cost","like","band","gap","in","the","case","of","DFT",",","this","model","may","be","useful",".","This","model","is","one","of","variants","of","Graph","Convolutional","Networks",".","The","main","differences","between","other","GCN","models","are","how","to","construct","graphs","and","how","to","update","node","representations",".","This","model","defines","the","crystal","graph","from","structures","using","distances","between","atoms",".","The","crystal","graph","is","an","undirected","multigraph","which","is","defined","by","nodes","representing","atom","properties","and","edges","representing","connections","between","atoms","in","a","crystal",".","And",",","this","model","updates","the","node","representations","using","both","neighbor","node","and","edge","representations",".","Please","confirm","the","detail","algorithms","from","[","1","]","_",".","Examples","--","--","--","--",">",">",">","import","deepchem","as","dc",">",">",">","from","pymatgen.core","import","Lattice",",","Structure",">",">",">","lattice","=","Lattice.cubic","(","4.2",")",">",">",">","structure","=","Structure","(","lattice",",","[","``","Cs","''",",","``","Cl","''","]",",","[","[","0",",","0",",","0","]",",","[","0.5",",","0.5",",","0.5","]","]",")",">",">",">","featurizer","=","dc.feat.CGCNNFeaturizer","(",")",">",">",">","cgcnn_feat","=","featurizer.featurize","(","[","structure","]",")","[","0","]",">",">",">","print","(","type","(","cgcnn_feat",")",")","<","class","'deepchem.feat.graph_data.GraphData","'",">",">",">",">","cgcnn_dgl_feat","=","cgcnn_feat.to_dgl_graph","(",")",">",">",">","print","(","type","(","cgcnn_dgl_feat",")",")","<","class","'dgl.heterograph.DGLGraph","'",">",">",">",">","model","=","dc.models.CGCNN","(","mode='regression","'",",","n_tasks=2",")",">",">",">","out","=","model","(","cgcnn_dgl_feat",")",">",">",">","print","(","type","(","out",")",")","<","class","'torch.Tensor","'",">",">",">",">","out.shape","==","(","1",",","2",")","True","References","--","--","--","--","--","..","[","1","]","Xie",",","Tian",",","and","Jeffrey","C.","Grossman",".","``","Crystal","graph","convolutional","neural","networks","for","an","accurate","and","interpretable","prediction","of","material","properties",".","''","Physical","review","letters","120.14","(","2018",")",":","145301",".","Notes","--","--","-","This","class","requires","DGL","and","PyTorch","to","be","installed","."]
docstr: Predict labels
  
  Parameters
  ----------
  dgl_graph: DGLGraph
      DGLGraph for a batch of graphs. The graph expects that the node features
      are stored in `ndata['x']`, and the edge features are stored in `edata['edge_attr']`.
  
  Returns
  -------
  out: torch.Tensor
      The output values of this model.
      If mode == 'regression', the shape is `(batch_size, n_tasks)`.
      If mode == 'classification', the shape is `(batch_size, n_tasks, n_classes)` (n_tasks > 1)
      or `(batch_size, n_classes)` (n_tasks == 1) and the output values are probabilities of each class label.
docstr_tok: ["Predict","labels","Parameters","--","--","--","--","--","dgl_graph",":","DGLGraph","DGLGraph","for","a","batch","of","graphs",".","The","graph","expects","that","the","node","features","are","stored","in","`","ndata","[","'","x","'","]","`",",","and","the","edge","features","are","stored","in","`","edata","[","'edge_attr","'","]","`",".","Returns","--","--","--","-","out",":","torch.Tensor","The","output","values","of","this","model",".","If","mode","==","'regression","'",",","the","shape","is","`","(","batch_size",",","n_tasks",")","`",".","If","mode","==","'classification","'",",","the","shape","is","`","(","batch_size",",","n_tasks",",","n_classes",")","`","(","n_tasks",">","1",")","or","`","(","batch_size",",","n_classes",")","`","(","n_tasks","==","1",")","and","the","output","values","are","probabilities","of","each","class","label","."]
code: def forward(self, dgl_graph):
      """Predict labels
  
      Parameters
      ----------
      dgl_graph: DGLGraph
          DGLGraph for a batch of graphs. The graph expects that the node features
          are stored in `ndata['x']`, and the edge features are stored in `edata['edge_attr']`.
  
      Returns
      -------
      out: torch.Tensor
          The output values of this model.
          If mode == 'regression', the shape is `(batch_size, n_tasks)`.
          If mode == 'classification', the shape is `(batch_size, n_tasks, n_classes)` (n_tasks > 1)
          or `(batch_size, n_classes)` (n_tasks == 1) and the output values are probabilities of each class label.
      """
      graph = dgl_graph
      # embedding node features
      node_feats = graph.ndata.pop("x")
      edge_feats = graph.edata.pop("edge_attr")
      node_feats = self.embedding(node_feats)
  
      # convolutional layer
      for conv in self.conv_layers:
          node_feats = conv(graph, node_feats, edge_feats)
  
      # pooling
      graph.ndata["updated_x"] = node_feats
      graph_feat = F.softplus(self.pooling(graph, "updated_x"))
      graph_feat = F.softplus(self.fc(graph_feat))
      out = self.out(graph_feat)
  
      if self.mode == "regression":
          return out
      else:
          logits = out.view(-1, self.n_tasks, self.n_classes)
          # for n_tasks == 1 case
          logits = torch.squeeze(logits)
          proba = F.softmax(logits)
          return proba, logits
  
file_path: deepchem/deepchem/models/torch_models/cgcnn.py
imports: import torch
  import torch.nn
  import torch.nn.functional
  from deepchem.models.losses import Loss, L2Loss, SparseSoftmaxCrossEntropy
  from deepchem.models.torch_models.torch_model import TorchModel
label_desc: Use image node_id 2 for calling the CGCNN obj's underlying member method code with example usage: obj.forward(dgl_graph) and returns: out, proba,  logits