Permutation
***********

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

Generalized Permutation Matrix
==============================

A general permutation matrix can be expressed as the multiplication of a permutation matrix and a diagonal matrix.
For instance, we can decompose a 4 :math:`\times` 4 general permutation matrix as follows:

.. math::
  A = \left[ \begin{array}{cccc}  & & a_0 & \\ a_1 & & & \\ & & & a_2 \\ & a_3 & & \end{array}\right] = 
  \left[ \begin{array}{cccc}  a_0 & &  & \\ & a_1 & & \\ & & a_2 & \\ & & & a_3 \end{array}\right] 
  \left[ \begin{array}{cccc}  & & 1 & \\ 1 & & & \\ & & & 1 \\ & 1 & & \end{array}\right].
  
cuStateVec API `custatevecApplyPermutationMatrix` applies a general permutation matrix like :math:`A` to a state vector.
The API may require external workspace for large matrices, 
and `custatevecApplyPermutationMatrix_bufferSize` provides the size of workspace.

Use case
--------

.. code-block:: cpp

  // check the size of external workspace
  custatevecApplyPermutationMatrix_bufferSize(
      handle, svDataType, permutation, diagonals, diagonalsDataType, adjoint,
      nTargets, &extraWorkspaceSizeInBytes);

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

  // perform permutation
  custatevecApplyPermutationMatrix(
      handle, sv, svDataType, nIndexBits, permutation, diagonals, 
      diagonalsDataType, adjoint, targets, nTargets, controls, nControls,
      extraWorkspace, extraWorkspaceSizeInBytes);

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

.. _custatevecApplyPermutationMatrix_bufferSize-label:

:code:`custatevecApplyPermutationMatrix_bufferSize`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecApplyPermutationMatrix_bufferSize

----

.. _custatevecApplyPermutationMatrix-label:

:code:`custatevecApplyPermutationMatrix`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecApplyPermutationMatrix

Swap of qubits
==============

.. _custatevecSwapIndexBits-label:

:code:`custatevecSwapIndexBits`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::

   This API is not available in this version.

.. doxygenfunction:: custatevecSwapIndexBits