unitarylab-algorithms 1.0.0__tar.gz

unitarylab_algorithms-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+MIT LicenseCopyright (c) 2026 
+UnitaryLab Quantum Technology Co., Ltd., Shanghai, P.R. China
+
+Permission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.

unitarylab_algorithms-1.0.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: unitarylab_algorithms
+Version: 1.0.0
+Summary: A Python package for quantum algorithms from UnitaryLab.
+Author: UnitaryLab
+License-Expression: MIT
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: torch
+Requires-Dist: matplotlib
+Requires-Dist: scikit-learn
+Requires-Dist: mpmath
+Dynamic: license-file
+
+# unitarylab_algorithms
+
+本 [算法库](https://github.com/unitarylab/unitarylab_algorithms) 由 [UntiaryLab](https://unitarylab.com/) 整理开发实现，包含可独立调用的量子算法实现。目前共整理出 28 个算法，按主题划分为 6 个类别：密码学、基础算法、哈密顿量模拟、线性代数、量子机器学习、Schrodingerization 方程求解。
+
+## 下载
+
+本算法库运行依赖于 UnitaryLab 量子模拟器软件包，可通过pip下载
+```bash
+pip install unitarylab
+```
+
+通过pip下载本算法库
+```bash
+pip install unitarylab_algorithms
+```
+
+## 当前算法清单
+
+### 1. cryptology
+
+- `discrete_log`: Discrete Log Algorithm
+- `shor`: Shor Algorithm
+- `simon`: Simon Algorithm
+
+### 2. fundamental_algorithm
+
+- `hadamard_transform`: Hadamard Transform Algorithm
+- `hadamard_test`: Hadamard Test Algorithm
+- `amplitude_amplification`: Amplitude Amplification Algorithm
+- `amplitude_estimation`: Amplitude Estimation Algorithm
+- `grover`: Grover Algorithm
+- `qpe`: Quantum Phase Estimation Algorithm
+
+### 3. hamiltonian_simulation
+
+- `trotter`: Trotter Algorithm
+- `qdrift`: QDrift Algorithm
+- `taylor`: Taylor Algorithm
+- `qsp`: Quantum Signal Processing for Hamiltonian Simulation
+- `cartan`: Cartan Decomposition Algorithm
+
+### 4. linear_algebra
+
+- `hhl`: HHL Algorithm
+- `lcu`: LCU Algorithm
+- `qft`: Quantum Fourier Transform Algorithm
+- `qsp`: Quantum Signal Processing Algorithm
+- `qsvt_qlsa`: QSVT Linear Solver Algorithm
+- `vqls`: VQLS Algorithm
+
+### 5. quantum_machine_learning
+
+- `vqe`: Variational Quantum Eigensolver
+- `qaoa`: Quantum Approximate Optimization Algorithm
+- `qcbm`: Quantum Circuit Born Machine
+- `vqc`: Variational Quantum Classifier
+- `cvqnn`: Continuous-Variable Quantum Neural Network
+
+### 6. schrodingerization
+
+- `equation_heat`: Heat Equation Algorithm
+- `equation_heat2d`: Heat2D Equation Algorithm
+- `equation_advection`: Advection Equation Algorithm
+

unitarylab_algorithms-1.0.0/README.md

@@ -0,0 +1,64 @@
+# unitarylab_algorithms
+
+本 [算法库](https://github.com/unitarylab/unitarylab_algorithms) 由 [UntiaryLab](https://unitarylab.com/) 整理开发实现，包含可独立调用的量子算法实现。目前共整理出 28 个算法，按主题划分为 6 个类别：密码学、基础算法、哈密顿量模拟、线性代数、量子机器学习、Schrodingerization 方程求解。
+
+## 下载
+
+本算法库运行依赖于 UnitaryLab 量子模拟器软件包，可通过pip下载
+```bash
+pip install unitarylab
+```
+
+通过pip下载本算法库
+```bash
+pip install unitarylab_algorithms
+```
+
+## 当前算法清单
+
+### 1. cryptology
+
+- `discrete_log`: Discrete Log Algorithm
+- `shor`: Shor Algorithm
+- `simon`: Simon Algorithm
+
+### 2. fundamental_algorithm
+
+- `hadamard_transform`: Hadamard Transform Algorithm
+- `hadamard_test`: Hadamard Test Algorithm
+- `amplitude_amplification`: Amplitude Amplification Algorithm
+- `amplitude_estimation`: Amplitude Estimation Algorithm
+- `grover`: Grover Algorithm
+- `qpe`: Quantum Phase Estimation Algorithm
+
+### 3. hamiltonian_simulation
+
+- `trotter`: Trotter Algorithm
+- `qdrift`: QDrift Algorithm
+- `taylor`: Taylor Algorithm
+- `qsp`: Quantum Signal Processing for Hamiltonian Simulation
+- `cartan`: Cartan Decomposition Algorithm
+
+### 4. linear_algebra
+
+- `hhl`: HHL Algorithm
+- `lcu`: LCU Algorithm
+- `qft`: Quantum Fourier Transform Algorithm
+- `qsp`: Quantum Signal Processing Algorithm
+- `qsvt_qlsa`: QSVT Linear Solver Algorithm
+- `vqls`: VQLS Algorithm
+
+### 5. quantum_machine_learning
+
+- `vqe`: Variational Quantum Eigensolver
+- `qaoa`: Quantum Approximate Optimization Algorithm
+- `qcbm`: Quantum Circuit Born Machine
+- `vqc`: Variational Quantum Classifier
+- `cvqnn`: Continuous-Variable Quantum Neural Network
+
+### 6. schrodingerization
+
+- `equation_heat`: Heat Equation Algorithm
+- `equation_heat2d`: Heat2D Equation Algorithm
+- `equation_advection`: Advection Equation Algorithm
+

unitarylab_algorithms-1.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unitarylab_algorithms"
+version = "1.0.0"
+description = "A Python package for quantum algorithms from UnitaryLab."
+readme = "README.md"
+requires-python = ">=3.10, <3.13"
+authors = [
+    { name = "UnitaryLab" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+
+dependencies = [
+    "numpy",
+    "scipy",
+    "torch",
+    "matplotlib",
+    "scikit-learn",
+    "mpmath",
+]
+
+[tool.setuptools]
+include-package-data = false
+zip-safe = false
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = [
+    "unitarylab_algorithms",
+    "unitarylab_algorithms.*",
+]
+
+[tool.setuptools.package-data]
+unitarylab_algorithms = [
+    "**/*.json",
+    "**/*.md",
+]

unitarylab_algorithms-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unitarylab_algorithms-1.0.0/unitarylab_algorithms/__init__.py

@@ -0,0 +1,79 @@
+"""
+Quantum Algorithms
+=========================
+
+This module provides quantum algorithms including:
+- Cryptology algorithms
+    - Discrete Logarithm Algorithm
+    - Shor's Algorithm
+    - Simon's Algorithm
+- Fundamental algorithms
+    - Hadamard Test Algorithm
+    - Hadamard Transform Algorithm
+    - Grover's Algorithm
+    - Amplitude Amplification Algorithm
+    - Amplitude Estimation Algorithm
+    - Quantum Phase Estimation Algorithm
+- Linear Algebra algorithms
+    - HHL Algorithm
+    - LCU Algorithm
+    - QFT Algorithm
+    - QSP Algorithm
+    - QSVT(QLSA) Algorithm
+    - VQLS Algorithm
+- Hamiltonian Simulation algorithms
+    - Trotter Algorithm
+    - QDRIFT Algorithm
+    - Taylor Series Algorithm
+    - QSP Algorithm
+- Quantum Machine Learning algorithms
+    - VQE Algorithm
+    - QAOA Algorithm
+    - QCBM Algorithm
+    - VQC Algorithm
+    - CVQNN Algorithm
+"""
+
+from .cryptology import *
+from .fundamental_algorithm import *
+from .linear_algebra import *
+from .hamiltonian_simulation import *
+from .quantum_machine_learning import *
+from .schrodingerization import *
+
+__all__ = [
+    "DiscreteLogAlgorithm",
+    "ShorAlgorithm",
+    "SimonAlgorithm",
+
+    "HadamardTransformAlgorithm",
+    "HadamardTestAlgorithm",
+    "AmplitudeAmplificationAlgorithm",
+    "AmplitudeEstimationAlgorithm",
+    "GroverAlgorithm",
+    "QPEAlgorithm",
+
+    "TrotterAlgorithm",
+    "QDriftAlgorithm",
+    "TaylorAlgorithm",
+    "QSPHSAlgorithm",
+    "CartanDecompositionAlgorithm",
+
+    "HHLAlgorithm",
+    "LCUAlgorithm",
+    "QFTAlgorithm",
+    "QSPAlgorithm",
+    "QSVTLinearSolverAlgorithm",
+    "VQLSAlgorithm",
+
+    "VQEAlgorithm",
+    "QAOAAlgorithm",
+    "CVQNNAlgorithm",
+    "QCBMAlgorithm",
+    "VQCAlgorithm",
+
+    "HeatEquationAlgorithm",
+    "AdvectionEquationAlgorithm",
+    "Heat2dEquationAlgorithm",
+]
+

unitarylab_algorithms-1.0.0/unitarylab_algorithms/algo_base.py

@@ -0,0 +1,129 @@
+from typing import Any, Dict, List, Optional
+import os
+
+
+class BaseAlgorithm:
+    """Shared base class for algorithm result/log formatting."""
+
+    def __init__(self, name: str, prefix: str = "", text_mode: str = "plain", algo_dir: Optional[str] = None):
+        self.name = self.__class__.__name__ if name == "" else name
+        self.prefix = self.name[:3].upper() if prefix == "" else prefix
+        self.prefix = '[' + self.prefix + ']' if not self.prefix.startswith('[') else self.prefix
+
+        self.text_mode = text_mode
+        self.algo_dir = algo_dir
+        self.status = ""
+        self.input: Dict[str, Any] = {}
+        self.output: Dict[str, Any] = {}
+        self.info: list = []
+        self.summary: str = ""
+
+    def run(self, *args, **kwargs) -> Dict[str, Any]:
+        """Run the algorithm with given parameters. To be implemented by subclasses."""
+        raise NotImplementedError("Subclasses must implement the run() method.")
+    
+    def _auxiliary_method(self, *args, **kwargs) -> Any:
+        """An example auxiliary method that can be used by subclasses."""
+        pass
+
+    def log(self, message) -> None:
+        """Print a message and save it into info logs."""
+        if isinstance(message, str):
+            msg = self.prefix + ": " + message
+            print(msg)
+            self.info.append(message)
+        elif isinstance(message, dict):
+            for key, value in message.items():
+                msg = f"        - {key} = {value}"
+                print(msg)
+
+    def update_input(self, input_dict: Dict[str, Any]) -> None:
+        """Update the input parameters dictionary."""
+        self.input.update(input_dict)
+        print(f"{self.prefix}: Starting {self.name}")
+        print(f"{self.prefix}: Input parameters: ")
+        self.log(self.input)
+
+    def update_output(self, output_dict: Dict[str, Any]) -> None:
+        """Update the output information dictionary."""
+        self.output.update(output_dict)
+        print(f"{self.prefix}: Output information: ")
+        self.log(self.output)
+
+    def save_circuit(self, circuit, name=None) -> str:
+        """Save the circuit into a file."""
+        if name is None:
+            filename = f"{self.name.replace(' ', '_').lower()}_circuit.svg"
+        else:
+            filename = f"{name}.svg"
+        
+        filepath = f"{self.algo_dir}/{filename}"
+        circuit.draw(filename=filepath, title=f"{self.name} Circuit")
+        self.log(f"  Circuit diagram saved: {filepath}")
+        return filepath
+
+    def save_txt(self) -> None:
+        """Save the algorithm result into a file."""
+        filename = f"{self.name.replace(' ', '_').lower()}_result.txt"
+        filepath = f"{self.algo_dir}/{filename}"
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(self.format_result_ascii())
+        self.log(f"  Result saved: {filepath}")
+        return filename
+
+    def _build_return_dict(self, success: bool, circuit_path, filepath, circuit=None) -> Dict[str, Any]:
+        """Build a dictionary containing all relevant information for returning."""
+        success = 'ok' if success else 'failed'
+        if isinstance(filepath, str):
+            filepath = [filepath]
+        files = []
+        for filename in filepath:
+            files.append({"format": filename[-3:], "filename": filename})
+        
+        result = {"status": success, "circuit_path": circuit_path, "plot": files, "circuit": circuit}
+        return result.update(self.output) or result
+
+    def format_result_ascii(self) -> str:
+        """Format the most recent algorithm result as text output."""
+        result = ""
+        # Algorithm start
+        if self.text_mode == "plain":
+            result += '\n' + f'{"=" * 25}\n{self.name} Algorithm Result\n{"=" * 25}\n'
+        elif self.text_mode == "legacy":
+            result += '=' * 70 + '\n' + f"{' ' * 10}⚛️ {self.name} Algorithm Result ⚛️\n" + '=' * 70 + '\n'
+
+        # Solve status
+        if self.text_mode == "plain":
+            result += f"Status: {self.status}\n\n"
+        elif self.text_mode == "legacy":
+            result += f"📊 Status: {self.status}\n\n"
+
+        # Input parameters
+        if self.text_mode == "plain":
+            result += "Input parameters:\n"
+        elif self.text_mode == "legacy":
+            result += "-" * 70 + '\n' + "📥 Input parameters:\n" + "-" * 70 + "\n"
+        result += "\n".join([f"  - {key}: {value}" for key, value in self.input.items()]) + "\n\n"
+
+        # Runtime logs
+        if self.text_mode == "plain":
+            result += "Runtime logs:\n"
+        elif self.text_mode == "legacy":
+            result += "-" * 70 + '\n' + "📝 Runtime logs:\n" + "-" * 70 + "\n"
+        result += "\n".join([f"  - {line}" for line in self.info]) + "\n\n"
+
+        # Output information
+        if self.text_mode == "plain":
+            result += "Output information:\n"
+        elif self.text_mode == "legacy":
+            result += "-" * 70 + '\n' + "📤 Output information:\n" + "-" * 70 + "\n"
+        result += "\n".join([f"  - {key}: {value}" for key, value in self.output.items()]) + "\n\n"
+
+        # Summary
+        if self.text_mode == "plain":
+            result += "Summary:\n"
+        elif self.text_mode == "legacy":
+            result += "-" * 70 + '\n' + "🔍 Summary:\n" + "-" * 70 + "\n"
+        result += f"  {self.summary}\n"
+
+        return result

unitarylab_algorithms-1.0.0/unitarylab_algorithms/cryptology/__init__.py

@@ -0,0 +1,17 @@
+"""
+Quantum Cryptology Algorithm
+=========================
+
+This module provides quantum algorithms including:
+- dlg: Discrete Logarithm Problem (DLP) algorithm
+"""
+
+from .discrete_log import DiscreteLogAlgorithm
+from .shor import ShorAlgorithm
+from .simon import SimonAlgorithm
+
+__all__ = [
+    "DiscreteLogAlgorithm",
+    "ShorAlgorithm",
+    "SimonAlgorithm",
+]

unitarylab_algorithms-1.0.0/unitarylab_algorithms/cryptology/discrete_log/README_en.md

@@ -0,0 +1,104 @@
+# Discrete Logarithm Algorithm Explained
+
+## Parameter Settings
+
+- `g`: Base, default value is `3`.
+- `y`: Target value, default value is `13`.
+- `P`: Modulus (typically a prime number), default value is `17`.
+
+> **Summary**: The discrete logarithm algorithm is used to find the unknown $x$ in $g^x \equiv y \pmod P$ in polynomial time. Given the inputs $g$, $y$, and $P$, it encodes the period information using Quantum Phase Estimation, combines classical continued fractions with modular arithmetic techniques, and ultimately outputs the computed discrete logarithm $x$.
+
+---
+
+## Table of Contents
+
+- [Execution Flow](#execution-flow)
+- [Core Idea](#core-idea)
+- [Mathematical Principles](#mathematical-principles)
+- [Algorithm Steps](#algorithm-steps)
+- [Quantum Advantage](#quantum-advantage)
+- [Complexity Analysis](#complexity-analysis)
+- [Applications and Impact](#applications-and-impact)
+
+---
+
+## Execution Flow
+
+1. **Parameter Preparation**:
+   - Verify that $g$ and $y$ must be coprime with $P$.
+   - Based on the bit length of $P$, calculate the count register size $n_{\text{count}}$ and work register size $n_{\text{work}}$ (a total of $2n_{\text{count}} + n_{\text{work}}$ qubits).
+2. **Quantum Circuit Construction**:
+   - Initialize two control (count) registers (corresponding to the powers of $g$ and $y^{-1}$) and one work register.
+   - Apply a Hadamard layer to the control registers to prepare a uniform superposition state.
+   - Initialize the work register to $|1\rangle$.
+   - For the first control register, apply controlled modular multiplication operators with multipliers $g^{2^i}$ (simulated by matrices).
+   - For the second control register, apply controlled modular multiplication operators with multipliers $(y^{-1})^{2^j}$ where $y^{-1}$ is the inverse in $\pmod P$ (simulated by matrices).
+   - Apply the **Inverse Quantum Fourier Transform (IQFT)** to both control registers.
+3. **Quantum Simulation and Measurement**:
+   - Execute the quantum circuit simulation.
+   - Extract the probability distribution of the respective quantum state components for further analysis.
+4. **Classical Post-processing (Continued Fractions & Congruences)**:
+   - Extract the most probable sets of observational values $(c_1, c_2)$ from the measured probability spectrum.
+   - Use classical continued fraction algorithms to analyze the ratio $c_1/N$ and extract the possible group order (period) $r$.
+   - Based on the extracted results for $x_1/r$ and $x_2/r$, formulate the linear modular equation $x \cdot x_1 + x_2 \equiv 0 \pmod r$ and solve for $x$.
+   - Verify if the result satisfies $g^x \equiv y \pmod P$.
+5. **Result Output**: Export the SVG chart of the quantum circuit, output the computation time, the detected period $r$, and the found result $x$.
+
+---
+
+## Core Idea
+
+To solve the discrete logarithm problem $g^x \equiv y \pmod P$ over a finite cyclic group, Peter Shor demonstrated that it could be reduced to a Hidden Subgroup Problem (a 2D period-finding problem).
+Define a function:
+$$f(a,b) = g^a y^{-b} \bmod P$$
+Evidently, if a pair $(a,b)$ is found such that $f(a,b) = 1$, since $y = g^x$, this implies:
+$$g^a (g^x)^{-b} = g^{a - bx} \equiv 1 \pmod P$$
+This equality holds when $a - bx \equiv 0 \pmod r$ (where $r$ is the multiplicative order of $g$). The unknown $x$ can then be classically computed using the modular inverse: $x = ab^{-1} \bmod r$. Thus, by locating the group's order and the function's implicit 2-dimensional period via quantum superposition and phase estimation, the variable $x$ can be successfully resolved.
+
+---
+
+## Mathematical Principles
+
+### Controlled Group Operations and Joint State
+Using two registers each of size $N$ to represent the superposition state $(a,b)$, the joint state represents:
+$$\frac{1}{N}\sum_{a=0}^{N-1}\sum_{b=0}^{N-1}|a\rangle|b\rangle|g^ay^{-b}\bmod P\rangle$$
+This implicitly computes and encapsulates the periodic information across a 2D grid defined by $x$.
+
+### Two-Dimensional Quantum Fourier Transform
+After applying two independent Quantum Fourier Transforms, the system's amplitudes will constructively interfere (forming peaks) around specific coordinate pairs $(c_1, c_2)$ satisfying:
+$$\frac{c_1}{N} \approx \frac{k}{r} \quad \text{and} \quad \frac{c_2}{N} \approx \frac{kx}{r}$$
+where $r$ is the period (the order of $g$ modulo $P$). By doing so, $r$ can be extracted from $c_1$, and subsequently $x$ can be derived by calculating $c_2/c_1 \approx x \pmod r$.
+
+---
+
+## Algorithm Steps
+
+1. **Classical Pre-check**: Check the coprime conditions and calculate the required sizes for the control and work registers.
+2. **State Preparation**: Prepare $|0\rangle^{\otimes 2n} |1\rangle$, then apply a Hadamard layer to obtain $|+\rangle^{\otimes 2n} |1\rangle$.
+3. **Quantum Period Mapping**: Apply the two-dimensional black-box controlled operator $U|a\rangle|b\rangle|z\rangle = |a\rangle|b\rangle|z \cdot g^a y^{-b} \bmod P\rangle$.
+4. **IQFT Phase Extraction**: Apply IQFT to the first two registers to concentrate the amplitudes toward $c_1, c_2$.
+5. **Classical Measurement and Parsing**: Extract the period and $x$ using the continued fractions theorem. Verify the answer via back substitution over the original congruence until success.
+
+---
+
+## Quantum Advantage
+
+| Task | Classical Complexity | Quantum Complexity (Shor DLP) |
+|------|-----------|----------------|
+| Solving Discrete Logarithm | Sub-exponential time (e.g., General Number Field Sieve) | $O((\log P)^3)$ |
+
+Note: Just as with prime factorization, Shor's treatment of the discrete logarithm problem achieved an exponential quantum speedup. This effectively undermines the foundation of traditional cryptographic systems like Diffie-Hellman and Elliptic Curves.
+
+---
+
+## Complexity Analysis
+
+- **Quantum Part**: $O(\log P)$ qubit footprint; polynomial grade $O((\log P)^3)$ quantum gate operations are required to establish the grid of controlled modular multiplications and IQFTs.
+- **Overall Computation Time**: Stemming from the high likelihood of sampling correct states and the efficiency of classical post-processing (finding large inverse numbers and continued fractions), the overall time complexity is $O((\log P)^3)$.
+
+---
+
+## Applications and Impact
+
+- **Breaking Public-Key Cryptography Foundations**: Beyond RSA (based on integer factorization), the security of modern cryptographic architectures—such as the Diffie-Hellman (DH) key exchange protocol, Digital Signature Algorithm (DSA), ElGamal, and Elliptic Curve Cryptography (ECC) variations—is constructed entirely on the intractability of the classical discrete logarithm problem, all of which fall to this algorithm model.
+- **Driving the Next-Generation Security Formats**: Because quantum algorithms can crack these protocols in polynomial time, this algorithm serves as a forceful catalyst, pushing the global computer industry toward Post-Quantum Cryptography (PQC), such as lattice-based and hash-based cryptography.

unitarylab_algorithms-1.0.0/unitarylab_algorithms/cryptology/discrete_log/README_zh.md

@@ -0,0 +1,104 @@
+# 离散对数算法详解
+
+## 参数设置
+
+- `g`: 底数 (Base)，默认值为 `3`。
+- `y`: 目标值 (Target value)，默认值为 `13`。
+- `P`: 模数 (Modulus，通常为素数)，默认值为 `17`。
+
+> **总结**：离散对数算法用于在多项式时间内求解 $g^x \equiv y \pmod P$ 中的未知数 $x$。输入底数 $g$、目标值 $y$ 和模数 $P$，通过量子相位估计编码周期信息，结合经典连分数与同余方程技术，最终输出计算得到的离散对数 $x$。
+
+---
+
+## 目录
+
+- [运行流程](#运行流程)
+- [核心思想](#核心思想)
+- [数学原理](#数学原理)
+- [算法步骤](#算法步骤)
+- [量子优势](#量子优势)
+- [复杂度分析](#复杂度分析)
+- [应用与影响](#应用与影响)
+
+---
+
+## 运行流程
+
+1. **参数制备**：
+   - 验证 $g$ 和 $y$ 必须与 $P$ 互素。
+   - 根据 $P$ 的位长，计算出计数寄存器位长 $n_{\text{count}}$ 和工作寄存器位长 $n_{\text{work}}$（总计耗费 $2n_{\text{count}} + n_{\text{work}}$ 个量子比特）。
+2. **量子电路构建**：
+   - 初始化两个控制（计数）寄存器（分别对应 $g$ 的幂次与 $y^{-1}$ 的幂次）和工作寄存器。
+   - 对控制寄存器施加 Hadamard 层制备均匀叠加态。
+   - 设置工作寄存器初始状态为 $|1\rangle$。
+   - 对第一个控制寄存器，依次施加以 $g^{2^i}$ 为乘数的受控模乘算子（矩阵模拟）。
+   - 对第二个控制寄存器，依次施加以 $y^{-1}$（在 $\pmod P$ 下的逆元）的对应幂次为乘数的受控模乘算子（矩阵模拟）。
+   - 对两个控制寄存器分别施加**逆量子傅里叶变换 (IQFT)**。
+3. **量子模拟与测量**：
+   - 执行量子电路模拟。
+   - 提取执行后各量子态分量的概率分布用于下一阶段分析。
+4. **经典后处理（连分数与同余方程）**：
+   - 从测得概率图谱中提取最可能的几组观测值 $(c_1, c_2)$。
+   - 运用经典连分数算法分析 $c_1/N$ 等比值，提取可能的群阶（周期）$r$。
+   - 根据 $x_1/r$ 和 $x_2/r$ 的提取结果构建模线性方程 $x \cdot x_1 + x_2 \equiv 0 \pmod r$，反解得到 $x$。
+   - 验证代入 $g^x \equiv y \pmod P$ 是否成立。
+5. **结果输出**：导出量子电路 SVG 图表，并输出计算耗时、检测到的周期 $r$ 及求得的结果 $x$。
+
+---
+
+## 核心思想
+
+求解有限循环群上的离散对数问题 $g^x \equiv y \pmod P$，Peter Shor 提出可以将其转化为一种隐子群问题（二维周期查找问题）。
+定义一个函数：
+$$f(a,b) = g^a y^{-b} \bmod P$$
+显然，如果找到了 $(a,b)$ 使得 $f(a,b) = 1$，由于 $y = g^x$，这意味着：
+$$g^a (g^x)^{-b} = g^{a - bx} \equiv 1 \pmod P$$
+当 $a - bx \equiv 0 \pmod r$（$r$ 为 $g$ 的阶）时等式成立，此时即可通过经典模逆元求出 $x = ab^{-1} \bmod r$。因此，通过量子叠加及相位估计来寻找群的阶与函数的隐式二维周期，便能解出变量 $x$。
+
+---
+
+## 数学原理
+
+### 受控群运算与联合态
+用两个大小分别为 $N$ 的寄存器表示叠加状态 $(a,b)$，其联合状态可表示为：
+$$\frac{1}{N}\sum_{a=0}^{N-1}\sum_{b=0}^{N-1}|a\rangle|b\rangle|g^ay^{-b}\bmod P\rangle$$
+此状态通过隐式计算封装了由 $x$ 建立的 $(a,b)$ 网格上的周期信息。
+
+### 二维量子傅里叶变换
+应用两次相互独立的量子傅里叶变换后，系统状态的振幅在满足如下条件的特定 $(c_1, c_2)$ 点会发生相长干涉（出现波峰）：
+$$\frac{c_1}{N} \approx \frac{k}{r} \quad \text{且} \quad \frac{c_2}{N} \approx \frac{kx}{r}$$
+其中 $r$ 为周期（$g$ 在 $\pmod P$ 的阶）。借由此可以分别从 $c_1$ 算出 $r$，再通过 $c_2/c_1 \approx x \pmod r$ 提取 $x$ 自身。
+
+---
+
+## 算法步骤
+
+1. **经典预检查**：判定参数互素条件，算出用于量子阶段的具体控制/工作寄存器尺寸。
+2. **状态制备**：制备 $|0\rangle^{\otimes 2n} |1\rangle$，然后施加 Hadamard 层得到 $|+\rangle^{\otimes 2n} |1\rangle$。
+3. **量子周期映射**：施加二维黑盒控制算子 $U|a\rangle|b\rangle|z\rangle = |a\rangle|b\rangle|z \cdot g^a y^{-b} \bmod P\rangle$。
+4. **傅里叶逆变换提取相位**：对前两个寄存器施加 IQFT，将振幅集中指向 $c_1, c_2$ 附近。
+5. **经典测量与解析**：测量第一个和第二个寄存器，用连分数定理提取周期并求取 $x$。通过同余反代校验直至结果正确。
+
+---
+
+## 量子优势
+
+| 任务 | 经典复杂度 | 量子复杂度 (Shor DLP) |
+|------|-----------|----------------|
+| 离散对数求解 | 次指数时间（通用数域筛法 GNFS 等） | $O((\log P)^3)$ |
+
+注：与对于单纯的素数分解算法相同，Shor 针对离散对数的问题同样取得了指数量级的算法加速，使得传统的 Diffie-Hellman 与椭圆曲线等密码体系变得脆弱。
+
+---
+
+## 复杂度分析
+
+- **量子部分**：$O(\log P)$ 的比特开销，多项式级 $O((\log P)^3)$ 量子门操作以实现受控模乘累加运算与 IQFT 网格。
+- **整体计算时间**：由于测量结果高频命中以及只需要常规的经典后处理（大数求逆和连分数），预期整体时间复杂度同为 $O((\log P)^3)$。
+
+---
+
+## 应用与影响
+
+- **打破公钥密码体系基础**：除了基于素数分解的 RSA；现代诸多密码协议如 Diffie-Hellman (DH) 密钥交换协议、数字签名标准 (DSA)、ElGamal 算法以及基于椭圆曲线 (ECC) 的等价方案，其安全性统统奠立于经典离散对数问题的难解性之上，均可被该算法模型所攻破。
+- **推动新一代安全策略**：因为量子技术能以多项式时间降维打击这些协议，此算法强力助推了全球计算机产业向后量子密码学 (PQC) 如格密码、哈希密码过渡的浪潮。

unitarylab_algorithms-1.0.0/unitarylab_algorithms/cryptology/discrete_log/__init__.py

@@ -0,0 +1,13 @@
+"""
+discrete log  Algorithm Module
+========================
+
+Implementation of Simon's algorithm for finding hidden periods.
+"""
+
+from .algorithm import DiscreteLogAlgorithm, test
+
+__all__ = [
+    'DiscreteLogAlgorithm',
+    'test'
+]