Metadata-Version: 2.4
Name: flagquantum
Version: 0.2.0
Summary: A distributed quantum computing framework built on PyTorch
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.14,>=2.5
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Provides-Extra: jax
Requires-Dist: jax<0.11,>=0.10; extra == "jax"
Provides-Extra: cuda
Requires-Dist: triton<4,>=3.1; extra == "cuda"
Provides-Extra: braket
Requires-Dist: amazon-braket-sdk<2,>=1.117; extra == "braket"
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"
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; 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"
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.5; extra == "invertible"
Provides-Extra: all
Requires-Dist: pytest>=7.0.0; extra == "all"
Requires-Dist: pytest-cov>=4.0.0; extra == "all"
Requires-Dist: pytest-xdist>=3.0.0; extra == "all"
Requires-Dist: ruff>=0.1.0; extra == "all"
Requires-Dist: black>=23.0; extra == "all"
Requires-Dist: mypy>=1.0; extra == "all"
Requires-Dist: build>=1.2.0; extra == "all"
Requires-Dist: pre-commit>=3.7.0; extra == "all"
Requires-Dist: tomli>=2.0; python_version < "3.11" and 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="320">

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

[Quick start](#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.

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](docs/reference/PUBLICATION_VALIDATION.md) 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:

```console
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.

```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 GPU
workspace or Quafu quantum hardware. Configure the [Jiuding workspace and credentials](docs/guides/JIUDING.md)
or the [Quafu token and QSteed plugin](docs/guides/QUAFU_BACKEND.md) before
running the corresponding call.

```python
# 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](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)
