# README — Dataset Generation for Heterogeneous EVRP-TW (HEVRP-TW)

## 1. Purpose
This repository (or folder) generates a **heterogeneous-fleet** benchmark dataset for the **Heterogeneous Electric Vehicle Routing Problem with Time Windows and recharging (HEVRP-TW)**.  
It is based on the classic **EVRP-TW instances of Schneider et al. (2014)**, and it **preserves the original geography and customer/service data** while adding **vehicle heterogeneity** and **charging-station dummy copies** so that alternative MILP formulations can be compared fairly.

## 2. Source Benchmark Instances
**Base instances:** Schneider et al. (2014) EVRP-TW benchmark.  
We keep unchanged:
- customer and station coordinates,
- customer demands,
- service durations,
- time windows,
- station availability (if provided),
- original distances (or coordinates from which distances are computed).

The base instances include three distribution types:
- **c-type:** clustered customers,
- **r-type:** random customers,
- **rc-type:** mixed clustered–random customers.

## 3. Generated Instance Sets
### 3.1 Small set
- **Customers:** V ∈ {5,10,15}  
- **Count:** 36 instances total (covering c, r, rc types)
- **Vehicles:** set to **|K| = |V|**  
- **Usage in experiments:** all models **P1–P10** are solved with **1 hour** time limit per instance (MIP), and all metrics are reported as defined in the paper.

### 3.2 Medium set (C20,30,40)
- Constructed from the **large Schneider et al. instances** by taking the **first 20, 30, and 40 customers**.
- Named **C20-C40 instances**.
- **Vehicles:** set to **|K| = 10** for C20-C30 and 20 for C40.
- **Usage in experiments:** primarily used to report:
  - LP-relaxation bound (`LB_root`) and
  - raw model size statistics (#vars, #constrs, #nonzeros),

## 4. Fleet Heterogeneity: Parameter Generation
All heterogeneity is generated **per instance** and **per vehicle**.  
For each vehicle k:
- **Charging rate:** `g_k ~ Uniform([3.0, 4.0])`
- **Battery capacity:** `Q_k ~ Uniform([60, 100])`
- **Payload capacity:** `C_k ~ Uniform([200, 300])`
- **Energy consumption coefficient:** `r_k ~ Uniform([0.8, 1.2])`

### 4.1 Travel speed and travel times
A single travel speed is drawn per vehicle:
- **Speed:** `v_k ~ Triangular(v_min, v_mode, v_max)` with  
  `(v_min, v_mode, v_max) = (25, 30, 38)` km/h

Travel times are then computed consistently from distances:
- `t_{ijk} = d_{ij} / v_k`

This setting is intended to reflect typical urban parcel-van speeds with slowdowns in dense areas and moderate speeds in semi-central zones.

## 5. Dummy Charging-Station Copies (Multiple Visits)
To allow multiple recharging visits to the **same physical station** while preserving a **visit-at-most-once** structure at the node level, the generator creates **dummy copies** of stations.

### 5.1 Copy selection procedure (per instance)
We follow the approach used in related EVRP literature (e.g., Macrina et al., Cortés et al.):

1. Solve the instance **with no station copies** (one node per physical station).
2. If solved to **proven optimality**, add **one copy per station** and re-solve.
3. Repeat until:
   - (i) the **optimal objective** is identical for **two consecutive iterations**, or
   - (ii) the iteration cannot be solved to optimality within **3600 seconds**.

**Final decision used in experiments:** based on these preliminary runs, we set **one copy per station** in the small-sized dataset.

## 6. Output Format
Each generated instance should contain (at minimum) the following fields:

### 6.1 Node sets
- `V`: customer node IDs
- `Fp`: charging-station dummy node IDs (including copies)
- `K`: vehicle IDs

### 6.2 Data parameters
- `d[i,j]`: distances for relevant arcs (including return distances `d[i,0]` if required by a formulation)
- `q[i]`: demand (0 for depot and station nodes)
- `s[i]`: service time
- `e[i], l[i]`: time-window bounds
- `l0`: planning horizon upper bound

Vehicle-specific:
- `C[k]`: payload capacity
- `Q[k]`: battery capacity
- `g[k]` (or `chg[k]`): charging rate/time-per-unit
- `r[k]`: consumption coefficient
- `v[k]`: travel speed
- `t[i,j,k]`: travel time

### 6.3 Dummy mapping 
- `dummy_to_station`: maps each dummy station node to its physical station ID

## 9. Notes and Common Pitfalls
- Ensure the distance matrix includes the **return-to-depot distances** `d[i,0]` if any model uses an implicit return term (e.g., last-node indicator models).
- If your arc set omits return arcs `(i,0)`, make sure any code that needs `d[i,0]` checks that these values exist.
- For LP-only experiments, avoid reporting MIP node counts; nodes are not meaningful when only the LP relaxation is solved.

## 10. Citation
If you use this dataset, please cite:
- Schneider, M., Stenger, A., & Goeke, D. (2014). The electric vehicle-routing problem with time windows and recharging stations. *Transportation Science*.

And cite the supporting references used for speed/operations assumptions as in the paper.

---
Maintainer: <Nima Moradi / Concordia University/ nima.moradi@mail.concordia.ca>
Last updated: <2026-01-02>
