1st draft of FlagQuantum

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.

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

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

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

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

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

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 |