From a10acecafacd43c6aaabe5d7a532e6f144a7b369 Mon Sep 17 00:00:00 2001
From: cheng874 <licheng_0205@qq.com>
Date: Thu, 14 May 2026 17:35:03 +0800
Subject: [PATCH 1/4] 1st draft of FlagQuantum

---
 .../FlagQuantum-overview.md                   |  3 +
 .../FlagQuantum_overview/architecture.md      | 53 ++++++++++
 .../FlagQuantum_overview/features.md          | 17 ++++
 .../getting_started/getting-started.md        |  5 +
 .../flagquantum_en/getting_started/install.md | 28 ++++++
 .../getting_started/requirements.md           |  8 ++
 docs/flagquantum_en/index.md                  | 96 +++++++++++++++++++
 docs/flagquantum_en/reference.md              | 11 +++
 .../release_notes/release-notes.md            | 19 ++++
 docs/flagquantum_en/user_guide/basic-usage.md | 21 ++++
 .../flagquantum_en/user_guide/custom-gates.md | 17 ++++
 .../user_guide/distributed-execution.md       | 13 +++
 .../user_guide/invertible-mode.md             |  8 ++
 .../user_guide/parameterized-gates.md         | 19 ++++
 .../user_guide/quantum-encoding.md            | 21 ++++
 docs/flagquantum_en/user_guide/run-tests.md   | 11 +++
 docs/flagquantum_en/user_guide/tutorials.md   | 12 +++
 docs/flagquantum_en/user_guide/user-guide.md  | 80 ++++++++++++++++
 18 files changed, 442 insertions(+)
 create mode 100644 docs/flagquantum_en/FlagQuantum_overview/FlagQuantum-overview.md
 create mode 100644 docs/flagquantum_en/FlagQuantum_overview/architecture.md
 create mode 100644 docs/flagquantum_en/FlagQuantum_overview/features.md
 create mode 100644 docs/flagquantum_en/getting_started/getting-started.md
 create mode 100644 docs/flagquantum_en/getting_started/install.md
 create mode 100644 docs/flagquantum_en/getting_started/requirements.md
 create mode 100644 docs/flagquantum_en/index.md
 create mode 100644 docs/flagquantum_en/reference.md
 create mode 100644 docs/flagquantum_en/release_notes/release-notes.md
 create mode 100644 docs/flagquantum_en/user_guide/basic-usage.md
 create mode 100644 docs/flagquantum_en/user_guide/custom-gates.md
 create mode 100644 docs/flagquantum_en/user_guide/distributed-execution.md
 create mode 100644 docs/flagquantum_en/user_guide/invertible-mode.md
 create mode 100644 docs/flagquantum_en/user_guide/parameterized-gates.md
 create mode 100644 docs/flagquantum_en/user_guide/quantum-encoding.md
 create mode 100644 docs/flagquantum_en/user_guide/run-tests.md
 create mode 100644 docs/flagquantum_en/user_guide/tutorials.md
 create mode 100644 docs/flagquantum_en/user_guide/user-guide.md

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..e43dd43d
--- /dev/null
+++ b/docs/flagquantum_en/FlagQuantum_overview/FlagQuantum-overview.md
@@ -0,0 +1,3 @@
+# 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. 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.
diff --git a/docs/flagquantum_en/FlagQuantum_overview/architecture.md b/docs/flagquantum_en/FlagQuantum_overview/architecture.md
new file mode 100644
index 00000000..6e74b75a
--- /dev/null
+++ b/docs/flagquantum_en/FlagQuantum_overview/architecture.md
@@ -0,0 +1,53 @@
+# Architecture
+
+FlagQuantum is organized into the following modules:
+
+```
+flagquantum/
+├── devices/          # Quantum device implementations
+├── 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`).
+
+### 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
diff --git a/docs/flagquantum_en/FlagQuantum_overview/features.md b/docs/flagquantum_en/FlagQuantum_overview/features.md
new file mode 100644
index 00000000..ab6d6a31
--- /dev/null
+++ b/docs/flagquantum_en/FlagQuantum_overview/features.md
@@ -0,0 +1,17 @@
+# Features
+
+FlagQuantum provides a comprehensive set of features for quantum circuit simulation:
+
+- **Distributed Statevector Simulation**: Leverage multiple GPUs to simulate large quantum circuits using `DTensor` from `torch.distributed`
+
+- **Automatic Resharding**: Intelligently redistributes statevectors to minimize communication overhead during gate operations
+
+- **Comprehensive Gate Set**: Includes Pauli, Clifford, rotation, and controlled gates with parameterized support
+
+- **Invertible Backpropagation**: Memory-efficient gradient computation for trainable quantum circuits
+
+- **Custom Gate Registration**: Extend the library with your own gates without modifying the core
+
+- **Post-Selection & Noise Models**: Built-in support for measurement post-selection and depolarizing noise
+
+- **Flexible Encoding**: Multiple encoding schemes (angle, amplitude, basis) for classical data embedding
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..f84b75e3
--- /dev/null
+++ b/docs/flagquantum_en/getting_started/requirements.md
@@ -0,0 +1,8 @@
+# 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
\ No newline at end of file
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..b45211ce
--- /dev/null
+++ b/docs/flagquantum_en/release_notes/release-notes.md
@@ -0,0 +1,19 @@
+# FlagQuantum <To be confirmed> release
+
+- **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.
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..64935f02
--- /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
+device = fq.DistributedQuantumDevice(n_wires=4, bsz=2, world_sz=1)
+
+# 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/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..854ccc85
--- /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(4, 4)  # batch=4, features=4
+fq.angle_encoder(device, x, wires=[0, 1, 2, 3])
+
+# Amplitude encoding
+amplitudes = torch.randn(4, 16)  # 2^4 = 16 amplitudes
+fq.amplitude_encoder(device, 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..299f13aa
--- /dev/null
+++ b/docs/flagquantum_en/user_guide/user-guide.md
@@ -0,0 +1,80 @@
+# 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}`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)
+:::
+
+::::

From f92a22c2fb639733363ae94973d5e35957f670df Mon Sep 17 00:00:00 2001
From: cheng874 <licheng_0205@qq.com>
Date: Thu, 28 May 2026 18:21:23 +0800
Subject: [PATCH 2/4] Comments updated

---
 .../FlagQuantum-overview.md                   |  6 +++-
 .../FlagQuantum_overview/architecture.md      | 16 +++++++++++
 .../FlagQuantum_overview/features.md          | 28 ++++++++++++++-----
 .../release_notes/release-notes.md            |  8 +++++-
 4 files changed, 49 insertions(+), 9 deletions(-)

diff --git a/docs/flagquantum_en/FlagQuantum_overview/FlagQuantum-overview.md b/docs/flagquantum_en/FlagQuantum_overview/FlagQuantum-overview.md
index e43dd43d..98f31a1c 100644
--- a/docs/flagquantum_en/FlagQuantum_overview/FlagQuantum-overview.md
+++ b/docs/flagquantum_en/FlagQuantum_overview/FlagQuantum-overview.md
@@ -1,3 +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. 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.
+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
index 6e74b75a..4082b890 100644
--- a/docs/flagquantum_en/FlagQuantum_overview/architecture.md
+++ b/docs/flagquantum_en/FlagQuantum_overview/architecture.md
@@ -5,6 +5,7 @@ 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
@@ -17,6 +18,21 @@ flagquantum/
 
 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:
diff --git a/docs/flagquantum_en/FlagQuantum_overview/features.md b/docs/flagquantum_en/FlagQuantum_overview/features.md
index ab6d6a31..d2ed4165 100644
--- a/docs/flagquantum_en/FlagQuantum_overview/features.md
+++ b/docs/flagquantum_en/FlagQuantum_overview/features.md
@@ -2,16 +2,30 @@
 
 FlagQuantum provides a comprehensive set of features for quantum circuit simulation:
 
-- **Distributed Statevector Simulation**: Leverage multiple GPUs to simulate large quantum circuits using `DTensor` from `torch.distributed`
+## Distributed Simulation
 
-- **Automatic Resharding**: Intelligently redistributes statevectors to minimize communication overhead during gate operations
+- **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.
 
-- **Comprehensive Gate Set**: Includes Pauli, Clifford, rotation, and controlled gates with parameterized support
+## Gate Set & Extensibility
 
-- **Invertible Backpropagation**: Memory-efficient gradient computation for trainable quantum circuits
+- **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.
 
-- **Custom Gate Registration**: Extend the library with your own gates without modifying the core
+## Advanced Capabilities
 
-- **Post-Selection & Noise Models**: Built-in support for measurement post-selection and depolarizing noise
+- **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.
 
-- **Flexible Encoding**: Multiple encoding schemes (angle, amplitude, basis) for classical data embedding
+## 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
+
+- **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.
diff --git a/docs/flagquantum_en/release_notes/release-notes.md b/docs/flagquantum_en/release_notes/release-notes.md
index b45211ce..0691dbd7 100644
--- a/docs/flagquantum_en/release_notes/release-notes.md
+++ b/docs/flagquantum_en/release_notes/release-notes.md
@@ -1,4 +1,6 @@
-# FlagQuantum <To be confirmed> release
+# Release Notes
+
+## v0.1.0
 
 - **Added features**
 
@@ -17,3 +19,7 @@
   - 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.

From cd0d90c28519a2ab275a37ce925528cf275c4232 Mon Sep 17 00:00:00 2001
From: cheng874 <licheng_0205@qq.com>
Date: Thu, 28 May 2026 18:27:21 +0800
Subject: [PATCH 3/4] Update OpenQASM 2.0

---
 docs/flagquantum_en/FlagQuantum_overview/architecture.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/flagquantum_en/FlagQuantum_overview/architecture.md b/docs/flagquantum_en/FlagQuantum_overview/architecture.md
index 4082b890..d739b8f5 100644
--- a/docs/flagquantum_en/FlagQuantum_overview/architecture.md
+++ b/docs/flagquantum_en/FlagQuantum_overview/architecture.md
@@ -67,3 +67,4 @@ 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

From 73d8add12ff3b2a2e02311f8d16c74a5e06410a1 Mon Sep 17 00:00:00 2001
From: cheng874 <licheng_0205@qq.com>
Date: Mon, 15 Jun 2026 16:51:51 +0800
Subject: [PATCH 4/4] Updated FlagQuantum comments

---
 .../FlagQuantum_overview/architecture.md      |  5 +--
 .../FlagQuantum_overview/features.md          | 24 +++++++-----
 .../getting_started/requirements.md           | 10 ++++-
 .../release_notes/release-notes.md            |  4 ++
 docs/flagquantum_en/user_guide/basic-usage.md |  4 +-
 .../export-to-real-quantum-hardware.md        | 37 +++++++++++++++++++
 .../user_guide/quantum-encoding.md            |  8 ++--
 docs/flagquantum_en/user_guide/user-guide.md  |  9 +++++
 8 files changed, 81 insertions(+), 20 deletions(-)
 create mode 100644 docs/flagquantum_en/user_guide/export-to-real-quantum-hardware.md

diff --git a/docs/flagquantum_en/FlagQuantum_overview/architecture.md b/docs/flagquantum_en/FlagQuantum_overview/architecture.md
index d739b8f5..820f5901 100644
--- a/docs/flagquantum_en/FlagQuantum_overview/architecture.md
+++ b/docs/flagquantum_en/FlagQuantum_overview/architecture.md
@@ -22,9 +22,8 @@ The `devices` module provides quantum device implementations, including the `Dis
 
 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:
+- 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
diff --git a/docs/flagquantum_en/FlagQuantum_overview/features.md b/docs/flagquantum_en/FlagQuantum_overview/features.md
index d2ed4165..f424259d 100644
--- a/docs/flagquantum_en/FlagQuantum_overview/features.md
+++ b/docs/flagquantum_en/FlagQuantum_overview/features.md
@@ -4,28 +4,32 @@ FlagQuantum provides a comprehensive set of features for quantum circuit simulat
 
 ## 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.
+- 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.
+- 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.
+- 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.
+- 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.
+- 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.
+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/requirements.md b/docs/flagquantum_en/getting_started/requirements.md
index f84b75e3..780386a5 100644
--- a/docs/flagquantum_en/getting_started/requirements.md
+++ b/docs/flagquantum_en/getting_started/requirements.md
@@ -5,4 +5,12 @@ This section includes information about the hardware platforms and software requ
 ## Software Requirements
 
 - Python 3.10 or higher
-- PyTorch 2.5 or higher
\ No newline at end of file
+- 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/release_notes/release-notes.md b/docs/flagquantum_en/release_notes/release-notes.md
index 0691dbd7..18a4e568 100644
--- a/docs/flagquantum_en/release_notes/release-notes.md
+++ b/docs/flagquantum_en/release_notes/release-notes.md
@@ -2,6 +2,10 @@
 
 ## 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.
diff --git a/docs/flagquantum_en/user_guide/basic-usage.md b/docs/flagquantum_en/user_guide/basic-usage.md
index 64935f02..11f173d7 100644
--- a/docs/flagquantum_en/user_guide/basic-usage.md
+++ b/docs/flagquantum_en/user_guide/basic-usage.md
@@ -7,8 +7,8 @@ Create a distributed quantum device and apply gates using the functional API:
 import flagquantum as fq
 import torch
 
-# Create a distributed quantum device
-device = fq.DistributedQuantumDevice(n_wires=4, bsz=2, world_sz=1)
+# 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])
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/quantum-encoding.md b/docs/flagquantum_en/user_guide/quantum-encoding.md
index 854ccc85..d2839350 100644
--- a/docs/flagquantum_en/user_guide/quantum-encoding.md
+++ b/docs/flagquantum_en/user_guide/quantum-encoding.md
@@ -4,12 +4,12 @@ FlagQuantum provides multiple encoding schemes for embedding classical data into
 
 ```{code-block} python
 # Angle encoding
-x = torch.randn(4, 4)  # batch=4, features=4
-fq.angle_encoder(device, x, wires=[0, 1, 2, 3])
+x = torch.randn(2, 4)  # batch=2, features=4
+fq.angle_encoder(qdev, x, wires=[0, 1, 2, 3])
 
 # Amplitude encoding
-amplitudes = torch.randn(4, 16)  # 2^4 = 16 amplitudes
-fq.amplitude_encoder(device, amplitudes)
+amplitudes = torch.randn(2, 16)  # 2^4 = 16 amplitudes
+fq.amplitude_encoder(qdev, amplitudes)
 
 # Custom encoding circuit
 encoder = fq.GeneralEncoder([
diff --git a/docs/flagquantum_en/user_guide/user-guide.md b/docs/flagquantum_en/user_guide/user-guide.md
index 299f13aa..dc73ca14 100644
--- a/docs/flagquantum_en/user_guide/user-guide.md
+++ b/docs/flagquantum_en/user_guide/user-guide.md
@@ -32,6 +32,15 @@ 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