Metadata-Version: 2.4
Name: flagquantum
Version: 0.3.1
Summary: A PyTorch-first framework for differentiable quantum computing and quantum AI.
Author-email: FlagQuantum Team <flagquantum@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/flagos-ai/FlagQuantum
Project-URL: Repository, https://github.com/flagos-ai/FlagQuantum
Project-URL: Issues, https://github.com/flagos-ai/FlagQuantum/issues
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch<2.15,>=2.10
Requires-Dist: tomli<3,>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest<10,>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov<8,>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist<4,>=3.0.0; extra == "dev"
Requires-Dist: ruff<0.17,>=0.15.0; extra == "dev"
Requires-Dist: black<27,>=24.1.0; extra == "dev"
Requires-Dist: mypy<3,>=2.0.0; extra == "dev"
Requires-Dist: build<2,>=1.2.0; extra == "dev"
Requires-Dist: pre-commit<5,>=3.7.0; extra == "dev"
Requires-Dist: tomli<3,>=2.0; python_version < "3.11" and extra == "dev"
Requires-Dist: pyyaml<7,>=6.0; extra == "dev"
Provides-Extra: jax
Requires-Dist: jax<0.11,>=0.10; extra == "jax"
Provides-Extra: cotengra
Requires-Dist: cotengra<0.9,>=0.8; extra == "cotengra"
Provides-Extra: stim
Requires-Dist: stim<2,>=1.16; extra == "stim"
Provides-Extra: pymatching
Requires-Dist: pymatching<3,>=2.3; extra == "pymatching"
Provides-Extra: cuda
Requires-Dist: triton<4,>=3.1; extra == "cuda"
Provides-Extra: azure
Requires-Dist: qdk[azure]<2,>=1.32.3; extra == "azure"
Provides-Extra: kaiwu
Requires-Dist: numpy<3,>=1.24; extra == "kaiwu"
Provides-Extra: braket
Requires-Dist: amazon-braket-sdk<2,>=1.117; python_version >= "3.11" and extra == "braket"
Provides-Extra: cirq
Requires-Dist: cirq-core<1.8,>=1.6.1; python_version >= "3.11" and extra == "cirq"
Provides-Extra: cudaq
Requires-Dist: cudaq<0.17,>=0.15.1; python_version >= "3.11" and extra == "cudaq"
Provides-Extra: quafu
Requires-Dist: quarkcircuit<0.6,>=0.5.13; python_version >= "3.12" and extra == "quafu"
Provides-Extra: qiskit
Requires-Dist: qiskit[qasm3-import]<3,>=2; extra == "qiskit"
Requires-Dist: qiskit-aer<1,>=0.17; extra == "qiskit"
Requires-Dist: sympy<2,>=1.13; extra == "qiskit"
Provides-Extra: pennylane
Requires-Dist: pennylane<0.46,>=0.44.1; python_version >= "3.11" and extra == "pennylane"
Provides-Extra: interop-all
Requires-Dist: amazon-braket-sdk<2,>=1.117; python_version >= "3.11" and extra == "interop-all"
Requires-Dist: cirq-core<1.8,>=1.6.1; python_version >= "3.11" and extra == "interop-all"
Requires-Dist: pennylane<0.46,>=0.44.1; python_version >= "3.11" and extra == "interop-all"
Requires-Dist: quarkcircuit<0.6,>=0.5.13; python_version >= "3.12" and extra == "interop-all"
Requires-Dist: qiskit[qasm3-import]<3,>=2; extra == "interop-all"
Requires-Dist: qiskit-aer<1,>=0.17; extra == "interop-all"
Requires-Dist: sympy<2,>=1.13; extra == "interop-all"
Provides-Extra: examples
Requires-Dist: datasets>=2.20.0; extra == "examples"
Requires-Dist: transformers>=4.40.0; extra == "examples"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5.0; extra == "viz"
Provides-Extra: invertible
Requires-Dist: torch<2.14,>=2.13; extra == "invertible"
Provides-Extra: all
Requires-Dist: pytest<10,>=7.0.0; extra == "all"
Requires-Dist: pytest-cov<8,>=4.0.0; extra == "all"
Requires-Dist: pytest-xdist<4,>=3.0.0; extra == "all"
Requires-Dist: ruff<0.17,>=0.15.0; extra == "all"
Requires-Dist: black<27,>=24.1.0; extra == "all"
Requires-Dist: mypy<3,>=2.0.0; extra == "all"
Requires-Dist: build<2,>=1.2.0; extra == "all"
Requires-Dist: pre-commit<5,>=3.7.0; extra == "all"
Requires-Dist: tomli<3,>=2.0; python_version < "3.11" and extra == "all"
Requires-Dist: pyyaml<7,>=6.0; extra == "all"
Requires-Dist: matplotlib>=3.5.0; extra == "all"
Requires-Dist: jax<0.11,>=0.10; extra == "all"
Requires-Dist: datasets>=2.20.0; extra == "all"
Requires-Dist: transformers>=4.40.0; extra == "all"
Requires-Dist: triton<4,>=3.1; extra == "all"
Dynamic: license-file

<div align="center">
  <img src="assets/logo_flagquantum.png" alt="FlagQuantum" width="520">

<p><strong>Quantum computing, built for learning.</strong></p>
<p>A PyTorch-first framework for differentiable quantum computing and quantum AI.</p>

[Qubit ordering](#qubit-ordering-qubit-0-is-the-most-significant-bit) · [Quick start](#install-and-train-your-first-quantum-model) · [Documentation](docs/README.md) · [Examples](examples/README.md)

</div>

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](docs/reference/PUBLICATION_VALIDATION.md) for what has
been tested and what remains a research goal.

## Qubit ordering: qubit 0 is the most-significant bit

> [!IMPORTANT]
> **FlagQuantum uses big-endian qubit order.** For an `n`-qubit register,
> basis states are written as `|q0 q1 ... q(n-1)>`; qubit `0` is the
> most-significant bit (MSB), and qubit `n-1` is the least-significant bit (LSB).

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.

| Framework or service | Exposed qubit/result order | Compared with FlagQuantum |
| --- | --- | --- |
| **[FlagQuantum](https://flagquantum.com)** | Qubit `0` is the MSB | Native convention |
| [Cirq](https://quantumai.google/reference/python/cirq/StateVectorMixin) | The first qubit in `qubit_order` is the MSB | Same when ordered `[q0, q1, ...]` |
| [PennyLane](https://docs.pennylane.ai/en/stable/code/api/pennylane.BasisState.html) | Basis-state digits follow the supplied qubit sequence | Same when ordered `[0, 1, ...]` |
| [Qiskit](https://quantum.cloud.ibm.com/docs/en/guides/bit-ordering) | Qubit `0` is the LSB | Opposite significance |
| [NVIDIA cuStateVec](https://docs.nvidia.com/cuda/cuquantum/24.08.1/custatevec/overview.html#bit-ordering) | Index bit `0` is the LSB | Opposite significance |
| [Jiuding QuantumAI Cloud](https://cloud.flagquantum.com) | Runs FlagQuantum remotely and returns FlagQuantum-ordered results | Same |
| [Quafu](https://quafu.com.cn) | Provider count strings are converted to logical qubit order, with qubit `0` on the left | Normalized to the same order |
| [Amazon Braket](https://aws.amazon.com/braket/) | Ascending qubit order, with qubit `0` as the MSB | Same |
| [Azure Quantum](https://learn.microsoft.com/azure/quantum/overview-azure-quantum) | Depends on the selected Azure target and hardware provider | No platform-wide convention |

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):**

```console
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:**

```console
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](https://pytorch.org/get-started/locally/), then run:

```console
python -m pip install flagquantum
```

Installing from source? Follow the short setup in [CONTRIBUTING.md](CONTRIBUTING.md).

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

|  |  |
| --- | --- |
| **NVIDIA CUDA** | Upstream PyTorch |
| **Hygon DCU** | Vendor PyTorch runtime |
| **Moore Threads MUSA** | Vendor PyTorch runtime |
| **MetaX** | Vendor PyTorch runtime |
| **Biren** | Vendor PyTorch runtime |

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](docker/dev/README.md).

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.

```python
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](examples/quick_start.py).

## Same circuit. Different execution targets.

The experimental adapters can evaluate the same observable on a
[Jiuding QuantumAI Cloud](https://cloud.flagquantum.com) GPU workspace or Quafu
quantum hardware. Configure the
[Jiuding QuantumAI Cloud workspace and credentials](docs/guides/JIUDING.md) or
the [Quafu token](docs/guides/QUAFU_BACKEND.md) before running the corresponding
call.

```python
# 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](docs/guides/JIUDING.md#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](https://github.com/FlagQuantum/FlagQuantum-Compiler-QSteed)
plugin, as described in
[optional local compiler plugin](docs/guides/QUAFU_BACKEND.md#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](flagquantum/twin/README.md)
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](flagquantum/qec/README.md) connecting syndrome extraction,
decoding, and correction. Logical operations and hardware feedback are longer-term
research goals.

[Quantum AI tutorials](examples/single_machine_quantum_ai/README.md) ·
[Distributed statevector](examples/distributed_statevector_topologies/README.md) ·
[Distributed MPS](examples/distributed_mps/README.md) ·
[ARCHITECTURE.md](ARCHITECTURE.md)

<!-- BEGIN GENERATED CAPABILITY_SUMMARY -->
Support varies by execution path. See the [capability catalog](docs/generated/CAPABILITIES.md) for maturity and limitations.
<!-- END GENERATED CAPABILITY_SUMMARY -->

<!-- BEGIN GENERATED PERFORMANCE_CLAIMS -->
[Benchmarks and validated results](docs/generated/CAPABILITIES.md#validated-public-performance-claims)
<!-- END GENERATED PERFORMANCE_CLAIMS -->

---

[Contributing](CONTRIBUTING.md) · [Apache License 2.0](LICENSE)
