quest_bind

QuEST v3.5.0的包装器。

量子精确仿真工具包（QuEST）是一个无冗余、追求速度的量子电路仿真器 [1]。它以MIT许可证分发。

如何使用

初始化一个新的二进制crate

cargo new tryme
cd tryme/

将 quest_bind 添加到项目的依赖项

cargo add quest_bind

现在编写一些代码并将其放入 ./src/main.rs

use quest_bind::*;

fn main() -> Result<(), QuestError> {
    // Initialize QuEST environment and report to screen
    let env = &QuestEnv::new();
    env.report_quest_env();

    // Create a 2-qubit register and report its parameters
    let mut qureg = Qureg::try_new(2, env).expect("cannot allocate new Qureg");
    qureg.report_qureg_params();
    // Initialize |00> state and print out the state to screen
    qureg.init_zero_state();
    qureg.report_state_to_screen(0);

    // Prepare a Bell state `|00> + |11>`: apply Hadamard gate
    // on qubit 0, then NOT on qubit 1, controlled by qubit 0.
    println!("---\nPrepare Bell state: |00> + |11>");
    qureg.hadamard(0).and(qureg.controlled_not(0, 1))?;

    // Measure both qubits
    let outcome0 = qureg.measure(0)?;
    let outcome1 = qureg.measure(1)?;
    println!("Qubit \"0\" measured in state: |{outcome0}>");
    println!("Qubit \"1\" measured in state: |{outcome1}>");

    // Because the state was entangled, the outcomes
    // should always be the same
    if outcome0 == outcome1 {
        println!("They match!");
        Ok(())
    } else {
        panic!("qubits in Bell state should be perfectly correlated");
    }

    // At this point both `qureg` and `env` are dropped and
    // the allocated memory is freed.
}

文档可在 线上 以及本地找到

cargo doc --open

最后，编译并运行程序

cargo run

你应该能看到类似的内容

EXECUTION ENVIRONMENT:
Running locally on one node
Number of ranks is 1
OpenMP enabled
Number of threads available is 8
Precision: size of qreal is 8 bytes
QUBITS:
Number of qubits is 2.
Number of amps is 4.
Number of amps per rank is 4.
---
Prepare Bell state: |00> + |11>
Qubit "0" measured in state: |0>
Qubit "1" measured in state: |0>
They match!

分布式和GPU加速模式

可以通过设置适当的特性标志在 quest_bind 中启用QuEST对MPI和GPU加速计算的支持。要启用QuEST的MPI模式，设置quest_bind的mpi特性。只需编辑二进制crate的Cargo.toml

[package]
name = "tryme"
version = "0.1.0"
edition = "2021"

[dependencies]
quest_bind = { features = ["mpi"] }

现在，如果你再次编译并运行上述程序，输出应该是

EXECUTION ENVIRONMENT:
Running distributed (MPI) version
Number of ranks is 1
...

特性 "gpu" 启用GPU加速模式。这两个特性是互斥的，如果同时设置了这两个标志，则特性 "mpi" 优先。

测试

要为此库运行单元测试，首先将QuEST源代码作为子模块一起克隆仓库

git clone --recurse-submodules https://github.com/marek-miller/quest_bind.git
cd quest_bind

然后运行

cargo test

请注意，quest_bind 不会运行 QuEST 的测试套件，也不会检查 QuEST 的正确性。这里的测试旨在检查是否正确调用了C API，以及Rust的类型是否安全地在FFI边界之间传递。

如果您想以单精度浮点模式运行测试套件，请确保构建脚本使用正确的类型定义重新编译 libQuEST.so

cargo clean
cargo test --features=f32

默认情况下，quest_bind 使用Rust的双精度浮点类型：f64。请参阅下文中的 数值类型 部分。

您还可以通过运行，例如，来尝试可用的示例。

 cargo run --release --example grovers_search

要查看所有可用示例的列表，请尝试

cargo run --example

性能说明

在典型情况下，当CPU使用率主要由数值计算主导而不是API调用时，使用QuEST例程直接调用程序与使用quest_bind的类似应用程序之间应该没有可察觉的性能差异。但是，请记住，通过使用“发布”配置文件编译您的代码来启用对quest_bind和QuEST的优化。

cargo run --release

异常处理

在失败的情况下，QuEST通过用户可配置的全局invalidQuESTInputError()抛出异常。默认情况下，此函数会打印错误消息并中止，这在大型分布式设置中是有问题的。

cargo add env_logger

fn main()  {
    env_logger::init();
    // (...)
}

RUST_LOG=info cargo run

pub type c_float = f32;
pub type c_double = f64;
pub type c_int = i32;
pub type c_longlong = i64;
pub type c_ulong = u64;

rustup doc