API reference

The whole public API is one class, qsengine.QuantumCircuit, and a version string. Backends are chosen with the backend argument: "auto", "cpu" or "gpu".

import qsengine

qc = qsengine.QuantumCircuit(2)

QuantumCircuit

QuantumCircuit(num_qubits, num_clbits=0)

Create an empty circuit on num_qubits qubits, all starting in |0⟩, and num_clbits classical bits, all starting at 0. At most 30 qubits and 64 classical bits.

Raises ValueError if either is above its maximum.

qc.num_qubits, qc.num_clbits

The number of qubits and of classical bits. Read-only.

Returns int.

len(qc)

The number of operations recorded so far: gates, measurements and resets. A swap counts as one.

Returns int.

print(qc), str(qc)

A text drawing of the circuit, one wire per qubit with qubit 0 on top. ● marks a control, × the ends of a swap.

Returns str.

qc.h(q), qc.x(q), qc.y(q), qc.z(q), qc.s(q), qc.sdg(q), qc.t(q), qc.tdg(q)

Record a single-qubit gate on qubit q.

Raises ValueError if q is out of range.

qc.rx(q, theta), qc.ry(q, theta), qc.rz(q, theta), qc.p(q, lam)

Record a rotation of theta radians about the X, Y or Z axis, or a phase of lam radians.

Raises ValueError if q is out of range or the angle is NaN or infinite.

qc.u(q, theta, phi, lam)

Record the general single-qubit gate U, in the same convention as Qiskit.

Raises ValueError if q is out of range or an angle is NaN or infinite.

qc.cx(control, target), qc.cz(control, target), qc.cp(control, target, lam), qc.crz(control, target, theta)

Record a CNOT, controlled-Z, controlled-phase or controlled-RZ gate.

Raises ValueError if a qubit is out of range, control equals target, or an angle is NaN or infinite.

qc.swap(qubit1, qubit2)

Record a SWAP, as three CNOTs.

Raises ValueError if a qubit is out of range or the two are equal.

qc.ccx(control1, control2, target)

Record a Toffoli gate.

Raises ValueError if a qubit is out of range or used twice.

qc.measure(qubit, clbit)

Measure qubit into classical bit clbit, part-way through the circuit or at the end. Both may be equal-length lists, as in qc.measure([0, 1], [0, 1]), of Python or NumPy integers.

Raises ValueError if a qubit or classical bit is out of range, or inside if_test.

qc.reset(qubit)

Put qubit back to |0⟩, whatever state it is in, so it can be used again.

Raises ValueError if qubit is out of range, or inside if_test.

with qc.if_test(clbits, value):

Gates added inside the block run only in shots where the classical bits equal value. clbits is one classical bit or a list; bit i of value is the value required of clbits[i].

Raises ValueError if a classical bit is out of range, value does not fit, or blocks are nested.

qc.unitary(matrix, target, controls=[])

Record any 2x2 unitary matrix (nested lists or a NumPy array) on target, applied only where every qubit in controls is |1⟩. A matrix within 1e-9 of unitary is replaced by the nearest unitary matrix.

Raises ValueError if the matrix is not 2x2 or not unitary, or a qubit is out of range or used twice.

qc.run(shots=1024, seed=None, backend="auto")

Simulate the circuit shots times and count the results. If the circuit measures, the bitstrings are its classical bits; otherwise every qubit is measured at the end. A circuit that measures part-way is simulated once per shot. Pass seed for repeatable counts.

Returns dict[str, int] mapping bitstrings (bit 0 on the right) to counts.

qc.probabilities(backend="auto")

Simulate the circuit and return the probability of each of the 2ⁿ basis states, computed rather than sampled. Measurements at the very end are ignored. With backend="auto" the result has 32-bit precision from 14 qubits when a GPU is present; pass backend="cpu" for 64-bit.

Returns a NumPy float64 array. Raises ValueError if the circuit measures or resets before a later gate.

qc.statevector(backend="auto")

Simulate the circuit and return the amplitudes, computed rather than sampled. Measurements at the very end are ignored. With backend="auto" the result has 32-bit precision from 14 qubits when a GPU is present; pass backend="cpu" for 64-bit.

Returns a NumPy complex128 array. Raises ValueError if the circuit measures or resets before a later gate.

qc.expectation(paulis, backend="auto")

The expectation value of a Pauli string such as "ZZI" (one letter per qubit, qubit 0 on the right), or of each string in a list, from one simulation.

Returns float for one string, a NumPy float64 array for a list. Raises ValueError for a string of the wrong length or with letters other than I, X, Y, Z.

qsengine.__version__

The installed version.

Returns str, for example "1.1.1".

Errors

Invalid input raises immediately, on the line that caused it, and the gate is not recorded. These are the exact messages: