---

English

What is unitarylab?

Unitarylab is the Python quantum simulator SDK developed by UnitaryLab. 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 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

pip install unitarylab

CPU-only installation (optional)

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

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

Verify the installation:

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.

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>:

{'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:

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:

# 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:

import numpy as np

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

Draw and Analyze Circuits

# 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:

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:

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

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:

from unitarylab import Circuit

Further Documentation

• UnitaryLab Website
• Simulator User Manual
• UnitaryLab Algorithms on PyPI

---

中文

unitarylab 是什么？

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

该模拟器适合量子计算教学、算法原型开发、科研实验，以及与 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 和哈密顿量模拟等高层模块。

安装

pip install unitarylab

仅使用 CPU（可选）

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

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

验证安装：

import unitarylab
print(unitarylab.__version__)

快速开始：Bell 态

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

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%：

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

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

测量与经典寄存器

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

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 参数：

# 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')

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

import numpy as np

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

电路绘图与分析

# 显示电路图，支持 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() 可用于在运行较大规模实验前检查门数量、电路深度和层结构。

电路变换

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

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 电路并将其嵌入更大电路的示例：

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')

包结构

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

大多数用户只需要导入：

from unitarylab import Circuit

更多文档

• UnitaryLab 官方网站
• Simulator 用户手册
• UnitaryLab Algorithms（PyPI）

License

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