QkNeighbors
QkNeighbors
struct QkNeighbors
An adjacency-list representation of a coupling graph.
This is initialized by qk_neighbors_from_target.
This object is read-only from C. To satisfy the safety guarantees of qk_neighbors_clear, you must not overwrite any data initialized by qk_neighbors_from_target, including any pointed-to data.
Representation
After initialization by qk_neighbors_from_target, the structure will be in one of two modes:
- all-to-all connectivity
- limited two-qubit connectivity
In the all-to-all case, the neighbors and partition pointers will both be the null pointer, and num_qubits will be the number of qubits in the QkTarget. These objects do not have backing allocations, and do not need to be given to qk_neighbors_clear (though this function is a safe no-op in this case).
In the limited two-qubit case (which is by far the more common for real hardware), see the documentation of the structure members for their interpretation.
const uint32_t *neighbors
A partitioned adjacency-list representation of the neighbors of each qubit. This pointer is valid for exactly partition[num_qubits + 1] reads.
For qubit number i, its neighbors are the values between offsets partition[i] (inclusive) and partition[i + 1] (exclusive). The values between these two offsets are sorted in ascending order and contain no duplicates.
const size_t *partition
How the neighbors field is partitioned into slices. This pointer is valid for exactly num_qubits + 1 reads. The first value is always 0, and values increase monotonically.
uint32_t num_qubits
The number of qubits.
Functions
qk_neighbors_is_all_to_all
bool qk_neighbors_is_all_to_all(const QkNeighbors *neighbors)
Does this coupling graph represent all-to-all connectivity?
This is represented by neighbors and partition being null pointers, so they are not valid for any reads.
Safety
neighbors must point to a valid, initialized QkNeighbors object.
Parameters
- neighbors – The coupling graph.
Returns
Whether the graph represents all to all connectivity.
qk_neighbors_from_target
bool qk_neighbors_from_target(const QkTarget *target, QkNeighbors *neighbors)
Initialize a QkNeighbors object from a QkTarget.
If the target contains multi-qubit gates, they will be ignored and the connectivity will only represent the two-qubit coupling constraints. If the target represents all-to-all connectivity, the function returns true, and the output pointers will be initialized to be null pointers, in keeping with the representation of all-to-all connectivity.
Examples
QkTarget *target = build_target_from_somewhere();
QkNeighbors neighbors;
if (qk_neighbors_from_target(target, &neighbors)) {
printf("All-to-all connectivity on &lu qubits.\n", neighbors.num_qubits);
return;
}
printf("Qubit 3 has %zu neighbors.\n", neighbors.partition[4] - neighbors.partition[3]);
printf("Those neighbors are: [");
for (size_t offset = neighbors.partition[3]; offset < neighbors.partition[4]; offset++) {
printf("%u%s",
neighbors.neighbors[offset],
offset + 1 == neighbors.partition[4] ? "" : ", ");
}
printf("]\n");
qk_neighbors_clear(&neighbors);Safety
target must point to a valid QkTarget object. neighbors must be aligned and safe to write to, but need not be initialized.
Parameters
- target – The target to read the connectivity from.
- neighbors – The
QkNeighborsobject to initialize.
Returns
Whether the QkTarget represented all-to-all connectivity (true) or has regular connectivity (false).
qk_neighbors_clear
void qk_neighbors_clear(QkNeighbors *neighbors)
Free all the allocations within the object.
After calling this function, the QkNeighbors object will contain null pointers in all its allocations and present as if it represents all-to-all connectivity.
This should only be called on QkNeighbors objects that were initialized by qk_neighbors_from_target.
Safety
neighbors must point to a valid, initialized QkNeighbors object, which must have been initialized by a call to qk_neighbors_from_target and unaltered since then.
Parameters
- neighbors – A pointer to a
QkNeighborsobject.