FQkit

FQkit is a small Python framework for building and simulating quantum circuits. The source stays short on purpose, so you can learn how a quantum computer works by reading it and changing it.

Documentation website: the full docs live in website/: a Next.js + Nextra site. Run it locally with cd website && npm install && npm run dev, or deploy it for free on Vercel (see the website README).

Features

• Qubits and parameterized gates (H, RX, RY, RZ)
• Multi-qubit gates: CNOT, CZ, SWAP, Toffoli
• Circuit construction with QuantumCircuit
• Parameter binding for variational circuits
• A statevector simulator that returns the final state
• Measurement with shot-based sampling
• Export to OpenQASM 2.0: run your circuits on real IBM hardware via Qiskit

Installation

pip install fqkit

FQkit needs Python 3.9 or newer. NumPy is installed with it.

To work on the source, clone the repository and install it in editable mode:

git clone https://github.com/Felixowusu20/Fqkit.git
cd Fqkit
pip install -e ".[dev]"
pytest

Quick start

Build a Bell state, an entangled pair of qubits, and measure it:

from fqkit import QuantumCircuit, Hadamard, CNOT, run, measure_all

qc = QuantumCircuit(2)
qc.add_gate(Hadamard(), [0])      # put qubit 0 into superposition
qc.add_gate(CNOT(), [0, 1])       # entangle qubit 1 with qubit 0

state = run(qc)                   # -> array([0.707, 0, 0, 0.707])
counts = measure_all(state, shots=1024)

print("State :", state)
print("Counts:", counts)          # -> {'00': ~512, '11': ~512}

Variational circuits

Gates can take symbolic Parameters that you bind to numbers later: the basis of variational algorithms like VQE and QAOA:

from fqkit import QuantumCircuit, Hadamard, RX, Parameter, bind_parameters, run, measure_all

theta = Parameter("theta")

qc = QuantumCircuit(2)
qc.add_gate(Hadamard(), [0])
qc.add_gate(RX(theta), [1])

bind_parameters(qc, {"theta": 3.14159})

counts = measure_all(run(qc), shots=1024)
print(counts)

Export to OpenQASM: run on real hardware

Any circuit can be exported to OpenQASM 2.0, the open standard that Qiskit reads. That means a circuit you build in fqkit can run on a real quantum computer through IBM Quantum's free tier: no hardware of your own needed. Everything in this pipeline (OpenQASM, Qiskit, the IBM free tier) costs nothing.

from fqkit import QuantumCircuit, Hadamard, CNOT

qc = QuantumCircuit(2)
qc.add_gate(Hadamard(), [0])
qc.add_gate(CNOT(), [0, 1])

print(qc.to_qasm())          # or: to_qasm(qc)

OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0], q[1];
measure q -> c;

Load it in Qiskit (free)

pip install qiskit (free and open source), then:

from qiskit import QuantumCircuit as QiskitCircuit
from qiskit.quantum_info import Statevector

qiskit_qc = QiskitCircuit.from_qasm_str(qc.to_qasm(measure=False))
print(Statevector.from_instruction(qiskit_qc).probabilities_dict())
# {'00': 0.5, '11': 0.5}

Run on real hardware

run() stays on your computer. Hardware jobs go through fqkit.hardware, which calls the vendor SDK, waits on the queue, and returns counts in fqkit bit order (qubit 0 on the left). The vendor packages are optional, so a normal install still depends only on NumPy.

pip install "fqkit[ibm]"       # IBM Quantum, through Qiskit Runtime
pip install "fqkit[braket]"    # IonQ, Rigetti, IQM, and AQT, through Amazon Braket
pip install "fqkit[hardware]"  # both

from fqkit.hardware import providers, submit

providers()                    # ibm, ionq, rigetti, iqm, aqt

job = submit(qc, "ibm", shots=1024)
print(job.job_id, job.status())   # QUEUED, RUNNING, COMPLETED, CANCELLED, FAILED
print(job.counts())               # waits for the device

job = submit(qc, "ionq", shots=100)
job = submit(qc, "rigetti", shots=100)

IBM needs a free account at https://quantum.cloud.ibm.com. Save the token once with QiskitRuntimeService.save_account, or pass token= to submit. With no backend name, fqkit picks the least busy real device. Pass backend="ibm_..." to choose one, or backends("ibm", live=True) to list the devices that are up.

IonQ, Rigetti, IQM, and AQT are one Amazon Braket account. Those QPU tasks are billed by AWS. submit(qc, "ionq") targets IonQ Forte-1. Pass backend= as a full device ARN when you need a different chip. job.status() returns immediately. job.counts() blocks until the machine finishes. get_job(machine, job_id) reconnects to a job you already submitted.

The lessons in the browser keep using the local simulator. A hardware token stays in your own Python process.

Project layout

fqkit/
  core/
    qubit.py              # Qubit: an index into Hilbert space
    parameter.py          # Parameter: a symbolic variable
    gate.py               # Gate + H, RX, RY, RZ, CNOT, CZ, SWAP, Toffoli
    operation.py          # Operation: a gate applied to specific qubits
    circuit.py            # QuantumCircuit: an ordered list of operations
    parameter_binding.py  # bind_parameters: substitute symbols -> numbers
    simulator.py          # run: apply gates to a statevector
    measurement.py        # measure_all: sample |amplitude|^2
    qasm.py               # to_qasm: export circuits to OpenQASM 2.0
  hardware/
    ibm.py                # IBM Quantum via Qiskit Runtime
    braket.py             # IonQ, Rigetti, IQM, AQT via Amazon Braket

Convention

FQkit uses big-endian qubit ordering: qubit 0 is the most significant bit of the state-vector index, and the first qubit passed to a multi-qubit gate is its most significant qubit (for CNOT, the control).

Testing

FQkit ships with a pytest suite covering the simulator, every gate, parameter binding, measurement, input validation, and the OpenQASM export, including round-trip tests that load an exported circuit into Qiskit and check that the statevectors match fqkit's own simulator.

pip install -e ".[dev]"   # installs pytest
pytest -v                 # 46 tests

The Qiskit round-trip tests are skipped automatically if Qiskit is not installed. Install it (free) with pip install qiskit to run those too.