class_docstr: Multi-headed self-attention for WavLM model :cite:`chen2022wavlm`.
  Wraps around ``torch.nn.MultiheadAttention``, creating relaive position embeddings and passing them to multi-headed
  attention as a mask.
  Source: https://github.com/microsoft/unilm/blob/2d8302f09c99bca2b82e6e868d81d4281cceebc8/wavlm/modules.py#L303-L763
  
  Args:
      embed_dim (int): Total dimension of the model.
      num_heads (int): The number of heads.
      dropout (float, optional): Dropout probability on attn_output_weights. (Default: to ``0.0``)
      bias (bool, optional): If ``True``, add bias to input / output projection layers. (Default: ``True``)
      has_relative_attention_bias (bool, optional): If ``True``, apply relative position embedding.
          Necessary in the first encoder layer, but not in the subsequent ones. (Default: ``False``)
      num_buckets (int, optional): Number of buckets for relative position embedding. (Default: ``32``)
      max_distance (int, optional): Naximum distance for relative position embedding. (Default: ``128``)
      gru_rel_pos (bool, optional): If ``True``, apply gated relative position embedding. (Default: ``False``)
docstr: Compute relative position buckets for WavLM model. Computation similar to formula (5) in WavLM
     paper :cite:`chen2022wavlm`.
  Args:
      relative_positions (Tensor): Relative offsets between query and key positions,
          of shape ``(query_length, key_length)``.
      bidirectional (bool): If ``True``, values will be filled both above and below the diagonal in the resulting
          matrix. If ``False``, the elements above the diagonal (i.e. with negative relative offsets) will be set
          to zero. (Default ``True``)
  Returns:
      Tensor of shape ``(query_length, key_length)`` filled bucketed values of with relative positions.
code: def _relative_positions_bucket(
      self, relative_positions: Tensor, bidirectional: bool = True
  ):
      """Compute relative position buckets for WavLM model. Computation similar to formula (5) in WavLM
         paper :cite:`chen2022wavlm`.
      Args:
          relative_positions (Tensor): Relative offsets between query and key positions,
              of shape ``(query_length, key_length)``.
          bidirectional (bool): If ``True``, values will be filled both above and below the diagonal in the resulting
              matrix. If ``False``, the elements above the diagonal (i.e. with negative relative offsets) will be set
              to zero. (Default ``True``)
      Returns:
          Tensor of shape ``(query_length, key_length)`` filled bucketed values of with relative positions.
      """
      num_buckets = self.num_buckets
      max_distance = self.max_distance
      # Shape (query_length, key_length)
      relative_buckets = torch.zeros_like(
          relative_positions, dtype=torch.long
      )
  
      if bidirectional:
          num_buckets = num_buckets // 2
          relative_buckets += (relative_positions > 0).to(
              torch.long
          ) * num_buckets
          relative_positions = torch.abs(relative_positions)
      else:
          relative_positions = -torch.min(
              relative_positions, torch.zeros_like(relative_positions)
          )
  
      max_exact = num_buckets // 2
      is_small = relative_positions < max_exact
  
      relative_postion_if_large = max_exact + (
          torch.log(relative_positions.float() / max_exact)
          / math.log(max_distance / max_exact)
          * (num_buckets - max_exact)
      ).to(torch.long)
      relative_postion_if_large = torch.min(
          relative_postion_if_large,
          torch.full_like(relative_postion_if_large, num_buckets - 1),
      )
  
      relative_buckets += torch.where(
          is_small, relative_positions, relative_postion_if_large
      )
      return relative_buckets
  
file_path: audio/src/torchaudio/models/wav2vec2/wavlm_attention.py
imports: import math
  from typing import Optional, Tuple
  import torch
  from torch import nn, Tensor
label_desc: Use image node_id 3 for calling the WavLMSelfAttention obj's underlying member method code with example usage: obj._relative_positions_bucket(relative_positions, bidirectional) and returns: relative_buckets