cuStabilizer functions#

Library Initialization and Management API#

int custabilizerGetVersion()#

Returns the semantic version number of the cuStabilizer library.

Returns:: Combined version number in format 10000 * major + 100 * minor + patch.

const char *custabilizerGetErrorString(custabilizerStatus_t status)#

Get the description string for a given cuStabilizer status code.

Parameters:: status – [in] The status code.
Returns:: A null-terminated string describing the status code.

custabilizerStatus_t custabilizerCreate(custabilizerHandle_t *handle)#

Create and initialize the library context.

Parameters:: handle – [out] Library handle.
Returns:: custabilizerStatus_t

custabilizerStatus_t custabilizerDestroy(custabilizerHandle_t handle)#

Destroy the library context.

Parameters:: handle – [in] Library handle.
Returns:: custabilizerStatus_t

Circuit API#

group Circuit

Typedefs

typedef void *custabilizerCircuit_t#: Opaque data structure holding the Circuit.

Functions

custabilizerStatus_t custabilizerCircuitSizeFromString( const custabilizerHandle_t handle, const char *circuitString, int64_t *bufferSize )#

Returns the size of the device buffer required for a circuit.

Parameters:

handle – [in] Library handle.
circuitString – [in] String representation of the circuit.
bufferSize – [out] Size of the buffer in bytes.

Returns:

custabilizerStatus_t

custabilizerStatus_t custabilizerCreateCircuitFromString( const custabilizerHandle_t handle, const char *circuitString, void *bufferDevice, int64_t bufferSize, custabilizerCircuit_t *circuit )#

Create a new circuit from a string representation.

The string format is compatible with Stim circuit string.

Example:

custabilizerHandle_t handle;
custabilizerCreate(&handle);

char circuitString[] =
   "H 0\n"
   "X_ERROR(0.5) 1\n"
   "CNOT 0 1\n";
int64_t bufferSize;
custabilizerCircuit_t circuit;
custabilizerCircuitSizeFromString(handle, circuitString, &bufferSize);
void *buffer;
cudaMalloc(&buffer, bufferSize);
custabilizerCreateCircuitFromString(handle, circuitString, buffer,
                                    bufferSize, &circuit);

Use custabilizerFrameSimulatorApplyCircuit to run the circuit.

Parameters:

handle – [in] Library handle.
circuitString – [in] String representation of the circuit.
bufferDevice – [inout] Device buffer to store the circuit.
bufferSize – [in] Size of the device buffer in bytes.
circuit – [out] Pointer to the created circuit.

Returns:

custabilizerStatus_t

custabilizerStatus_t custabilizerDestroyCircuit( custabilizerCircuit_t circuit )#

Destroy a circuit.

Parameters:: circuit – [in] Circuit to destroy.
Returns:: custabilizerStatus_t

Simulator API#

group FrameSimulator

Typedefs

typedef void *custabilizerFrameSimulator_t#: Opaque data structure holding the simulator state.

Functions

custabilizerStatus_t custabilizerCreateFrameSimulator( const custabilizerHandle_t handle, int64_t numQubits, int64_t numShots, int64_t numMeasurements, int64_t tableStrideMajor, custabilizerFrameSimulator_t *frameSimulator )#

Create a FrameSimulator.

The stride is specified by the tableStrideMajor parameter, which is usually (numShots + 7)/8 padded to the next multiple of 4.

The data is updated by calling custabilizerFrameSimulatorApplyCircuit.

Parameters:

handle – [in] Library handle.
numQubits – [in] Number of qubits in the Pauli frame.
numShots – [in] Number of samples to simulate.
numMeasurements – [in] Number of measurements in the measurement table
tableStrideMajor – [in] Stride over the major axis for all input bit tables. Specified in bytes and must be a multiple of 4.
frameSimulator – [out] Pointer to the created frame simulator.

Returns:

custabilizerStatus_t

custabilizerStatus_t custabilizerDestroyFrameSimulator( custabilizerFrameSimulator_t frameSimulator )#

Destroy the FrameSimulator.

Parameters:: frameSimulator – [in] Frame simulator to destroy.
Returns:: custabilizerStatus_t

custabilizerStatus_t custabilizerFrameSimulatorApplyCircuit( const custabilizerHandle_t handle, custabilizerFrameSimulator_t frameSimulator, const custabilizerCircuit_t circuit, int randomizeFrameAfterMeasurement, uint64_t seed, custabilizerBitInt_t *xTableDevice, custabilizerBitInt_t *zTableDevice, custabilizerBitInt_t *mTableDevice, cudaStream_t stream )#

Run Pauli frame simulation using the circuit.

Use custabilizerCreateFrameSimulator to create a frame simulator with appropriate parameters for this call. The method accepts an initial state in the form of bit tables. All bit tables assume LSB ordering. That is, the bit for the first shot is stored at mask 0x1. If the buffers are smaller than required minimum size, the behavior is undefined.

The xTableDevice and zTableDevice specify the initial Pauli frame in a qubit-major format. The operator on Pauli string I and qubit J is encoded by bits I on row J in x_table and z_table.

(x_table[J][I], z_table[J][I])   Pauli operator
             0, 0                     I
             0, 1                     Z
             1, 0                     X
             1, 1                     Y

Here is an illustrative example of bit tables with 4 paulis on 3 qubits: XYZ, IIZ, XII, IIY.

int64_t numQubits = 3;
int64_t numShots = 32;
int64_t numMeasurements = 2;
int64_t stride = (numShots + 7) / 8;
int bit_table_bytes = numQubits * stride;
int m_table_bytes = numMeasurements * stride;
int bit_int_bytes = sizeof(custabilizerBitInt_t);
custabilizerBitInt_t x_table[bit_table_bytes / bit_int_bytes] = {
    //    IXIX 
    //    IIIY
    //    YIZZ 
// pauli  4321
    0x00000101, // Qubit 0
    0x00000001, // Qubit 1
    0x00001000  // Qubit 2
};
custabilizerBitInt_t z_table[bit_table_bytes / bit_int_bytes] = {
// pauli  4321
    0x00000000, // Qubit 0
    0x00000001, // Qubit 1
    0x00001011  // Qubit 2
};
custabilizerBitInt_t m_table[m_table_bytes / bit_int_bytes] = {
    0x00000000,
    0x00000000
};
custabilizerBitInt_t *xTableDevice, *zTableDevice, *mTableDevice;
cudaMalloc(&xTableDevice, bit_table_bytes);
cudaMalloc(&zTableDevice, bit_table_bytes);
cudaMalloc(&mTableDevice, m_table_bytes);
cudaMemcpy(xTableDevice, x_table, bit_table_bytes, cudaMemcpyHostToDevice);
cudaMemcpy(zTableDevice, z_table, bit_table_bytes, cudaMemcpyHostToDevice);
cudaMemcpy(mTableDevice, m_table, m_table_bytes, cudaMemcpyHostToDevice);

custabilizerHandle_t handle;
custabilizerCreate(&handle);
custabilizerFrameSimulator_t frameSimulator;
custabilizerStatus_t status = custabilizerCreateFrameSimulator(handle,
                              numQubits, numShots, numMeasurements,
                              stride, &frameSimulator);

int seed = 5;
cudaStream_t stream = 0;
int rnd_frame = 0;
// Assuming `circuit` is defined earlier
status = custabilizerFrameSimulatorApplyCircuit(
                              handle, frameSimulator, circuit, rnd_frame,
                              seed, xTableDevice, zTableDevice, mTableDevice, stream);

custabilizerDestroyFrameSimulator(frameSimulator);
custabilizerDestroy(handle);
cudaFree(xTableDevice);
cudaFree(zTableDevice);
cudaFree(mTableDevice);
custabilizerDestroy(handle);

Parameters:

handle – [in] Library handle.
frameSimulator – [in] An instance of FrameSimulator with parameters consistent with the bit tables
circuit – [in] A circuit that acts on at most numQubits and contains at most numMeasurements measurements
randomizeFrameAfterMeasurement – [in] Disabling the randomization is helpful in some cases to focus on the error frame propagation.
seed – [in] Random seed.
xTableDevice – [inout] Device buffer of the X bit table in qubit-major order. Must be of size at least numQubits * tableStrideMajor
zTableDevice – [inout] Device buffer of the Z bit table in qubit-major order. Must be of size at least numQubits * tableStrideMajor
mTableDevice – [inout] Device buffer of the measurement bit table in measurement-major order. Must be of size at least numMeasurements * tableStrideMajor
stream – [in] CUDA stream.

Returns:

custabilizerStatus_t