class_docstr: [`BeamScorer`] implementing standard beam search decoding.
  
  Adapted in part from [Facebook's XLM beam search
  code](https://github.com/facebookresearch/XLM/blob/9e6f6814d17be4fe5b15f2e6c43eb2b2d76daeb4/src/model/transformer.py#L529).
  
  Reference for the diverse beam search algorithm and implementation [Ashwin Kalyan's DBS
  implementation](https://github.com/ashwinkalyan/dbs/blob/master/dbs/beam_utils.lua)
  
  Args:
      batch_size (`int`):
          Batch Size of `input_ids` for which standard beam search decoding is run in parallel.
      num_beams (`int`):
          Number of beams for beam search.
      device (`torch.device`):
          Defines the device type (*e.g.*, `"cpu"` or `"cuda"`) on which this instance of `BeamSearchScorer` will be
          allocated.
      length_penalty (`float`, *optional*, defaults to 1.0):
          Exponential penalty to the length that is used with beam-based generation. It is applied as an exponent to
          the sequence length, which in turn is used to divide the score of the sequence. Since the score is the log
          likelihood of the sequence (i.e. negative), `length_penalty` > 0.0 promotes longer sequences, while
          `length_penalty` < 0.0 encourages shorter sequences.
      do_early_stopping (`bool` or `str`, *optional*, defaults to `False`):
          Controls the stopping condition for beam-based methods, like beam-search. It accepts the following values:
          `True`, where the generation stops as soon as there are `num_beams` complete candidates; `False`, where an
          heuristic is applied and the generation stops when is it very unlikely to find better candidates;
          `"never"`, where the beam search procedure only stops when there cannot be better candidates (canonical
          beam search algorithm).
      num_beam_hyps_to_keep (`int`, *optional*, defaults to 1):
          The number of beam hypotheses that shall be returned upon calling
          [`~transformers.BeamSearchScorer.finalize`].
      num_beam_groups (`int`, *optional*, defaults to 1):
          Number of groups to divide `num_beams` into in order to ensure diversity among different groups of beams.
          See [this paper](https://arxiv.org/pdf/1610.02424.pdf) for more details.
      max_length (`int`, *optional*):
          The maximum length of the sequence to be generated.
class_docstr_tok: ["[","`","BeamScorer","`","]","implementing","standard","beam","search","decoding",".","Adapted","in","part","from","[","Facebook","'s","XLM","beam","search","code","]","(","https",":","\/\/github.com\/facebookresearch\/XLM\/blob\/9e6f6814d17be4fe5b15f2e6c43eb2b2d76daeb4\/src\/model\/transformer.py","#","L529",")",".","Reference","for","the","diverse","beam","search","algorithm","and","implementation","[","Ashwin","Kalyan","'s","DBS","implementation","]","(","https",":","\/\/github.com\/ashwinkalyan\/dbs\/blob\/master\/dbs\/beam_utils.lua",")","Args",":","batch_size","(","`","int","`",")",":","Batch","Size","of","`","input_ids","`","for","which","standard","beam","search","decoding","is","run","in","parallel",".","num_beams","(","`","int","`",")",":","Number","of","beams","for","beam","search",".","device","(","`","torch.device","`",")",":","Defines","the","device","type","(","*","e.g",".","*",",","`","``","cpu","''","`","or","`","``","cuda","''","`",")","on","which","this","instance","of","`","BeamSearchScorer","`","will","be","allocated",".","length_penalty","(","`","float","`",",","*","optional","*",",","defaults","to","1.0",")",":","Exponential","penalty","to","the","length","that","is","used","with","beam-based","generation",".","It","is","applied","as","an","exponent","to","the","sequence","length",",","which","in","turn","is","used","to","divide","the","score","of","the","sequence",".","Since","the","score","is","the","log","likelihood","of","the","sequence","(","i.e",".","negative",")",",","`","length_penalty","`",">","0.0","promotes","longer","sequences",",","while","`","length_penalty","`","<","0.0","encourages","shorter","sequences",".","do_early_stopping","(","`","bool","`","or","`","str","`",",","*","optional","*",",","defaults","to","`","False","`",")",":","Controls","the","stopping","condition","for","beam-based","methods",",","like","beam-search",".","It","accepts","the","following","values",":","`","True","`",",","where","the","generation","stops","as","soon","as","there","are","`","num_beams","`","complete","candidates",";","`","False","`",",","where","an","heuristic","is","applied","and","the","generation","stops","when","is","it","very","unlikely","to","find","better","candidates",";","`","``","never","''","`",",","where","the","beam","search","procedure","only","stops","when","there","can","not","be","better","candidates","(","canonical","beam","search","algorithm",")",".","num_beam_hyps_to_keep","(","`","int","`",",","*","optional","*",",","defaults","to","1",")",":","The","number","of","beam","hypotheses","that","shall","be","returned","upon","calling","[","`","~transformers.BeamSearchScorer.finalize","`","]",".","num_beam_groups","(","`","int","`",",","*","optional","*",",","defaults","to","1",")",":","Number","of","groups","to","divide","`","num_beams","`","into","in","order","to","ensure","diversity","among","different","groups","of","beams",".","See","[","this","paper","]","(","https",":","\/\/arxiv.org\/pdf\/1610.02424.pdf",")","for","more","details",".","max_length","(","`","int","`",",","*","optional","*",")",":","The","maximum","length","of","the","sequence","to","be","generated","."]
code: def finalize(
      self,
      input_ids: torch.LongTensor,
      final_beam_scores: torch.FloatTensor,
      final_beam_tokens: torch.LongTensor,
      final_beam_indices: torch.LongTensor,
      max_length: int,
      pad_token_id: Optional[int] = None,
      eos_token_id: Optional[Union[int, List[int]]] = None,
      beam_indices: Optional[torch.LongTensor] = None,
      decoder_prompt_len: Optional[int] = 0,
  ) -> Tuple[torch.LongTensor]:
      batch_size = len(self._beam_hyps) // self.num_beam_groups
  
      if isinstance(eos_token_id, int):
          eos_token_id = [eos_token_id]
  
      # finalize all open beam hypotheses and add to generated hypotheses
      for batch_group_idx, beam_hyp in enumerate(self._beam_hyps):
          if self._done[batch_group_idx]:
              continue
  
          # all open beam hypotheses are added to the beam hypothesis
          # beam hypothesis class automatically keeps the best beams
          for index_per_group in range(self.group_size):
              batch_beam_idx = (
                  batch_group_idx * self.group_size + index_per_group
              )
              final_score = final_beam_scores[batch_beam_idx].item()
              final_tokens = input_ids[batch_beam_idx]
              beam_index = (
                  beam_indices[batch_beam_idx]
                  if beam_indices is not None
                  else None
              )
              generated_len = (
                  final_tokens.shape[-1] - decoder_prompt_len
              )
              beam_hyp.add(
                  final_tokens,
                  final_score,
                  beam_indices=beam_index,
                  generated_len=generated_len,
              )
  
      # select the best hypotheses
      sent_lengths = input_ids.new(
          batch_size * self.num_beam_hyps_to_keep
      )
      best = []
      best_indices = []
      best_scores = torch.zeros(
          batch_size * self.num_beam_hyps_to_keep,
          device=self.device,
          dtype=torch.float32,
      )
  
      # retrieve best hypotheses
      for i in range(batch_size):
          beam_hyps_in_batch = self._beam_hyps[
              i * self.num_beam_groups : (i + 1) * self.num_beam_groups
          ]
          candidate_beams = [
              beam
              for beam_hyp in beam_hyps_in_batch
              for beam in beam_hyp.beams
          ]
          sorted_hyps = sorted(candidate_beams, key=lambda x: x[0])
          for j in range(self.num_beam_hyps_to_keep):
              best_hyp_tuple = sorted_hyps.pop()
              best_score = best_hyp_tuple[0]
              best_hyp = best_hyp_tuple[1]
              best_index = best_hyp_tuple[2]
              sent_lengths[self.num_beam_hyps_to_keep * i + j] = len(
                  best_hyp
              )
  
              # append hyp to lists
              best.append(best_hyp)
  
              # append indices to list
              best_indices.append(best_index)
  
              best_scores[
                  i * self.num_beam_hyps_to_keep + j
              ] = best_score
  
      # prepare for adding eos
      sent_lengths_max = sent_lengths.max().item() + 1
      sent_max_len = (
          min(sent_lengths_max, max_length)
          if max_length is not None
          else sent_lengths_max
      )
      decoded: torch.LongTensor = input_ids.new(
          batch_size * self.num_beam_hyps_to_keep, sent_max_len
      )
  
      if len(best_indices) > 0 and best_indices[0] is not None:
          indices: torch.LongTensor = input_ids.new(
              batch_size * self.num_beam_hyps_to_keep, sent_max_len
          )
      else:
          indices = None
  
      # shorter batches are padded if needed
      if sent_lengths.min().item() != sent_lengths.max().item():
          if pad_token_id is None:
              raise ValueError("`pad_token_id` has to be defined")
          decoded.fill_(pad_token_id)
  
      if indices is not None:
          indices.fill_(-1)
  
      # fill with hypotheses and eos_token_id if the latter fits in
      for i, (hypo, best_idx) in enumerate(zip(best, best_indices)):
          decoded[i, : sent_lengths[i]] = hypo
  
          if indices is not None:
              indices[i, : len(best_idx)] = torch.tensor(best_idx)
  
          if sent_lengths[i] < sent_max_len:
              # inserting only the first eos_token_id
              decoded[i, sent_lengths[i]] = eos_token_id[0]
  
      return UserDict(
          {
              "sequences": decoded,
              "sequence_scores": best_scores,
              "beam_indices": indices,
          }
      )
  
imports: from abc import ABC, abstractmethod
  from collections import UserDict
  from typing import Dict, List, Optional, Tuple, Union
  import numpy
  import torch
  from ..utils import add_start_docstrings
  from .beam_constraints import Constraint, ConstraintListState
label_desc: Use image node_id 4 for calling the BeamSearchScorer obj's underlying member method code with example usage: obj.finalize(input_ids, final_beam_scores, final_beam_tokens, final_beam_indices, max_length, pad_token_id, eos_token_id, beam_indices, decoder_prompt_len) and returns: UserDict