安装与环境配置

适用版本 · ArcQML 0.1.0

本页目录

2.1 发行目录

以下路径均以用户取得的 ArcQML 发行目录为基准，将示例中的 PATH_TO_YOUR_FILES 替换为实际存放发行包的目录，并保持发行包内部的相对目录结构不变。

text

PATH_TO_YOUR_FILES/ArcQML/
├── crates/                 # Rust 接口及配套功能
├── libs/
│   ├── x86_64-pc-windows-msvc/
│   │   └── arcqml_runtime_private.lib
│   └── x86_64-unknown-linux-gnu/
│       └── libarcqml_runtime_private.a
├── wheels/
│   └── arcqml-0.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
├── examples/               # 完整示例
├── docs/                   # 技术手册、API 文档与教程
├── Cargo.toml
└── LICENSE-RUNTIME

libs 中的二进制库必须与操作系统和 CPU 架构匹配，不应改名或与其他 ArcQML 版本混用。当前发行包提供 Windows x86_64 MSVC 与 Linux x86_64 GNU 两种 Rust Runtime。wheels 中的文件名表明当前 Python 包只适用于 CPython 3.11、Linux x86_64；该 wheel 不能直接安装到 Windows、macOS、ARM Linux 或其他 Python 版本。

兼容其它操作系统及环境的版本即将发布。

2.2 Rust 环境与 Runtime 配置

Rust 接口要求 Rust 1.85 或更高版本，并使用 Rust 2024 edition。Windows 用户可按照 Rust 官方安装页安装 rustup，安装时保留默认的 MSVC toolchain；Linux 用户可使用官网提供的安装命令：

bash

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

安装后执行 rustc --version 和 cargo --version 确认命令可用。然后进入发行包根目录，将环境变量 ARCQML_RUNTIME_LIB_DIR 指向与当前平台匹配的 libs 子目录。该变量用于链接预编译 Runtime。

Windows PowerShell：

powershell

Set-Location "PATH_TO_YOUR_FILES\ArcQML"
$env:ARCQML_RUNTIME_LIB_DIR = (Resolve-Path ".\libs\x86_64-pc-windows-msvc").Path
cargo check -p arcqml

Linux：

bash

cd PATH_TO_YOUR_FILES/ArcQML
export ARCQML_RUNTIME_LIB_DIR="$PWD/libs/x86_64-unknown-linux-gnu"
cargo check -p arcqml

环境变量只对当前终端会话生效；打开新终端后需要重新设置。用户自己的 Rust 项目可以通过路径依赖引用发行包中的接口：

toml

[dependencies]
arcqml = { path = "PATH_TO_YOUR_FILES/ArcQML/crates/arcqml" }

运行该项目时同样需要先设置 ARCQML_RUNTIME_LIB_DIR。如果复制或移动发行包，应同步更新依赖路径与 Runtime 路径。

2.3 Python 环境与 wheel 安装

当前 Python wheel 适用于 Linux x86_64 和 CPython 3.11。建议使用独立 Conda 环境，避免现有环境中的 Python 或 NumPy 版本影响安装。以下命令均在 ArcQML 发行包根目录执行：

bash

cd PATH_TO_YOUR_FILES/ArcQML
conda create -n arcqml-example python=3.11 -y
conda activate arcqml-example
python -m pip install --upgrade pip
python -m pip install ./wheels/arcqml-0.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

wheel 已静态嵌入与其版本匹配的 ArcQML Runtime，因此 Python 用户不需要设置 ARCQML_RUNTIME_LIB_DIR，也不需要安装 Rust、Maturin 或从源码编译扩展。可用 python -c "import arcqml; print(arcqml)" 验证导入是否成功。若 pip 报告 wheel 与平台不兼容，应先核对 python --version、python -c "import platform; print(platform.machine())" 与操作系统。

2.4 一次可训练前向与反向的数据流

text

Circuit.parameters()
    │  参数值在执行时绑定到 Gate
    ▼
(Batch)StateVectorSimulator.run(circuit, observable)
    │  接口层校验并绑定参数，预编译 Runtime 执行状态演化与期望值计算
    ▼
F64 标量或 [B] F64 Tensor
    │  与普通 Tensor loss 组成统一自动微分图
    ▼
loss.backward()
    │  经典 VJP → Runtime 量子伴随计算 → Parameter.grad
    ▼
optimizer.step(circuit.parameters())

整条量子电路作为自定义 Tensor 操作接入自动微分图。公开接口层负责参数与形状校验、计算图连接和优化器更新；闭源 Runtime 负责状态向量数值内核、可观测量计算与量子伴随反向。run 的父节点包含可微初态与所有电路参数，因此，外部损失函数无须了解量子门内部执行过程，量子期望值也能继续参与经典可微计算。

下载完整 Markdown 技术手册 ↓