Under the hood
How does the algorithm work?
VolitionDrive does not pick the cheapest station on the map. It searches sequences of stops so you never run below your reserve, counting detours, stop hassle, and what leftover fuel is worth at the destination.
1. Big picture
Given a route, your tank, starting fuel, consumption, and live station prices, the planner looks for the cheapest feasible sequence of refuels. “Cheapest” means money paid at the pump, minus a cautious credit for fuel you still hold at arrival, plus soft penalties for every stop and every detour kilometre.
Goal: arrive with the reserve intact (or a full tank if you asked for it), without comparing prices across different currencies.
2. Build the fuel corridor
First the road is fetched from OSRM. Stations are then pulled from official open-data feeds around samples of that path.
- Sample the route about every 8 km and keep stations within ~3 km of the line.
- Project each station onto the nearest point on the route → a kilometre marker and a lateral offset.
- Estimate the real detour: roughly 2 × offset × 1.4 on ordinary roads; motorways use exit / service-area rules, and opposite-carriageway stops are dropped.
Why sample a corridor?
Searching every station in a country would be slow and irrelevant. A thin band along the drive is where a rational stop can happen without a huge detour.
3. Tank physics
Before optimising prices, the planner computes how far you can legally go on the usable part of the tank. The reserve percentage (default 20%) is never planned below on any leg or at arrival.
usable liters = tank × (1 − reserve%)
range (km) = usable ÷ (consumption L/100 ÷ 100)
fuel for a leg (L) = distance_km × consumption / 100
Why a hard reserve?
Plans that empty the tank look great on paper and fail in traffic, hills, or a closed station. The reserve is your safety buffer; you can tighten or loosen it in the cockpit.
4. Shrink the search
Hundreds of corridor stations explode the search space. Along each short stretch of road the planner keeps only two representatives: the cheapest station and the easiest one to reach (smallest detour).
- Cluster width ≈ max(1.5 km, route_km / 300).
- Ties break toward the other objective (price vs detour).
Why not keep every station?
Neighbours a few hundred metres apart rarely change the optimal story. Keeping cheapest + easiest preserves real choices without drowning the search.
5. Choose what to buy at each stop
The core is a forward search over states: “stopped at station i with f liters left.” From each state it tries a few purchase sizes, then drives to later stations you can still reach with the reserve intact.
Exact — buy just enough to reach a later stop (or the destination) with the reserve.
Minimum — if “just enough” is tiny, buy at least ~10 L so the stop is worth pulling over.
Bridge — a smaller ~5 L top-up only allowed to reach a proper fill at the very next stop.
Fill — top the tank when carrying cheap fuel forward beats buying later.
Arrival fill — optional: end by filling near the destination (within ~8 km).
Why bridges and minimums?
A 1 L stop wastes time. A short bridge is allowed only as a stepping stone into a real purchase, so the plan never strings together tiny dribbles.
6. Score every plan
Pump cost alone would favour absurd detours for a one-cent saving. Each stop therefore adds a convenience penalty priced in “liters at the corridor median,” and leftover fuel at the destination is credited at 95% of the local price so carrying cheap fuel only wins when it is clearly cheaper.
stop penalty (€) = (1 L + 0.35 L/km × detour_km) × median_price
score = money_paid − spare_fuel_credit
spare credit = max(0, arrival_fuel − floor) × 0.95 × destination_price
Why 95%, not 100%?
Full credit would happily arrive with a heavy tank of “cheap” fuel that might not beat buying locally once uncertainty and hassle are included. The 5% haircut keeps the bias toward not over-carrying.
7. Currency borders
When the corridor crosses a currency (for example EUR → GBP), the route is split into legs at the midpoint between the last station of one currency and the first of the next. Each leg is optimised alone. Fuel carried across the border gets no spare-fuel credit, and the next leg must start with enough fuel to reach its first station with the reserve intact.
Why split by currency?
A litre in euros is not a litre in pounds. Comparing them in one objective would invent fake savings. Separate legs keep the maths honest.
8. Savings story & top-up hint
After a plan is found, VolitionDrive compares it to a simple baseline: the average price of highway stations on the corridor (or all corridor stations if none are marked highway). That difference is the “saved vs baseline” figure.
Baseline = average of highway prices when available, else corridor average.
If you did not request a full arrival tank, but filling completely at the last stop would still beat buying those litres near the destination (by at least ~€1 on ≥5 L), the UI surfaces that as an optional top-up hint — it is not forced into the plan.
Play with the trade-off
A stop only wins if the price gap covers the convenience penalty. Drag the sliders: how cheap does a station need to be, for how large a fill, before a detour is worth it?
Break-even liters = stop penalty ÷ price gap
Worth stopping — break-even fill is about 6.0 L.