安装与环境配置

适用版本 · ArcQML 0.1.0

本页目录

发行目录

使用或分发前，请先阅读发行状态与许可证。自有公开源码仅限非商业用途，官方闭源 Runtime 另受非商业二进制许可约束；wheel 中的各组成部分适用各自许可。

本次发行是 Windows 实验性预览版，使用 Rust 1.98.0 和 CPython 3.11，Linux 验收暂缓。下述 Linux 目录和命令保留为历史环境示例，不代表本次发行提供 Linux 产物。实际安装请使用本次随附且与平台匹配的库和 wheel，勿混用历史产物；当前安装步骤见 ArcQML 仓库，已知内存安全问题 S01 见安全限制。

以下路径均以用户取得的 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-pc-windows-msvc 与 Linux x86_64-unknown-linux-gnu 两种 Rust Runtime 路径。示例中的 Linux wheel 只适用于 CPython 3.11、Linux x86_64，不能安装到 Windows；本次 Windows 预览版应使用其随附的 Windows Runtime 和 wheel。

其他操作系统、CPU 架构和 Python 版本的支持，以后续实际提供的构建产物为准。

Rust 环境与 Runtime 配置

Rust 接口使用 Rust 2024 edition，建议安装当前稳定版工具链，本次示例在 Rust 1.98.0 上验证。Windows 用户可按照 Rust 官方安装页安装 rustup，使用 MSVC toolchain，并安装对应的 Visual Studio C++ Build Tools 与 Windows SDK；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

环境变量只对当前终端会话生效；打开新终端后需要重新设置。cargo check 只检查源码和类型，不验证最终应用链接。

用户自己的 Rust 项目可以通过路径依赖引用发行包中的接口：

toml

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

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

Python 环境与 wheel 安装

以下保留历史 Linux x86_64、CPython 3.11 和兼容 manylinux2014 的 glibc 环境安装示例，不适用于本次 Windows 预览版。建议使用独立 Conda 环境，避免现有环境中的 Python 或 NumPy 版本影响安装。当前 Windows 安装命令见 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())" 与操作系统。

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

text

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

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

下载完整 Markdown 技术手册 ↓