Extending qalgora-Q with a Custom Simulator

○ Planned · Not yet implemented

The capabilities described on this page are planned and not yet implemented or released. They explain future design directions and should not be interpreted as delivered features.

The simulator layer is an open interface. By subclassing the circuit-simulator base, registering it, and shipping a small target config, your own state representation becomes a first-class --target — the same path our built-in backends take.

Planned — not runnable (规划中·暂不可运行)

The C++ compiler/library has not been released, so the code on this page cannot be compiled or run. The base class, registration macro, config, and build commands shown across the different sections are separate design drafts — treat the published release as authoritative for the exact signatures.

Subclass the simulator base

Derive from CircuitSimulatorBase<FloatType> and override the handful of methods that describe how your representation allocates qubits, applies a gate, measures, and samples:

#include "CircuitSimulator.h"

namespace {

class MySimulator : public qalgora::CircuitSimulatorBase<double> {
protected:
  void addQubitToState() override { /* grow the state by one qubit */ }
  void addQubitsToState(std::size_t count) override { /* grow by count */ }
  void resetQubitStateImpl() override { /* clear back to |0...0> */ }
  void applyGate(const GateApplicationTask &task) override { /* core: apply one gate */ }

public:
  MySimulator() = default;
  virtual ~MySimulator() = default;

  bool measureQubit(std::size_t qubitIdx) override { /* collapse + return bit */ }
  void resetQubit(std::size_t &qubitIdx) override { /* reset one qubit */ }
  qalgora::SampleResult sample(std::vector<std::size_t> &measuredBits,
                               int shots) override { /* draw shots */ }
  const std::string_view name() const override { return "MySimulator"; }
};

} // namespace

QALGORA_REGISTER_SIMULATOR(MySimulator)

C++ API is planned — won’t run today

The runnable reference build is Python-only; the C++ library, its headers and the build tooling shown here are a planned interface and are not published yet, so this snippet will not compile or run as-is. Use the Python API against the reference build to actually run these examples today.

Ship a target config

A MySimulator.config file tells the runtime which shared library backs the target:

# MySimulator.config
QALGORA_SIMULATION_BACKEND="MySimulator"

Build and use it

Compile with the provided CMake helper, install the libqsim-MySimulator.so plus its config, and the new backend is selectable like any other:

cmake_minimum_required(VERSION 3.24 FATAL_ERROR)
project(CustomBackend LANGUAGES CXX)
find_package(QSIR REQUIRED)
qsir_add_backend(MySimulator MySimulator.cpp "")

export QALGORA_PATH=/path/to/qalgora/install
mkdir build && cd build
cmake .. -G Ninja -DQSIR_DIR="$QALGORA_PATH/lib/cmake/qsir"
ninja install

qalgora++ file.cpp --target MySimulator

Where this fits

A custom backend is how you plug in a specialised state representation — a domain-specific approximation, an FPGA emulator, or an in-house HPC kernel — without touching the rest of the stack. The same extension point underlies our tensor-network and stabilizer simulators.

使用自定义模拟器扩展 qalgora-Q

○ 规划中

本页所述能力属于规划功能，当前尚未发布或尚未实现。相关内容仅用于说明未来设计方向，不应理解为已交付能力。

模拟器层是一个开放接口。只要继承电路模拟器基类、完成注册，再配上一份简短的目标配置，你自己的态表示就能成为一等的 --target——和内置后端走同一条路径。

规划中·暂不可运行

C++ 编译器/库尚未发布，本页代码不可编译运行；不同小节展示的基类、注册宏、配置与构建命令为不同设计草案，具体签名以发布版为准。

继承模拟器基类

从 CircuitSimulatorBase<FloatType> 派生，重写几个方法，说明你的态表示如何分配量子比特、施加门、测量和采样：

#include "CircuitSimulator.h"

namespace {

class MySimulator : public qalgora::CircuitSimulatorBase<double> {
protected:
  void addQubitToState() override { /* grow the state by one qubit */ }
  void addQubitsToState(std::size_t count) override { /* grow by count */ }
  void resetQubitStateImpl() override { /* clear back to |0...0> */ }
  void applyGate(const GateApplicationTask &task) override { /* core: apply one gate */ }

public:
  MySimulator() = default;
  virtual ~MySimulator() = default;

  bool measureQubit(std::size_t qubitIdx) override { /* collapse + return bit */ }
  void resetQubit(std::size_t &qubitIdx) override { /* reset one qubit */ }
  qalgora::SampleResult sample(std::vector<std::size_t> &measuredBits,
                               int shots) override { /* draw shots */ }
  const std::string_view name() const override { return "MySimulator"; }
};

} // namespace

QALGORA_REGISTER_SIMULATOR(MySimulator)

C++ 接口为规划中 · 暂不可运行

可运行的参考实现仅提供 Python；此处展示的 C++ 库头文件与构建工具属于规划中的接口尚未发布因此该片段当前无法直接编译或运行。若要真正运行这些示例请使用 Python API 对接参考实现。

附带目标配置

用一份 MySimulator.config 文件告诉运行时，该目标由哪个共享库支撑：

# MySimulator.config
QALGORA_SIMULATION_BACKEND="MySimulator"

构建并使用它

用配套的 CMake 辅助工具编译，把 libqsim-MySimulator.so 连同它的配置文件一起安装好，新后端就能像其它后端一样选用：

cmake_minimum_required(VERSION 3.24 FATAL_ERROR)
project(CustomBackend LANGUAGES CXX)
find_package(QSIR REQUIRED)
qsir_add_backend(MySimulator MySimulator.cpp "")

export QALGORA_PATH=/path/to/qalgora/install
mkdir build && cd build
cmake .. -G Ninja -DQSIR_DIR="$QALGORA_PATH/lib/cmake/qsir"
ninja install

qalgora++ file.cpp --target MySimulator

适用场景

自定义后端让你接入专门的态表示——可以是面向特定领域的近似算法、FPGA 仿真器，也可以是自研的 HPC 内核——而不必改动技术栈的其余部分。张量网络模拟器和稳定子模拟器也正是建在同一个扩展点上。

Previous上一页← Extending qalgora-Q扩展 qalgora-Q Next下一页Working with qalgora IR操作 qalgora IR →