qalgora-Q Docs Hub量子文档 ✦ Ask AI✦ 问问文档
/

Installation

The runnable reference build — a pure-NumPy statevector simulator that runs every core example in these docs (gate-model kernels, sampling, expectation values) — is available today from source. Advanced specification APIs (QEC decoders, GQE, photonic GBS gates, hardware introspection…) are documented as the intended interface and are clearly marked in-page; they are not bundled in the reference build yet. Open-system dynamics and noise-channel modelling, by contrast, do run on the reference build today (NumPy/SciPy, CPU-only). The packaged distributions (a PyPI wheel, a GPU build, a Docker image, and prebuilt C++ packages) are planned and not yet published; until they ship, use the reference build below.

Runnable reference build (available now)

The open reference build is a pure-NumPy exact statevector simulator, CPU-only, no GPU or cloud account needed. Every core gate-model example runs against it today — kernels, gates, sample, observe, get_state, and CPU statevector simulation; pages that use a specification API carry an in-line “specification API” note. If you set a remote target such as ibm or ionq, the build emits a visible warning and runs locally on the CPU statevector simulator instead — it never silently pretends to use real hardware. The source is currently in private beta — request access, then install from your local checkout (Python 3.10+):

# from the root of your reference-build checkout (source access on request)
pip install ./runtime

Then run your first kernel and confirm it works:

import qalgora

@qalgora.kernel
def bell():
    q = qalgora.qvector(2)
    h(q[0])
    x.ctrl(q[0], q[1])
    mz(q)

print(qalgora.sample(bell))   # ~{ 00:500  11:500 }
What runs locally
Kernels, gates, sample, observe with spin operators, get_state and all CPU simulator targets (cpu is an alias of qpp-cpu) execute for real. Cloud/hardware targets (ibm, ionq, braket…) require vendor credentials; the reference build accepts them but falls back to the local simulator.

Planned distributions

Not yet published
The channels below are the planned distribution paths and are not available yet — the PyPI packages, the Docker image, and the C++ source repository do not exist at the time of writing. They are documented here to describe the intended interface. Until they ship, install the reference build above.

pip wheel (planned)

Intended fastest path on Python 3.10+ (Linux x86_64 or aarch64):

# planned — not yet released; commands kept commented out so they are not run by accident
# python3 -m pip install qalgora        # planned — not yet on PyPI
# python3 -m pip install qalgora-gpu    # planned — GPU-accelerated build

Docker image (planned)

# planned — not yet released; commands kept commented out so they are not run by accident
# docker pull registry.qhquantum.com/qalgora:latest      # planned — registry not yet live
# docker run --gpus all -it --rm registry.qhquantum.com/qalgora:latest

Build from source, C++ (planned)

# planned — not yet released; commands kept commented out so they are not run by accident
# git clone https://github.com/qhquantum/qalgora.git     # planned — repository not yet public
# cd qalgora
# bash scripts/build_qalgora.sh
Requirements (planned packages)
GPU backends will require a supported GPU with compute capability 7.0+ and a matching driver. CPU-only simulation works everywhere but scales to fewer qubits.

安装

可运行的参考实现现已能从源码获取——它是一个纯 NumPy 态矢量模拟器，本文档里每一个核心示例（门模型内核、采样、期望值）都能跑通。开放系统动力学（dynamics）与噪声通道建模也能在参考实现上跑通，它们基于 NumPy/SciPy、仅用 CPU。更高级的规范接口（QEC 解码器、GQE、光子 GBS 门、硬件自省…）只是预期接口，已在各页面内标注，参考实现暂未内置。打包发行版（PyPI wheel、GPU 版本、Docker 镜像与预编译 C++ 包）尚在规划中，暂未发布；在它们正式发布之前，请用下方的参考实现。

可运行的参考实现（现已可用）

开源参考实现是一个纯 NumPy 的精确态矢量模拟器，仅需 CPU，无需 GPU 或云账号。本文档中的每一个核心门模型示例今天都能直接跑通——内核、量子门、sample、observe、get_state 与 CPU 态矢量模拟；使用规范接口的页面会带有行内「规范接口」提示。若你设置了 ibm、ionq 等远程目标，参考实现会给出明显 warning 并回退到本地 CPU 态矢量模拟器运行，绝不会悄悄假装提交到了真机。源码目前处于私有 beta——申请访问后，在本地 checkout 中安装（Python 3.10+）：

# 在参考实现 checkout 的根目录下（源码按需提供）
pip install ./runtime

然后运行你的第一个内核，确认一切正常：

import qalgora

@qalgora.kernel
def bell():
    q = qalgora.qvector(2)
    h(q[0])
    x.ctrl(q[0], q[1])
    mz(q)

print(qalgora.sample(bell))   # ~{ 00:500  11:500 }
本地能跑什么
内核、量子门、sample、带 spin 算符的 observe、 get_state 以及所有 CPU 模拟器目标（cpu 是 qpp-cpu 的别名）都能真实执行。云端/硬件目标 （ibm、ionq、braket 等）需要厂商凭据；参考实现会接受它们， 但回退到本地模拟器。

规划中的发行方式

尚未发布
下列渠道为规划中的发行方式，目前尚不可用——PyPI 包、Docker 镜像与 C++ 源码仓库在撰写本文时均不存在。此处列出仅用于说明计划中的接口。在它们正式发布前，请安装上方的参考实现。

pip wheel（规划中）

计划中最快捷的方式，需 Python 3.10+（Linux x86_64 或 aarch64）：

# 规划中——尚未发布；命令保留为注释，避免被误执行
# python3 -m pip install qalgora        # 规划中——尚未发布到 PyPI
# python3 -m pip install qalgora-gpu    # 规划中——GPU 加速版本

Docker 镜像（规划中）

# 规划中——尚未发布；命令保留为注释，避免被误执行
# docker pull registry.qhquantum.com/qalgora:latest      # 规划中——镜像仓库尚未上线
# docker run --gpus all -it --rm registry.qhquantum.com/qalgora:latest

从源码构建，C++（规划中）

# 规划中——尚未发布；命令保留为注释，避免被误执行
# git clone https://github.com/qhquantum/qalgora.git     # 规划中——仓库尚未公开
# cd qalgora
# bash scripts/build_qalgora.sh
环境要求（规划中的包）
GPU 后端将需要计算能力 7.0 及以上的 GPU，以及对应版本的驱动。纯 CPU 模拟在所有平台均可运行，但可支持的量子比特数量有限。