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¶

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

custatevecStatus_t custatevecApplyMatrix_bufferSize(custatevecHandle_t handle, cudaDataType_t svDataType, const uint32_t nIndexBits, const void *matrix, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const int32_t adjoint, const uint32_t nTargets, const uint32_t nControls, custatevecComputeType_t computeType, size_t *extraWorkspaceSizeInBytes)

This function gets the required workspace size for custatevecApplyMatrix()

This function returns the required extra workspace size to execute custatevecApplyMatrix(). This function returns 0 to extraWorkspaceSizeInBytes if no extra buffer is required for a given set of arguments,

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
adjoint – [in] apply adjoint of matrix
nTargets – [in] the number of target bits
nControls – [in] the number of control bits
computeType – [in] computeType of matrix multiplication
extraWorkspaceSizeInBytes – [out] workspace size

`custatevecApplyMatrix`¶

custatevecStatus_t custatevecApplyMatrix(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, const void *matrix, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const int32_t adjoint, const int32_t *targets, const uint32_t nTargets, const int32_t *controls, const uint32_t nControls, const int32_t *controlBitValues, custatevecComputeType_t computeType, void *extraWorkspace, size_t extraWorkspaceSizeInBytes)

Apply gate matrix.

Apply gate matrix to a state vector. The state vector size is 2^nIndexBits.

The matrix argument is a host or device pointer of a 2-dimensional array for a square matrix. The size of matrix is (2^nTargets x 2^nTargets) and the value type is specified by the matrixDataType argument. The layout argument specifies the matrix layout which can be row-major or column-major order. The targets and controls arguments specify target and control bit positions in the state vector index.

The controlBitValues argument specifies bit values of control bits. The ordering of controlBitValues is specified by the controls argument. If a null pointer is specified to this argument, all control bit values are set to 1.

By definition, bit positions in targets and controls arguments should not overlap.

This function may return CUSTATEVEC_STATUS_INSUFFICIENT_WORKSPACE for large nTargets. 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 custatevecApplyMatrix_bufferSize(). A null pointer can be passed to the extraWorkspace argument if no extra workspace is required.

Note

In the Beta1 release, the combination of svDataType=CUDA_C_32F and matrixDataType=CUDA_C_64F only works with up-to 6 targets. If a value passed to the nTargets argument exceeds this limit, CUSTATEVEC_STATUS_INVALID_VALUE is returned.

Parameters

handle – [in] the handle to the cuStateVec library
sv – [inout] state vector
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 square matrix
matrixDataType – [in] data type of matrix
layout – [in] enumerator specifying the memory layout of matrix
adjoint – [in] apply adjoint of matrix
targets – [in] pointer to a host array of target bits
nTargets – [in] the number of target bits
controls – [in] pointer to a host array of control bits
nControls – [in] the number of control bits
controlBitValues – [in] pointer to a host array of control bit values
computeType – [in] computeType of matrix multiplication
extraWorkspace – [in] extra workspace
extraWorkspaceSizeInBytes – [in] extra workspace size

Pauli Matrices¶

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

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

Matrix \(P_{target[i]}\) can be either of the followings:

\[\begin{split}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]`.\end{split}\]

Use case¶

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

API reference¶

`custatevecApplyExp`¶

custatevecStatus_t custatevecApplyExp(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, double theta, const custatevecPauli_t *paulis, const int32_t *targets, const uint32_t nTargets, const int32_t *controls, const int32_t *controlBitValues, const uint32_t nControls)

Apply the exponential of a multi-qubit Pauli operator.

Apply exponential of a tensor product of Pauli bases specified by bases, exp(i x theta x product_of_pauli_bases). The paulis, targets, and nTargets arguments specify Pauli bases and their bit positions in the state vector index.

At least one target and a corresponding Pauli basis should be specified to call this function.

The controls and nControls arguments specifies the control bit positions in the state vector index.

The controlBitValues argument specifies bit values of control bits. The ordering of controlBitValues is specified by the controls argument. If a null pointer is specified to this argument, all control bit values are set to 1.

Parameters

handle – [in] the handle to the cuStateVec library
sv – [inout] state vector
svDataType – [in] data type of the state vector
nIndexBits – [in] the number of bits in the state vector index
theta – [in] theta
paulis – [in] host pointer to custatevecPauli_t array
targets – [in] pointer to a host array of target bits
nTargets – [in] the number of target bits
controls – [in] pointer to a host array of control bits
controlBitValues – [in] pointer to a host array of control bit values
nControls – [in] the number of control bits

Diagonal Matrices¶

`custatevecApplyDiagonalMatrix`¶

Note

This API is not available in this version.

Warning

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

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¶

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

Warning

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

`custatevecTestMatrixType`¶

Warning

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

Gate Application¶

General Matrices¶

Use case¶

API reference¶

custatevecApplyMatrix_bufferSize¶

custatevecApplyMatrix¶

Pauli Matrices¶

Use case¶

API reference¶

custatevecApplyExp¶

Diagonal Matrices¶

custatevecApplyDiagonalMatrix¶

Matrix Tests¶

Use case¶

API reference¶

custatevecTestMatrixType_bufferSize¶

custatevecTestMatrixType¶

`custatevecApplyMatrix_bufferSize`¶

`custatevecApplyMatrix`¶

`custatevecApplyExp`¶

`custatevecApplyDiagonalMatrix`¶

`custatevecTestMatrixType_bufferSize`¶

`custatevecTestMatrixType`¶