.. _set_mode:

set_mode
========


Sets a new mode for VM functions according to the ``mode`` parameter and
returns the previous VM mode.


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

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

The ``set_mode`` function sets a new mode for VM functions according to the ``new_mode`` parameter and returns the previous VM mode. The mode change has a global effect on all the VM functions within a queue.

|O-MKL| VM mode parameters provide control on the accuracy of mathematical functions, and on |O-MKL| VM Strided API behavior. The mode set for a given queue can be overridden locally by the local mode parameter in a VM function call.

The mode value is a bitwise OR (|) combination of the values described in the following table.

.. tabularcolumns:: |\Y{0.4}|\Y{0.6}|

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

   * -  Value
     -  Description
   * -  Accuracy Control
     -
   * -  ``oneapi::mkl::vm::mode::ha``
     -  High accuracy versions of VM functions. (DEFAULT)
   * -  ``oneapi::mkl::vm::mode::la``
     -  Low accuracy versions of VM functions.
   * -  ``oneapi::mkl::vm::mode::ep``
     -  Enhanced performance accuracy versions of VM functions.
   * -  Slice Argument Checking
     -
   * -  ``oneapi::mkl::vm::mode::badarg_exception``
     -  Throw a ``oneapi::mkl::invalid_argument`` exception on invalid arguments. (DEFAULT)
   * -  ``oneapi::mkl::vm::mode::badarg_quiet``
     -  Invalid arguments quietly make the call a "no-op". The VM status is set to ``vm::status::empty_computation``.
   * -  Slice Indexing Controls
     -
   * -  ``oneapi::mkl::vm::mode::slice_normal``
     -  Non-equal slice sizes are considered invalid. (DEFAULT)
   * -  ``oneapi::mkl::vm::mode::slice_minimum``
     -  The minimum of all slice sizes defines the number of evaluations.
   * -  ``oneapi::mkl::vm::mode::slice_cyclic``
     -  The output slice(s) size defines the number of evaluations. Input slices wrap around from the start.
   * -  Default Local Mode
     -
   * -  ``oneapi::mkl::vm::mode::not_defined``
     -  VM mode not defined. This has no effect.

The default value if no VM mode is defined or if the VM mode value is set to ``mode::not_defined`` is (``mode::badarg_exception`` | ``mode::slice_normal`` | ``mode::ha``).


API
***


Syntax
------

.. code-block:: cpp

   uint64_t set_mode(queue& exec_queue, uint64_t   new_mode )

``set_mode`` supports the following devices: Host, CPU, and GPU.


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

exec_queue
   The queue where the routine should be executed.


new_mode
   Specifies the VM mode to be set.


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

return value (old_mode)
   Specifies the former VM mode.


Examples
********

.. code-block::

   oldmode = set_mode (exec_queue , mode::la);
   oldmode = set_mode (exec_queue , mode::ep | mode::ftzdazon);