.. _fmod:

fmod
====


Computes the element-wise remainder of vector ``a`` elements divided by vector ``b`` elements that has the same sign as vector ``a`` elements.


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

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

The ``fmod (a,b)`` function computes the modulus function of each element of vector ``a``, with respect to the corresponding elements of vector ``b``:


``ai - bi*trunc(ai/bi)``


In general, the modulus function ``fmod (ai, bi)`` returns the value
``ai - n*bi`` for some integer ``n`` such that if ``b``\ :sub:`i` is
nonzero, the result has the same sign as ``a``\ :sub:`i` and a
magnitude less than the magnitude of ``b``\ :sub:`i`.

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

   * -  Argument 1
     -  Argument 2
     -  Result
     -  Error Code
   * -  ``a`` not NAN
     -  ±0
     -  NAN
     -  ``status::sing``
   * -  ±\ :math:`\infty`
     -  ``b`` not NAN
     -  NAN
     -  ``status::sing``
   * -  ±0
     -  ``b``\ ≠ 0, not NAN
     -  ±0
     -   
   * -  ``a`` finite
     -  ±\ :math:`\infty`
     -  ``a``
     -   
   * -  NAN
     -  ``b``
     -   
     -   
   * -  ``a``
     -  NAN
     -  NAN
     -   


API
***


Syntax
------

**Buffer API**


.. code-block:: cpp

   namespace oneapi::mkl::vm {

   sycl::event fmod(sycl::queue & exec_queue,
         std::int64_t n,
         sycl::buffer<T> & a,
         sycl::buffer<T> & b,
         sycl::buffer<T> & y,
         oneapi::mkl::vm::mode mode = oneapi::mkl::vm::mode::not_defined,
         oneapi::mkl::vm::error_handler<T> errhandler = {});

   }

.. code-block:: cpp

   namespace oneapi::mkl::vm {

   sycl::event fmod(sycl::queue & exec_queue,
         sycl::buffer<T> & a,
         oneapi::mkl::slice sa,
         sycl::buffer<T> & b,
         oneapi::mkl::slice sb,
         sycl::buffer<T> & y,
         oneapi::mkl::slice sy,
         oneapi::mkl::vm::mode mode = oneapi::mkl::vm::mode::not_defined,
         oneapi::mkl::vm::error_handler<T> errhandler = {});

   }

**USM API**

.. code-block:: cpp

   namespace oneapi::mkl::vm {

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

   }

.. code-block:: cpp

   namespace oneapi::mkl::vm {

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

   }


``fmod`` 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 1st input vector.


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


b
   The buffer containing the 2nd input vector.


sb
   Slice selector for ``b``. 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``.


errhandler
   Sets local error handling mode for this function call. See the
   :ref:`create_error_handler` function for arguments and their descriptions. This is an optional parameter. The local error handler is disabled by default.


**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 1st input vector.


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


b
   Pointer to the 2nd input vector.


sb
   Slice selector for ``b``. 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
   Vector of dependent events (to wait for input data to be ready).


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``.


errhandler
   Sets local error handling mode for this function call. See the
   :ref:`create_error_handler` function for arguments and their descriptions. This is an optional parameter. The local error handler is disabled by default.


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

**Buffer API**

y
   The buffer containing the output vector of size ``n``.


return value (event)
   Computation end event.


**USM API**


y
   Pointer to the output vector of size ``n``.


return value (event)
   Computation end event.


Examples
********

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


.. code-block::


   examples/dpcpp/vml/source/vfmod.cpp