QkClassicalRegister

typedef struct QkClassicalRegister QkClassicalRegister

A common way to instantiate several bits at once is to create a register. A register is a named collection of bits. Creating a register enables giving a collection of bits a name which can be use as metadata around specific bits in a circuit. This name will also typically be preserved when exporting the circuit to interchange languages.

You can create a register by calling qk_classical_register_new(), for example:

#include <qiskit.h>

QkClassicalRegister *creg = qk_classical_register_new(5, "my_creg");

Which creates a new 5 classical bit register named "my_creg".

Then to add the register to a circuit you use the qk_circuit_add_classical_register() function:

QkCircuit *qc = qk_circuit_new(0, 0);
qk_circuit_add_classical_register(qc, creg);
uint32_t num_qubits = qk_circuit_num_qubits(qc); // 5

While circuits track registers, the registers themselves impart almost no behavioral differences on circuits.

Functions

qk_classical_register_new

QkClassicalRegister *qk_classical_register_new(uint32_t num_clbits, const char *name)

Construct a new owning classical register with a given number of clbits and name

Example

QkClassicalRegister *cr = qk_classical_register_new(5, "five_qubits");

Safety

The name parameter must be a pointer to memory that contains a valid nul terminator at the end of the string. It also must be valid for reads of bytes up to and including the nul terminator.

Parameters

num_clbits – The number of clbits to create the register for
name – The name string for the created register. The name must be comprised of valid UTF-8 characters.

Returns

A pointer to the created register

qk_classical_register_free

void qk_classical_register_free(QkClassicalRegister *reg)

Free a classical register.

Example

QkClassicalRegister *cr = qk_classical_register_new(1024, "creg");
qk_classical_register_free(cr);

Safety

Behavior is undefined if reg is not either null or a valid pointer to a QkClassicalRegister.

Parameters

reg – A pointer to the register to free.

qk_classical_register_name

char *qk_classical_register_name(const QkClassicalRegister *creg)

Get the name of a classical register.

Returns a newly allocated C string containing the name of the classical register.

Example

QkClassicalRegister *cr = qk_classical_register_new(3, "my_creg");
char *name = qk_classical_register_name(cr);
printf("Register name: %s\n", name);
qk_str_free(name);
qk_classical_register_free(cr);

Safety

Behavior is undefined if creg is not a valid, non-null pointer to a QkClassicalRegister.

Parameters

creg – A pointer to the classical register.

Returns

A pointer to a newly allocated null-terminated string containing the register name. The caller must free this string using qk_str_free.

qk_classical_register_num_bits

size_t qk_classical_register_num_bits(const QkClassicalRegister *creg)

Get the number of classical bits in a classical register.

Returns the size (number of classical bits) of the classical register.

Example

QkClassicalRegister *cr = qk_classical_register_new(3, "my_creg");
size_t num_clbits = qk_classical_register_num_bits(cr);
printf("Number of clbits: %zu\n", num_clbits);  // Prints: 3
qk_classical_register_free(cr);

Safety

Behavior is undefined if creg is not a valid, non-null pointer to a QkClassicalRegister.

Parameters

creg – A pointer to the classical register.

Returns

The number of classical bits in the register.

qk_classical_register_circuit_bits

void qk_classical_register_circuit_bits(const QkClassicalRegister *creg, const QkCircuit *circuit, uint32_t *out_bits)

Get the circuit bit indices for all clbits in a classical register.

Outputs a mapping from each clbit in the classical register to its corresponding index in the circuit’s clbit list. If a clbit from the register is not present in the circuit, its index in the mapping will be UINT32_MAX.

Example

QkCircuit *qc = qk_circuit_new(0, 2);
QkClassicalRegister *cr = qk_classical_register_new(3, "my_creg");
qk_circuit_add_classical_register(qc, cr);

uint32_t bit_indices[3];

qk_classical_register_circuit_bits(cr, qc, bit_indices);

// bit_indices now contains [2, 3, 4] since all clbits are in the circuit
// and the circuit has 2 anonymous clbits

qk_classical_register_free(cr);
qk_circuit_free(qc);

Safety

Behavior is undefined if:

creg is not a valid, non-null pointer to a QkClassicalRegister.
circuit is not a valid, non-null pointer to a QkCircuit.
creg has one or more bits and out_bits is not an aligned, non-null pointer to an array with at least qk_classical_register_num_bits(creg) elements.

Parameters

creg – A pointer to the classical register to map.
circuit – A pointer to the circuit containing the clbits.
out_bits – A pointer to an array where the mapped indices will be written. The array must be pre-allocated with at least qk_classical_register_num_bits elements for creg. Each element will contain either the circuit bit index or UINT32_MAX if the clbit is not in the circuit.

Was this page helpful?

Report a bug, typo, or request content on GitHub.