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.

custatevecCommunicatorDescriptor_t

typedef struct custatevecCommunicator_t *custatevecCommunicatorDescriptor_t

This descriptor manages inter-process communications, initialized by using custatevecCommunicatorCreate() and destroyed by using custatevecCommunicatorDestroy().

custatevecDistIndexBitSwapSchedulerDescriptor_t

typedef struct custatevecDistIndexBitSwapScheduler_t *custatevecDistIndexBitSwapSchedulerDescriptor_t

This descriptor holds the context of scheduler for distributed index bit swaps, initialized using custatevecDistIndexBitSwapSchedulerCreate() and destroyed using custatevecDistIndexBitSwapSchedulerDestroy(), respectively.

custatevecSVSwapWorkerDescriptor_t

typedef struct custatevecSVSwapWorker_t *custatevecSVSwapWorkerDescriptor_t

This descriptor holds the context of data transfer worker for distributed index bit swaps, initialized using custatevecSVSwapWorkerCreate() and destroyed using custatevecSVSwapWorkerDestroy(), respectively.

custatevecSVSwapParameters_t

struct custatevecSVSwapParameters_t

Public Members

int32_t swapBatchIndex

swapBatchIndex specified by an argument of custatevecDistIndexBitSwapSchedulerGetParameters()

int32_t orgSubSVIndex

origin subSV index specified by an argument of custatevecDistIndexBitSwapSchedulerGetParameters()

int32_t dstSubSVIndex

destination subSV index

int32_t orgSegmentMaskString[CUSTATEVEC_MAX_SEGMENT_MASK_SIZE]

segment mask string in the origin

int32_t dstSegmentMaskString[CUSTATEVEC_MAX_SEGMENT_MASK_SIZE]

segment mask string in the destination

int32_t segmentMaskOrdering[CUSTATEVEC_MAX_SEGMENT_MASK_SIZE]

mask ordering for segment mask strings

uint32_t segmentMaskLen

segment mask length

uint32_t nSegmentBits

the number of index bits in the segment

custatevecDataTransferType_t dataTransferType

the type of this data transfer

custatevecIndex_t transferSize

the number of elements being transferred, transferSize = 1 << (nSegmentBits - segmentMaskLen).

custatevecSubSVMigratorDescriptor_t

typedef struct custatevecSubSVMigratorDescriptor *custatevecSubSVMigratorDescriptor_t

This descriptor holds the context of the migrator operation, initialized using custatevecSubSVMigratorCreate() and destroyed using custatevecSubSVMigratorDestroy(), respectively.

CUSTATEVEC_ALLOCATOR_NAME_LEN

CUSTATEVEC_ALLOCATOR_NAME_LEN

CUSTATEVEC_MAX_SEGMENT_MASK_SIZE

CUSTATEVEC_MAX_SEGMENT_MASK_SIZE

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 occurred 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_COMMUNICATOR_ERROR = 12

Operation with the communicator failed.

enumerator CUSTATEVEC_STATUS_LOADING_LIBRARY_FAILED = 13

Dynamic loading of the shared library failed.

enumerator CUSTATEVEC_STATUS_MAX_VALUE = 14

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.

custatevecMatrixMapType_t

enum custatevecMatrixMapType_t

Constants to specify how to assign matrices to batched state vectors.

Values:

enumerator CUSTATEVEC_MATRIX_MAP_TYPE_BROADCAST = 0

matrix to be applied is uniform among the all state vectors.

enumerator CUSTATEVEC_MATRIX_MAP_TYPE_MATRIX_INDEXED = 1

each state vector refers to indices to select its 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

custatevecStateVectorType_t

enum custatevecStateVectorType_t

Constants to specify the quantum state.

Values:

enumerator CUSTATEVEC_STATE_VECTOR_TYPE_ZERO = 0

create a zero state, \(|00\cdots0\rangle\).

enumerator CUSTATEVEC_STATE_VECTOR_TYPE_UNIFORM = 1

create an equal superposition of all computational basis, \(\frac{1}{\sqrt{2^n}}\left(|00\cdots00\rangle + |00\cdots01\rangle + \cdots + |11\cdots10\rangle + |11\cdots11\rangle\right)\).

enumerator CUSTATEVEC_STATE_VECTOR_TYPE_GHZ = 2

create a GHZ state, \(\frac{1}{\sqrt{2}}\left(|00\cdots0\rangle + |11\cdots1\rangle\right)\).

enumerator CUSTATEVEC_STATE_VECTOR_TYPE_W = 3

create a W state, \(\frac{1}{\sqrt{n}}\left(|000\cdots001\rangle + |000\cdots010\rangle + \cdots + |010\cdots000\rangle + |100\cdots000\rangle\right)\).

custatevecCommunicatorType_t

enum custatevecCommunicatorType_t

Constant to specify the communicator used in inter-process communications.

Values:

enumerator CUSTATEVEC_COMMUNICATOR_TYPE_EXTERNAL = 0

An user-provided communicator will be used for inter-process communications.

enumerator CUSTATEVEC_COMMUNICATOR_TYPE_OPENMPI = 1

Open MPI will be used for inter-process communications.

enumerator CUSTATEVEC_COMMUNICATOR_TYPE_MPICH = 2

MPICH will be used for inter-process communications.

custatevecDataTransferType_t

enum custatevecDataTransferType_t

Constant to specify the data transfer direction in point-to-point communication.

Values:

enumerator CUSTATEVEC_DATA_TRANSFER_TYPE_NONE = 0

Data transfer worker will not send or receive any data.

enumerator CUSTATEVEC_DATA_TRANSFER_TYPE_SEND = 1

Data transfer worker will send data.

enumerator CUSTATEVEC_DATA_TRANSFER_TYPE_RECV = 2

Data transfer worker will receive data.

enumerator CUSTATEVEC_DATA_TRANSFER_TYPE_SEND_RECV = CUSTATEVEC_DATA_TRANSFER_TYPE_SEND | CUSTATEVEC_DATA_TRANSFER_TYPE_RECV