Package Delivery System

Salt Lake City delivery simulation • Python • K‑means clustering • Greedy routing • Custom hash table

Overview

This project simulates the operations of a delivery service, where a fleet of trucks must deliver 40 packages across Salt Lake City under real‑world constraints such as deadlines, truck capacity, driver availability, and special package conditions. The program automates the entire workflow: it loads and parses data from CSV files (packages, addresses, and distances), groups and assigns packages intelligently, generates efficient delivery routes, and simulates the delivery timeline with accelerated real‑time output.

Key Features

Data‑Driven Initialization

Reads and stores package information in a custom hash table for constant‑time lookups.
Maintains address data in indexed form and builds a symmetrical distance matrix.
Ensures efficient access to delivery deadlines, notes, and routing distances.

Constraint Handling

Enforces rules like “delayed until 9:05 AM,” “must be delivered with package X,” or “only on truck Y.”
Dynamically corrects addresses mid‑route when new information becomes available.
Prioritizes packages by deadline and delay constraints (priority tiers 0–3).

Clustering & Routing

Uses k‑means clustering to split large groups across trucks, ensuring feasibility.
Builds routes via a nearest‑neighbor greedy algorithm to minimize distance while respecting constraints.
Schedules each truck’s departure, delivery stops, and return‑to‑hub events.

Simulation Engine

Generates a timeline of events (departures, deliveries, returns) in accelerated real‑time.
Continuously updates package statuses: “at the hub,” “en route,” “delivered.”
Supports time‑based queries to report package status at any specific time of day.

Technologies & Design

Python 3 Custom Hash Table Adjacency/Distance Matrix Event Timeline
Algorithms: Nearest Neighbor (routing), K‑Means (grouping), constraint‑based prioritization.
Design: Clear separation of concerns across modules (PackageHandler, PackageLoader, DeliveryHandler, Fleet, Truck).

Results

The simulation successfully delivers all 40 packages while respecting deadlines and operational constraints. Verbose mode demonstrates loading & prioritization, route assignments per truck, real‑time delivery logs with timestamps and deadline checks, and address‑correction events with re‑routing mid‑simulation.

Data Inputs

packageCSV.csv — package id, address, deadline, weight, and special notes
addressCSV.csv — indexed list of delivery addresses
distanceCSV.csv — symmetric matrix of pairwise distances

The web demo uses the same engine as the CLI version with a slightly augmented main for UI and verbosity.

How It Works

Load CSVs into in‑memory structures (hash table, address index, distance matrix).
Handle constraints and assign priorities (deadlines, delays, co‑delivery groups, truck limits).
Group packages via k‑means when a set exceeds truck capacity.
Route each truck using nearest‑neighbor, then schedule events.
Simulate the day in accelerated time and expose status‑at‑time queries.

Author: Joel J Gerard • projects.jjg.dev