SDK ソルバープラグイン開発ガイド

[!NOTE] 最新の実装状況は機能実装ステータス (Remaining Functionality) を参照してください。

概要

EvoSpikeNet は SolverPlugin 機構を持ちます。組み合わせ最適化・QAOA・量子アニーリングなど
任意のソルバーバックエンドをプラグインとして差し替え可能です。

実用ユースケース: - クラシカル SA / Greedy — リアルタイム制約が厳しい場合のデフォルト - QAOA シミュレータ — 古典近似でのプロトタイプ評価 - Qiskit (IBMQ / Aer) — 量子ハードウェア接続 - D-Wave — 量子アニーリングデバイス接続

アーキテクチャ

QPFCQAOABridge
   └─ get_optimizer(name)          # evospikenet/optimizer.py
        ├─ PluginFactory.SOLVER    # プラグインレジストリ優先
        │     ├─ "classical"        → ClassicalSolverPlugin   (SA)
        │     ├─ "qaoa_simulator"   → QAOASimulatorSolverPlugin
        │     ├─ "qiskit"           → QiskitSolverPlugin       (Aer / IBMQ)
        │     └─ "dwave"            → DWaveSolverPlugin        (QPU / SA fallback)
        └─ 組み込みバックエンド (フォールバック)

インストール

最小構成（classical / qaoa_simulator のみ）:

pip install -e .

Qiskit バックエンドを有効化する場合:

pip install qiskit qiskit-aer

D-Wave バックエンドを有効化する場合:

pip install dwave-ocean-sdk

SolverPlugin インターフェース

必須実装メソッド:

メソッド	説明
`get_metadata()`	`PluginMetadata` を返す。`plugin_type=PluginType.SOLVER` を指定
`initialize()`	依存ライブラリのロード・デバイス接続確認
`activate()`	プラグインをアクティブ状態へ遷移
`deactivate()`	リソース解放
`solve(problem, timeout, options)`	最適化を実行しソルバー候補リストを返す

solve() の引数 / 戻り値:

def solve(
    self,
    problem: Dict[str, Any],   # vehicles, stops, distances など
    timeout: float = 5.0,       # 秒
    options: Dict[str, Any] = None,  # solver 固有パラメータ
) -> List[Dict[str, Any]]:
    # 戻り値は score 昇順（小ほど良い）のリスト
    # 各要素: {"assignment": {...}, "score": float, "meta": {...}}

カスタムソルバープラグインの作成手順

1. `SolverPlugin` を継承する

from evospikenet.plugins.solver_plugin import SolverPlugin
from evospikenet.plugins import PluginMetadata, PluginStatus, PluginType

class MyAnnealerPlugin(SolverPlugin):

    def get_metadata(self) -> PluginMetadata:
        return PluginMetadata(
            name="my_annealer",
            version="1.0.0",
            plugin_type=PluginType.SOLVER,
            description="Custom annealing backend",
            author="Your Team",
        )

    def initialize(self) -> bool:
        # 依存ライブラリの確認・接続初期化
        self.status = PluginStatus.INITIALIZED
        return True

    def activate(self) -> bool:
        self.status = PluginStatus.ACTIVE
        return True

    def deactivate(self) -> bool:
        self.status = PluginStatus.UNLOADED
        return True

    def solve(self, problem, timeout=5.0, options=None):
        # 実装: problem を最適化してソルバー候補を返す
        ...
        return [{"assignment": result, "score": cost, "meta": {"backend": "my_annealer"}}]

2. `PluginFactory` に登録する

import evospikenet.plugin_factory as _pf_mod
from evospikenet.optimizer import get_optimizer

# グローバルファクトリに登録
factory = _pf_mod._global_factory  # or PluginFactory()
plugin = MyAnnealerPlugin()
plugin.initialize()
plugin.activate()
factory.register_plugin(plugin)

# 以降は get_optimizer() で名前で取得できる
opt = get_optimizer("my_annealer")
result = opt.solve(problem, timeout=5.0)

3. 環境変数で実行時に切り替える（EVOSPIKENET_PLUGIN_ALLOWLIST）

# 自組織プラグインを追加でロード可能にする
export EVOSPIKENET_PLUGIN_ALLOWLIST="evospikenet.plugins,myorg.plugins"

組み込みバックエンド詳細

classical（SimulatedAnnealing）

依存: なし
特徴: ランダムスワップによる SA。リアルタイム制約下のデフォルト。
options: seed (int)

qaoa_simulator

依存: なし
特徴: SA/SPSA/greedy を組み合わせた古典 QAOA 近似。
options: seed (int)

qiskit

依存: qiskit, qiskit-aer
特徴: Aer ローカルシミュレータ or IBMQ クラウド QPU
認証: 環境変数 IBMQ_TOKEN に IBM Quantum API トークンを設定
options: provider (str), token_env (str), reps (int), shots (int)
注記: VRP→Pauli operator マッピングは未実装。Aer 利用時は古典フォールバック。

export IBMQ_TOKEN="<your_ibmq_token>"

dwave

依存: dwave-ocean-sdk
特徴: D-Wave QPU / SimulatedAnnealing / Tabu サンプラー
認証: 環境変数 DWAVE_API_TOKEN, DWAVE_API_ENDPOINT
options: sampler ("QPU"|"SimulatedAnnealing"|"Tabu"), num_reads (int)
注記: dwave-ocean-sdk 未導入時は SA フォールバック。

export DWAVE_API_TOKEN="<your_dwave_token>"

Q-PFC との統合

QPFCQAOABridge から直接バックエンド名を渡すだけで切り替え可能です。

from evospikenet.qpfc_qaoa_bridge import QPFCQAOABridge

# クラシカル（デフォルト）
bridge = QPFCQAOABridge(backend="classical")

# QAOA シミュレータ
bridge = QPFCQAOABridge(backend="qaoa_simulator")

# Qiskit / IBMQ
bridge = QPFCQAOABridge(backend="qiskit")

# D-Wave
bridge = QPFCQAOABridge(backend="dwave")

ベンチマーク

# 100 試行 × 4 サイズ × 2 バックエンドでベンチ
PYTHONPATH=.:EvoSpikeNet-Core python EvoSpikeNet-Core/scripts/bench_qpfc_qaoa_bulk.py --n 100

# 効果量レポートを確認
cat EvoSpikeNet-Core/bench_reports/qpfc_qaoa_effect_sizes.md

動作確認済みバックエンド（2026年6月）

バックエンド	確認内容	meta.backend
`classical`	SAフォールバックなしで実行確認	`simulated_annealing`
`qaoa_simulator`	SA/SPSA 古典近似実行確認	`qaoa_simulator`
`openjij`	OpenJij SASampler 実機動作確認（トークン不要）	`openjij_sa`
`fixstars_amplify`	Fixstars Amplify AE 実機接続確認（`.env` から `FIXSTARS_TOKEN` 読み込み）	`fixstars_amplify_fixstars`
`dwave`	`dwave-ocean-sdk` 未導入時は SA フォールバック	`simulated_annealing`
`qiskit`	`IBMQ_TOKEN` 未設定時は SA フォールバック	`qiskit_fallback`

環境変数・.env 設定

.env ファイルは Products/.env に一元管理します。evospikenet.optimizer インポート時に自動読み込まれます。

# Products/.env  (すでに .gitignore 済み)
FIXSTARS_TOKEN=<your_fixstars_amplify_token>
IBMQ_TOKEN=<your_ibmq_token>
DWAVE_API_TOKEN=<your_dwave_token>
DWAVE_API_ENDPOINT=<your_dwave_endpoint>