Metadata-Version: 2.4
Name: unitarylab
Version: 1.1.6
Summary: A Python package for quantum simulator from UnitaryLab.
Author: UnitaryLab
License-Expression: LicenseRef-UnitaryLab-LICENSE
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.zh-CN
License-File: LICENSE.en
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: torch
Requires-Dist: matplotlib
Requires-Dist: pylatexenc
Requires-Dist: scikit-learn
Requires-Dist: sympy
Requires-Dist: mpmath
Dynamic: license-file

<div align="center">

<h1>unitarylab</h1>

<p>
  <strong>A Python quantum circuit simulator for building, executing, analyzing, and exporting quantum circuits.</strong><br/>
  <strong>面向量子电路构建、执行、分析与导出的 Python 量子模拟器。</strong>
</p>

<p>
  <img src="https://img.shields.io/badge/Python-3.10%20%7C%203.11%20%7C%203.12-3b82f6?style=flat-square&logo=python&logoColor=white" alt="Python 3.10, 3.11, and 3.12"/>
  <img src="https://img.shields.io/badge/Backend-NumPy%20%7C%20PyTorch%20%7C%20C%2B%2B-7c3aed?style=flat-square" alt="NumPy, PyTorch, and C++ backends"/>
  <img src="https://img.shields.io/badge/Interface-Circuit-f59e0b?style=flat-square" alt="Circuit interface"/>
  <img src="https://img.shields.io/badge/License-UnitaryLab-22c55e?style=flat-square" alt="UnitaryLab license"/>
</p>

<p>
  <a href="#english">English</a>
  &middot;
  <a href="#chinese">中文</a>
</p>

</div>

---

<a name="english"></a>

## English

### What is unitarylab?

**Unitarylab** is the Python quantum simulator SDK developed by [UnitaryLab](https://unitarylab.com/). It provides a high-level `Circuit` interface backed by statevector execution, so you can move from circuit construction to simulation results and circuit inspection in a single workflow.

It is suitable for quantum-computing education, algorithm prototyping, research experiments, and integrating the [UnitaryLab Algorithms](https://pypi.org/project/unitarylab-algorithms/) library.

### Key Features

- **Simple circuit construction** — Build circuits with `Circuit`, `Register`, and `ClassicalRegister`.
- **Rich gate operations** — Use single-qubit, rotation, controlled, multi-controlled, SWAP, and custom unitary gates.
- **Statevector execution** — Inspect the final statevector, basis-state probabilities, and measurement results.
- **Flexible backends** — Execute with NumPy, PyTorch or C++ on CPU; use PyTorch with CUDA-capable GPU environments when available.
- **Circuit inspection** — Visulize circuits using Matplotlib, text, or LaTeX, and analyze gate counts, circuit depth, and layer structure.
- **Circuit transformations** — Copy, invert, append, compose, and decompose circuits without changing the original circuit.
- **Interoperability** — Import and export circuits through OpenQASM 3.0 utilities.
- **Algorithm-ready foundation** — Use high-level modules such as QFT, QPE, LCU, HHL, QSP, QSVT, and Hamiltonian simulation.

### Installation

```bash
pip install unitarylab
```

#### CPU-only installation (optional)

If you do not need GPU acceleration, install the CPU-only build of PyTorch before installing `unitarylab`:

```bash
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install unitarylab
```

Verify the installation:

```python
import unitarylab

print(unitarylab.__version__)
```


### Quick Start: Bell State

The following example creates a two-qubit Bell state, executes it, and reads its statevector and probabilities.

```python
from unitarylab import Circuit

# Create a 2-qubit circuit
qc = Circuit(2)

# Prepare (|00> + |11>) / sqrt(2)
qc.h(0)
qc.cx(0, 1)

# Execute the circuit
result = qc.execute()

print(result.state)
print(result.probabilities)
```

The probability distribution contains approximately 50% for `|00>` and 50% for `|11>`:

```python
{'00': 0.5, '11': 0.5}
```

`probabilities` uses binary computational-basis strings as keys. The simulator follows a little-endian qubit-ordering convention; keep this in mind when interpreting multi-qubit results.

### Measurements and Classical Registers

Create a classical register when you need classical measurement outcomes:

```python
from unitarylab import Circuit, Register，ClassicalRegister

qr = Register('q', 2)
cr = ClassicalRegister('c', 2)
qc = Circuit(qr, cr)

qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

result = qc.execute()
print(result.classical_results_map)
```

For this Bell-state circuit, the two measured bits agree on every run: the result is either `00` or `11`.

### Execution Backends

`execute()` accepts `backend`, `device`, and `dtype` options:

```python
# PyTorch backend on CPU (default backend)
result = qc.execute(backend='torch', device='cpu')

# NumPy backend on CPU
result = qc.execute(backend='numpy', device='cpu')

# C++ backend on CPU
result = qc.execute(backend='cpp', device='cpu')

# PyTorch backend on GPU (requires a suitable PyTorch/CUDA environment)
result = qc.execute(backend='torch', device='gpu')
```

For precision-sensitive workloads, a dtype can also be supplied:

```python
import numpy as np

result = qc.execute(backend='torch', device='cpu', dtype=np.complex128)
```

### Draw and Analyze Circuits

```python
# Display the circuit diagram. Matplotlib is the default output format.
# Text and LaTeX formats are also supported.
qc.draw()
# qc.draw(output="text")
# qc.draw(output="latex")

# Save the Matplotlib circuit diagram
qc.draw(filename="bell-state.png", title="Bell State")

# Analyze the circuit structure
info = qc.analyze()
info.show()

# Get the matrix representation of a small-scale circuit
matrix = qc.get_matrix()
```

`analyze()` is useful for checking gate counts, circuit depth, and layer structure before running larger experiments.

### Circuit Transformations

Circuit transformations return new circuit objects and leave the source circuit unchanged:

```python
qc = Circuit(2)
qc.h(0)
qc.cx(0, 1)

copied = qc.copy()
inverse = qc.inverse()
dagger = qc.dagger()
```

Circuits can also be appended or composed to build larger workflows from reusable circuit blocks.

### Algorithm and Utility Library

The simulator provides high-level algorithm components through `unitarylab.library`:

| Area | Public interfaces |
|------|-------------------|
| Quantum Fourier transform | `QFT`, `IQFT` |
| Quantum phase estimation | `QPE` |
| Linear combination of unitaries | `LCU` |
| Hamiltonian simulation | `hamiltonian_simulation`, `QSP_hamiltonian_simulation` |
| Quantum signal processing | `QSP` |
| Quantum singular value transformation | `QSVT` |
| Block encoding | `block_encode` |
| Linear-system solving | `solve` |

These interfaces are the public algorithm API of the simulator. Internal implementation modules and private module names are not part of the documented API and may change between releases.

Example: construct a QFT circuit and embed it into a larger circuit:

```python
from unitarylab import Circuit
from unitarylab.library import QFT

qft = QFT(n=4)
qc = Circuit(4)
qc.append(qft, target=[0, 1, 2, 3])
qc.draw(title='Quantum Fourier Transform')
```

### Package Structure

```text
unitarylab/
├── core/               # Circuit, Register, and ClassicalRegister
├── backend/            # Quantum gates, gate sequences, execution, and QASM
├── circuit_analysis/   # Circuit structure analysis
├── drawer/             # Circuit drawing and text/LaTeX output
├── info/               # Information display utilities
├── codegen/             # Circuit code generation
├── transpiler/          # Circuit transformation and optimization
└── library/             # Public algorithm interfaces
```

Most users only need:

```python
from unitarylab import Circuit
```

### Further Documentation

- [UnitaryLab Website](https://unitarylab.com/)
- [Simulator User Manual](https://docs.unitarylab.com/en/docs/unitarylab-simulator-user-manual/)
- [UnitaryLab Algorithms on PyPI](https://pypi.org/project/unitarylab-algorithms/)

---

<a name="chinese"></a>

## 中文

### unitarylab 是什么？

**unitarylab** 是由 [UnitaryLab](https://unitarylab.com/) 开发的 Python 量子模拟器 SDK。它以高层 `Circuit` 接口为核心，提供基于状态向量的量子电路执行能力，帮助用户在同一套工作流中完成电路构建、模拟运行、结果读取和结构分析。

该模拟器适合量子计算教学、算法原型开发、科研实验，以及与 [UnitaryLab Algorithms](https://pypi.org/project/unitarylab-algorithms/) 算法库配合使用。

### 核心特性

- **简洁的电路构建接口** — 使用 `Circuit`、`Register` 和 `ClassicalRegister` 创建量子电路。
- **丰富的量子门操作** — 支持单量子比特门、旋转门、受控门、多重受控门、SWAP 门和自定义酉门。
- **状态向量模拟** — 获取最终状态向量、计算基概率分布和测量结果。
- **灵活的执行后端** — 支持 NumPy、 PyTorch 以及 C++ 在 CPU 执行，并可在合适的 CUDA 环境下使用 PyTorch GPU 加速。
- **电路可视化与分析** — 使用 Matplotlib、文本或 LaTeX 可视化电路，并分析门数、电路深度和层结构。
- **电路变换** — 支持复制、求逆、追加、组合和分解电路，原始电路不会被修改。
- **OpenQASM 互操作** — 通过 OpenQASM 3.0 工具导入和导出电路。
- **算法库基础设施** — 提供 QFT、QPE、LCU、HHL、QSP、QSVT 和哈密顿量模拟等高层模块。

### 安装

```bash
pip install unitarylab
```

#### 仅使用 CPU（可选）

如果不需要 GPU 加速，可先安装 PyTorch 的 CPU 版本，再安装 `unitarylab`：

```bash
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install unitarylab
```

验证安装：

```python
import unitarylab
print(unitarylab.__version__)
```

### 快速开始：Bell 态

下面的示例创建一个两量子比特 Bell 态，执行电路并读取状态向量与概率分布。

```python
from unitarylab import Circuit

# 创建两量子比特电路
qc = Circuit(2)

# 制备 (|00> + |11>) / sqrt(2)
qc.h(0)
qc.cx(0, 1)

# 执行电路
result = qc.execute()
print(result.state)
print(result.probabilities)
```

运行结果中，`|00>` 和 `|11>` 的概率约各为 50%：

```python
{'00': 0.5, '11': 0.5}
```

`probabilities` 使用计算基二进制字符串作为键；解释多量子比特结果时，请注意模拟器采用 little-endian 的量子比特顺序约定。

### 测量与经典寄存器

如果需要读取经典测量结果，应先创建经典寄存器：

```python
from unitarylab import Circuit, Register，ClassicalRegister


qr = Register('q', 2)
cr = ClassicalRegister('c', 2)
qc = Circuit(qr, cr)

qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

result = qc.execute()
print(result.classical_results_map)
```

对于这个 Bell 态电路，两个测量比特在每次运行中都会保持一致，结果只能是 `00` 或 `11`。

### 执行后端

`execute()` 支持 `backend`、`device` 和 `dtype` 参数：

```python
# PyTorch CPU 后端（默认后端）
result = qc.execute(backend='torch', device='cpu')

# NumPy CPU 后端
result = qc.execute(backend='numpy', device='cpu')

# C++ CPU 后端
result = qc.execute(backend='cpp', device='cpu')

# PyTorch GPU 后端（需要合适的 PyTorch/CUDA 环境）
result = qc.execute(backend='torch', device='gpu')
```

对于对精度敏感的任务，也可以指定数据类型：

```python
import numpy as np

result = qc.execute(backend='torch', device='cpu', dtype=np.complex128)
```

### 电路绘图与分析

```python
# 显示电路图，支持 Matplotlib(默认)、文本格式和 LaTeX 
qc.draw()
# qc.draw(output=“text”)
# qc.draw(output“Latex”)

# 保存 Matplotlib 电路图
qc.draw(filename='bell-state.png', title='Bell State')

# 分析电路结构
info = qc.analyze()
info.show()

# 获取小规模电路的矩阵
matrix = qc.get_matrix()
```

`analyze()` 可用于在运行较大规模实验前检查门数量、电路深度和层结构。

### 电路变换

电路变换会返回新的电路对象，不会修改源电路：

```python
qc = Circuit(2)
qc.h(0)
qc.cx(0, 1)

copied = qc.copy()
inverse = qc.inverse()
dagger = qc.dagger()  
```

还可以通过追加或组合电路，将可复用的电路模块构建成更大的工作流。

### 算法与工具库

模拟器通过 `unitarylab.library` 提供高层算法构件：

| 方向 | 公开接口 |
|------|----------|
| 量子傅里叶变换 | `QFT`、`IQFT` |
| 量子相位估计 | `QPE` |
| 线性组合酉算子 | `LCU` |
| 哈密顿量模拟 | `hamiltonian_simulation`、`QSP_hamiltonian_simulation` |
| 量子信号处理 | `QSP` |
| 量子奇异值变换 | `QSVT` |
| 块编码 | `block_encode` |
| 线性方程组求解 | `solve` |

以上接口构成模拟器公开的算法 API。内部实现模块和私有模块名称不属于文档化 API，后续版本中可能发生变化。

下面是构造 QFT 电路并将其嵌入更大电路的示例：

```python
from unitarylab import Circuit
from unitarylab.library import QFT

qft = QFT(n=4)
qc = Circuit(4)
qc.append(qft, target=[0, 1, 2, 3])
qc.draw(title='Quantum Fourier Transform')
```

### 包结构

```text
unitarylab/
├── core/               # Circuit、Register 和 ClassicalRegister
├── backend/            # 量子门、门序列、执行与 QASM 支持
├── circuit_analysis/   # 电路结构分析
├── drawer/             # 电路绘图及文本/LaTeX 输出
├── info/               # 信息展示工具
├── codegen/            # 电路代码生成
├── transpiler/         # 电路转换与优化
└── library/            # 公开算法接口
```

大多数用户只需要导入：

```python
from unitarylab import Circuit
```

### 更多文档

- [UnitaryLab 官方网站](https://unitarylab.com/)
- [Simulator 用户手册](https://docs.unitarylab.com/zh/docs/unitarylab-simulator-user-manual/)
- [UnitaryLab Algorithms（PyPI）](https://pypi.org/project/unitarylab-algorithms/)

# License

License: LicenseRef-UnitaryLab-LICENSE. 
The Chinese license text is authoritative; the English version is provided for reference only.
