class_docstr: This ``Model`` implements the coreference resolution model described "End-to-end Neural
  Coreference Resolution"
  <https://www.semanticscholar.org/paper/End-to-end-Neural-Coreference-Resolution-Lee-He/3f2114893dc44eacac951f148fbff142ca200e83>
  by Lee et al., 2017.
  The basic outline of this model is to get an embedded representation of each span in the
  document. These span representations are scored and used to prune away spans that are unlikely
  to occur in a coreference cluster. For the remaining spans, the model decides which antecedent
  span (if any) they are coreferent with. The resulting coreference links, after applying
  transitivity, imply a clustering of the spans in the document.
  
  Parameters
  ----------
  vocab : ``Vocabulary``
  text_field_embedder : ``TextFieldEmbedder``
      Used to embed the ``text`` ``TextField`` we get as input to the model.
  context_layer : ``Seq2SeqEncoder``
      This layer incorporates contextual information for each word in the document.
  mention_feedforward : ``FeedForward``
      This feedforward network is applied to the span representations which is then scored
      by a linear layer.
  antecedent_feedforward: ``FeedForward``
      This feedforward network is applied to pairs of span representation, along with any
      pairwise features, which is then scored by a linear layer.
  feature_size: ``int``
      The embedding size for all the embedded features, such as distances or span widths.
  max_span_width: ``int``
      The maximum width of candidate spans.
  spans_per_word: float, required.
      A multiplier between zero and one which controls what percentage of candidate mention
      spans we retain with respect to the number of words in the document.
  max_antecedents: int, required.
      For each mention which survives the pruning stage, we consider this many antecedents.
  lexical_dropout: ``int``
      The probability of dropping out dimensions of the embedded text.
  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: This method generates possible antecedents per span which survived the pruning
  stage. This procedure is `generic across the batch`. The reason this is the case is
  that each span in a batch can be coreferent with any previous span, but here we
  are computing the possible `indices` of these spans. So, regardless of the batch,
  the 1st span _cannot_ have any antecedents, because there are none to select from.
  Similarly, each element can only predict previous spans, so this returns a matrix
  of shape (num_spans_to_keep, max_antecedents), where the (i,j)-th index is equal to
  (i - 1) - j if j <= i, or zero otherwise.
  
  Parameters
  ----------
  num_spans_to_keep : ``int``, required.
      The number of spans that were kept while pruning.
  max_antecedents : ``int``, required.
      The maximum number of antecedent spans to consider for every span.
  device: ``int``, required.
      The CUDA device to use.
  
  Returns
  -------
  valid_antecedent_indices : ``torch.IntTensor``
      The indices of every antecedent to consider with respect to the top k spans.
      Has shape ``(num_spans_to_keep, max_antecedents)``.
  valid_antecedent_offsets : ``torch.IntTensor``
      The distance between the span and each of its antecedents in terms of the number
      of considered spans (i.e not the word distance between the spans).
      Has shape ``(1, max_antecedents)``.
  valid_antecedent_log_mask : ``torch.FloatTensor``
      The logged mask representing whether each antecedent span is valid. Required since
      different spans have different numbers of valid antecedents. For example, the first
      span in the document should have no valid antecedents.
      Has shape ``(1, num_spans_to_keep, max_antecedents)``.
docstr_tok: ["This","method","generates","possible","antecedents","per","span","which","survived","the","pruning","stage",".","This","procedure","is","`","generic","across","the","batch","`",".","The","reason","this","is","the","case","is","that","each","span","in","a","batch","can","be","coreferent","with","any","previous","span",",","but","here","we","are","computing","the","possible","`","indices","`","of","these","spans",".","So",",","regardless","of","the","batch",",","the","1st","span","_cannot_","have","any","antecedents",",","because","there","are","none","to","select","from",".","Similarly",",","each","element","can","only","predict","previous","spans",",","so","this","returns","a","matrix","of","shape","(","num_spans_to_keep",",","max_antecedents",")",",","where","the","(","i",",","j",")","-th","index","is","equal","to","(","i","-","1",")","-","j","if","j","<","=","i",",","or","zero","otherwise",".","Parameters","--","--","--","--","--","num_spans_to_keep",":","``","int","``",",","required",".","The","number","of","spans","that","were","kept","while","pruning",".","max_antecedents",":","``","int","``",",","required",".","The","maximum","number","of","antecedent","spans","to","consider","for","every","span",".","device",":","``","int","``",",","required",".","The","CUDA","device","to","use",".","Returns","--","--","--","-","valid_antecedent_indices",":","``","torch.IntTensor","``","The","indices","of","every","antecedent","to","consider","with","respect","to","the","top","k","spans",".","Has","shape","``","(","num_spans_to_keep",",","max_antecedents",")","``",".","valid_antecedent_offsets",":","``","torch.IntTensor","``","The","distance","between","the","span","and","each","of","its","antecedents","in","terms","of","the","number","of","considered","spans","(","i.e","not","the","word","distance","between","the","spans",")",".","Has","shape","``","(","1",",","max_antecedents",")","``",".","valid_antecedent_log_mask",":","``","torch.FloatTensor","``","The","logged","mask","representing","whether","each","antecedent","span","is","valid",".","Required","since","different","spans","have","different","numbers","of","valid","antecedents",".","For","example",",","the","first","span","in","the","document","should","have","no","valid","antecedents",".","Has","shape","``","(","1",",","num_spans_to_keep",",","max_antecedents",")","``","."]
code: def _generate_valid_antecedents(
      num_spans_to_keep, max_antecedents, device
  ):
      """
      This method generates possible antecedents per span which survived the pruning
      stage. This procedure is `generic across the batch`. The reason this is the case is
      that each span in a batch can be coreferent with any previous span, but here we
      are computing the possible `indices` of these spans. So, regardless of the batch,
      the 1st span _cannot_ have any antecedents, because there are none to select from.
      Similarly, each element can only predict previous spans, so this returns a matrix
      of shape (num_spans_to_keep, max_antecedents), where the (i,j)-th index is equal to
      (i - 1) - j if j <= i, or zero otherwise.
  
      Parameters
      ----------
      num_spans_to_keep : ``int``, required.
          The number of spans that were kept while pruning.
      max_antecedents : ``int``, required.
          The maximum number of antecedent spans to consider for every span.
      device: ``int``, required.
          The CUDA device to use.
  
      Returns
      -------
      valid_antecedent_indices : ``torch.IntTensor``
          The indices of every antecedent to consider with respect to the top k spans.
          Has shape ``(num_spans_to_keep, max_antecedents)``.
      valid_antecedent_offsets : ``torch.IntTensor``
          The distance between the span and each of its antecedents in terms of the number
          of considered spans (i.e not the word distance between the spans).
          Has shape ``(1, max_antecedents)``.
      valid_antecedent_log_mask : ``torch.FloatTensor``
          The logged mask representing whether each antecedent span is valid. Required since
          different spans have different numbers of valid antecedents. For example, the first
          span in the document should have no valid antecedents.
          Has shape ``(1, num_spans_to_keep, max_antecedents)``.
      """
      # Shape: (num_spans_to_keep, 1)
      target_indices = util.get_range_vector(
          num_spans_to_keep, device
      ).unsqueeze(1)
  
      # Shape: (1, max_antecedents)
      valid_antecedent_offsets = (
          util.get_range_vector(max_antecedents, device) + 1
      ).unsqueeze(0)
  
      # This is a broadcasted subtraction.
      # Shape: (num_spans_to_keep, max_antecedents)
      raw_antecedent_indices = target_indices - valid_antecedent_offsets
  
      # In our matrix of indices, the upper triangular part will be negative
      # because the offsets will be > the target indices. We want to mask these,
      # because these are exactly the indices which we don't want to predict, per span.
      # We're generating a logspace mask here because we will eventually create a
      # distribution over these indices, so we need the 0 elements of the mask to be -inf
      # in order to not mess up the normalisation of the distribution.
      # Shape: (1, num_spans_to_keep, max_antecedents)
      valid_antecedent_log_mask = (
          (raw_antecedent_indices >= 0).float().unsqueeze(0).log()
      )
  
      # Shape: (num_spans_to_keep, max_antecedents)
      valid_antecedent_indices = F.relu(
          raw_antecedent_indices.float()
      ).long()
      return (
          valid_antecedent_indices,
          valid_antecedent_offsets,
          valid_antecedent_log_mask,
      )
  
imports: from __future__ import absolute_import
  import logging
  import math
  import torch
  import torch.nn.functional
  from allennlp.data import Vocabulary
  from allennlp.models.model import Model
  from allennlp.modules.token_embedders import Embedding
  from allennlp.modules import FeedForward
  from allennlp.modules import Seq2SeqEncoder, TimeDistributed, TextFieldEmbedder, SpanPruner
  from allennlp.modules.span_extractors import SelfAttentiveSpanExtractor, EndpointSpanExtractor
  from allennlp.nn import util, InitializerApplicator, RegularizerApplicator
  from allennlp.training.metrics import MentionRecall, ConllCorefScores
label_desc: Use image node_id 5 for calling the CoreferenceResolver obj's underlying member method code with example usage: obj._generate_valid_antecedents(num_spans_to_keep, max_antecedents, device) and returns: valid_antecedent_indices,  valid_antecedent_offsets,  valid_antecedent_log_mask