DeliverySim

sim_compact_com.mp4

A delivery route optimization and visualization dashboard for an Instacart-like business model. This system simulates and optimizes delivery operations using real-world data from San Francisco. Also supports returns and return paths. All modeling is probablistic based on demand rates (changeable parameters). Assumes orders are received at start of time period (i.e. at start of day, hr, week, etc)

Features

Category	Description
Simulation Engine	Real-time computational simulation tracking driver positions, package states, house and retailer statuses
Interactive UI	Frontend displaying driver paths, package heatmaps, and key metrics ($/package, total cost, driver time)
VRP Solver	Google OR-Tools implementation for complex routing with pickup/delivery constraints
Optimization	Multiple modes (time, cost, distance) for route optimization
Data	San Francisco housing and retail locations with optional traffic simulation
Architecture	Object-oriented design for all system components (drivers, retailers, packages, houses)

Installation

# Clone the repository
git clone https://github.com/yourusername/DeliverySim.git
cd DeliverySim

# Install dependencies
pip install -r requirements.txt

Usage

Running the Dashboard

python app/app.py

Navigate to the provided local URL to access the interactive dashboard interface where you can watch the simulation unfold in real-time.

Running Simulations

# Run a basic simulation with default parameters
python sim/BasicSim.py

NOTE: it is useful to adjust the solver parameters. The solver max time determines the accuracy of the solution. Increase it for a better solution. For example,

OR_TOOLS_TIME_LIMIT_SECONDS = 60*5 # five minute solve-time per day

You can also adjust the mean number of packages by adjusting this parameter:

# Package Delivery Rates
MEAN_PACKAGE_PER_DAY_PER_HOUSE = -1 # mean num packages, normal dist, std=1. I recommend values from -1 to 1.

You may need to increase solve times as the number of packages increases (otherwise a valid solution may not be found).

Project Structure

• app/: Web dashboard and visualization components using Flask and SocketIO
• consts/: Configuration constants, distance matrices, and world variables
• objects/: Core object models (drivers, packages, retailers, homes, locations)
• sim/: Simulation logic including OR-Tools VRP implementation
• utils/: Helper utilities
• data/: Simulation run history and results

Switching cities

The uploaded (to this repo) distance matrices are only for SF. You can create your own for any city by modifying the following:

1. Change the city name in consts/world_variables.py:

2. Update the retailer and home coordinates in consts/consts.py to match locations in your chosen city. The current lists (list_of_retailer_coords and list_of_home_coords) contain San Francisco coordinates only.

3. Configure traffic and cost settings in consts/consts.py:

   # Traffic Settings
   ADD_TRAFFIC_DELAYS = True  # Set to False if you don't want traffic delays
   STOPSIGN_EXPECTED_DELAY = 5  # seconds
   STOPLIGHT_EXPECTED_DELAY = 10  # seconds
   
   # Cost type for distance matrix
   DISTANCE_MATRIX_COST_TYPE = 'money'  # Options: 'length', 'time', 'money'. If money, uses a calculated rate of min_wage * time + mile_rate * miles driven

4. Generate a new distance matrix by starting the sim. The sim will take longer than normal and eventually generate a distance matrix.:

   python app/app.py

5. The new distance matrix will be saved as distance_matrix.json in the root directory. You can move this to the consts/distance_matrices/ directory if you want to keep multiple matrices.

6. If you want to generate matrices with different settings (with/without traffic, cost vs time vs distance, etc), you can:

   • Change the ADD_TRAFFIC_DELAYS setting
   • Run the generation command again
   • Save each matrix with a descriptive name in the consts/distance_matrices/ directory

Note: Generating a distance matrix can take significant time depending on the number of locations and the size of the city's road network. The system uses OSMnx to download the street network data for your specified city.

Configuration Parameters

The simulation is highly configurable through parameters in consts/consts.py. Key parameters include:

Visualization Settings

• RUN_HEADLESS: Controls whether to run in browser (visual) or headless mode (faster)
• SHOW_ANY_EDGES: Toggle for displaying map edges
• SHOW_DETAILED_EDGES: Show detailed edge information when edges are displayed

Traffic Settings

• ADD_TRAFFIC_DELAYS: Enable realistic traffic delay simulation
• STOPSIGN_EXPECTED_DELAY: Average delay at stop signs (seconds)
• STOPLIGHT_EXPECTED_DELAY: Average delay at traffic lights (seconds)

Simulation Control

• TIMESTEP_RATE: Time between state updates (seconds)
• SCALING_FACTOR: Simulation time per second of real time (accelerates simulation)
• SIMULATION_LENGTH_DAYS: Total simulation duration in days

Delivery Parameters

• MEAN_PACKAGE_PER_DAY_PER_HOUSE: Average number of packages per house per day
• DRIVER_PICKUP_TOLERANCE: Tolerance (meters) for drivers to pick up/drop off packages
• VEHICLE_MAX_CAPACITY: Maximum number of packages a vehicle can carry
• NUM_DRIVERS: Number of drivers in the simulation
• PICKUP_DELAY_SECONDS: Time spent at each pickup location
• DROPOFF_DELAY_SECONDS: Time spent at each dropoff location

Cost Calculation

• MINIMUM_WAGE: Base hourly wage for drivers (dollars)
• MINIMUM_WAGE_MULTIPLIER: Multiplier for minimum wage
• MILE_RATE: Compensation per mile driven (dollars)

Computation Parameters

• DISTANCE_MATRIX_COST_TYPE: Type of cost for optimization ('length', 'time', 'money')
• OR_TOOLS_TIME_LIMIT_SECONDS: Time limit for OR-Tools solver
• OR_TOOLS_MAX_SOLUTION_LIMIT: Maximum number of solutions for OR-Tools to try

Data Sources

The project uses real-world data sampled from San Francisco:

• Housing zones for delivery destinations
• Retail locations for package origins
• Distance matrices for accurate routing
• Cost calculations based on industry models

Real-Time Simulation

DeliverySim is not just a visualization tool but a complete computational simulation that:

• Computes in Real-Time: All driver movements, package pickups/deliveries, and routing decisions are calculated as the simulation runs
• Accelerated Timeline: Runs faster than real-time (configurable via SCALING_FACTOR) while maintaining computational accuracy
• Live Metrics: Displays driver statistics, package states, and business costs as they evolve
• Dynamic Routing: Solves the Vehicle Routing Problem at the start of each day to optimize delivery routes
• Interactive Controls: Toggle path visibility, clear paths, and observe day transitions as they happen

How It Works

1. Packages are generated daily for delivery from retailers to homes
2. The system uses OR-Tools to solve the Vehicle Routing Problem with pickup and delivery constraints
3. Drivers follow optimized routes to pick up and deliver packages in real-time
4. The dashboard visualizes the entire operation as it happens, showing driver movements, package states, and locations
5. Cost metrics and performance analytics are tracked and displayed live as the simulation progresses