class_docstr: Sinusoid position embedder that maps position indexes into embeddings
  via sinusoid calculation. This module does not have trainable parameters.
  Used in, e.g., Transformer models
  `(Vaswani et al.) "Attention Is All You Need"`.
  
  Each channel of the input Tensor is incremented by a sinusoid of a
  different frequency and phase.
  This allows attention to learn to use absolute and relative positions.
  
  Timing signals should be added to some precursors of both the query
  and the memory inputs to attention.
  The use of relative position is possible because `sin(x+y)` and
  `cos(x+y)` can be expressed in terms of `y`, `sin(x)`, and `cos(x)`.
  In particular, we use a geometric sequence of timescales starting with
  min_timescale and ending with max_timescale.  The number of different
  timescales is equal to ``dim / 2``. For each timescale, we
  generate the two sinusoidal signals `sin(timestep/timescale)` and
  `cos(timestep/timescale)`.  All of these sinusoids are concatenated in
  the dim dimension.
  
  Args:
      position_size (int): The number of possible positions, e.g., the maximum
          sequence length. Set ``position_size=None`` and
          ``hparams['cache_embeddings']=False`` to enable infinite large or
          negative position indexes.
  
  .. document private functions
  .. automethod:: _build
class_docstr_tok: ["Sinusoid","position","embedder","that","maps","position","indexes","into","embeddings","via","sinusoid","calculation",".","This","module","does","not","have","trainable","parameters",".","Used","in",",","e.g.",",","Transformer","models","`","(","Vaswani","et","al",".",")","``","Attention","Is","All","You","Need","''","`",".","Each","channel","of","the","input","Tensor","is","incremented","by","a","sinusoid","of","a","different","frequency","and","phase",".","This","allows","attention","to","learn","to","use","absolute","and","relative","positions",".","Timing","signals","should","be","added","to","some","precursors","of","both","the","query","and","the","memory","inputs","to","attention",".","The","use","of","relative","position","is","possible","because","`","sin","(","x+y",")","`","and","`","cos","(","x+y",")","`","can","be","expressed","in","terms","of","`","y","`",",","`","sin","(","x",")","`",",","and","`","cos","(","x",")","`",".","In","particular",",","we","use","a","geometric","sequence","of","timescales","starting","with","min_timescale","and","ending","with","max_timescale",".","The","number","of","different","timescales","is","equal","to","``","dim","\/","2","``",".","For","each","timescale",",","we","generate","the","two","sinusoidal","signals","`","sin","(","timestep\/timescale",")","`","and","`","cos","(","timestep\/timescale",")","`",".","All","of","these","sinusoids","are","concatenated","in","the","dim","dimension",".","Args",":","position_size","(","int",")",":","The","number","of","possible","positions",",","e.g.",",","the","maximum","sequence","length",".","Set","``","position_size=None","``","and","``","hparams","[","'cache_embeddings","'","]","=False","``","to","enable","infinite","large","or","negative","position","indexes",".","..","document","private","functions","..","automethod",":",":","_build"]
docstr: Embeds.
  Either :attr:`positions` or :attr:`sequence_length` is required:
  
  - If both are given, :attr:`sequence_length` is used to mask out
    embeddings of those time steps beyond the respective sequence \
    lengths.
  - If only :attr:`sequence_length` is given, then positions
    from `0` to `sequence_length-1` are embedded.
  
  Args:
      positions (optional): An integer tensor containing the position
          ids to embed.
      sequence_length (optional): An integer tensor of shape
          ``[batch_size]``. Time steps beyond
          the respective sequence lengths will have zero-valued
          embeddings.
  
  Returns:
      A Tensor of shape ``[batch_size, max_time, dim]``.
docstr_tok: ["Embeds",".","Either",":","attr",":","`","positions","`","or",":","attr",":","`","sequence_length","`","is","required",":","-","If","both","are","given",",",":","attr",":","`","sequence_length","`","is","used","to","mask","out","embeddings","of","those","time","steps","beyond","the","respective","sequence","\\","lengths",".","-","If","only",":","attr",":","`","sequence_length","`","is","given",",","then","positions","from","`","0","`","to","`","sequence_length-1","`","are","embedded",".","Args",":","positions","(","optional",")",":","An","integer","tensor","containing","the","position","ids","to","embed",".","sequence_length","(","optional",")",":","An","integer","tensor","of","shape","``","[","batch_size","]","``",".","Time","steps","beyond","the","respective","sequence","lengths","will","have","zero-valued","embeddings",".","Returns",":","A","Tensor","of","shape","``","[","batch_size",",","max_time",",","dim","]","``","."]
code: def _build(self, positions=None, sequence_length=None):
      r"""Embeds.
          Either :attr:`positions` or :attr:`sequence_length` is required:
  
          - If both are given, :attr:`sequence_length` is used to mask out
            embeddings of those time steps beyond the respective sequence \
            lengths.
          - If only :attr:`sequence_length` is given, then positions
            from `0` to `sequence_length-1` are embedded.
  
          Args:
              positions (optional): An integer tensor containing the position
                  ids to embed.
              sequence_length (optional): An integer tensor of shape
                  ``[batch_size]``. Time steps beyond
                  the respective sequence lengths will have zero-valued
                  embeddings.
  
          Returns:
              A Tensor of shape ``[batch_size, max_time, dim]``.
          """
      if positions is None:
          if sequence_length is None:
              raise ValueError(
                  "Either `positions` or `sequence_length` is required."
              )
          max_length = tf.reduce_max(sequence_length)
          single_inputs = tf.range(
              start=0, limit=max_length, dtype=tf.int32
          )
          # Expands `single_inputs` to have shape [batch_size, max_length]
          expander = tf.expand_dims(tf.ones_like(sequence_length), -1)
          inputs = expander * tf.expand_dims(single_inputs, 0)
      else:
          inputs = positions
  
      if self._cache_embeddings:
          outputs = tf.nn.embedding_lookup(self.signal, inputs)
      else:
          outputs = self._compute_embeddings(inputs)
  
      return outputs
  
imports: import math
  import tensorflow
  from texar.tf.modules.embedders.embedder_base import EmbedderBase
  from texar.tf.modules.embedders import embedder_utils
  from texar.tf.utils.mode import is_train_mode
  from texar.tf.utils.shapes import mask_sequences
  from texar.tf.utils.shapes import shape_list
label_desc: Use image node_id 4 for calling the SinusoidsPositionEmbedder obj's underlying member method code with example usage: obj._build(positions, sequence_length) and returns: outputs