Simulated Bifurcation · PyTorch · CUDA

用 GPU 加速求解 QUBO / Ising 问题 GPU-accelerated QUBO / Ising optimization

本项目基于 simulated-bifurcation 和 PyTorch，在 NVIDIA GPU 上并行求解二次无约束二值优化（QUBO）与 Ising 模型。本页介绍如何从零搭建运行环境，并跑通第一个例子。 This project uses simulated-bifurcation and PyTorch to solve Quadratic Unconstrained Binary Optimization (QUBO) and Ising problems in parallel on NVIDIA GPUs. This page walks you through setting up the environment from scratch and running your first example.

Python 3.10
torch 2.6.0+cu118
simulated-bifurcation 1.2.0
CUDA 11.8

环境要求Requirements

Python 3.10 推荐用 Anaconda / Miniconda 创建独立环境。 An isolated Anaconda / Miniconda environment is recommended.
NVIDIA 显卡（可选） NVIDIA GPU (optional) 驱动需支持 CUDA 11.8（版本 ≥ 520）。没有显卡也能用 CPU 运行。 Driver must support CUDA 11.8 (version ≥ 520). Without a GPU the code still runs on CPU.
操作系统 Operating system Windows 或 Linux（已在 Windows + Anaconda 上测试）。 Windows or Linux (tested on Windows + Anaconda).

PyTorch 的 cu118 安装包已经自带 CUDA 运行库，不需要另外安装 CUDA Toolkit，只要显卡驱动版本够新即可。

PyTorch's cu118 wheels ship with the CUDA runtime, so you do not need to install the CUDA Toolkit separately — a recent enough GPU driver is all it takes.

安装步骤Installation

安装 Python 3.10Install Python 3.10

用 conda 新建一个 Python 3.10 环境并激活：

Create and activate a Python 3.10 environment with conda:
```
conda create -n gpu-q python=3.10 -y
conda activate gpu-q
```
不用 conda 的话，也可以从 python.org 安装 Python 3.10，再用 python -m venv .venv 创建虚拟环境。

Not using conda? Install Python 3.10 from python.org and create a virtual environment with python -m venv .venv.
下载代码并安装依赖Get the code and install dependencies
```
git clone https://github.com/djzts/GPU_acced_Q.git
cd GPU_acced_Q
pip install -r requirements.txt
```
requirements.txt 固定了 numpy、sympy、tqdm 等依赖的版本，其中的 torch==2.2.0 会在下一步被替换成 GPU 版本。

requirements.txt pins numpy, sympy, tqdm and other dependencies. The torch==2.2.0 it installs is replaced by the GPU build in the next step.
安装 GPU 版 PyTorchInstall the GPU build of PyTorch使用 GPU 时GPU only

想用 GPU 加速，请安装 2.6.0+cu118：

To use the GPU, install 2.6.0+cu118:
```
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118
```
这一步必须放在第 2 步之后，否则 requirements.txt 会把 PyTorch 改回 2.2.0。只用 CPU 的话可以跳过这一步。

Run this after step 2, otherwise requirements.txt will downgrade PyTorch back to 2.2.0. Skip this step if you only use the CPU.
安装 simulated-bifurcationInstall simulated-bifurcation
```
pip install simulated-bifurcation==1.2.0
```
至此安装完成。

That's it — the installation is complete.

在 Jupyter Notebook 里安装的话，可以直接打开仓库里的 install package.ipynb 依次运行。装完后请重启内核（Kernel → Restart），新版本的包才会生效。

Prefer Jupyter? Open install package.ipynb from the repository and run its cells in order. Restart the kernel afterwards (Kernel → Restart) so the newly installed packages are picked up.

验证安装Verify the install

检查 PyTorch 版本和 GPU 是否可用：

Check the PyTorch version and whether the GPU is visible:

python -c "import torch, simulated_bifurcation as sb; print(torch.__version__, torch.cuda.is_available())"

正常情况下会输出：

You should see:

2.6.0+cu118 True

如果输出的是 False，请看下方常见问题。

If it prints False, see Troubleshooting below.

快速上手Quick start

simulated-bifurcation 求解的是如下形式的二次多项式的最小值或最大值：

simulated-bifurcation minimizes or maximizes quadratic polynomials of the form:

f(x) = x^TQx + ℓ^Tx + c

`input_type`	变量取值Variable domain	对应问题Problem type
`"binary"`	{0, 1}	QUBO
`"spin"`	{−1, +1}	Ising 模型Ising model

例 1：在 GPU 上求解 QUBOExample 1: solve a QUBO on the GPU

import torch
import simulated_bifurcation as sb

Q = torch.tensor([[1.0, -2.0],
                  [0.0,  3.0]], dtype=torch.float32)

# minimize x^T Q x with x in {0, 1}^2, running on the GPU
best_vector, best_val = sb.minimize(Q, input_type="binary", device="cuda")
print("Best vector (binary domain):", best_vector)
print("Best value:", best_val)

Best vector (binary domain): tensor([0., 0.], device='cuda:0')
Best value: 0.0

没有 GPU 时，把 device="cuda" 删掉（默认 CPU）或改成 device="cpu"。

No GPU? Remove device="cuda" (CPU is the default) or set device="cpu".

例 2：Ising 模型Example 2: Ising model

best_vector, best_val = sb.maximize(Q, input_type="spin")
print("Best vector (spin domain):", best_vector)
print("Best value:", best_val)

Best vector (spin domain): tensor([ 1., -1.])
Best value: 6.0

最优值是 6.0（[1, -1] 或 [-1, 1]）。这是启发式算法，偶尔会得到 2.0 这样的次优解，见常见问题。

The optimum is 6.0 ([1, -1] or [-1, 1]). Because this is a heuristic, you may occasionally get a sub-optimal 2.0 — see Troubleshooting.

例 3：带一次项和常数项，同时保留所有解Example 3: linear and constant terms, keeping every solution

对于 f(x, y, z) = x² − y² + 2z² + xy − 2yz − x + 2z + 2，写成矩阵形式即：

For f(x, y, z) = x² − y² + 2z² + xy − 2yz − x + 2z + 2, the matrix form is:

Q = torch.tensor([[1.0,  0.5,  0.0],
                  [0.5, -1.0, -1.0],
                  [0.0, -1.0,  2.0]], dtype=torch.float32)
l = torch.tensor([-1.0, 0.0, 2.0], dtype=torch.float32)
c = 2.0

poly_model = sb.build_model(Q, vector=l, constant=c, input_type="binary")

# run 64 agents in parallel and return all of their results
all_vectors, all_values = poly_model.minimize(agents=64, best_only=False)
print("All solutions shape:", all_vectors.shape)
print("All evaluations shape:", all_values.shape)

All solutions shape: torch.Size([64, 3])
All evaluations shape: torch.Size([64])

完整代码见仓库中的 Example.py（运行 python Example.py），更详细的推导见 SB user book.ipynb。

The full script is Example.py in the repository (run python Example.py); SB user book.ipynb walks through the derivation in more detail.

仓库文件Repository files

文件File	说明Description
`requirements.txt`	固定版本的 Python 依赖Pinned Python dependencies
`install package.ipynb`	在 Jupyter 中一步步安装依赖Step-by-step dependency install inside Jupyter
`SB user book.ipynb`	使用手册：安装步骤 + 例子与推导User book: install steps plus worked examples
`Example.py`	可直接运行的示例脚本Ready-to-run example script

常见问题Troubleshooting

torch.cuda.is_available() 返回 Falsetorch.cuda.is_available() returns False

1. 运行 nvidia-smi，确认能看到显卡，且驱动版本 ≥ 520。
2. 运行 python -c "import torch; print(torch.__version__)"，版本号应以 +cu118 结尾。如果是 +cpu 或者没有后缀，请重新执行第 3 步。
3. 确认当前激活的是 gpu-q 环境（Jupyter 中要选择对应的内核）。

1. Run nvidia-smi and make sure the GPU is listed with driver version ≥ 520.
2. Run python -c "import torch; print(torch.__version__)" — the version should end with +cu118. If it ends with +cpu or has no suffix, redo step 3.
3. Make sure the gpu-q environment is active (in Jupyter, select the matching kernel).

没有 NVIDIA 显卡可以用吗？Can I use it without an NVIDIA GPU?

可以。跳过第 3 步，代码里不要传 device="cuda"（或改为 device="cpu"）。CPU 上同样能得到结果，只是规模大时速度较慢。

Yes. Skip step 3 and don't pass device="cuda" (or pass device="cpu"). You get the same results on CPU, just slower for large problems.

在 Jupyter 中装完包后导入的还是旧版本Jupyter still imports the old package version

pip 装完后必须重启内核（Kernel → Restart），已加载的模块不会自动更新。

Restart the kernel (Kernel → Restart) after installing — modules that are already loaded aren't reloaded automatically.

每次结果不完全一样？Why do results differ between runs?

Simulated Bifurcation 是带随机初始化的启发式算法，不保证每次都得到全局最优，不同次运行的结果可能不同。对结果要求高时，可以多运行几次取最好的一次，或用 best_only=False 查看所有 agents 的结果。

Simulated Bifurcation is a heuristic with random initialization: it does not guarantee the global optimum, and results can vary between runs. When the result matters, run it several times and keep the best, or pass best_only=False to inspect every agent's result.