Overhaul project structure, developer workflow, and documentation

.pre-commit-config.yaml

@@ -7,14 +7,15 @@ repos:
       - id: check-yaml
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.14
+    rev: v0.15.1
     hooks:
       - id: ruff-check
         args: [ --fix ]
       - id: ruff-format
 
   - repo: https://github.com/mwouts/jupytext
-    rev: v1.19.0
+    rev: v1.19.1
     hooks:
       - id: jupytext
         args: [--sync]
+        files: ^(examples/|tutorials/)

CONTRIBUTING.md

@@ -0,0 +1,112 @@
+This is a comprehensive, professional `CONTRIBUTING.md` tailored for your project.
+It covers the specific tools you've configured and adds industry-standard best practices for a seamless open-source contribution experience.
+
+---
+
+# Contributing to DeepQuantum
+
+First off, thank you for considering contributing to DeepQuantum!
+It’s people like you who make the open-source community such an amazing place to learn, inspire, and create.
+
+To maintain high code quality and a consistent developer experience, we have established a modern workflow using **Ruff**, **Jupytext**, and **pre-commit hooks**.
+Please follow these guidelines to get started.
+
+---
+
+## Setup Development Environment
+
+Before you start coding, ensure you have the development dependencies installed.
+We recommend using a virtual environment (Conda or venv).
+
+1. **Install Dependencies**:
+   ```bash
+   pip install -r requirements-dev.txt
+   ```
+
+2. **Install pre-commit hooks**:
+   We use `pre-commit` to automate code linting and formatting.
+   This ensures your code is compliant before every commit.
+   ```bash
+   pre-commit install
+   ```
+
+3. **Initialize Environment**:
+   It is a good practice to run the hooks against all files once to ensure your local environment is in sync:
+   ```bash
+   pre-commit run --all-files
+   ```
+
+---
+
+## Coding Standards
+
+We use **Ruff** as our primary linter and formatter.
+Our configuration includes:
+- **Line Length**: 120 characters.
+- **Quote Style**: Single quotes (`'`).
+- **Imports**: Sorted automatically (isort rules).
+
+### Linting Rules
+We enforce a strict set of rules, including Python upgrade suggestions (`UP`), naming conventions (`N`), and code simplifications (`SIM`).
+- **In the `src/` directory**: We additionally enforce **Google-style docstrings**.
+Please ensure your functions and classes are well-documented.
+
+### IDE Integration
+We recommend installing the **Ruff extension** for VS Code or your preferred IDE.
+Enable **Format on Save** to handle most styling issues automatically.
+
+---
+
+## Working with Notebooks (Jupytext)
+
+Our tutorials and examples are managed using **Jupytext**.
+This allows us to maintain Jupyter Notebooks (`.ipynb`) while tracking version-control-friendly Python scripts (`.py:percent`).
+
+### The Rule of Thumb:
+**Maintain the `.ipynb` files only.**
+The paired `.py` files are automatically generated or updated via pre-commit hooks.
+
+### IDE Integration:
+We recommend installing the **Jupytext extension** for VS Code or your preferred IDE to sync files automatically.
+
+> [!IMPORTANT]
+> **Version Consistency**: The VS Code Jupytext extension often points to a global path rather than your active Conda environment.
+Please ensure that the Jupytext version used by your IDE matches the one in `requirements-dev.txt` to avoid formatting discrepancies.
+
+---
+
+## Maintenance & Updates
+
+To keep the development tools up to date with the latest security fixes and features, please occasionally update the pre-commit hook versions:
+
+```bash
+pre-commit autoupdate
+```
+
+---
+
+## Pull Request Process
+
+1. **Create a Branch**: Use a descriptive name like `feat/new-model` or `fix/issue-123`.
+2. **Commit Your Changes**:
+   - If `pre-commit` fails during commit, it will often automatically fix the issues.
+   - Simply **re-add (`git add`)** the fixed files and commit again.
+3. **Reference Issues**: In your PR description, use keywords like `Closes #123` to link the PR to an issue.
+4. **Clean History**: We prefer a clean commit history.
+Please consider squashing your commits or rebasing on `main` before the final review.
+
+---
+
+## Documentation Guidelines
+
+For source code, we follow the **Google Docstring Convention**.
+- **`D102` / `D105` / `D107`**: We currently ignore missing docstrings in public methods and magic methods to reduce boilerplate, but we highly encourage documenting any complex logic.
+
+---
+
+## Need Help?
+
+If you have questions about the setup or a specific feature, feel free to:
+- Open an **Issue** on GitHub.
+
+Thank you for contributing to the future of quantum computing!

README.md

@@ -2,7 +2,6 @@
 
 ![DeepQuantum logo](docs/source/_static/assets/logo_light_v1.png)
 
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![docs](https://img.shields.io/badge/docs-link-blue.svg)](https://dqapi.turingq.com/)
 [![PyPI](https://img.shields.io/pypi/v/deepquantum.svg?logo=pypi)](https://pypi.org/project/deepquantum/)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/deepquantum)
@@ -87,6 +86,7 @@ Below are some minimal examples to help you get started.
 
 ```python
 import deepquantum as dq
+
 cir = dq.QubitCircuit(2)
 cir.h(0)
 cir.cnot(0, 1)
@@ -113,21 +113,21 @@ print(cir.expectation())
 - Photonic quantum circuit with the Fock backend, based on Fock basis state
 
 ```python
-cir = dq.QumodeCircuit(2, [1,1])
-cir.dc([0,1])
+cir = dq.QumodeCircuit(2, [1, 1])
+cir.dc([0, 1])
 cir.ps(0, 0.1)
-cir.bs([0,1], [0.2,0.3])
+cir.bs([0, 1], [0.2, 0.3])
 print(cir())
 print(cir.measure())
 ```
 
 - Photonic quantum circuit with the Fock backend, based on Fock state tensor
 
 ```python
-cir = dq.QumodeCircuit(2, [(1, [1,1])], basis=False)
-cir.dc([0,1])
+cir = dq.QumodeCircuit(2, [(1, [1, 1])], basis=False)
+cir.dc([0, 1])
 cir.ps(0, 0.1)
-cir.bs([0,1], [0.2,0.3])
+cir.bs([0, 1], [0.2, 0.3])
 print(cir())
 print(cir.measure())
 ```
@@ -138,7 +138,7 @@ print(cir.measure())
 cir = dq.QumodeCircuit(2, 'vac', cutoff=10, backend='gaussian')
 cir.s(0, 0.1)
 cir.d(1, 0.1)
-cir.bs([0,1], [0.2,0.3])
+cir.bs([0, 1], [0.2, 0.3])
 print(cir())
 print(cir.measure())
 print(cir.photon_number_mean_var(wires=0))
@@ -151,7 +151,7 @@ print(cir.measure_homodyne(wires=1))
 cir = dq.QumodeCircuit(2, 'vac', backend='bosonic')
 cir.cat(0, 0.5, 0.0)
 cir.gkp(1, 0.5, 0.5)
-cir.bs([0,1], [0.2,0.3])
+cir.bs([0, 1], [0.2, 0.3])
 print(cir())
 print(cir.photon_number_mean_var(wires=0))
 print(cir.measure_homodyne(wires=1))
@@ -167,7 +167,7 @@ pattern.e(1, 2)
 pattern.m(1)
 pattern.x(2, domain=1)
 # CNOT
-pattern.n([3,4])
+pattern.n([3, 4])
 pattern.e(2, 3)
 pattern.e(0, 3)
 pattern.e(3, 4)
@@ -196,10 +196,11 @@ print(cir() / pattern().full_state)
 
 ```python
 import torch
+
 # OMP_NUM_THREADS=2 torchrun --nproc_per_node=4 main.py
-backend = 'gloo' # for CPU
+backend = 'gloo'  # for CPU
 # torchrun --nproc_per_node=4 main.py
-backend = 'nccl' # for GPU
+backend = 'nccl'  # for GPU
 rank, world_size, local_rank = dq.setup_distributed(backend)
 if backend == 'nccl':
     device = f'cuda:{local_rank}'
@@ -229,9 +230,9 @@ dq.cleanup_distributed()
 
 ```python
 # OMP_NUM_THREADS=2 torchrun --nproc_per_node=4 main.py
-backend = 'gloo' # for CPU
+backend = 'gloo'  # for CPU
 # torchrun --nproc_per_node=4 main.py
-backend = 'nccl' # for GPU
+backend = 'nccl'  # for GPU
 rank, world_size, local_rank = dq.setup_distributed(backend)
 nmode = 4
 cutoff = 4
@@ -252,6 +253,22 @@ if rank == 0:
 dq.cleanup_distributed()
 ```
 
+# Contributing
+
+We welcome contributions from the community!
+To maintain high code quality and consistent style, we use a modern development workflow.
+
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Jupytext](https://img.shields.io/badge/jupytext-enabled-blue)](https://github.com/mwouts/jupytext)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+
+Please refer to our **[CONTRIBUTING.md](CONTRIBUTING.md)** for detailed instructions on:
+- **Linting & Formatting**: Our coding standards using Ruff.
+- **Notebook Management**: How we sync `.ipynb` and `.py` files using Jupytext.
+- **Pull Request Process**: How to link issues and submit your changes.
+
+Before your first commit, remember to run `pre-commit install` in your local environment.
+
 # Citation
 
 If you use DeepQuantum in your research, please cite [our paper](https://arxiv.org/abs/2512.18995):

docs/source/conf.py

@@ -14,20 +14,20 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'DeepQuantum'
-copyright = '2026, TuringQ'
+copyright = '2026, TuringQ'  # noqa: A001
 author = 'TuringQ'
 release = f'{dq.__version__}'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    'sphinx.ext.autodoc',     # 自动生成 API 文档
-    'sphinx.ext.napoleon',    # 支持 NumPy/Google 风格注释
-    'sphinx.ext.viewcode',    # 增加“查看源码”链接
-    'sphinx.ext.mathjax',     # 数学公式渲染
-    'sphinx.ext.autosummary', # 自动生成模块摘要
-    'myst_nb',                # 核心：解析 Notebook 和 MyST Markdown
+    'sphinx.ext.autodoc',  # 自动生成 API 文档
+    'sphinx.ext.napoleon',  # 支持 NumPy/Google 风格注释
+    'sphinx.ext.viewcode',  # 增加“查看源码”链接
+    'sphinx.ext.mathjax',  # 数学公式渲染
+    'sphinx.ext.autosummary',  # 自动生成模块摘要
+    'myst_nb',  # 核心：解析 Notebook 和 MyST Markdown
 ]
 
 add_module_names = False
@@ -62,10 +62,10 @@
 
 html_theme_options = {
     # 启用右侧的“在 GitHub 上编辑/查看”按钮
-    'repository_url': 'https://github.com/TuringQ/deepquantum', # 改成你的仓库地址
-    'use_repository_button': True,   # 开启 GitHub 仓库链接
-    'use_download_button': True,     # 开启当前页面(ipynb)下载按钮
-    'use_fullscreen_button': True,   # 开启全屏阅读按钮
+    'repository_url': 'https://github.com/TuringQ/deepquantum',  # 改成你的仓库地址
+    'use_repository_button': True,  # 开启 GitHub 仓库链接
+    'use_download_button': True,  # 开启当前页面(ipynb)下载按钮
+    'use_fullscreen_button': True,  # 开启全屏阅读按钮
     # 左侧导航栏配置
     'home_page_in_toc': False,
     'show_navbar_depth': 3,

docs/source/quick_start/basic_usage.md

@@ -82,9 +82,9 @@ class MyCircuit(nn.Module):
         self.cir = self.circuit(nqubit)
 
     def circuit(self, nqubit):
-        cir = dq.QubitCircuit(nqubit)         
+        cir = dq.QubitCircuit(nqubit)
         cir.hlayer()
-        # Using 'encode', specify where the variational parameters  
+        # Using 'encode', specify where the variational parameters
         # are encoded into the quantum circuit
         cir.rylayer(encode=True)
         cir.cnot_ring()
@@ -93,7 +93,7 @@ class MyCircuit(nn.Module):
         return cir
 
     def forward(self):
-        # During the forward process, variational parameters are 
+        # During the forward process, variational parameters are
         # added to the quantum circuit as 'data'
         self.cir(data=self.params)
         return self.cir.expectation().mean()
@@ -132,7 +132,7 @@ cir()
 # The bit string from left to right corresponds to the order of wires, which means
 # the first qubit is at the top, and the last qubit is at the bottom.
 print(cir.measure())
-# We can also set the sampling number, perform partial measurements, 
+# We can also set the sampling number, perform partial measurements,
 # and display ideal probabilities.
 print(cir.measure(shots=100, wires=[1,2], with_prob=True))
 ```
@@ -144,13 +144,13 @@ When employing parameterized quantum circuits in variational quantum algorithms,
 ```python
 cir = dq.QubitCircuit(4)
 cir.xlayer([0,2])
-# Multiple observables can be added, and the results of 
+# Multiple observables can be added, and the results of
 # each expectation value will be automatically concatenated
 # Flexibly specify measurement wires and bases using a list-based combination
 # e.g., wires=[0,1,2]、basis='xyz' representing the observable whose
 # wires 0, 1, and 2 corresponds to Pauli-X, Pauli-Y, and Pauli-Z, respectively
 for i in range(4):
-    cir.observable(i)      
+    cir.observable(i)
 cir() # Expectation value can be obtained after running the circuit
 print(cir.expectation())
 ```
@@ -173,4 +173,4 @@ print(cir.post_select(measure_rst))
 cir.draw()
 ```
 
-Note: defer_measure and post_select do not alter the final state state stored by QubitCircuit, making them incompatible with measure and expectation for conditional measurement.
+Note: defer_measure and post_select do not alter the final state state stored by QubitCircuit, making them incompatible with measure and expectation for conditional measurement.

docs/source/quick_start/introduction.md

@@ -4,4 +4,4 @@ Quantum computing is a rapidly growing field, poised to address the enormous com
 
 In the era of deep learning, important considerations for a quantum computing framework include its simulation scale, the ability to leverage GPU power for efficiency, the degree of integration with machine learning/deep learning libraries, and its user-friendliness and convenience. Influential quantum computing frameworks often aim to provide real quantum computing resources to users through cloud platforms.
 
-DeepQuantum is a lightweight quantum programming framework based on PyTorch, designed for programming and simulating quantum computing, quantum neural networks, and hybrid quantum-classical algorithms. It naturally integrates with PyTorch, offering a programming style closely aligned with PyTorch's own. This makes it more accessible to developers with a computer science background and those familiar with or exposed to PyTorch, lowering the learning curve and easing the transition from machine learning (deep learning) to quantum machine learning (quantum deep learning). DeepQuantum is meticulously designed for convenient initialization of quantum neural networks and flexible data encoding. It also implements tensor network algorithms, supporting large-scale quantum circuit simulations based on matrix product states.
+DeepQuantum is a lightweight quantum programming framework based on PyTorch, designed for programming and simulating quantum computing, quantum neural networks, and hybrid quantum-classical algorithms. It naturally integrates with PyTorch, offering a programming style closely aligned with PyTorch's own. This makes it more accessible to developers with a computer science background and those familiar with or exposed to PyTorch, lowering the learning curve and easing the transition from machine learning (deep learning) to quantum machine learning (quantum deep learning). DeepQuantum is meticulously designed for convenient initialization of quantum neural networks and flexible data encoding. It also implements tensor network algorithms, supporting large-scale quantum circuit simulations based on matrix product states.

docs/source/quick_start/introduction_cn.md

@@ -4,4 +4,4 @@
 
 在深度学习时代，一个量子计算框架所能支持的模拟规模、是否能够利用GPU的算力来提升效率、与机器学习/深度学习库结合的紧密程度以及其易用性、便捷性都是重要的考量。 同时，具有影响力的量子计算框架往往也肩负着通过云平台为用户提供真实量子计算资源的使命。
 
-DeepQuantum是一款基于PyTorch的轻量级的量子编程框架，用于量子计算、量子神经网络和混合量子-经典算法的编程和模拟。因此可以很自然地与PyTorch做到无缝衔接，编程风格也十分接近PyTorch本身的用法。 对于计算机背景出身、熟悉或接触过PyTorch的开发者来说更加友好，学习门槛低，很容易上手，更加适合相关开发者从机器学习（深度学习）进入到量子机器学习（量子深度学习）。 经过精心的设计，DeepQuantum在初始化量子神经网络时更加便捷，进行数据编码时更加灵活。 同时，DeepQuantum中也实现了张量网络算法，支持基于矩阵乘积态的大规模量子线路模拟。
+DeepQuantum是一款基于PyTorch的轻量级的量子编程框架，用于量子计算、量子神经网络和混合量子-经典算法的编程和模拟。因此可以很自然地与PyTorch做到无缝衔接，编程风格也十分接近PyTorch本身的用法。 对于计算机背景出身、熟悉或接触过PyTorch的开发者来说更加友好，学习门槛低，很容易上手，更加适合相关开发者从机器学习（深度学习）进入到量子机器学习（量子深度学习）。 经过精心的设计，DeepQuantum在初始化量子神经网络时更加便捷，进行数据编码时更加灵活。 同时，DeepQuantum中也实现了张量网络算法，支持基于矩阵乘积态的大规模量子线路模拟。