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

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

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(
      svDataType, 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

Expectation on Pauli Basis
==========================

.. _custatevecExpectationOnPauliBasis-label:

:code:`custatevecExpectationOnPauliBasis`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::

   This API is not available in this version. 

.. doxygenfunction:: custatevecExpectationOnPauliBasis