class_docstr: Bidirectional forward-backward RNN encoder.
  
  Args:
      cell_fw (RNNCell, optional): The forward RNN cell. If not given,
          a cell is created as specified in :attr:`hparams["rnn_cell_fw"]`.
      cell_bw (RNNCell, optional): The backward RNN cell. If not given,
          a cell is created as specified in :attr:`hparams["rnn_cell_bw"]`.
      cell_dropout_mode (optional): A tensor taking value of
          :tf_main:`tf.estimator.ModeKeys <estimator/ModeKeys>`, which
          toggles dropout in the RNN cells (e.g., activates dropout in
          TRAIN mode). If `None`, :func:`~texar.tf.global_mode()` is
          used. Ignored if respective cell is given.
      output_layer_fw (optional): An instance of
          :tf_main:`tf.layers.Layer <layers/Layer>`. Apply to the forward
          RNN cell output of each step. If `None` (default), the output
          layer is created as specified in :attr:`hparams["output_layer_fw"]`.
      output_layer_bw (optional): An instance of
          :tf_main:`tf.layers.Layer <layers/Layer>`. Apply to the backward
          RNN cell output of each step. If `None` (default), the output
          layer is created as specified in :attr:`hparams["output_layer_bw"]`.
      hparams (dict or HParams, optional): Hyperparameters. Missing
          hyperparamerter will be set to default values. See
          :meth:`default_hparams` for the hyperparameter sturcture and
          default values.
  
  See :meth:`_build` for the inputs and outputs of the encoder.
  
  Example:
  
      .. code-block:: python
  
          # Use with embedder
          embedder = WordEmbedder(vocab_size, hparams=emb_hparams)
          encoder = BidirectionalRNNEncoder(hparams=enc_hparams)
  
          outputs, final_state = encoder(
              inputs=embedder(data_batch['text_ids']),
              sequence_length=data_batch['length'])
          # outputs == (outputs_fw, outputs_bw)
          # final_state == (final_state_fw, final_state_bw)
  
  .. document private functions
  .. automethod:: _build
class_docstr_tok: ["Bidirectional","forward-backward","RNN","encoder",".","Args",":","cell_fw","(","RNNCell",",","optional",")",":","The","forward","RNN","cell",".","If","not","given",",","a","cell","is","created","as","specified","in",":","attr",":","`","hparams","[","``","rnn_cell_fw","''","]","`",".","cell_bw","(","RNNCell",",","optional",")",":","The","backward","RNN","cell",".","If","not","given",",","a","cell","is","created","as","specified","in",":","attr",":","`","hparams","[","``","rnn_cell_bw","''","]","`",".","cell_dropout_mode","(","optional",")",":","A","tensor","taking","value","of",":","tf_main",":","`","tf.estimator.ModeKeys","<","estimator\/ModeKeys",">","`",",","which","toggles","dropout","in","the","RNN","cells","(","e.g.",",","activates","dropout","in","TRAIN","mode",")",".","If","`","None","`",",",":","func",":","`","~texar.tf.global_mode","(",")","`","is","used",".","Ignored","if","respective","cell","is","given",".","output_layer_fw","(","optional",")",":","An","instance","of",":","tf_main",":","`","tf.layers.Layer","<","layers\/Layer",">","`",".","Apply","to","the","forward","RNN","cell","output","of","each","step",".","If","`","None","`","(","default",")",",","the","output","layer","is","created","as","specified","in",":","attr",":","`","hparams","[","``","output_layer_fw","''","]","`",".","output_layer_bw","(","optional",")",":","An","instance","of",":","tf_main",":","`","tf.layers.Layer","<","layers\/Layer",">","`",".","Apply","to","the","backward","RNN","cell","output","of","each","step",".","If","`","None","`","(","default",")",",","the","output","layer","is","created","as","specified","in",":","attr",":","`","hparams","[","``","output_layer_bw","''","]","`",".","hparams","(","dict","or","HParams",",","optional",")",":","Hyperparameters",".","Missing","hyperparamerter","will","be","set","to","default","values",".","See",":","meth",":","`","default_hparams","`","for","the","hyperparameter","sturcture","and","default","values",".","See",":","meth",":","`","_build","`","for","the","inputs","and","outputs","of","the","encoder",".","Example",":","..","code-block",":",":","python","#","Use","with","embedder","embedder","=","WordEmbedder","(","vocab_size",",","hparams=emb_hparams",")","encoder","=","BidirectionalRNNEncoder","(","hparams=enc_hparams",")","outputs",",","final_state","=","encoder","(","inputs=embedder","(","data_batch","[","'text_ids","'","]",")",",","sequence_length=data_batch","[","'length","'","]",")","#","outputs","==","(","outputs_fw",",","outputs_bw",")","#","final_state","==","(","final_state_fw",",","final_state_bw",")","..","document","private","functions","..","automethod",":",":","_build"]
docstr: Encodes the inputs.
  
  Args:
      inputs: A 3D Tensor of shape `[batch_size, max_time, dim]`.
          The first two dimensions
          `batch_size` and `max_time` may be exchanged if
          `time_major=True` is specified.
      sequence_length (optional): A 1D int tensor of shape `[batch_size]`.
          Sequence lengths
          of the batch inputs. Used to copy-through state and zero-out
          outputs when past a batch element's sequence length.
      initial_state (optional): Initial state of the RNN.
      time_major (bool): The shape format of the :attr:`inputs` and
          :attr:`outputs` Tensors. If `True`, these tensors are of shape
          `[max_time, batch_size, depth]`. If `False` (default),
          these tensors are of shape `[batch_size, max_time, depth]`.
      mode (optional): A tensor taking value in
          :tf_main:`tf.estimator.ModeKeys <estimator/ModeKeys>`, including
          `TRAIN`, `EVAL`, and `PREDICT`. Controls output layer dropout
          if the output layer is specified with :attr:`hparams`.
          If `None` (default), :func:`texar.tf.global_mode()`
          is used.
      return_cell_output (bool): Whether to return the output of the RNN
          cell. This is the results prior to the output layer.
      **kwargs: Optional keyword arguments of
          :tf_main:`tf.nn.dynamic_rnn <nn/dynamic_rnn>`,
          such as `swap_memory`, `dtype`, `parallel_iterations`, etc.
  
  Returns:
      - By default (both `return_cell_output` and `return_output_size`             are False), returns a pair :attr:`(outputs, final_state)`
  
          - :attr:`outputs`: A tuple `(outputs_fw, outputs_bw)`                 containing                 the forward and the backward RNN outputs, each of which is of                 shape `[batch_size, max_time, output_dim]` if                 `time_major` is False, or                 `[max_time, batch_size, output_dim]` if                 `time_major` is True.                 If RNN cell output is a (nested) tuple of Tensors, then                 `outputs_fw` and `outputs_bw` will be a (nested) tuple having                 the same structure as the cell output.
  
          - :attr:`final_state`: A tuple                 `(final_state_fw, final_state_bw)`                 containing the final states of the forward and backward                 RNNs, each of which is a                 Tensor of shape `[batch_size] + cell.state_size`, or                 a (nested) tuple of Tensors if `cell.state_size` is a (nested)                tuple.
  
      - If `return_cell_output` is True, returns a triple             :attr:`(outputs, final_state, cell_outputs)` where
  
          - :attr:`cell_outputs`: A tuple                 `(cell_outputs_fw, cell_outputs_bw)` containting the outputs                 by the forward and backward RNN cells prior to the                 output layers, having the same structure with :attr:`outputs`                 except for the `output_dim`.
  
      - If `return_output_size` is True, returns a tuple             :attr:`(outputs, final_state, output_size)` where
  
          - :attr:`output_size`: A tupple                 `(output_size_fw, output_size_bw)` containing the size of                 `outputs_fw` and `outputs_bw`, respectively.                 Take `*_fw` for example,                 `output_size_fw` is a (possibly nested tuple of) int.                 If a single int or an int array, then `outputs_fw` has shape                 `[batch/time, time/batch] + output_size_fw`. If                 a (nested) tuple, then `output_size_fw` has the same                 structure as with `outputs_fw`. The same applies to                  `output_size_bw`.
  
      - If both `return_cell_output` and             `return_output_size` are True, returns             :attr:`(outputs, final_state, cell_outputs, output_size)`.
docstr_tok: ["Encodes","the","inputs",".","Args",":","inputs",":","A","3D","Tensor","of","shape","`","[","batch_size",",","max_time",",","dim","]","`",".","The","first","two","dimensions","`","batch_size","`","and","`","max_time","`","may","be","exchanged","if","`","time_major=True","`","is","specified",".","sequence_length","(","optional",")",":","A","1D","int","tensor","of","shape","`","[","batch_size","]","`",".","Sequence","lengths","of","the","batch","inputs",".","Used","to","copy-through","state","and","zero-out","outputs","when","past","a","batch","element","'s","sequence","length",".","initial_state","(","optional",")",":","Initial","state","of","the","RNN",".","time_major","(","bool",")",":","The","shape","format","of","the",":","attr",":","`","inputs","`","and",":","attr",":","`","outputs","`","Tensors",".","If","`","True","`",",","these","tensors","are","of","shape","`","[","max_time",",","batch_size",",","depth","]","`",".","If","`","False","`","(","default",")",",","these","tensors","are","of","shape","`","[","batch_size",",","max_time",",","depth","]","`",".","mode","(","optional",")",":","A","tensor","taking","value","in",":","tf_main",":","`","tf.estimator.ModeKeys","<","estimator\/ModeKeys",">","`",",","including","`","TRAIN","`",",","`","EVAL","`",",","and","`","PREDICT","`",".","Controls","output","layer","dropout","if","the","output","layer","is","specified","with",":","attr",":","`","hparams","`",".","If","`","None","`","(","default",")",",",":","func",":","`","texar.tf.global_mode","(",")","`","is","used",".","return_cell_output","(","bool",")",":","Whether","to","return","the","output","of","the","RNN","cell",".","This","is","the","results","prior","to","the","output","layer",".","*","*","kwargs",":","Optional","keyword","arguments","of",":","tf_main",":","`","tf.nn.dynamic_rnn","<","nn\/dynamic_rnn",">","`",",","such","as","`","swap_memory","`",",","`","dtype","`",",","`","parallel_iterations","`",",","etc",".","Returns",":","-","By","default","(","both","`","return_cell_output","`","and","`","return_output_size","`","are","False",")",",","returns","a","pair",":","attr",":","`","(","outputs",",","final_state",")","`","-",":","attr",":","`","outputs","`",":","A","tuple","`","(","outputs_fw",",","outputs_bw",")","`","containing","the","forward","and","the","backward","RNN","outputs",",","each","of","which","is","of","shape","`","[","batch_size",",","max_time",",","output_dim","]","`","if","`","time_major","`","is","False",",","or","`","[","max_time",",","batch_size",",","output_dim","]","`","if","`","time_major","`","is","True",".","If","RNN","cell","output","is","a","(","nested",")","tuple","of","Tensors",",","then","`","outputs_fw","`","and","`","outputs_bw","`","will","be","a","(","nested",")","tuple","having","the","same","structure","as","the","cell","output",".","-",":","attr",":","`","final_state","`",":","A","tuple","`","(","final_state_fw",",","final_state_bw",")","`","containing","the","final","states","of","the","forward","and","backward","RNNs",",","each","of","which","is","a","Tensor","of","shape","`","[","batch_size","]","+","cell.state_size","`",",","or","a","(","nested",")","tuple","of","Tensors","if","`","cell.state_size","`","is","a","(","nested",")","tuple",".","-","If","`","return_cell_output","`","is","True",",","returns","a","triple",":","attr",":","`","(","outputs",",","final_state",",","cell_outputs",")","`","where","-",":","attr",":","`","cell_outputs","`",":","A","tuple","`","(","cell_outputs_fw",",","cell_outputs_bw",")","`","containting","the","outputs","by","the","forward","and","backward","RNN","cells","prior","to","the","output","layers",",","having","the","same","structure","with",":","attr",":","`","outputs","`","except","for","the","`","output_dim","`",".","-","If","`","return_output_size","`","is","True",",","returns","a","tuple",":","attr",":","`","(","outputs",",","final_state",",","output_size",")","`","where","-",":","attr",":","`","output_size","`",":","A","tupple","`","(","output_size_fw",",","output_size_bw",")","`","containing","the","size","of","`","outputs_fw","`","and","`","outputs_bw","`",",","respectively",".","Take","`","*","_fw","`","for","example",",","`","output_size_fw","`","is","a","(","possibly","nested","tuple","of",")","int",".","If","a","single","int","or","an","int","array",",","then","`","outputs_fw","`","has","shape","`","[","batch\/time",",","time\/batch","]","+","output_size_fw","`",".","If","a","(","nested",")","tuple",",","then","`","output_size_fw","`","has","the","same","structure","as","with","`","outputs_fw","`",".","The","same","applies","to","`","output_size_bw","`",".","-","If","both","`","return_cell_output","`","and","`","return_output_size","`","are","True",",","returns",":","attr",":","`","(","outputs",",","final_state",",","cell_outputs",",","output_size",")","`","."]
code: def _build(
      self,
      inputs,
      sequence_length=None,
      initial_state_fw=None,
      initial_state_bw=None,
      time_major=False,
      mode=None,
      return_cell_output=False,
      return_output_size=False,
      **kwargs,
  ):
      """Encodes the inputs.
  
          Args:
              inputs: A 3D Tensor of shape `[batch_size, max_time, dim]`.
                  The first two dimensions
                  `batch_size` and `max_time` may be exchanged if
                  `time_major=True` is specified.
              sequence_length (optional): A 1D int tensor of shape `[batch_size]`.
                  Sequence lengths
                  of the batch inputs. Used to copy-through state and zero-out
                  outputs when past a batch element's sequence length.
              initial_state (optional): Initial state of the RNN.
              time_major (bool): The shape format of the :attr:`inputs` and
                  :attr:`outputs` Tensors. If `True`, these tensors are of shape
                  `[max_time, batch_size, depth]`. If `False` (default),
                  these tensors are of shape `[batch_size, max_time, depth]`.
              mode (optional): A tensor taking value in
                  :tf_main:`tf.estimator.ModeKeys <estimator/ModeKeys>`, including
                  `TRAIN`, `EVAL`, and `PREDICT`. Controls output layer dropout
                  if the output layer is specified with :attr:`hparams`.
                  If `None` (default), :func:`texar.tf.global_mode()`
                  is used.
              return_cell_output (bool): Whether to return the output of the RNN
                  cell. This is the results prior to the output layer.
              **kwargs: Optional keyword arguments of
                  :tf_main:`tf.nn.dynamic_rnn <nn/dynamic_rnn>`,
                  such as `swap_memory`, `dtype`, `parallel_iterations`, etc.
  
          Returns:
              - By default (both `return_cell_output` and `return_output_size` \
              are False), returns a pair :attr:`(outputs, final_state)`
  
                  - :attr:`outputs`: A tuple `(outputs_fw, outputs_bw)` \
                  containing \
                  the forward and the backward RNN outputs, each of which is of \
                  shape `[batch_size, max_time, output_dim]` if \
                  `time_major` is False, or \
                  `[max_time, batch_size, output_dim]` if \
                  `time_major` is True. \
                  If RNN cell output is a (nested) tuple of Tensors, then \
                  `outputs_fw` and `outputs_bw` will be a (nested) tuple having \
                  the same structure as the cell output.
  
                  - :attr:`final_state`: A tuple \
                  `(final_state_fw, final_state_bw)` \
                  containing the final states of the forward and backward \
                  RNNs, each of which is a \
                  Tensor of shape `[batch_size] + cell.state_size`, or \
                  a (nested) tuple of Tensors if `cell.state_size` is a (nested)\
                  tuple.
  
              - If `return_cell_output` is True, returns a triple \
              :attr:`(outputs, final_state, cell_outputs)` where
  
                  - :attr:`cell_outputs`: A tuple \
                  `(cell_outputs_fw, cell_outputs_bw)` containting the outputs \
                  by the forward and backward RNN cells prior to the \
                  output layers, having the same structure with :attr:`outputs` \
                  except for the `output_dim`.
  
              - If `return_output_size` is True, returns a tuple \
              :attr:`(outputs, final_state, output_size)` where
  
                  - :attr:`output_size`: A tupple \
                  `(output_size_fw, output_size_bw)` containing the size of \
                  `outputs_fw` and `outputs_bw`, respectively. \
                  Take `*_fw` for example, \
                  `output_size_fw` is a (possibly nested tuple of) int. \
                  If a single int or an int array, then `outputs_fw` has shape \
                  `[batch/time, time/batch] + output_size_fw`. If \
                  a (nested) tuple, then `output_size_fw` has the same \
                  structure as with `outputs_fw`. The same applies to  \
                  `output_size_bw`.
  
              - If both `return_cell_output` and \
              `return_output_size` are True, returns \
              :attr:`(outputs, final_state, cell_outputs, output_size)`.
          """
      no_initial_state = (
          initial_state_fw is None and initial_state_bw is None
      )
      if ("dtype" not in kwargs) and no_initial_state:
          cell_outputs, states = tf.nn.bidirectional_dynamic_rnn(
              cell_fw=self._cell_fw,
              cell_bw=self._cell_bw,
              inputs=inputs,
              sequence_length=sequence_length,
              initial_state_fw=initial_state_fw,
              initial_state_bw=initial_state_bw,
              time_major=time_major,
              dtype=tf.float32,
              **kwargs,
          )
      else:
          cell_outputs, states = tf.nn.bidirectional_dynamic_rnn(
              cell_fw=self._cell_fw,
              cell_bw=self._cell_bw,
              inputs=inputs,
              sequence_length=sequence_length,
              initial_state_fw=initial_state_fw,
              initial_state_bw=initial_state_bw,
              time_major=time_major,
              **kwargs,
          )
  
      outputs_fw, output_size_fw = _apply_rnn_encoder_output_layer(
          self._output_layer_fw,
          time_major,
          self._output_layer_hparams_fw,
          mode,
          cell_outputs[0],
          self._cell_fw.output_size,
      )
  
      outputs_bw, output_size_bw = _apply_rnn_encoder_output_layer(
          self._output_layer_bw,
          time_major,
          self._output_layer_hparams_bw,
          mode,
          cell_outputs[1],
          self._cell_bw.output_size,
      )
  
      outputs = (outputs_fw, outputs_bw)
      output_size = (output_size_fw, output_size_bw)
  
      if not self._built:
          self._add_internal_trainable_variables()
          # Add trainable variables of cells and output layers
          # which may be constructed externally.
          self._add_trainable_variable(
              layers.get_rnn_cell_trainable_variables(self._cell_fw)
          )
          self._add_trainable_variable(
              layers.get_rnn_cell_trainable_variables(self._cell_bw)
          )
          if self._output_layer_fw and not isinstance(
              self._output_layer_fw, (list, tuple)
          ):
              self._add_trainable_variable(
                  self._output_layer_fw.trainable_variables
              )
          if self._output_layer_bw and not isinstance(
              self._output_layer_bw, (list, tuple)
          ):
              self._add_trainable_variable(
                  self._output_layer_bw.trainable_variables
              )
          self._built = True
  
      returns = (outputs, states)
      if return_cell_output:
          returns += (cell_outputs,)
      if return_output_size:
          returns += (output_size,)
      return returns
  
imports: import functools
  import numpy
  import tensorflow
  from tensorflow.contrib.framework import nest
  from texar.tf.modules.encoders.encoder_base import EncoderBase
  from texar.tf.modules.networks.conv_networks import _to_list
  from texar.tf.core import layers
  from texar.tf.utils.mode import is_train_mode
  from texar.tf.utils.shapes import mask_sequences
  from texar.tf.hyperparams import HParams
label_desc: Use image node_id 3 for calling the BidirectionalRNNEncoder obj's underlying member method code with example usage: obj._build(inputs, sequence_length, initial_state_fw, initial_state_bw, time_major, mode, return_cell_output, return_output_size) and returns: returns