class_docstr: Transformer decoder consisting of *config.decoder_layers* layers. Each layer is a [`M2M100DecoderLayer`]
  
  Args:
      config: M2M100Config
      embed_tokens (nn.Embedding): output embedding
class_docstr_tok: ["Transformer","decoder","consisting","of","*","config.decoder_layers","*","layers",".","Each","layer","is","a","[","`","M2M100DecoderLayer","`","]","Args",":","config",":","M2M100Config","embed_tokens","(","nn.Embedding",")",":","output","embedding"]
docstr: Args:
      input_ids (`torch.LongTensor` of shape `(batch_size, sequence_length)`):
          Indices of input sequence tokens in the vocabulary. Padding will be ignored by default should you
          provide it.
  
          Indices can be obtained using [`AutoTokenizer`]. See [`PreTrainedTokenizer.encode`] and
          [`PreTrainedTokenizer.__call__`] for details.
  
          [What are input IDs?](../glossary#input-ids)
      attention_mask (`torch.Tensor` of shape `(batch_size, sequence_length)`, *optional*):
          Mask to avoid performing attention on padding token indices. Mask values selected in `[0, 1]`:
  
          - 1 for tokens that are **not masked**,
          - 0 for tokens that are **masked**.
  
          [What are attention masks?](../glossary#attention-mask)
      encoder_hidden_states (`torch.FloatTensor` of shape `(batch_size, encoder_sequence_length, hidden_size)`, *optional*):
          Sequence of hidden-states at the output of the last layer of the encoder. Used in the cross-attention
          of the decoder.
      encoder_attention_mask (`torch.LongTensor` of shape `(batch_size, encoder_sequence_length)`, *optional*):
          Mask to avoid performing cross-attention on padding tokens indices of encoder input_ids. Mask values
          selected in `[0, 1]`:
  
          - 1 for tokens that are **not masked**,
          - 0 for tokens that are **masked**.
  
          [What are attention masks?](../glossary#attention-mask)
      head_mask (`torch.Tensor` of shape `(decoder_layers, decoder_attention_heads)`, *optional*):
          Mask to nullify selected heads of the attention modules. Mask values selected in `[0, 1]`:
  
          - 1 indicates the head is **not masked**,
          - 0 indicates the head is **masked**.
  
      cross_attn_head_mask (`torch.Tensor` of shape `(decoder_layers, decoder_attention_heads)`, *optional*):
          Mask to nullify selected heads of the cross-attention modules in the decoder to avoid performing
          cross-attention on hidden heads. Mask values selected in `[0, 1]`:
  
          - 1 indicates the head is **not masked**,
          - 0 indicates the head is **masked**.
  
      past_key_values (`tuple(tuple(torch.FloatTensor))`, *optional*, returned when `use_cache=True` is passed or when `config.use_cache=True`):
          Tuple of `tuple(torch.FloatTensor)` of length `config.n_layers`, with each tuple having 2 tensors of
          shape `(batch_size, num_heads, sequence_length, embed_size_per_head)`) and 2 additional tensors of
          shape `(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)`.
  
          Contains pre-computed hidden-states (key and values in the self-attention blocks and in the
          cross-attention blocks) that can be used (see `past_key_values` input) to speed up sequential decoding.
  
          If `past_key_values` are used, the user can optionally input only the last `decoder_input_ids` (those
          that don't have their past key value states given to this model) of shape `(batch_size, 1)` instead of
          all `decoder_input_ids` of shape `(batch_size, sequence_length)`.
      inputs_embeds (`torch.FloatTensor` of shape `(batch_size, sequence_length, hidden_size)`, *optional*):
          Optionally, instead of passing `input_ids` you can choose to directly pass an embedded representation.
          This is useful if you want more control over how to convert `input_ids` indices into associated vectors
          than the model's internal embedding lookup matrix.
      output_attentions (`bool`, *optional*):
          Whether or not to return the attentions tensors of all attention layers. See `attentions` under
          returned tensors for more detail.
      output_hidden_states (`bool`, *optional*):
          Whether or not to return the hidden states of all layers. See `hidden_states` under returned tensors
          for more detail.
      return_dict (`bool`, *optional*):
          Whether or not to return a [`~utils.ModelOutput`] instead of a plain tuple.
docstr_tok: ["Args",":","input_ids","(","`","torch.LongTensor","`","of","shape","`","(","batch_size",",","sequence_length",")","`",")",":","Indices","of","input","sequence","tokens","in","the","vocabulary",".","Padding","will","be","ignored","by","default","should","you","provide","it",".","Indices","can","be","obtained","using","[","`","AutoTokenizer","`","]",".","See","[","`","PreTrainedTokenizer.encode","`","]","and","[","`","PreTrainedTokenizer.__call__","`","]","for","details",".","[","What","are","input","IDs","?","]","(","..","\/glossary","#","input-ids",")","attention_mask","(","`","torch.Tensor","`","of","shape","`","(","batch_size",",","sequence_length",")","`",",","*","optional","*",")",":","Mask","to","avoid","performing","attention","on","padding","token","indices",".","Mask","values","selected","in","`","[","0",",","1","]","`",":","-","1","for","tokens","that","are","*","*","not","masked","*","*",",","-","0","for","tokens","that","are","*","*","masked","*","*",".","[","What","are","attention","masks","?","]","(","..","\/glossary","#","attention-mask",")","encoder_hidden_states","(","`","torch.FloatTensor","`","of","shape","`","(","batch_size",",","encoder_sequence_length",",","hidden_size",")","`",",","*","optional","*",")",":","Sequence","of","hidden-states","at","the","output","of","the","last","layer","of","the","encoder",".","Used","in","the","cross-attention","of","the","decoder",".","encoder_attention_mask","(","`","torch.LongTensor","`","of","shape","`","(","batch_size",",","encoder_sequence_length",")","`",",","*","optional","*",")",":","Mask","to","avoid","performing","cross-attention","on","padding","tokens","indices","of","encoder","input_ids",".","Mask","values","selected","in","`","[","0",",","1","]","`",":","-","1","for","tokens","that","are","*","*","not","masked","*","*",",","-","0","for","tokens","that","are","*","*","masked","*","*",".","[","What","are","attention","masks","?","]","(","..","\/glossary","#","attention-mask",")","head_mask","(","`","torch.Tensor","`","of","shape","`","(","decoder_layers",",","decoder_attention_heads",")","`",",","*","optional","*",")",":","Mask","to","nullify","selected","heads","of","the","attention","modules",".","Mask","values","selected","in","`","[","0",",","1","]","`",":","-","1","indicates","the","head","is","*","*","not","masked","*","*",",","-","0","indicates","the","head","is","*","*","masked","*","*",".","cross_attn_head_mask","(","`","torch.Tensor","`","of","shape","`","(","decoder_layers",",","decoder_attention_heads",")","`",",","*","optional","*",")",":","Mask","to","nullify","selected","heads","of","the","cross-attention","modules","in","the","decoder","to","avoid","performing","cross-attention","on","hidden","heads",".","Mask","values","selected","in","`","[","0",",","1","]","`",":","-","1","indicates","the","head","is","*","*","not","masked","*","*",",","-","0","indicates","the","head","is","*","*","masked","*","*",".","past_key_values","(","`","tuple","(","tuple","(","torch.FloatTensor",")",")","`",",","*","optional","*",",","returned","when","`","use_cache=True","`","is","passed","or","when","`","config.use_cache=True","`",")",":","Tuple","of","`","tuple","(","torch.FloatTensor",")","`","of","length","`","config.n_layers","`",",","with","each","tuple","having","2","tensors","of","shape","`","(","batch_size",",","num_heads",",","sequence_length",",","embed_size_per_head",")","`",")","and","2","additional","tensors","of","shape","`","(","batch_size",",","num_heads",",","encoder_sequence_length",",","embed_size_per_head",")","`",".","Contains","pre-computed","hidden-states","(","key","and","values","in","the","self-attention","blocks","and","in","the","cross-attention","blocks",")","that","can","be","used","(","see","`","past_key_values","`","input",")","to","speed","up","sequential","decoding",".","If","`","past_key_values","`","are","used",",","the","user","can","optionally","input","only","the","last","`","decoder_input_ids","`","(","those","that","do","n't","have","their","past","key","value","states","given","to","this","model",")","of","shape","`","(","batch_size",",","1",")","`","instead","of","all","`","decoder_input_ids","`","of","shape","`","(","batch_size",",","sequence_length",")","`",".","inputs_embeds","(","`","torch.FloatTensor","`","of","shape","`","(","batch_size",",","sequence_length",",","hidden_size",")","`",",","*","optional","*",")",":","Optionally",",","instead","of","passing","`","input_ids","`","you","can","choose","to","directly","pass","an","embedded","representation",".","This","is","useful","if","you","want","more","control","over","how","to","convert","`","input_ids","`","indices","into","associated","vectors","than","the","model","'s","internal","embedding","lookup","matrix",".","output_attentions","(","`","bool","`",",","*","optional","*",")",":","Whether","or","not","to","return","the","attentions","tensors","of","all","attention","layers",".","See","`","attentions","`","under","returned","tensors","for","more","detail",".","output_hidden_states","(","`","bool","`",",","*","optional","*",")",":","Whether","or","not","to","return","the","hidden","states","of","all","layers",".","See","`","hidden_states","`","under","returned","tensors","for","more","detail",".","return_dict","(","`","bool","`",",","*","optional","*",")",":","Whether","or","not","to","return","a","[","`","~utils.ModelOutput","`","]","instead","of","a","plain","tuple","."]
code: def forward(
      self,
      input_ids: Optional[torch.Tensor] = None,
      attention_mask: Optional[torch.Tensor] = None,
      encoder_hidden_states: Optional[torch.Tensor] = None,
      encoder_attention_mask: Optional[torch.Tensor] = None,
      head_mask: Optional[torch.Tensor] = None,
      cross_attn_head_mask: Optional[torch.Tensor] = None,
      past_key_values: Optional[List[torch.FloatTensor]] = None,
      inputs_embeds: Optional[torch.Tensor] = None,
      use_cache: Optional[bool] = None,
      output_attentions: Optional[bool] = None,
      output_hidden_states: Optional[bool] = None,
      return_dict: Optional[bool] = None,
  ):
      r"""
      Args:
          input_ids (`torch.LongTensor` of shape `(batch_size, sequence_length)`):
              Indices of input sequence tokens in the vocabulary. Padding will be ignored by default should you
              provide it.
  
              Indices can be obtained using [`AutoTokenizer`]. See [`PreTrainedTokenizer.encode`] and
              [`PreTrainedTokenizer.__call__`] for details.
  
              [What are input IDs?](../glossary#input-ids)
          attention_mask (`torch.Tensor` of shape `(batch_size, sequence_length)`, *optional*):
              Mask to avoid performing attention on padding token indices. Mask values selected in `[0, 1]`:
  
              - 1 for tokens that are **not masked**,
              - 0 for tokens that are **masked**.
  
              [What are attention masks?](../glossary#attention-mask)
          encoder_hidden_states (`torch.FloatTensor` of shape `(batch_size, encoder_sequence_length, hidden_size)`, *optional*):
              Sequence of hidden-states at the output of the last layer of the encoder. Used in the cross-attention
              of the decoder.
          encoder_attention_mask (`torch.LongTensor` of shape `(batch_size, encoder_sequence_length)`, *optional*):
              Mask to avoid performing cross-attention on padding tokens indices of encoder input_ids. Mask values
              selected in `[0, 1]`:
  
              - 1 for tokens that are **not masked**,
              - 0 for tokens that are **masked**.
  
              [What are attention masks?](../glossary#attention-mask)
          head_mask (`torch.Tensor` of shape `(decoder_layers, decoder_attention_heads)`, *optional*):
              Mask to nullify selected heads of the attention modules. Mask values selected in `[0, 1]`:
  
              - 1 indicates the head is **not masked**,
              - 0 indicates the head is **masked**.
  
          cross_attn_head_mask (`torch.Tensor` of shape `(decoder_layers, decoder_attention_heads)`, *optional*):
              Mask to nullify selected heads of the cross-attention modules in the decoder to avoid performing
              cross-attention on hidden heads. Mask values selected in `[0, 1]`:
  
              - 1 indicates the head is **not masked**,
              - 0 indicates the head is **masked**.
  
          past_key_values (`tuple(tuple(torch.FloatTensor))`, *optional*, returned when `use_cache=True` is passed or when `config.use_cache=True`):
              Tuple of `tuple(torch.FloatTensor)` of length `config.n_layers`, with each tuple having 2 tensors of
              shape `(batch_size, num_heads, sequence_length, embed_size_per_head)`) and 2 additional tensors of
              shape `(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)`.
  
              Contains pre-computed hidden-states (key and values in the self-attention blocks and in the
              cross-attention blocks) that can be used (see `past_key_values` input) to speed up sequential decoding.
  
              If `past_key_values` are used, the user can optionally input only the last `decoder_input_ids` (those
              that don't have their past key value states given to this model) of shape `(batch_size, 1)` instead of
              all `decoder_input_ids` of shape `(batch_size, sequence_length)`.
          inputs_embeds (`torch.FloatTensor` of shape `(batch_size, sequence_length, hidden_size)`, *optional*):
              Optionally, instead of passing `input_ids` you can choose to directly pass an embedded representation.
              This is useful if you want more control over how to convert `input_ids` indices into associated vectors
              than the model's internal embedding lookup matrix.
          output_attentions (`bool`, *optional*):
              Whether or not to return the attentions tensors of all attention layers. See `attentions` under
              returned tensors for more detail.
          output_hidden_states (`bool`, *optional*):
              Whether or not to return the hidden states of all layers. See `hidden_states` under returned tensors
              for more detail.
          return_dict (`bool`, *optional*):
              Whether or not to return a [`~utils.ModelOutput`] instead of a plain tuple.
      """
      output_attentions = (
          output_attentions
          if output_attentions is not None
          else self.config.output_attentions
      )
      output_hidden_states = (
          output_hidden_states
          if output_hidden_states is not None
          else self.config.output_hidden_states
      )
      use_cache = (
          use_cache if use_cache is not None else self.config.use_cache
      )
      return_dict = (
          return_dict
          if return_dict is not None
          else self.config.use_return_dict
      )
  
      # retrieve input_ids and inputs_embeds
      if input_ids is not None and inputs_embeds is not None:
          raise ValueError(
              "You cannot specify both decoder_input_ids and decoder_inputs_embeds at the same time"
          )
      elif input_ids is not None:
          input_shape = input_ids.size()
          input_ids = input_ids.view(-1, input_shape[-1])
      elif inputs_embeds is not None:
          input_shape = inputs_embeds.size()[:-1]
      else:
          raise ValueError(
              "You have to specify either decoder_input_ids or decoder_inputs_embeds"
          )
  
      # past_key_values_length
      past_key_values_length = (
          past_key_values[0][0].shape[2]
          if past_key_values is not None
          else 0
      )
  
      if inputs_embeds is None:
          inputs_embeds = (
              self.embed_tokens(input_ids) * self.embed_scale
          )
  
      # create causal mask
      # [bsz, seq_len] -> [bsz, 1, tgt_seq_len, src_seq_len]
      combined_attention_mask = _prepare_4d_causal_attention_mask(
          attention_mask,
          input_shape,
          inputs_embeds,
          past_key_values_length,
      )
  
      # expand encoder attention mask
      if (
          encoder_hidden_states is not None
          and encoder_attention_mask is not None
      ):
          # [bsz, seq_len] -> [bsz, 1, tgt_seq_len, src_seq_len]
          encoder_attention_mask = _prepare_4d_attention_mask(
              encoder_attention_mask,
              inputs_embeds.dtype,
              tgt_len=input_shape[-1],
          )
  
      # embed positions
      positions = self.embed_positions(
          input_ids, inputs_embeds, past_key_values_length
      )
      positions = positions.to(inputs_embeds.device)
  
      hidden_states = inputs_embeds + positions
  
      hidden_states = nn.functional.dropout(
          hidden_states, p=self.dropout, training=self.training
      )
  
      if self.gradient_checkpointing and self.training:
          if use_cache:
              logger.warning_once(
                  "`use_cache=True` is incompatible with gradient checkpointing. Setting"
                  " `use_cache=False`..."
              )
              use_cache = False
  
      # decoder layers
      all_hidden_states = () if output_hidden_states else None
      all_self_attns = () if output_attentions else None
      all_cross_attentions = () if output_attentions else None
      next_decoder_cache = () if use_cache else None
  
      # check if head_mask/cross_attn_head_mask has a correct number of layers specified if desired
      for attn_mask, mask_name in zip(
          [head_mask, cross_attn_head_mask],
          ["head_mask", "cross_attn_head_mask"],
      ):
          if attn_mask is not None:
              if attn_mask.size()[0] != len(self.layers):
                  raise ValueError(
                      f"The `{mask_name}` should be specified for {len(self.layers)} layers, but it is for"
                      f" {head_mask.size()[0]}."
                  )
      deepspeed_zero3_is_enabled = is_deepspeed_zero3_enabled()
  
      for idx, decoder_layer in enumerate(self.layers):
          if output_hidden_states:
              all_hidden_states += (hidden_states,)
  
          # add LayerDrop (see https://arxiv.org/abs/1909.11556 for description)
          dropout_probability = torch.rand([])
  
          skip_the_layer = (
              True
              if self.training
              and (dropout_probability < self.layerdrop)
              else False
          )
          if not skip_the_layer or deepspeed_zero3_is_enabled:
              # under deepspeed zero3 all gpus must run in sync
  
              past_key_value = (
                  past_key_values[idx]
                  if past_key_values is not None
                  else None
              )
  
              if self.gradient_checkpointing and self.training:
                  layer_outputs = self._gradient_checkpointing_func(
                      decoder_layer.__call__,
                      hidden_states,
                      combined_attention_mask,
                      encoder_hidden_states,
                      encoder_attention_mask,
                      head_mask[idx] if head_mask is not None else None,
                      cross_attn_head_mask[idx]
                      if cross_attn_head_mask is not None
                      else None,
                      None,
                      output_attentions,
                      use_cache,
                  )
              else:
                  layer_outputs = decoder_layer(
                      hidden_states,
                      attention_mask=combined_attention_mask,
                      encoder_hidden_states=encoder_hidden_states,
                      encoder_attention_mask=encoder_attention_mask,
                      layer_head_mask=(
                          head_mask[idx]
                          if head_mask is not None
                          else None
                      ),
                      cross_attn_layer_head_mask=(
                          cross_attn_head_mask[idx]
                          if cross_attn_head_mask is not None
                          else None
                      ),
                      past_key_value=past_key_value,
                      output_attentions=output_attentions,
                      use_cache=use_cache,
                  )
  
              hidden_states = layer_outputs[0]
  
          if skip_the_layer:
              continue
  
          if use_cache:
              next_decoder_cache += (
                  layer_outputs[3 if output_attentions else 1],
              )
  
          if output_attentions:
              all_self_attns += (layer_outputs[1],)
              all_cross_attentions += (layer_outputs[2],)
  
      hidden_states = self.layer_norm(hidden_states)
  
      # add hidden states from the last decoder layer
      if output_hidden_states:
          all_hidden_states += (hidden_states,)
  
      next_cache = next_decoder_cache if use_cache else None
      if not return_dict:
          return tuple(
              v
              for v in [
                  hidden_states,
                  next_cache,
                  all_hidden_states,
                  all_self_attns,
                  all_cross_attentions,
              ]
              if v is not None
          )
      return BaseModelOutputWithPastAndCrossAttentions(
          last_hidden_state=hidden_states,
          past_key_values=next_cache,
          hidden_states=all_hidden_states,
          attentions=all_self_attns,
          cross_attentions=all_cross_attentions,
      )
  
imports: import math
  from typing import List, Optional, Tuple, Union
  import torch
  from torch import nn
  from torch.nn import CrossEntropyLoss
  from ...activations import ACT2FN
  from ...integrations.deepspeed import is_deepspeed_zero3_enabled
  from ...modeling_attn_mask_utils import _prepare_4d_attention_mask, _prepare_4d_causal_attention_mask
  from ...modeling_outputs import BaseModelOutput, BaseModelOutputWithPastAndCrossAttentions, Seq2SeqLMOutput, Seq2SeqModelOutput
  from ...modeling_utils import PreTrainedModel
  from ...utils import add_code_sample_docstrings, add_end_docstrings, add_start_docstrings, add_start_docstrings_to_model_forward, logging, replace_return_docstrings
  from .configuration_m2m_100 import M2M100Config
label_desc: Use image node_id 2 for calling the M2M100Decoder obj's underlying member method code with example usage: obj.forward(input_ids, attention_mask, encoder_hidden_states, encoder_attention_mask, head_mask, cross_attn_head_mask, past_key_values, inputs_embeds, use_cache, output_attentions, output_hidden_states, return_dict) and returns: BaseModelOutputWithPastAndCrossAttentions, tuple