class_docstr: `SpanExtractorWithSpanWidthEmbedding` implements some common code for span
  extractors which will need to embed span width.
  
  Specifically, we initiate the span width embedding matrix and other
  attributes in `__init__`, leave an `_embed_spans` method that can be
  implemented to compute span embeddings in different ways, and in `forward`
  we concatenate span embeddings returned by `_embed_spans` with span width
  embeddings to form the final span representations.
  
  We keep SpanExtractor as a purely abstract base class, just in case someone
  wants to build a totally different span extractor.
  
  # Parameters
  
  input_dim : `int`, required.
      The final dimension of the `sequence_tensor`.
  num_width_embeddings : `int`, optional (default = `None`).
      Specifies the number of buckets to use when representing
      span width features.
  span_width_embedding_dim : `int`, optional (default = `None`).
      The embedding size for the span_width features.
  bucket_widths : `bool`, optional (default = `False`).
      Whether to bucket the span widths into log-space buckets. If `False`,
      the raw span widths are used.
  
  # Returns
  
  span_embeddings : `torch.FloatTensor`.
      A tensor of shape `(batch_size, num_spans, embedded_span_size)`,
      where `embedded_span_size` depends on the way spans are represented.
class_docstr_tok: ["`","SpanExtractorWithSpanWidthEmbedding","`","implements","some","common","code","for","span","extractors","which","will","need","to","embed","span","width",".","Specifically",",","we","initiate","the","span","width","embedding","matrix","and","other","attributes","in","`","__init__","`",",","leave","an","`","_embed_spans","`","method","that","can","be","implemented","to","compute","span","embeddings","in","different","ways",",","and","in","`","forward","`","we","concatenate","span","embeddings","returned","by","`","_embed_spans","`","with","span","width","embeddings","to","form","the","final","span","representations",".","We","keep","SpanExtractor","as","a","purely","abstract","base","class",",","just","in","case","someone","wants","to","build","a","totally","different","span","extractor",".","#","Parameters","input_dim",":","`","int","`",",","required",".","The","final","dimension","of","the","`","sequence_tensor","`",".","num_width_embeddings",":","`","int","`",",","optional","(","default","=","`","None","`",")",".","Specifies","the","number","of","buckets","to","use","when","representing","span","width","features",".","span_width_embedding_dim",":","`","int","`",",","optional","(","default","=","`","None","`",")",".","The","embedding","size","for","the","span_width","features",".","bucket_widths",":","`","bool","`",",","optional","(","default","=","`","False","`",")",".","Whether","to","bucket","the","span","widths","into","log-space","buckets",".","If","`","False","`",",","the","raw","span","widths","are","used",".","#","Returns","span_embeddings",":","`","torch.FloatTensor","`",".","A","tensor","of","shape","`","(","batch_size",",","num_spans",",","embedded_span_size",")","`",",","where","`","embedded_span_size","`","depends","on","the","way","spans","are","represented","."]
docstr: Given a sequence tensor, extract spans, concatenate width embeddings
  when need and return representations of them.
  
  # Parameters
  
  sequence_tensor : `torch.FloatTensor`, required.
      A tensor of shape (batch_size, sequence_length, embedding_size)
      representing an embedded sequence of words.
  span_indices : `torch.LongTensor`, required.
      A tensor of shape `(batch_size, num_spans, 2)`, where the last
      dimension represents the inclusive start and end indices of the
      span to be extracted from the `sequence_tensor`.
  sequence_mask : `torch.BoolTensor`, optional (default = `None`).
      A tensor of shape (batch_size, sequence_length) representing padded
      elements of the sequence.
  span_indices_mask : `torch.BoolTensor`, optional (default = `None`).
      A tensor of shape (batch_size, num_spans) representing the valid
      spans in the `indices` tensor. This mask is optional because
      sometimes it's easier to worry about masking after calling this
      function, rather than passing a mask directly.
  
  # Returns
  
  A tensor of shape `(batch_size, num_spans, embedded_span_size)`,
  where `embedded_span_size` depends on the way spans are represented.
docstr_tok: ["Given","a","sequence","tensor",",","extract","spans",",","concatenate","width","embeddings","when","need","and","return","representations","of","them",".","#","Parameters","sequence_tensor",":","`","torch.FloatTensor","`",",","required",".","A","tensor","of","shape","(","batch_size",",","sequence_length",",","embedding_size",")","representing","an","embedded","sequence","of","words",".","span_indices",":","`","torch.LongTensor","`",",","required",".","A","tensor","of","shape","`","(","batch_size",",","num_spans",",","2",")","`",",","where","the","last","dimension","represents","the","inclusive","start","and","end","indices","of","the","span","to","be","extracted","from","the","`","sequence_tensor","`",".","sequence_mask",":","`","torch.BoolTensor","`",",","optional","(","default","=","`","None","`",")",".","A","tensor","of","shape","(","batch_size",",","sequence_length",")","representing","padded","elements","of","the","sequence",".","span_indices_mask",":","`","torch.BoolTensor","`",",","optional","(","default","=","`","None","`",")",".","A","tensor","of","shape","(","batch_size",",","num_spans",")","representing","the","valid","spans","in","the","`","indices","`","tensor",".","This","mask","is","optional","because","sometimes","it","'s","easier","to","worry","about","masking","after","calling","this","function",",","rather","than","passing","a","mask","directly",".","#","Returns","A","tensor","of","shape","`","(","batch_size",",","num_spans",",","embedded_span_size",")","`",",","where","`","embedded_span_size","`","depends","on","the","way","spans","are","represented","."]
code: def forward(
      self,
      sequence_tensor: torch.FloatTensor,
      span_indices: torch.LongTensor,
      sequence_mask: torch.BoolTensor = None,
      span_indices_mask: torch.BoolTensor = None,
  ):
      """
      Given a sequence tensor, extract spans, concatenate width embeddings
      when need and return representations of them.
  
      # Parameters
  
      sequence_tensor : `torch.FloatTensor`, required.
          A tensor of shape (batch_size, sequence_length, embedding_size)
          representing an embedded sequence of words.
      span_indices : `torch.LongTensor`, required.
          A tensor of shape `(batch_size, num_spans, 2)`, where the last
          dimension represents the inclusive start and end indices of the
          span to be extracted from the `sequence_tensor`.
      sequence_mask : `torch.BoolTensor`, optional (default = `None`).
          A tensor of shape (batch_size, sequence_length) representing padded
          elements of the sequence.
      span_indices_mask : `torch.BoolTensor`, optional (default = `None`).
          A tensor of shape (batch_size, num_spans) representing the valid
          spans in the `indices` tensor. This mask is optional because
          sometimes it's easier to worry about masking after calling this
          function, rather than passing a mask directly.
  
      # Returns
  
      A tensor of shape `(batch_size, num_spans, embedded_span_size)`,
      where `embedded_span_size` depends on the way spans are represented.
      """
      # shape (batch_size, num_spans, embedding_dim)
      span_embeddings = self._embed_spans(
          sequence_tensor,
          span_indices,
          sequence_mask,
          span_indices_mask,
      )
      if self._span_width_embedding is not None:
          # width = end_index - start_index + 1 since `SpanField` use inclusive indices.
          # But here we do not add 1 beacuse we often initiate the span width
          # embedding matrix with `num_width_embeddings = max_span_width`
          # shape (batch_size, num_spans)
          widths_minus_one = span_indices[..., 1] - span_indices[..., 0]
  
          if self._bucket_widths:
              widths_minus_one = util.bucket_values(
                  widths_minus_one, num_total_buckets=self._num_width_embeddings  # type: ignore
              )
  
          # Embed the span widths and concatenate to the rest of the representations.
          span_width_embeddings = self._span_width_embedding(
              widths_minus_one
          )
          span_embeddings = torch.cat(
              [span_embeddings, span_width_embeddings], -1
          )
  
      if span_indices_mask is not None:
          # Here we are masking the spans which were originally passed in as padding.
          return span_embeddings * span_indices_mask.unsqueeze(-1)
  
      return span_embeddings
  
file_path: allennlp/allennlp/modules/span_extractors/span_extractor_with_span_width_embedding.py
imports: from typing import Optional
  import torch
  from allennlp.common.checks import ConfigurationError
  from allennlp.modules.span_extractors.span_extractor import SpanExtractor
  from allennlp.modules.token_embedders.embedding import Embedding
  from allennlp.nn import util
label_desc: Use image node_id 2 for calling the SpanExtractorWithSpanWidthEmbedding obj's underlying member method code with example usage: obj.forward(sequence_tensor, span_indices, sequence_mask, span_indices_mask) and returns: span_embeddings, unknown