cuStateVec Functions
####################

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


Library Management
******************

Handle Management API
=====================

.. _custatevecCreate-label:

:code:`custatevecCreate`
------------------------

.. doxygenfunction:: custatevecCreate

----

.. _custatevecDestroy-label:

:code:`custatevecDestroy`
-------------------------

.. doxygenfunction:: custatevecDestroy

----

.. _custatevecGetDefaultWorkspaceSize-label:

:code:`custatevecGetDefaultWorkspaceSize`
-----------------------------------------

.. doxygenfunction:: custatevecGetDefaultWorkspaceSize

----

.. _custatevecSetWorkspace-label:

:code:`custatevecSetWorkspace`
-------------------------------------

.. doxygenfunction:: custatevecSetWorkspace


CUDA Stream Management API
==========================

.. _custatevecSetStream-label:

:code:`custatevecSetStream`
---------------------------

.. doxygenfunction:: custatevecSetStream

----

.. _custatevecGetStream-label:

:code:`custatevecGetStream`
---------------------------

.. doxygenfunction:: custatevecGetStream

Error Management API
====================

.. _custatevecGetErrorName-label:

:code:`custatevecGetErrorName`
------------------------------

.. doxygenfunction:: custatevecGetErrorName

----

.. _custatevecGetErrorString-label:

:code:`custatevecGetErrorString`
------------------------------

.. doxygenfunction:: custatevecGetErrorString

Logger API
==========

.. _custatevecLoggerSetCallback-label:

:code:`custatevecLoggerSetCallback`
-----------------------------------

.. doxygenfunction:: custatevecLoggerSetCallback

----

.. _custatevecLoggerSetFile-label:

:code:`custatevecLoggerSetFile`
-------------------------------

.. doxygenfunction:: custatevecLoggerSetFile

----

.. _custatevecLoggerOpenFile-label:

:code:`custatevecLoggerOpenFile`
--------------------------------

.. doxygenfunction:: custatevecLoggerOpenFile

----

.. _custatevecLoggerSetLevel-label:

:code:`custatevecLoggerSetLevel`
--------------------------------

.. doxygenfunction:: custatevecLoggerSetLevel

----

.. _custatevecLoggerSetMask-label:

:code:`custatevecLoggerSetMask`
-------------------------------

.. doxygenfunction:: custatevecLoggerSetMask

----

.. _custatevecLoggerForceDisable-label:

:code:`custatevecLoggerForceDisable`
------------------------------------

.. doxygenfunction:: custatevecLoggerForceDisable


Versioning API
==============

.. _custatevecGetProperty-label:

:code:`custatevecGetProperty`
-----------------------------

.. doxygenfunction:: custatevecGetProperty

----

.. _custatevecGetVersion-label:

:code:`custatevecGetVersion`
-----------------------------

.. doxygenfunction:: custatevecGetVersion


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

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, nIndexBits, matrix, matrixDataType, layout, adjoint, nTargets, 
      nControls, 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, controlBitValues,
      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 Pauli matrices :math:`I`, :math:`X`, :math:`Y`, and :math:`Z`, which are corresponding to the `custatevecPauli_t` enums `CUSTATEVEC_PAULI_I`, `CUSTATEVEC_PAULI_X`, `CUSTATEVEC_PAULI_Y`, and `CUSTATEVEC_PAULI_Z`, respectively. 
Also refer to :ref:`custatevecPauli_t<custatevecPauli_t-label>` for details.

Use case
--------

.. code-block:: cpp

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

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

.. _custatevecApplyExp-label:

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


Measurement
***********

Measurement on Z-bases
======================

Let us consider the measurement of an :math:`nIndexBits`-qubit state vector :math:`sv` on an :math:`nBasisBits`-bit Z product basis :math:`basisBits`.

The sums of squared absolute values of state vector elements on the Z product basis, :math:`abs2sum0` and :math:`abs2sum1`, are obtained by the followings:

.. math::

  abs2sum0 &= \Bra{sv} \left\{ \dfrac{1}{2} \left( 1 + Z_{basisBits[0]} \otimes Z_{basisBits[1]} \otimes \cdots \otimes Z_{basisBits[nBasisBits-1]} \right) \right\} \Ket{sv}, \\
  abs2sum1 &= \Bra{sv} \left\{ \dfrac{1}{2} \left( 1 - Z_{basisBits[0]} \otimes Z_{basisBits[1]} \otimes \cdots \otimes Z_{basisBits[nBasisBits-1]} \right) \right\} \Ket{sv}. 

Therefore, probabilities to obtain parity 0 and 1 are expressed in the following expression:

.. math::

  Pr(parity = 0) &= \dfrac{abs2sum0}{abs2sum0 + abs2sum1}, \\
  Pr(parity = 1) &= \dfrac{abs2sum1}{abs2sum0 + abs2sum1}.

Depending on the measurement result, the state vector is collapsed.
If parity is equal to 0, we obtain the following vector:

.. math::

  \ket{sv} = \dfrac{1}{\sqrt{norm}} \left\{ \dfrac{1}{2} \left( 1 + Z_{basisBits[0]} \otimes Z_{basisBits[1]} \otimes \cdots \otimes Z_{basisBits[nBasisBits-1]} \right) \right\} \Ket{sv},

and if parity is equal to 1, we obtain the following vector:

.. math::
  \ket{sv} = \dfrac{1}{\sqrt{norm}} \left\{ \dfrac{1}{2} \left( 1 - Z_{basisBits[0]} \otimes Z_{basisBits[1]} \otimes \cdots \otimes Z_{basisBits[nBasisBits-1]} \right) \right\} \Ket{sv},

where :math:`norm` is the normalization factor.

Use case
--------

We can measure by `custatevecMeasureOnZBasis` as follows:

.. code-block:: cpp
 
  // measure on a Z basis
  custatevecMeasureOnZBasis(
      handle, sv, svDataType, nIndexBits, &parity, basisBits, nBasisBits, 
      randnum, collapse);

The operation is equivalent to the following:

.. code-block:: cpp

  // compute the sums of squared absolute values of state vector elements 
  // on a Z product basis
  double abs2sum0, abs2sum1;
  custatevecAbs2SumOnZBasis(
      handle, sv, svDataType, nIndexBits, &abs2sum0, &abs2sum1, basisBits,
      nBasisBits);

  // [User] compute parity and norm
  double abs2sum = abs2sum0 + abs2sum1;
  int parity = (randnum * abs2sum < abs2sum0) ? 0 : 1;
  double norm = (parity == 0) ? abs2sum0 : abs2sum1;

  // collapse if necessary
  switch (collapse) {
  case CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO:
      custatevecCollapseOnZBasis(
          handle, sv, svDataType, nIndexBits, parity, basisBits, nBasisBits, 
          norm);
      break;  /* collapse */
  case CUSTATEVEC_COLLAPSE_NONE:
      break;  /* Do nothing */

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

.. _custatevecAbs2SumOnZBasis-label:

:code:`custatevecAbs2SumOnZBasis`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecAbs2SumOnZBasis

----

.. _custatevecCollapseOnZBasis-label:

:code:`custatevecCollapseOnZBasis`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecCollapseOnZBasis

----

.. _custatevecMeasureOnZBasis-label:

:code:`custatevecMeasureOnZBasis`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecMeasureOnZBasis


Batched Single Qubit Measurement
================================

Assume that we measure an :math:`nIndexBits`-qubits state vector :math:`sv` with a :math:`bitOrderingLen`-bits bit string :math:`bitOrdering`.

The sums of squared absolute values of state vector elements are obtained by the following:

.. math::

  abs2sum[idx] = \braket{sv|i}\braket{i|sv},

where :math:`idx =  b_{BitOrderingLen-1}\cdots b_1 b_0`, :math:`i = b_{bitOrdering[BitOrderingLen-1]} \cdots b_{bitOrdering[1]} b_{bitOrdering[0]}`, :math:`b_p \in \{0, 1\}`.

Therefore, probability to obtain the :math:`idx`-th pattern of bits are expressed in the following expression:

.. math::
  Pr(idx) = \dfrac{abs2sum[idx]}{\sum_{k}abs2sum[k]}.

Depending on the measurement result, the state vector is collapsed.

If :math:`idx` satisfies :math:`(idx \ \& \ bitString) = idx`, we obtain :math:`sv[idx] = \dfrac{1}{\sqrt{norm}} sv[idx]`.
Otherwise, :math:`sv[idx] = 0`, where :math:`norm` is the normalization factor.

Use case
--------

We can measure by `custatevecBatchMeasure` as follows:

.. code-block:: cpp
 
  // measure with a bit string
  custatevecBatchMeasure(
      handle, sv, svDataType, nIndexBits, bitString, bitOrdering, bitStringLen,
      randnum, collapse);

The operation is equivalent to the following:

.. code-block:: cpp

  // compute the sums of squared absolute values of state vector elements 
  int maskLen = 0;
  int* maskBitString = nullptr;
  int* maskOrdering = nullptr;

  custatevecAbs2SumArray(
      handle, sv, svDataType, nIndexBits, abs2Sum, bitOrdering, bitOrderingLen, 
      maskBitString, maskOrdering, maskLen);

  // [User] compute a cumulative sum and choose bitString by a random number

  // collapse if necessary
  switch (collapse) {
  case CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO:
      custatevecCollapseByBitString(
          handle, sv, svDataType, nIndexBits, bitString, bitOrdering, 
          bitStringLen, norm);
      break;  /* collapse */
  case CUSTATEVEC_COLLAPSE_NONE:
      break;  /* Do nothing */

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

.. _custatevecAbs2SumArray-label:

:code:`custatevecAbs2SumArray`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecAbs2SumArray

----

.. _custatevecCollapseByBitString-label:

:code:`custatevecCollapseByBitString`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecCollapseByBitString

----

.. _custatevecBatchMeasure-label:

:code:`custatevecBatchMeasure`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecBatchMeasure


Expectation
***********

Expectation via a Matrix
========================

Expectation performs the following operation:

.. math::
  \langle A \rangle = \bra{\phi}A\ket{\phi},

where :math:`\ket{\phi}` is a state vector and :math:`A` is a matrix or an observer.
The API for expectation `custatevecExpectation` may require external workspace for large matrices, 
and `custatevecExpectation_bufferSize` provides the size of workspace.

Use case
--------

.. code-block:: cpp

  // check the size of external workspace
  custatevecExpectation_bufferSize(
      handle, svDataType, nIndexBits, matrix, matrixDataType, layout, nBasisBits, computeType,    
      &extraWorkspaceSizeInBytes);

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

  // perform expectation
  custatevecExpectation(
      handle, sv, svDataType, nIndexBits, expect, expectDataType, residualNorm, 
      matrix, matrixDataType, layout, basisBits, nBasisBits, computeType,
      extraWorkspace, extraWorkspaceSizeInBytes);

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

.. _custatevecExpectation_bufferSize-label:

:code:`custatevecExpectation_bufferSize`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecExpectation_bufferSize

----

.. _custatevecExpectation-label:

:code:`custatevecExpectation`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. doxygenfunction:: custatevecExpectation


Sampling
********

Sampling enables to obtain measurement results many times by using probability
calculated from quantum states.

Use case
========

.. code-block:: cpp

  // create sampler and check the size of external workspace
  custatevecSampler_create(
      handle, sv, svDataType, nIndexBits, sampler, nMaxShots, 
      &extraWorkspaceSizeInBytes);

  // allocate external workspace if necessary
  void extraWorkspace = nullptr;
  if (extraWorkspaceSizeInBytes > 0)
      cudaMalloc(extraWorkspace, extraWorkspaceSizeInBytes);
  
  // calculate cumulative abs2sum
  custatevecSampler_preprocess(
      handle, sampler, extraWorkspace, extraWorkspaceSizeInBytes);

  // [User] generate randnums, array of random numbers [0, 1) for sampling
  ...

  // sample bit strings
  custatevecSampler_sample(
      handle, sampler, bitStrings, bitOrdering, bitStringLen, randnums, nShots,
      output);

.. _custatevecSampler_create-label:

API reference
=============

:code:`custatevecSampler_create`
--------------------------------

.. doxygenfunction:: custatevecSampler_create

----

.. _custatevecSampler_preprocess-label:

:code:`custatevecSampler_preprocess`
------------------------------------

.. doxygenfunction:: custatevecSampler_preprocess

----

.. _custatevecSampler_sample-label:

:code:`custatevecSampler_sample`
--------------------------------

.. doxygenfunction:: custatevecSampler_sample