Overview#

Kaiwu SDK#

Kaiwu SDK is a software development kit for combinatorial optimization problems. It provides complete Python interfaces for QUBO/Ising modeling, matrix preprocessing, solver invocation, and result post-processing. On top of the modeling capabilities of the community edition, the enterprise edition adds SPQC hardware solving, classical optimizers, precision adaptation, HOBO modeling, license authentication, and usage-data reporting, making it easier to switch between local debugging and real computing resources.

The main modules of the current SDK are as follows:

Module	Function
`core`	Basic modeling and conversion module. It provides `Binary`, `Spin`, `QuboModel`, `IsingModel`, expression evaluation, constraint penalty terms, QUBO/Ising matrix conversion, and other capabilities. This module is provided by the `kaiwu-community` dependency.
`common`	General utility module. It provides common capabilities such as log configuration, checkpoint, loop controllers, solution pools, Hamiltonian calculation, and matrix checks. This module is provided by the `kaiwu-community` dependency.
`hobo`	Higher-order binary optimization (HOBO) modeling module. It provides `HoboModel` for constructing and reducing binary optimization problems that contain higher-order terms.
`preprocess`	Matrix preprocessing module. It provides tools for QUBO/Ising matrix bit-width evaluation, precision adjustment, dynamic range metrics, upper and lower bound estimation, and precision-adaptation splitting/mutation.
`hybrid`	Hybrid solving module. It provides `PenaltyMethodOptimizer` for solving constrained QUBO models together with optimizers in `cim` or `classical`.
`cim`	SPQC solving module. It provides `CIMOptimizer` and `TaskMode` for submitting Ising/QUBO matrices to SPQC-related computing backends and retrieving results.
`classical`	Classical optimizer module. It provides local optimizers such as simulated annealing, tabu search, and brute-force search, suitable for debugging, benchmarking, and solving small-scale problems.
`sampler`	Sampling and post-processing module. It provides tools such as `SimulatedAnnealingSampler` for generating or processing candidate solutions.
`license`	Enterprise license module. It provides license initialization, validation, pre-run checks, and usage-data reporting.

In a typical application, users first model the problem with core or hobo, then convert the model into a QUBO or Ising matrix. They then use preprocess to adapt the matrix precision, bit width, or range. Finally, depending on the scenario, they choose the classical local optimizer, the cim hardware optimizer, or use the penalty method in hybrid to handle constrained problems uniformly. common and license run through the whole workflow, providing engineering support and enterprise authorization capabilities respectively.

Typical usage#

        sequenceDiagram
   autonumber
   participant User as 用户代码
   participant License as license
   participant Model as core / hobo
   participant Preprocess as preprocess
   participant Hybrid as hybrid
   participant Optimizer as classical / cim
   participant Result as sampler / common

   User->>License: init / ensure_license()
   License-->>User: license 校验结果
   User->>Model: 构建 Binary / Spin / HoboModel
   Model-->>User: QuboModel / IsingModel / 矩阵
   User->>Preprocess: 位宽评估、精度调整、范围适配
   Preprocess-->>User: 预处理后的 QUBO / Ising 矩阵
   User->>Hybrid: PenaltyMethodOptimizer.solve()
   Hybrid->>Optimizer: 调用 optimizer.solve(matrix)
   Note over Optimizer: classical 用于本地调试和小规模求解<br/>cim 用于对接 SPQC 计算后端
   Optimizer-->>Hybrid: 候选解 / 能量 / 运行信息
   Hybrid->>Result: 结果评估、排序、日志 / checkpoint
   Result-->>User: 最优解、解池与指标
   Note over Model,Result: core / common 由 kaiwu-community 依赖提供<br/>kaiwu 提供 cim、classical、hobo、hybrid、license、preprocess、sampler

Prerequisites#

SPQC#

SPQC (Special-Purpose Quantum Computer), is a quantum computer technology that QBoson focuses on developing at present. CIM(Coherent Ising Machine) is a special-purpose quantum computer based on degenerate optical parametric oscillator (DOPO). In mathematical practice, we can abstract SPQC as a specialized computer for optimizing Ising models.

Ising Model#

Ising Model is a kind of stochastic process model describing the phase transition of substances, with the mathematical form of:

H(\sigma)=-\sum_{i,j}J_{ij}\sigma_i\sigma_j-\mu\sum_ih_i\sigma_i

where $\sigma$ denotes the spin variables to be solved, taking values in $\{-1,1\}$ . $H$ is the Hamiltonian, $J$ is the quadratic coefficient, and $\mu$ and $h$ are linear coefficients. These are known quantities.

QUBO#

QUBO (Quadratic unconstrained binary optimization) has the following mathematical form:

::

where $x$ denotes the binary variables to be solved, taking values in $\{0,1\}$ . $f$ is the objective function, and $q$ is the known quadratic coefficient. In linear algebra form:

f_Q(\pmb x)=\pmb x^T\pmb Q\pmb x

where $\pmb x$ is a binary vector and $\pmb Q$ is the QUBO matrix. The objective of QUBO is to find $\pmb x$ that minimizes or maximizes $f$ , namely:

\pmb x^*=\mathop{\arg\min}\limits_{\pmb x}f_Q(\pmb x)

In Kaiwu SDK, viewing QUBO model details through kw.core.details will display offset and coefficients information. Where offset represents the constant term in the QUBO model, which has nothing to do with the variables. coefficients represents the coefficient value of each binary variable in the QUBO model, And the coefficient values of their interaction terms.

Solving Models Using SPQC#

Solving a QUBO or optimizing an Ising model with SPQC means inputting $q_{ij}$ from the QUBO or $J_{ij}$ from the Ising model into the SPQC, after which the SPQC returns $\pmb x$ or $\sigma$ .

Citing Kaiwu SDK#

If the Kaiwu SDK is helpful to your academic research, Bose Quantum thanks you for citing it as follows.

@software{KaiwuSDK,
title = {Kaiwu SDK for development and research on special-purpose quantum computer},
author = {{QBoson Inc.}},
year = {2022},
url = {https://www.qboson.com/}
}

@misc{KaiwuSDK,
title = {Kaiwu SDK for development and research on special-purpose quantum computer},
author = {{QBoson Inc.}},
year = {2022},
url = {https://www.qboson.com/}
}