Version 4.5.0

.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# Overhaul project structure, developer workflow, and documentation
+4e3707d369d7d77a0d3c99974057abdd62877347

.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CONTRIBUTING.md

@@ -1,8 +1,3 @@
-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!

README.md

@@ -290,7 +290,7 @@ To maintain high code quality and consistent style, we use a modern development
 [![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:
+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.

docs/source/conf.py

@@ -31,6 +31,9 @@
 ]
 
 add_module_names = False
+autodoc_inherit_docstrings = False
+autodoc_typehints = 'both'
+autodoc_typehints_description_target = 'documented'
 autosummary_generate = True
 
 napoleon_google_docstring = True

docs/source/index.md

@@ -1,6 +1,5 @@
 ```{include} ../../README.md
 :relative-images:
-:relative-docs:
 ```
 
 <!-- ```{toctree}
@@ -23,7 +22,7 @@ quick_start/basic_usage_cn.md
 quick_start/basic_examples_cn.md
 ```
 
-```{toctree}
+<!-- ```{toctree}
 :maxdepth: 1
 :caption: Tutorials
 :hidden:
@@ -40,7 +39,7 @@ tutorials/mbqc_basics.ipynb
 
 demos/gbs/boson_sampling/boson_sampling.ipynb
 demos/tdm/advanced_cluster_state/advanced_cluster_state.ipynb
-```
+``` -->
 
 ```{toctree}
 :maxdepth: 1

docs/source/quick_start/basic_examples.md

@@ -84,10 +84,10 @@ print(cir3.expectation())
 For quantum simulators, operational efficiency is a crucial performance metric. In tasks like VQE and quantum machine learning, aside from the forward evolution of quantum circuits, gradient calculation is a pivotal factor affecting efficiency. Comparisons between DeepQuantum, Qiskit and VQNet are illustrated as follows.
 
 ```python
+import deepquantum as dq
 import time
 import torch
 from torch.autograd.functional import hessian
-import deepquantum as dq
 
 def benchmark(f, *args, trials=10):
     time0 = time.time()

docs/source/quick_start/basic_examples_cn.md

@@ -81,13 +81,15 @@ print(cir3.expectation())
 
 ## 梯度计算的benchmark
 
-对于量子模拟器来说，运行效率是最重要的评价指标之一。对于VQE和量子机器学习等任务，除了量子线路的前向演化，梯度的计算是影响运行效率的最重要的因素。下面展示了DeepQuantum和Qiskit、VQNet的对比。
+对于量子模拟器来说，运行效率是最重要的评价指标之一。
+对于VQE和量子机器学习等任务，除了量子线路的前向演化，梯度的计算是影响运行效率的最重要的因素。
+下面展示了DeepQuantum和Qiskit、VQNet的对比。
 
 ```python
+import deepquantum as dq
 import time
 import torch
 from torch.autograd.functional import hessian
-import deepquantum as dq
 
 def benchmark(f, *args, trials=10):
     time0 = time.time()
@@ -152,8 +154,9 @@ def hessian_dq(n, l, trials=10):
 
 ## 大规模模拟
 
-用经典计算机对量子线路进行模拟，所需的计算资源会随着量子比特数的增加而呈指数级增长。DeepQuantum底层实现了张量网络算法，得以支持大规模的模拟。
-用户只需要设置QubitCircuit的mps=True即可，并且可以用chi来调节基于张量网络近似量子态的精度，chi越大模拟精度越高，运行速度越慢。
+用经典计算机对量子线路进行模拟，所需的计算资源会随着量子比特数的增加而呈指数级增长。
+DeepQuantum底层实现了张量网络算法，得以支持大规模的模拟。
+用户只需要设置`QubitCircuit`的`mps=True`即可，并且可以用`chi`来调节基于张量网络近似量子态的精度，`chi`越大模拟精度越高，运行速度越慢。
 
 ```python
 batch = 2
@@ -172,7 +175,8 @@ print(cir.expectation())
 ## 量子傅里叶变换
 
 量子傅里叶变换是离散傅里叶变换的量子对应。
-DeepQuantum基于Ansatz类实现了量子傅里叶变换（Ansatz类只是在QubitCircuit的基础上对新增的输入参数进行了有效性的判断）。用户同样可以基于Ansatz类来方便地复现和开发各种量子算法。
+DeepQuantum基于`Ansatz`类实现了量子傅里叶变换（`Ansatz`类只是在`QubitCircuit`的基础上对新增的输入参数进行了有效性的判断）。
+用户同样可以基于`Ansatz`类来方便地复现和开发各种量子算法。
 下面是具体的实现。
 
 ```python
@@ -207,7 +211,8 @@ class QuantumFourierTransform(dq.Ansatz):
 
 ## 量子相位估计
 
-量子相位估计算法是很多量子算法的关键。假设一个幺正算符U作用在其本征态 |u⟩ 上会出现一个相位 $e^{2{\pi}i{\psi}}$ ，相位估计算法的作用就是对这个相位 $\psi$ 进行估计。
+量子相位估计算法是很多量子算法的关键。
+假设一个幺正算符U作用在其本征态 |u⟩ 上会出现一个相位 $e^{2{\pi}i{\psi}}$ ，相位估计算法的作用就是对这个相位 $\psi$ 进行估计。
 下面演示的是DeepQuantum中已经实现的量子相位估计的例子，即针对单量子比特的相移门，得到它的相位。
 
 ```python

docs/source/quick_start/basic_usage_cn.md

@@ -11,17 +11,17 @@ import torch.nn as nn
 
 ## 量子线路对象
 
-DeepQuantum的基本对象是QubitCircuit和QumodeCircuit。
-QubitCircuit用量子比特数（n）来初始化量子线路，即cir=dq.QubitCircuit(n)。
-QumodeCircuit用模式数（n）来初始化光量子线路，即cir=dq.QumodeCircuit(n)。
+DeepQuantum的基本对象是`QubitCircuit`和`QumodeCircuit`。
+`QubitCircuit`用量子比特数（n）来初始化量子线路，即`cir=dq.QubitCircuit(n)`。
+`QumodeCircuit`用模式数（n）来初始化光量子线路，即`cir=dq.QumodeCircuit(n)`。
 DeepQuantum可以帮助用户很方便地实现参数化量子线路，从而进行量子机器学习。
 
 ## QubitCircuit基础使用说明
 
 ### 量子态
 
-QubitState是表示量子态的类。
-比如，我们可以利用QubitState准备一个单比特量子态，其数据是torch的tensor，存在属性state中。
+`QubitState`是表示量子态的类。
+比如，我们可以利用`QubitState`准备一个单比特量子态，其数据是`torch`的`Tensor`，存在属性`state`中。
 便捷地将经典数据编码为一个量子态
 
 ```python
@@ -53,23 +53,23 @@ print(qstate.state)
 
 ### 基本的量子门
 
-我们可以将各种量子门作用在QubitCircuit上。
-例如，我们可以将Hadamard门作用于1号量子比特：cir.h(1)；将Rx门作用于2号量子比特：cir.rx(2, inputs=0.2)；多量子比特门也一样：cir.cnot(0, 1)。
-同时，我们还可以一次性在量子线路上放置一层量子门，如cir.rxlayer()。
+我们可以将各种量子门作用在`QubitCircuit上`。
+例如，我们可以将Hadamard门作用于1号量子比特：`cir.h(1)`；将Rx门作用于2号量子比特：`cir.rx(2, inputs=0.2)`；多量子比特门也一样：`cir.cnot(0, 1)`。
+同时，我们还可以一次性在量子线路上放置一层量子门，如`cir.rxlayer()`。
 如果量子门没有指定输入参数，则会自动初始化变分参数。
 
 ```python
 cir = dq.QubitCircuit(4)
 ```
 
-第一个参数wires指定放置的线路，自动初始化内部的变分参数
+第一个参数`wires`指定放置的线路，自动初始化内部的变分参数
 
 ```python
 cir.rxlayer(wires=[0,2])
 ```
 
 我们也可以手动初始化参数，具体如下所示。
-利用inputs手动初始化固定参数
+利用`inputs`手动初始化固定参数
 
 ```python
 cir.rxlayer(wires=[0, 1, 2, ...], inputs=[theta_0, theta_1, ...])
@@ -158,7 +158,7 @@ print(cir.expectation())
 
 #### 条件测量
 
-使用condition参数可以实现条件测量，此时条件测量的位置由控制位controls决定。
+使用`condition`参数可以实现条件测量，此时条件测量的位置由控制位`controls`决定。
 
 ```python
 cir = dq.QubitCircuit(3)
@@ -174,13 +174,13 @@ print(cir.post_select(measure_rst))
 cir.draw()
 ```
 
-注意，defer_measure和post_select并不改变QubitCircuit所保存的末态state，因此measure和expectation目前并不兼容条件测量。
+注意，`defer_measure`和`post_select`并不改变`QubitCircuit`所保存的末态`state`，因此`measure`和`expectation`目前并不兼容条件测量。
 
 ## QumodeCircuit基础使用说明
 
 ### Fock后端的使用
 
-使用Fock后端可以构建基于离散变量的光量子线路，basis=True对应着量子态用Fock基矢态表示，basis=False对应着量子态用Fock态张量表示。
+使用Fock后端可以构建基于离散变量的光量子线路，`basis=True`对应着量子态用Fock基矢态表示，`basis=False`对应着量子态用Fock态张量表示。
 
 #### 量子态
 
@@ -194,8 +194,8 @@ print(qstate1, qstate2)
 
 #### 基本量子门
 
-我们可以将各种量子门作用在QumodeCircuit上。
-例如，我们可以将移相器作用于第1个mode：cir.ps(0)；将分束器作用于第1、2个mode：cir.bs([0,1])。
+我们可以将各种量子门作用在`QumodeCircuit`上。
+例如，我们可以将移相器作用于第1个mode：`cir.ps(0)`；将分束器作用于第1、2个mode：`cir.bs([0,1])`。
 如果量子门没有指定输入参数，则会自动初始化变分参数。
 
 ```python
@@ -217,7 +217,7 @@ print(state, sample)
 
 #### 线路可视化
 
-通过cir.draw()可以将搭建的光量子线路可视化并保存
+通过`cir.draw()`可以将搭建的光量子线路可视化并保存
 
 ```python
 cir.draw(filename='circuit.svg')
@@ -252,7 +252,7 @@ clements.draw()
 
 #### 量子态
 
-高斯态通过协方差矩阵cov和平均值矢量mean来表示，'vac'对应真空态，也可以设置cov和mean。
+高斯态通过协方差矩阵`cov`和平均值矢量`mean`来表示，`'vac'`对应真空态，也可以设置`cov`和`mean`。
 
 ```python
 qstate1 = dq.GaussianState(nmode=2, state='vac')
@@ -264,7 +264,7 @@ print(qstate1, qstate2)
 
 #### 基本量子门
 
-高斯操作对应的量子门有单模压缩门s、位移门d、旋转门r和分束器bs等。
+高斯操作对应的量子门有单模压缩门`s`、位移门`d`、旋转门`r`和分束器`bs`等。
 
 ```python
 cir = dq.QumodeCircuit(nmode=2, init_state='vac', cutoff=3, backend='gaussian')
@@ -277,13 +277,13 @@ cir.bs([0,1], [torch.pi/4, torch.pi/4])
 cir.draw()
 ```
 
-上面的压缩门和位移门具有r和theta两个参数。
-当用户只指定r时，theta默认为0。
-当用户只指定theta时，r默认随机初始化。
+上面的压缩门和位移门具有`r`和`theta`两个参数。
+当用户只指定`r`时，`theta`默认为0。
+当用户只指定`theta`时，`r`默认随机初始化。
 
 #### 线路演化和测量
 
-这里measure_homodyne测量对应的物理量是正交算符 $\hat{x}$ 和 $\hat{p}$ 的值，photon_number_mean_var对应的是每个mode的光子数的平均值和方差。
+这里`measure_homodyne`测量对应的物理量是正交算符 $\hat{x}$ 和 $\hat{p}$ 的值，`photon_number_mean_var`对应的是每个mode的光子数的平均值和方差。
 
 ```python
 state = cir()
@@ -304,13 +304,13 @@ adj_mat = torch.tensor([[0., 1., 1., 0., 0., 0.],
                         [0., 1., 0., 0., 1., 1.],
                         [0., 0., 0., 1., 0., 0.],
                         [0., 1., 0., 1., 0., 0.]])
-gbs = dqp.GBS_Graph(adj_mat=adj_mat, cutoff=2)
+gbs = dqp.GraphGBS(adj_mat=adj_mat, cutoff=2)
 state = gbs()
 sample = gbs.measure() # 高斯玻色采样
 print(sample)
 ```
 
-通过gbs.draw()可以可视化高斯玻色采样线路。
+通过`gbs.draw()`可以可视化高斯玻色采样线路。
 
 ```python
 gbs.draw()

docs/source/quick_start/introduction.md

@@ -1,7 +1,15 @@
 # Introduction and Overview
 
-Quantum computing is a rapidly growing field, poised to address the enormous computational power demands of the future. The integration of machine learning (deep learning) into quantum machine learning (quantum deep learning) also holds the potential for significant value. In the current Noisy Intermediate-Scale Quantum (NISQ) era, due to the prohibitive cost and limited accessibility of real quantum computing resources, research in QML largely depends on classical computers to simulate quantum circuits. Therefore, with the boundless potential of this field, both domestic and international companies have already laid the groundwork in programming frameworks and software services, capitalizing on early-mover advantages to attract and cultivate potential users, even before the advent of fault-tolerant universal quantum computers.
+Quantum computing is a rapidly growing field, poised to address the enormous computational power demands of the future.
+The integration of machine learning (deep learning) into quantum machine learning (quantum deep learning) also holds the potential for significant value.
+In the current Noisy Intermediate-Scale Quantum (NISQ) era, due to the prohibitive cost and limited accessibility of real quantum computing resources, research in QML largely depends on classical computers to simulate quantum circuits.
+Therefore, with the boundless potential of this field, both domestic and international companies have already laid the groundwork in programming frameworks and software services, capitalizing on early-mover advantages to attract and cultivate potential users, even before the advent of fault-tolerant universal quantum computers.
 
-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.
+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

@@ -1,7 +1,14 @@
 # 引言和概述
 
-量子计算是一个蓬勃发展的领域，有望为未来巨大的算力需求提供解决方案，而结合了机器学习（深度学习）的量子机器学习（量子深度学习）也有望产生巨大的价值。 在目前的NISQ时代，由于真实的量子计算资源过于昂贵而无法获得或难以获得，对于量子机器学习的研究在很大程度上需要借助经典计算机对量子线路进行模拟。 因此，基于这个领域在未来的无限可能，在真正的容错通用量子计算机落地前，国内外各家相关公司早已在编程框架、软件服务方面进行了布局，以利用先发优势吸引和培养潜在用户。
+量子计算是一个蓬勃发展的领域，有望为未来巨大的算力需求提供解决方案，而结合了机器学习（深度学习）的量子机器学习（量子深度学习）也有望产生巨大的价值。
+在目前的NISQ时代，由于真实的量子计算资源过于昂贵而无法获得或难以获得，对于量子机器学习的研究在很大程度上需要借助经典计算机对量子线路进行模拟。
+因此，基于这个领域在未来的无限可能，在真正的容错通用量子计算机落地前，国内外各家相关公司早已在编程框架、软件服务方面进行了布局，以利用先发优势吸引和培养潜在用户。
 
-在深度学习时代，一个量子计算框架所能支持的模拟规模、是否能够利用GPU的算力来提升效率、与机器学习/深度学习库结合的紧密程度以及其易用性、便捷性都是重要的考量。 同时，具有影响力的量子计算框架往往也肩负着通过云平台为用户提供真实量子计算资源的使命。
+在深度学习时代，一个量子计算框架所能支持的模拟规模、是否能够利用GPU的算力来提升效率、与机器学习/深度学习库结合的紧密程度以及其易用性、便捷性都是重要的考量。
+同时，具有影响力的量子计算框架往往也肩负着通过云平台为用户提供真实量子计算资源的使命。
 
-DeepQuantum是一款基于PyTorch的轻量级的量子编程框架，用于量子计算、量子神经网络和混合量子-经典算法的编程和模拟。因此可以很自然地与PyTorch做到无缝衔接，编程风格也十分接近PyTorch本身的用法。 对于计算机背景出身、熟悉或接触过PyTorch的开发者来说更加友好，学习门槛低，很容易上手，更加适合相关开发者从机器学习（深度学习）进入到量子机器学习（量子深度学习）。 经过精心的设计，DeepQuantum在初始化量子神经网络时更加便捷，进行数据编码时更加灵活。 同时，DeepQuantum中也实现了张量网络算法，支持基于矩阵乘积态的大规模量子线路模拟。
+DeepQuantum是一款基于PyTorch的轻量级的量子编程框架，用于量子计算、量子神经网络和混合量子-经典算法的编程和模拟。
+因此可以很自然地与PyTorch做到无缝衔接，编程风格也十分接近PyTorch本身的用法。
+对于计算机背景出身、熟悉或接触过PyTorch的开发者来说更加友好，学习门槛低，很容易上手，更加适合相关开发者从机器学习（深度学习）进入到量子机器学习（量子深度学习）。
+经过精心的设计，DeepQuantum在初始化量子神经网络时更加便捷，进行数据编码时更加灵活。
+同时，DeepQuantum中也实现了张量网络算法，支持基于矩阵乘积态的大规模量子线路模拟。