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 context-level 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 by importing a user-provided inter-process communicator (e.g., MPI_Comm).

Accepts and stores a copy of the provided inter-process 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 in its current distributed execution configuration.

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 execution 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 the 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 a set of the bra modes, which are identical in terms of their extents between the two sets, with the ket modes preceding the bra modes, for example: S[i0, i1, j0, j1] tensor represents a mixed quantum state with two degrees 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 the ket modes (no bra modes). Furthermore, batched pure/mixed states introduce one additional (batch) mode to their dense tensor representation, namely: S[i0, i1, b] for the batched pure state, and S[i0, i1, j0, j1, b] for the batched mixed state, where b is the size of the batch (batch size or extent of the batch mode).

Parameters

  • handle – [in] Library handle.

  • purity – [in] Desired quantum state purity.

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

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

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

  • dataType – [in] Numerical 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 plain 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 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. Note, however, that the batch dimension of a locally stored component may have a smaller extent than the total batch size due to potential slicing.

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

  • componentBufferSize – [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] Number of modes in the queried component tensor.

  • 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] Number of modes in the queried component tensor.

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

  • stateComponentModeOffsets – [out] Component tensor mode offsets defining the locally stored slice (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, API function cudensitymatGetComponentInfo can be used for retrieving the information on 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 than the required sizes retrieved 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). The number of components can be retrived by calling the API function cudensitymatStateGetNumComponents.

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

Note

This API function is typically used for initializing the output quantum state to true zero before accumulating in it the action of an operator on some input quantum 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)

Multiplies the quantum state(s) by a scalar factor(s).

Parameters

  • 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 quantum state).

  • stream – [in] CUDA stream.

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 quantum 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 quantum state is defined to be its squared norm. Trace of a mixed quantum state is equal to the trace of its density matrix. The result is generally a vector of dimension equal to the quantum state batch size.

Parameters

  • handle – [in] Library handle.

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

  • trace – [out] Pointer to the trace(s) vector storage in the GPU-accessible RAM (same data type as used by the quantum 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 quantum 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 quantum 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, cudensitymatWrappedTensorGradientCallback_t tensorGradientCallback, 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 set of space modes (quantum degrees of freedom). A tensor operator is composed of a set of the ket modes and a set of the 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 the ket modes while modes {j0, j1} form the corresponding set of the bra modes, where the ket mode i0 corresponds to the bra mode j0, and the ket mode i1 corresponds to the bra mode j1 (the modes are always paired this way). Only one mode in each pair of the 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 corresponding remaining uncontracted mode replaces the contracted 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. The length of each stored diagonal is equal to the full matrix dimension, padded with trailing zeros for non-main diagonals.

Note

Currently the multi-diagonal storage format is only supported by 1-body elementary tensor operators (restriction subject to lifting in future).

Warning

Different elementary tensor operators must not use the same or overlapping GPU storage buffers, otherwise it will cause an 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 (>= 1), otherwise ignored.

  • diagonalOffsets – [in] For multi-diagonal tensor operator matrices, these are the 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.

  • tensorGradientCallback – [in] Optional user-defined tensor gradient callback function which can be called later to compute the Vector-Jacobian Product (VJP) for the tensor operator, to produce gradients with respect to the user-defined real parameters, or NULL.

  • elemOperator – [out] Elementary tensor operator.

Returns

cudensitymatStatus_t

cudensitymatCreateElementaryOperatorBatch

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

Creates a batch of elementary tensor operators acting on a given number of quantum state modes (aka space modes). This is a batched version of the cudensitymatCreateElementaryOperator API function.

This API function is used to create a batch of elementary tensor operators of the same shape stored contiguously in memory, where the batch size must match the batch size of the quantum state acted on. An elementary tensor operator is a single tensor operator acting on a specific set of space modes (quantum degrees of freedom). A tensor operator is composed of a set of the ket modes and a set of the 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 the ket modes while modes {j0, j1} form the corresponding set of the bra modes, where the ket mode i0 corresponds to the bra mode j0, and the ket mode i1 corresponds to the bra mode j1 (the modes are always paired this way). Only one mode in each pair of the 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 corresponding remaining uncontracted mode replaces the contracted 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. The length of each stored diagonal is equal to the full matrix dimension, padded with trailing zeros for non-main diagonals.

Note

Currently the multi-diagonal storage format is only supported by 1-body elementary tensor operators (restriction subject to lifting in future). Furthermore, all elementary tensor operators within the batch are assumed to have the same sparse structure in terms of which matrix diagonals are stored, that is, the same diagonalOffsets.

Warning

Different elementary tensor operators must not use the same or overlapping GPU storage buffers, otherwise it will cause an 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.

  • batchSize – [in] Batch size (>= 1).

  • 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 (>= 1).

  • 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, where all elementary tensor operators within the batch are stored contiguously in memory.

  • tensorCallback – [in] Optional user-defined batched tensor callback function which can be called later to fill in the tensor elements in the provided batched storage, or NULL. Note that the provided batched tensor callback function is expected to fill in all tensor instances within the batch in one call.

  • tensorGradientCallback – [in] Optional user-defined batched tensor gradient callback function which can be called later to compute the Vector-Jacobian Product (VJP) for the batched tensor operator, to produce gradients with respect to the batched user-defined real parameters, or NULL.

  • elemOperator – [out] Batched elementary tensor operator (a batch of individual elementary tensor operators stored contiguously in memory).

Returns

cudensitymatStatus_t

cudensitymatDestroyElementaryOperator

cudensitymatStatus_t cudensitymatDestroyElementaryOperator(cudensitymatElementaryOperator_t elemOperator)

Destroys an elementary tensor operator (simple or batched).

Parameters

elemOperator – [in] Elementary tensor operator.

Returns

cudensitymatStatus_t

cudensitymatCreateMatrixOperatorDenseLocal

cudensitymatStatus_t cudensitymatCreateMatrixOperatorDenseLocal(const cudensitymatHandle_t handle, int32_t numSpaceModes, const int64_t spaceModeExtents[], cudaDataType_t dataType, void *matrixData, cudensitymatWrappedTensorCallback_t matrixCallback, cudensitymatWrappedTensorGradientCallback_t matrixGradientCallback, cudensitymatMatrixOperator_t *matrixOperator)

Creates a full matrix operator acting on all quantum state modes (aka space modes) from a dense matrix stored (replicated) locally on each process.

A full matrix operator is a single tensor operator represented by its square matrix acting in the full Hilbert space. The dimension of the matrix is equal to the product of the extents of all space modes. The elements of the provided dense matrix are expected to be stored exactly in the same way as if the matrix operator was defined as an elementary tensor operator acting in the full space (acting on all space modes), please see description of the cudensitymatCreateElementaryOperator API function.

Note

The optional matrix callback function is still expected to take the actual tensor shape of the defined full matrix operator, namely, the tensor shape induced by the provided array of the space mode extents.

Parameters

  • handle – [in] Library handle.

  • numSpaceModes – [in] Number of the (state) space modes acted on. It must coincide with the total number of space modes in the Hilbert space.

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

  • dataType – [in] Matrix operator data type.

  • matrixData – [in] GPU-accessible pointer to the matrix operator elements storage.

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

  • matrixGradientCallback – [in] Optional user-defined tensor gradient callback function which can be called later to compute the Vector-Jacobian Product (VJP) for the matrix operator, to produce gradients with respect to the user-defined real parameters, or NULL.

  • matrixOperator – [out] Full matrix operator.

Returns

cudensitymatStatus_t

cudensitymatCreateMatrixOperatorDenseLocalBatch

cudensitymatStatus_t cudensitymatCreateMatrixOperatorDenseLocalBatch(const cudensitymatHandle_t handle, int32_t numSpaceModes, const int64_t spaceModeExtents[], int64_t batchSize, cudaDataType_t dataType, void *matrixData, cudensitymatWrappedTensorCallback_t matrixCallback, cudensitymatWrappedTensorGradientCallback_t matrixGradientCallback, cudensitymatMatrixOperator_t *matrixOperator)

Creates a batch of full matrix operators acting on all quantum state modes (aka space modes) from an array of dense matrices stored (replicated) locally on each process. This is a batched version of the cudensitymatCreateMatrixOperatorDenseLocal API function.

This API function is used to create a batch of full matrix operators stored contiguously in memory, where the batch size must match the batch size of the quantum state acted on. A full matrix operator is a single tensor operator represented by its square matrix acting in the full Hilbert space. The dimension of the matrix is equal to the product of the extents of all space modes. The elements of the provided dense matrix are expected to be stored exactly in the same way as if the matrix operator was defined as an elementary tensor operator acting in the full space (acting on all space modes), please see description of the cudensitymatCreateElementaryOperatorBatch API function.

Note

The optional batched matrix callback function is still expected to take the actual tensor shape of the defined full matrix operator, namely, the tensor shape induced by the provided array of the space mode extents and the corresponding batch size (last mode).

Parameters

  • handle – [in] Library handle.

  • numSpaceModes – [in] Number of the (state) space modes acted on. It must coincide with the total number of space modes in the Hilbert space.

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

  • batchSize – [in] Batch size (>= 1).

  • dataType – [in] Matrix operator data type.

  • matrixData – [in] GPU-accessible pointer to the matrix operator elements storage where all matrix operator instances within the batch are stored contiguously in memory.

  • matrixCallback – [in] Optional user-defined batched tensor callback function which can be called later to fill in the matrix elements in the provided batched storage, or NULL. Note that the provided batched tensor callback function is expected to fill in all matrix instances within the batch in one call.

  • matrixGradientCallback – [in] Optional user-defined batched tensor gradient callback function which can be called later to compute the Vector-Jacobian Product (VJP) for the batched matrix operator, to produce gradients with respect to the batched user-defined real parameters, or NULL.

  • matrixOperator – [out] Batched full matrix operator (a batch of full matrix operators).

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 products of either elementary tensor operators or full matrix operators. Each individual elementary tensor operator within a product acts on a subset of space modes, either from the left or from the right (for each mode). Each full matrix operator within a product acts on all space modes, either from the left or from the right (for all modes).

Note

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

Parameters

  • handle – [in] Library handle.

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

  • spaceModeExtents – [in] Extents of the modes (quantum 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, cudensitymatWrappedScalarGradientCallback_t coefficientGradientCallback)

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

The elementary tensor operators constituting the provided tensor operator product are applied to the quantum state in-order, each elementary tensor operator acting on a quantum state mode either on the left or on the right, or both.

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 zero) or a bra mode of the quantum state (positive value).

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

  • coefficientCallback – [in] Optional 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.

  • coefficientGradientCallback – [in] Optional user-defined scalar gradient callback function which can be called later to compute the gradients of the complex scalar coefficient with respect to the user-defined real parameters, or NULL.

Returns

cudensitymatStatus_t

cudensitymatOperatorTermAppendElementaryProductBatch

cudensitymatStatus_t cudensitymatOperatorTermAppendElementaryProductBatch(const cudensitymatHandle_t handle, cudensitymatOperatorTerm_t operatorTerm, int32_t numElemOperators, const cudensitymatElementaryOperator_t elemOperators[], const int32_t stateModesActedOn[], const int32_t modeActionDuality[], int64_t batchSize, const cuDoubleComplex staticCoefficients[], cuDoubleComplex totalCoefficients[], cudensitymatWrappedScalarCallback_t coefficientCallback, cudensitymatWrappedScalarGradientCallback_t coefficientGradientCallback)

Appends a batch of elementary tensor operator products acting on quantum state modes to the operator term.

This is a batched version of the cudensitymatOperatorTermAppendElementaryProduct API function in which the provided static coefficients form an array of some length given by the batchSize argument. The provided elementary tensor operators themselves may or may not be batched. If any of them is batched itself, its batch size must match the batchSize argument. Furthermore, all non-unity batch sizes must match the batch size of the quantum state acted on.

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 (each elementary tensor operator may or may not be batched).

  • 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 zero) or a bra mode of the quantum state (positive value).

  • batchSize – [in] Batch size (>= 1).

  • staticCoefficients – [in] GPU-accessible array of constant (static) complex scalar coefficients associated with the appended batch of elementary tensor operator products (of length batchSize).

  • totalCoefficients – [in] GPU-accessible storage for the array of total complex scalar coefficients associated with the appended batch of elementary tensor operator products (of length batchSize). Each coefficient will be a product of a static coefficient and a dynamic coefficient generated by the provided scalar callback during the computation phase. If the scalar callback is not supplied here (NULL), this argument can also be set to NULL.

  • coefficientCallback – [in] Optional user-defined batched complex scalar callback function which can be called later to update the array of dynamic scalar coefficients associated with the defined batch of elementary tensor operator products, or NULL. The total coefficient associated with an elementary tensor operator product is a product of the constant (static) coefficient and the result of the scalar callback function, if defined.

  • coefficientGradientCallback – [in] Optional user-defined batched scalar gradient callback function which can be called later to compute the gradients of the batched complex scalar coefficients with respect to the batched user-defined real parameters, or NULL.

Returns

cudensitymatStatus_t

cudensitymatOperatorTermAppendMatrixProduct

cudensitymatStatus_t cudensitymatOperatorTermAppendMatrixProduct(const cudensitymatHandle_t handle, cudensitymatOperatorTerm_t operatorTerm, int32_t numMatrixOperators, const cudensitymatMatrixOperator_t matrixOperators[], const int32_t matrixConjugation[], const int32_t actionDuality[], cuDoubleComplex coefficient, cudensitymatWrappedScalarCallback_t coefficientCallback, cudensitymatWrappedScalarGradientCallback_t coefficientGradientCallback)

Appends a product of full matrix operators, each acting on all quantum state modes, to the operator term.

The full matrix operators constituting the provided matrix operator product are applied to the quantum state in-order, either on the left or on the rigt, either normal or in the conjugate-transposed form.

Parameters

  • handle – [in] Library handle.

  • operatorTerm – [inout] Operator term.

  • numMatrixOperators – [in] Number of full matrix operators in the matrix operator product.

  • matrixOperators – [in] Full matrix operators constituting the matrix operator product.

  • matrixConjugation – [in] Hermitean conjugation status of each matrix in the matrix operator product (zero means normal, positive integer means conjugate-transposed). For real matrices, hermitean conjugation reduces to a mere matrix transpose since there is no complex conjugation involved.

  • actionDuality – [in] Duality status of each matrix operator action, that is, whether it acts on all ket modes of the quantum state (value zero) or on all bra modes of the quantum state (positive integer value).

  • coefficient – [in] Constant (static) complex scalar coefficient associated with the matrix operator product.

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

  • coefficientGradientCallback – [in] Optional user-defined scalar gradient callback function which can be called later to compute the gradients of the complex scalar coefficient with respect to the user-defined real parameters, or NULL.

Returns

cudensitymatStatus_t

cudensitymatOperatorTermAppendMatrixProductBatch

cudensitymatStatus_t cudensitymatOperatorTermAppendMatrixProductBatch(const cudensitymatHandle_t handle, cudensitymatOperatorTerm_t operatorTerm, int32_t numMatrixOperators, const cudensitymatMatrixOperator_t matrixOperators[], const int32_t matrixConjugation[], const int32_t actionDuality[], int64_t batchSize, const cuDoubleComplex staticCoefficients[], cuDoubleComplex totalCoefficients[], cudensitymatWrappedScalarCallback_t coefficientCallback, cudensitymatWrappedScalarGradientCallback_t coefficientGradientCallback)

Appends a batch of full matrix operators to the operator term, each full matrix operator acting on all quantum state modes. This is a batched version of the cudensitymatOperatorTermAppendMatrixProduct API function.

This is a batched version of the cudensitymatOperatorTermAppendMatrixProduct API function in which the provided coefficients form an array of some length given by the batchSize argument. The provided full matrix operator itself may or may not be batched. If it is batched, its batch size must match the one the batchSize argument. If the full matrix operator itlsef is not batched, the same matrix will be used for all batch instances defined here. Furthermore, all non-unity batch sizes must match the batch size of the quantum state acted on.

Parameters

  • handle – [in] Library handle.

  • operatorTerm – [inout] Operator term.

  • numMatrixOperators – [in] Number of full matrix operators in the matrix operator product.

  • matrixOperators – [in] Full matrix operators constituting the matrix operator product (each full matrix operator may or may not be batched).

  • matrixConjugation – [in] Hermitean conjugation status of each matrix in the matrix operator product (zero means normal, positive integer means conjugate-transposed). For real matrices, hermitean conjugation reduces to a mere matrix transpose since there is no complex conjugation involved.

  • actionDuality – [in] Duality status of each matrix operator action, that is, whether it acts on all ket modes of the quantum state (value zero) or on all bra modes of the quantum state (positive integer value).

  • batchSize – [in] Batch size (>= 1).

  • staticCoefficients – [in] GPU-accessible array of constant (static) complex scalar coefficients associated with the appended batch of full matrix operator products (of length batchSize).

  • totalCoefficients – [in] GPU-accessible storage for the array of total complex scalar coefficients associated with the appended batch of full matrix operator products (of length batchSize). Each coefficient will be a product of a static coefficient and a dynamic coefficient generated by the provided scalar callback during the computation phase. If the scalar callback is not supplied here (NULL), this argument can also be set to NULL.

  • coefficientCallback – [in] Optional user-defined batched complex scalar callback function which can be called later to update the array of dynamic scalar coefficients associated with the defined batch of full matrix operator products, or NULL. The total coefficient associated with an elementary tensor operator product is a product of the constant (static) coefficient and the result of the scalar callback function, if defined.

  • coefficientGradientCallback – [in] Optional user-defined batched scalar gradient callback function which can be called later to compute the gradients of the batched complex scalar coefficients with respect to the batched user-defined real parameters, or NULL.

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 with some coefficients.

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, cudensitymatWrappedScalarGradientCallback_t coefficientGradientCallback)

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 (static) complex scalar coefficient associated with the operator term.

  • coefficientCallback – [in] Optional 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.

  • coefficientGradientCallback – [in] Optional user-defined scalar gradient callback function which can be called later to compute the gradients of the complex scalar coefficient with respect to the user-defined real parameters, or NULL.

Returns

cudensitymatStatus_t

cudensitymatOperatorAppendTermBatch

cudensitymatStatus_t cudensitymatOperatorAppendTermBatch(const cudensitymatHandle_t handle, cudensitymatOperator_t superoperator, cudensitymatOperatorTerm_t operatorTerm, int32_t duality, int64_t batchSize, const cuDoubleComplex staticCoefficients[], cuDoubleComplex totalCoefficients[], cudensitymatWrappedScalarCallback_t coefficientCallback, cudensitymatWrappedScalarGradientCallback_t coefficientGradientCallback)

Appends a batch of operator terms to the operator.

This is a batched version of the cudensitymatOperatorAppendTerm API function in which the provided coefficients form an array of some length given by the batchSize argument. The operator term itself may or may not be batched, that is, it may or may not contain batched components (batched elementary tensor operator products or batched full matrix operator products). If any of its components is batched, the batch sizes must match. They also must match the batch size of the quantum state acted on. If any of the operator terms or elementary tensor operators or full matrix operators inside any operator term is not batched, its value will be replicated along the batch dimension.

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.

  • batchSize – [in] Batch size (>= 1).

  • staticCoefficients – [in] GPU-accessible array of constant (static) complex scalar coefficients associated with the appended batch of operator terms (of length batchSize).

  • totalCoefficients – [in] GPU-accessible storage for the array of total complex scalar coefficients associated with the appended batch of operator terms (of length batchSize). Each coefficient will be a product of a static coefficient and a dynamic coefficient generated by the coefficient callback during the computation phase. If the scalar callback is not supplied here (NULL), this argument can also be set to NULL.

  • coefficientCallback – [in] Optional user-defined batched complex scalar callback function which can be called later to update the array of scalar coefficients associated with the defined batch of operator terms, or NULL. The total coefficient associated with an operator term is a product of the constant (static) coefficient and the result of the scalar callback function, if defined.

  • coefficientGradientCallback – [in] Optional user-defined batched scalar gradient callback function which can be called later to compute the gradients of the batched complex scalar coefficients with respect to the batched user-defined real parameters, or NULL.

Returns

cudensitymatStatus_t

cudensitymatOperatorPrepareAction

cudensitymatStatus_t cudensitymatOperatorPrepareAction(const cudensitymatHandle_t handle, 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 – [inout] Operator.

  • stateIn – [in] Representative input quantum state on which the operator is supposed to act. The actual quantum 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 quantum 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, cudensitymatOperator_t superoperator, double time, int64_t batchSize, 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 – [inout] Operator.

  • time – [in] Time value.

  • batchSize – [in] Batch size (>=1).

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

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

  • 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

cudensitymatOperatorPrepareActionBackwardDiff

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

Prepares backward differentiation of the operator action on a quantum state.

In general, before the backward differentiation of 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 – [inout] Operator.

  • stateIn – [in] Representative input quantum state on which the operator is supposed to act. The actual quantum 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).

  • stateOutAdj – [in] Representative adjoint of the output quantum state produced by the action of the operator on the input quantum state. The actual output quantum 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

cudensitymatOperatorComputeActionBackwardDiff

cudensitymatStatus_t cudensitymatOperatorComputeActionBackwardDiff(const cudensitymatHandle_t handle, cudensitymatOperator_t superoperator, double time, int64_t batchSize, int32_t numParams, const double *params, const cudensitymatState_t stateIn, const cudensitymatState_t stateOutAdj, cudensitymatState_t stateInAdj, double *paramsGrad, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)

Computes backward differentiation of the operator action on a given quantum state.

In general, an operator can be parameterized by a set of user-defined real parameters which parameterize elementary tensor operators, matrix operators, and coefficients which are used to define the operator. This function computes the partial derivatives of the operator action on a quantum state with respect to the user-defined real parameters. Specifically, the function computes the Vector-Jacobian Product (VJP) of the operator action on the quantum state with respect to the user-defined real parameters. That is, given the adjoint of the output quantum state, the function computes the following quantities:

  • partial derivatives of the cost function with respect to the user-defined real parameters which parameterize the operator (explicit derivatives).

  • adjoint of the input quantum state (implicit derivatives). Symbolically, this can be expressed as follows:

Operator action: y[i] += A(p)[i,j] * x[j] where A(p) is the operator parameterized by N user-defined real parameters p[n], 1 <= n <= N, y is the output quantum state, and x is the input quantum state.

Forward derivatives: dy[i] = A[i,j] * dx[j] + dA[i,k] * x[k]

Backward derivatives (these two are computed by the current API function): Input quantum state adjoint: dc/dx[j] = dc/dy[i] * A[i,j] Partial operator derivatives: dc/dp[n] = dc/dy[i] * (dA[i,k] * x[k])/dp[n]

Given the above two quantities, the full operator action derivatives can be constructed as: Full operator action derivatives: dc/dp[n] = dc/dx[j] * dx[j]/dp[n] + (dc/dy[i] * (dA[i,k] * x[k])/dp[n])

When computing the partial operator derivatives, the term (dA[i,k] * x[k])/dp[n] is computed as a sum of contributions over all differentiable elementary tensor operators, matrix operators, and complex scalar coefficients which parameterize the operator, as follows: dc/dp[n] = (dA[i,k] * x[k])/dp[n] = sum_j (dA[i,k] * x[k])/qQ[j] * dQ[j]/dp[n] where Q[j] is a specific differentiable quantity (elementary tensor operator, matrix operator, or complex scalar coefficient) which parameterizes the operator, and dQ[j]/dp[n] is the partial derivative of Q[j] with respect to the n-th user-defined real parameter p[n]. Each dQ[j]/dp[n] is specified by a user-provided scalar/tensor gradient callback function which takes the adjoint of the corresponding quantity Q[j] as an input argument (scalarGrad or tensorGrad), multiplies it by the dQ[j]/dp[n] Jacobian, and accumulates the REAL part of the result multipled by TWO (since the total cost function is always real) in the output array of partial derivatives with respect to the user-defined real parameters (argument paramsGrad). If the state/operator is batched, the partial derivatives are computed for the entire batch, in which case the paramsGrad array must have shape [numParams, batchSize] in the F-order, while the scalarGrad and tensorGrad arrays can be either batched or non-batched, based on the corresponding quantity Q[j] being batched or non-batched. In case the quantity Q[j] is not batched while the quantum states are batched, the scalarGrad and tensorGrad arrays passed to the gradient callback function will not be batched, but the params and paramsGrad arrays will be batched, but only their first batch instance will actually be used (argument batchSize will be set to 1 in this case), specifically, only params[0:N-1, 0] and paramsGrad[0:N-1, 0] will be used.

Parameters

  • handle – [in] Library handle.

  • superoperator – [inout] Operator.

  • time – [in] Time value.

  • batchSize – [in] Batch size (>=1).

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

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

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

  • stateOutAdj – [in] Adjoint of the output quantum state (or a batch).

  • stateInAdj – [inout] Adjoint of the input quantum state (or a batch). Note that this array will not be zeroed out on entrance, it will be accumulated into.

  • paramsGrad – [inout] GPU-accessible pointer where the partial derivatives with respect to the user-defined real parameters will be accumulated (same shape as params). Note that this array will not be zeroed out on entrance, it will be accumulated into.

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

  • 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, int64_t batchSize, 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.

  • batchSize – [in] Batch size (>=1).

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

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

  • 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, int64_t batchSize, 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 – [inout] Expectation value object.

  • time – [in] Specified time.

  • batchSize – [in] Batch size (>=1).

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

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

  • 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

Versioning API

cudensitymatGetVersion

size_t cudensitymatGetVersion()

Returns the semantic version number of the cuDensityMat library.