cuDensityMat Functions

Library Context Management API

cudensitymatCreate

cudensitymatStatus_t cudensitymatCreate(cudensitymatHandle_t *handle)

Creates and initializes the library context.

Parameters

handle – [out] Library handle.

Returns

cudensitymatStatus_t

cudensitymatDestroy

cudensitymatStatus_t cudensitymatDestroy(cudensitymatHandle_t handle)

Destroys the library context.

Parameters

handle – [in] Library handle.

Returns

cudensitymatStatus_t

cudensitymatResetRandomSeed

cudensitymatStatus_t cudensitymatResetRandomSeed(cudensitymatHandle_t handle, int32_t randomSeed)

Resets the random seed used by the random number generator inside the library context.

Parameters

  • handle – [inout] Library handle.

  • randomSeed – [in] Random seed value.

Returns

cudensitymatStatus_t

Distributed Parallelization API

cudensitymatResetDistributedConfiguration

cudensitymatStatus_t cudensitymatResetDistributedConfiguration(cudensitymatHandle_t handle, cudensitymatDistributedProvider_t provider, const void *commPtr, size_t commSize)

Resets the current distributed execution configuration associated with the given library context.

Accepts and stores a copy of the provided communicator which will be used for distributing numerical operations across all involved distributed processes.

Parameters

  • handle – [inout] Library handle.

  • provider – [in] Communication service provider.

  • commPtr – [in] Pointer to the communicator in a type-erased form.

  • commSize – [in] Size of the communicator in bytes.

Returns

cudensitymatStatus_t

cudensitymatGetNumRanks

cudensitymatStatus_t cudensitymatGetNumRanks(const cudensitymatHandle_t handle, int32_t *numRanks)

Returns the total number of distributed processes associated with the given library context.

Parameters

  • handle – [in] Library handle.

  • numRanks – [out] Number of distributed processes.

Returns

cudensitymatStatus_t

cudensitymatGetProcRank

cudensitymatStatus_t cudensitymatGetProcRank(const cudensitymatHandle_t handle, int32_t *procRank)

Returns the rank of the current process in the distributed configuration associated with the given library context.

Parameters

  • handle – [in] Library handle.

  • procRank – [out] Rank of the current distributed process.

Returns

cudensitymatStatus_t

Workspace Management API

cudensitymatCreateWorkspace

cudensitymatStatus_t cudensitymatCreateWorkspace(const cudensitymatHandle_t handle, cudensitymatWorkspaceDescriptor_t *workspaceDescr)

Creates a workspace descriptor.

Parameters

  • handle – [in] Library handle.

  • workspaceDescr – [out] Workspace descriptor.

Returns

cudensitymatStatus_t

cudensitymatDestroyWorkspace

cudensitymatStatus_t cudensitymatDestroyWorkspace(cudensitymatWorkspaceDescriptor_t workspaceDescr)

Destroys a workspace descriptor.

Parameters

workspaceDescr – [inout] Workspace descriptor.

Returns

cudensitymatStatus_t

cudensitymatWorkspaceGetMemorySize

cudensitymatStatus_t cudensitymatWorkspaceGetMemorySize(const cudensitymatHandle_t handle, const cudensitymatWorkspaceDescriptor_t workspaceDescr, cudensitymatMemspace_t memSpace, cudensitymatWorkspaceKind_t workspaceKind, size_t *memoryBufferSize)

Queries the required workspace buffer size.

Parameters

  • handle – [in] Library handle.

  • workspaceDescr – [in] Workspace descriptor.

  • memSpace – [in] Memory space.

  • workspaceKind – [in] Workspace kind.

  • memoryBufferSize – [out] Required workspace buffer size in bytes.

Returns

cudensitymatStatus_t

cudensitymatWorkspaceSetMemory

cudensitymatStatus_t cudensitymatWorkspaceSetMemory(const cudensitymatHandle_t handle, cudensitymatWorkspaceDescriptor_t workspaceDescr, cudensitymatMemspace_t memSpace, cudensitymatWorkspaceKind_t workspaceKind, void *memoryBuffer, size_t memoryBufferSize)

Attaches memory to a workspace buffer.

Parameters

  • handle – [in] Library handle.

  • workspaceDescr – [inout] Workspace descriptor.

  • memSpace – [in] Memory space.

  • workspaceKind – [in] Workspace kind.

  • memoryBuffer – [in] Pointer to a user-owned memory buffer to be used by the specified workspace.

  • memoryBufferSize – [in] Size of the provided memory buffer in bytes.

Returns

cudensitymatStatus_t

cudensitymatWorkspaceGetMemory

cudensitymatStatus_t cudensitymatWorkspaceGetMemory(const cudensitymatHandle_t handle, const cudensitymatWorkspaceDescriptor_t workspaceDescr, cudensitymatMemspace_t memSpace, cudensitymatWorkspaceKind_t workspaceKind, void **memoryBuffer, size_t *memoryBufferSize)

Retrieves a workspace buffer.

Parameters

  • handle – [in] Library handle.

  • workspaceDescr – [in] Workspace descriptor.

  • memSpace – [in] Memory space.

  • workspaceKind – [in] Workspace kind.

  • memoryBuffer – [out] Pointer to a user-owned memory buffer used by the specified workspace.

  • memoryBufferSize – [out] Size of the memory buffer in bytes.

Returns

cudensitymatStatus_t

Quantum State API

cudensitymatCreateState

cudensitymatStatus_t cudensitymatCreateState(const cudensitymatHandle_t handle, cudensitymatStatePurity_t purity, int32_t numSpaceModes, const int64_t spaceModeExtents[], int64_t batchSize, cudaDataType_t dataType, cudensitymatState_t *state)

Defines an empty quantum state of a given purity and shape, or a batch of such quantum states.

The number of space modes defining the state space is always the number of quantum degrees of freedom used to define the corresponding composite tensor-product space. With that, the number of modes in a pure-state tensor equals the number of space modes (quantum degrees of freedom). The number of modes in a mixed-state tensor equals twice the number of the space modes, consisting of a set of the ket modes and the bra modes, which are identical in terms of their extents between the two sets, and the ket modes precede the bra modes, for example: S[i0, i1, j0, j1] tensor represents a mixed quantum state with two degree of freedom, where modes {i0, i1} form the ket set, and modes {j0, j1} form the bra set such that ket mode i0 corresponds to the bra mode j0, and ket mode i1 corresponds to the bra mode j1. In contrast, a pure quantum state with two degrees of freedom is represented by the tensor S[i0, i1] with only ket modes (no bra modes). Furthermore, batched pure/mixed states add one additional (batch) mode to their dense tensor representation, namely: S[i0, i1, b] for the pure state, and S[i0, i1, j0, j1, b] for the mixed state, where b is the size of the batch (batch dimension).

Parameters

  • handle – [in] Library handle.

  • purity – [in] Desired quantum state purity.

  • numSpaceModes – [in] Number of space modes (number of degrees of freedom).

  • spaceModeExtents – [in] Extents of the space modes (dimensions of the degrees of freedom).

  • batchSize – [in] Batch size (number of equally-shaped quantum states). Setting the batch size to zero is the same as setting it to 1.

  • dataType – [in] Representation data type (type of tensor elements).

  • state – [out] Empty quantum state (or a batch of quantum states).

Returns

cudensitymatStatus_t

cudensitymatDestroyState

cudensitymatStatus_t cudensitymatDestroyState(cudensitymatState_t state)

Destroys the quantum state.

Parameters

state – [in] Quantum state (or a batch of quantum states).

Returns

cudensitymatStatus_t

cudensitymatStateGetNumComponents

cudensitymatStatus_t cudensitymatStateGetNumComponents(const cudensitymatHandle_t handle, const cudensitymatState_t state, int32_t *numStateComponents)

Queries the number of components (tensors) constituting the chosen quantum state representation (on the current process in multi-process runs).

Quantum state representation may include one or more components (tensors) distributed over one or more parallel processes (in distributed multi-GPU runs). The full state vector or density matrix representations consist of only one component, the full state tensor, which can be sliced and distributed over all parallel processes (in distributed multi-GPU runs). Factorized quantum state representations include more than one component, and these components (tensors) are generally distributed over all parallel processes (in distributed multi-GPU runs).

Note

In multi-process runs, this function returns the number of locally stored components which, in general, can be smaller than the total number of components stored across all parallel processes. One can use the API function cudensitymatStateGetComponentInfo to obtain more information on a given local component by providing its local id.

Note

Batching does not add new components to the quantum state representation, it just makes all existing components batched. The corresponding tensors acquire one additional (most significant) mode which represents the batch dimension.

Parameters

  • handle – [in] Library handle.

  • state – [in] Quantum state (or a batch of quantum states).

  • numStateComponents – [out] Number of components (tensors) in the quantum state representation (on the current process).

Returns

cudensitymatStatus_t

cudensitymatStateGetComponentStorageSize

cudensitymatStatus_t cudensitymatStateGetComponentStorageSize(const cudensitymatHandle_t handle, const cudensitymatState_t state, int32_t numStateComponents, size_t componentBufferSize[])

Queries the storage size (in bytes) for each component (tensor) constituting the quantum state representation (on the current process in multi-process runs).

Parameters

  • handle – [in] Library handle.

  • state – [in] Quantum state (or a batch of quantum states).

  • numStateComponents – [in] Number of components (tensors) in the quantum state representation (on the current process).

  • componentSize – [out] Storage size (bytes) for each component (tensor) consituting the quantum state representation (on the current process).

Returns

cudensitymatStatus_t

cudensitymatStateGetComponentNumModes

cudensitymatStatus_t cudensitymatStateGetComponentNumModes(const cudensitymatHandle_t handle, cudensitymatState_t state, int32_t stateComponentLocalId, int32_t *stateComponentGlobalId, int32_t *stateComponentNumModes, int32_t *batchModeLocation)

Queries the number of modes in a local component tensor (on the current process in multi-process runs).

Parameters

  • handle – [in] Library handle.

  • state – [in] Quantum state (or a batch of quantum states).

  • stateComponentLocalId – [in] Component local id (on the current parallel process).

  • stateComponentGlobalId – [out] Component global id (across all parallel processes).

  • stateComponentNumModes – [out] Component tensor order (number of modes).

  • batchModeLocation – [out] Location of the batch mode (or -1 if the batch mode is absent).

Returns

cudensitymatStatus_t

cudensitymatStateGetComponentInfo

cudensitymatStatus_t cudensitymatStateGetComponentInfo(const cudensitymatHandle_t handle, cudensitymatState_t state, int32_t stateComponentLocalId, int32_t *stateComponentGlobalId, int32_t *stateComponentNumModes, int64_t stateComponentModeExtents[], int64_t stateComponentModeOffsets[])

Queries information for a locally stored component tensor which represents either the full component or its slice (on the current process in multi-process runs).

This API function queries the global component id (across all parallel processes), the number of tensor modes (including the batch mode if present), the extents of all modes, and the base offsets for all modes which can be different from zero if the locally stored component tensor represents a slice of the full component tensor. A base offset of a sliced mode is the starting index value of that mode inside the full tensor mode.

Parameters

  • handle – [in] Library handle.

  • state – [in] Quantum state (or a batch of quantum states).

  • stateComponentLocalId – [in] Component local id (on the current parallel process).

  • stateComponentGlobalId – [out] Component global id (across all parallel processes).

  • stateComponentNumModes – [out] Component tensor order (number of modes).

  • stateComponentModeExtents – [out] Component tensor mode extents (the size of the array must be sufficient, see cudensitymatStateGetComponentNumModes)

  • stateComponentModeOffsets – [out] Component tensor mode offsets (the size of the array must be sufficient, see cudensitymatStateGetComponentNumModes)

Returns

cudensitymatStatus_t

cudensitymatStateAttachComponentStorage

cudensitymatStatus_t cudensitymatStateAttachComponentStorage(const cudensitymatHandle_t handle, cudensitymatState_t state, int32_t numStateComponents, void *componentBuffer[], const size_t componentBufferSize[])

Attaches a user-owned GPU-accessible storage buffer for each component (tensor) constituting the quantum state representation (on the current process in multi-process runs).

The provided user-owned GPU-accessible storage buffers will be used for storing components (tensors) constituting the quantum state representation (on the current process in multi-process runs). The initial value of the provided storage buffers will be respected by the library, thus providing a mechanism for specifing any initial value of the quantum state in its chosen representation form. In multi-process runs, the API function cudensitymatGetComponentInfo will return the information which slice of the requested component (tensor) is stored on the current process.

Note

The sizes of the provided storage buffers must be equal or larger to the required sizes retrived via cudensitymatStateGetComponentStorageSize.

Parameters

  • handle – [in] Library handle.

  • state – [inout] Quantum state (or a batch of quantum states)

  • numStateComponents – [in] Number of components (tensors) in the quantum state representation (on the current process).

  • componentBuffer – [in] Pointers to user-owned GPU-accessible storage buffers for all components (tensors) constituting the quantum state representation (on the current process).

  • componentBufferSize – [in] Sizes of the provded storage buffers for all components (tensors) constituting the quantum state representation (on the current process).

Returns

cudensitymatStatus_t

cudensitymatStateInitializeZero

cudensitymatStatus_t cudensitymatStateInitializeZero(const cudensitymatHandle_t handle, cudensitymatState_t state, cudaStream_t stream)

Initializes the quantum state to zero (null state).

Parameters

  • handle – [in] Library handle.

  • state – [inout] Quantum state (or a batch of quantum states).

  • stream – [in] CUDA stream.

Returns

cudensitymatStatus_t

cudensitymatStateComputeScaling

cudensitymatStatus_t cudensitymatStateComputeScaling(const cudensitymatHandle_t handle, cudensitymatState_t state, const void *scalingFactors, cudaStream_t stream)

Initializes the quantum state to a random value.

Computes multiplication of the quantum state(s) by a scalar factor(s).

Parameters

  • handle – [in] Library handle.

  • state – [inout] Quantum state (or a batch of quantum states).

  • stream – [in] CUDA stream.

  • handle – [in] Library handle.

  • state – [inout] Quantum state (or a batch of quantum states).

  • scalingFactors – [in] Array of scaling factor(s) of dimension equal to the batch size in the GPU-accessible RAM (same data type as used by the state).

  • stream – [in] CUDA stream.

Returns

cudensitymatStatus_t

Returns

cudensitymatStatus_t

cudensitymatStateComputeNorm

cudensitymatStatus_t cudensitymatStateComputeNorm(const cudensitymatHandle_t handle, const cudensitymatState_t state, void *norm, cudaStream_t stream)

Computes the squared Frobenius norm(s) of the quantum state(s).

The result is generally a vector of dimension equal to the state batch size.

Note

For quantum states represented by complex data types, the actual data type of the returned norm is float for cuFloatComplex and double for cuDoubleComplex, respectively.

Note

For quantum states represented by FP32 complex numbers the norm type is float; For quantum states represented by FP64 complex numbers the norm type is double.

Parameters

  • handle – [in] Library handle.

  • state – [in] Quantum state (or a batch of quantum states).

  • norm – [out] Pointer to the squared Frobenius norm(s) vector storage in the GPU-accessible RAM (float or double real data type).

  • stream – [in] CUDA stream.

Returns

cudensitymatStatus_t

cudensitymatStateComputeTrace

cudensitymatStatus_t cudensitymatStateComputeTrace(const cudensitymatHandle_t handle, const cudensitymatState_t state, void *trace, cudaStream_t stream)

Computes the trace(s) of the quantum state(s).

Trace of a pure state is defined to be its squared norm. Trace of a mixed state is equal to the trace of its density matrix. The result is generally a vector of dimension equal to the state batch size.

Parameters

  • handle – [in] Library handle.

  • state – [in] Quantum state (or a batch of quantum states).

  • norm – [out] Pointer to the trace(s) vector storage in the GPU-accessible RAM (same data type as used by the state).

  • stream – [in] CUDA stream.

Returns

cudensitymatStatus_t

cudensitymatStateComputeAccumulation

cudensitymatStatus_t cudensitymatStateComputeAccumulation(const cudensitymatHandle_t handle, const cudensitymatState_t stateIn, cudensitymatState_t stateOut, const void *scalingFactors, cudaStream_t stream)

Computes accumulation of a quantum state(s) into another quantum state(s) of compatible shape.

Parameters

  • handle – [in] Library handle.

  • stateIn – [in] Accumulated quantum state (or a batch of quantum states).

  • stateOut – [inout] Accumulating quantum state (or a batch of quantum states).

  • scalingFactors – [in] Array of scaling factor(s) of dimension equal to the batch size in the GPU-accessible RAM (same data type as used by the state).

  • stream – [in] CUDA stream.

Returns

cudensitymatStatus_t

cudensitymatStateComputeInnerProduct

cudensitymatStatus_t cudensitymatStateComputeInnerProduct(const cudensitymatHandle_t handle, const cudensitymatState_t stateLeft, const cudensitymatState_t stateRight, void *innerProduct, cudaStream_t stream)

Computes the inner product(s) between the left quantum state(s) and the right quantum state(s): < state(s)Left | state(s)Right >

For pure quantum states, this function computes the regular Hilbert-space inner product. For mixed quantum states, it computes the matrix inner product induced by the Frobenius matrix norm: The sum of regular Hilbert-space inner products for all columns of two density matrices.

The result is generally a vector of dimension equal to the batch size of both states, which must be the same. The participating quantum states must have compatible shapes.

Parameters

  • handle – [in] Library handle.

  • stateLeft – [in] Left quantum state (or a batch of quantum states).

  • stateRight – [in] Right quantum state (or a batch of quantum states).

  • innerProduct – [out] Pointer to the inner product(s) vector storage in the GPU-accessible RAM (same data type as the one used by the quantum states).

  • stream – [in] CUDA stream.

Returns

cudensitymatStatus_t

Quantum Operator API

cudensitymatCreateElementaryOperator

cudensitymatStatus_t cudensitymatCreateElementaryOperator(const cudensitymatHandle_t handle, int32_t numSpaceModes, const int64_t spaceModeExtents[], cudensitymatElementaryOperatorSparsity_t sparsity, int32_t numDiagonals, const int32_t diagonalOffsets[], cudaDataType_t dataType, void *tensorData, cudensitymatWrappedTensorCallback_t tensorCallback, cudensitymatElementaryOperator_t *elemOperator)

Creates an elementary tensor operator acting on a given number of quantum state modes (aka space modes).

An elementary tensor operator is a single tensor operator acting on a specific subset of space modes (quantum degrees of freedom). The tensor operator is composed of a set of ket modes and a set of corresponding bra modes of matching extents, where both sets have the same number of modes, and the ket modes precede the bra modes, both in the same order. For example, T[i0, i1, j0, j1] is a 2-body tensor operator in which modes {i0, i1} form a set of ket modes while modes {j0, j1} form the corresponding set of bra modes, where ket mode i0 corresponds to the bra mode j0, and ket mode i1 corresponds to the bra mode j1 (the modes are always paired this way). Only one mode in each pair of corresponding modes is contracted with the quantum state tensor, either from the left or from the right. For example, either the bra mode j0 is contracted with a specific ket mode of the quantum state, representing an operator action from the left, or the ket mode i0 is contracted with a specific bra mode of the quantum state, representing an operator action from the right. Then, the remaining uncontracted mode replaces the contratcted mode of the quantum state.

Storage of tensor elements in memory:

  • CUDENSITYMAT_OPERATOR_SPARSITY_NONE: Dense tensor stored using the generalized column-wise layout.

  • CUDENSITYMAT_OPERATOR_SPARSITY_MULTIDIAGONAL: The full non-zero diagonals are stored in a concatenated form following the order how they appear in the diagonalOffsets argument.

Warning

Different elementary tensor operators must not use the same or overlapping GPU storage buffers, otherwise it will cause undefined behavior.

Parameters

  • handle – [in] Library handle.

  • numSpaceModes – [in] Number of the (state) space modes acted on.

  • spaceModeExtents – [in] Extents of the (state) space modes acted on.

  • sparsity – [in] Tensor operator sparsity defining the storage scheme.

  • numDiagonals – [in] For multi-diagonal tensor operator matrices, specifies the total number of non-zero diagonals.

  • diagonalOffsets – [in] Offsets of the non-zero diagonals (for example, the main diagonal has offset 0, the diagonal right above the main diagonal has offset +1, the diagonal right below the main diagonal has offset -1, and so on).

  • dataType – [in] Tensor operator data type.

  • tensorData – [in] GPU-accessible pointer to the tensor operator elements storage.

  • tensorCallback – [in] Optional user-defined tensor callback function which can be called later to fill in the tensor elements in the provided storage, or NULL.

  • elemOperator – [out] Elementary tensor operator.

Returns

cudensitymatStatus_t

cudensitymatDestroyElementaryOperator

cudensitymatStatus_t cudensitymatDestroyElementaryOperator(cudensitymatElementaryOperator_t elemOperator)

Destroys an elementary tensor operator.

Parameters

elemOperator – [in] Elementary tensor operator.

Returns

cudensitymatStatus_t

cudensitymatCreateOperatorTerm

cudensitymatStatus_t cudensitymatCreateOperatorTerm(const cudensitymatHandle_t handle, int32_t numSpaceModes, const int64_t spaceModeExtents[], cudensitymatOperatorTerm_t *operatorTerm)

Creates an empty operator term which is going to be a sum of tensor products of individual tensor operators, where each individual tensor operator within a product acts on disjoint quantum state modes (quantum degrees of freedom).

Note

The created operator term will only be able to act on the quantum states which reside in the same space where the operator is set to act.

Parameters

  • handle – [in] Library handle.

  • numSpaceModes – [in] Number of modes (degrees of freedom) defining the primary/dual tensor product space in which the operator term will act.

  • spaceModeExtents – [in] Extents of the modes (degrees of freedom) defining the primary/dual tensor product space in which the operator term will act.

  • operatorTerm – [out] Operator term.

Returns

cudensitymatStatus_t

cudensitymatDestroyOperatorTerm

cudensitymatStatus_t cudensitymatDestroyOperatorTerm(cudensitymatOperatorTerm_t operatorTerm)

Destroys an operator term.

Parameters

operatorTerm – [in] Operator term.

Returns

cudensitymatStatus_t

cudensitymatOperatorTermAppendElementaryProduct

cudensitymatStatus_t cudensitymatOperatorTermAppendElementaryProduct(const cudensitymatHandle_t handle, cudensitymatOperatorTerm_t operatorTerm, int32_t numElemOperators, const cudensitymatElementaryOperator_t elemOperators[], const int32_t stateModesActedOn[], const int32_t modeActionDuality[], cuDoubleComplex coefficient, cudensitymatWrappedScalarCallback_t coefficientCallback)

Appends a product of elementary tensor operators acting on quantum state modes to the operator term.

Parameters

  • handle – [in] Library handle.

  • operatorTerm – [inout] Operator term.

  • numElemOperators – [in] Number of elementary tensor operators in the tensor operator product.

  • elemOperators – [in] Elementary tensor operators constituting the tensor operator product.

  • stateModesActedOn – [in] State modes acted on by the tensor operator product. This is a concatenated list of the state modes acted on by all constituting elementary tensor operators in the same order how they appear in the elemOperators argument.

  • modeActionDuality – [in] Duality status of each mode action, that is, whether the action applies to a ket mode of the quantum state (value 0) or a bra mode of the quantum state (value 1 or other non-zero).

  • coefficient – [in] Constant complex scalar coefficient associated with the tensor operator product.

  • coefficientCallback – [in] User-defined complex scalar callback function which can be called later to update the scalar coefficient associated with the tensor operator product, or NULL. The total coefficient associated with the tensor operator product is a product of the constant coefficient and the result of the scalar callback function, if defined.

Returns

cudensitymatStatus_t

cudensitymatOperatorTermAppendGeneralProduct

cudensitymatStatus_t cudensitymatOperatorTermAppendGeneralProduct(const cudensitymatHandle_t handle, cudensitymatOperatorTerm_t operatorTerm, int32_t numElemOperators, const int32_t numOperatorModes[], const int64_t *operatorModeExtents[], const int64_t *operatorModeStrides[], const int32_t stateModesActedOn[], const int32_t modeActionDuality[], cudaDataType_t dataType, void *tensorData[], cudensitymatWrappedTensorCallback_t tensorCallbacks[], cuDoubleComplex coefficient, cudensitymatWrappedScalarCallback_t coefficientCallback)

Appends a product of generic dense tensor operators acting on different quantum state modes to the operator term.

This is a slightly more general version of cudensitymatOperatorTermAppendElementaryProduct which does not require explicit construction of the cudensitymatElementaryOperator_t objects. Additionally, it accepts specification of tensor storage strides when describing the raw dense tensors representing tensor operators in the provided tensor operator product. On the other hand, it does not allow specification of the tensor operator sparsity, thus resulting in reduced performance for such cases.

Warning

Dense tensor operators from the appended tensor product must not share GPU storage buffers. Each tensor operator appended to the operator term as part of the tensor product via this API function must have its own GPU storage buffer.

Parameters

  • handle – [in] Library handle.

  • operatorTerm – [inout] Operator term.

  • numElemOperators – [in] Number of dense tensor operators in the given tensor operator product.

  • numOperatorModes – [in] Number of modes in each tensor operator (twice the number of state modes it acts on).

  • operatorModeExtents – [in] Mode extents for each dense tensor operator.

  • operatorModeStrides – [in] Mode strides for each dense tensor operator. If a specific element is set to NULL, the corresponding dense tensor operator will assume the default generalized column-wise storage strides.

  • stateModesActedOn – [in] State modes acted on by the tensor operator product. This is a concatenated list of the state modes acted on by all constituting dense tensor operators in the same order how they appear in the above arguments.

  • modeActionDuality – [in] Duality status of each mode action, whether the action applies to a ket mode of the quantum state (value 0) or a bra mode of the quantum state (value 1 or other non-zero).

  • dataType – [in] Data type (for all dense tensor operators).

  • tensorData – [in] GPU-accessible pointers to the elements of each dense tensor operator constituting the tensor operator product.

  • tensorCallbacks – [in] User-defined tensor callback functions which can be called later to update the elements of each dense tensor operator (any of the callbacks can be NULL).

  • coefficient – [in] Constant complex scalar coefficient associated with the tensor operator product.

  • coefficientCallback – [in] User-defined complex scalar callback function which can be called later to update the scalar coefficient associated with the tensor operator product, or NULL. The total coefficient associated with the tensor operator product is a product of the constant coefficient and the result of the scalar callback function, if defined.

Returns

cudensitymatStatus_t

cudensitymatCreateOperator

cudensitymatStatus_t cudensitymatCreateOperator(const cudensitymatHandle_t handle, int32_t numSpaceModes, const int64_t spaceModeExtents[], cudensitymatOperator_t *superoperator)

Creates an empty operator which is going to be a collection of operator terms.

If the operator is expected to act on a pure quantum state, it is just a regular operator that will act on the pure state vector from one side. If the operator is expected to act on a mixed quantum state, its action can become more complicated where it may act on both sides of the density matrix representing the mixed quantum state. In this case, the operator is specifically called the super-operator. However, one should note that in both cases this is still a mathematical operator, just acting on a different kind of mathematical vector.

Note

The created operator will only be able to act on the quantum states which reside in the same space where the operator is set to act.

Parameters

  • handle – [in] Library handle.

  • numSpaceModes – [in] Number of modes (degrees of freedom) defining the primary/dual tensor product space in which the operator term will act.

  • spaceModeExtents – [in] Extents of the modes (degrees of freedom) defining the primary/dual tensor product space in which the operator term will act.

  • superoperator – [out] Operator.

Returns

cudensitymatStatus_t

cudensitymatDestroyOperator

cudensitymatStatus_t cudensitymatDestroyOperator(cudensitymatOperator_t superoperator)

Destroys an operator.

Parameters

superoperator – [in] Operator.

Returns

cudensitymatStatus_t

cudensitymatOperatorAppendTerm

cudensitymatStatus_t cudensitymatOperatorAppendTerm(const cudensitymatHandle_t handle, cudensitymatOperator_t superoperator, cudensitymatOperatorTerm_t operatorTerm, int32_t duality, cuDoubleComplex coefficient, cudensitymatWrappedScalarCallback_t coefficientCallback)

Appends an operator term to the operator.

Parameters

  • handle – [in] Library handle.

  • superoperator – [inout] Operator.

  • operatorTerm – [in] Operator term.

  • duality – [in] Duality status of the operator term action as a whole. If not zero, the duality status of each mode action inside the operator term will be flipped, that is, action from the left will be replaced by action from the right, and vice versa.

  • coefficient – [in] Constant complex scalar coefficient associated with the operator term.

  • coefficientCallback – [in] User-defined complex scalar callback function which can be called later to update the scalar coefficient associated with the operator term, or NULL. The total coefficient associated with the operator term is a product of the constant coefficient and the result of the scalar callback function, if defined.

Returns

cudensitymatStatus_t

cudensitymatOperatorPrepareAction

cudensitymatStatus_t cudensitymatOperatorPrepareAction(const cudensitymatHandle_t handle, const cudensitymatOperator_t superoperator, const cudensitymatState_t stateIn, const cudensitymatState_t stateOut, cudensitymatComputeType_t computeType, size_t workspaceSizeLimit, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)

Prepares the operator for an action on a quantum state.

In general, before the operator action on a specific quantum state(s) can be computed, it needs to be prepared for computation first, which is the purpose of this API function.

Note

The required size of the workspace buffer returned inside the workspace descriptor may sometimes be zero, in which case there is no need to allocate a workspace buffer.

Parameters

  • handle – [in] Library handle.

  • superoperator – [in] Operator.

  • stateIn – [in] Representative input quantum state on which the operator is supposed to act. The actual state acted on during computation may be different, but it has to be of the same shape, kind, and factorization structure (topology, bond dimensions, etc).

  • stateOut – [in] Representative output quantum state produced by the action of the operator on the input quantum state. The actual state acted on during computation may be different, but it has to be of the same shape, kind, and factorization structure (topology, bond dimensions, etc).

  • computeType – [in] Desired compute type.

  • workspaceSizeLimit – [in] Workspace buffer size limit (bytes).

  • workspace – [inout] Empty workspace descriptor on entrance. The workspace size required for the computation will be set on exit.

  • stream – [in] CUDA stream.

Returns

cudensitymatStatus_t

cudensitymatOperatorComputeAction

cudensitymatStatus_t cudensitymatOperatorComputeAction(const cudensitymatHandle_t handle, const cudensitymatOperator_t superoperator, double time, int32_t numParams, const double params[], const cudensitymatState_t stateIn, cudensitymatState_t stateOut, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)

Computes the action of the operator on a given input quantum state, accumulating the result in the output quantum state (accumulative action).

Note

The provided input and output quantum states must be of the same kind, shape, and structure as the quantum states provided during the preceding preparation phase.

Warning

The output quantum state cannot coincide with the input quantum state.

Parameters

  • handle – [in] Library handle.

  • superoperator – [in] Operator.

  • time – [in] Time value.

  • numParams – [in] Number of variable parameters defined by the user.

  • params – [in] Variable parameters defined by the user.

  • stateIn – [in] Input quantum state (or a batch of input quantum states).

  • stateOut – [inout] Updated resulting quantum state which accumulates operator action on the input quantum state.

  • workspace – [in] Allocated workspace descriptor.

  • stream – [in] CUDA stream.

Returns

cudensitymatStatus_t

cudensitymatCreateOperatorAction

cudensitymatStatus_t cudensitymatCreateOperatorAction(const cudensitymatHandle_t handle, int32_t numOperators, cudensitymatOperator_t operators[], cudensitymatOperatorAction_t *operatorAction)

Creates an action descriptor for one or more operators, thus defining an aggregate action of the operator(s) on a set of input quantum states compliant with the operator domains, where all input quantum states can also be batched.

Specification of an operator itself is generally insufficient for specifying the r.h.s. of the desired ordinary differential equation (ODE) defining the evolution of the quantum state in time. In general, the ODE r.h.s. specification requires specifying the action of one or more operators on one or more (batched) quantum states (normally, density matrices). The abstraction of the OperatorAction serves exactly this purpose. When the aggregate operator action is computed, each provided operator will act on its own input quantum state producing a contribution to the same output quantum state.

Note

Sometimes one needs to solve a coupled system of ordinary differential equations where a number of quantum states are simultaneously evolved in time. In such a case, not all quantum states have to affect the evolution of a given one of them. To handle such cases, some of the operator-state products, which do not contribute, can be set to zero by setting the corresponding entry of the operators[] argument to NULL.

Parameters

  • handle – [in] Library handle.

  • numOperators – [in] Number of operators involved (number of operator-state products).

  • operators – [in] Constituting operator(s) with the same domain of action. Some of the operators may be set to NULL to represent zero action on a specific input quantum state.

  • operatorAction – [out] Operator action.

Returns

cudensitymatStatus_t

cudensitymatDestroyOperatorAction

cudensitymatStatus_t cudensitymatDestroyOperatorAction(cudensitymatOperatorAction_t operatorAction)

Destroys the operator action descriptor.

Parameters

operatorAction – [in] Operator action.

Returns

cudensitymatStatus_t

cudensitymatOperatorActionPrepare

cudensitymatStatus_t cudensitymatOperatorActionPrepare(const cudensitymatHandle_t handle, cudensitymatOperatorAction_t operatorAction, const cudensitymatState_t stateIn[], const cudensitymatState_t stateOut, cudensitymatComputeType_t computeType, size_t workspaceSizeLimit, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)

Prepares the (aggregate) operator(s) action for computation.

In general, before the (aggregate) operator(s) action on specific quantum states can be computed, it needs to be prepared for computation first, which is the purpose of this API function.

Note

The required size of the workspace buffer returned inside the workspace descriptor may sometimes be zero, in which case there is no need to allocate a workspace buffer.

Parameters

  • handle – [in] Library handle.

  • operatorAction – [inout] Operator(s) action specification.

  • stateIn – [in] Input quantum state(s) for all operator(s) defining the current Operator Action. Each input quantum state can be a batch of quantum states itself (with the same batch dimension).

  • stateOut – [in] Updated output quantum state (or a batch) which accumulates the (aggregate) operator(s) action on all input quantum state(s).

  • computeType – [in] Desired compute type.

  • workspaceSizeLimit – [in] Workspace buffer size limit (bytes).

  • workspace – [inout] Empty workspace descriptor on entrance. The workspace size required for the computation will be set on exit.

  • stream – [in] CUDA stream.

Returns

cudensitymatStatus_t

cudensitymatOperatorActionCompute

cudensitymatStatus_t cudensitymatOperatorActionCompute(const cudensitymatHandle_t handle, cudensitymatOperatorAction_t operatorAction, double time, int32_t numParams, const double params[], const cudensitymatState_t stateIn[], cudensitymatState_t stateOut, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)

Executes the action of one or more operators constituting the aggreggate operator(s) action on the same number of input quantum states, accumulating the results into a single output quantum state.

Note

The output quantum state cannot be one of the input quantum states.

Parameters

  • handle – [in] Library handle.

  • operatorAction – [inout] Operator(s) action.

  • time – [in] Time value.

  • numParams – [in] Number of variable parameters defined by the user.

  • params – [in] Variable parameters defined by the user.

  • stateIn – [in] Input quantum state(s). Each input quantum state can be a batch of quantum states, in general.

  • stateOut – [inout] Updated output quantum state which accumulates operator action(s) on all input quantum state(s).

  • workspace – [in] Allocated workspace descriptor.

  • stream – [in] CUDA stream.

Returns

cudensitymatStatus_t

Operator Expectation API

cudensitymatCreateExpectation

cudensitymatStatus_t cudensitymatCreateExpectation(const cudensitymatHandle_t handle, cudensitymatOperator_t superoperator, cudensitymatExpectation_t *expectation)

Creates the operator expectation value computation object.

Note

The unnormalized expectation value will be produced during the computation. If the quantum state is not normalized, one will need to additionally compute the state norm or trace in order to obtain the normalized operator expectation value.

Note

The operator must stay alive during the lifetime of the Expectation object.

Parameters

  • handle – [in] Library handle.

  • superoperator – [in] Operator.

  • expectation – [out] Expectation value object.

Returns

cudensitymatStatus_t

cudensitymatDestroyExpectation

cudensitymatStatus_t cudensitymatDestroyExpectation(cudensitymatExpectation_t expectation)

Destroys an expectation value object.

Parameters

expectation – [in] Expectation value object.

Returns

cudensitymatStatus_t

cudensitymatExpectationPrepare

cudensitymatStatus_t cudensitymatExpectationPrepare(const cudensitymatHandle_t handle, cudensitymatExpectation_t expectation, const cudensitymatState_t state, cudensitymatComputeType_t computeType, size_t workspaceSizeLimit, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)

Prepares the expectation value object for computation.

In general, before the expectation value can be computed, it needs to be prepared for computation first, which is the purpose of this API function.

Note

The required size of the workspace buffer returned inside the workspace descriptor may sometimes be zero, in which case there is no need to allocate a workspace buffer.

Parameters

  • handle – [in] Library handle.

  • expectation – [inout] Expectation value object.

  • state – [in] Quantum state (or a batch of quantum states).

  • computeType – [in] Desired compute type.

  • workspaceSizeLimit – [in] Workspace buffer size limit (bytes).

  • workspace – [inout] Empty workspace descriptor on entrance. The workspace size required for the computation will be set on exit.

  • stream – [in] CUDA stream.

Returns

cudensitymatStatus_t

cudensitymatExpectationCompute

cudensitymatStatus_t cudensitymatExpectationCompute(const cudensitymatHandle_t handle, cudensitymatExpectation_t expectation, double time, int32_t numParams, const double params[], const cudensitymatState_t state, void *expectationValue, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)

Computes the operator expectation value(s) with respect to the given quantum state(s).

The result is generally a vector of dimension equal to the state batch size.

Parameters

  • handle – [in] Library handle.

  • expectation – [in] Expectation value object.

  • time – [in] Specified time.

  • numParams – [in] Number of variable parameters defined by the user.

  • params – [in] Variable parameters defined by the user.

  • state – [in] Quantum state (or a batch of quantum states).

  • expectationValue – [out] Pointer to the expectation value(s) vector storage in GPU-accessible RAM of the same data type as used by the state and operator.

  • workspace – [in] Allocated workspace descriptor.

  • stream – [in] CUDA stream.

Returns

cudensitymatStatus_t