cuStateVec Functions¶

Library Management¶

Handle Management API¶

`custatevecCreate`¶

custatevecStatus_t custatevecCreate(custatevecHandle_t *handle)¶

This function initializes the cuStateVec library and creates a handle on the cuStateVec context. It must be called prior to any other cuStateVec API functions.

Parameters: handle – [in] the pointer to the handle to the cuStateVec context

`custatevecDestroy`¶

custatevecStatus_t custatevecDestroy(custatevecHandle_t handle)¶

This functions releases resources used by the cuStateVec library.

Parameters: handle – [in] the handle to the cuStateVec context

`custatevecGetDefaultWorkspaceSize`¶

custatevecStatus_t custatevecGetDefaultWorkspaceSize(custatevecHandle_t handle, size_t *workspaceSizeInBytes)¶

This function returns the default workspace size defined by the cuStateVec library.

This function returns the default size used for the workspace.

Parameters

handle – [in] the handle to the cuStateVec context
workspaceSizeInBytes – [out] default workspace size

`custatevecSetWorkspace`¶

custatevecStatus_t custatevecSetWorkspace(custatevecHandle_t handle, void *workspace, size_t workspaceSizeInBytes)¶

This function sets the workspace used by the cuStateVec library.

This function sets the workspace attached to the handle. The required size of the workspace is obtained by custatevecGetDefaultWorkspaceSize().

By setting a larger workspace, users are able to execute functions without allocating the extra workspace in some functions

Parameters

handle – [in] the handle to the cuStateVec context
workspace – [in] device pointer to workspace
workspaceSizeInBytes – [in] workspace size

CUDA Stream Management API¶

`custatevecSetStream`¶

custatevecStatus_t custatevecSetStream(custatevecHandle_t handle, cudaStream_t streamId)¶

This function sets the stream to be used by the cuStateVec library to execute its routine.

Parameters

handle – [in] the handle to the cuStateVec context
streamId – [in] the stream to be used by the library

`custatevecGetStream`¶

custatevecStatus_t custatevecGetStream(custatevecHandle_t handle, cudaStream_t *streamId)¶

This function gets the cuStateVec library stream used to execute all calls from the cuStateVec library functions.

Parameters

handle – [in] the handle to the cuStateVec context
streamId – [out] the stream to be used by the library

Error Management API¶

`custatevecGetErrorName`¶

const char *custatevecGetErrorName(custatevecStatus_t status)¶

This function returns the name string for the input error code. If the error code is not recognized, “unrecognized error code” is returned.

Parameters: status – [in] Error code to convert to string

`custatevecGetErrorString`¶

const char *custatevecGetErrorString(custatevecStatus_t status)¶

This function returns the description string for an error code. If the error code is not recognized, “unrecognized error code” is returned.

Parameters: status – [in] Error code to convert to string

Logger API¶

`custatevecLoggerSetCallback`¶

custatevecStatus_t custatevecLoggerSetCallback(custatevecLoggerCallback_t callback)¶

Experimental: This function sets the logging callback function.

Parameters: callback – [in] Pointer to a callback function. See custatevecLoggerCallback_t.

`custatevecLoggerSetFile`¶

custatevecStatus_t custatevecLoggerSetFile(FILE *file)¶

Experimental: This function sets the logging output file.

Note

Once registered using this function call, the provided file handle must not be closed unless the function is called again to switch to a different file handle.

Parameters: file – [in] Pointer to an open file. File should have write permission.

`custatevecLoggerOpenFile`¶

custatevecStatus_t custatevecLoggerOpenFile(const char *logFile)¶

Experimental: This function opens a logging output file in the given path.

Parameters: logFile – [in] Path of the logging output file.

`custatevecLoggerSetLevel`¶

custatevecStatus_t custatevecLoggerSetLevel(int32_t level)¶

Experimental: This function sets the value of the logging level. Levels are defined as follows:

Level	Description
“0”	Off
“1”	Errors
“2”	Performance Trace
“3”	Performance Hints
“4”	Heuristics Trace
“5”	API Trace

Refer to custatevecLoggerCallback_t for the details.

Parameters: level – [in] Value of the logging level.

`custatevecLoggerSetMask`¶

custatevecStatus_t custatevecLoggerSetMask(int32_t mask)¶

Experimental: This function sets the value of the logging mask. Masks are defined as a combination of the following masks:

Level	Description
“0”	Off
“1”	Errors
“2”	Performance Trace
“4”	Performance Hints
“8”	Heuristics Trace
“16”	API Trace

Refer to custatevecLoggerCallback_t for the details.

Parameters: mask – [in] Value of the logging mask.

`custatevecLoggerForceDisable`¶

custatevecStatus_t custatevecLoggerForceDisable()¶: Experimental: This function disables logging for the entire run.

Versioning API¶

`custatevecGetProperty`¶

custatevecStatus_t custatevecGetProperty(libraryPropertyType type, int32_t *value)¶

This function returns the version information of the cuStateVec library.

Parameters

type – [in] requested property (MAJOR_VERSION, MINOR_VERSION, or PATCH_LEVEL).
value – [out] value of the requested property.

`custatevecGetVersion`¶

size_t custatevecGetVersion()¶: This function returns the version information of the cuStateVec library.

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

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 Pauli matrices \(I\), \(X\), \(Y\), and \(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 custatevecPauli_t for details.

Use case¶

// apply exponential
custatevecApplyExp(
    handle, sv, svDataType, nIndexBits, theta, paulis, targets, nTargets,
    controls, controlBitValues, 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

Measurement¶

Measurement on Z-bases¶

Let us consider the measurement of an \(nIndexBits\)-qubit state vector \(sv\) on an \(nBasisBits\)-bit Z product basis \(basisBits\).

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

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

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

\[\begin{split}Pr(parity = 0) &= \dfrac{abs2sum0}{abs2sum0 + abs2sum1}, \\ Pr(parity = 1) &= \dfrac{abs2sum1}{abs2sum0 + abs2sum1}.\end{split}\]

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

\[\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:

\[\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 \(norm\) is the normalization factor.

Use case¶

We can measure by custatevecMeasureOnZBasis() as follows:

// measure on a Z basis
custatevecMeasureOnZBasis(
    handle, sv, svDataType, nIndexBits, &parity, basisBits, nBasisBits,
    randnum, collapse);

The operation is equivalent to the following:

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

custatevecStatus_t custatevecAbs2SumOnZBasis(custatevecHandle_t handle, const void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, double *abs2sum0, double *abs2sum1, const int32_t *basisBits, const uint32_t nBasisBits)¶

Calculates the sum of squared absolute values on a given Z product basis.

This function calculates sums of squared absolute values on a given Z product basis. If a NULL pointer is specified to abs2sum0 or abs2sum1, the sum for the corresponding value is not calculated. Since the sum of (abs2sum0 + abs2sum1) is identical to the norm of the state vector, one can calculate the probability where parity==0 as (abs2sum0 / (abs2sum0 + abs2sum1)).

Parameters

handle – [in] the handle to the cuStateVec library
sv – [in] state vector
svDataType – [in] data type of state vector
nIndexBits – [in] the number of index bits
abs2sum0 – [out] pointer to a host or device variable to store the sum of squared absolute values for parity==0
abs2sum1 – [out] pointer to a host or device variable to store the sum of squared absolute values for parity==1
basisBits – [in] pointer to a host array of Z-basis index bits
nBasisBits – [in] the number of basisBits

`custatevecCollapseOnZBasis`¶

custatevecStatus_t custatevecCollapseOnZBasis(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, const int32_t parity, const int32_t *basisBits, const uint32_t nBasisBits, double norm)¶

Collapse state vector on a given Z product basis.

This function collapses state vector on a given Z product basis. The state specified by the parity argument is normalized by using norm, otherwise reset to zero.

Parameters

handle – [in] the handle to the cuStateVec library
sv – [inout] state vector
svDataType – [in] data type of state vector
nIndexBits – [in] the number of index bits
parity – [in] parity, 0 or 1
basisBits – [in] pointer to a host array of Z-basis index bits
nBasisBits – [in] the number of Z basis bits
norm – [in] normalization factor

`custatevecMeasureOnZBasis`¶

custatevecStatus_t custatevecMeasureOnZBasis(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, int32_t *parity, const int32_t *basisBits, const uint32_t nBasisBits, const double randnum, enum custatevecCollapseOp_t collapse)¶

Measurement on a given Z-product basis.

This function does measurement on a given Z product basis. The measurement result is the parity of the specified Z product basis. At least one basis bit should be specified, otherwise this function fails.

If CUSTATEVEC_COLLAPSE_NONE is specified for the collapse argument, this function only returns the measurement result without collapsing the state vector. If CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO is specified, this function collapses the state vector as custatevecCollapseOnZBasis() does.

If a random number is not in [0, 1), this function returns CUSTATEVEC_STATUS_INVALID_VALUE. At least one basis bit should be specified, otherwise this function returns CUSTATEVEC_STATUS_INVALID_VALUE.

Parameters

handle – [in] the handle to the cuStateVec library
sv – [inout] state vector
svDataType – [in] data type of state vector
nIndexBits – [in] the number of index bits
parity – [out] parity, 0 or 1
basisBits – [in] pointer to a host array of Z basis bits
nBasisBits – [in] the number of Z basis bits
randnum – [in] random number, [0, 1).
collapse – [in] Collapse operation

Batched Single Qubit Measurement¶

Assume that we measure an \(nIndexBits\)-qubits state vector \(sv\) with a \(bitOrderingLen\)-bits bit string \(bitOrdering\).

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

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

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

Therefore, probability to obtain the \(idx\)-th pattern of bits are expressed in the following expression:

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

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

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

Use case¶

We can measure by custatevecBatchMeasure() as follows:

// measure with a bit string
custatevecBatchMeasure(
    handle, sv, svDataType, nIndexBits, bitString, bitOrdering, bitStringLen,
    randnum, collapse);

The operation is equivalent to the following:

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

custatevecStatus_t custatevecAbs2SumArray(custatevecHandle_t handle, const void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, double *abs2sum, const int32_t *bitOrdering, const uint32_t bitOrderingLen, const int32_t *maskBitString, const int32_t *maskOrdering, const uint32_t maskLen)¶

Calculate abs2sum array for a given set of index bits.

Calculates an array of sums of squared absolute values of state vector elements. The abs2sum array can be on host or device. The index bit ordering abs2sum array is specified by the bitOrdering and bitOrderingLen arguments. Unspecified bits are folded (summed up).

The maskBitString, maskOrdering and maskLen arguments set bit mask in the state vector index. The abs2sum array is calculated by using state vector elements whose indices match the mask bit string. If the makeLen argument is 0, NULL pointers can be specified to the maskBitString and maskOrdering arguments, and all state vector elements are used for calculation.

By definition, bit positions in bitOrdering and maskOrdering arguments should not overlap.

The empty bitOrdering can be specified to calculate the norm of state vector. In this case, 0 is passed to the bitOrderingLen arguments and the bitOrdering argument can be a null pointer.

Note

Since the size of abs2sum array is proportional to 2^(bitOrderingLen - maskLen), the max length of bitOrdering depends on the amount of available memory and maskLen.

Parameters

handle – [in] the handle to the cuStateVec library
sv – [in] state vector
svDataType – [in] data type of state vector
nIndexBits – [in] the number of index bits
abs2sum – [out] pointer to a host or device array of sums of squared absolute values
bitOrdering – [in] pointer to a host array of index bit ordering
bitOrderingLen – [in] the length of bitOrdering
maskBitString – [in] pointer to a host array for a bit string to specify mask
maskOrdering – [in] pointer to a host array for the mask ordering
maskLen – [in] the length of mask

`custatevecCollapseByBitString`¶

custatevecStatus_t custatevecCollapseByBitString(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, const int32_t *bitString, const int32_t *bitOrdering, const uint32_t bitStringLen, double norm)¶

Collapse state vector to the state specified by a given bit string.

This function collapse state vector to the state specified by a given bit string. The state specified by the bitString, bitOrdering and bitStringLen arguments is normalized by using the norm argument. Other states are reset to zero.

At least one basis bit should be specified, otherwise this function returns CUSTATEVEC_STATUS_INVALID_VALUE.

Parameters

handle – [in] the handle to the cuStateVec library
sv – [inout] state vector
svDataType – [in] data type of state vector
nIndexBits – [in] the number of index bits
bitString – [in] pointer to a host array of bit string
bitOrdering – [in] pointer to a host array of bit string ordering
bitStringLen – [in] length of bit string
norm – [in] normalization constant

`custatevecBatchMeasure`¶

custatevecStatus_t custatevecBatchMeasure(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, int32_t *bitString, const int32_t *bitOrdering, const uint32_t bitStringLen, const double randnum, enum custatevecCollapseOp_t collapse)¶

Batched single qubit measurement.

This function does batched single qubit measurement and returns a bit string. The bitOrdering argument specifies index bits to be measured. The measurement result is stored in bitString in the ordering specified by the bitOrdering argument.

If CUSTATEVEC_COLLAPSE_NONE is specified for the collapse argument, this function only returns the measured bit string without collapsing the state vector. When CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO is specified, this function collapses the state vector as custatevecCollapseByBitString() does.

If a random number is not in [0, 1), this function returns CUSTATEVEC_STATUS_INVALID_VALUE. At least one basis bit should be specified, otherwise this function returns CUSTATEVEC_STATUS_INVALID_VALUE.

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
bitString – [out] pointer to a host array of measured bit string
bitOrdering – [in] pointer to a host array of bit string ordering
bitStringLen – [in] length of bitString
randnum – [in] random number, [0, 1).
collapse – [in] Collapse operation

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

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

Sampling¶

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

Use case¶

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

API reference¶

`custatevecSampler_create`¶

custatevecStatus_t custatevecSampler_create(custatevecHandle_t handle, const void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, custatevecSamplerDescriptor_t *sampler, uint32_t nMaxShots, size_t *extraWorkspaceSizeInBytes)¶

create sampler descriptor

This function creates a sampler descriptor. If an extra workspace is required, its size is returned to extraWorkspaceSizeInBytes.

Parameters

handle – [in] the handle to the cuStateVec library
sv – [in] pointer to state vector
svDataType – [in] data type of state vector
nIndexBits – [in] the number of index bits of the state vector
sampler – [out] pointer to a new sampler descriptor
nMaxShots – [in] the max number of shots used for this sampler context
extraWorkspaceSizeInBytes – [out] workspace size

`custatevecSampler_preprocess`¶

custatevecStatus_t custatevecSampler_preprocess(custatevecHandle_t handle, custatevecSamplerDescriptor_t *sampler, void *extraWorkspace, const size_t extraWorkspaceSizeInBytes)¶

Preprocess the state vector for preparation of sampling.

This function prepares internal states of the sampler descriptor. A pointer passed to the extraWorkspace argument is associated to the sampler handle and should be kept during its life time.

The size of extraWorkspace is obtained when custatevecSampler_create() is called.

Parameters

handle – [in] the handle to the cuStateVec library
sampler – [inout] Sampler object handle
extraWorkspace – [in] extra workspace
extraWorkspaceSizeInBytes – [in] size of the extra workspace

`custatevecSampler_sample`¶

custatevecStatus_t custatevecSampler_sample(custatevecHandle_t handle, custatevecSamplerDescriptor_t *sampler, custatevecIndex_t *bitStrings, const int32_t *bitOrdering, const uint32_t bitStringLen, const double *randnums, const uint32_t nShots, enum custatevecSamplerOutput_t output)¶

Sample bit strings from the state vector.

This function does sampling. The bitOrdering and bitStringLen arguments specify bits to be sampled. Sampled bit strings are represented as an array of custatevecIndex_t and are stored to the host memory buffer that the bitStrings argument points to.

The randnums argument is an array of user-generated random numbers whose length is nShots. The range of random numbers should be in [0, 1). A random number given by the randnums argument is clipped to [0, 1) if its range is not in [0, 1).

The output argument specifies the order of sampled bit strings.

If CUSTATEVEC_SAMPLER_OUTPUT_RANDNUM_ORDER is specified, the order of sampled bit strings is the same as that in the randnums argument. If CUSTATEVEC_SAMPLER_OUTPUT_ASCENDING_ORDER is specified, bit strings are returned in the ascending order.

Parameters

handle – [in] the handle to the cuStateVec library
sampler – [in] Sampler object handle
bitStrings – [out] pointer to a host array to store sampled bit strings
bitOrdering – [in] pointer to a host array of bit ordering for sampling
bitStringLen – [in] the number of bits in bitOrdering
randnums – [in] pointer to a host array of random numbers,
nShots – [in] the number of shots
output – [in] the order of sampled bit strings

cuStateVec Functions¶

Library Management¶

Handle Management API¶

custatevecCreate¶

custatevecDestroy¶

custatevecGetDefaultWorkspaceSize¶

custatevecSetWorkspace¶

CUDA Stream Management API¶

custatevecSetStream¶

custatevecGetStream¶

Error Management API¶

custatevecGetErrorName¶

custatevecGetErrorString¶

Logger API¶

custatevecLoggerSetCallback¶

custatevecLoggerSetFile¶

custatevecLoggerOpenFile¶

custatevecLoggerSetLevel¶

custatevecLoggerSetMask¶

custatevecLoggerForceDisable¶

Versioning API¶

custatevecGetProperty¶

custatevecGetVersion¶

Gate Application¶

General Matrices¶

Use case¶

API reference¶

custatevecApplyMatrix_bufferSize¶

custatevecApplyMatrix¶

Pauli Matrices¶

Use case¶

API reference¶

custatevecApplyExp¶

Measurement¶

Measurement on Z-bases¶

Use case¶

API reference¶

custatevecAbs2SumOnZBasis¶

custatevecCollapseOnZBasis¶

custatevecMeasureOnZBasis¶

Batched Single Qubit Measurement¶

Use case¶

API reference¶

custatevecAbs2SumArray¶

custatevecCollapseByBitString¶

custatevecBatchMeasure¶

Expectation¶

Expectation via a Matrix¶

Use case¶

API reference¶

custatevecExpectation_bufferSize¶

custatevecExpectation¶

Sampling¶

Use case¶

API reference¶

custatevecSampler_create¶

custatevecSampler_preprocess¶

custatevecSampler_sample¶

`custatevecCreate`¶

`custatevecDestroy`¶

`custatevecGetDefaultWorkspaceSize`¶

`custatevecSetWorkspace`¶

`custatevecSetStream`¶

`custatevecGetStream`¶

`custatevecGetErrorName`¶

`custatevecGetErrorString`¶

`custatevecLoggerSetCallback`¶

`custatevecLoggerSetFile`¶

`custatevecLoggerOpenFile`¶

`custatevecLoggerSetLevel`¶

`custatevecLoggerSetMask`¶

`custatevecLoggerForceDisable`¶

`custatevecGetProperty`¶

`custatevecGetVersion`¶

`custatevecApplyMatrix_bufferSize`¶

`custatevecApplyMatrix`¶

`custatevecApplyExp`¶

`custatevecAbs2SumOnZBasis`¶

`custatevecCollapseOnZBasis`¶

`custatevecMeasureOnZBasis`¶

`custatevecAbs2SumArray`¶

`custatevecCollapseByBitString`¶

`custatevecBatchMeasure`¶

`custatevecExpectation_bufferSize`¶

`custatevecExpectation`¶

`custatevecSampler_create`¶

`custatevecSampler_preprocess`¶

`custatevecSampler_sample`¶