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 __init__(
      self,
      batch_size: int,
      num_beams: int,
      device: torch.device,
      length_penalty: Optional[float] = 1.0,
      do_early_stopping: Optional[Union[bool, str]] = False,
      num_beam_hyps_to_keep: Optional[int] = 1,
      num_beam_groups: Optional[int] = 1,
      max_length: Optional[int] = None,
  ):
      self.num_beams = num_beams
      self.device = device
      self.length_penalty = length_penalty
      self.do_early_stopping = do_early_stopping
      self.num_beam_hyps_to_keep = num_beam_hyps_to_keep
      self.num_beam_groups = num_beam_groups
      self.group_size = self.num_beams // self.num_beam_groups
  
      self._is_init = False
      # self._beam_hyps[i*self.num_beam_groups+j] is the beam_hyps of the j-th group in the i-th mini-batch.
      # If group_beam_search is not used, the list consists of `batch_size` beam_hyps.
      self._beam_hyps = [
          BeamHypotheses(
              num_beams=self.group_size,
              length_penalty=self.length_penalty,
              early_stopping=self.do_early_stopping,
              max_length=max_length,
          )
          for _ in range(batch_size * self.num_beam_groups)
      ]
      # self._done[i*self.num_beam_groups+j] indicates whether the generation of the beam_hyps of the j-th group
      # in the i-th mini-batch is complete.
      self._done = torch.tensor(
          [False for _ in range(batch_size * self.num_beam_groups)],
          dtype=torch.bool,
          device=self.device,
      )
  
      if not isinstance(num_beams, int) or num_beams <= 1:
          raise ValueError(
              f"`num_beams` has to be an integer strictly greater than 1, but is {num_beams}. For `num_beams` == 1,"
              " one should make use of `greedy_search` instead."
          )
  
      if (
          not isinstance(num_beam_groups, int)
          or (num_beam_groups > num_beams)
          or (num_beams % num_beam_groups != 0)
      ):
          raise ValueError(
              "`num_beam_groups` has to be an integer smaller or equal than `num_beams` and `num_beams` has to be"
              f" divisible by `num_beam_groups`, but is {num_beam_groups} with `num_beams` being {num_beams}."
          )
  
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 1 to create a new BeamSearchScorer object from inherited base classes: BeamScorer with example: obj = BeamSearchScorer(batch_size, num_beams, device, length_penalty, do_early_stopping, num_beam_hyps_to_keep, num_beam_groups, max_length)