.. _cbrt:

cbrt
====

Computes the element-wise cube root of vector elements.


.. contents::
    :local:
    :depth: 1

Description
***********

The ``cbrt(a)`` function computes a cube root of vector elements.

.. list-table::
   :header-rows: 1

   * -  Argument
     -  Result
     -  Error Code
   * -  +0
     -  +0
     -
   * -  -0
     -  -0
     -
   * -  +\ :math:`\infty`
     -  +\ :math:`\infty`
     -
   * -  -\ :math:`\infty`
     -  -\ :math:`\infty`
     -
   * -  QNAN
     -  QNAN
     -
   * -  SNAN
     -  QNAN
     -
   * -  +0
     -  +0
     -


API
***


Syntax
------

**Buffer API**

.. code-block:: cpp

   namespace oneapi::mkl::vm {

   sycl::event cbrt(sycl::queue & exec_queue,
         std::int64_t n,
         sycl::buffer<T> & a,
         sycl::buffer<T> & y,
         oneapi::mkl::vm::mode mode = oneapi::mkl::vm::mode::not_defined);

   }

.. code-block:: cpp

   namespace oneapi::mkl::vm {

   sycl::event cbrt(sycl::queue & exec_queue,
         sycl::buffer<T> & a,
         oneapi::mkl::slice sa,
         sycl::buffer<T> & y,
         oneapi::mkl::slice sy,
         oneapi::mkl::vm::mode mode = oneapi::mkl::vm::mode::not_defined);

   }

**USM API**

.. code-block:: cpp

   namespace oneapi::mkl::vm {

   sycl::event cbrt(sycl::queue & exec_queue,
         std::int64_t n,
         T const * a,
         T * y,
         std::vector<cl::sycl::event> const & depends = {},
         oneapi::mkl::vm::mode mode = oneapi::mkl::vm::mode::not_defined);

     }

.. code-block:: cpp

   namespace oneapi::mkl::vm {

   sycl::event cbrt(sycl::queue & exec_queue,
         T const * a,
         oneapi::mkl::slice sa,
         T * y,
         oneapi::mkl::slice sy,
         std::vector<cl::sycl::event> const & depends = {},
         oneapi::mkl::vm::mode mode = oneapi::mkl::vm::mode::not_defined);

     }



``cbrt`` supports the following precisions and devices:


.. list-table::
   :header-rows: 1

   * -  T
     -  Devices supported
   * -  ``float``
     -  Host, CPU, and GPU
   * -  ``double``
     -  Host, CPU, and GPU


Input Parameters
----------------

**Buffer API**


exec_queue
   The queue where the routine should be executed.


n
   Specifies the number of elements to be calculated.


a
   The buffer containing the input vector.


sa
   Slice selector for ``a``. See :ref:`data-types` for a description of the |O-MKL| slice type.


sy
   Slice selector for ``y``. See :ref:`data-types` for a description of the |O-MKL| slice type.


mode
   Overrides the global VM mode setting for this function call. See :ref:`set_mode` function for possible values and their description. This is an optional parameter. The default value is ``mode::not_defined``.


**USM API**


exec_queue
   The queue where the routine should be executed.


n
   Specifies the number of elements to be calculated.


a
   Pointer to the input vector.


sa
   Slice selector for ``a``. See :ref:`data-types` for a description of the |O-MKL| slice type.


sy
   Slice selector for ``y``. See :ref:`data-types` for a description of the |O-MKL| slice type.


depends
   Pointer to the input vector.


mode
   Overrides the global VM mode setting for this function call. See the :ref:`set_mode` function for possible values and their description. This is an optional parameter. The default value is ``mode::not_defined``.


Output Parameters
-----------------

**Buffer API**


y
   The buffer containing the output vector.


return value (event)
   Computation end event.


**USM API**


y
   Pointer to the output vector.


return value (event)
   Computation end event.


Examples
********

An example of how to use ``cbrt`` can be found in the |O-MKL|
installation directory, under:

.. code-block::

   examples/dpcpp/vml/source/vcbrt.cpp