QkQuantumRegister

typedef struct QkQuantumRegister QkQuantumRegister

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 preseserved when exporting the circuit to interchange languages.

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

#include <qiskit.h>

QkQuantumRegister *qreg = qk_quantum_register_new(5, "my_qreg");

Which creates a new 5 qubit register named "my_qreg".

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

QkCircuit *qc = qk_circuit_new(0, 0);
qk_circuit_add_quantum_register(qc, qreg);
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_quantum_register_new

QkQuantumRegister *qk_quantum_register_new(uint32_t num_qubits, const char *name)

Construct a new owning quantum register with a given number of qubits and name

Example

QkQuantumRegister *qr = qk_quantum_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_qubits – The number of qubits 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_quantum_register_free

void qk_quantum_register_free(QkQuantumRegister *reg)

Free a quantum register.

Example

QkQuantumRegister *qr = qk_quantum_register_new(1024, "qreg");
qk_quantum_register_free(qr);

Safety

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

Parameters

reg – A pointer to the register to free.

qk_quantum_register_name

char *qk_quantum_register_name(const QkQuantumRegister *qreg)

Get the name of a quantum register.

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

Example

QkQuantumRegister *qr = qk_quantum_register_new(5, "my_qreg");
char *name = qk_quantum_register_name(qr);
printf("Register name: %s\n", name);
qk_str_free(name);
qk_quantum_register_free(qr);

Safety

Behavior is undefined if qreg is not a valid, non-null pointer to a QkQuantumRegister.

Parameters

qreg – A pointer to the quantum 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_quantum_register_num_bits

size_t qk_quantum_register_num_bits(const QkQuantumRegister *qreg)

Get the number of bits in a quantum register.

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

Example

QkQuantumRegister *qr = qk_quantum_register_new(5, "my_qreg");
size_t num_qubits = qk_quantum_register_num_bits(qr);
printf("Number of qubits: %zu\n", num_qubits);  // Prints: 5
qk_quantum_register_free(qr);

Safety

Behavior is undefined if qreg is not a valid, non-null pointer to a QkQuantumRegister.

Parameters

qreg – A pointer to the quantum register.

Returns

The number of bits in the register.

qk_quantum_register_circuit_bits

void qk_quantum_register_circuit_bits(const QkQuantumRegister *qreg, const QkCircuit *circuit, uint32_t *out_bits)

Get the circuit bit indices for all qubits in a quantum register.

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

Example

QkCircuit *qc = qk_circuit_new(2, 0);
QkQuantumRegister *qr = qk_quantum_register_new(3, "my_qreg");
qk_circuit_add_quantum_register(qc, qr);

uint32_t bit_indices[3];

qk_quantum_register_circuit_bits(qr, qc, bit_indices);

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

qk_quantum_register_free(qr);
qk_circuit_free(qc);

Safety

Behavior is undefined if:

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

Parameters

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

Was this page helpful?

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