cuDensityMat Data Types

cudensitymatHandle_t

typedef void *cudensitymatHandle_t

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

This handle holds the library context (device properties, system information, etc.). The handle must be initialized and destroyed using the cudensitymatCreate() and cudensitymatDestroy() 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_CUDMLVER_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_64F = (1U << 4U)
enumerator CUDENSITYMAT_COMPUTE_32F = (1U << 2U)

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.

enumerator CUDENSITYMAT_DISTRIBUTED_PROVIDER_NCCL = 2

NCCL communication service (may require MPI as well)

enumerator CUDENSITYMAT_DISTRIBUTED_PROVIDER_NVSHMEM = 3

NVSHMEM communication service.

cudensitymatDistributedCommunicator_t

struct cudensitymatDistributedCommunicator_t

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

Public Members

void *commPtr

owning pointer to the MPI_Comm data structure

size_t commSize

size of the MPI_Comm data structure

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 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 buffers.

Values:

enumerator CUDENSITYMAT_WORKSPACE_SCRATCH = 0

Scratch workspace memory.

cudensitymatState_t

typedef void *cudensitymatState_t

Opaque data structure holding the quantum state representation.

The quantum state is defined by its purity (pure or mixed), shape (specification of all quantum degrees of freedom), numerical representation (tensor or matrix), structural compression (tensor network or eigen decomposition), explicit 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 quantum degrees of freedom. Additionally, a projected quantum state can be introduced by projecting the full quantum state space to a lower-dimensional subspace.

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

cudensitymatOperatorTerm_t

typedef void *cudensitymatOperatorTerm_t

Opaque data structure representing an operator term that can act on a single or multiple quantum degrees of freedom from either side of the mixed quantum state, i.e., either from the ket side or from the bra side. For pure quantum states, it can only act from one side.

Generally, an operator term is defined as a sum of products of individual tensor operators, where each individual tensor operator within a product acts on disjoint quantum degrees of freedom. The sum may contain one or more such products, where each product may consist of one or more tensor operators.

cudensitymatOperator_t

typedef void *cudensitymatOperator_t

Opaque data structure representing a composite operator (collection of operator terms) that can act on a single or multiple degrees of freedom from either side of the mixed quantum state, i.e., either from the ket side or from the bra side. For pure quantum states, it can only act from one side.

Here the operator is defined as a collection of one or more operator terms.

cudensitymatOperatorAction_t

typedef void *cudensitymatOperatorAction_t

Opaque data structure representing a collective action of a given number of operators on the corresponding number of input quantum states, producing an update on 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 action pair. The action pair is defined as an operator acting on an input quantum state, producing an update on the same output quantum state for each action pair.

cudensitymatExpectation_t

typedef void *cudensitymatExpectation_t

Opaque data structure specifying the operator expectation value computation.

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

cudensitymatScalarCallback_t

typedef int32_t (*cudensitymatScalarCallback_t)(double time, int32_t numParams, const double params[], cudaDataType_t dataType, void *scalarStorage)

External callback function returning a scalar.

An external user-provided scalar callback function can be registered with the library for deferred invocation at a given point of time, supplied with some given real parameter values.

Parameters

  • time – [in] Time value.

  • numParams – [in] Number of external real parameters.

  • params – [in] Array of the real parameter values.

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

  • scalarStorage – [inout] Pointer to the scalar storage in CPU-accessible memory.

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, int32_t numParams, const double params[], cudaDataType_t dataType, void *tensorStorage)

External callback function returning a tensor.

An external user-defined tensor callback function can be registered with the library for deferred invocation at a given point of time, supplied with some given real parameter values.

Note

A tensor callback function fills in a dense array which represents an 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.

Parameters

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

  • numModes – [in] Number of modes in the returned data array.

  • modeExtents – [in] Mode extents in the returned data array.

  • 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.

  • numParams – [in] Number of external real parameters.

  • params – [in] Array of the real parameter values.

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

  • tensorStorage – [inout] Pointer to the tensor elements storage (array data) in CPU-accessible memory.

Returns

int32_t Error code.

cudensitymatWrappedScalarCallback_t

struct cudensitymatWrappedScalarCallback_t

Callback wrapper structs.

cudensitymatWrappedTensorCallback_t

struct cudensitymatWrappedTensorCallback_t