cuStateVec Ex functions

Dictionary API

custatevecExDictionaryDestroy

custatevecStatus_t custatevecExDictionaryDestroy(custatevecExDictionaryDescriptor_t dictionary)

Destroy dictionary instance.

custatevecExDictionaryDestroy() destroys dictionary instance. Dictionary is the object to hold key-value pairs.

Parameters

dictionary – [in] dictionary descriptor instance

StateVector API

custatevecExConfigureStateVectorSingleDevice

custatevecStatus_t custatevecExConfigureStateVectorSingleDevice(custatevecExDictionaryDescriptor_t *svConfig, cudaDataType_t svDataType, int32_t numWires, int32_t numDeviceWires, int32_t deviceId, uint32_t capability)

Create state vector configuration.

This function creates a dictionary that holds state vector configuration according to the given set of arguments. The numWires argument specifies the number of wires of state vector, and the numDeviceWires argument specifies the number of wires allocated on a device. The capability argument is to enable optional features. The value is specified as a bit-wise OR of custatevecExStateVectorCapability_t. As the present version does not have any capability defined, the value should be 0.

For the present release, the same value should be specified to the numWires and numDeviceWires arguments. These two arguments are declared for a future extension.

Parameters

  • svConfig – [out] dictionary instance that holds state vector configuration

  • svDataType – [in] state vector data type

  • numWires – [in] number of wires of state vector

  • numDeviceWires – [in] number of wires of state vector on device

  • deviceId – [in] device id

  • capability – [in] bit mask to specify optional features of state vector

custatevecExStateVectorCreateSingleProcess

custatevecStatus_t custatevecExStateVectorCreateSingleProcess(custatevecExStateVectorDescriptor_t *stateVector, const custatevecExDictionaryDescriptor_t svConfig, cudaStream_t *streams, int32_t numStreams, custatevecExResourceManagerDescriptor_t allocator)

Create state vector.

This function creates a state vector instance according to the svConfig argument and returns the instance to the stateVector argument.

The streams and numStreams arguments specify CUDA streams. CUDA API calls and kernel launches are serialized on the given streams. The number of streams should match the number of devices where the state vector is allocated. All CUDA calls serialized on the streams are synchronized by calling custatevecExStateVectorSynchronize(). If a null pointer is passed to the streams argument, all calls are serialized on the default streams. In this case, the value of the numStreams argument should be 0.

The allocator argument is to specify external memory allocator. If a null pointer is specified, the library default memory allocator is used.

Note

Custom memory allocator is not enabled in this release. Please pass nullptr to the allocator argument. Otherwise, this function returns CUSTATEVEC_STATUS_INVALID_VALUE.

Parameters

  • stateVector – [out] a host pointer to the variable that receives state vector instance

  • svConfig – [in] state vector configuration created by a state vector configuration function

  • streams – [in] a pointer to a host array that holds CUDA streams

  • numStreams – [in] the number of streams given by the streams argument

  • allocator – [in] memory allocator

custatevecExStateVectorDestroy

custatevecStatus_t custatevecExStateVectorDestroy(custatevecExStateVectorDescriptor_t stateVector)

Destroy state vector instance.

This function destroys state vector instance.

Parameters

stateVector – [in] state vector instance

custatevecExStateVectorGetProperty

custatevecStatus_t custatevecExStateVectorGetProperty(const custatevecExStateVectorDescriptor_t stateVector, custatevecExStateVectorProperty_t property, void *value, size_t sizeInBytes)

Retrieve state vector properties.

This function retrieves state vector properties. The property argument specifies one of properties, and the property value is returned to the host buffer specified by the value argument.

The following is the table for properties and corresponding data types.

custatevecExStateVectorProperty_t

data type

CUSTATEVEC_EX_SV_PROP_DISTRIBUTION_TYPE

custatevecExStateVectorDistributionType_t

CUSTATEVEC_EX_SV_PROP_DATA_TYPE

cudaDataType_t

CUSTATEVEC_EX_SV_PROP_NUM_WIRES

int32_t

CUSTATEVEC_EX_SV_PROP_WIRE_ORDERING

int32_t[]

CUSTATEVEC_EX_SV_PROP_NUM_LOCAL_WIRES

int32_t

CUSTATEVEC_EX_SV_PROP_NUM_DEVICE_SUBSVS

int32_t

CUSTATEVEC_EX_SV_PROP_DEVICE_SUBSV_INDICES

int32_t[]

Each property enum returns the values as described below.

The sizeInBytes argument specifies the byte size of the value buffer and should be equal to or larger than the required byte size. Otherwise, this function returns CUSTATEVEC_STATUS_INVALID_VALUE.

Parameters

  • stateVector – [in] state vector instance

  • property – [in] a value of custatevecExStateVectorProperty_t

  • value – [out] host pointer to a host buffer that receives the value of the specified property

  • sizeInBytes – [in] byte size of the value buffer

custatevecExStateVectorSetMathMode

custatevecStatus_t custatevecExStateVectorSetMathMode(custatevecExStateVectorDescriptor_t stateVector, custatevecMathMode_t mode)

Set the compute precision mode for a state vector instance.

This function sets the compute precision mode for the specified state vector instance. Each state vector can have its own compute precision mode independently.

The compute precision mode controls the precision and performance characteristics of mathematical operations performed on the state vector.

The default math mode for the cuStateVecEx API is CUSTATEVEC_MATH_MODE_ALLOW_FP32_EMULATED_BF16X9. To disable the use of BF16x9 floating point emulation, set the mode to CUSTATEVEC_MATH_MODE_DISALLOW_FP32_EMULATED_BF16X9.

Parameters

  • stateVector – [inout] state vector instance

  • mode – [in] Compute precision mode as defined by custatevecMathMode_t.

custatevecExStateVectorSetZeroState

custatevecStatus_t custatevecExStateVectorSetZeroState(custatevecExStateVectorDescriptor_t stateVector)

Set the zero state to state vector.

This function sets the zero state (|0000…00>).

Parameters

stateVector – [inout] state vector instance

custatevecExStateVectorGetState

custatevecStatus_t custatevecExStateVectorGetState(const custatevecExStateVectorDescriptor_t stateVector, void *state, cudaDataType_t dataType, custatevecIndex_t begin, custatevecIndex_t end, int32_t maxNumConcurrentCopies)

Copy state vector elements to host buffer.

State vector elements in [begin, end) are copied to the host buffer specified by the state argument. The data type specified by the dataType argument should equal to that specified when configuring state vector. The host buffer should be large enough to hold copied elements.

The dataType argument should be identical to that of the state vector instance specified by the stateVector argument. Otherwise, this API returns CUSTATEVEC_STATUS_INVALID_VALUE.

The maxNumConcurrentCopies argument specifies the max number of concurrent copies that can be utilized during the copy of state vector elements. The actual number of concurrent copies is implementation defined.

Note

The call to custatevecExStateVectorGetState() can be asynchronous. Please call custatevecExStateVectorSynchronize() to complete the copying of state vector elements.

Parameters

  • stateVector – [in] state vector instance

  • state – [out] pointer to a host buffer that receives state vector elements

  • dataType – [in] dataType of the state vector elements

  • begin – [in] index of state vector element where the copy begins

  • end – [in] index of state vector element where the copy ends

  • maxNumConcurrentCopies – [in] Max number of parallel copies.

custatevecExStateVectorSetState

custatevecStatus_t custatevecExStateVectorSetState(custatevecExStateVectorDescriptor_t stateVector, const void *state, cudaDataType_t dataType, custatevecIndex_t begin, custatevecIndex_t end, int32_t maxNumConcurrentCopies)

Set complex value array on host to state vector.

Complex values given by the state argument are copied to the specified state vector. The copy range in the state vector index is [begin, end). The data type of complex values should equal to that specified on configuring state vector.

The maxNumConcurrentCopies argument specifies the max number of concurrent copies that can be utilized during the copy of state vector elements. The actual number of concurrent copies is implementation defined.

Note

The call to custatevecExStateVectorSetState() can be asynchronous. Please call custatevecExStateVectorSynchronize() to complete the copying of state vector elements.

Parameters

  • stateVector – [out] state vector instance

  • state – [in] pointer to a complex vector on host

  • dataType – [in] dataType of the state vector elements

  • begin – [in] index of state vector element where the copy begins

  • end – [in] index of state vector element where the copy ends

  • maxNumConcurrentCopies – [in] Max number of parallel copies.

custatevecExStateVectorReassignWireOrdering

custatevecStatus_t custatevecExStateVectorReassignWireOrdering(custatevecExStateVectorDescriptor_t stateVector, const int32_t *wireOrdering, int32_t wireOrderingLen)

Reassign wire ordering to state vector.

Reassign (overwrite) wire ordering of the given state vector. The elements given by the wireOrdering argument should be in [0, numWires) where numWires represents the number of wires of the state vector. Otherwise this API returns CUSTATEVEC_STATUS_INVALID_VALUE. The wireOrderingLen argument represents the length of wire ordering. The value should match the number of wires. Otherwise this API returns CUSTATEVEC_STATUS_INVALID_VALUE.

Parameters

  • stateVector – [inout] state vector instance

  • wireOrdering – [in] the pointer to a integer host array that holds wire ordering

  • wireOrderingLen – [in] the length of wire ordering

custatevecExStateVectorPermuteIndexBits

custatevecStatus_t custatevecExStateVectorPermuteIndexBits(custatevecExStateVectorDescriptor_t stateVector, const int32_t *permutation, int32_t permutationLen, custatevecExPermutationType_t permutationType)

Permute index bits and wires of state vector.

Permutes index bits of state vector, and the wire ordering is accordingly updated to reflect the permuted index bit ordering.

Permutation is specified by the permutation argument as an integer array. The permutationLen argument specifies the length of the permutation. The function can apply two types of permutation, scatter or gather, which is specified by the permutationType argument.

The wire ordering is updated as defined in the following formulas.

// When CUSTATEVEC_EX_PERMUTATION_SCATTER specified.
dstWires[permutation[idx]] = srcWires[idx]

// When CUSTATEVEC_EX_PERMUTATION_GATHER specified.
dstWires[idx] = srcWires[permutation[idx]]

By definition, the elements of permutation array should be integers in [0, numWires - 1] where numWires represents the number of wires of the specified state vector instance. If CUSTATEVEC_EX_PERMUTATION_SCATTER is specified to the permutationType, the permutation length should be identical to the number of wires. If CUSTATEVEC_EX_PERMUTATION_GATHER is specified to the permutationType and permutationLen is smaller than the number of wires in state vector, wires that don’t appear in the permutation argument are sorted and appended to the permutation array.

Ex. numWires = 5, permutation = {0, 2, 3}, permutationLen = 3. Wires {1, 4} don’t appear. Those two wires are sorted and appended to the permutation. Therefore, the complemented permutation is {0, 2, 3, 1, 4}.

Parameters

  • stateVector – [inout] StateVector instance

  • permutation – [in] a host pointer to an integer array specifying the permutation

  • permutationLen – [in] length of the permutation

  • permutationType – [in] permutation type (scatter or gather)

custatevecExStateVectorGetResourcesFromDeviceSubSV

custatevecStatus_t custatevecExStateVectorGetResourcesFromDeviceSubSV(custatevecExStateVectorDescriptor_t stateVector, int32_t subSVIndex, int32_t *deviceId, void **d_subSV, cudaStream_t *stream, custatevecHandle_t *handle)

Get resources from device sub state vector.

Get the computing resource associated with the device state vector. The subSVIndex argument specifies the sub state vector index. The deviceId, d_subSV arguments return the device id, the device memory pointer of the specified sub state vector. The stream and handle arguments return the CUDA stream and the cuStateVec handle. All CUDA calls in custatevecEx API are serialized on the returned stream. The returned cuStateVec handle can be passed to cuStateVec APIs to operate on the returned device pointer.

The number of the device sub state vectors is retrieved by calling custatevecExStateVectorGetProperty() API with CUSTATEVEC_EX_SV_PROP_NUM_DEVICE_SUBSVS specified as the property name, and the sub state vector indices are retrieved by specifying CUSTATEVEC_EX_SV_PROP_DEVICE_SUBSV_INDICES, respectively. A single-device state vector always has one device sub-state vector.

Any of the deviceId, d_subSV or stream arguments should not be a null pointer. Otherwise, this API returns CUSTATEVEC_STATUS_INVALID_VALUE. A null pointer can be passed to the handle argument. For this case, the cuStateVec handle will not be returned.

Parameters

  • stateVector – [in] StateVector instance

  • subSVIndex – [in] sub state vector index

  • deviceId – [out] device id

  • d_subSV – [out] a host pointer that receives the specified sub state vector pointer.

  • stream – [out] a host pointer to CUDA stream

  • handle – [out] a host pointer to custatevecHandle_t

custatevecExStateVectorGetResourcesFromDeviceSubSVView

custatevecStatus_t custatevecExStateVectorGetResourcesFromDeviceSubSVView(const custatevecExStateVectorDescriptor_t stateVector, int32_t subSVIndex, int32_t *deviceId, const void **d_subSV, cudaStream_t *stream, custatevecHandle_t *handle)

Get resources from device sub state vector view.

This API works almost the same as custatevecExStateVectorGetResourcesFromDeviceSubSV() except for the returned device pointer is immutable.

Please refer to the documentation of custatevecExStateVectorGetResourcesFromDeviceSubSV() API for the descriptions of the arguments.

Parameters

  • stateVector – [in] StateVector instance

  • subSVIndex – [in] sub state vector index

  • deviceId – [out] device id

  • d_subSV – [out] a host pointer that receives the specified sub state vector pointer.

  • stream – [out] a host pointer to CUDA stream

  • handle – [out] a host pointer to custatevecHandle_t

custatevecExStateVectorSynchronize

custatevecStatus_t custatevecExStateVectorSynchronize(custatevecExStateVectorDescriptor_t stateVector)

Flush all operations and synchronize.

This function flushes all operations issued before the call of this function and synchronize on the streams associated with the specified state vector.

Parameters

stateVector – [in] state vector instance

Simulator API

custatevecExAbs2SumArray

custatevecStatus_t custatevecExAbs2SumArray(custatevecExStateVectorDescriptor_t stateVector, double *abs2sum, const int32_t *outputOrdering, int32_t outputOrderingLen, const int32_t *maskBitString, const int32_t *maskWireOrdering, int32_t maskLen)

Calculate abs2sum array for a given set of wires.

Calculates an array of sums of squared absolute values of state vector elements. The abs2sum array can be on host or device. The tensor ordering of the abs2sum array is specified by the outputOrdering and the outputOrderingLen arguments. Unspecified wires are folded (summed up).

The maskBitString, maskWireOrdering and maskLen arguments set a bit string to mask the state vector. The abs2sum array is calculated by using state vector elements that match the mask bit string. If the maskLen argument is 0, null pointers can be specified to the maskBitString and maskWireOrdering arguments, and all state vector elements are used for calculation.

By definition, bit positions in outputOrdering and maskWireOrdering arguments should not overlap.

The empty outputOrdering can be specified to calculate the norm of state vector. In this case, 0 is passed to the outputOrderingLen argument and the outputOrdering argument can be a null pointer.

Note

Since the size of abs2sum array is proportional to \( 2^{outputOrderingLen} \) , the max length of outputOrdering depends on the amount of available memory and maskLen.

Parameters

  • stateVector – [in] StateVector instance

  • abs2sum – [out] pointer to a host or device array of sums of squared absolute values

  • outputOrdering – [in] pointer to a host array of output tensor ordering

  • outputOrderingLen – [in] the length of outputOrdering

  • maskBitString – [in] pointer to a host array for a bit string to specify mask bits

  • maskWireOrdering – [in] pointer to a host array that specifies the wire ordering of maskBitString

  • maskLen – [in] the length of mask

custatevecExMeasure

custatevecStatus_t custatevecExMeasure(custatevecExStateVectorDescriptor_t stateVector, custatevecIndex_t *bitString, const int32_t *bitStringOrdering, int32_t bitStringOrderingLen, double randnum, custatevecCollapseOp_t collapse, const void *reserved)

Perform qubit measurements.

This function executes multiple single qubit measurements with a single call and returns a bit string that represents the measurement outcomes. The bitStringOrdering argument specifies wires to be measured.

The measurement result is stored in bitString as a 64-bit integer bit mask. The ordering of bitString is specified by the bitStringOrdering and bitStringOrderingLen arguments. The idx-th bit of bitString corresponds to the measurement outcome of bitStringOrdering[idx].

The collapse argument specifies the operation applied for the state vector.

If CUSTATEVEC_COLLAPSE_NONE is specified, this function only returns the measured bit string without modifying the state vector.

If CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO is specified, this function collapses the state vector.

If CUSTATEVEC_COLLAPSE_RESET is specified, the state vector is collapsed as CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO does. Then, the measurement outcome is checked. If the measurement outcome for a specified wire is |1>, the wire is flipped (reset) to |0>. Otherwise, the state vector is not modified.

If a random number is not in [0, 1), this function returns CUSTATEVEC_STATUS_INVALID_VALUE. At least one wire should be specified, otherwise this function returns CUSTATEVEC_STATUS_INVALID_VALUE.

Parameters

  • stateVector – [in] StateVector instance

  • bitString – [out] host pointer that receives the measured bit string

  • bitStringOrdering – [in] pointer to a host array of bit string ordering

  • bitStringOrderingLen – [in] length of bitStringOrdering

  • randnum – [in] random number, [0, 1).

  • collapse – [in] Collapse operation

  • reserved – [in] Reserved argument. A null pointer should be passed.

custatevecExSample

custatevecStatus_t custatevecExSample(custatevecExStateVectorDescriptor_t stateVector, custatevecIndex_t *bitStrings, const int32_t *bitStringOrdering, int32_t bitStringOrderingLen, const double *randnums, int32_t numShots, custatevecSamplerOutput_t output, const void *reserved)

Sample bit strings from the state vector.

This function performs sampling. The bitStringOrdering and bitStringOrderingLen arguments specify wires to be sampled. Sampled bit strings are represented as an array of custatevecIndex_t and are stored to the host memory buffer that the bitStrings argument points to.

The randnums argument is an array of user-generated random numbers whose length is numShots. The range of random numbers should be in [0, 1). A random number given by the randnums argument is clipped to [0, 1) if its range is not in [0, 1).

The output argument specifies the order of sampled bit strings:

Parameters

  • stateVector – [in] State vector instance

  • bitStrings – [out] pointer to a host array to store sampled bit strings

  • bitStringOrdering – [in] pointer to a host array of bit string ordering for sampling

  • bitStringOrderingLen – [in] length of bitStringOrdering

  • randnums – [in] pointer to an array of random numbers

  • numShots – [in] the number of shots

  • output – [in] the order of sampled bit strings

  • reserved – [in] Reserved argument. A null pointer should be passed.

custatevecExApplyMatrix

custatevecStatus_t custatevecExApplyMatrix(custatevecExStateVectorDescriptor_t stateVector, const void *matrix, cudaDataType_t matrixDataType, custatevecExMatrixType_t exMatrixType, custatevecMatrixLayout_t layout, int32_t adjoint, const int32_t *targets, int32_t numTargets, const int32_t *controls, const int32_t *controlBitValues, int32_t numControls)

Apply gate matrix.

Apply gate matrix for state vector.

The matrix argument is a host or device pointer that points to matrix element array. The matrixDataType argument specifies the data type of matrix elements. The value should be CUDA_C_32F or CUDA_C_64F for complex 64 or complex 128 type, respectively.

The exMatrixType argument specifies the matrix types, dense (square), diagonal or anti-diagonal. The memory layout of the matrix is row- or column-major, which is specified by the layout argument.

The matrix type is dense (square) if CUSTATEVEC_EX_MATRIX_DENSE is specified. The matrix argument points to a buffer that holds dense matrix as two-dimensional array. The matrix dimension is ( \(2^\text{numTargets} \times 2^\text{numTargets}\) ). The memory layout follows the specification of the layout argument. The layout is row-major if CUSTATEVEC_MATRIX_LAYOUT_ROW, or column-major if CUSTATEVEC_MATRIX_LAYOUT_COL is specified.

The matrix type is diagonal if CUSTATEVEC_EX_MATRIX_DIAGONAL is specified. The matrix argument points to a buffer that accommodates a complex vector of diagonal elements. The vector length is identical to the matrix dimension, ( \(2^\text{numTargets}\) ). The memory layout of the diagonal elements is identical for row- and column-major layouts. Thus, the memory layout specification by the layout argument is ignored.

The matrix type is anti-diagonal if CUSTATEVEC_EX_MATRIX_ANTI_DIAGONAL is specified. The matrix argument points to a host or device buffer that accommodates a complex vector of anti-diagonal elements. The vector length is identical to the matrix dimension, ( \(2^\text{numTargets}\) ). The memory layout is specified by the layout argument expressed as shown below,

elements[idx] = matrix(idx, dim - (idx + 1))  // row-major layout

elements[idx] = matrix(dim - (idx + 1), idx)  // col-major layout

by using elements[idx] for the idx-th anti-diagonal element and matrix(row, col) for the matrix element at (row, col).

The targets and controls arguments specify target and control wires in the state vector. The controlBitValues argument specifies bit values of control wires. The ordering of controlBitValues is specified by the controls argument. If a null pointer is specified to this argument, all control bit values are set to 1.

By definition, all target and control values should be in [0, numWires). Wires in targets and controls arguments should not overlap.

Parameters

  • stateVector – [inout] state vector instance

  • matrix – [in] pointer to a host buffer that holds matrix elements

  • matrixDataType – [in] data type of matrix

  • exMatrixType – [in] enumerator specifying the matrix type and layout

  • layout – [in] enumerator specifying the matrix layout

  • adjoint – [in] apply adjoint of matrix

  • targets – [in] pointer to a host array of target wires

  • numTargets – [in] the number of target wires

  • controls – [in] pointer to a host array of control wires

  • controlBitValues – [in] pointer to a host array of control bit values

  • numControls – [in] the number of control wires

custatevecExApplyPauliRotation

custatevecStatus_t custatevecExApplyPauliRotation(custatevecExStateVectorDescriptor_t stateVector, double theta, const custatevecPauli_t *paulis, const int32_t *targets, int32_t numTargets, const int32_t *controls, const int32_t *controlBitValues, int32_t numControls)

Apply the exponential of a multi-qubit Pauli operator.

Apply exponential of a tensor product of Pauli operators, \( e^{i \theta P} \), where \(P\) is the tensor product \(P = paulis[0] \otimes paulis[1] \otimes \cdots \otimes paulis[numTargets-1]\) acting on the wires specified by the targets argument. The paulis and numTargets arguments specify the Pauli operators and their count.

At least one target and a corresponding Pauli basis should be specified.

The controls and numControls arguments specify the control wires in the state vector.

The controlBitValues argument specifies bit values of control wires. The ordering of controlBitValues is specified by the controls argument. If a null pointer is specified to this argument, all control bit values are set to 1.

Parameters

  • stateVector – [inout] state vector instance

  • theta – [in] theta

  • paulis – [in] host pointer to custatevecPauli_t array

  • targets – [in] pointer to a host array of target wires

  • numTargets – [in] the number of target wires

  • controls – [in] pointer to a host array of control wires

  • controlBitValues – [in] pointer to a host array of control bit values

  • numControls – [in] the number of control wires

custatevecExComputeExpectationOnPauliBasis

custatevecStatus_t custatevecExComputeExpectationOnPauliBasis(custatevecExStateVectorDescriptor_t stateVector, double *expectationValues, const custatevecPauli_t **pauliOperatorArrays, int32_t numPauliOperatorArrays, const int32_t **basisWiresArray, const int32_t *numBasisWiresArray)

Compute expectation values for a batch of (multi-qubit) Pauli operators.

This function computes multiple expectation values for given sequences of Pauli operators by a single call.

A single Pauli operator sequence, pauliOperators, is represented by using an array of custatevecPauli_t. The basis wires on which these Pauli operators are acting are represented by an array of wires.

The length of pauliOperators and basisWires are the same and specified by numBasisWires.

The number of Pauli operator sequences is specified by the numPauliOperatorArrays argument.

Multiple sequences of Pauli operators are represented in the form of arrays of arrays in the following manners:

  • The pauliOperatorArrays argument is an array of arrays of custatevecPauli_t.

  • The basisWiresArray is an array of the wire arrays.

  • The numBasisWiresArray argument holds an array of the length of Pauli operator sequences and wire arrays.

Computed expectation values are stored in a host buffer specified by the expectationValues argument of length numPauliOperatorArrays.

This function returns CUSTATEVEC_STATUS_INVALID_VALUE if wires specified for a Pauli operator sequence has duplicates and/or points to a wire that does not exist.

This function accepts empty Pauli operator sequence to get the norm of the state vector.

Parameters

  • stateVector – [in] state vector instance

  • expectationValues – [out] pointer to a host array to store expectation values

  • pauliOperatorArrays – [in] pointer to a host array of Pauli operator arrays

  • numPauliOperatorArrays – [in] the number of Pauli operator arrays

  • basisWiresArray – [in] host array of basis wire arrays

  • numBasisWiresArray – [in] host array of the number of basis wires

SVUpdater API

custatevecExConfigureSVUpdater

custatevecStatus_t custatevecExConfigureSVUpdater(custatevecExDictionaryDescriptor_t *svUpdaterConfig, cudaDataType_t dataType, const custatevecExSVUpdaterConfigItem_t *configItems, int32_t numConfigItems)

Create SVUpdater configuration.

This function creates the configuration dictionary for SVUpdater. The dataType argument specifies the value type internally used in SVUpdater. Its value should be CUDA_C_32F or CUDA_C_64F. The configItems and numConfigItems arguments are the array of custatevecExSVUpdaterConfigItem_t.

The following configuration items are available:

The configItems should not contain duplicate items with the same name. For configurations that are not specified, system default values will be used.

The configItems can be a null pointer. In that case, numConfigItems should be set to 0.

It’s the user’s responsibility to destroy the created svUpdaterConfig object by calling custatevecExDictionaryDestroy().

Note

Default configuration is recommended for optimal performance. For CUSTATEVEC_EX_SVUPDATER_CONFIG_MAX_NUM_HOST_THREADS, values between 4 and 16 generally provide good performance. For CUSTATEVEC_EX_SVUPDATER_CONFIG_DENSE_FUSION_SIZE, values between 4 and 6 are automatically selected by the library. These values correspond to the upper limit where gate application kernels remain memory-bound rather than compute-bound, ensuring optimal performance. For CUSTATEVEC_EX_SVUPDATER_CONFIG_DIAGONAL_FUSION_SIZE, the library default is recommended. The value is automatically adjusted based on the number of qubits in the state vector.

Parameters

  • svUpdaterConfig – [out] SVUpdater configuration

  • dataType – [in] data type used in SVUpdater

  • configItems – [in] host pointer to the array of Configuration items

  • numConfigItems – [in] the number of configuration items

custatevecExSVUpdaterCreate

custatevecStatus_t custatevecExSVUpdaterCreate(custatevecExSVUpdaterDescriptor_t *svUpdater, const custatevecExDictionaryDescriptor_t svUpdaterConfig, custatevecExResourceManagerDescriptor_t allocator)

Create SVUpdater.

This function creates SVUpdater instance.

Note

Custom memory allocator is not enabled in this release. Please pass nullptr to the allocator argument. Otherwise, this function returns CUSTATEVEC_STATUS_INVALID_VALUE.

Parameters

  • svUpdater – [out] created SVUpdater

  • svUpdaterConfig – [in] SVUpdater configuration

  • allocator – [in] Custom memory allocator

custatevecExSVUpdaterDestroy

custatevecStatus_t custatevecExSVUpdaterDestroy(custatevecExSVUpdaterDescriptor_t svUpdater)

Destroy SVUpdater instance.

This function destroys SVUpdater instance.

Parameters

svUpdater – [in] SVUpdater instance

custatevecExSVUpdaterClear

custatevecStatus_t custatevecExSVUpdaterClear(custatevecExSVUpdaterDescriptor_t svUpdater)

Clear operations queued in SVUpdater.

This function clears queued operations in SVUpdater.

Parameters

svUpdater – [inout] SVUpdater instance

custatevecExSVUpdaterEnqueueMatrix

custatevecStatus_t custatevecExSVUpdaterEnqueueMatrix(custatevecExSVUpdaterDescriptor_t svUpdater, const void *matrix, cudaDataType_t matrixDataType, custatevecExMatrixType_t exMatrixType, custatevecMatrixLayout_t layout, int32_t adjoint, const int32_t *targets, int32_t numTargets, const int32_t *controls, const int32_t *controlBitValues, int32_t numControls)

Enqueue unitary matrix to SVUpdater.

This function enqueues a gate matrix to SVUpdater.

The matrix argument is a host pointer that points to matrix element array. The matrixDataType argument specifies the data type of matrix elements. The value should be CUDA_C_32F or CUDA_C_64F for complex 64 or complex 128 type, respectively. Only CUDA_C_64F is acceptable if the SVUpdater data type is CUDA_C_64F by calling custatevecExConfigureSVUpdater(). Also, CUDA_C_64F and CUDA_C_32F are acceptable if the SVUpdater data type is CUDA_C_32F.

The exMatrixType argument specifies the matrix types, dense (square), diagonal or anti-diagonal. The memory layout of the matrix is row- or column-major, which is specified by the layout argument.

The matrix type is dense (square) if CUSTATEVEC_EX_MATRIX_DENSE is specified. The matrix argument points to a buffer that holds dense matrix as two-dimensional array. The matrix dimension is ( \(2^\text{numTargets} \times 2^\text{numTargets}\) ). The memory layout follows the specification of the layout argument. The layout is row-major if CUSTATEVEC_MATRIX_LAYOUT_ROW, or column-major if CUSTATEVEC_MATRIX_LAYOUT_COL is specified.

The matrix type is diagonal if CUSTATEVEC_EX_MATRIX_DIAGONAL is specified. The matrix argument points to a buffer that accommodates a complex vector of diagonal elements. The vector length is identical to the matrix dimension, ( \(2^\text{numTargets}\) ). The memory layout of the diagonal elements is identical for row- and column-major layouts. Thus, the memory layout specification by the layout argument is ignored.

The matrix type is anti-diagonal if CUSTATEVEC_EX_MATRIX_ANTI_DIAGONAL is specified. The matrix argument points to a host or device buffer that accommodates a complex vector of anti-diagonal elements. The vector length is identical to the matrix dimension, ( \(2^\text{numTargets}\) ). The memory layout is specified by the layout argument expressed as shown below,

elements[idx] = matrix(idx, dim - (idx + 1))  // row-major layout

elements[idx] = matrix(dim - (idx + 1), idx)  // col-major layout

by using elements[idx] for the idx-th anti-diagonal element and matrix(row, col) for the matrix element at (row, col).

The targets and controls arguments specify target and control wires in the state vector. The controlBitValues argument specifies bit values of control wires. The ordering of controlBitValues is specified by the controls argument. If a null pointer is specified to this argument, all control bit values are set to 1.

The max number of targets is limited to 15 if CUSTATEVEC_EX_MATRIX_DENSE or CUSTATEVEC_EX_MATRIX_ANTI_DIAGONAL specified, and 30 if CUSTATEVEC_EX_MATRIX_DIAGONAL, specified, respectively. However, 10 or more targets is not recommended; the recommended number of targets for typical usage is 6 or fewer.

By definition, all target and control values should be in [0, numWires). Wires in targets and controls arguments should not overlap.

Parameters

  • svUpdater – [inout] SVUpdater instance

  • matrix – [in] pointer to a host buffer that holds matrix elements

  • matrixDataType – [in] data type of matrix

  • exMatrixType – [in] enumerator specifying the matrix type

  • layout – [in] enumerator specifying the matrix layout

  • adjoint – [in] apply adjoint of matrix

  • targets – [in] pointer to a host array of target wires

  • numTargets – [in] the number of target wires

  • controls – [in] pointer to a host array of control wires

  • controlBitValues – [in] pointer to a host array of control bit values

  • numControls – [in] the number of control wires

custatevecExSVUpdaterEnqueueUnitaryChannel

custatevecStatus_t custatevecExSVUpdaterEnqueueUnitaryChannel(custatevecExSVUpdaterDescriptor_t svUpdater, const void *const *unitaries, cudaDataType_t unitariesDataType, const custatevecExMatrixType_t *exMatrixTypes, int32_t numUnitaries, custatevecMatrixLayout_t layout, const double *probabilities, const int32_t *channelWires, int32_t numChannelWires)

Enqueue mixed unitary channel.

This function enqueues a mixed unitary channel to SVUpdater.

The unitaries argument is a host pointer to an array of unitary matrices. Each array element in the unitaries argument points to an array of matrix elements that represents a unitary matrix. The actual data type of matrix elements is specified by the unitariesDataType argument. The exMatrixTypes is a host array that specifies the matrix types of unitary matrices. The matrix types specified by exMatrixTypes determine the lengths of matrix element arrays specified by the unitaries argument. The layout argument specifies the matrix layout in the same way as described in custatevecExSVUpdaterEnqueueMatrix().

The probabilities argument is a host array that represents the probabilities associated with the specified unitary matrices to be randomly sampled. The array length is numUnitaries. The total sum of all probabilities must be less than or equal to 1.0. When the sum is less than 1.0, the remaining probability corresponds to no transformation, implementing a probabilistic quantum channel where the state vector remains unchanged with probability (1 - sum_of_probabilities). The probabilities are used as-is for sampling without normalization in this API.

If any probability value in the probabilities array is zero or negative, CUSTATEVEC_STATUS_INVALID_VALUE is returned.

Only CUDA_C_64F is acceptable if the SVUpdater data type is CUDA_C_64F by calling custatevecExConfigureSVUpdater(). Also, CUDA_C_64F and CUDA_C_32F are acceptable if the SVUpdater data type is CUDA_C_32F.

The channelWires and numChannelWires arguments specify the wires on which the sampled unitary matrix is to be applied. The max number of wires are limited to 15 if CUSTATEVEC_EX_MATRIX_DENSE or CUSTATEVEC_EX_MATRIX_ANTI_DIAGONAL specified, and 30 if CUSTATEVEC_EX_MATRIX_DIAGONAL, specified, respectively. However, 10 or more wires is not recommended; the recommended number of wires for typical usage is 6 or fewer.

Parameters

  • svUpdater – [inout] SVUpdater instance

  • unitaries – [in] host pointer to an array of unitary matrix elements

  • unitariesDataType – [in] dataType of the specified unitary matrices

  • exMatrixTypes – [in] matrix types of the specified unitary matrices

  • numUnitaries – [in] the number of matrices.

  • layout – [in] layout of the specified unitary matrices

  • probabilities – [in] host array that holds the probabilities

  • channelWires – [in] wires that sampled unitary channel is applied

  • numChannelWires – [in] the number of wires

custatevecExSVUpdaterEnqueueGeneralChannel

custatevecStatus_t custatevecExSVUpdaterEnqueueGeneralChannel(custatevecExSVUpdaterDescriptor_t svUpdater, const void *const *matrices, cudaDataType_t matrixDataType, const custatevecExMatrixType_t *exMatrixTypes, int32_t numMatrices, custatevecMatrixLayout_t layout, const int32_t *channelWires, int32_t numChannelWires)

Enqueue general channel.

This function enqueues a general channel to SVUpdater.

The matrices argument is a host pointer to an array of matrices that are assumed to be Kraus operators defining the general quantum channel. Each array element in the matrices argument points to an array of matrix elements that represents a matrix. The actual data type of matrix elements is specified by the matrixDataType argument. The numMatrices argument specifies the number of matrices. The exMatrixTypes is a host array that specifies the matrix types of the matrices. The matrix types specified by exMatrixTypes determine the lengths of matrix element arrays specified by the matrices argument. The layout argument specifies the matrix layout in the same way as described in custatevecExSVUpdaterEnqueueMatrix(). If a general channel is queued to SVUpdater, state vector will be normalized, and its norm will be 1 after the call of custatevecExSVUpdaterApply().

Only CUDA_C_64F is acceptable if the SVUpdater data type is CUDA_C_64F by calling custatevecExConfigureSVUpdater(). Also, CUDA_C_64F and CUDA_C_32F are acceptable if the SVUpdater data type is CUDA_C_32F.

The channelWires and numChannelWires arguments specify the wires on which the general channel is to be applied. The max number of wires is limited to 15 for all matrix types. However, 10 or more wires is not recommended; the recommended number of wires for typical usage is 6 or fewer.

It is the user’s responsibility to provide a complete set of Kraus operators. If an incomplete set of Kraus operators is provided, the SVUpdater may return errors during custatevecExSVUpdaterApply().

Parameters

  • svUpdater – [inout] SVUpdater instance

  • matrices – [in] host pointer to an array of matrix elements

  • matrixDataType – [in] dataType of the matrices

  • exMatrixTypes – [in] matrix types of the specified matrices

  • numMatrices – [in] the number of matrices.

  • layout – [in] layout of the matrices

  • channelWires – [in] wires that the general channel is applied

  • numChannelWires – [in] the number of wires

custatevecExSVUpdaterGetMaxNumRequiredRandnums

custatevecStatus_t custatevecExSVUpdaterGetMaxNumRequiredRandnums(custatevecExSVUpdaterDescriptor_t svUpdater, int32_t *maxNumRequiredRandnums)

Get the max number of required random numbers.

Get the max required number of random numbers to call custatevecExSVUpdaterApply().

Parameters

  • svUpdater – [in] SVUpdater instance

  • maxNumRequiredRandnums – [out] the max required number of random numbers.

custatevecExSVUpdaterApply

custatevecStatus_t custatevecExSVUpdaterApply(custatevecExSVUpdaterDescriptor_t svUpdater, custatevecExStateVectorDescriptor_t stateVector, const double *randnums, int32_t numRandnums)

Apply queued operations.

Apply operations queued in SVUpdater to the specified state vector.

The data type of state vector should be identical to that of SVUpdater specified by calling custatevecExConfigureSVUpdater(). Otherwise, this API returns CUSTATEVEC_STATUS_INVALID_VALUE. The randnums and numRandnums arguments pass the array of random numbers that is utilized to apply noise channels. Each random number in the randnums array must be in the range [0, 1). The number of required random numbers is retrieved by calling custatevecExSVUpdaterGetMaxNumRequiredRandnums().

It’s a user’s responsibility to generate the required number of random numbers in the valid range. If a given random number is not in the range, the value is clipped.

Parameters

  • svUpdater – [inout] SVUpdater instance

  • stateVector – [inout] state vector instance

  • randnums – [in] a host pointer to an array of random numbers in the range [0, 1)

  • numRandnums – [in] the number of random numbers