class_docstr: Generation beam search.
  
  Note that the attributes list is not exhaustive. Rather, it highlights
  tensors to document their shape. (Since the state variables' "batch"
  size decreases as beams finish, we denote this axis with a B rather than
  ``batch_size``).
  
  Args:
      beam_size (int): Number of beams to use (see base ``parallel_paths``).
      batch_size (int): See base.
      pad (int): See base.
      bos (int): See base.
      eos (int): See base.
      unk (int): See base.
      start (int): See base.
      n_best (int): Don't stop until at least this many beams have
          reached EOS.
      global_scorer (onmt.translate.GNMTGlobalScorer): Scorer instance.
      min_length (int): See base.
      max_length (int): See base.
      return_attention (bool): See base.
      block_ngram_repeat (int): See base.
      exclusion_tokens (set[int]): See base.
  
  Attributes:
      _batch_offset (LongTensor): Shape ``(B,)``.
      _beam_offset (LongTensor): Shape ``(batch_size x beam_size,)``.
      alive_seq (LongTensor): See base.
      topk_log_probs (FloatTensor): Shape ``(B, beam_size,)``. These
          are the scores used for the topk operation.
      src_len (LongTensor): Lengths of encodings. Used for
          masking attentions.
      select_indices (LongTensor or NoneType): Shape
          ``(B x beam_size,)``. This is just a flat view of the
          ``_batch_index``.
      topk_scores (FloatTensor): Shape
          ``(B, beam_size)``. These are the
          scores a sequence will receive if it finishes.
      topk_ids (LongTensor): Shape ``(B, beam_size)``. These are the
          word indices of the topk predictions.
      _batch_index (LongTensor): Shape ``(B, beam_size)``.
      _prev_penalty (FloatTensor or NoneType): Shape
          ``(B, beam_size)``. Initialized to ``None``.
      _coverage (FloatTensor or NoneType): Shape
          ``(1, B x beam_size, inp_seq_len)``.
      hypotheses (list[list[Tuple[Tensor]]]): Contains a tuple
          of score (float), sequence (long), and attention (float or None).
class_docstr_tok: ["Generation","beam","search",".","Note","that","the","attributes","list","is","not","exhaustive",".","Rather",",","it","highlights","tensors","to","document","their","shape",".","(","Since","the","state","variables","'","``","batch","''","size","decreases","as","beams","finish",",","we","denote","this","axis","with","a","B","rather","than","``","batch_size","``",")",".","Args",":","beam_size","(","int",")",":","Number","of","beams","to","use","(","see","base","``","parallel_paths","``",")",".","batch_size","(","int",")",":","See","base",".","pad","(","int",")",":","See","base",".","bos","(","int",")",":","See","base",".","eos","(","int",")",":","See","base",".","unk","(","int",")",":","See","base",".","start","(","int",")",":","See","base",".","n_best","(","int",")",":","Do","n't","stop","until","at","least","this","many","beams","have","reached","EOS",".","global_scorer","(","onmt.translate.GNMTGlobalScorer",")",":","Scorer","instance",".","min_length","(","int",")",":","See","base",".","max_length","(","int",")",":","See","base",".","return_attention","(","bool",")",":","See","base",".","block_ngram_repeat","(","int",")",":","See","base",".","exclusion_tokens","(","set","[","int","]",")",":","See","base",".","Attributes",":","_batch_offset","(","LongTensor",")",":","Shape","``","(","B",",",")","``",".","_beam_offset","(","LongTensor",")",":","Shape","``","(","batch_size","x","beam_size",",",")","``",".","alive_seq","(","LongTensor",")",":","See","base",".","topk_log_probs","(","FloatTensor",")",":","Shape","``","(","B",",","beam_size",",",")","``",".","These","are","the","scores","used","for","the","topk","operation",".","src_len","(","LongTensor",")",":","Lengths","of","encodings",".","Used","for","masking","attentions",".","select_indices","(","LongTensor","or","NoneType",")",":","Shape","``","(","B","x","beam_size",",",")","``",".","This","is","just","a","flat","view","of","the","``","_batch_index","``",".","topk_scores","(","FloatTensor",")",":","Shape","``","(","B",",","beam_size",")","``",".","These","are","the","scores","a","sequence","will","receive","if","it","finishes",".","topk_ids","(","LongTensor",")",":","Shape","``","(","B",",","beam_size",")","``",".","These","are","the","word","indices","of","the","topk","predictions",".","_batch_index","(","LongTensor",")",":","Shape","``","(","B",",","beam_size",")","``",".","_prev_penalty","(","FloatTensor","or","NoneType",")",":","Shape","``","(","B",",","beam_size",")","``",".","Initialized","to","``","None","``",".","_coverage","(","FloatTensor","or","NoneType",")",":","Shape","``","(","1",",","B","x","beam_size",",","inp_seq_len",")","``",".","hypotheses","(","list","[","list","[","Tuple","[","Tensor","]","]","]",")",":","Contains","a","tuple","of","score","(","float",")",",","sequence","(","long",")",",","and","attention","(","float","or","None",")","."]
code: def advance(self, log_probs, attn):
      vocab_size = log_probs.size(-1)
  
      # using integer division to get an integer _B without casting
      _B = log_probs.shape[0] // self.beam_size
  
      if self._stepwise_cov_pen and self._prev_penalty is not None:
          self.topk_log_probs += self._prev_penalty
          self.topk_log_probs -= self.global_scorer.cov_penalty(
              self._coverage + attn, self.global_scorer.beta
          ).view(_B, self.beam_size)
  
      # force the output to be longer than self.min_length
      step = len(self)
      self.ensure_min_length(log_probs)
      self.ensure_unk_removed(log_probs)
      # Multiply probs by the beam probability.
      log_probs += self.topk_log_probs.view(_B * self.beam_size, 1)
  
      # if the sequence ends now, then the penalty is the current
      # length + 1, to include the EOS token
      length_penalty = self.global_scorer.length_penalty(
          step + 1, alpha=self.global_scorer.alpha
      )
      if length_penalty != 1:
          curr_scores = log_probs / length_penalty
      else:
          curr_scores = log_probs
  
      # Avoid any direction that would repeat unwanted ngrams
      self.block_ngram_repeats(curr_scores)
  
      # Pick up candidate token by curr_scores
      self.topk_scores, self.topk_ids = self._pick(curr_scores)
  
      # Recover log probs.
      # Length penalty is just a scalar. It doesn't matter if it's applied
      # before or after the topk.
      self.topk_log_probs = self.topk_scores * length_penalty
  
      # Resolve beam origin and map to batch index flat representation.
      self._batch_index = (
          self.topk_ids // vocab_size
          + self._beam_offset[:_B].unsqueeze(1)
      )
      self.select_indices = self._batch_index.view(_B * self.beam_size)
      self.topk_ids %= vocab_size
  
      # Append last prediction to reordered alive sequence
      self.alive_seq = torch.cat(
          [
              self.alive_seq[self.select_indices],
              self.topk_ids.view(_B * self.beam_size, 1),
          ],
          -1,
      )
  
      self.maybe_update_forbidden_tokens()
  
      if self.return_attention or self._cov_pen:
          current_attn = attn[self.select_indices]
          if step == 1:
              self.alive_attn = current_attn
              # update global state (step == 1)
              if self._cov_pen:  # coverage penalty
                  self._prev_penalty = torch.zeros_like(
                      self.topk_log_probs
                  )
                  self._coverage = current_attn
          else:
              self.alive_attn = self.alive_attn[self.select_indices]
              self.alive_attn = torch.cat(
                  [self.alive_attn, current_attn], 1
              )
              # update global state (step > 1)
              if self._cov_pen:
                  self._coverage = self._coverage[self.select_indices]
                  self._coverage += current_attn
                  self._prev_penalty = self.global_scorer.cov_penalty(
                      self._coverage, beta=self.global_scorer.beta
                  ).view(_B, self.beam_size)
  
      if self._vanilla_cov_pen:
          # shape: (batch_size x beam_size, 1)
          cov_penalty = self.global_scorer.cov_penalty(
              self._coverage, beta=self.global_scorer.beta
          )
          self.topk_scores -= cov_penalty.view(
              _B, self.beam_size
          ).float()
  
      self.is_finished_list = self.topk_ids.eq(self.eos).tolist()
  
      self.ensure_max_length()
  
imports: import torch
  from onmt.translate import penalties
  from onmt.translate.decode_strategy import DecodeStrategy
  import warnings
label_desc: Use image node_id 11 for calling the BeamSearchBase obj's underlying member method code with example usage: obj.advance(log_probs, attn) without return types