parameters: (a, shift, axis=None)
docstring: Roll array elements along a given axis.
  
      Elements that roll beyond the last position are re-introduced at
      the first.
  
      Parameters
      ----------
      a : array_like
          Input array.
      shift : int or tuple of ints
          The number of places by which elements are shifted.  If a tuple,
          then `axis` must be a tuple of the same size, and each of the
          given axes is shifted by the corresponding number.  If an int
          while `axis` is a tuple of ints, then the same value is used for
          all given axes.
      axis : int or tuple of ints, optional
          Axis or axes along which elements are shifted.  By default, the
          array is flattened before shifting, after which the original
          shape is restored.
  
      Returns
      -------
      res : ndarray
          Output array, with the same shape as `a`.
  
      See Also
      --------
      rollaxis : Roll the specified axis backwards, until it lies in a
                 given position.
  
      Notes
      -----
      .. versionadded:: 1.12.0
  
      Supports rolling over multiple dimensions simultaneously.
  
      Examples
      --------
      >>> x = np.arange(10)
      >>> np.roll(x, 2)
      array([8, 9, 0, 1, 2, 3, 4, 5, 6, 7])
      >>> np.roll(x, -2)
      array([2, 3, 4, 5, 6, 7, 8, 9, 0, 1])
  
      >>> x2 = np.reshape(x, (2,5))
      >>> x2
      array([[0, 1, 2, 3, 4],
             [5, 6, 7, 8, 9]])
      >>> np.roll(x2, 1)
      array([[9, 0, 1, 2, 3],
             [4, 5, 6, 7, 8]])
      >>> np.roll(x2, -1)
      array([[1, 2, 3, 4, 5],
             [6, 7, 8, 9, 0]])
      >>> np.roll(x2, 1, axis=0)
      array([[5, 6, 7, 8, 9],
             [0, 1, 2, 3, 4]])
      >>> np.roll(x2, -1, axis=0)
      array([[5, 6, 7, 8, 9],
             [0, 1, 2, 3, 4]])
      >>> np.roll(x2, 1, axis=1)
      array([[4, 0, 1, 2, 3],
             [9, 5, 6, 7, 8]])
      >>> np.roll(x2, -1, axis=1)
      array([[1, 2, 3, 4, 0],
             [6, 7, 8, 9, 5]])
docstring_summary: Roll array elements along a given axis.
docstring_tokens: Roll array elements along a given axis .
function: def roll(a, shift, axis=None):
      """
      Roll array elements along a given axis.
  
      Elements that roll beyond the last position are re-introduced at
      the first.
  
      Parameters
      ----------
      a : array_like
          Input array.
      shift : int or tuple of ints
          The number of places by which elements are shifted.  If a tuple,
          then `axis` must be a tuple of the same size, and each of the
          given axes is shifted by the corresponding number.  If an int
          while `axis` is a tuple of ints, then the same value is used for
          all given axes.
      axis : int or tuple of ints, optional
          Axis or axes along which elements are shifted.  By default, the
          array is flattened before shifting, after which the original
          shape is restored.
  
      Returns
      -------
      res : ndarray
          Output array, with the same shape as `a`.
  
      See Also
      --------
      rollaxis : Roll the specified axis backwards, until it lies in a
                 given position.
  
      Notes
      -----
      .. versionadded:: 1.12.0
  
      Supports rolling over multiple dimensions simultaneously.
  
      Examples
      --------
      >>> x = np.arange(10)
      >>> np.roll(x, 2)
      array([8, 9, 0, 1, 2, 3, 4, 5, 6, 7])
      >>> np.roll(x, -2)
      array([2, 3, 4, 5, 6, 7, 8, 9, 0, 1])
  
      >>> x2 = np.reshape(x, (2,5))
      >>> x2
      array([[0, 1, 2, 3, 4],
             [5, 6, 7, 8, 9]])
      >>> np.roll(x2, 1)
      array([[9, 0, 1, 2, 3],
             [4, 5, 6, 7, 8]])
      >>> np.roll(x2, -1)
      array([[1, 2, 3, 4, 5],
             [6, 7, 8, 9, 0]])
      >>> np.roll(x2, 1, axis=0)
      array([[5, 6, 7, 8, 9],
             [0, 1, 2, 3, 4]])
      >>> np.roll(x2, -1, axis=0)
      array([[5, 6, 7, 8, 9],
             [0, 1, 2, 3, 4]])
      >>> np.roll(x2, 1, axis=1)
      array([[4, 0, 1, 2, 3],
             [9, 5, 6, 7, 8]])
      >>> np.roll(x2, -1, axis=1)
      array([[1, 2, 3, 4, 0],
             [6, 7, 8, 9, 5]])
  
      """
      a = asanyarray(a)
      if axis is None:
          return roll(a.ravel(), shift, 0).reshape(a.shape)
  
      else:
          axis = normalize_axis_tuple(axis, a.ndim, allow_duplicate=True)
          broadcasted = broadcast(shift, axis)
          if broadcasted.ndim > 1:
              raise ValueError(
                  "'shift' and 'axis' should be scalars or 1D sequences")
          shifts = {ax: 0 for ax in range(a.ndim)}
          for sh, ax in broadcasted:
              shifts[ax] += sh
  
          rolls = [((slice(None), slice(None)),)] * a.ndim
          for ax, offset in shifts.items():
              offset %= a.shape[ax] or 1  # If `a` is empty, nothing matters.
              if offset:
                  # (original, result), (original, result)
                  rolls[ax] = ((slice(None, -offset), slice(offset, None)),
                               (slice(-offset, None), slice(None, offset)))
  
          result = empty_like(a)
          for indices in itertools.product(*rolls):
              arr_index, res_index = zip(*indices)
              result[res_index] = a[arr_index]
  
          return result
function_tokens: def roll ( a , shift , axis = None ) : a = asanyarray ( a ) if axis is None : return roll ( a . ravel ( ) , shift , 0 ) . reshape ( a . shape ) else : axis = normalize_axis_tuple ( axis , a . ndim , allow_duplicate = True ) broadcasted = broadcast ( shift , axis ) if broadcasted . ndim > 1 : raise ValueError ( "'shift' and 'axis' should be scalars or 1D sequences" ) shifts = { ax : 0 for ax in range ( a . ndim ) } for sh , ax in broadcasted : shifts [ ax ] += sh rolls = [ ( ( slice ( None ) , slice ( None ) ) , ) ] * a . ndim for ax , offset in shifts . items ( ) : offset %= a . shape [ ax ] or 1 # If `a` is empty, nothing matters. if offset : # (original, result), (original, result) rolls [ ax ] = ( ( slice ( None , - offset ) , slice ( offset , None ) ) , ( slice ( - offset , None ) , slice ( None , offset ) ) ) result = empty_like ( a ) for indices in itertools . product ( * rolls ) : arr_index , res_index = zip ( * indices ) result [ res_index ] = a [ arr_index ] return result