Fleet logistics with a live digital twin.
Q-FLUX formulates truck-to-order assignment as a QUBO and solves it with an annealer. Classical methods handle road routing, sequencing, feasibility repair, disruption analysis, and fuel planning.
When a disruption occurs, Q-FLUX identifies the affected orders, isolates them, and re-optimises only that part of the fleet.
Python 3.11 or newer. Tested on 3.11, 3.12 and 3.14.
dimod==0.12.22dwave-neal==0.6.0dwave-samplers==1.8.0
networkx==3.6.1numpy==2.5.2scipy==1.18.0
fastapi==0.141.1uvicorn==0.52.3
dwave-system==1.36.0
Only needed when QFLUX_USE_QPU=1 and a Leap token is available.
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/uvicorn qflux.backend.app:app --port 8000Open http://localhost:8000.
Optional: requirements-baseline.txt adds OR-Tools for the CP-SAT baseline. The rest of the application runs without it.
- Generate World — 4 depots, 40 mixed trucks, 150 orders, and ~690 roads with road classes, tolls, congestion, and fuel stations.
- Plan Initial Routes — orders are partitioned into zones and each zone is solved as a QUBO.
- Disrupt — simulate a breakdown, road closure, or urgent orders.
- Re-optimise Zone — isolate affected orders and re-solve only that zone.
- Eliminate Deadhead — assign collections to suitable trucks already returning home.
The seed, truck count, order count, and disruption target can be changed from the interface.
Click a truck to isolate its route. Forty routes over one road network is forty overlapping lines. Clicking a truck on the map or in the fleet roster highlights the specific path and shows statistics related to it. Click again, or on bare map, to release it. Double-click a roster row to centre the map on that truck instead.
A truck carrying nothing says why. Three different things produce a
0 · 0% row and only one of them is a defect, so the roster names which:
| Reason | What it means |
|---|---|
| no driver | driver availability filtered it out of every order |
| held in reserve | eligible, but at its cost per km cheaper trucks covered the demand. This is the spare capacity a breakdown draws on, and re-optimisation does put it to work |
| no legal road out | no road leaving its depot is drivable by that class |
Pick the disruption yourself. By default the seed chooses what breaks but you can pick a spot to apply disruption as well. Press Pick target on map and the map arms: click the road to close, the truck to break down, or the place the urgent orders should land. Nearest to the click is affected, Esc cancels.
world generator ──► digital twin (server-side state)
│
┌───────────────────┴──────────────────────────────────┐
│ initial routing disruption path │
│ partition propagate │
│ │ isolate │
│ └────────┬─────────────┘ │
│ per zone: │
│ eligibility (filter) │
│ build QUBO (dimod) │
│ anneal (neal) │
│ repair (classical) │
│ sequence + fuel (classical) │
│ cost + baseline (CP-SAT, greedy, annealer) │
└──────────────────────────────────────────────────────┘
│
FastAPI ──► Leaflet front-end
Before building the QUBO, impossible truck-order combinations are removed.
Examples:
- truck road restrictions
- capacity
- refrigeration
- hazmat compatibility
- driver availability
- fuel range
- blocked or unreachable roads
H = A·H_assign + B·H_capacity + C·H_hazmat + Σ cost[o,t]·x[o,t]
x[o,t] is 1 when order o is assigned to truck t.
Only eligible truck-order pairs become variables. Assignment, capacity, and hazmat constraints contribute QUBO penalties; mileage, tolls, travel time, priority, deadline lateness, and cross-depot drift contribute to the assignment cost.
The demo uses neal.SimulatedAnnealingSampler. Each read is an independent annealing run, and the lowest-energy sample found is used as the assignment.
Set QFLUX_USE_QPU=1 with a D-Wave Leap token to use LeapHybridSampler. The same BQM is used in either case; failures fall back to neal.
The QUBO decides which truck gets which order. Actual road paths are calculated classically on the NetworkX road graph.
After assignment, the classical pipeline performs:
- feasibility repair
- nearest-neighbour sequencing
- 2-opt improvement
- fuel-stop insertion
- return to home depot
The current prototype uses deterministic graph-based impact propagation:
known disruption
↓
route consequences
↓
displaced traffic / congestion
↓
affected orders
↓
new deadline risk / unreachable assignments
For road closures, affected trucks are rerouted on the blocked graph, displaced traffic is added to the roads used by those detours, congestion multipliers are updated, stranded orders are detected, and newly late orders are added to the affected set.
A future version can augment this stage with an AI/ML traffic-impact model using historical and live data.
After impact analysis, only the affected orders are isolated. The new zone is passed through the same pipeline:
affected orders
↓
new candidate trucks
↓
eligibility
↓
new QUBO
↓
annealing
↓
repair + re-sequencing
↓
splice back into the live plan
Untouched assignments remain in the digital twin.
Every order is one of two directions:
- Delivery: depot → order node
- Collection: order node → home depot
Collections are deliberately left out of the initial solve. They are held for the Eliminate Deadhead stage, where returning trucks can pick them up on the way home.
The same zone-QUBO engine is used to choose among feasible return-leg opportunities.
The deadhead stage:
- Finds pending collections
- Keeps trucks already running a return leg
- Filters out trucks that cannot legally serve the collection
- Calculates the additional detour required to reach the collection and continue home
- Sends the resulting assignment problem through the same QUBO engine
Collections outside the configured detour threshold remain pending rather than forcing dedicated trips.
The world generator keeps generated demand within physically reachable fleet capacity. During planning, unplaced orders can be recovered through widened candidate pools and the fleet-wide sweep-up stage.
The system reports unplaced or undeliverable orders explicitly.
Each zone can be evaluated with:
- Annealer / QUBO
- Greedy assignment
- OR-Tools CP-SAT
All three use the same eligible truck-order pairs and the same assignment objective. All the wins and losses are displayed honestly with exact percentage change.
Default world:
| Parameter | Value |
|---|---|
| Depots | 4 |
| Trucks | 40 |
| Orders | 150 |
| Deliveries | 120 |
| Collections | 30 |
| Road network | ~400 nodes / 684 roads |
| Zones | 13 |
| Largest initial QUBO | ~51 variables |
Using seed 9 with a road-closure disruption:
- Initial plan: 6256
- Re-optimized plan: 6669
- Do-nothing after closure: 7259
- Saving vs. riding out the disruption: 590 (8.13%)
- 13 orders moved across 7 trucks
- Annealer: 5743
- Greedy: 5876
- Proven assignment optimum: 5670
- Annealer gap: 1.29%
- Optimum reached on 4 of 13 zones
- 27 of 30 collections folded into existing return legs
Shows the per-stage explain feed for the current run.
Shows the active constraints and how they are enforced:
- filter - removes variables before the QUBO
- weight - contributes to the assignment cost
- penalty - increases QUBO energy for violations
The tab also shows the generated QUBO and its actual penalty coefficients.
Shows the annealer, greedy assignment, and OR-Tools CP-SAT results per zone and in total.
| Constraint | How | Status |
|---|---|---|
| Truck type & size vs road | graph refuses illegal road types per class | full |
| Capacity & refrigeration | filter + pairwise QUBO penalty | full |
| Fuel range & mileage | range filter, mileage weight, reserve-based refuelling | full |
| Blocked roads & detours | edge.blocked + NetworkX reroute |
full |
| Tolls & distance | weight in edge cost | full |
| Priority / urgency | weight (bonus) | full |
| Multiple warehouses | zone partition respects owning depot | full |
| Driver availability | filter | full |
| Travel time | road speed + congestion + service time, weighted into cost | full |
| Delivery deadlines | soft lateness cost, not a hard time window | proxy |
| Hazmat co-load | pairwise conflict handling | proxy |
| Return to home depot | sequencing + drift penalty | proxy |
Q-FLUX is a prototype for integrating quantum optimization into a practical logistics pipeline.
Current limitations:
- The road network is synthetic; there is no real map or telematics data.
- The digital twin is in-memory and single-session.
- Deadlines are soft penalties, not hard time windows.
- Stop sequencing is classical.
- The current disruption model is a single-shot traffic response, not a traffic equilibrium.
Future work includes richer traffic prediction, larger optimization models, and execution on quantum-annealing hardware.