English

UnitaryLab provides a high-level Circuit API for quantum-circuit construction, simulation, analysis, visualization, interoperability, and hardware compilation. It supports dense statevectors, matrix-product states, and density matrices.

Website · Simulator User Manual · 中文

Installation

UnitaryLab requires Python 3.10–3.12.

pip install unitarylab

Optional components can be installed as needed:

# CUDA 12 C++ backend
pip install "unitarylab[cuda]"

# Quantum chemistry workflows
pip install "unitarylab[chemistry]"

The main package supports Windows, Linux, and macOS. The CUDA extra supports Linux x86_64, Linux aarch64 server environments, and Windows x86-64, and requires a compatible NVIDIA driver. The chemistry extension currently supports Linux and macOS.

Bell-state quick start

from unitarylab import Circuit

circuit = Circuit(2)
circuit.h(0)
circuit.cx(0, 1)

result = circuit.execute()
print(result.probabilities)

The probability mapping contains every computational basis state:

{"00": 0.5, "10": 0.0, "01": 0.0, "11": 0.5}

Displayed bit strings use little-endian qubit order: qubit 0 is the rightmost bit.

Core capabilities

Common workflow

Create a circuit, add measurements when classical results are needed, and choose the number of independent execution shots:

from unitarylab import Circuit, Register, ClassicalRegister

q = Register("q", 2)
c = ClassicalRegister("c", 2)
circuit = Circuit(q, c)

circuit.h(q[0])
circuit.cx(q[0], q[1])
circuit.measure(q[0:2], c[0:2])

result = circuit.execute(shots=1000, seed=42)
print(result.counts)
print(result.classical_results_map)
print(result.classical_registers)

• counts aggregates classical bit strings from all shots.
• classical_results_map contains classical-bit values from the final shot.
• classical_registers groups final-shot values by register name.
• state is the dense final-shot state; backend_state exposes the native backend representation.

For state inspection without circuit measurements, execution results also provide targeted probability queries, marginal distributions, non-collapsing sampling, projective measurement, and normalized observable expectation values.

result = Circuit(1).execute()

print(result.probability("0"))
print(result.sample(shots=8, seed=7))
print(result.expectation("Z"))

Pauli-string characters correspond to the supplied qubits in order. This operator order is separate from displayed probability strings, where qubit 0 appears at the right-hand end.

Backend compatibility

Choosing a backend

• Start with the default torch CPU backend when broad compatibility and a ready-to-use environment matter most.
• Prefer cpp with device="cpu" when execution speed is the priority and the native extension is available.
• Prefer cpp with device="gpu" for the highest-performance supported CUDA path; install unitarylab[cuda] and use a compatible NVIDIA driver.
• Use numpy when a NumPy-native dense state or minimal backend integration is more important.
• Use tensornet for larger, low-entanglement circuits where an MPS representation can avoid a full dense statevector.
• Use execute_density() for mixed states and noise models. Density-matrix execution does not currently provide circuit measurement or shots/counts.

Backend selection is explicit when needed:

result = circuit.execute(backend="numpy", device="cpu")
result = circuit.execute(backend="tensornet", device="cpu")
density_result = circuit.execute_density(device="cpu")

Circuit analysis and quantum computer task submission

The high-level API includes circuit drawing and analysis, structural circuit operations, local optimization and transpilation, OpenQASM 2/3 import and export, compilation, and provider-neutral hardware submission.

circuit.draw()
info = circuit.analyze(show=False)

optimized = circuit.optimize(optimization_level=1)
transpiled = circuit.transpile(basis="default")
qasm = circuit.to_qasm()

Real-hardware submission requires provider API token and may require a machine identifier or vendor SDK:

TOKEN = "your-provider-token"

hardware_result = circuit.submit(
    provider="guodun",
    machine="gd_qc1",  # Guodun "Xiaohong-1"
    token=TOKEN,
    shots=1024,
)

Confirm the provider, target machine, credentials, and possible quota or charges before submitting a real hardware task. See the online manual for provider-specific requirements.

For complete API signatures, backend behavior, noise semantics, hardware provider requirements, and algorithm examples, see the Simulator User Manual.

Documentation

• Quick start
• API overview
• Core circuit interface
• Execution and tool workflow
• Algorithms and utilities

中文

UnitaryLab 通过高层 Circuit API 提供量子线路构建、模拟、分析、绘图、 互操作和硬件编译能力，支持稠密状态向量、矩阵乘积态与密度矩阵模拟。

官网 · 模拟器用户手册 · English

安装

UnitaryLab 支持 Python 3.10–3.12。

pip install unitarylab

可按需安装可选组件：

# CUDA 12 C++ 后端
pip install "unitarylab[cuda]"

# 量子化学工作流
pip install "unitarylab[chemistry]"

主包支持 Windows、Linux 和 macOS。CUDA extra 支持 Linux x86_64、Linux aarch64 服务器环境和 Windows x86-64，并要求兼容的 NVIDIA 驱动。量子化学 扩展目前支持 Linux 和 macOS。

Bell 态快速示例

from unitarylab import Circuit

circuit = Circuit(2)
circuit.h(0)
circuit.cx(0, 1)

result = circuit.execute()
print(result.probabilities)

概率映射包含全部计算基态：

{"00": 0.5, "10": 0.0, "01": 0.0, "11": 0.5}

显示的比特字符串采用 little-endian 量子比特顺序，qubit 0 位于最右侧。

核心能力

常用工作流

创建线路；需要经典结果时添加测量，并通过 shots 指定独立执行次数：

from unitarylab import Circuit, Register, ClassicalRegister

q = Register("q", 2)
c = ClassicalRegister("c", 2)
circuit = Circuit(q, c)

circuit.h(q[0])
circuit.cx(q[0], q[1])
circuit.measure(q[0:2], c[0:2])

result = circuit.execute(shots=1000, seed=42)
print(result.counts)
print(result.classical_results_map)
print(result.classical_registers)

• counts 汇总全部 shots 的经典比特串。
• classical_results_map 保存最后一个 shot 的经典位值。
• classical_registers 按寄存器名称组织最后一个 shot 的结果。
• state 是最后一个 shot 的稠密状态，backend_state 则保留后端原生表示。

未在线路中添加测量时，执行结果还支持单项概率、边缘分布、不坍缩采样、 投影测量和归一化 Observable 期望值查询。

result = Circuit(1).execute()

print(result.probability("0"))
print(result.sample(shots=8, seed=7))
print(result.expectation("Z"))

Pauli 字符串中的字符按传入的 qubits 顺序逐一对应量子比特。该算符顺序与 概率字符串的显示顺序相互独立；概率字符串中 qubit 0 位于最右侧。

后端兼容表

后端选择建议

• 更看重兼容性和开箱即用体验时，从默认的 torch CPU 后端开始。
• 性能优先且原生扩展可用时，优先选择 cpp + device="cpu"。
• 具备 NVIDIA 环境时，优先选择 cpp + device="gpu" 获得更高 性能；使用前需安装 unitarylab[cuda] 并配置兼容的 NVIDIA 驱动。
• 更看重 NumPy 原生稠密状态或最小化后端集成时选择 numpy。
• 面向较大规模、低纠缠线路时，可使用 tensornet 的 MPS 表示避免构造完整 稠密状态向量。
• 模拟混态和噪声模型时使用 execute_density()；密度矩阵执行目前不提供 线路测量或 shots/counts。

需要时可显式选择后端：

result = circuit.execute(backend="numpy", device="cpu")
result = circuit.execute(backend="tensornet", device="cpu")
density_result = circuit.execute_density(device="cpu")

线路转义分析及量子真机任务提交

高层接口提供线路绘图与分析、线路结构变换、本地优化与转译、OpenQASM 2/3 导入导出、编译，以及统一的真机提交能力。

circuit.draw()
info = circuit.analyze(show=False)

optimized = circuit.optimize(optimization_level=1)
transpiled = circuit.transpile(basis="default")
qasm = circuit.to_qasm()

真机提交需要真机供应商 API token，并可能要求机器标识或厂商 SDK：

TOKEN = "your-provider-token"

hardware_result = circuit.submit(
    provider="guodun",
    machine="gd_qc1",  # 国盾量子“骁鸿一号”
    token=TOKEN,
    shots=1024,
)

提交真实硬件任务前，请确认 provider、目标机器、token以及可能产生的额度或费用， 并在在线用户手册中查看各 provider 的具体要求。

完整 API 签名、后端行为、噪声语义、硬件 provider 要求和算法示例请查看 模拟器用户手册。

文档导航

• 快速开始
• API 使用总览
• 核心线路接口
• 线路执行与工具流程
• 算法与工具库

License

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