### Apply Basic Photonic Gates on QumodeCircuit

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

Illustrates how to initialize a `dq.QumodeCircuit` with a Fock backend and apply common photonic quantum gates. Examples include phase shifters (`ps`), beam splitters (`bs`), and Mach-Zehnder interferometers (`mzi`), demonstrating how to specify modes and parameters.

```python
init_state = [1,0]
cir = dq.QumodeCircuit(nmode=2, init_state=init_state, cutoff=3, backend='fock', basis=True)
cir.ps(0, torch.pi)
cir.ps(1, torch.pi)
cir.bs([0,1], [torch.pi/4, torch.pi/4])
cir.mzi([0,1], [torch.pi/4, torch.pi/4])
```

--------------------------------

### Initialize QubitState with Classical Data

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Shows how to create a `QubitState` object by directly providing a classical data array, which is stored as a `torch` tensor in the `state` attribute. This example initializes a single-qubit state.

```python
qstate = dq.QubitState(nqubit=1, state=[0,1])
print(qstate.state)
```

--------------------------------

### Install DeepQuantum from source

Source: https://github.com/turingq/deepquantum/blob/main/README.md

This snippet shows how to install DeepQuantum by cloning its Git repository and installing it in editable mode. It also provides an option to use a Tsinghua source mirror for dependencies.

```bash
git clone https://github.com/TuringQ/deepquantum.git
cd deepquantum
pip install -e .
# or use tsinghua source
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple
```

--------------------------------

### Initialize DeepQuantum and Check Version

Source: https://github.com/turingq/deepquantum/blob/main/docs/mbqc_basics.ipynb

Imports necessary libraries (deepquantum, numpy, torch) and prints the installed version of deepquantum.

```python
import deepquantum as dq
import numpy as np
import torch
print('version',dq.__version__)
```

--------------------------------

### Install DeepQuantum using pip

Source: https://github.com/turingq/deepquantum/blob/main/README.md

This snippet demonstrates how to install the DeepQuantum library using the pip package manager. It includes options for standard installation, developer installation, and using a Tsinghua source mirror for faster downloads.

```bash
pip install deepquantum
# or for developers
pip install deepquantum[dev]
# or use tsinghua source
pip install deepquantum -i https://pypi.tuna.tsinghua.edu.cn/simple
```

--------------------------------

### Import DeepQuantum and Related Libraries

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Demonstrates how to import the `deepquantum` library along with `torch` and `torch.nn`, which are essential for building quantum machine learning applications.

```python
import deepquantum as dq
import torch
import torch.nn as nn
```

--------------------------------

### Install Bayesian Optimization Library

Source: https://github.com/turingq/deepquantum/blob/main/examples/test_for_onchip_optimizer.ipynb

Installs the `bayesian-optimization` library, which is a common dependency for optimization tasks, potentially used later for variational quantum algorithms.

```python
# !pip install bayesian-optimization
```

--------------------------------

### Import DeepQuantum and Dependencies

Source: https://github.com/turingq/deepquantum/blob/main/examples/tdm/simple_cluster_state/一维纠缠态的制备.ipynb

Imports necessary libraries: deepquantum for quantum operations, numpy for numerical operations, and torch for tensor manipulations.

```python
import deepquantum as dq
import numpy as np
import torch
```

--------------------------------

### Combine DeepQuantum Quantum Circuits by Addition Operator

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/案例.md

This example showcases DeepQuantum's flexibility in manipulating quantum circuits by allowing them to be combined using the addition operator. Multiple `dq.QubitCircuit` instances are created and then added together. This demonstrates a concise way to build complex quantum operations.

```python
nqubit = 2
batch = 2
data1 = torch.sin(torch.tensor(list(range(batch * nqubit)))).reshape(batch, nqubit)
data2 = torch.cos(torch.tensor(list(range(batch * nqubit)))).reshape(batch, nqubit)
cir1 = dq.QubitCircuit(nqubit)
cir1.rxlayer(encode=True)
cir2 = dq.QubitCircuit(nqubit)
cir2.rylayer(encode=True)
cir3 = dq.QubitCircuit(nqubit)
cir3.rzlayer()

data = torch.cat([data1, data2], dim=-1)
cir = cir1 + cir3 + cir2 + cir3 # 线路相加后直接形成一个新的量子线路
cir.observable(0)
cir(data)
print(cir.expectation())
```

--------------------------------

### Calculate Expectation Value of Observable

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Demonstrates the initial setup for calculating the expectation value of an observable in DeepQuantum. It shows how to initialize a `QubitCircuit` and apply a simple layer of gates, setting the stage for adding observables and computing their expectation values.

```python
cir = dq.QubitCircuit(4)
cir.xlayer([0,2])
```

--------------------------------

### Apply Layered Rx Gates with Manual Parameters

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Illustrates how to manually initialize fixed parameters for a layer of Rx gates using the 'inputs' argument. This provides explicit control over the gate parameters.

```python
cir.rxlayer(wires=[0, 1, 2, ...], inputs=[theta_0, theta_1, ...])
```

--------------------------------

### Initialize a QubitCircuit

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

This snippet initializes a `dq.QubitCircuit` object with a specified number of qubits (4 in this case), preparing it for quantum gate operations.

```python
cir = dq.QubitCircuit(4)
```

--------------------------------

### Define Trainable Quantum Circuit with PyTorch nn.Module

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Provides an example of integrating a DeepQuantum circuit into a PyTorch `nn.Module` for trainable parameters. It shows how to define variational parameters using `nn.Parameter`, construct a circuit with layers like `hlayer`, `rylayer`, and `cnot_ring`, and pass parameters during the forward pass for expectation value calculation.

```python
class MyCircuit(nn.Module):
    def __init__(self, nqubit):
        super().__init__()
        # Manually initialize the variational parameter to 1
        self.params = nn.Parameter(torch.ones(nqubit))
        self.cir = self.circuit(nqubit)

    def circuit(self, nqubit):
        cir = dq.QubitCircuit(nqubit)         
        cir.hlayer()
        # Using 'encode', specify where the variational parameters  
        # are encoded into the quantum circuit
        cir.rylayer(encode=True)
        cir.cnot_ring()
        for i in range(nqubit):
            cir.observable(i)
        return cir

    def forward(self):
        # During the forward process, variational parameters are 
        # added to the quantum circuit as 'data'
        self.cir(data=self.params)
        return self.cir.expectation().mean()
```

--------------------------------

### Define Trainable Quantum Circuit using PyTorch nn.Module

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

This example demonstrates how to integrate a DeepQuantum `QubitCircuit` into a PyTorch `nn.Module` for variational quantum algorithms. It shows manual initialization of trainable parameters (`nn.Parameter`), encoding them into the quantum circuit using `encode=True` for `rylayer`, and performing a forward pass to calculate expectation values.

```python
class MyCircuit(nn.Module):
    def __init__(self, nqubit):
        super().__init__()
        # 手动初始化变分参数为1
        self.params = nn.Parameter(torch.ones(nqubit))
        self.cir = self.circuit(nqubit)

    def circuit(self, nqubit):
        cir = dq.QubitCircuit(nqubit)
        cir.hlayer()
        # 利用encode，指定变分参数编码到量子线路中的位置
        cir.rylayer(encode=True)
        cir.cnot_ring()
        for i in range(nqubit):
            cir.observable(i)
        return cir

    def forward__(self):
        # 在前向过程中，变分参数作为data加入量子线路
        self.cir(data=self.params)
        return self.cir.expectation().mean()
```

--------------------------------

### Import DeepQuantum and Dependencies

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

This snippet imports the necessary DeepQuantum modules (dq, dqp) along with PyTorch (torch) and its neural network module (torch.nn) for quantum circuit development and machine learning applications.

```python
import deepquantum as dq
import deepquantum.photonic as dqp
import torch
import torch.nn as nn
```

--------------------------------

### Initialize QubitState to GHZ State

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Shows how to initialize a `QubitState` object to a Greenberger–Horne–Zeilinger (GHZ) state using the 'ghz' string literal. This example creates a 3-qubit GHZ state.

```python
qstate = dq.QubitState(nqubit=3, state='ghz')
print(qstate.state)
```

--------------------------------

### Run GHZ Circuit with Multiple Batches of Parameters

Source: https://github.com/turingq/deepquantum/blob/main/examples/tdm/simple_cluster_state/一维纠缠态的制备.ipynb

Demonstrates running the GHZ circuit with multiple batches of periodic parameters by stacking the `data1` tensor. The output `samples.mT` shows the corresponding batch results.

```python
data3 = torch.stack([data1, data1])
cir(data=data3, nstep=14)
samples = cir.samples
samples.mT
```

--------------------------------

### Distributed Simulation of Photonic Quantum Circuits

Source: https://github.com/turingq/deepquantum/blob/main/README.md

This example shows how to set up and run a distributed simulation for a photonic quantum circuit using `deepquantum` and `torch.distributed`. Similar to the quantum circuit, it configures the backend and performs a photonic circuit simulation across multiple processes, including state and measurement results.

```python
# OMP_NUM_THREADS=2 torchrun --nproc_per_node=4 main.py
backend = 'gloo' # for CPU
# torchrun --nproc_per_node=4 main.py
backend = 'nccl' # for GPU
rank, world_size, local_rank = dq.setup_distributed(backend)
nmode = 4
cutoff = 4
data = torch.arange(14, dtype=torch.float) / 10
cir = dq.DistributedQumodeCircuit(nmode, [0] * nmode, cutoff)
for i in range(nmode):
    cir.s(i, encode=True)
for i in range(nmode - 1):
    cir.bs([i, i + 1], encode=True)
if backend == 'nccl':
    data = data.to(f'cuda:{local_rank}')
    cir.to(f'cuda:{local_rank}')
state = cir(data).amps
result = cir.measure(with_prob=True)
if rank == 0:
    print(state)
    print(result)
dq.cleanup_distributed()
```

--------------------------------

### Initialize QubitState to All-Zeros State

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

Shows how to initialize a multi-qubit quantum state to the computational basis all-zeros state using the 'zeros' string literal for the `state` parameter in `dq.QubitState`.

```python
qstate = dq.QubitState(nqubit=2, state='zeros')
print(qstate.state)
```

--------------------------------

### Transpile QubitCircuit with Batch Initial State

Source: https://github.com/turingq/deepquantum/blob/main/docs/mbqc_basics.ipynb

Demonstrates transpiling a `QubitCircuit` that starts with a batch of initial states. It shows how the resulting `Pattern` retains the batch structure for its initial state, verifying the shape of the full state.

```python
n_qubits = 2
batch_size = 5
init_state = torch.rand(batch_size, 2**n_qubits) # 输入QubitCiurcuit后会自动归一化

cir = dq.QubitCircuit(n_qubits, init_state=init_state)
cir.h(0)
cir.h(1)
cir.cnot(0, 1)

pattern = cir.pattern()
print(pattern.init_state.full_state.shape)
pattern.init_state.full_state
```

--------------------------------

### Measure GHZ State in DeepQuantum

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Illustrates how to prepare a GHZ state and then perform a measurement on the `QubitCircuit`. It explains the output format (dictionary of bit strings and counts) and demonstrates options for partial measurements and displaying ideal probabilities.

```python
cir = dq.QubitCircuit(3)
cir.h(0)
cir.cnot(0, 1)
cir.cnot(0, 2)
cir.barrier()
cir()
# Measure the final state in QubitCircuit, and the returned result
# is a dictionary or a list of dictionaries.
# The dictionary uses bit strings as keys and their measured counts as values.
# The default value of 'shots' is 1024.
# 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, 
# and display ideal probabilities.
print(cir.measure(shots=100, wires=[1,2], with_prob=True))
```

--------------------------------

### Initialize QubitCircuit for Gate Operations

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Initializes a `QubitCircuit` object with 4 qubits, preparing it for subsequent quantum gate operations.

```python
cir = dq.QubitCircuit(4)
```

--------------------------------

### DeepQuantum QubitCircuit Object Initialization

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Describes the fundamental `QubitCircuit` object in DeepQuantum, used to represent quantum circuits. It explains how to initialize it with a specified number of qubits and its role in implementing parameterized quantum circuits for machine learning.

```APIDOC
QubitCircuit:
  __init__(n: int)
    n: The number of qubits in the circuit.
```

--------------------------------

### Apply Layered Rx Gates with Automatic Parameters

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Demonstrates applying a layer of Rx gates to specified wires in a `QubitCircuit`. The internal variational parameters for these gates are automatically initialized by DeepQuantum.

```python
cir.rxlayer(wires=[0,2])
```

--------------------------------

### Enable Large-Scale Quantum Simulation using DeepQuantum Tensor Networks

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/案例.md

This example demonstrates how DeepQuantum can perform large-scale quantum simulations on classical computers using tensor network algorithms. By setting `mps=True` and `chi` in `dq.QubitCircuit`, users can approximate quantum states with matrix product states. This enables simulations with more qubits than traditional methods, with `chi` controlling accuracy.

```python
batch = 2
nqubit = 100
data = torch.sin(torch.tensor(list(range(batch * nqubit)))).reshape(batch, nqubit)
cir = dq.QubitCircuit(nqubit, mps=True, chi=4)
cir.rylayer(encode=True)
cir.rxlayer()
cir.cnot_ring()
for i in range(nqubit):
    cir.observable(i)
cir(data)
print(cir.expectation())
```

--------------------------------

### Initialize QubitState to All-Zero State

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Demonstrates initializing a `QubitState` object to an all-zero quantum state using the 'zeros' string literal. This creates a 2-qubit state where both qubits are in the |0> state.

```python
qstate = dq.QubitState(nqubit=2, state='zeros')
print(qstate.state)
```

--------------------------------

### Initialize MBQC Pattern with Custom Initial States

Source: https://github.com/turingq/deepquantum/blob/main/docs/mbqc_basics.ipynb

Demonstrates initializing a `dq.Pattern` with various custom initial states, including a full state vector and string representations ('minus', 'zero', 'one'), showcasing flexibility in setting the pattern's starting quantum state.

```python
# 自定义初态
pattern = dq.Pattern(nodes_state=[0, 1], state=[1, 0, 0, 0])
print(pattern.init_state.full_state)

# 初态str表示
pattern = dq.Pattern(nodes_state=[0, 1], state='minus')
print(pattern.init_state.full_state)

pattern = dq.Pattern(nodes_state=[0, 1], state='zero')
print(pattern.init_state.full_state)

pattern = dq.Pattern(nodes_state=[0, 1], state='one')
print(pattern.init_state.full_state)
```

--------------------------------

### Initialize QubitState to Equal Superposition State

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

Illustrates initializing a multi-qubit quantum state into an equal superposition of all computational basis states by passing 'equal' to the `state` parameter of `dq.QubitState`.

```python
qstate = dq.QubitState(nqubit=2, state='equal')
print(qstate.state)
```

--------------------------------

### Simulating Photonic Circuit with Bosonic Backend

Source: https://github.com/turingq/deepquantum/blob/main/README.md

This example demonstrates a photonic quantum circuit simulation using `deepquantum.QumodeCircuit` with the Bosonic backend. It initializes with a vacuum state and applies cat states (cat), GKP states (gkp), and beam splitter (bs) operations, then measures photon number mean/variance and homodyne detection.

```python
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])
print(cir())
print(cir.photon_number_mean_var(wires=0))
print(cir.measure_homodyne(wires=1))
```

--------------------------------

### Apply Rx Layer with Manually Initialized Parameters

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

Shows how to apply an Rx gate layer to multiple qubits while explicitly providing fixed input parameters for each gate. This allows for precise control over the gate rotations.

```python
cir.rxlayer(wires=[0, 1, 2, ...], inputs=[theta_0, theta_1, ...])
```

--------------------------------

### Visualize QumodeCircuit Diagram

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

Demonstrates how to visualize the constructed photonic quantum circuit using `cir.draw()`. This function generates a visual representation of the circuit and saves it to a specified file, such as an SVG image.

```python
cir.draw(filename='circuit.svg')
```

--------------------------------

### Import DeepQuantum and NumPy Libraries

Source: https://github.com/turingq/deepquantum/blob/main/examples/basic_gate_MBQC.ipynb

Imports the `deepquantum` library for quantum circuit simulation and `numpy` for numerical operations, essential for defining angles and handling quantum states in the examples.

```python
import deepquantum as dq
import numpy as np
```

--------------------------------

### Run EPR Circuit with Multiple Batches of Parameters

Source: https://github.com/turingq/deepquantum/blob/main/examples/tdm/simple_cluster_state/一维纠缠态的制备.ipynb

Demonstrates running the circuit with multiple batches of periodic parameters by stacking the `data1` tensor. The output `sample.mT` shows the corresponding batch results.

```python
data3 = torch.stack([data1, data1])
cir(data=data3, nstep=13)
sample = cir.samples
sample.mT
```

--------------------------------

### Visualize Unrolled GHZ Circuit

Source: https://github.com/turingq/deepquantum/blob/main/examples/tdm/simple_cluster_state/一维纠缠态的制备.ipynb

Executes the circuit and then visualizes its unrolled equivalent, showing the full sequence of operations after forward propagation for the GHZ state preparation.

```python
cir()
cir.draw(unroll=True)
```

--------------------------------

### Initialize FockState for Photonic Circuits

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

Demonstrates the initialization of `dq.FockState` for photonic quantum circuits. It shows two modes: `basis=True` for single Fock basis states and `basis=False` for superposition states represented as a list of (amplitude, state vector) tuples.

```python
qstate1 = dq.FockState(state=[1,0,1,0], basis=True)
qstate2 = dq.FockState(state=[(0.6, [1,0,1,0]), (0.8, [1,1,0,0])], basis=False)
print(qstate1, qstate2)
```

--------------------------------

### Simulating Photonic Circuit with Fock Backend (State Tensor)

Source: https://github.com/turingq/deepquantum/blob/main/README.md

This example demonstrates a photonic quantum circuit using the Fock backend, initialized with a Fock state tensor instead of basis states (`basis=False`). It applies similar optical components and performs measurements.

```python
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])
print(cir())
print(cir.measure())
```

--------------------------------

### Initialize QubitState to GHZ State

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

Demonstrates the initialization of a multi-qubit quantum state to a GHZ (Greenberger–Horne–Zeilinger) entangled state using the 'ghz' string literal for the `state` parameter in `dq.QubitState`.

```python
qstate = dq.QubitState(nqubit=3, state='ghz')
print(qstate.state)
```

--------------------------------

### Apply Multi-controlled Quantum Gates

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Demonstrates the application of various multi-controlled quantum gates in DeepQuantum, including Toffoli, Fredkin, and general controlled gates like `x`, `crx`, `crxx`, and `u3`. It shows how to specify control and target qubits.

```python
cir = dq.QubitCircuit(4)
cir.toffoli(0, 1, 2) # Specify control bits and target bits in sequence
cir.fredkin(0, 1, 2)
# General quantum gates can specify any control bits using the 'controls' parameter
cir.x(3, controls=[0,1,2])
cir.crx(0, 1)
cir.crxx(0, 1, 2)
cir.u3(2, controls=[0,1,3])
cir.draw()
```

--------------------------------

### Apply Multi-Controlled Quantum Gates

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

Illustrates the application of various multi-controlled quantum gates in DeepQuantum. It includes Toffoli, Fredkin, controlled-X (with multiple controls), controlled-Rx, controlled-Rxx, and controlled-U3 gates, demonstrating how to specify control and target qubits.

```python
cir = dq.QubitCircuit(4)
cir.toffoli(0, 1, 2) # 按顺序指定控制位和目标位
cir.fredkin(0, 1, 2)
# 一般的量子门都可以通过controls参数来指定任意控制位
cir.x(3, controls=[0,1,2])
cir.crx(0, 1)
cir.crxx(0, 1, 2)
cir.u3(2, controls=[0,1,3])
cir.draw()
```

--------------------------------

### Define and Measure Observables in DeepQuantum

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

This snippet demonstrates how to define observables on a quantum circuit and then calculate their expectation values. It shows a basic loop to add multiple observables and retrieve the final expectation value after running the circuit.

```python
# 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() # Expectation value can be obtained after running the circuit
print(cir.expectation())
```

--------------------------------

### Initialize QubitState with Custom State Vector

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

Demonstrates how to create a single-qubit quantum state using `dq.QubitState` by providing a custom state vector. The `state` attribute holds the underlying PyTorch tensor representation of the quantum state.

```python
qstate = dq.QubitState(nqubit=1, state=[0,1])
print(qstate.state)
```

--------------------------------

### Estimating Quantum Phase with DeepQuantum QPE

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Application_Cases.md

This example demonstrates the Quantum Phase Estimation (QPE) algorithm as implemented in DeepQuantum. It shows how to estimate the phase of a unitary operator acting on an eigenvector, specifically for a single-qubit phase shift gate. The snippet initializes the QPE object, executes the algorithm, measures the result, and verifies the estimated phase.

```python
t = 3 # The number of counting qubits
phase = 1 / 8 # Phase to be estimated
qpe = dq.QuantumPhaseEstimationSingleQubit(t, phase)
qpe()
res = qpe.measure(wires=list(range(t)))
max_key = max(res, key=res.get)
phase_est = int(max_key, 2) / 2 ** t
print(phase_est == phase)
```

--------------------------------

### Perform Quantum Circuit Measurement

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

Demonstrates how to measure the final state of a `QubitCircuit`. It shows the creation of a GHZ state and then performs measurements, returning results as a dictionary of bitstrings and their counts. It also illustrates options for specifying the number of shots, partial measurements on specific wires, and displaying ideal probabilities.

```python
cir = dq.QubitCircuit(3)
cir.h(0)
cir.cnot(0, 1)
cir.cnot(0, 2)
cir.barrier()
cir()
# 对QubitCircuit中的末态进行测量，返回的结果是字典或者字典的列表
# 字典的key是比特串，value是对应测量到的次数
# 测量总数shots默认为1024
# 比特串从左到右对应于线路从小到大
# 即第一个qubit在最高位，最后一个qubit在最低位
print(cir.measure())
# 我们也可以设定采样次数、进行部分测量以及显示理想的概率。
print(cir.measure(shots=100, wires=[1,2], with_prob=True))
```

--------------------------------

### Transpiling Quantum Circuit to MBQC Pattern

Source: https://github.com/turingq/deepquantum/blob/main/README.md

This example shows how to transpile a standard `deepquantum.QubitCircuit` into an equivalent Measurement-Based Quantum Computation (MBQC) pattern. It compares the full state of the original circuit with the transpiled pattern to verify equivalence.

```python
cir = dq.QubitCircuit(2)
cir.h(0)
cir.cnot(0, 1)
cir.rx(1, 0.2)
pattern = cir.pattern()
print(cir())
print(pattern().full_state)
print(cir() / pattern().full_state)
```

--------------------------------

### Simulating Quantum Circuit with Matrix Product State Backend

Source: https://github.com/turingq/deepquantum/blob/main/README.md

This example shows how to use the Matrix Product State (MPS) backend in `deepquantum.QubitCircuit` by setting `mps=True` and adjusting the bond dimension `chi`. It performs similar operations to the basic quantum circuit but leverages MPS for potentially larger simulations.

```python
cir = dq.QubitCircuit(2, mps=True, chi=4)
cir.h(0)
cir.cnot(0, 1)
cir.rx(1, 0.2)
cir.observable(0)
print(cir())
print(cir.expectation())
```

--------------------------------

### Perform Sequential Quantum State Evolution with DeepQuantum Sub-circuits

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/案例.md

This snippet demonstrates an alternative method for evolving quantum states through multiple sub-circuits sequentially. Instead of combining circuits via addition, it passes the quantum state from one circuit's output to the next circuit's input. This provides fine-grained control over the state's evolution.

```python
state = cir1(data1)
state = cir3(state=state)
state = cir2(data2, state=state)
state = cir3(state=state)
cir3.reset_observable()
cir3.observable(0)
print(cir3.expectation())
```

--------------------------------

### Apply Rx Layer with Auto-Initialized Parameters

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

Applies an Rx gate layer to specified qubits (wires 0 and 2) within the `QubitCircuit`. If input parameters are not provided, DeepQuantum automatically initializes variational parameters for these gates, making them suitable for optimization.

```python
cir.rxlayer(wires=[0,2])
```

--------------------------------

### Implement Hybrid Quantum-Classical Models with DeepQuantum and PyTorch

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/案例.md

This Python code defines a `Hybrid` neural network module combining classical PyTorch layers with a DeepQuantum quantum circuit. It demonstrates integrating quantum layers into a classical deep learning framework. The `forward` method shows data encoding into the quantum circuit and expectation value calculation.

```python
class Hybrid(nn.Module):
    def __init__(self, dim_in, nqubit):
        super().__init__()
        self.fc1 = nn.Linear(dim_in, nqubit)
        # 构建好的线路本身就是nn.Module
        self.cir = self.circuit(nqubit)
        self.fc2 = nn.Linear(nqubit, 1)

    def circuit(self, nqubit):
        cir = dq.QubitCircuit(nqubit)
        cir.hlayer()
        # 准备将经典数据编码到量子线路中
        cir.rylayer(encode=True)
        cir.rxlayer()
        cir.cnot_ring()
        for i in range(nqubit):
            cir.observable(i)
        return cir

    def forward(self, x):
        x = torch.arctan(self.fc1(x))
        # 前向计算的第一个参数对应于要编码的数据
        self.cir(x)
        exp = self.cir.expectation()
        out = self.fc2(exp)
        return out

nqubit = 4
batch = 2
nfeat = 8
x = torch.sin(torch.tensor(list(range(batch * nfeat)))).reshape(batch, nfeat)
net = Hybrid(nfeat, nqubit)
y = net(x)
print(y)
for i in net.named_parameters():
    print(i)
```

--------------------------------

### Initialize DeepQuantum Photonic Circuit Environment

Source: https://github.com/turingq/deepquantum/blob/main/examples/test_for_onchip_optimizer.ipynb

Imports necessary DeepQuantum modules and other scientific computing libraries. It initializes NumPy print options for better readability, generates a random unitary matrix, and decomposes it into MZI (Mach-Zehnder Interferometer) parameters using the 'cssr' method, which forms the basis of the photonic circuit.

```python
import deepquantum as dq
import deepquantum.photonic.circuit as circuit
import matplotlib.pyplot as plt
import numpy as np

from deepquantum.optimizer import *
from deepquantum.photonic.decompose import *
from scipy.stats import unitary_group

np.set_printoptions(precision=8, floatmode='fixed', suppress=True) # to make the print info aligned

N = 8
u8x8 = unitary_group.rvs(N)
decomp_rlt = UnitaryDecomposer(u8x8, "cssr").decomp()
mzi_info = decomp_rlt[0]
```

--------------------------------

### Evolve Pattern with Custom Initial GraphState

Source: https://github.com/turingq/deepquantum/blob/main/docs/mbqc_basics.ipynb

Shows how to evolve a `Pattern` by providing a custom initial `GraphState` object, in addition to encoded data. This allows for simulating the pattern starting from a specific quantum state, offering greater control over the simulation's initial conditions.

```python
init_graph_state = dq.GraphState([0, 1], state=[1, 0, 0, 0])

pattern(data=angle, state=init_graph_state).full_state
```

--------------------------------

### Benchmark DeepQuantum Gradient and Hessian Computation Performance

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/案例.md

This Python code defines utility functions for benchmarking the performance of gradient and Hessian computations in DeepQuantum. It includes a generic `benchmark` function to measure execution times. Specific functions (`grad_dq`, `hessian_dq`) set up quantum circuits and calculate gradients/Hessians using DeepQuantum and PyTorch.

```python
import time
import torch
from torch.autograd.functional import hessian
import deepquantum as dq

def benchmark(f, *args, trials=10):
    time0 = time.time()
    r = f(*args)
    time1 = time.time()
    for _ in range(trials):
        r = f(*args)
    time2 = time.time()
    if trials > 0:
        time21 = (time2 - time1) / trials
    else:
        time21 = 0
    ts = (time1 - time0, time21)
    print('staging time: %.6f s' % ts[0])
    if trials > 0:
        print('running time: %.6f s' % ts[1])
    return r, ts

 def grad_dq(n, l, trials=10):
    def get_grad_dq(params):
        if params.grad != None:
            params.grad.zero_()
        cir = dq.QubitCircuit(n)
        for j in range(l):
            for i in range(n - 1):
                cir.cnot(i, i + 1)
            cir.rxlayer(encode=True)
            cir.rzlayer(encode=True)
            cir.rxlayer(encode=True)
        cir.observable(basis='x')
        cir(data=params)
        exp = cir.expectation()
        exp.backward()
        return params.grad

    return benchmark(get_grad_dq, torch.ones([3 * n * l], requires_grad=True))

def hessian_dq(n, l, trials=10):
    def f(params):
        cir = dq.QubitCircuit(n)
        for j in range(l):
            for i in range(n - 1):
                cir.cnot(i, i + 1)
            cir.rxlayer(encode=True)
            cir.rzlayer(encode=True)
            cir.rxlayer(encode=True)
        cir.observable(basis='x')
        cir(data=params)
        return cir.expectation()

    def get_hs_dq(x):
        return hessian(f, x)

    return benchmark(get_hs_dq, torch.ones([3 * n * l]))
```

--------------------------------

### Map Graph Samples to Feature Vectors using Event Examples

Source: https://github.com/turingq/deepquantum/blob/main/examples/gbs/similar_graph/similar_graph.ipynb

This function `feature_map_event_sample` transforms a set of graph samples into feature vectors. It iterates through each sample, calculates the sum of samples for specified event photon numbers `event_photon_numbers` using `event_sample`, and then normalizes these counts to form a feature vector. The resulting feature vectors are stacked using `torch.stack`.

```python
def feature_map_event_sample(event_photon_numbers, n, samples):
    """Map a set of graph G to the feature vectors using the event examples."""
    all_feature_vectors = []
    for sample in samples:
        count_list = []
        total_num_samples = sum(sample.values())
        for k in event_photon_numbers:
            e_k_n = event_sample(k, n, sample)
            temp_sum = 0
            for i in range(len(e_k_n)):
                temp_sum = temp_sum + sum(e_k_n[i].values())
            count_list.append(temp_sum)
        feature_vector = (torch.stack(count_list) / total_num_samples).reshape(1,-1)
        all_feature_vectors.append(feature_vector.squeeze())
    return torch.stack(all_feature_vectors)
```

--------------------------------

### Simulating Large-Scale Quantum Circuits with DeepQuantum MPS

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Application_Cases.md

This snippet demonstrates how DeepQuantum enables large-scale quantum circuit simulations using tensor network algorithms (MPS). By setting 'mps=True' in QubitCircuit and adjusting 'chi', users can control simulation precision and runtime. The example initializes a 100-qubit circuit, applies various layers, and calculates expectations.

```python
batch = 2
nqubit = 100
data = torch.sin(torch.tensor(list(range(batch * nqubit)))).reshape(batch, nqubit)
cir = dq.QubitCircuit(nqubit, mps=True, chi=4)
cir.rylayer(encode=True)
cir.rxlayer()
cir.cnot_ring()
for i in range(nqubit):
    cir.observable(i)
cir(data)
print(cir.expectation())
```

--------------------------------

### Perform Conditional Measurements with `defer_measure` and `post_select`

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

This example illustrates how to perform conditional measurements in DeepQuantum using the `condition` parameter for gates and the `defer_measure` and `post_select` methods. It shows how to apply controlled operations and then process measurement results, noting that `defer_measure` and `post_select` do not alter the final state and are incompatible with `measure` and `expectation` for conditional measurement.

```python
cir = dq.QubitCircuit(3)
cir.h(0)
cir.x(1, controls=0, condition=True)
cir.x(2, controls=1, condition=True)
print(cir())
# Conduct random delay measurements
state, measure_rst, prob = cir.defer_measure(with_prob=True)
print(state)
# Choose specific measurement results
print(cir.post_select(measure_rst))
cir.draw()
```

--------------------------------

### deepquantum.photonic.qmath Module API Documentation

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/deepquantum.photonic.rst

API documentation for the deepquantum.photonic.qmath module, generated using Sphinx automodule directives to include all members, undocumented members, and inheritance information.

```APIDOC
.. automodule:: deepquantum.photonic.qmath
   :members:
   :undoc-members:
   :show-inheritance:
```

--------------------------------

### Visualize Unrolled EPR Circuit

Source: https://github.com/turingq/deepquantum/blob/main/examples/tdm/simple_cluster_state/一维纠缠态的制备.ipynb

Executes the circuit and then visualizes its unrolled equivalent, showing the full sequence of operations after forward propagation.

```python
cir()
cir.draw(unroll=True)
```

--------------------------------

### deepquantum.photonic.utils Module API Documentation

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/deepquantum.photonic.rst

API documentation for the deepquantum.photonic.utils module, generated using Sphinx automodule directives to include all members, undocumented members, and inheritance information.

```APIDOC
.. automodule:: deepquantum.photonic.utils
   :members:
   :undoc-members:
   :show-inheritance:
```

--------------------------------

### Initialize QubitState to Equal Superposition State

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc_en/Basic_Usage_Guide.md

Illustrates initializing a `QubitState` object to an equal-weighted superposition state using the 'equal' string literal. This creates a 2-qubit state in superposition.

```python
qstate = dq.QubitState(nqubit=2, state='equal')
print(qstate.state)
```

--------------------------------

### deepquantum.photonic.state Module API Documentation

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/deepquantum.photonic.rst

API documentation for the deepquantum.photonic.state module, generated using Sphinx automodule directives to include all members, undocumented members, and inheritance information.

```APIDOC
.. automodule:: deepquantum.photonic.state
   :members:
   :undoc-members:
   :show-inheritance:
```

--------------------------------

### deepquantum.photonic.circuit Module API Documentation

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/deepquantum.photonic.rst

API documentation for the deepquantum.photonic.circuit module, generated using Sphinx automodule directives to include all members, undocumented members, and inheritance information.

```APIDOC
.. automodule:: deepquantum.photonic.circuit
   :members:
   :undoc-members:
   :show-inheritance:
```

--------------------------------

### Distributed Simulation of Quantum Circuits

Source: https://github.com/turingq/deepquantum/blob/main/README.md

This snippet demonstrates setting up and running a distributed simulation for a quantum circuit using `deepquantum` and `torch.distributed`. It configures the backend (gloo for CPU, nccl for GPU), initializes the distributed environment, and performs a quantum circuit simulation across multiple processes, including gradient calculation.

```python
import torch
# OMP_NUM_THREADS=2 torchrun --nproc_per_node=4 main.py
backend = 'gloo' # for CPU
# torchrun --nproc_per_node=4 main.py
backend = 'nccl' # for GPU
rank, world_size, local_rank = dq.setup_distributed(backend)
if backend == 'nccl':
    device = f'cuda:{local_rank}'
elif backend == 'gloo':
    device = 'cpu'
data = torch.arange(4, dtype=torch.float, device=device, requires_grad=True)
cir = dq.DistributedQubitCircuit(4)
cir.rylayer(encode=True)
cir.cnot_ring()
cir.observable(0)
cir.observable(1, 'x')
if backend == 'nccl':
    cir.to(f'cuda:{local_rank}')
state = cir(data).amps
result = cir.measure(with_prob=True)
exp = cir.expectation().sum()
exp.backward()
if rank == 0:
    print(state)
    print(result)
    print(exp)
    print(data.grad)
dq.cleanup_distributed()
```

--------------------------------

### deepquantum.photonic.operation Module API Documentation

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/deepquantum.photonic.rst

API documentation for the deepquantum.photonic.operation module, generated using Sphinx automodule directives to include all members, undocumented members, and inheritance information.

```APIDOC
.. automodule:: deepquantum.photonic.operation
   :members:
   :undoc-members:
   :show-inheritance:
```

--------------------------------

### Evolve and Measure QumodeCircuit

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/基础使用指南.md

Shows how to evolve a `QumodeCircuit` to obtain its final state and then perform a measurement. The `cir()` call triggers the circuit evolution, and `cir.measure()` collects measurement samples from the final state.

```python
state = cir()
sample = cir.measure()
print(state, sample)
```

--------------------------------

### deepquantum.photonic.gate Module API Documentation

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/deepquantum.photonic.rst

API documentation for the deepquantum.photonic.gate module, generated using Sphinx automodule directives to include all members, undocumented members, and inheritance information.

```APIDOC
.. automodule:: deepquantum.photonic.gate
   :members:
   :undoc-members:
   :show-inheritance:
```

--------------------------------

### deepquantum.photonic.draw Module API Documentation

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/deepquantum.photonic.rst

API documentation for the deepquantum.photonic.draw module, generated using Sphinx automodule directives to include all members, undocumented members, and inheritance information.

```APIDOC
.. automodule:: deepquantum.photonic.draw
   :members:
   :undoc-members:
   :show-inheritance:
```

--------------------------------

### Import DeepQuantum and Dependencies

Source: https://github.com/turingq/deepquantum/blob/main/examples/tdm/advanced_cluster_state/复杂纠缠态的制备.ipynb

Imports necessary libraries: `deepquantum` for quantum simulation, `numpy` for numerical operations, and `torch` for tensor computations.

```python
import deepquantum as dq
import numpy as np
import torch
```

--------------------------------

### deepquantum.photonic.mapper Module API Documentation

Source: https://github.com/turingq/deepquantum/blob/main/docs/sphinx_doc/deepquantum.photonic.rst

API documentation for the deepquantum.photonic.mapper module, generated using Sphinx automodule directives to include all members, undocumented members, and inheritance information.

```APIDOC
.. automodule:: deepquantum.photonic.mapper
   :members:
   :undoc-members:
   :show-inheritance:
```

--------------------------------

### Visualize Quantum Circuit Diagram

Source: https://github.com/turingq/deepquantum/blob/main/examples/tdm/advanced_cluster_state/复杂纠缠态的制备.ipynb

Draws the quantum circuit diagram for visualization.

```python
cir.draw()
```

--------------------------------

### Run EPR Circuit with Encoded Periodic Parameters

Source: https://github.com/turingq/deepquantum/blob/main/examples/tdm/simple_cluster_state/一维纠缠态的制备.ipynb

Encodes periodic parameters for the circuit and runs it for 13 steps, performing homodyne measurements. The resulting samples are expected to show pairwise correlations, with the first sample corresponding to the vacuum state.

```python
data1 = torch.tensor([[np.pi/2, np.pi/2],
                      [np.pi/4, 0]])
data2 = data1.unsqueeze(0)
cir(data=data2, nstep=13)
sample = cir.samples
sample
```