# Bit-ordering in Qiskit

If you have a set of $n$ bits (or qubits), you'll usually label each bit $0 \rightarrow n-1$. Different softwares and resources must choose how they order these bits both in computer memory and when displayed on-screen.

## Qiskit conventions

Here's how Qiskit orders bits in different scenarios.

### Quantum circuits

The QuantumCircuit class stores its qubits in a list (QuantumCircuit.qubits). The index of a qubit in this list defines the qubit's label.

from qiskit import QuantumCircuit
qc = QuantumCircuit(2)
qc.qubits  # qubit "0"
Qubit(QuantumRegister(2, 'q'), 0)


### Circuit diagrams

On a circuit diagram, qubit $0$ is the topmost qubit, and qubit $n$ the bottommost qubit. You can change this with the reverse_bits argument of QuantumCircuit.draw (see Change ordering in Qiskit).

qc.x(1)
qc.draw()
q_0: ─────
┌───┐
q_1: ┤ X ├
└───┘


### Integers

When interpreting bits as a number, bit $0$ is the least significant bit, and bit $n$ the most significant. This is helpful when coding because each bit has the value $2^\text{label}$ (label being the qubit's index in QuantumCircuit.qubits). For example, the following circuit execution ends with bit $0$ being 0, and bit $1$ being 1. This is interpreted as the decimal integer 2 (measured with probability 1.0).

from qiskit.primitives import Sampler
qc.measure_all()
Sampler().run(qc).result().quasi_dists
{2: 1.0}


### Strings

When displaying or interpreting a list of bits (or qubits) as a string, bit $n$ is the leftmost bit, and bit $0$ is the rightmost bit. This is because we usually write numbers with the most significant digit on the left, and in Qiskit, bit $n$ is interpreted as the most significant bit.

For example, the following cell defines a Statevector from a string of single-qubit states. In this case, qubit $0$ is in state $|{+}\rangle$, and qubit $1$ in state $|0\rangle$.

from qiskit.quantum_info import Statevector
sv = Statevector.from_label("0+")
sv.probabilities_dict()
{'00': 0.4999999999999999, '01': 0.4999999999999999}


This occasionally causes confusion when interpreting a string of bits, as you might expect the leftmost bit to be bit $0$, whereas it usually represents bit $n$.

### Statevector matrices

When representing a statevector as a list of complex numbers (amplitudes), Qiskit orders these amplitudes such that the amplitude at index $x$ represents the computational basis state $|x\rangle$.

print(sv)  # amplitude of state |01>
print(sv)  # amplitude of state |10>
(0.7071067811865475+0j)
0j


### Gates

Each gate in Qiskit can interpret a list of qubits in its own way, but controlled gates usually follow the convention (control, target).

For example, the following cell adds a controlled-X gate where qubit $0$ is the control and qubit $1$ is the target.

from qiskit import QuantumCircuit
qc = QuantumCircuit(2)
qc.cx(0, 1)
qc.draw()
q_0: ──■──
┌─┴─┐
q_1: ┤ X ├
└───┘


Following all the previously mentioned conventions in Qiskit, this CX-gate performs the transformation $|01\rangle \leftrightarrow |11\rangle$, so has the following matrix.

$\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 \\ 0 & 0 & 1 & 0 \\ 0 & 1 & 0 & 0 \\ \end{pmatrix}$

## Change ordering in Qiskit

To draw a circuit with qubits in reversed order (that is, qubit $0$ at the bottom), use the reverse_bits argument. This only affects the generated diagram and does not affect the circuit; the X-gate still acts on qubit $0$.

from qiskit import QuantumCircuit
qc = QuantumCircuit(2)
qc.x(0)
qc.draw(reverse_bits=True)
q_1: ─────
┌───┐
q_0: ┤ X ├
└───┘


You can use the reverse_bits method to return a new circuit with the qubits' labels reversed (this does not mutate the original circuit).

qc.reverse_bits().draw()
q_0: ─────
┌───┐
q_1: ┤ X ├
└───┘


Note that in this new circuit, the X-gate acts on qubit $1$.