cuStateVec Data Types

Opaque Data Structures

custatevecIndex_t

typedef int64_t custatevecIndex_t

Type for state vector indexing.

This type is used to represent the indices of the state vector. As every bit in the state vector index corresponds to one qubit in a circuit, this type is also used to represent bit strings. The bit ordering is in little endian. The 0-th bit is the LSB.

custatevecHandle_t

typedef struct custatevecContext *custatevecHandle_t

This handle stores necessary information for carrying out state vector calculations.

This handle holds the cuStateVec library context (device properties, system information, etc.), which is used in all cuStateVec function calls. The handle must be initialized and destroyed using the custatevecCreate() and custatevecDestroy() functions, respectively.

custatevecSamplerDescriptor_t

typedef struct custatevecSamplerDescriptor *custatevecSamplerDescriptor_t

This descriptor holds the context of the sampling operation, initialized using custatevecSamplerCreate() and destroyed using custatevecSamplerDestroy(), respectively.

custatevecAccessorDescriptor_t

typedef struct custatevecAccessorDescriptor *custatevecAccessorDescriptor_t

This descriptor holds the context of accessor operation, initialized using custatevecAccessorCreate() and destroyed using custatevecAccessorDestroy(), respectively.

custatevecLoggerCallback_t

typedef void (*custatevecLoggerCallback_t)(int32_t logLevel, const char *functionName, const char *message)

A callback function pointer type for logging. Use custatevecLoggerSetCallback() to set the callback function.

Parameters

• logLevel – [in] the log level

• functionName – [in] the name of the API that logged this message

• message – [in] the log message

custatevecLoggerCallbackData_t

typedef void (*custatevecLoggerCallbackData_t)(int32_t logLevel, const char *functionName, const char *message, void *userData)

A callback function pointer type for logging, with user data accepted. Use custatevecLoggerSetCallbackData() to set the callback function.

Parameters

• logLevel – [in] the log level

• functionName – [in] the name of the API that logged this message

• message – [in] the log message

• userData – [in] the user-provided data to be used inside the callback function

custatevecDeviceMemHandler_t

struct custatevecDeviceMemHandler_t

The device memory handler structure holds information about the user-provided, stream-ordered device memory pool (mempool).

Public Members

void *ctx

A pointer to the user-owned mempool/context object.

int (*device_alloc)(void *ctx, void **ptr, size_t size, cudaStream_t stream)

A function pointer to the user-provided routine for allocating device memory of size on stream.

The allocated memory should be made accessible to the current device (or more precisely, to the current CUDA context bound to the library handle).

This interface supports any stream-ordered memory allocator ctx. Upon success, the allocated memory can be immediately used on the given stream by any operations enqueued/ordered on the same stream after this call.

It is the caller’s responsibility to ensure a proper stream order is established.

The allocated memory should be at least 256-byte aligned.

Parameters

• ctx – [in] A pointer to the user-owned mempool object.

• ptr – [out] On success, a pointer to the allocated buffer.

• size – [in] The amount of memory in bytes to be allocated.

• stream – [in] The CUDA stream on which the memory is allocated (and the stream order is established).

Returns

Error status of the invocation. Return 0 on success and any nonzero integer otherwise. This function must not throw if it is a C++ function.

int (*device_free)(void *ctx, void *ptr, size_t size, cudaStream_t stream)

A function pointer to the user-provided routine for deallocating device memory of size on stream.

This interface supports any stream-ordered memory allocator. Upon success, any subsequent accesses (of the memory pointed to by the pointer ptr) ordered after this call are undefined behaviors.

It is the caller’s responsibility to ensure a proper stream order is established.

If the arguments ctx and size are not the same as those passed to device_alloc to allocate the memory pointed to by ptr, the behavior is undefined.

The argument stream need not be identical to the one used for allocating ptr, as long as the stream order is correctly established. The behavior is undefined if this assumption is not held.

Parameters

• ctx – [in] A pointer to the user-owned mempool object.

• ptr – [in] The pointer to the allocated buffer.

• size – [in] The size of the allocated memory.

• stream – [in] The CUDA stream on which the memory is deallocated (and the stream ordering is established).

Returns

Error status of the invocation. Return 0 on success and any nonzero integer otherwise. This function must not throw if it is a C++ function.

char name[CUSTATEVEC_ALLOCATOR_NAME_LEN]

The name of the provided mempool.

---

Enumerators

custatevecStatus_t

enum custatevecStatus_t

Contains the library status. Each cuStateVec API returns this enumerator.

Values:

enumerator CUSTATEVEC_STATUS_SUCCESS = 0

The API call has finished successfully.

enumerator CUSTATEVEC_STATUS_NOT_INITIALIZED = 1

The library handle was not initialized.

enumerator CUSTATEVEC_STATUS_ALLOC_FAILED = 2

Memory allocation in the library was failed.

enumerator CUSTATEVEC_STATUS_INVALID_VALUE = 3

Wrong parameter was passed. For example, a null pointer as input data, or an invalid enum value.

enumerator CUSTATEVEC_STATUS_ARCH_MISMATCH = 4

The device capabilities are not enough for the set of input parameters provided.

enumerator CUSTATEVEC_STATUS_EXECUTION_FAILED = 5

Error during the execution of the device tasks.

enumerator CUSTATEVEC_STATUS_INTERNAL_ERROR = 6

Unknown error occured in the library.

enumerator CUSTATEVEC_STATUS_NOT_SUPPORTED = 7

API is not supported by the backend.

enumerator CUSTATEVEC_STATUS_INSUFFICIENT_WORKSPACE = 8

Workspace on device is too small to execute.

enumerator CUSTATEVEC_STATUS_SAMPLER_NOT_PREPROCESSED = 9

Sampler was called prior to preprocessing.

enumerator CUSTATEVEC_STATUS_NO_DEVICE_ALLOCATOR = 10

The device memory pool was not set.

enumerator CUSTATEVEC_STATUS_DEVICE_ALLOCATOR_ERROR = 11

Operation with the device memory pool failed.

enumerator CUSTATEVEC_STATUS_MAX_VALUE = 12

---

custatevecPauli_t

enum custatevecPauli_t

Constants to specify Pauli basis:

• \(\boldsymbol{\sigma}_0 = \mathbf{I} = \left[ \begin{array}{rr} 1 & 0 \\ 0 & 1 \end{array}\right]\)

• \(\boldsymbol{\sigma}_x = \left[ \begin{array}{rr} 0 & 1 \\ 1 & 0 \end{array}\right]\)

• \(\boldsymbol{\sigma}_y = \left[ \begin{array}{rr} 0 & -i \\ i & 0 \end{array}\right]\)

• \(\boldsymbol{\sigma}_z = \left[ \begin{array}{rr} 1 & 0 \\ 0 & -1 \end{array}\right]\)

Values:

enumerator CUSTATEVEC_PAULI_I = 0

Identity matrix.

enumerator CUSTATEVEC_PAULI_X = 1

Pauli X matrix.

enumerator CUSTATEVEC_PAULI_Y = 2

Pauli Y matrix.

enumerator CUSTATEVEC_PAULI_Z = 3

Pauli Z matrix.

---

custatevecMatrixLayout_t

enum custatevecMatrixLayout_t

Constants to specify a matrix’s memory layout.

Values:

enumerator CUSTATEVEC_MATRIX_LAYOUT_COL = 0

Matrix stored in the column-major order.

enumerator CUSTATEVEC_MATRIX_LAYOUT_ROW = 1

Matrix stored in the row-major order.

---

custatevecMatrixType_t

enum custatevecMatrixType_t

Constants to specify the matrix type.

Values:

enumerator CUSTATEVEC_MATRIX_TYPE_GENERAL = 0

Non-specific type.

enumerator CUSTATEVEC_MATRIX_TYPE_UNITARY = 1

Unitary matrix.

enumerator CUSTATEVEC_MATRIX_TYPE_HERMITIAN = 2

Hermitian matrix.

---

custatevecCollapseOp_t

enum custatevecCollapseOp_t

Constants to specify collapse operations.

Values:

enumerator CUSTATEVEC_COLLAPSE_NONE = 0

Do not collapse the statevector.

enumerator CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO = 1

Collapse, normalize, and fill zeros in the statevector.

---

custatevecComputeType_t

enum custatevecComputeType_t

Constants to specify the minimal accuracy for arithmetic operations.

Values:

enumerator CUSTATEVEC_COMPUTE_DEFAULT = 0

FP32(float) for Complex64, FP64(double) for Complex128.

enumerator CUSTATEVEC_COMPUTE_32F = (1U << 2U)

FP32(float)

enumerator CUSTATEVEC_COMPUTE_64F = (1U << 4U)

FP64(double)

enumerator CUSTATEVEC_COMPUTE_TF32 = (1U << 12U)

TF32(tensor-float-32)

---

custatevecSamplerOutput_t

enum custatevecSamplerOutput_t

Constants to specify the order of bit strings in sampling outputs.

Values:

enumerator CUSTATEVEC_SAMPLER_OUTPUT_RANDNUM_ORDER = 0

the same order as the given random numbers

enumerator CUSTATEVEC_SAMPLER_OUTPUT_ASCENDING_ORDER = 1

reordered in the ascending order

---

custatevecDeviceNetworkType_t

enum custatevecDeviceNetworkType_t

Constants to specify the device network topology.

Values:

enumerator CUSTATEVEC_DEVICE_NETWORK_TYPE_SWITCH = 1

devices are connected via network switch

enumerator CUSTATEVEC_DEVICE_NETWORK_TYPE_FULLMESH = 2

devices are connected by full mesh network