A professional Python project for logistics optimization, operational intelligence, scenario simulation, and geospatial routing.
This project simulates a realistic industrial logistics operation, optimizes vehicle routes with Operations Research, evaluates operational KPIs, stress-tests business scenarios, exposes results through a FastAPI backend, and includes an advanced OpenStreetMap road-network routing module.
Industrial, logistics, energy, manufacturing, and supply chain companies must decide every day:
- Which vehicle should serve each customer?
- In what order should deliveries be made?
- Can the fleet satisfy demand within delivery time windows?
- What happens if demand increases or vehicles become unavailable?
- How much cost can be reduced through better route planning?
This project turns those operational decisions into a reproducible optimization system.
The project compares a simple baseline routing heuristic against a formal OR-Tools optimization engine.
| Metric | Baseline Heuristic | Optimized OR-Tools | Impact |
|---|---|---|---|
| Total Distance | 689.60 km | 396.60 km | -293.00 km |
| Total Travel Time | 921 min | 529 min | -392 min |
| Late Deliveries | 9 | 0 | -9 |
| On-Time Delivery Rate | 70.00% | 100.00% | +30 pts |
| Total Cost | 10948.14 | 7914.44 | -3033.70 |
- Python software engineering
- Operations Research
- Vehicle Routing Problem
- Capacitated routing
- Time windows
- Scheduling constraints
- Scenario simulation
- Supply chain analytics
- Logistics cost analysis
- KPI engineering
- FastAPI backend development
- Docker deployment
- Geospatial analytics
- OpenStreetMap road-network modeling
- NetworkX shortest-path routing
See the full architecture diagram here:
docs/architecture.md
This project intentionally evolved through realistic engineering iterations.
The first version used abstract x/y coordinates and Euclidean distance. This was useful for learning and validating the optimization logic.
Limitation:
The first Folium map looked unrealistic because Folium interpreted abstract x/y coordinates as real latitude/longitude coordinates.
The project was upgraded to use realistic latitude/longitude-style coordinates around the Monterrey metropolitan industrial area.
Improvements:
- Depot located around Apodaca industrial area
- Customers distributed across Monterrey, San Nicolas, Apodaca, Guadalupe, Escobedo, Santa Catarina, San Pedro, Cadereyta, Garcia, and Pesqueria
- Haversine distance
- Road-distance factor
- Realistic travel-time estimates
- Folium maps now look geographically credible
An optional advanced routing module was added using:
- OSMnx
- NetworkX
- OpenStreetMap road networks
- Shortest-path road distances
- Travel-time matrices from real roads
The large OSM graph is cached locally and excluded from Git version control to keep the repository clean and professional.
| Component | Description |
|---|---|
| Data Generator | Creates realistic depot, customer, vehicle, demand, time-window, and priority data |
| Distance Matrix Builder | Builds Haversine-based distance and travel-time matrices |
| Baseline Heuristic | Creates a simple nearest-neighbor baseline route plan |
| OR-Tools Optimizer | Solves a capacitated Vehicle Routing Problem with Time Windows |
| KPI Calculator | Calculates cost, distance, time, delivery performance, and fleet utilization |
| Scenario Engine | Generates operational what-if scenarios |
| Scenario Runner | Runs optimization across all scenarios |
| Scenario Visualizations | Creates KPI comparison charts |
| Folium Maps | Generates interactive route maps |
| FastAPI Backend | Serves KPI and scenario results through API endpoints |
| Docker Deployment | Runs the API in a reproducible container |
| OSM Routing Engine | Builds real-road distance/time matrices using OpenStreetMap |
The platform evaluates multiple industry-style scenarios:
| Scenario | Business Meaning |
|---|---|
| High Demand +40% | Peak season, campaign day, urgent operational surge |
| Fewer Vehicles | Vehicle breakdowns, driver shortage, maintenance downtime |
| Fuel Cost +35% | Diesel increase or higher subcontractor rates |
| Capacity Reduction -25% | Weight restriction, safety policy, or partial loading constraint |
| Scenario | Distance km | Travel Time min | Demand Served | Deliveries | On-Time Rate | Vehicles | Utilization | Total Cost |
|---|---|---|---|---|---|---|---|---|
| Capacity Reduction 25% | 370.33 | 494 | 448 | 25 | 100% | 6 | 96.34% | 7600.89 |
| Fewer Vehicles 4 Available | 298.22 | 398 | 393 | 23 | 100% | 4 | 98.25% | 5429.17 |
| Fuel Cost Increase 35% | 396.60 | 529 | 586 | 30 | 100% | 6 | 94.52% | 9564.38 |
| High Demand 40% | 384.81 | 513 | 605 | 25 | 100% | 6 | 97.58% | 7762.28 |
industrial-logistics-optimization/ ├── api/ │ └── main.py ├── data/ │ ├── raw/ │ ├── processed/ │ ├── scenarios/ │ ├── scenario_results/ │ └── osm/ ├── docs/ │ └── architecture.md ├── reports/ │ ├── figures/ │ └── maps/ ├── src/ │ └── logistics_optimization/ │ ├── data_generator.py │ ├── data_generator_v1_synthetic.py │ ├── distance_matrix.py │ ├── baseline_heuristic.py │ ├── ortools_optimizer.py │ ├── kpi_calculator.py │ ├── scenario_engine.py │ ├── scenario_runner.py │ ├── scenario_visualizations.py │ ├── visualizations.py │ ├── interactive_maps.py │ └── osm_routing_engine.py ├── Dockerfile ├── requirements.txt ├── .dockerignore ├── .gitignore └── README.md
python3 -m venv .venv source .venv/bin/activate
python -m pip install --upgrade pip pip install -r requirements.txt
python src/logistics_optimization/data_generator.py
python src/logistics_optimization/distance_matrix.py
python src/logistics_optimization/baseline_heuristic.py
python src/logistics_optimization/ortools_optimizer.py
python src/logistics_optimization/kpi_calculator.py
python src/logistics_optimization/scenario_engine.py python -m src.logistics_optimization.scenario_runner
python src/logistics_optimization/visualizations.py python src/logistics_optimization/scenario_visualizations.py python src/logistics_optimization/interactive_maps.py
Run the API locally:
python -m uvicorn api.main:app --reload
Open:
http://127.0.0.1:8000/docs
Available endpoints:
| Endpoint | Description |
|---|---|
| GET / | API root |
| GET /health | Health check |
| GET /kpis/base | Returns baseline KPIs |
| GET /kpis/scenarios | Returns scenario comparison KPIs |
| POST /run-scenarios | Re-runs all operational scenarios |
Build the Docker image:
docker build -t industrial-logistics-optimization .
Run the API container:
docker run --rm -p 8001:8000 industrial-logistics-optimization
Open:
http://127.0.0.1:8001/docs
The project includes an optional OpenStreetMap routing engine.
Run:
python src/logistics_optimization/osm_routing_engine.py
This generates:
data/osm/locations_with_osm_nodes.csv data/osm/osm_distance_matrix_km.csv data/osm/osm_time_matrix_min.csv
The downloaded road network graph is stored locally as:
data/osm/monterrey_drive_network.graphml
This file is intentionally ignored by Git because it is large and can be regenerated.
| Decision | Reason |
|---|---|
| Baseline heuristic included | Creates a realistic comparison point |
| OR-Tools used | Industry-grade optimization library |
| Haversine distance | Better approximation for geographic coordinates |
| Road factor applied | Approximates real road distance from straight-line distance |
| Folium maps | Visual validation of route geography |
| Scenario engine | Simulates operational risk and stress cases |
| FastAPI | Turns analysis into a usable backend service |
| Docker | Makes deployment reproducible |
| OSMnx and NetworkX | Adds advanced real-road routing capability |
| Large OSM graph excluded from Git | Keeps repository clean and professional |
This system helps logistics and operations teams answer practical business questions:
- Can the current fleet satisfy demand?
- Which routes reduce cost and delivery time?
- What operational constraints create bottlenecks?
- What happens if demand increases?
- What happens if fleet availability drops?
- How sensitive is the operation to fuel cost?
- Which scenarios reduce service level?
A concise way to explain the project:
"I built an industrial logistics optimization platform in Python. It simulates a realistic vehicle routing operation around the Monterrey industrial area, generates customer demand and time windows, compares a nearest-neighbor baseline against an OR-Tools Vehicle Routing Problem optimization model, calculates operational KPIs, stress-tests scenarios like demand surges and fleet reductions, visualizes routes with Folium, exposes results through FastAPI, containerizes the backend with Docker, and includes an advanced OpenStreetMap routing engine using OSMnx and NetworkX."
- Python
- Pandas
- NumPy
- Matplotlib
- Folium
- FastAPI
- Docker
- OR-Tools
- OSMnx
- NetworkX
- Operations Research
- Vehicle Routing Problem
- Scenario Simulation
- KPI Engineering
- Geospatial Analytics
- Supply Chain Analytics
- Logistics Optimization
- Decision Support Systems
- Use real traffic data
- Integrate OSRM for road-based routing at scale
- Add Streamlit dashboard
- Add customer priority penalties
- Add multi-depot routing
- Add driver shift scheduling
- Add stochastic demand simulation
- Add CI/CD checks
- Deploy API to cloud
Portfolio-grade prototype completed.
The project demonstrates practical optimization, operations analytics, geospatial modeling, backend deployment, and business-impact communication.
