Gate Application 
****************

.. role::  raw-html(raw)
    :format: html

General Matrices
================

cuStateVec API `custatevecApplyMatrix` can apply a matrix representing a gate to a state vector.
The API may require external workspace for large matrices, 
and `custatevecApplyMatrix_bufferSize` provides the size of workspace.

Use case
--------

.. code-block:: cpp

  // check the size of external workspace
  custatevecApplyMatrix_bufferSize(
      handle, svDataType, matrix, matrixDataType, layout, adjoint, nTargets, 
      computeType, &extraWorkspaceSizeInBytes);

  // allocate external workspace if necessary
  void extraWorkspace = nullptr;
  if (extraWorkspaceSizeInBytes > 0)
      cudaMalloc(extraWorkspace, extraWorkspaceSizeInBytes);

  // apply gate
  custatevecApplyMatrix(
      handle, sv, svDataType, nIndexBits, matrix, matrixDataType, layout,
      adjoint, targets, nTargets, controls, nControls, computeType,
      extraWorkspace, extraWorkspaceSizeInBytes);

API reference
-------------

.. _custatevecApplyMatrix_bufferSize-label:

:code:`custatevecApplyMatrix_bufferSize`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecApplyMatrix_bufferSize

----

.. _custatevecApplyMatrix-label:

:code:`custatevecApplyMatrix`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecApplyMatrix


Pauli Matrices
==============

Exponential of a tensor product of Pauli matrices can be expressed as follows:

.. math::
  e^{i \theta \left( P_{target[0]} \otimes P_{target[1]} \otimes \cdots \otimes P_{target[nTargets-1]} \right)}.

Matrix :math:`P_{target[i]}` can be either of the followings:

.. math::
  I = \left[ \begin{array}{rr} 1 & 0 \\ 0 & 1 \end{array}\right]`, 
  X = \left[ \begin{array}{rr} 0 & 1 \\ 1 & 0 \end{array}\right]`, 
  Y = \left[ \begin{array}{rr} 0 & -i \\ i & 0 \end{array}\right]`, 
  Z = \left[ \begin{array}{rr} 1 & 0 \\ 0 & -1 \end{array}\right]`.

Use case
--------

.. code-block:: cpp

  // apply exponential
  custatevecApplyExp(
      handle, sv, svDataType, nIndexBits, theta, paulis, targets, nTargets,
      controls, nControls);

API reference
-------------

.. _custatevecApplyExp-label:

:code:`custatevecApplyExp`
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: custatevecApplyExp


Diagonal Matrices
=================

.. _custatevecApplyDiagonalMatrix-label:

:code:`custatevecApplyDiagonalMatrix`
-------------------------------------

.. note::

   This API is not available in this version. 

.. doxygenfunction:: custatevecApplyDiagonalMatrix


Matrix Tests
============

cuStateVec API `custatevecTestMatrixType` can check if a given matrix is unitary or Hermitian.
The API may require external workspace for large matrices, 
and `custatevecTestMatrixType_bufferSize` provides the size of workspace.

Use case
--------

.. code-block:: cpp

  // check the size of external workspace
  custatevecTestMatrixType_bufferSize(
      handle, matrixType, matrix, matrixDataType, layout, nRows, nCols, adjoint,
      computeType, &extraWorkspaceSizeInBytes);

  // allocate external workspace if necessary
  void extraWorkspace = nullptr;
  if (extraWorkspaceSizeInBytes > 0)
      cudaMalloc(extraWorkspace, extraWorkspaceSizeInBytes);

  // perform testing
  custatevecTestMatrixType(
      handle, residualNorm, matrixType, matrix, matrixDataType, layout, nRows, 
      nCols, adjoint, computeType, extraWorkspace, extraWorkspaceSizeInBytes);

API reference
-------------

.. _custatevecTestMatrixType_bufferSize-label:

:code:`custatevecTestMatrixType_bufferSize`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecTestMatrixType_bufferSize

----

.. _custatevecTestMatrixType-label:

:code:`custatevecTestMatrixType`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecTestMatrixType