Fleet Routing and Dispatch Optimizer

Purpose

Fleet Routing and Dispatch Optimizer solves practical vehicle routing and dispatch scheduling under real operational constraints.

It supports:

• Multi-vehicle route planning
• Capacity-constrained dispatch
• Time-window-aware service sequencing
• Trade-off optimization (distance, time, fleet size)

Use this tool when dispatch decisions must be reproducible, explainable, and cost-accountable.

Typical Questions This Tool Helps Answer

• What is the lowest-cost dispatch plan that still respects capacity and time-window constraints?
• How many vehicles are actually required to meet today's service commitments?
• Which stops are most at risk of lateness or unmet demand under current fleet assumptions?

Problem Class

This tool addresses variants of VRP (Vehicle Routing Problem):

• CVRP: capacitated VRP
• VRPTW: VRP with time windows
• Multi-depot routing
• Soft-constraint scenarios with penalty costs

Background

Fleet routing and dispatch optimization solves a constrained vehicle-routing problem (VRP) where objective quality and operational feasibility must be balanced. A common scalarized form is:

$$\min\left(w_d D + w_t T + w_v V + w_p P\right)$$

Where $D$ is total distance, $T$ is total travel/service time, $V$ is vehicles used, and $P$ aggregates violation penalties (late arrivals, overtime, unmet demand).

Constraint System

Operational feasibility is defined by interacting constraints:

• Vehicle capacity and compatibility.
• Depot start/end and shift limits.
• Time-window feasibility at each stop.
• Service-time inclusion and break rules.

Small data-quality errors in any constraint dimension can invalidate apparently strong objective scores.

Solver Strategy and Trade-Offs

Practical pipelines often use fast constructive seeds (for example Clarke-Wright/sweep), then local or metaheuristic improvement (2-opt, relocate/swap, tabu, GA, annealing). The key trade-off is solve time versus marginal quality gain and scenario throughput.

Robustness and Scenario Use

Dispatch recommendations should be stress-tested under demand variance, closure events, and travel-time inflation. Robust plans maintain acceptable KPI behavior across perturbations, not only in a nominal run.

Methodological Considerations

• Validate constraint completeness before objective tuning.
• Compare alternative weight vectors to expose Pareto-like trade-offs.
• Report both objective values and violation diagnostics for governance.

Practical Interpretation Pitfalls

A lower objective score is not automatically operationally superior if it relies on brittle assumptions or pushes service equity below acceptable policy thresholds.

Inputs

Critical Input Hygiene

• Ensure network connectivity (no disconnected critical subgraphs)
• Use projected CRS for network/depots/stops (tool enforces projected CRS when known)
• Ensure demand and capacity units match (weight, volume, pallets, etc.)
• Ensure stop demand values are non-negative and realistic for fleet capacity

Vector Attribute Expectations

• depots attribute lookup priority for depot id: depot_id, DEPOT_ID, id, ID.
• stops attribute lookup priority for stop id: stop_id, STOP_ID, id, ID.
• stops demand field lookup: demand, DEMAND (default when missing: 1.0).
• stops service time field lookup: service_time_minutes, SERVICE_TIME_MINUTES, service_time, SERVICE_TIME (default when missing: 10.0).

vehicles_csv Schema (Authoritative)

Header (recommended):

vehicle_id,capacity,available_time_minutes,cost_per_minute,cost_per_km,depot_id

• Exactly 6 columns are required per non-empty row.
• Header row is optional but, if present, must include vehicle_id on row 1 to be auto-detected as header.
• capacity, available_time_minutes, cost_per_minute, and cost_per_km must parse as numeric values.

Example:

vehicle_id,capacity,available_time_minutes,cost_per_minute,cost_per_km,depot_id
truck_01,1200,540,0.65,1.20,depot_west
truck_02,800,480,0.58,1.05,depot_east

restrictions Schema (Optional)

Required columns:

from_x,from_y,to_x,to_y

Optional columns:

• penalty_factor (alias: penalty) default 1.0
• closed (alias: is_closed) default false

Accepted truthy values for closure: 1, true, yes, y (case-insensitive).

Example:

from_x,from_y,to_x,to_y,closed,penalty_factor
500120.0,4820030.0,500240.0,4820035.0,true,1.0
500300.0,4820100.0,500410.0,4820108.0,false,1.8

Parameters

objective

• minimize_distance: fuel and mileage focus
• minimize_time: SLA/response-time focus
• minimize_cost: direct optimization of (distance_km * cost_per_km) + (time_minutes * cost_per_minute)
• balanced: compromise score across distance, time, and cost

Output Path Parameters (Required)

• routes_output: path extension controls vector format (for example .shp, .geojson, .gpkg).
• assignment_csv_output: written as CSV with assignment rows.
• route_kpis_csv_output: written as CSV with per-route rows and a FLEET_TOTAL summary row.
• exceptions_csv_output: written as CSV with one row per failed stop assignment.

html_report

• If provided, an HTML summary file is generated in addition to CSV/vector outputs.
• HTML report includes run summary counts and key output paths for packaging.

Outputs

Output artifact keys below are runtime outputs, not input parameters.

Output File Schemas

routes_output attributes:

• ROUTE_ID
• VEHICLE_ID
• DEPOT_ID
• STOP_COUNT
• DIST_KM
• TIME_MIN
• COST

assignment_csv_output columns:

stop_id,route_id,vehicle_id,sequence_order,arrival_time_minutes,departure_time_minutes

route_kpis_csv_output columns:

vehicle_id,route_id,capacity_utilization_pct,distance_km,time_minutes,cost_units,stop_count

Notes:

• Includes a final fleet aggregate row with vehicle_id=FLEET_TOTAL and route_id=FLEET_TOTAL.

exceptions_csv_output columns:

stop_id,reason

Common reason values:

• demand_exceeds_max_vehicle_capacity
• no_feasible_route

Result Payload Keys

In addition to output files, the run result contains keys for orchestration and auditing:

• status
• routes_count
• stops_assigned
• stops_failed
• objective
• routes
• assignment_csv
• route_kpis_csv
• exceptions_csv
• summary
• html_report (only when requested)

Interpreting KPIs in route_kpis_csv_output

• capacity_utilization_pct: percentage of route capacity consumed by assigned stop demand.
• distance_km: full loop distance including return to depot.
• time_minutes: travel plus service time, including return leg travel time.
• cost_units: computed from distance and time using per-vehicle coefficients.

Validation Workflow

Before Operational Use

1. Run baseline scenario with historical dispatch data
2. Compare against known outcomes (distance, overtime, late stops)
3. Validate stop sequence plausibility with dispatch team

Sensitivity Testing

1. Vary demand by +/-10%
2. Remove one vehicle and compare service impact
3. Tighten time windows and inspect infeasibility growth

Field Validation

1. Pilot with one depot/day
2. Capture driver deviations and ground truth constraints
3. Feed corrections back into network and timing assumptions

Troubleshooting

Example: Daily Last-Mile Dispatch

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment()
wbe.working_directory = "/data/logistics_daily"

wbe.fleet_routing_and_dispatch_optimizer(
        network="metro_network.shp",
        depots="depots.shp",
        stops="orders_2026_05_14.shp",
        vehicles_csv="fleet_profile.csv",
        objective="balanced",
        restrictions="road_restrictions.csv",
        edge_cost_field="MINUTES",
        routes_output="out/routes_2026_05_14.geojson",
        assignment_csv_output="out/assignment_2026_05_14.csv",
        route_kpis_csv_output="out/kpis_2026_05_14.csv",
        exceptions_csv_output="out/exceptions_2026_05_14.csv",
        html_report="out/fleet_dispatch_2026_05_14.html"
)

Any WbEnvironment instance name is valid (wbe above is only an example).

Example: Emergency Utility Service Calls

wbe.fleet_routing_and_dispatch_optimizer(
        network="utility_response_network.shp",
        depots="service_crews.shp",
        stops="incident_calls.shp",
        vehicles_csv="crew_truck_capabilities.csv",
        objective="minimize_time",
        edge_cost_field="MINUTES",
        routes_output="out/utility_routes.geojson",
        assignment_csv_output="out/utility_assignments.csv",
        route_kpis_csv_output="out/utility_kpis.csv",
        exceptions_csv_output="out/utility_exceptions.csv"
)

Implementation Practices

• Store each run with a scenario ID and immutable input snapshot
• Publish only routes that pass dispatch sanity checks
• Maintain separate tactical (fast) and strategic (deep) optimization profiles

Related Tools

• network_readiness_and_diagnostics_intelligence
• service_area_planning_and_coverage_optimization
• emergency_scenario_routing_and_accessibility_simulator

References

• Toth, P., & Vigo, D. (2014). Vehicle Routing: Problems, Methods, and Applications (2nd ed.). SIAM.
• Laporte, G. (2009). Fifty years of vehicle routing. Transportation Science, 43(4), 408-416.

Parameter Interaction Notes

For Fleet Routing and Dispatch Optimizer, output quality is most sensitive to parameter combinations rather than single values in isolation.

• objective and vehicle cost coefficients interact strongly: - minimize_cost only behaves as expected when cost_per_minute and cost_per_km are calibrated to real economics. - balanced can reduce extreme route shapes but may not minimize any single KPI.
• available_time_minutes and service_time_minutes jointly control assignment feasibility; high service durations can dominate travel-time improvements.
• Restriction closures (closed=true) can rapidly increase infeasibility; inspect exceptions_csv_output after each closure scenario.

QA and Acceptance Criteria

Use a staged acceptance approach for Fleet Routing and Dispatch Optimizer:

1. Input integrity: validate projected CRS, network connectivity, depot-stop coverage, and CSV schema correctness.
2. Method validity: run a pilot dispatch day and compare route order against dispatch-team expectation.
3. Output plausibility: verify route loops return to depot and KPI magnitudes are operationally realistic.
4. Reproducibility: rerun with identical inputs and confirm stable assignment/KPI outputs.

Recommended acceptance checks:

• Every output artifact exists at the requested path.
• assignment_csv_output rows are consistent with route stop counts.
• route_kpis_csv_output contains the final FLEET_TOTAL row.
• exceptions_csv_output reasons are explainable and actionable.

Advanced Operational Guidance

For production deployment of Fleet Routing and Dispatch Optimizer:

• Maintain a versioned parameter profile (e.g., exploratory, standard, compliance).
• Store run metadata with input hashes, parameter JSON, and timestamp for auditability.
• Lock route output format by extension (for example, .gpkg for enterprise geodatabases, .geojson for interoperability).
• Use scenario-specific restrictions files rather than editing network geometry for temporary closures.

Implementation Patterns

Common implementation patterns with Fleet Routing and Dispatch Optimizer:

• Baseline run: produce first-pass outputs with balanced defaults.
• Sensitivity run: vary 1-2 high-impact parameters to assess stability.
• Production run: lock accepted profile and generate deliverables.
• Monitoring run: repeat with identical profile on new data for change tracking.

Related Tools

Use Fleet Routing and Dispatch Optimizer together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Fleet Routing and Dispatch Optimizer is most valuable when teams need measurable service-level improvements (coverage, response time, cost-to-serve) with governance-ready transparency.

What this workflow helps you achieve:

• Translates network complexity into decision-ready options.
• Supports defensible operational planning with explicit constraints.
• Creates repeatable workflows for quarterly and annual optimization cycles.

Results Delivery Checklist

Before sharing results with stakeholders:

1. Validate network topology and impedance attributes for all served areas.
2. Confirm objective function matches business KPI priorities.
3. Document constraints (capacity, time windows, exclusions) in deliverable notes.
4. Provide baseline-vs-optimized comparison metrics.
5. Include at least one scenario stress test (demand spike, outage, or route closure).

Common Questions

Q: Which result should I review first? A: Start with baseline-vs-optimized KPI changes for coverage, response time, and cost-to-serve.

Q: What is a common interpretation mistake? A: Assuming a better objective score means the plan is deployable without verifying all constraints are respected.

Q: Which settings most affect recommended routes? A: Demand assumptions, enabled constraints, and objective weighting usually have the largest effect on dispatch outcomes.

Q: How should teams use these outputs operationally? A: Pilot the optimized schedule in a controlled service window, compare realized KPIs to baseline, then scale rollout if performance holds.