cuDensityMat data types

cudensitymatHandle_t

typedef void *cudensitymatHandle_t

Opaque data structure holding the library context (context handle).

Context handle holds the library context (device properties, system information, etc.). A context handle must be initialized prior and destroyed after any other library API call using the cudensitymatCreate and cudensitymatDestroy API functions, respectively.

cudensitymatStatus_t

enum cudensitymatStatus_t

Return status of the library API functions.

All library API functions return a status which can take one of the following values.

Values:

enumerator CUDENSITYMAT_STATUS_SUCCESS = 0

The operation has completed successfully.

enumerator CUDENSITYMAT_STATUS_NOT_INITIALIZED = 1

The library is not initialized.

enumerator CUDENSITYMAT_STATUS_ALLOC_FAILED = 3

Resource allocation failed inside the library.

enumerator CUDENSITYMAT_STATUS_INVALID_VALUE = 7

An invalid parameter value was passed to a function (normally indicates a user error).

enumerator CUDENSITYMAT_STATUS_ARCH_MISMATCH = 8

The GPU device is either not ready or the target architecture is not supported.

enumerator CUDENSITYMAT_STATUS_EXECUTION_FAILED = 13

The GPU program failed to execute. This is often caused by a CUDA kernel launch failure on the GPU.

enumerator CUDENSITYMAT_STATUS_INTERNAL_ERROR = 14

An internal library error has occurred.

enumerator CUDENSITYMAT_STATUS_NOT_SUPPORTED = 15

The requested operation is not supported.

enumerator CUDENSITYMAT_STATUS_CALLBACK_ERROR = 16

An error occurred inside a user callback function.

enumerator CUDENSITYMAT_STATUS_CUBLAS_ERROR = 17

A call to the cuBLAS library did not succeed.

enumerator CUDENSITYMAT_STATUS_CUDA_ERROR = 18

An unknown CUDA error has occurred.

enumerator CUDENSITYMAT_STATUS_INSUFFICIENT_WORKSPACE = 19

The provided workspace buffer is insufficient.

enumerator CUDENSITYMAT_STATUS_INSUFFICIENT_DRIVER = 20

The CUDA driver version is insufficient.

enumerator CUDENSITYMAT_STATUS_IO_ERROR = 21

An error occurred during file I/O.

enumerator CUDENSITYMAT_STATUS_CUTENSOR_VERSION_MISMATCH = 22

The dynamically linked cuTENSOR library is incompatible.

enumerator CUDENSITYMAT_STATUS_NO_DEVICE_ALLOCATOR = 23

Drawing GPU device memory from a memory pool is requested, but the memory pool has not been set.

enumerator CUDENSITYMAT_STATUS_CUTENSOR_ERROR = 24

A call to the cuTENSOR library did not succeed.

enumerator CUDENSITYMAT_STATUS_CUSOLVER_ERROR = 25

A call to the cuSOLVER library did not succeed.

enumerator CUDENSITYMAT_STATUS_DEVICE_ALLOCATOR_ERROR = 26

GPU device memory pool operation failure.

enumerator CUDENSITYMAT_STATUS_DISTRIBUTED_FAILURE = 27

Distributed communication service failure.

enumerator CUDENSITYMAT_STATUS_INTERRUPTED = 28

Operation interrupted by the user and cannot recover or complete.

enumerator CUDENSITYMAT_STATUS_CUTENSORNET_ERROR = 29

A call to the cuTensorNet library did not succeed.

cudensitymatComputeType_t

enum cudensitymatComputeType_t

Supported compute types.

Values:

enumerator CUDENSITYMAT_COMPUTE_32F = (1U << 2U)
enumerator CUDENSITYMAT_COMPUTE_64F = (1U << 4U)

cudensitymatDistributedProvider_t

enum cudensitymatDistributedProvider_t

Supported providers of the distributed communication service.

Values:

enumerator CUDENSITYMAT_DISTRIBUTED_PROVIDER_NONE = 0

No communication service provider (single-GPU execution)

enumerator CUDENSITYMAT_DISTRIBUTED_PROVIDER_MPI = 1

MPI communication service.

cudensitymatDistributedCommunicator_t

struct cudensitymatDistributedCommunicator_t

Explicit data structure for storing an inter-process communicator in a type-erased form.

Public Members

void *commPtr

pointer to the MPI_Comm data structure

size_t commSize

size of the MPI_Comm data structure

cudensitymatCallbackDevice_t

enum cudensitymatCallbackDevice_t

Supported target devices for user-defined callbacks.

Values:

enumerator CUDENSITYMAT_CALLBACK_DEVICE_CPU
enumerator CUDENSITYMAT_CALLBACK_DEVICE_GPU

CUDENSITYMAT_ALLOCATOR_NAME_LEN

CUDENSITYMAT_ALLOCATOR_NAME_LEN

The maximal length of the name for a user-provided memory pool.

cudensitymatWorkspaceDescriptor_t

typedef void *cudensitymatWorkspaceDescriptor_t

Opaque data structure describing a workspace memory buffer.

cudensitymatMemspace_t

enum cudensitymatMemspace_t

Memory spaces for workspace buffer allocation.

Values:

enumerator CUDENSITYMAT_MEMSPACE_DEVICE = 0

Device memory space.

enumerator CUDENSITYMAT_MEMSPACE_HOST = 1

Host memory space.

cudensitymatWorkspaceKind_t

enum cudensitymatWorkspaceKind_t

Kinds of workspace memory buffers.

Values:

enumerator CUDENSITYMAT_WORKSPACE_SCRATCH = 0

Scratch workspace memory.

cudensitymatState_t

typedef void *cudensitymatState_t

Opaque data structure holding the quantum state representation.

A quantum state is defined by its purity (pure or mixed), shape (specification of all quantum degrees of freedom), numerical representation (dense tensor or sparse tensor), structural compression (full or factorized tensor), forced symmetries (if any), etc.

Note

Each quantum degree of freedom is represented by a vector space of some dimension. The full quantum state lives in a tensor product space constructed from the vector spaces associated with the given quantum degrees of freedom.

cudensitymatStatePurity_t

enum cudensitymatStatePurity_t

Quantum state purity (pure or mixed state).

Values:

enumerator CUDENSITYMAT_STATE_PURITY_PURE

Pure quantum state.

enumerator CUDENSITYMAT_STATE_PURITY_MIXED

Mixed quantum state.

cudensitymatElementaryOperator_t

typedef void *cudensitymatElementaryOperator_t

Opaque data structure representing an elementary tensor operator (or their batch) acting on a single or multiple quantum degrees of freedom.

cudensitymatElementaryOperatorSparsity_t

enum cudensitymatElementaryOperatorSparsity_t

Elementary operator sparsity kind.

Values:

enumerator CUDENSITYMAT_OPERATOR_SPARSITY_NONE = 0

No sparsity (dense tensor)

enumerator CUDENSITYMAT_OPERATOR_SPARSITY_MULTIDIAGONAL = 1

Multi-diagonal sparsity (one or multiple diagonals)

cudensitymatMatrixOperator_t

typedef void *cudensitymatMatrixOperator_t

Opaque data structure representing a full operator matrix (or their batch) acting on all quantum degrees of freedom.

cudensitymatOperatorTerm_t

typedef void *cudensitymatOperatorTerm_t

Opaque data structure representing an operator term acting on quantum degrees of freedom from either side (for a mixed quantum state it can act either from the ket side or from the bra side whereas for a pure quantum state it can only act from one side).

Generally, an operator term is defined as a sum of components, where each component is either a product of elementary tensor operators or a full matrix operator, with some scalar coefficient. The sum may contain one or more such components. Each product of elementary tensor operators may consist of one or more elementary tensor operators, or contain no elementary tensor operators at all, representing an identity.

cudensitymatOperator_t

typedef void *cudensitymatOperator_t

Opaque data structure representing a composite operator (collection of operator terms with some scalar coefficients) acting on quantum degrees of freedom from either side.

cudensitymatOperatorAction_t

typedef void *cudensitymatOperatorAction_t

Opaque data structure representing a collective r.h.s. action of a given number of composite operators on the corresponding number of input quantum states, producing an update to a single output quantum state (when the actual computation is performed).

This data structure allows specification of a collective operator action where both the operators and the input quantum states may be different in each operator action pair. The action pair is defined as an operator acting on an input quantum state, producing an update to a given output quantum state for all action pairs.

cudensitymatExpectation_t

typedef void *cudensitymatExpectation_t

Opaque data structure specifying the operator expectation value computation.

This data structure encapsulates the desired operator for which it will be able to compute the expectation value over a specified quantum state.

cudensitymatScalarCallback_t

typedef int32_t (*cudensitymatScalarCallback_t)(double time, int64_t batchSize, int32_t numParams, const double *params, cudaDataType_t dataType, void *scalarStorage, cudaStream_t stream)

External CPU/GPU callback function returning a batch of scalar coefficients, including a special case of batch size one (single scalar).

An external user-provided scalar callback function can be registered with the library for deferred invocation at a given point of time: Given the time value and a (batched) array of real parameter values, which parameterize a (batched) quantum operator, it will fill in a batch of scalar coefficients used for defining the (batched) quantum operator. Batch size one corresponds to a single instance (no batching).

Parameters

  • time – [in] Time value.

  • batchSize – [in] User-defined batch size (>=1).

  • numParams – [in] Number of external real parameters the full operator depends on.

  • params – [in] GPU-accessible pointer to an F-ordered 2d-array of user-defined real parameter values: params[numParams, batchSize].

  • dataType – [in] Data type of the returned scalars.

  • scalarStorage – [inout] Pointer to the array storage in a CPU- or GPU-accessible memory buffer of length batchSize.

Returns

int32_t Error code.

cudensitymatTensorCallback_t

typedef int32_t (*cudensitymatTensorCallback_t)(cudensitymatElementaryOperatorSparsity_t sparsity, int32_t numModes, const int64_t modeExtents[], const int32_t diagonalOffsets[], double time, int64_t batchSize, int32_t numParams, const double *params, cudaDataType_t dataType, void *tensorStorage, cudaStream_t stream)

External CPU/GPU callback function returning a batch of tensors, including a special case of batch size one (single tensor).

An external user-provided tensor callback function can be registered with the library for deferred invocation at a given point of time: Given the time value and a (batched) array of real parameter values, which parameterize a (batched) quantum operator, it will fill in a batch of tensors used for representing the (batched) quantum operator. Batch size one corresponds to a single instance (no batching).

Note

A tensor callback function fills in a (batched) dense array which represents a (batched) elementary tensor operator with its specific sparsity kind:

  • CUDENSITYMAT_OPERATOR_SPARSITY_NONE: The returned dense array has exactly the same shape as the elementary tensor operator itself;

  • CUDENSITYMAT_OPERATOR_SPARSITY_MULTIDIAGONAL: The returned dense array has shape [N,M], where N is the dimension of the matrix of the elementary tensor operator, while M is the number of non-zero diagonals of that matrix, padded with trailing zeros to the full matrix dimension. In both cases, the batch mode is appended at the end (most senior mode).

Parameters

  • sparsity – [in] Elementary tensor operator sparsity kind.

  • numModes – [in] Number of modes in the returned data array (without the batch mode).

  • modeExtents – [in] Mode extents in the returned data array (without the batch mode).

  • diagonalOffsets – [in] For CUDENSITYMAT_OPERATOR_SPARSITY_MULTIDIAGONAL, offsets of the stored non-zero diagonals of the elementary tensor operator matrix: The main diagonal has offset zero, the below-main diagonals have negative offsets, the above-main diagonals have positive offsets. For CUDENSITYMAT_OPERATOR_SPARSITY_NONE, this argument has no meaning and can be set to NULL.

  • time – [in] Time value.

  • batchSize – [in] User-defined batch size (>=1).

  • numParams – [in] Number of external real parameters the full operator depends on.

  • params – [in] GPU-accessible pointer to an F-ordered 2d-array of user-defined real parameter values: params[numParams, batchSize].

  • dataType – [in] Data type of the returned array.

  • tensorStorage – [inout] Pointer to the tensor elements storage (array data) in a CPU- or GPU-accessible memory buffer of length batchSize (times tensor shape).

Returns

int32_t Error code.

cudensitymatWrappedScalarCallback_t

struct cudensitymatWrappedScalarCallback_t

Scalar callback wrapper data structure.

A wrapped struct containing the scalar callback and the scalar callback wrapper. The callback wrapper is only used when the library is used from Python and stores a Python callback function. It should be set to NULL when the library is used from C and stores a C callback function.

Public Members

cudensitymatScalarCallback_t callback

Scalar callback function.

cudensitymatCallbackDevice_t device

Device type for the stored callback function (CPU or GPU).

void *wrapper

Wrapper for a scalar callback, should be set to NULL when used from C.

cudensitymatWrappedTensorCallback_t

struct cudensitymatWrappedTensorCallback_t

Tensor callback wrapper data structure.

A wrapped struct containing the tensor callback and the tensor callback wrapper. The callback wrapper is only used when the library is used from Python and stores a Python callback function. It should be set to NULL when the library is used from C and stores a C callback function.

Public Members

cudensitymatTensorCallback_t callback

Tensor callback function.

cudensitymatCallbackDevice_t device

Device type for the stored callback function (CPU or GPU).

void *wrapper

Wrapper for a tensor callback, should be set to NULL when used from C.