class_docstr: This dependency parser follows the model of
  ` Deep Biaffine Attention for Neural Dependency Parsing (Dozat and Manning, 2016)
  <https://arxiv.org/abs/1611.01734>`_ .
  
  Word representations are generated using a bidirectional LSTM,
  followed by separate biaffine classifiers for pairs of words,
  predicting whether a directed arc exists between the two words
  and the dependency label the arc should have. Decoding can either
  be done greedily, or the optimial Minimum Spanning Tree can be
  decoded using Edmond's algorithm by viewing the dependency tree as
  a MST on a fully connected graph, where nodes are words and edges
  are scored dependency arcs.
  
  Parameters
  ----------
  vocab : ``Vocabulary``, required
      A Vocabulary, required in order to compute sizes for input/output projections.
  text_field_embedder : ``TextFieldEmbedder``, required
      Used to embed the ``tokens`` ``TextField`` we get as input to the model.
  encoder : ``Seq2SeqEncoder``
      The encoder (with its own internal stacking) that we will use to generate representations
      of tokens.
  tag_representation_dim : ``int``, required.
      The dimension of the MLPs used for dependency tag prediction.
  arc_representation_dim : ``int``, required.
      The dimension of the MLPs used for head arc prediction.
  tag_feedforward : ``FeedForward``, optional, (default = None).
      The feedforward network used to produce tag representations.
      By default, a 1 layer feedforward network with an elu activation is used.
  arc_feedforward : ``FeedForward``, optional, (default = None).
      The feedforward network used to produce arc representations.
      By default, a 1 layer feedforward network with an elu activation is used.
  pos_tag_embedding : ``Embedding``, optional.
      Used to embed the ``pos_tags`` ``SequenceLabelField`` we get as input to the model.
  use_mst_decoding_for_validation : ``bool``, optional (default = True).
      Whether to use Edmond's algorithm to find the optimal minimum spanning tree during validation.
      If false, decoding is greedy.
  dropout : ``float``, optional, (default = 0.0)
      The variational dropout applied to the output of the encoder and MLP layers.
  input_dropout : ``float``, optional, (default = 0.0)
      The dropout applied to the embedded text input.
  initializer : ``InitializerApplicator``, optional (default=``InitializerApplicator()``)
      Used to initialize the model parameters.
  regularizer : ``RegularizerApplicator``, optional (default=``None``)
      If provided, will be used to calculate the regularization penalty during training.
docstr: Parameters
  ----------
  words : Dict[str, torch.LongTensor], required
      The output of ``TextField.as_array()``, which should typically be passed directly to a
      ``TextFieldEmbedder``. This output is a dictionary mapping keys to ``TokenIndexer``
      tensors.  At its most basic, using a ``SingleIdTokenIndexer`` this is: ``{"tokens":
      Tensor(batch_size, sequence_length)}``. This dictionary will have the same keys as were used
      for the ``TokenIndexers`` when you created the ``TextField`` representing your
      sequence.  The dictionary is designed to be passed directly to a ``TextFieldEmbedder``,
      which knows how to combine different word representations into a single vector per
      token in your input.
  pos_tags : ``torch.LongTensor``, required.
      The output of a ``SequenceLabelField`` containing POS tags.
      POS tags are required regardless of whether they are used in the model,
      because they are used to filter the evaluation metric to only consider
      heads of words which are not punctuation.
  head_tags : torch.LongTensor, optional (default = None)
      A torch tensor representing the sequence of integer gold class labels for the arcs
      in the dependency parse. Has shape ``(batch_size, sequence_length)``.
  head_indices : torch.LongTensor, optional (default = None)
      A torch tensor representing the sequence of integer indices denoting the parent of every
      word in the dependency parse. Has shape ``(batch_size, sequence_length)``.
  
  Returns
  -------
  An output dictionary consisting of:
  loss : ``torch.FloatTensor``, optional
      A scalar loss to be optimised.
  arc_loss : ``torch.FloatTensor``
      The loss contribution from the unlabeled arcs.
  loss : ``torch.FloatTensor``, optional
      The loss contribution from predicting the dependency
      tags for the gold arcs.
  heads : ``torch.FloatTensor``
      The predicted head indices for each word. A tensor
      of shape (batch_size, sequence_length).
  head_types : ``torch.FloatTensor``
      The predicted head types for each arc. A tensor
      of shape (batch_size, sequence_length).
  mask : ``torch.LongTensor``
      A mask denoting the padded elements in the batch.
docstr_tok: ["Parameters","--","--","--","--","--","words",":","Dict","[","str",",","torch.LongTensor","]",",","required","The","output","of","``","TextField.as_array","(",")","``",",","which","should","typically","be","passed","directly","to","a","``","TextFieldEmbedder","``",".","This","output","is","a","dictionary","mapping","keys","to","``","TokenIndexer","``","tensors",".","At","its","most","basic",",","using","a","``","SingleIdTokenIndexer","``","this","is",":","``","{","``","tokens","''",":","Tensor","(","batch_size",",","sequence_length",")","}","``",".","This","dictionary","will","have","the","same","keys","as","were","used","for","the","``","TokenIndexers","``","when","you","created","the","``","TextField","``","representing","your","sequence",".","The","dictionary","is","designed","to","be","passed","directly","to","a","``","TextFieldEmbedder","``",",","which","knows","how","to","combine","different","word","representations","into","a","single","vector","per","token","in","your","input",".","pos_tags",":","``","torch.LongTensor","``",",","required",".","The","output","of","a","``","SequenceLabelField","``","containing","POS","tags",".","POS","tags","are","required","regardless","of","whether","they","are","used","in","the","model",",","because","they","are","used","to","filter","the","evaluation","metric","to","only","consider","heads","of","words","which","are","not","punctuation",".","head_tags",":","torch.LongTensor",",","optional","(","default","=","None",")","A","torch","tensor","representing","the","sequence","of","integer","gold","class","labels","for","the","arcs","in","the","dependency","parse",".","Has","shape","``","(","batch_size",",","sequence_length",")","``",".","head_indices",":","torch.LongTensor",",","optional","(","default","=","None",")","A","torch","tensor","representing","the","sequence","of","integer","indices","denoting","the","parent","of","every","word","in","the","dependency","parse",".","Has","shape","``","(","batch_size",",","sequence_length",")","``",".","Returns","--","--","--","-","An","output","dictionary","consisting","of",":","loss",":","``","torch.FloatTensor","``",",","optional","A","scalar","loss","to","be","optimised",".","arc_loss",":","``","torch.FloatTensor","``","The","loss","contribution","from","the","unlabeled","arcs",".","loss",":","``","torch.FloatTensor","``",",","optional","The","loss","contribution","from","predicting","the","dependency","tags","for","the","gold","arcs",".","heads",":","``","torch.FloatTensor","``","The","predicted","head","indices","for","each","word",".","A","tensor","of","shape","(","batch_size",",","sequence_length",")",".","head_types",":","``","torch.FloatTensor","``","The","predicted","head","types","for","each","arc",".","A","tensor","of","shape","(","batch_size",",","sequence_length",")",".","mask",":","``","torch.LongTensor","``","A","mask","denoting","the","padded","elements","in","the","batch","."]
code: def forward(
      self,  # type: ignore
      words,
      pos_tags,
      metadata,
      head_tags=None,
      head_indices=None,
  ):
      # pylint: disable=arguments-differ
      """
      Parameters
      ----------
      words : Dict[str, torch.LongTensor], required
          The output of ``TextField.as_array()``, which should typically be passed directly to a
          ``TextFieldEmbedder``. This output is a dictionary mapping keys to ``TokenIndexer``
          tensors.  At its most basic, using a ``SingleIdTokenIndexer`` this is: ``{"tokens":
          Tensor(batch_size, sequence_length)}``. This dictionary will have the same keys as were used
          for the ``TokenIndexers`` when you created the ``TextField`` representing your
          sequence.  The dictionary is designed to be passed directly to a ``TextFieldEmbedder``,
          which knows how to combine different word representations into a single vector per
          token in your input.
      pos_tags : ``torch.LongTensor``, required.
          The output of a ``SequenceLabelField`` containing POS tags.
          POS tags are required regardless of whether they are used in the model,
          because they are used to filter the evaluation metric to only consider
          heads of words which are not punctuation.
      head_tags : torch.LongTensor, optional (default = None)
          A torch tensor representing the sequence of integer gold class labels for the arcs
          in the dependency parse. Has shape ``(batch_size, sequence_length)``.
      head_indices : torch.LongTensor, optional (default = None)
          A torch tensor representing the sequence of integer indices denoting the parent of every
          word in the dependency parse. Has shape ``(batch_size, sequence_length)``.
  
      Returns
      -------
      An output dictionary consisting of:
      loss : ``torch.FloatTensor``, optional
          A scalar loss to be optimised.
      arc_loss : ``torch.FloatTensor``
          The loss contribution from the unlabeled arcs.
      loss : ``torch.FloatTensor``, optional
          The loss contribution from predicting the dependency
          tags for the gold arcs.
      heads : ``torch.FloatTensor``
          The predicted head indices for each word. A tensor
          of shape (batch_size, sequence_length).
      head_types : ``torch.FloatTensor``
          The predicted head types for each arc. A tensor
          of shape (batch_size, sequence_length).
      mask : ``torch.LongTensor``
          A mask denoting the padded elements in the batch.
      """
      embedded_text_input = self.text_field_embedder(words)
      if pos_tags is not None and self._pos_tag_embedding is not None:
          embedded_pos_tags = self._pos_tag_embedding(pos_tags)
          embedded_text_input = torch.cat(
              [embedded_text_input, embedded_pos_tags], -1
          )
      elif self._pos_tag_embedding is not None:
          raise ConfigurationError(
              "Model uses a POS embedding, but no POS tags were passed."
          )
  
      mask = get_text_field_mask(words)
      embedded_text_input = self._input_dropout(embedded_text_input)
      encoded_text = self.encoder(embedded_text_input, mask)
  
      batch_size, _, encoding_dim = encoded_text.size()
  
      head_sentinel = self._head_sentinel.expand(
          batch_size, 1, encoding_dim
      )
      # Concatenate the head sentinel onto the sentence representation.
      encoded_text = torch.cat([head_sentinel, encoded_text], 1)
      mask = torch.cat([mask.new_ones(batch_size, 1), mask], 1)
      if head_indices is not None:
          head_indices = torch.cat(
              [head_indices.new_zeros(batch_size, 1), head_indices], 1
          )
      if head_tags is not None:
          head_tags = torch.cat(
              [head_tags.new_zeros(batch_size, 1), head_tags], 1
          )
      float_mask = mask.float()
      encoded_text = self._dropout(encoded_text)
  
      # shape (batch_size, sequence_length, arc_representation_dim)
      head_arc_representation = self._dropout(
          self.head_arc_feedforward(encoded_text)
      )
      child_arc_representation = self._dropout(
          self.child_arc_feedforward(encoded_text)
      )
  
      # shape (batch_size, sequence_length, tag_representation_dim)
      head_tag_representation = self._dropout(
          self.head_tag_feedforward(encoded_text)
      )
      child_tag_representation = self._dropout(
          self.child_tag_feedforward(encoded_text)
      )
      # shape (batch_size, sequence_length, sequence_length)
      attended_arcs = self.arc_attention(
          head_arc_representation, child_arc_representation
      )
  
      minus_inf = -1e8
      minus_mask = (1 - float_mask) * minus_inf
      attended_arcs = (
          attended_arcs
          + minus_mask.unsqueeze(2)
          + minus_mask.unsqueeze(1)
      )
  
      if self.training or not self.use_mst_decoding_for_validation:
          predicted_heads, predicted_head_tags = self._greedy_decode(
              head_tag_representation,
              child_tag_representation,
              attended_arcs,
              mask,
          )
      else:
          predicted_heads, predicted_head_tags = self._mst_decode(
              head_tag_representation,
              child_tag_representation,
              attended_arcs,
              mask,
          )
      if head_indices is not None and head_tags is not None:
          arc_nll, tag_nll = self._construct_loss(
              head_tag_representation=head_tag_representation,
              child_tag_representation=child_tag_representation,
              attended_arcs=attended_arcs,
              head_indices=head_indices,
              head_tags=head_tags,
              mask=mask,
          )
          loss = arc_nll + tag_nll
  
          evaluation_mask = self._get_mask_for_eval(
              mask[:, 1:], pos_tags
          )
          # We calculate attatchment scores for the whole sentence
          # but excluding the symbolic ROOT token at the start,
          # which is why we start from the second element in the sequence.
          self._attachment_scores(
              predicted_heads[:, 1:],
              predicted_head_tags[:, 1:],
              head_indices[:, 1:],
              head_tags[:, 1:],
              evaluation_mask,
          )
      else:
          arc_nll, tag_nll = self._construct_loss(
              head_tag_representation=head_tag_representation,
              child_tag_representation=child_tag_representation,
              attended_arcs=attended_arcs,
              head_indices=predicted_heads.long(),
              head_tags=predicted_head_tags.long(),
              mask=mask,
          )
          loss = arc_nll + tag_nll
  
      output_dict = {
          "heads": predicted_heads,
          "head_tags": predicted_head_tags,
          "arc_loss": arc_nll,
          "tag_loss": tag_nll,
          "loss": loss,
          "mask": mask,
          "words": [meta["words"] for meta in metadata],
          "pos": [meta["pos"] for meta in metadata],
      }
  
      return output_dict
  
imports: from __future__ import division
  from __future__ import absolute_import
  import logging
  import copy
  import torch
  import torch.nn.functional
  from torch.nn.modules import Dropout
  import numpy
  from allennlp.common.checks import check_dimensions_match, ConfigurationError
  from allennlp.data import Vocabulary
  from allennlp.modules import Seq2SeqEncoder, TextFieldEmbedder, Embedding, InputVariationalDropout
  from allennlp.modules.matrix_attention.bilinear_matrix_attention import BilinearMatrixAttention
  from allennlp.modules import FeedForward
  from allennlp.models.model import Model
  from allennlp.nn import InitializerApplicator, RegularizerApplicator, Activation
  from allennlp.nn.util import get_text_field_mask, get_range_vector
  from allennlp.nn.util import get_device_of, last_dim_log_softmax, get_lengths_from_binary_sequence_mask
  from allennlp.nn.decoding.chu_liu_edmonds import decode_mst
  from allennlp.training.metrics import AttachmentScores
label_desc: Use image node_id 2 for calling the BiaffineDependencyParser obj's underlying member method code with example usage: obj.forward(words, pos_tags, metadata, head_tags, head_indices) and returns: output_dict