Metadata-Version: 2.4
Name: unitarylab
Version: 1.4.2
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
Requires-Dist: cqlib
Requires-Dist: networkx
Provides-Extra: cuda
Requires-Dist: unitarylab-cu12<0.3,>=0.2; extra == "cuda"
Provides-Extra: chemistry
Requires-Dist: unitarylab-chemistry<0.2,>=0.1; extra == "chemistry"
Dynamic: license-file

<div align="center">

<h1>unitarylab</h1>

<p>
  <strong>A Python toolkit for building, simulating, analyzing, and compiling 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%20%7C%20TensorNet-7c3aed?style=flat-square" alt="NumPy, PyTorch, C++, and TensorNet 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="#中文">中文</a>
</p>

</div>

---

<a id="english"></a>

# 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](https://unitarylab.com/) · [Simulator User Manual](https://docs.unitarylab.com/en/docs/unitarylab-simulator-user-manual/) · [中文](#中文)

## Installation

UnitaryLab requires Python 3.10–3.12.

```bash
pip install unitarylab
```

Optional components can be installed as needed:

```bash
# 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

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

```python
{"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

| Area | Capability |
|---|---|
| Circuit construction | Registers, standard gates, controlled gates, measurements, and reusable circuit blocks |
| Statevector execution | PyTorch, NumPy, native C++ CPU/CUDA backends|
| Tensor Network execution | Matrix-Product-State-based TensorNet backends |
| Mixed-state execution | Density-matrix simulation and built-in noise channels |
| Results | State, probabilities, marginal queries, sampling, measurement, counts, and expectation values |
| Circuit tools | Drawing, analysis, transforms, optimization, and transpilation |
| Interoperability | OpenQASM 2/3 import and export, plus unitarylab native Python source generation |
| Hardware | Local compilation and provider-neutral hardware submission |
| Algorithms | Quantum transforms, simulation, linear solvers, equations, and Schrodingerization |

## Common workflow

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

```python
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.

```python
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

| Backend | Device | Notes |
|---|---|---|
| `torch` | `cpu`, `gpu` | Default backend with broad compatibility; GPU uses a compatible CUDA or Apple MPS environment |
| `numpy` | `cpu` | Dense NumPy statevector and a convenient NumPy-native result |
| `cpp` | `cpu` | Performance-oriented native C++ execution; generally preferred when speed is the priority |
| `cpp` | `gpu` | Performance-oriented CUDA C++ execution; requires `unitarylab[cuda]` |
| `tensornet` | `cpu` | Tensor network execution for low-entanglement circuits |
| `execute_density()` | `cpu`, `gpu`/`cuda` | CUDA devices require `unitarylab[cuda]` |

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

```python
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.

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

```python
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](https://docs.unitarylab.com/en/docs/unitarylab-simulator-user-manual/).

## Documentation

- [Quick start](https://docs.unitarylab.com/en/docs/unitarylab-simulator-user-manual/quick-start)
- [API overview](https://docs.unitarylab.com/en/docs/unitarylab-simulator-user-manual/api-overview)
- [Core circuit interface](https://docs.unitarylab.com/en/docs/unitarylab-simulator-user-manual/core-circuit)
- [Execution and tool workflow](https://docs.unitarylab.com/en/docs/unitarylab-simulator-user-manual/circuit-workflow)
- [Algorithms and utilities](https://docs.unitarylab.com/en/docs/unitarylab-simulator-user-manual/library-reference)

---

<a id="中文"></a>

# 中文

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

[官网](https://unitarylab.com/) · [模拟器用户手册](https://docs.unitarylab.com/zh/docs/unitarylab-simulator-user-manual/) · [English](#english)

## 安装

UnitaryLab 支持 Python 3.10–3.12。

```bash
pip install unitarylab
```

可按需安装可选组件：

```bash
# 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 态快速示例

```python
from unitarylab import Circuit

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

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

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

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

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

## 核心能力

| 方向 | 能力 |
|---|---|
| 线路构建 | 寄存器、标准门、受控门、测量与可复用线路块 |
| 状态向量执行 | PyTorch、NumPy、原生 C++ CPU/CUDA 后端 |
| 张量网络执行 | 基于矩阵乘积态的 TensorNet 后端 |
| 混态执行 | 密度矩阵模拟与内置噪声通道 |
| 执行结果 | 状态、概率、边缘查询、采样、测量、计数与期望值 |
| 线路工具 | 绘图、分析、线路变换、优化与转译 |
| 互操作 | OpenQASM 2/3 导入导出与原生 unitarylab Python 源码生成 |
| 量子硬件 | 本地编译与统一的真机提交接口 |
| 算法 | 量子变换、模拟、线性求解、方程与薛定谔化 |

## 常用工作流

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

```python
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 期望值查询。

```python
result = Circuit(1).execute()

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

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

## 后端兼容表

| 后端 | device | 说明 |
|---|---|---|
| `torch` | `cpu`、`gpu` | 兼容性广的默认后端；GPU 使用兼容的 CUDA 或 Apple MPS 环境 |
| `numpy` | `cpu` | 稠密 NumPy 状态向量，便于直接获得 NumPy 原生结果 |
| `cpp` | `cpu` | 面向性能的原生 C++ 执行 |
| `cpp` | `gpu` | 面向高性能的 CUDA C++ 执行；需要 `unitarylab[cuda]` |
| `tensornet` | `cpu` | 面向低纠缠线路的张量网络后端执行 |
| `execute_density()` | `cpu`、`gpu`/`cuda` | CUDA device 需要 `unitarylab[cuda]` |

### 后端选择建议

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

需要时可显式选择后端：

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

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

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

```python
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：

```python
TOKEN = "your-provider-token"

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

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

完整 API 签名、后端行为、噪声语义、硬件 provider 要求和算法示例请查看
[模拟器用户手册](https://docs.unitarylab.com/zh/docs/unitarylab-simulator-user-manual/)。

## 文档导航

- [快速开始](https://docs.unitarylab.com/zh/docs/unitarylab-simulator-user-manual/quick-start)
- [API 使用总览](https://docs.unitarylab.com/zh/docs/unitarylab-simulator-user-manual/api-overview)
- [核心线路接口](https://docs.unitarylab.com/zh/docs/unitarylab-simulator-user-manual/core-circuit)
- [线路执行与工具流程](https://docs.unitarylab.com/zh/docs/unitarylab-simulator-user-manual/circuit-workflow)
- [算法与工具库](https://docs.unitarylab.com/zh/docs/unitarylab-simulator-user-manual/library-reference)

---

# License

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