class_docstr: Raw XLNet module for encoding sequences. Please see
  :class:`~texar.tf.modules.PretrainedXLNetMixin` for a brief description
  of XLNet.
  
  Args:
      pretrained_model_name (optional): a `str`, the name
          of pre-trained model (e.g., ``xlnet-based-cased``). Please refer to
          :class:`~texar.tf.modules.PretrainedXLNetMixin` for
          all supported models.
          If `None`, the model name in :attr:`hparams` is used.
      cache_dir (optional): the path to a folder in which the
          pre-trained models will be cached. If `None` (default),
          a default directory (``texar_data`` folder under user's home
          directory) will be used.
      hparams (dict or HParams, optional): Hyperparameters. Missing
          hyperparameter will be set to default values. See
          :meth:`default_hparams` for the hyperparameter structure
          and default values.
  
  .. document private functions
  .. automethod:: _build
class_docstr_tok: ["Raw","XLNet","module","for","encoding","sequences",".","Please","see",":","class",":","`","~texar.tf.modules.PretrainedXLNetMixin","`","for","a","brief","description","of","XLNet",".","Args",":","pretrained_model_name","(","optional",")",":","a","`","str","`",",","the","name","of","pre-trained","model","(","e.g.",",","``","xlnet-based-cased","``",")",".","Please","refer","to",":","class",":","`","~texar.tf.modules.PretrainedXLNetMixin","`","for","all","supported","models",".","If","`","None","`",",","the","model","name","in",":","attr",":","`","hparams","`","is","used",".","cache_dir","(","optional",")",":","the","path","to","a","folder","in","which","the","pre-trained","models","will","be","cached",".","If","`","None","`","(","default",")",",","a","default","directory","(","``","texar_data","``","folder","under","user","'s","home","directory",")","will","be","used",".","hparams","(","dict","or","HParams",",","optional",")",":","Hyperparameters",".","Missing","hyperparameter","will","be","set","to","default","values",".","See",":","meth",":","`","default_hparams","`","for","the","hyperparameter","structure","and","default","values",".","..","document","private","functions","..","automethod",":",":","_build"]
docstr: Create parameter groups for optimizers. When
  :attr:`lr_layer_decay_rate` is not 1.0, parameters from each layer form
  separate groups with different base learning rates.
  
  This method should be called before applying gradients to the variables
  through the optimizer. Particularly, after calling the optimizer's
  `compute_gradients` method, the user can call this method to get
  variable-specific learning rates for the network. The gradients for each
  variables can then be scaled accordingly. These scaled gradients are
  finally applied by calling optimizer's `apply_gradients` method.
  
  Example:
  
      .. code-block:: python
  
          grads_and_vars = optimizer.compute_gradients(loss)
  
          vars_to_grads = {key: value for key, value in grads_and_vars}
  
          vars_to_learning_rates = xlnet_encoder.param_groups(
                                                  lr=1,
                                                  ly_layer_scale=0.75)
  
          for key in vars_to_grads.keys():
              vars_to_grads[key] *= vars_to_learning_rates[key]
  
          train_op = optimizer.apply_gradients(zip(
              *vars_to_grads.items()))
  
  
  Args:
      lr (float): The learning rate. Can be omitted if
          :attr:`lr_layer_decay_rate` is 1.0.
      lr_layer_scale (float): Per-layer LR scaling rate. The `i`-th layer
          will be scaled by `lr_layer_scale ^ (num_layers - i - 1)`.
      decay_base_params (bool): If `True`, treat non-layer parameters
          (e.g. embeddings) as if they're in layer 0. If `False`, these
          parameters are not scaled.
  
  Returns: A dict mapping tensorflow variables to their learning rates.
docstr_tok: ["Create","parameter","groups","for","optimizers",".","When",":","attr",":","`","lr_layer_decay_rate","`","is","not","1.0",",","parameters","from","each","layer","form","separate","groups","with","different","base","learning","rates",".","This","method","should","be","called","before","applying","gradients","to","the","variables","through","the","optimizer",".","Particularly",",","after","calling","the","optimizer's","`","compute_gradients","`","method",",","the","user","can","call","this","method","to","get","variable-specific","learning","rates","for","the","network",".","The","gradients","for","each","variables","can","then","be","scaled","accordingly",".","These","scaled","gradients","are","finally","applied","by","calling","optimizer","'s","`","apply_gradients","`","method",".","Example",":","..","code-block",":",":","python","grads_and_vars","=","optimizer.compute_gradients","(","loss",")","vars_to_grads","=","{","key",":","value","for","key",",","value","in","grads_and_vars","}","vars_to_learning_rates","=","xlnet_encoder.param_groups","(","lr=1",",","ly_layer_scale=0.75",")","for","key","in","vars_to_grads.keys","(",")",":","vars_to_grads","[","key","]","*","=","vars_to_learning_rates","[","key","]","train_op","=","optimizer.apply_gradients","(","zip","(","*","vars_to_grads.items","(",")",")",")","Args",":","lr","(","float",")",":","The","learning","rate",".","Can","be","omitted","if",":","attr",":","`","lr_layer_decay_rate","`","is","1.0.","lr_layer_scale","(","float",")",":","Per-layer","LR","scaling","rate",".","The","`","i","`","-th","layer","will","be","scaled","by","`","lr_layer_scale","^","(","num_layers","-","i","-","1",")","`",".","decay_base_params","(","bool",")",":","If","`","True","`",",","treat","non-layer","parameters","(","e.g",".","embeddings",")","as","if","they","'re","in","layer","0",".","If","`","False","`",",","these","parameters","are","not","scaled",".","Returns",":","A","dict","mapping","tensorflow","variables","to","their","learning","rates","."]
code: def param_groups(
      self, lr=None, lr_layer_scale=1.0, decay_base_params=False
  ):
      r"""Create parameter groups for optimizers. When
      :attr:`lr_layer_decay_rate` is not 1.0, parameters from each layer form
      separate groups with different base learning rates.
  
      This method should be called before applying gradients to the variables
      through the optimizer. Particularly, after calling the optimizer's
      `compute_gradients` method, the user can call this method to get
      variable-specific learning rates for the network. The gradients for each
      variables can then be scaled accordingly. These scaled gradients are
      finally applied by calling optimizer's `apply_gradients` method.
  
      Example:
  
          .. code-block:: python
  
              grads_and_vars = optimizer.compute_gradients(loss)
  
              vars_to_grads = {key: value for key, value in grads_and_vars}
  
              vars_to_learning_rates = xlnet_encoder.param_groups(
                                                      lr=1,
                                                      ly_layer_scale=0.75)
  
              for key in vars_to_grads.keys():
                  vars_to_grads[key] *= vars_to_learning_rates[key]
  
              train_op = optimizer.apply_gradients(zip(
                  *vars_to_grads.items()))
  
  
      Args:
          lr (float): The learning rate. Can be omitted if
              :attr:`lr_layer_decay_rate` is 1.0.
          lr_layer_scale (float): Per-layer LR scaling rate. The `i`-th layer
              will be scaled by `lr_layer_scale ^ (num_layers - i - 1)`.
          decay_base_params (bool): If `True`, treat non-layer parameters
              (e.g. embeddings) as if they're in layer 0. If `False`, these
              parameters are not scaled.
  
      Returns: A dict mapping tensorflow variables to their learning rates.
      """
      vars_to_learning_rates = {}
      if lr_layer_scale != 1.0:
          if lr is None:
              raise ValueError(
                  "lr must be specified when lr_layer_decay_rate is not 1.0"
              )
  
          num_layers = self._hparams.num_layers
          scope = self.variable_scope.name
          base_var_names = ["r_w_bias", "r_r_bias", "word_embedder"]
  
          if self._hparams.use_segments:
              base_var_names.extend(["r_s_bias", "seg_embed"])
  
          for var in base_var_names:
              tf_variable = tf.trainable_variables(
                  scope=scope + "/" + var
              )[0]
              vars_to_learning_rates[tf_variable] = lr * (
                  lr_layer_scale**num_layers
                  if decay_base_params
                  else 1.0
              )
  
          for idx in range(num_layers):
              decay_rate = lr_layer_scale ** (num_layers - idx - 1)
              layer_variables = tf.trainable_variables(
                  scope=scope + "/" + "layer_{}".format(idx)
              )
              for variable in layer_variables:
                  vars_to_learning_rates[variable] = lr * decay_rate
      else:
          for variable in self.trainable_variables:
              vars_to_learning_rates[variable] = lr
  
      return vars_to_learning_rates
  
imports: import tensorflow
  from texar.tf.utils.mode import is_train_mode
  from texar.tf.core.layers import get_initializer, get_layer
  from texar.tf.modules.embedders.embedders import WordEmbedder
  from texar.tf.modules.encoders.encoder_base import EncoderBase
  from texar.tf.modules.pretrained.xlnet import PretrainedXLNetMixin
  from texar.tf.modules.pretrained.xlnet_utils import PositionWiseFF, RelativePositionalEncoding, RelativeMutiheadAttention
  from texar.tf.utils.utils import dict_fetch
label_desc: Use image node_id 4 for calling the XLNetEncoder obj's underlying member method code with example usage: obj.param_groups(lr, lr_layer_scale, decay_base_params) and returns: vars_to_learning_rates