SDK Common QUBO Problem Generation Guide

Updated: 2026-08-28

Purpose

This guide shows SDK users how to compile road routing, delivery allocation, low-altitude UAV corridors, high-altitude airspace choices, and generic binary decisions into a shared QUBO format. The generated QUBO is accepted by the existing D-Wave, OpenJij, Fixstars Amplify, Qiskit, and classical annealing backends.

Installation

The common builder requires only the normal Core installation.

cd EvoSpikeNet-Core
pip install -e .

OpenStreetMap road extraction is optional. Install it only in an environment that fetches live OSM road networks.

pip install -e '.[road]'

Cached road snapshots and automated tests use NetworkX graphs and require neither OSMnx nor network access.

Minimal Road Example

import networkx as nx
from evospikenet.optimization import RoadLocation, RoadNetworkBuilder, QuboProblemBuilder

graph = nx.MultiDiGraph()
graph.add_edge("hub", "depot", length=1200.0)
graph.add_edge("depot", "hub", length=1500.0)

locations = [RoadLocation("hub", 35.5492, 139.7898), RoadLocation("depot", 35.5312, 139.7029)]
snapshot = RoadNetworkBuilder().from_graph(graph, locations, {"hub": "hub", "depot": "depot"})
solver_input = QuboProblemBuilder().build(snapshot.to_optimization_problem("route-replan")).as_problem_dict()

Road graphs remain directed: \(d(i,j)\) can differ from \(d(j,i)\) because of one-way roads. Unreachable links are excluded from candidates rather than assigned an artificial cost.

Temporary Restrictions

Use DynamicConstraint for accidents, construction, closures, no-fly zones, weather, and unavailable vehicles.

from datetime import datetime, timedelta, timezone
from evospikenet.optimization import DynamicConstraint

now = datetime.now(timezone.utc)
closure = DynamicConstraint(
    constraint_id="closure-20260828-01",
    constraint_type="road_closure",
    severity="hard",
    candidate_ids=frozenset({"road:hub:depot"}),
    active_from=now,
    active_until=now + timedelta(minutes=30),
    penalty=10_000.0,
)

hard restrictions produce a prohibitive QUBO penalty and must also be checked before applying a solution. soft restrictions add a tunable detour or risk cost. Restrictions can target IDs or candidate attributes, and only active time windows are compiled.

Run the SDK Example

The offline sample creates directed road links, compiles a temporary closure, and prints the resulting solver input without downloading OSM data.

cd EvoSpikeNet-Core
python3.10 examples/sdk/programs/road_qubo_generation_demo.py

See Quantum Annealing Problem Generation Specification for the full design, QUBO constraints, and acceptance requirements. All solver output must pass application-level regulation, collision, and safety validation before operational use.