cuStateVec Ex: State Vector Operations#

This section explains the basic concept of cuStateVec Ex API.

Wire#

In cuStateVec Ex, a wire is the logical entity used to represent qubits within quantum circuit simulations. This terminology originates from quantum circuit diagrams, where qubits are represented as horizontal lines (wires) that quantum gates act upon.

An index bit is the fundamental addressing mechanism used in cuStateVec to represent a qubit. In state vector, the index bits of complex array (i.e., the state vector) represent the qubits as a classical entity.

Each wire is mapped to an index bit. The array of that mapping is called the wire ordering. State vector is a high-order tensor built upon power-of-two modes. Wire ordering specifies the tensor mode ordering of the state vector. The number of wires equals the number of index bits in the state vector object.

A wire specifies a qubit in simulations. Throughout the cuStateVec Ex API, operations such as gate application, measurements, and permutations are specified in terms of wires such as target wires and control wires.

Important

In cuStateVec Ex API, the state vector elements and wire ordering are always paired together to represent a quantum state. When accessing state vector elements (e.g., via custatevecExStateVectorGetState() or custatevecExStateVectorSetState()), the interpretation of state vector elements depends on the current wire ordering. This principle applies uniformly across all distribution models—single-device, multi-device, and multi-process configurations.

StateVector and wire ordering#

cuStateVec Ex API provides custatevecExStateVectorDescriptor_t as the object handle of the state vector.

The state vector object has the following components.

  • Device memory pointer to store state vector elements

  • The number of index bits (or wires)

  • Data type of state vector

  • custatevecHandle_t for cuStateVec API utilization

  • Wire ordering

The first four components are identical to those used to call cuStateVec API.

The wire ordering is the new component that defines the order of tensor modes of the state vector as a tensor.

Wire ordering illustration

Wire ordering in state vector#

The index bit represents the absolute position, and the wire is mapped to the index bit. The StateVector object represents quantum state by its elements and the wire ordering. The memory layout of state vector elements is defined by the wire ordering.

To manipulate the wire ordering, the custatevecExStateVectorPermuteIndexBits() API arbitrarily permutes index bits and updates the wire ordering accordingly.

State vector distribution#

On distribution, the state vector is equally sliced and distributed to multiple devices. Each state vector slice distributed to a device is called a sub state vector.

State vector distribution across devices

State vector distribution model#

The number of sub state vectors is always a power of two (e.g., 2, 4, 8, 16), corresponding to the number of devices. Each sub state vector is identified by a sub state vector index and maps to a specific device.

There are two types of index bits (wires) in a distributed state vector:

  • Local index bits: Index bits within each sub state vector. Operations on local index bits are executed independently on each device without inter-device communication.

  • Global index bits: Index bits that distinguish between different sub state vectors. Operations on global index bits require data transfers between devices.

The total number of wires is:

numWires = numGlobalIndexBits + numLocalIndexBits

where numGlobalIndexBits = log2(numDevices) or log2(numProcesses).

Example API flow#

The cuStateVec Ex API internally permutes wire ordering to apply operations to the state vector.

For operations on local index bits, state vector elements are localized to each device. Thus, operations are applied concurrently on each device without data transfers. However, for operations on global index bits, the cuStateVec Ex API can reorder wires to localize state vector elements to update the state vector.

Example API flow for distributed operations

Example API flow showing wire reordering for operations#

The above figure shows an example for gate application. In order to apply a dense gate matrix on a global wire, the custatevecExApplyMatrix() API swaps the global index bit with a local index bit to move the global wire to a local index bit. Then, the matrix is applied on the local wire.

The wire ordering can be modified by API calls to efficiently execute operations. The resulting wire ordering is API implementation defined.

For detailed concepts on distributed index bit operations, see Distributed Index Bit Swap.