diff --git a/docs/flagquantum_en/FlagQuantum_overview/FlagQuantum-overview.md b/docs/flagquantum_en/FlagQuantum_overview/FlagQuantum-overview.md new file mode 100644 index 00000000..98f31a1c --- /dev/null +++ b/docs/flagquantum_en/FlagQuantum_overview/FlagQuantum-overview.md @@ -0,0 +1,7 @@ +# FlagQuantum Overview + +FlagQuantum is a high-performance distributed quantum statevector simulator built on PyTorch, enabling quantum circuit simulation across multiple GPUs with automatic sharding and resharding while also seamlessly supporting real quantum hardware execution. It is part of the FlagOS ecosystem — a unified, open-source AI system software stack that fosters an open technology ecosystem by seamlessly integrating various models, systems, and chips. + +## Why FlagQuantum? + +As quantum circuits grow in qubit count and depth, classical simulation becomes prohibitively expensive. FlagQuantum addresses this challenge through distributed GPU acceleration while maintaining a flexible, extensible architecture. It bridges the gap between simulation and real hardware, allowing seamless transitions from development to deployment. diff --git a/docs/flagquantum_en/FlagQuantum_overview/architecture.md b/docs/flagquantum_en/FlagQuantum_overview/architecture.md new file mode 100644 index 00000000..820f5901 --- /dev/null +++ b/docs/flagquantum_en/FlagQuantum_overview/architecture.md @@ -0,0 +1,69 @@ +# Architecture + +FlagQuantum is organized into the following modules: + +``` +flagquantum/ +├── devices/ # Quantum device implementations +├── drawer/ # Quantum circuit visualization +├── ops/ # Quantum operations (gates, matrices, operators) +├── encoding/ # Data encoding methods +├── measure/ # Measurement utilities +└── utils/ # Helper functions (DTensor, interchange) +``` + +## Core Components + +### Devices + +The `devices` module provides quantum device implementations, including the `DistributedQuantumDevice` class that manages quantum states across multiple GPUs using PyTorch's distributed tensor (`DTensor`). + +### Drawer + +The drawer module enables circuit visualization with two modes: + +- Text Mode: Unicode-based diagrams supporting multi-qubit gate symbols (╭╰├│), auto line-wrapping (max_length), and configurable parameter precision. +- MPL Mode: Publication-quality Matplotlib figures with layer-based layout (same-column gates share x-coordinate), initial states (|0⟩), measurement symbols, and a professional color scheme: + - Fixed gates (H, X, Y, Z): soft blue #7B9EC2 + - Rotation gates (RX, RY, RZ): red #E15759 + - Phase gates (P): plum purple #DDA0DD + - CPhase / SWAP: teal #76B7B2 + - CRX/CRY/CRZ: orange #F28E2B + - RXX/RYY/RZZ: light pink #FFB6C1 (box layout, no control points) + - Supports Toffoli (CCX), Fredkin (CSWAP), multi-qubit gates + +### Operations + +The `ops` module contains all quantum gate implementations: + +- **Pauli gates**: X, Y, Z +- **Clifford gates**: H, S, SDG, CX, CZ, SWAP +- **Rotation gates**: RX, RY, RZ with parameterized support +- **Controlled gates**: Controlled versions of any single-qubit gate +- **Custom gates**: User-registered gates via the gate registry + +### Encoding + +The `encoding` module provides methods for embedding classical data into quantum states: + +- **Angle encoding**: Maps classical features to rotation angles +- **Amplitude encoding**: Encodes data directly into statevector amplitudes +- **Basis encoding**: Maps binary data to computational basis states +- **General encoder**: Custom encoding circuits defined by the user + +### Measurement + +The `measure` module provides measurement utilities including: + +- **Z-basis measurement**: Standard computational basis measurement +- **Expectation values**: Compute expectation values of observables +- **Post-selection**: Filter measurement outcomes based on conditions + +### Utilities + +The `utils` module contains helper functions for: + +- DTensor operations and sharding +- State interchange between devices +- Device management and configuration +- OpenQASM 2.0/3.0 exporter diff --git a/docs/flagquantum_en/FlagQuantum_overview/features.md b/docs/flagquantum_en/FlagQuantum_overview/features.md new file mode 100644 index 00000000..f424259d --- /dev/null +++ b/docs/flagquantum_en/FlagQuantum_overview/features.md @@ -0,0 +1,35 @@ +# Features + +FlagQuantum provides a comprehensive set of features for quantum circuit simulation: + +## Distributed Simulation + +- Multi-GPU Statevector Simulation: Leverage PyTorch's DTensor to distribute quantum states across multiple GPUs, scaling to larger qubit counts than single-GPU simulators. +- Automatic Resharding: Intelligently redistribute statevectors during gate operations to minimize communication overhead and maximize performance. + +## Gate Set & Extensibility + +- Comprehensive Gate Set: Includes Pauli (X, Y, Z), Clifford (H, S, SDG, CX, CZ, SWAP), rotation gates (RX, RY, RZ), and parameterized controlled gates. +- Custom Gate Registration: Extend the library with user-defined gates through the gate registry without modifying core code. + +## Advanced Capabilities + +- Invertible Backpropagation: Memory-efficient gradient computation for trainable quantum circuits, enabling quantum machine learning workflows. +- Post-Selection & Noise Models: Built-in support for measurement post-selection and depolarizing noise models for realistic simulation. +Data Encoding + +## Data Encoding + +- Flexible Encoding Schemes: Multiple methods for embedding classical data into quantum states — angle encoding, amplitude encoding, and basis encoding — plus a general user-defined encoder. +Visualization & Interoperability + +## Visualization & Interoperability + +- Circuit Visualization: Two-mode visualizer — Unicode text mode for terminal use and Matplotlib publication-quality mode with professional color schemes, layer-based layout, initial state display (|0⟩), and measurement symbols. +- OpenQASM 2.0/3.0 Export: Export circuits to run on real quantum hardware platforms including IBM Quantum, AWS Braket, Azure Quantum, IonQ, and Rigetti. +Ecosystem Integration +FlagQuantum is a core component of FlagOS, an open-source AI system software stack designed to foster an open technology ecosystem through seamless integration of diverse models, systems, and chips. Within FlagOS, FlagQuantum works alongside other components to enable end-to-end quantum-classical workflows. + +## Ecosystem Integration + +FlagQuantum is a core component of FlagOS, an open-source AI system software stack designed to foster an open technology ecosystem through seamless integration of diverse models, systems, and chips. Within FlagOS, FlagQuantum works alongside other components to enable end-to-end quantum-classical workflows. \ No newline at end of file diff --git a/docs/flagquantum_en/getting_started/getting-started.md b/docs/flagquantum_en/getting_started/getting-started.md new file mode 100644 index 00000000..00733aaf --- /dev/null +++ b/docs/flagquantum_en/getting_started/getting-started.md @@ -0,0 +1,5 @@ +# Getting Started + +This section covers the requirements for installing FlagQuantum and guides you through the installation process. + + diff --git a/docs/flagquantum_en/getting_started/install.md b/docs/flagquantum_en/getting_started/install.md new file mode 100644 index 00000000..14d3383c --- /dev/null +++ b/docs/flagquantum_en/getting_started/install.md @@ -0,0 +1,28 @@ +# Install FlagQuantum + +Read [Requirements](requirements.md) before proceeding. + +## Steps + +1. Install FlagQuantum + + - Install from source + + ```{code-block} shell + git clone https://github.com/flagos-ai/FlagQuantum.git + cd FlagQuantum + pip install -e . + ``` + + - Install with pip (when available) + + ```{code-block} shell + pip install flagquantum + ``` + +2. Verify FlagQuantum installation + + ```{code-block} python + import flagquantum as fq + print(fq.__version__) + ``` diff --git a/docs/flagquantum_en/getting_started/requirements.md b/docs/flagquantum_en/getting_started/requirements.md new file mode 100644 index 00000000..780386a5 --- /dev/null +++ b/docs/flagquantum_en/getting_started/requirements.md @@ -0,0 +1,16 @@ +# Requirements + +This section includes information about the hardware platforms and software requirements for FlagQuantum. + +## Software Requirements + +- Python 3.10 or higher +- PyTorch 2.5 or higher + +## Supported hardware platforms + +The following list includes the supported hardware platforms: + +- Hygon +- Moore Threads +- NVIDIA diff --git a/docs/flagquantum_en/index.md b/docs/flagquantum_en/index.md new file mode 100644 index 00000000..95788273 --- /dev/null +++ b/docs/flagquantum_en/index.md @@ -0,0 +1,96 @@ +# FlagQuantum Documentation + +```{button-ref} getting_started/getting-started +:ref-type: myst +:color: primary +:class: sd-btn-lg sd-px-4 sd-py-2 sd-fw-bold + +Getting Started +``` + +::::{grid} 1 2 2 3 +:gutter: 1 1 1 2 + +:::{grid-item-card} {octicon}`browser;1.5em;sd-mr-1` Overview +:link: FlagQuantum_overview/FlagQuantum-overview +:link-type: doc + +Have a quick view of FlagQuantum, and also some basic concepts. + ++++\n[Learn more »](FlagQuantum_overview/FlagQuantum-overview.md) +::: + +:::{grid-item-card} {octicon}`book;1.5em;sd-mr-1` Getting Started +:link: getting_started/getting-started +:link-type: doc + +Outlines the installation requirements for FlagQuantum and provides step-by-step instructions for setting it up. + ++++\n[Learn more »](getting_started/getting-started.md) +::: + +:::{grid-item-card} {octicon}`broadcast;1.5em;sd-mr-1` User Guide +:link: user_guide/user-guide +:link-type: doc + +Guides you through basic usage, distributed simulation, parameterized gates, and custom gate registration. + ++++\n[Learn more »](user_guide/user-guide.md) +::: + +:::: + +--- + + +```{toctree} +:caption: 📑 Release Notes +:maxdepth: 2 +:hidden: + +release_notes/release-notes.md +``` + +```{toctree} +:caption: 📚 Overview +:maxdepth: 2 +:hidden: + +FlagQuantum_overview/FlagQuantum-overview.md +FlagQuantum_overview/features.md +FlagQuantum_overview/architecture.md +``` + +```{toctree} +:caption: 📚 Getting Started +:maxdepth: 2 +:hidden: + +getting_started/getting-started.md +getting_started/requirements.md +getting_started/install.md +``` + +```{toctree} +:caption: 📚 User Guide +:maxdepth: 2 +:hidden: + +user_guide/user-guide.md +user_guide/basic-usage.md +user_guide/parameterized-gates.md +user_guide/quantum-encoding.md +user_guide/custom-gates.md +user_guide/distributed-execution.md +user_guide/invertible-mode.md +user_guide/tutorials.md +user_guide/run-tests.md +``` + +```{toctree} +:caption: 📖 Reference +:maxdepth: 2 +:hidden: + +reference.md +``` diff --git a/docs/flagquantum_en/reference.md b/docs/flagquantum_en/reference.md new file mode 100644 index 00000000..e1e98198 --- /dev/null +++ b/docs/flagquantum_en/reference.md @@ -0,0 +1,11 @@ +# References + +This project draws inspiration and reference from the following projects and organizations: + +- [NVIDIA CUDA-Q](https://github.com/NVIDIA/cuda-quantum) - For insights on GPU-accelerated quantum circuit simulation and distributed quantum computing +- [MIT TorchQuantum](https://github.com/mit-han-lab/torchquantum) - For inspiration on PyTorch-native quantum circuit representations +- [IonQ's TQD](https://github.com/ionq/torchquantum-dist) - For ideas on efficient state representations +- [Xanadu's PennyLane](https://github.com/PennyLaneAI/pennylane) - For the elegant functional API design and seamless integration with classical ML frameworks +- [IBM's Qiskit](https://github.com/Qiskit/qiskit) - For foundational concepts in quantum circuit construction and statevector simulation + +This project is built with PyTorch's DTensor for distributed tensor operations, enabling scalable quantum state simulation across multiple devices. \ No newline at end of file diff --git a/docs/flagquantum_en/release_notes/release-notes.md b/docs/flagquantum_en/release_notes/release-notes.md new file mode 100644 index 00000000..18a4e568 --- /dev/null +++ b/docs/flagquantum_en/release_notes/release-notes.md @@ -0,0 +1,29 @@ +# Release Notes + +## v0.1.0 + +```{note} +This is a preview release. The version number shown is a pre-release identifier and may change upon final release. Content in this preview is for reference only and does not constitute a commitment or warranty for the final product. +``` + +- **Added features** + + - Initial release of FlagQuantum, a high-performance distributed quantum statevector simulator built on PyTorch. + + - Distributed statevector simulation using `DTensor` from `torch.distributed` for multi-GPU execution. + + - Automatic resharding to minimize communication overhead during gate operations. + + - Comprehensive gate set including Pauli, Clifford, rotation, and controlled gates with parameterized support. + + - Invertible backpropagation for memory-efficient gradient computation. + + - Custom gate registration system for extending the library. + + - Post-selection and noise models including depolarizing noise. + + - Flexible data encoding with angle, amplitude, and basis encoding schemes. + + - Professional quantum circuit visualization capabilities. + + - OpenQASM 2.0/3.0 exporter for real quantum hardware and cross-framework execution. diff --git a/docs/flagquantum_en/user_guide/basic-usage.md b/docs/flagquantum_en/user_guide/basic-usage.md new file mode 100644 index 00000000..11f173d7 --- /dev/null +++ b/docs/flagquantum_en/user_guide/basic-usage.md @@ -0,0 +1,21 @@ +# Basic usage + +Create a distributed quantum device and apply gates using the functional API: + +```{code-block} python + +import flagquantum as fq +import torch + +# Create a distributed quantum device (default: device='cuda' if GPU available) +qdev= fq.DistributedQuantumDevice(n_wires=4, bsz=2, world_sz=1, device='cpu') + +# Apply gates (functional style) +fq.h(device, wires=[0]) +fq.rx(device, wires=[1], params=0.5) +fq.cx(device, wires=[0, 1]) + +# Measure all qubits +expectations = fq.measure_allZ(device) +print(expectations.shape) # (2, 4) +``` diff --git a/docs/flagquantum_en/user_guide/custom-gates.md b/docs/flagquantum_en/user_guide/custom-gates.md new file mode 100644 index 00000000..4d14f950 --- /dev/null +++ b/docs/flagquantum_en/user_guide/custom-gates.md @@ -0,0 +1,17 @@ +# Register custom gates + +Extend FlagQuantum with your own gate definitions: + +```{code-block} python +from flagquantum.ops import register_gate +import torch + +# Define custom gate matrix +my_gate = torch.tensor([[0, 1], [1, 0]], dtype=torch.complex64) +register_gate("my_gate", my_gate) + +# Now available as: +# - fq.ops.registry.my_gate (functional) +# - fq.ops.registry.my_gate_inv (inverse) +# - fq.ops.registry.MY_GATE (operator class) +``` diff --git a/docs/flagquantum_en/user_guide/distributed-execution.md b/docs/flagquantum_en/user_guide/distributed-execution.md new file mode 100644 index 00000000..5a11db95 --- /dev/null +++ b/docs/flagquantum_en/user_guide/distributed-execution.md @@ -0,0 +1,13 @@ +# Distributed multi-GPU execution + +Run quantum simulations across multiple GPUs: + +```{code-block} shell +# Run with 4 GPUs +torchrun --nproc_per_node=4 your_script.py +``` + +```{code-block} python +# In your script, world_sz is set automatically via torchrun +device = fq.DistributedQuantumDevice(n_wires=20, bsz=32, world_sz=4) +``` diff --git a/docs/flagquantum_en/user_guide/export-to-real-quantum-hardware.md b/docs/flagquantum_en/user_guide/export-to-real-quantum-hardware.md new file mode 100644 index 00000000..8c3876ae --- /dev/null +++ b/docs/flagquantum_en/user_guide/export-to-real-quantum-hardware.md @@ -0,0 +1,37 @@ +# Export to real quantum hardware + +FlagQuantum circuits can be exported to OpenQASM 3.0 and run on all major quantum computing platforms: + +```{code-block} python +# Build your circuit +qdev = fq.DistributedQuantumDevice(n_wires=3, record_op=True) +fq.H(wires=[0])(qdev) +fq.RX(wires=[1], init_params=torch.tensor([0.5]))(qdev) +fq.CNOT(wires=[0, 1])(qdev) +fq.measure_allZ(qdev) + +# Export to OpenQASM 3.0 +fq.export_to_qasm(qdev, "circuit.qasm", version=3.0) + +# Now run on ANY platform: +# - Quafu Quantum +# - Origin Quantum +# - IBM Quantum (via Qiskit) +# - AWS Braket (IonQ, Rigetti) +# - Azure Quantum +# - IonQ direct +# - Rigetti direct +``` + +Supported Platforms + +| Platform | Support | Description | +| :--- | :---: | :--- | +| Quafu Quantum | Native | Run on Chinese Quafu quantum cloud | +| Origin Quantum | Native | Run on Chinese Origin quantum cloud | +| IBM Quantum | Native | Run on real IBM quantum processors | +| AWS Braket | Full | Submit to IonQ, Rigetti, and more | +| Azure Quantum | Full | OpenQASM as core intermediate representation | +| IonQ | Native | Direct hardware submission | +| Rigetti | Native | Superconducting qubit systems | +| Q-CTRL Fire Opal | Full | Hardware optimization services | \ No newline at end of file diff --git a/docs/flagquantum_en/user_guide/invertible-mode.md b/docs/flagquantum_en/user_guide/invertible-mode.md new file mode 100644 index 00000000..56fb6080 --- /dev/null +++ b/docs/flagquantum_en/user_guide/invertible-mode.md @@ -0,0 +1,8 @@ +# Invertible mode + +For large circuits requiring gradient computation, use invertible mode to reduce memory usage: + +```{code-block} python +device = fq.DistributedQuantumDevice(n_wires=10, bsz=64, invertible=True) +# Uses less memory during backpropagation +``` diff --git a/docs/flagquantum_en/user_guide/parameterized-gates.md b/docs/flagquantum_en/user_guide/parameterized-gates.md new file mode 100644 index 00000000..6e75018e --- /dev/null +++ b/docs/flagquantum_en/user_guide/parameterized-gates.md @@ -0,0 +1,19 @@ +# Parameterized gates + +FlagQuantum supports trainable quantum circuits with gradient computation: + +```{code-block} python +# Create a gate with trainable parameter +rx_gate = fq.RX(wires=[0], trainable=True) +rx_gate(device) # Apply to device + +# Optimize the parameter +optimizer = torch.optim.Adam([rx_gate.params]) +for _ in range(100): + optimizer.zero_grad() + device.reset_states() + rx_gate(device) + loss = fq.measure_allZ(device).sum() + loss.backward() + optimizer.step() +``` diff --git a/docs/flagquantum_en/user_guide/quantum-encoding.md b/docs/flagquantum_en/user_guide/quantum-encoding.md new file mode 100644 index 00000000..d2839350 --- /dev/null +++ b/docs/flagquantum_en/user_guide/quantum-encoding.md @@ -0,0 +1,21 @@ +# Quantum encoding + +FlagQuantum provides multiple encoding schemes for embedding classical data into quantum states: + +```{code-block} python +# Angle encoding +x = torch.randn(2, 4) # batch=2, features=4 +fq.angle_encoder(qdev, x, wires=[0, 1, 2, 3]) + +# Amplitude encoding +amplitudes = torch.randn(2, 16) # 2^4 = 16 amplitudes +fq.amplitude_encoder(qdev, amplitudes) + +# Custom encoding circuit +encoder = fq.GeneralEncoder([ + {"func": "ry", "wires": [0], "input_idx": 0}, + {"func": "ry", "wires": [1], "input_idx": 1}, + {"func": "cx", "wires": [0, 1]}, +]) +encoder(device, x) +``` diff --git a/docs/flagquantum_en/user_guide/run-tests.md b/docs/flagquantum_en/user_guide/run-tests.md new file mode 100644 index 00000000..d4ca1380 --- /dev/null +++ b/docs/flagquantum_en/user_guide/run-tests.md @@ -0,0 +1,11 @@ +# Run tests + +You can use the following code block to run tests. + +```{code-block} shell +# Install test dependencies +pip install pytest pytest-cov + +# Run all tests +python run_tests.py +``` diff --git a/docs/flagquantum_en/user_guide/tutorials.md b/docs/flagquantum_en/user_guide/tutorials.md new file mode 100644 index 00000000..4af8a876 --- /dev/null +++ b/docs/flagquantum_en/user_guide/tutorials.md @@ -0,0 +1,12 @@ +# Tutorials + +You can explore our tutorial series in terms of Jupyter Note (`.jpynb`) in `examples/tutorials` to learn how to use FlagQuantum effectively: + +| # | Tutorial | Description | +|---|----------|-------------| +| 00 | Understanding States | Quantum state representations and initialization | +| 01 | Basic Operations | Single-qubit and two-qubit gates | +| 02 | Measurement | Quantum measurement and expectation values | +| 03 | Parameterized Gates | Trainable gates with automatic differentiation | +| 04 | Quantum Circuit Builder | Building and visualizing circuits | +| 05 | Quantum Machine Learning | End-to-end QML training pipeline | diff --git a/docs/flagquantum_en/user_guide/user-guide.md b/docs/flagquantum_en/user_guide/user-guide.md new file mode 100644 index 00000000..dc73ca14 --- /dev/null +++ b/docs/flagquantum_en/user_guide/user-guide.md @@ -0,0 +1,89 @@ +# User Guide + +This guide covers how to use FlagQuantum for quantum circuit simulation, including basic usage, parameterized gates with trainable parameters, quantum encoding, register custom gates, distributed multi-GPU execution, and memory invertible mode. + +::::{grid} 1 2 2 3 +:gutter: 1 1 1 2 + +:::{grid-item-card} {octicon}`play;1.5em;sd-mr-1` Basic Usage +:link: basic-usage +:link-type: doc + +Create a distributed quantum device and apply gates using the functional API. + ++++\n[Learn more »](basic-usage.md) +::: + +:::{grid-item-card} {octicon}`gear;1.5em;sd-mr-1` Parameterized Gates +:link: parameterized-gates +:link-type: doc + +Trainable quantum circuits with gradient computation. + ++++\n[Learn more »](parameterized-gates.md) +::: + +:::{grid-item-card} {octicon}`cpu;1.5em;sd-mr-1` Quantum Encoding +:link: quantum-encoding +:link-type: doc + +Encoding schemes for embedding classical data into quantum states. + ++++\n[Learn more »](quantum-encoding.md) +::: + +:::{grid-item-card} {octicon}`cpu;1.5em;sd-mr-1` Export to Real Quantum Hardware +:link: export-to-real-quantum-hardware +:link-type: doc + +Encoding schemes for embedding classical data into quantum states. + ++++\n[Learn more »](export-to-real-quantum-hardware.md) +::: + +:::{grid-item-card} {octicon}`pencil;1.5em;sd-mr-1` Custom Gates +:link: custom-gates +:link-type: doc + +Extend FlagQuantum with your own gate definitions. + ++++\n[Learn more »](custom-gates.md) +::: + +:::{grid-item-card} {octicon}`device-desktop;1.5em;sd-mr-1` Distributed Execution +:link: distributed-execution +:link-type: doc + +Run quantum simulations across multiple GPUs. + ++++\n[Learn more »](distributed-execution.md) +::: + +:::{grid-item-card} {octicon}`memory;1.5em;sd-mr-1` Invertible Mode +:link: invertible-mode +:link-type: doc + +Memory-efficient mode for large circuits with gradient computation. + ++++\n[Learn more »](invertible-mode.md) +::: + +:::{grid-item-card} {octicon}`book;1.5em;sd-mr-1` Tutorials +:link: tutorials +:link-type: doc + +Explore our tutorial series to learn FlagQuantum effectively. + ++++\n[Learn more »](tutorials.md) +::: + +:::{grid-item-card} {octicon}`flame;1.5em;sd-mr-1` Run Tests +:link: run-tests +:link-type: doc + +Install dependencies and run all tests. + ++++\n[Learn more »](run-tests.md) +::: + +::::