Expectation

Expectation via a Matrix

Expectation performs the following operation:

\[\langle A \rangle = \bra{\phi}A\ket{\phi},\]

where \(\ket{\phi}\) is a state vector and \(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 

// 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

custatevecStatus_t custatevecExpectation_bufferSize(custatevecHandle_t handle, cudaDataType_t svDataType, const uint32_t nIndexBits, const void *matrix, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const uint32_t nBasisBits, custatevecComputeType_t computeType, size_t *extraWorkspaceSizeInBytes)

This function gets the required size of the extra workspace.

This function returns the size of the extra workspace required to execute custatevecExpectation(). This function returns 0 to extraWorkspaceSizeInBytes if no extra buffer is required.

Parameters

  • handle – [in] the handle to the cuStateVec context

  • svDataType – [in] Data type of the state vector

  • nIndexBits – [in] the number of index bits of the state vector

  • matrix – [in] host or device pointer to a matrix

  • matrixDataType – [in] data type of matrix

  • layout – [in] enumerator specifying the memory layout of matrix

  • nBasisBits – [in] the number of target bits

  • computeType – [in] computeType of matrix multiplication

  • extraWorkspaceSizeInBytes – [out] size of the extra workspace

custatevecExpectation

custatevecStatus_t custatevecExpectation(custatevecHandle_t handle, const void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, void *expect, cudaDataType_t expectDataType, double *residualNorm, const void *matrix, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const int32_t *basisBits, const uint32_t nBasisBits, custatevecComputeType_t computeType, void *extraWorkspace, size_t extraWorkspaceSizeInBytes)

expectation of matrix observable

This function calculates expectation for a given matrix observable. The acceptable values for the expectDataType argument are CUDA_R_64F and CUDA_C_64F.

The basisBits and nBasisBits specifies the bases to calculate expectation. For the computeType argument, the same combinations for custatevecApplyMatrix() are available.

This function may return CUSTATEVEC_STATUS_INSUFFICIENT_WORKSPACE for large nBasisBits. In such cases, the extraWorkspace and extraWorkspaceInBytes arguments should be specified to provide extra workspace. The size of required extra workspace is obtained by calling custatevecExpectation_bufferSize(). A null pointer can be passed to the extraWorkspace argument if no extra workspace is required.

Note

The residualNorm argument is not available in the Beta1 release. If a matrix given by the matrix argument may not be a Hermitian matrix, please specify CUDA_C_64F to the expectDataType argument and check the imaginary part of the calculated expectation value.

In the Beta1 release, the combination of svDataType=CUDA_C_32F and matrixDataType=CUDA_C_64F only works up-to 6 basis bits. If nBasisBits exceeds this limit, CUSTATEVEC_STATUS_INVALID_VALUE is returned.

Parameters

  • handle – [in] the handle to the cuStateVec library

  • expect – [out] host pointer to a variable to store an expectation value

  • expectDataType – [in] data type of expect

  • residualNorm – [out] result of matrix type test

  • sv – [in] state vector

  • svDataType – [in] data type of the state vector

  • nIndexBits – [in] the number of index bits of the state vector

  • matrix – [in] observable as matrix

  • matrixDataType – [in] data type of matrix

  • layout – [in] matrix memory layout

  • basisBits – [in] pointer to a host array of basis index bits

  • nBasisBits – [in] the number of basis bits

  • computeType – [in] computeType of matrix multiplication

  • extraWorkspace – [in] pointer to an extra workspace

  • extraWorkspaceSizeInBytes – [in] the size of extra workspace

Expectation on Pauli Basis

Note

This API is not available in this version.

Warning

doxygenfunction: Cannot find function “custatevecExpectationOnPauliBasis” in doxygen xml output for project “cuStateVec” from directory: _xml