flagquantum 0.3.1

Quantum computing, built for learning.

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

Qubit ordering · 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.

Support is specific to each backend and workload. Local training and selected distributed paths have correctness evidence. See the validation scope for what has been tested and what remains a research goal.

Qubit ordering: qubit 0 is the most-significant bit

By default, a circuit starts in |00...0>, with amplitude 1 at statevector index 0 and 0 everywhere else. For example, applying X to qubit 0 of |000> produces |100> at index 4; applying it to qubit 2 produces |001> at index 1. This matches the tensor-product notation |q0> ⊗ |q1> ⊗ ... ⊗ |q(n-1)>, keeping equations, matrices, and qubit lists in the same left-to-right order.

Endianness affects statevector, matrix, and bitstring indexing, not the (control, target) order of gate arguments. Convert representations at framework boundaries instead of reversing gate arguments. Cloud services commonly expose measurement results rather than raw statevectors, so the service rows describe the order visible at FlagQuantum's result boundary.

Install and train your first quantum model

Requires Python 3.10–3.12. Choose the command for your computer.

macOS (Apple Silicon):

python -m pip install flagquantum

This release publishes macOS wheels for Apple Silicon only; Intel macOS is not a supported binary installation target.

Linux or Windows, CPU only:

python -m pip install "torch>=2.13,<2.15" --index-url https://download.pytorch.org/whl/cpu
python -m pip install flagquantum

FlagQuantum's compiled extension uses PyTorch's Stable ABI and is tested with PyTorch 2.10.x through 2.14.x in compatibility CI. New CPU/CUDA environments should use the recommended 2.13.x or 2.14.x runtime above. The first CPU install downloads about 200 MB of PyTorch. On a clean GitHub Ubuntu runner it took about 16 seconds; slower networks will take longer.

NVIDIA GPU: Select a PyTorch 2.13.x or 2.14.x CUDA command from the PyTorch installer, then run:

python -m pip install flagquantum

Installing from source? Follow the short setup in CONTRIBUTING.md.

Native accelerator support: FlagQuantum runs directly on the following vendor-provided PyTorch runtimes.

Keep the vendor runtime installed, then run python -m pip install flagquantum. The core requirement accepts torch>=2.10,<2.15, including local version labels such as 2.10.0+metax3.8.1.0; do not replace a managed runtime with an upstream CPU/CUDA wheel. Avoid --upgrade/--upgrade-strategy eager when retaining a managed runtime. The invertible extra still requires PyTorch 2.13.x and is not a vendor-runtime installation shortcut.

To build a CPU or GPU environment with QSteed and optional JAX, follow the container guide.

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 QuantumAI Cloud GPU workspace or Quafu quantum hardware. Configure the Jiuding QuantumAI Cloud workspace and credentials or the Quafu token before running the corresponding call.

# Managed GPU simulation on Jiuding QuantumAI Cloud
jiuding_result = fq.run(
    trained_circuit, target="jiuding:gpu", outputs=measurement,
)

# Quantum hardware: service compilation and estimation from measured shots
quafu_result = fq.run(
    trained_circuit, target="quafu:Baihua",
    outputs=measurement, shots=1024,
)

The Jiuding QuantumAI Cloud call above needs JIUDING_WORKSPACE set to the running workspace name when it is invoked from outside that workspace; inside the workspace the name is discovered automatically. See repeated low-latency workspace execution.

Direct Quafu submission is available in the 0.3 release line. Install flagquantum==0.3.0 for this path. With the older 0.2.0 release, use the documented local QSteed compilation path instead: pass compiler="qsteed" after installing the separate FlagQuantum Compiler QSteed plugin, as described in optional local compiler plugin. The quafu extra does not install that plugin.

Jiuding QuantumAI Cloud 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