1st draft of FlagQuantum

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.

docs/flagquantum_en/FlagQuantum_overview/architecture.md

@@ -0,0 +1,70 @@
+# 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

docs/flagquantum_en/FlagQuantum_overview/features.md

@@ -0,0 +1,31 @@
+# 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
+
+- **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.

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.
+
+

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__)
+   ```

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

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
+```

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. 

docs/flagquantum_en/release_notes/release-notes.md

@@ -0,0 +1,25 @@
+# Release Notes
+
+## v0.1.0
+
+- **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.

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)
+```

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)
+```

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)
+```

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
+```

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()
+```

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)
+```