WSmart+ Route

A High-Performance Framework for Combinatorial Optimization in Waste Collection Vehicle Routing

Documentation | Compatibility | Overview | Features | Quickstart | Models | Setup | Usage | Contributing

---

Documentation Hub

Our comprehensive documentation covers every aspect of the WSmart+ Route system:

Core Documentation

Document	Description	Target Audience
AGENTS.md	Complete registry of neural models, classical policies, and environment physics. The AI assistant guide for understanding the codebase.	Researchers, ML Engineers, AI Assistants
ARCHITECTURE.md	High-level system design, data flow diagrams, design patterns, and module boundaries.	Architects, Senior Developers
CONTRIBUTING.md	Code style, Git workflow, PR process, and development guidelines.	Contributors
DEVELOPMENT.md	Environment setup, CLI reference, development workflows, and debugging guides.	Developers
TESTING.md	Test suite organization, fixtures, coverage requirements, and best practices.	QA Engineers, Developers
COMPATIBILITY.md	Detailed matrix of supported models, environments, and configuration pairs.	Researchers, Developers
TROUBLESHOOTING.md	Common issues, diagnostic steps, error reference, and quick fixes.	Everyone
TUTORIAL.md	Deep dives into algorithms, code examples, and implementation guides.	Developers, Researchers

Module Documentation

Detailed technical documentation for each subsystem. Essential for deep dives into specific components:

Document	Description	Module Path
CLI Module	Command-line interface, argument parsing, Hydra integration, and entry points.	logic/src/cli/
Configuration Module	Config system architecture, Hydra composition, and config classes.	logic/src/configs/
Configuration Guide	Comprehensive guide to Hydra configuration, CLI overrides, and best practices.	-
Constants Module	System-wide constants, problem definitions, and enum types.	logic/src/utils/
Data Module	Dataset generation, loading utilities, and data augmentation.	logic/src/data/
Environments Module	Problem environments (VRPP, WCVRP, SCWCVRP) and state management.	logic/src/envs/
Interfaces Module	Abstract base classes, protocols, and type definitions.	logic/src/interfaces/
Models Module	Neural architectures, encoders, decoders, and network components.	logic/src/models/
Pipeline Module	Training, evaluation, simulation orchestration, and RL algorithms.	logic/src/pipeline/
Policies Module	Classical solvers (Gurobi, ALNS, HGS) and heuristic policies.	logic/src/policies/
Utilities Module	Helper functions, I/O utilities, logging, and debugging tools.	logic/src/utils/
Documentation Standards	Style guide and templates for all documentation.	-

---

Overview

WSmart+ Route is a high-performance framework for solving complex Combinatorial Optimization (CO) problems, specifically the Vehicle Routing Problem with Profits (VRPP) and Capacitated Waste Collection VRP (CWC VRP).

The project bridges Deep Reinforcement Learning (DRL) with Operations Research (OR), providing a benchmarking and deployment environment where neural models (PyTorch) compete with traditional solvers (Gurobi, Hexaly).

Mission

Goal	Description
Research Platform	Benchmark neural routing agents against classical OR solvers
Real-World Application	Optimize waste collection routes for municipalities
Simulation Environment	Test policies on realistic multi-day scenarios
User-Friendly Interface	PySide6 GUI for training, evaluation, and visualization

Why WSmart+ Route?

1. Neural + Classical: Compare attention-based models with exact solvers and metaheuristics
2. Production-Ready: CLI and GUI interfaces for researchers and practitioners
3. Extensible: Add new models, policies, and problems with minimal boilerplate
4. Well-Tested: Comprehensive test suite with 60%+ code coverage
5. Well-Documented: Extensive documentation for all skill levels

---

Key Features

Neural Intelligence

Capability	Description
Attention-Based Models	Transformer architectures (AM, TransGCN, DeepDecoder) for constructive routing
Graph Neural Networks	GAT, GCN, GGAC encoders for spatial relationship modeling
Hierarchical RL	Manager-Worker architecture with GAT-LSTM for temporal decision-making
Meta-Learning	MetaRNN for generalization across different problem distributions
Policy Gradients	REINFORCE, PPO, POMO with multiple baseline strategies

Optimization Solvers

Solver	Type	Description
Gurobi	Exact	Branch-Cut-and-Price for optimal solutions
Hexaly	Hybrid	High-performance local search optimization
ALNS	Metaheuristic	Adaptive Large Neighborhood Search
HGS	Genetic	Hybrid Genetic Search with local search
OR-Tools	Constraint	Google's constraint programming solver

Simulation Engine

Feature	Description
Multi-Day Scenarios	Test policies over extended time horizons (31-365 days)
Stochastic Fill Rates	Gamma and empirical distributions for bin level modeling
Real Road Networks	OpenStreetMap integration for realistic distance matrices
Parallel Execution	Multi-core simulation with checkpointing support
Overflow Tracking	Monitor and penalize bin overflows

User Interface

Component	Description
PySide6 GUI	Modern Qt-based desktop application
Training Dashboard	Real-time loss curves and validation metrics
Simulation Viewer	Interactive route visualization with Folium maps
Analysis Tools	Comparative policy evaluation and statistics

---

Quickstart

Get up and running in 3 steps:

# 1. Clone and sync dependencies
git clone https://github.com/ACFHarbinger/WSmart-Route.git
cd WSmart-Route
uv sync

# 2. Activate the environment
source .venv/bin/activate

# 3. Launch the GUI or run a command
python main.py gui
# Or run a quick simulation
python main.py test_sim --policies regular --size 20 --days 7

Verify Installation

# Run the test suite
python main.py test_suite

# Check code quality
uv run ruff check .

# Verify PyTorch and CUDA
python -c "import torch; print(f'PyTorch: {torch.__version__}, CUDA: {torch.cuda.is_available()}')"

System Requirements

Component	Minimum	Recommended
Python	3.9	3.11
RAM	16GB	32GB
GPU	8GB VRAM	16GB+ VRAM
CUDA	11.8	12.x
Disk	10GB	50GB

---

Model Ecosystem

We provide a comprehensive library of neural architectures and classical policies:

Neural Models

Model	Architecture	Use Case
AttentionModel (AM)	Transformer (Encoder-Decoder)	General-purpose constructive routing
MandatorySelectionManager	GNN + RNN	High-level temporal gating for HRL
TemporalAM	Transformer	Time-dependent attention mechanism
MetaRNN	RNN/LSTM	Meta-learning for distribution generalization
DeepDecoderAM	Deep Transformer	Enhanced decoder for large instances
PointerNetwork	RNN + Attention	Traditional pointer mechanism baseline
TransGCN	Transformer + GCN	Hybrid spatial-sequential encoding

Graph Encoders

Encoder	Type	Description
GATEncoder	Graph Attention	Multi-head attention for node embeddings
GCNEncoder	Graph Convolution	Standard GCN with aggregation
GGACEncoder	Gated Graph	Edge-node interaction with gating
TGCEncoder	Transformer-GCN	Hybrid spatial encoding
GACEncoder	Graph Attention Conv	Edge-aware attention mechanism
MLPEncoder	MLP	Non-graph baseline encoder

Classical Policies

Policy	Type	Description
LookAhead	Rolling Horizon	N-day planning with sub-optimization
ALNS	Metaheuristic	Destroy-repair operators with adaptive weights
BPC	Exact	Branch-and-Price-and-Cut via Gurobi/OR-Tools
HGS	Genetic	Evolutionary operators with local search
Regular	Baseline	Fixed-schedule periodic collection
LastMinute	Reactive	Threshold-triggered collection
Gurobi	Exact	Direct Gurobi MIP solver
Hexaly	Hybrid	Hexaly local search optimizer

---

Setup Dependencies

Choose your preferred installation method:

UV (Recommended)

Fastest setup using the uv package manager:

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync the project and create a virtual environment
uv sync

# Activate the environment
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate.bat # Windows CMD
.venv\Scripts\Activate.ps1 # Windows PowerShell

# Verify installation
uv pip list

Anaconda

conda env create --file env/environment.yml -y --name wsr
conda activate wsr
conda list

Virtual Environment (Standard)

Note: Requires Python 3.9+ pre-installed.

python3 -m venv env/.wsr
source env/.wsr/bin/activate
pip install -r env/requirements.txt
pip install -r env/pip_requirements.txt

Setup Scripts

For automated setup:

# Linux
bash scripts/setup_env.sh <uv|conda|venv>

# Windows
scripts\setup_env.bat <uv|conda|venv>

---

Setup Optimizers

Gurobi (Academic License Available)

1. Create an account on the Gurobi website
2. Request a license (free academic licenses available)
3. Download the software and install
4. Activate: grbgetkey <your-license-key>

Hexaly

1. Create an account on the Hexaly website
2. Request a license
3. Install: pip install hexaly

CUDA Drivers

Important: Required for GPU acceleration with NVIDIA hardware.

Download from the NVIDIA CUDA Toolkit and follow the installation guide.

---

Program Usage

Generating Data

# Pre-generate training data for 50-vertex graphs
python main.py generate_data virtual --problem vrpp --graph_sizes 50 --n_epochs 10 --seed 42 --data_distribution gamma1

# Generate validation and test data
python main.py generate_data val --problem all --graph_sizes 20 50 --seed 42 --data_distribution gamma1
python main.py generate_data test --problem all --graph_sizes 20 50 --seed 42 --data_distribution gamma1

Training

# Train Attention Model on VRPP with 50 vertices (Hydra + Lightning)
python main.py train_lightning model.name=am env.name=vrpp env.num_loc=50 train.n_epochs=100 train.batch_size=512

# Legacy Training (Old Pipeline)
python main.py train --model am --problem vrpp --graph_size 50 --baseline rollout

Resume Training

python main.py train --model am --graph_size 20 --n_epochs 50 --epoch_start 20 --load_path "results/vrpp_20/run_*/epoch-19.pt"

Multiple GPUs

# Use specific GPUs
CUDA_VISIBLE_DEVICES=0,1 python main.py train

# Disable CUDA
python main.py train --no_cuda

Evaluation

# Greedy evaluation
python main.py eval data/vrpp/vrpp20_test_seed1234.pkl --model assets/model_weights/vrpp_20/am --decode_strategy greedy

# Sampling evaluation (best of 1280)
python main.py eval data/vrpp/vrpp20_test_seed1234.pkl --model assets/model_weights/vrpp_20/am --decode_strategy sample --width 1280

# Beam search
python main.py eval data/vrpp/vrpp20_test_seed1234.pkl --model assets/model_weights/vrpp_20/am --decode_strategy bs --width 16

Simulation Testing

# Test classical policies on 20-bin network for 31 days
python main.py test_sim --policies policy_last_minute policy_regular policy_look_ahead_a gurobi --problem vrpp --size 20 --days 31 --n_vehicles 1

# Test neural model on 365-day scenario
python main.py test_sim --policies am --problem vrpp --size 20 --days 365 --model_path assets/model_weights/vrpp_20/am/epoch-99.pt

# Multi-sample testing with resume support
python main.py test_sim --policies gurobi alns --problem vrpp --size 100 --days 365 --n_samples 10 --resume --cpu_cores -1

Graphical User Interface

python main.py gui [--test_only]

Test Suite

# Run all tests
python main.py test_suite

# Run specific module/class/test
python main.py test_suite --module test_models
python main.py test_suite --class TestAttentionModel
python main.py test_suite --test test_forward_pass
python main.py test_suite --markers "unit and not slow"

Hyperparameter Optimization

# Random search
python main.py hp_optim --model am --problem vrpp --search_strategy random --n_trials 50

# DEHB (Differential Evolution Hyperband)
python main.py hp_optim --model am --problem vrpp --search_strategy dehb --min_budget 1 --max_budget 50

Meta-Reinforcement Learning

python main.py mrl_train --model meta_rnn --problem vrpp --graph_size 20 --n_tasks 10

---

CLI Reference

Command	Description
train	Train neural models
eval	Evaluate trained models
test_sim	Run simulation tests
generate_data	Generate datasets
hp_optim	Hyperparameter optimization
mrl_train	Meta-reinforcement learning
gui	Launch graphical interface
test_suite	Run test suite
tui	Text user interface

Use python main.py <command> --help for detailed options.

---

Scripts

Script	Description
gen_data.sh	Generate datasets for training, validation, or testing
train.sh	Train Deep Learning models
hyperparam_optim.sh	Hyperparameter optimization
test_sim.sh	Test policies on the simulator
slurm.sh	Run on Slurm cluster

Windows equivalents available as .bat files.

---

Build Distribution

# Build source and binary distribution
uv build

# Create executable with PyInstaller
pyinstaller build.spec [--clean] [--noconsole]

---

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Code style and formatting (Ruff, Black)
• Git workflow and branching strategy
• Pull request process
• Testing requirements

Quick Start for Contributors

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/WSmart-Route.git
cd WSmart-Route

# Set up development environment
uv sync
source .venv/bin/activate

# Create a feature branch
git checkout -b feature/your-feature-name

# Make changes, then run tests and linting
uv run pytest
uv run ruff check .
uv run black .

# Commit and push
git commit -m "Add your feature"
git push origin feature/your-feature-name

---

Project Structure

WSmart-Route/
├── logic/                    # Core Intelligence Layer
│   ├── src/
│   │   ├── models/          # Neural architectures
│   │   ├── policies/        # Classical solvers
│   │   ├── envs/            # Problem environments
│   │   ├── pipeline/        # Training/evaluation/simulation
│   │   └── utils/           # Shared utilities
│   └── test/                # Test suite
├── gui/                      # User Interface Layer
│   ├── src/
│   │   ├── windows/         # Application windows
│   │   ├── tabs/            # Functional tabs
│   │   └── helpers/         # Background workers
│   └── test/                # GUI tests
├── data/                     # Datasets
├── assets/                   # Models, configs, outputs
├── scripts/                  # Automation scripts
└── main.py                   # CLI entry point

---

Acknowledgments

This project adapts code and ideas from:

• Attention, Learn to Solve Routing Problems
• POMO: Policy Optimization with Multiple Optima
• WSmart+ Bin Analysis
• Do We Need Anisotropic Graph Neural Networks?
• Learning TSP Requires Rethinking Generalization
• HGS-CVRP
• RL4CO

---

License

This project is licensed under the terms specified in the LICENSE file.

---

WSmart+ Route - Bridging AI and Operations Research for Smarter Waste Collection

Report a Bug | Request a Feature | Documentation