.. _onemkl_blas_iamax:

iamax
=====

Finds the index of the element with the largest absolute value in a
vector.

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

The ``iamax`` routines return an index ``i`` such that ``x[i]``
has the maximum absolute value of all elements in vector ``x`` (real
variants), or such that (\|Re(``x[i]``)\| + \|Im(``x[i]``)\|) is maximal
(complex variants).

``iamax`` supports the following precisions:

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

   * -  T
   * -  ``float``
   * -  ``double``
   * -  ``std::complex<float>``
   * -  ``std:complex<double>``

.. note::
   The index is zero-based.

   If either ``n`` or ``incx`` are not positive, the routine returns ``0``.

   If more than one vector element is found with the same largest 
   absolute value, the index of the first one encountered is returned.

   If the vector contains ``NaN`` values, then the routine returns the 
   index of the first ``NaN``.


iamax (Buffer Version)
**********************

Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::blas::column_major {
       void iamax(sycl::queue &queue,
                  std::int64_t n,
                  sycl::buffer<T, 1> &x,
                  std::int64_t incx,
                  sycl::buffer<std::int64_t, 1> &result)
   }

.. code-block:: cpp

   namespace oneapi::mkl::blas::row_major {
       void iamax(sycl::queue &queue,
                  std::int64_t n,
                  sycl::buffer<T, 1> &x,
                  std::int64_t incx,
                  sycl::buffer<std::int64_t, 1> &result)
   }

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

exec_queue
   The queue where the routine should be executed.

n
   The number of elements in vector ``x``.

x
   The buffer that holds the input vector ``x``. Size of the buffer must be 
   at least (1 + (``n`` - 1)\*abs(``incx``)). See :ref:`matrix-storage` for more details. 

incx
   The stride of vector ``x``.

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

result
   The buffer where the zero-based index ``i`` of the maximal element
   is stored.

Examples
********

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

.. code-block::

   examples/dpcpp/blas/source/iamax.cpp


iamax (USM Version)
**********************

Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::blas::column_major {
       sycl::event iamax(sycl::queue &queue,
                         std::int64_t n,
                         const T *x,
                         std::int64_t incx,
                         T_res *result,
                         const std::vector<sycl::event> &dependencies = {})
   }

.. code-block:: cpp

   namespace oneapi::mkl::blas::row_major {
       sycl::event iamax(sycl::queue &queue,
                         std::int64_t n,
                         const T *x,
                         std::int64_t incx,
                         T_res *result,
                         const std::vector<sycl::event> &dependencies = {})
   }

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

queue
   The queue where the routine should be executed.

n
   The number of elements in vector ``x``.

x
   The pointer to input vector ``x``. Size of the array holding input
   vector ``x`` must be at least (1 + (``n`` - 1)\*abs(``incx``)). See :ref:`matrix-storage` for more details.

incx
   The stride of vector ``x``.

dependencies
   List of events to wait for before starting computation, if any. If
   omitted, defaults to no dependencies.

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

result
   The pointer to where the zero-based index ``i`` of the maximal
   element is stored.

Return Values
-------------

Output event to wait on to ensure computation is complete.