flagquantum 0.2.0

Quantum computing, built for learning.

A PyTorch-first framework for differentiable quantum computing and quantum AI.

Quick start · Documentation · Examples

Turn quantum circuits into trainable models. FlagQuantum brings PyTorch learning, multiple simulation representations, and hardware execution into one workflow. Its long-term goal is a continuous path from local scientific exploration to distributed training, device modeling, and fault-tolerant quantum computing research.

• Train with PyTorch. Compose quantum and classical layers with autograd and familiar optimizers.
• Choose the representation. Statevector, matrix product state (MPS), and tensor-network simulation for different circuit structures and resource budgets.
• Connect simulation to hardware. Keep the circuit and requested observable explicit as you move between supported execution targets.

This is a pre-release framework. Local training and selected distributed paths have correctness evidence; support is specific to each backend and workload. See the validation scope for what has been tested and what remains a research goal.

Train your first quantum model

Requires Python 3.10–3.12. From the repository root:

python -m pip install -e .

Build a two-qubit circuit and learn its rotation angle by minimizing ⟨Z₀⟩. fq.Module exposes the quantum model to PyTorch; outputs selects what to measure after training.

import torch
import flagquantum as fq


def circuit(parameters):
    return fq.Circuit(2).ry(0, parameters[0]).cx(0, 1)


model = fq.Module(circuit, n_parameters=1, init=torch.tensor([0.25]))
training = fq.train(
    model,
    optimizer=torch.optim.Adam(model.parameters(), lr=0.05),
    objective=lambda z: z.mean(),
    steps=10,
)

trained_circuit = circuit(next(model.parameters()).detach())
measurement = fq.expectation(fq.Z(0))
result = fq.run(trained_circuit, outputs=measurement)
print(result.expectation())

For a complete classical–quantum model, follow the hybrid training example.

Same circuit. Different execution targets.

The experimental adapters can evaluate the same observable on a Jiuding GPU workspace or Quafu quantum hardware. Configure the Jiuding workspace and credentials or the Quafu token and QSteed plugin before running the corresponding call.

# GPU simulation in a running Jiuding workspace
jiuding_result = fq.run(
    trained_circuit, target="jiuding:gpu", outputs=measurement,
)

# Quantum hardware: compile, submit, and estimate from measured shots
quafu_result = fq.run(
    trained_circuit, target="quafu:Baihua", compiler="qsteed",
    outputs=measurement, shots=1024,
)

Jiuding computes a simulated expectation; Quafu estimates it from hardware measurements. The training example runs on your local machine; these calls evaluate the trained circuit remotely. Live provider access is required and is not certified by the local or A800 checks.

Go further

Connect simulation with device observations. Use QPU digital twins to compare calibration-based model predictions with measured counts. See the experiment guide for task binding and the scope of hardware validation.

Toward fault-tolerant quantum computing. Start with a local QEC memory experiment connecting syndrome extraction, decoding, and correction. Logical operations and hardware feedback are longer-term research goals.

Quantum AI tutorials · Distributed statevector · Distributed MPS · ARCHITECTURE.md

Support varies by execution path. See the capability catalog for maturity and limitations.

Benchmarks and validated results

Contributing · Apache License 2.0