docs(QAOA): Comprehensive bilingual documentation

pyqpanda-algorithm/pyqpanda_alg/QAOA/README_QAOA_ENHANCED.md

@@ -0,0 +1,257 @@
+# QAOA (Quantum Approximate Optimization Algorithm) - 量子近似优化算法
+
+## Overview 概
+[truncated]
+mization Algorithm (QAOA) is a variational quantum algorithm designed to solve combinatorial optimization problems. It was proposed by Farhi, Goldstone, and Gutmann in 2014 as a candidate algorithm for achieving quantum advantage on near-term quantum devices.
+
+QAOA通过构造参数化量子电路来寻找哈密顿量的基态（最低能量态），从而解决组合优化问题。该算法被认为是实现近期量子设备量子优势的主要候选算法之一。
+
+## Mathematical Foundation 数学原理
+
+### Problem Formulation 问题建模
+
+Given a combinatorial optimization problem with objective function:
+$$f(x_1, x_2, \ldots, x_n) \rightarrow \min$$
+
+where $x_i \in \{0, 1\}$ are binary variables.
+
+将二元变量转换为泡利算符：
+$$x_i \rightarrow \frac{I - Z_i}{2}$$
+
+### QAOA Circuit Structure QAOA电路结构
+
+The QAOA ansatz consists of alternating layers:
+
+1. **Problem Hamiltonian layer** 问题哈密顿量层:
+$$U(H_C, \gamma) = e^{-i\gamma H_C}$$
+
+2. **Mixer Hamiltonian layer** 混合哈密顿量层:
+$$U(H_B, \beta) = e^{-i\beta H_B}$$
+
+where $H_C$ is the cost Hamiltonian and $H_B = \sum_i X_i$ is the mixer.
+
+For $p$ layers, the full circuit is:
+$$|\psi(\gamma, \beta)\rangle = e^{-i\beta_p H_B} e^{-i\gamma_p H_C} \cdots e^{-i\beta_1 H_B} e^{-i\gamma_1 H_C} |+\rangle^{\otimes n}$$
+
+## API Reference API参考文档
+
+### Core Functions 核心函数
+
+#### `p_1(n)`
+Convert binary variable $x_n$ to Pauli operator $\frac{I-Z_n}{2}$
+
+**Parameters 参数:**
+- `n` (int): Index of the variable, starting from 0
+
+**Returns 返回值:**
+- `PauliOperator`: Pauli operator representation
+
+**Example 示例:**
+```python
+from pyqpanda_alg.QAOA import qaoa
+operator = qaoa.p_1(0)
+print(operator)
+# Output: { qbit_total = 1, pauli_with_coef_s = { '':0.5 + 0j, 'Z0 ':-0.5 + 0j, } }
+```
+
+#### `p_0(n)`
+Convert binary variable $x_n$ to Pauli operator $\frac{I+Z_n}{2}$
+
+**Parameters 参数:**
+- `n` (int): Index of the variable, starting from 0
+
+**Returns 返回值:**
+- `PauliOperator`: Pauli operator representation
+
+#### `problem_to_z_operator(problem, norm=False)`
+Convert polynomial objective function to Pauli operator Hamiltonian
+
+**Parameters 参数:**
+- `problem` (sympy expression): Polynomial with binary variables
+- `norm` (bool, optional): Whether to normalize the operator. Default: False
+
+**Returns 返回值:**
+- `PauliOperator`: Hamiltonian in Pauli operator form
+
+**Example 示例:**
+```python
+import sympy as sp
+from pyqpanda_alg.QAOA import qaoa
+
+# Define binary variables
+vars = sp.symbols('x0:3')
+
+# Define objective function: 2*x0*x1 + 3*x2 - 1
+f = 2*vars[0]*vars[1] + 3*vars[2] - 1
+
+# Convert to Hamiltonian
+hamiltonian = qaoa.problem_to_z_operator(f)
+print(hamiltonian)
+```
+
+### QAOA Class QAOA类
+
+#### `QAOA(problem, depth=3, optimizer='COBYLA', tol=1e-3, max_iter=300, step_size=0.1)`
+
+Initialize QAOA solver for a given optimization problem.
+
+**Parameters 参数:**
+- `problem` (sympy expression or PauliOperator): The optimization problem
+- `depth` (int): Number of QAOA layers (p value). Default: 3
+- `optimizer` (str): Classical optimizer to use. Options: 'COBYLA', 'L-BFGS-B', 'SPSA'. Default: 'COBYLA'
+- `tol` (float): Optimization tolerance. Default: 1e-3
+- `max_iter` (int): Maximum optimization iterations. Default: 300
+- `step_size` (float): Initial step size for optimization. Default: 0.1
+
+**Methods 方法:**
+
+##### `run(shots=1024, init_point=None)`
+Execute QAOA optimization and return optimal parameters.
+
+**Parameters 参数:**
+- `shots` (int): Number of measurement shots. Default: 1024
+- `init_point` (array-like, optional): Initial parameter values. Default: None (random initialization)
+
+**Returns 返回值:**
+- `dict`: Optimization results containing:
+  - `optimal_params`: Optimal (gamma, beta) parameters
+  - `optimal_value`: Minimum energy value found
+  - `solution`: Binary string representing the solution
+  - `expectation_history`: Energy values during optimization
+
+##### `get_circuit(params)`
+Generate the QAOA quantum circuit with given parameters.
+
+**Parameters 参数:**
+- `params` (array-like): Array of [gamma_1, ..., gamma_p, beta_1, ..., beta_p]
+
+**Returns 返回值:**
+- `QCircuit`: Quantum circuit implementing QAOA ansatz
+
+## Usage Examples 使用示例
+
+### Example 1: Max-Cut Problem 最大割问题
+
+```python
+import networkx as nx
+import sympy as sp
+from pyqpanda_alg.QAOA import qaoa
+from pyqpanda3 import *
+
+# Create a graph
+G = nx.Graph()
+G.add_edges_from([(0, 1), (1, 2), (2, 3), (3, 0), (0, 2)])
+
+# Define Max-Cut objective
+vars = sp.symbols('x0:4')
+obj = 0
+for edge in G.edges():
+    i, j = edge
+    obj += vars[i] * (1 - vars[j]) + (1 - vars[i]) * vars[j]
+
+# Solve with QAOA
+solver = qaoa.QAOA(obj, depth=3, optimizer='COBYLA')
+result = solver.run(shots=1024)
+
+print(f"Optimal solution: {result['solution']}")
+print(f"Max-Cut value: {result['optimal_value']}")
+```
+
+### Example 2: Portfolio Optimization 投资组合优化
+
+```python
+import sympy as sp
+import numpy as np
+from pyqpanda_alg.QAOA import qaoa
+
+# Portfolio parameters
+n_assets = 5
+returns = np.array([0.1, 0.15, 0.08, 0.12, 0.09])
+covariance = np.random.rand(n_assets, n_assets)
+covariance = (covariance + covariance.T) / 2  # Make symmetric
+q = 0.5  # Risk tolerance
+
+# Define portfolio optimization problem
+vars = sp.symbols(f'x0:{n_assets}')
+obj = -sum(returns[i] * vars[i] for i in range(n_assets))
+obj += q * sum(covariance[i][j] * vars[i] * vars[j] 
+               for i in range(n_assets) for j in range(n_assets))
+
+# Solve
+solver = qaoa.QAOA(obj, depth=4, optimizer='SPSA')
+result = solver.run(shots=2048)
+
+# Decode solution
+selected_assets = [i for i, bit in enumerate(result['solution']) if bit == '1']
+print(f"Selected assets: {selected_assets}")
+```
+
+## Advanced Features 高级特性
+
+### Custom Mixer Hamiltonians 自定义混合哈密顿量
+
+Users can define custom mixers beyond the standard X-mixer:
+
+```python
+from pyqpanda3.hamiltonian import PauliOperator
+
+# XY mixer (preserves particle number)
+xy_mixer = sum(PauliOperator({f'X{i} X{j}': 0.5, f'Y{i} Y{j}': 0.5})
+               for i in range(n) for j in range(i+1, n))
+
+solver = qaoa.QAOA(problem, mixer_hamiltonian=xy_mixer)
+```
+
+### Warm-Start Initialization 热启动初始化
+
+Use classical optimization results to initialize QAOA parameters:
+
+```python
+from scipy.optimize import minimize
+
+# Classical pre-optimization
+classical_result = minimize(classical_objective, x0)
+
+# Use classical result for warm-start
+init_gamma = np.arctan(classical_result.x)
+init_beta = np.full(p, np.pi/8)
+init_point = np.concatenate([init_gamma, init_beta])
+
+result = solver.run(init_point=init_point)
+```
+
+## Best Practices 最佳实践
+
+1. **Choose appropriate depth**: Start with p=3-4 for small problems, increase for complex problems
+2. **Select optimizer carefully**: 
+   - Use 'COBYLA' for smooth landscapes
+   - Use 'SPSA' for noisy quantum hardware
+3. **Increase shots for accuracy**: Use 1024+ shots on simulators, 8192+ on real hardware
+4. **Multiple restarts**: Run QAOA multiple times with different random seeds
+5. **Classical preprocessing**: Use warm-start when classical solutions are available
+
+## Performance Tips 性能提示
+
+- Use `norm=True` for large problems to avoid numerical overflow
+- Enable GPU acceleration: `from pyqpanda3 import GPUQVM`
+- Reduce circuit depth if optimization convergence is slow
+- Use parameter interpolation for larger p values
+
+## References 参考文献
+
+1. Farhi, E., Goldstone, J., & Gutmann, S. (2014). A Quantum Approximate Optimization Algorithm. arXiv:1411.4028
+2. Hadfield, S. et al. (2019). From the Quantum Approximate Optimization Algorithm to a Quantum Alternating Operator Ansatz. Algorithms, 12(2), 34.
+3. Zhou, L. et al. (2020). Quantum Approximate Optimization Algorithm: Performance, Mechanism, and Implementation on Near-Term Devices. Physical Review X, 10(2), 021067.
+
+## Version History 版本历史
+
+- v1.0.0: Initial QAOA implementation with basic optimizer support
+- v1.1.0: Added SPSA optimizer for quantum hardware
+- v1.2.0: Added warm-start and custom mixer support
+- v1.3.0: Enhanced documentation and examples
+
+---
+
+**Maintainer**: Origin Quantum Computing Company 本源量子计算科技（合肥）股份有限公司  
+**License**: Apache License 2.0  
+**Last Updated**: 2026-03-08