class_docstr: Compute relative multi-head attention for XLNet encoder.
  
  This module computes relative multi-head attention as explained in
  `Transformer-XL, (Zihang et. al)` and in `XLNet (Zhiling et. al)`.
  
  Args:
      r_r_bias: A tensor of shape `(num_heads, head_dim)`.
          The bias value added to query head while computing position based
          attention score.
  
      r_w_bias: A tensor of shape `(num_heads, head_dim)`.
          The bias value added to query head while computing content based
          attention score.
  
      r_s_bias (optional): A tensor of shape `(num_heads, head_dim)`.
          The bias value added to query head while computing segment based
          attention score.
  
      segment_embed (optional): A tensor of shape `(2, num_heads, head_dim)`
          if use_segments is True. Otherwise, this is set to None.
  
      hparams (dict or HParams, optional): Hyperparameters. Missing
          hyperparameter will be set to default values. See
          :meth:`default_hparams` for the hyperparameter sturcture
          and default values.
class_docstr_tok: ["Compute","relative","multi-head","attention","for","XLNet","encoder",".","This","module","computes","relative","multi-head","attention","as","explained","in","`","Transformer-XL",",","(","Zihang","et",".","al",")","`","and","in","`","XLNet","(","Zhiling","et",".","al",")","`",".","Args",":","r_r_bias",":","A","tensor","of","shape","`","(","num_heads",",","head_dim",")","`",".","The","bias","value","added","to","query","head","while","computing","position","based","attention","score",".","r_w_bias",":","A","tensor","of","shape","`","(","num_heads",",","head_dim",")","`",".","The","bias","value","added","to","query","head","while","computing","content","based","attention","score",".","r_s_bias","(","optional",")",":","A","tensor","of","shape","`","(","num_heads",",","head_dim",")","`",".","The","bias","value","added","to","query","head","while","computing","segment","based","attention","score",".","segment_embed","(","optional",")",":","A","tensor","of","shape","`","(","2",",","num_heads",",","head_dim",")","`","if","use_segments","is","True",".","Otherwise",",","this","is","set","to","None",".","hparams","(","dict","or","HParams",",","optional",")",":","Hyperparameters",".","Missing","hyperparameter","will","be","set","to","default","values",".","See",":","meth",":","`","default_hparams","`","for","the","hyperparameter","sturcture","and","default","values","."]
docstr: Compute relative multi-head attention with relative positional
  encoding.
  
  Args:
      states_h: A content representation tensor of shape
          `[max_time, batch_size, hidden_dim]`
  
      pos_embed: Position embedding tensor of shape
          `[max_time, batch_size, hidden_dim]`.
  
      states_g (optional): A query representation tensor of shape
          `[max_time, batch_size, hidden_dim]`. This tensor is set during
          decoding.
  
      segment_mat (optional): A tensor of size
          `[max_time, tot_len, batch_size]` indicating if tokens are in the
           same seqment. A value at `(i, j, k)` of `1` indicates tokens at
            `i` and `j` are not in the same sequence in batch k.
  
      attn_mask_h (optional): A tensor of shape
          `[max_time, max_time, batch_size, 1]` Attention mask used while
          computing attention score for `states_h`
  
      attn_mask_g (optional): A tensor of shape
          `[max_time, max_time, batch_size, 1]` Attention mask used while
          computing attention score for `states_g`
  
      target_mapping (optional): The target token mapping. Float tensor of
          shape `[num_targets, max_time, batch_size]`.
          A value of 1 for ``target_mapping[i, j, k]`` indicates that
          the `i`-th target token (in order of permutation) in batch `k`
          is the token at position `j`.
          Each row ``target_mapping[i, :, k]`` can have no more than one
          value of 1.
  
      memory (optional): Memory from previous batches. A list of length
          `num_layers`, each a tensor of shape
          `[mem_len, batch_size, hidden_dim]`.
  
      mode (optional): A tensor taking value in
          :tf_main:`tf.estimator.ModeKeys <estimator/ModeKeys>`, including
          `TRAIN`, `EVAL`, and `PREDICT`. If `None`, dropout is
          controlled by :func:`texar.tf.global_mode`.
  
  :returns: Returns output states for `states_h` and `states_g`
      (`states_g` is not None)
docstr_tok: ["Compute","relative","multi-head","attention","with","relative","positional","encoding",".","Args",":","states_h",":","A","content","representation","tensor","of","shape","`","[","max_time",",","batch_size",",","hidden_dim","]","`","pos_embed",":","Position","embedding","tensor","of","shape","`","[","max_time",",","batch_size",",","hidden_dim","]","`",".","states_g","(","optional",")",":","A","query","representation","tensor","of","shape","`","[","max_time",",","batch_size",",","hidden_dim","]","`",".","This","tensor","is","set","during","decoding",".","segment_mat","(","optional",")",":","A","tensor","of","size","`","[","max_time",",","tot_len",",","batch_size","]","`","indicating","if","tokens","are","in","the","same","seqment",".","A","value","at","`","(","i",",","j",",","k",")","`","of","`","1","`","indicates","tokens","at","`","i","`","and","`","j","`","are","not","in","the","same","sequence","in","batch","k.","attn_mask_h","(","optional",")",":","A","tensor","of","shape","`","[","max_time",",","max_time",",","batch_size",",","1","]","`","Attention","mask","used","while","computing","attention","score","for","`","states_h","`","attn_mask_g","(","optional",")",":","A","tensor","of","shape","`","[","max_time",",","max_time",",","batch_size",",","1","]","`","Attention","mask","used","while","computing","attention","score","for","`","states_g","`","target_mapping","(","optional",")",":","The","target","token","mapping",".","Float","tensor","of","shape","`","[","num_targets",",","max_time",",","batch_size","]","`",".","A","value","of","1","for","``","target_mapping","[","i",",","j",",","k","]","``","indicates","that","the","`","i","`","-th","target","token","(","in","order","of","permutation",")","in","batch","`","k","`","is","the","token","at","position","`","j","`",".","Each","row","``","target_mapping","[","i",",",":",",","k","]","``","can","have","no","more","than","one","value","of","1.","memory","(","optional",")",":","Memory","from","previous","batches",".","A","list","of","length","`","num_layers","`",",","each","a","tensor","of","shape","`","[","mem_len",",","batch_size",",","hidden_dim","]","`",".","mode","(","optional",")",":","A","tensor","taking","value","in",":","tf_main",":","`","tf.estimator.ModeKeys","<","estimator\/ModeKeys",">","`",",","including","`","TRAIN","`",",","`","EVAL","`",",","and","`","PREDICT","`",".","If","`","None","`",",","dropout","is","controlled","by",":","func",":","`","texar.tf.global_mode","`",".",":","returns",":","Returns","output","states","for","`","states_h","`","and","`","states_g","`","(","`","states_g","`","is","not","None",")"]
code: def _build(
      self,
      states_h,
      pos_embed,
      states_g=None,
      segment_mat=None,
      attn_mask_h=None,
      attn_mask_g=None,
      target_mapping=None,
      memory=None,
      mode=None,
  ):
      r"""Compute relative multi-head attention with relative positional
      encoding.
  
      Args:
          states_h: A content representation tensor of shape
              `[max_time, batch_size, hidden_dim]`
  
          pos_embed: Position embedding tensor of shape
              `[max_time, batch_size, hidden_dim]`.
  
          states_g (optional): A query representation tensor of shape
              `[max_time, batch_size, hidden_dim]`. This tensor is set during
              decoding.
  
          segment_mat (optional): A tensor of size
              `[max_time, tot_len, batch_size]` indicating if tokens are in the
               same seqment. A value at `(i, j, k)` of `1` indicates tokens at
                `i` and `j` are not in the same sequence in batch k.
  
          attn_mask_h (optional): A tensor of shape
              `[max_time, max_time, batch_size, 1]` Attention mask used while
              computing attention score for `states_h`
  
          attn_mask_g (optional): A tensor of shape
              `[max_time, max_time, batch_size, 1]` Attention mask used while
              computing attention score for `states_g`
  
          target_mapping (optional): The target token mapping. Float tensor of
              shape `[num_targets, max_time, batch_size]`.
              A value of 1 for ``target_mapping[i, j, k]`` indicates that
              the `i`-th target token (in order of permutation) in batch `k`
              is the token at position `j`.
              Each row ``target_mapping[i, :, k]`` can have no more than one
              value of 1.
  
          memory (optional): Memory from previous batches. A list of length
              `num_layers`, each a tensor of shape
              `[mem_len, batch_size, hidden_dim]`.
  
          mode (optional): A tensor taking value in
              :tf_main:`tf.estimator.ModeKeys <estimator/ModeKeys>`, including
              `TRAIN`, `EVAL`, and `PREDICT`. If `None`, dropout is
              controlled by :func:`texar.tf.global_mode`.
  
      :returns: Returns output states for `states_h` and `states_g`
          (`states_g` is not None)
      """
      batch_size = tf.shape(states_h)[1]
  
      if memory is not None and memory.shape.ndims > 1:
          concat_input = tf.concat([memory, states_h], axis=0)
      else:
          concat_input = states_h
  
      # Content heads.
      q_head_h = tf.einsum("ibh,hnd->ibnd", states_h, self.q_head)
      k_head_h = tf.einsum("ibh,hnd->ibnd", concat_input, self.k_head)
      v_head_h = tf.einsum("ibh,hnd->ibnd", concat_input, self.v_head)
  
      # Positional heads.
      k_head_r = tf.einsum("ibh,hnd->ibnd", pos_embed, self.k_head_r)
  
      # Core attention ops.
      attn_vec_h = self._compute_attention_score(
          q_head_h,
          k_head_h,
          v_head_h,
          k_head_r,
          segment_mat,
          attn_mask_h,
          mode,
      )
  
      # Post attention processing.
      attn_out_h = self._post_attention(attn_vec_h, mode=mode)
  
      output_h = tf.contrib.layers.layer_norm(
          attn_out_h + states_h,
          begin_norm_axis=-1,
          scope=self.variable_scope,
          reuse=tf.AUTO_REUSE,
      )
  
      if states_g is not None:
          q_head_g = tf.einsum("ibh,hnd->ibnd", states_g, self.q_head)
          shape = tf.shape(q_head_g)
          q_head_g = tf.reshape(
              q_head_g,
              shape=(
                  shape[0],
                  batch_size,
                  self.num_heads,
                  self.head_dim,
              ),
          )
          if target_mapping is not None:
              q_head_g = tf.einsum(
                  "mbnd,mlb->lbnd", q_head_g, target_mapping
              )
          attn_vec_g = self._compute_attention_score(
              q_head_g,
              k_head_h,
              v_head_h,
              k_head_r,
              segment_mat,
              attn_mask_g,
              mode,
          )
          if target_mapping is not None:
              attn_vec_g = tf.einsum(
                  "lbnd,mlb->mbnd", attn_vec_g, target_mapping
              )
          attn_out_g = self._post_attention(attn_vec_g, mode=mode)
          output_g = tf.contrib.layers.layer_norm(
              attn_out_g + states_g,
              begin_norm_axis=-1,
              scope=self.variable_scope,
              reuse=tf.AUTO_REUSE,
          )
      else:
          output_g = None
  
      return output_h, output_g
  
imports: import tensorflow
  from texar.tf.core import layers
  from texar.tf.module_base import ModuleBase
  from texar.tf.utils.mode import is_train_mode
label_desc: Use image node_id 6 for calling the RelativeMutiheadAttention obj's underlying member method code with example usage: obj._build(states_h, pos_embed, states_g, segment_mat, attn_mask_h, attn_mask_g, target_mapping, memory, mode) and returns: output_h,  output_g