Skip to content

📦 parcel_indirect Model Documentation

1. Overview

Model Name: parcel_indirect

Purpose:
The goal of the parcel_indirect model is to prepare and process delivery data so it can be passed to Closer’s optimizer. This supports the generation of routing solutions for high-density Parcel contracts, such as DPD or CTT.

Pipeline Stage:
Pre-routing – this model operates before the route optimization step.

2. Input Data

Input Format: JSON payload

{
    "settings": {
        "slot_hours": 8.0,
        "nucleoid_distance": 50,
        "max_van_stops_per_hour": 8,
        "max_boxes_per_van": 64
    },
    "depot": {
        "id": "67cf302e66fb1544792b8fa5",
        "lat": 38.699423,
        "lon": -9.1898111
    },
    "orders": [
        {
            "orderId": "DY256754722PT",
            "box": [],
            "bags": ["#1DY256754722PT"],
            "lat": 38.7112951,
            "lon": -9.1596173,
            "size": 0.1
        }
    ]
}

3. Clustering Methodology

Step 1: Even Clustering

  • Algorithm: A modified K-Means using MILP (Mixed Integer Linear Programming).
  • Goal: Split orders evenly across clusters according to:
  • Maximum number of bags
  • Maximum number of satellites
  • Number of Clusters: Defined by the slot_hours setting.
  • Each cluster corresponds to a 1-hour window of van activity.

Step 2: DBSCAN Promotion

Within each hour-based cluster:

  • DBSCAN is applied to find denser regions (“nuclei”) using:
  • eps = nucleoid_distance * MT (where MT is a meter-to-coordinate factor)
  • min_samples = 1
  • Points are grouped incrementally using DBSCAN until the max_van_stops_per_hour is reached.
  • Existing out of format points are taken into account when checking stop limits.

4. Darkspot Handling

  • Definition: Geographical areas (polygons) where vans cannot stop.
  • Darkspot Exceptions:
  • If a shared address (points within 15 meters of each other) contains an existing out of format, all nearby points are promoted.
  • (Planned) If a location contains 20+ deliveries, all will be promoted, even if in a darkspot.

5. Output Format

class OutputPayload(BaseModel):
    depot: Depot
    orders: List[Order]
Orders retain the input structure, but:

Promoted points (to be handled by the van) have X prefixed to their orderId.

Format distinction:

XDs... → Original out of format

X#Ds... → Promoted by the model

Format distinction:

  • XDs... → Original out of format
  • X#Ds... → Promoted by the model

6. Edge Cases & Ongoing Work

  • Handling high-density locations (many deliveries at same coordinates)
  • Managing excess out-of-format deliveries
  • Implementing the “20 deliveries at one address” promotion rule

7. Execution and Lifecycle

  • The model is run once per client.
  • It is not retrained or versioned automatically.

8. Future Work: Metrics & Validation

To Be Discussed: Model validation metrics and KPIs

Suggested KPIs:

  • Average number of van stops per hour
  • Ratio of boxes per stop
  • Percentage of darkspot deliveries promoted
  • Number of orders served by vans vs satellites
  • Heatmap of out-of-format vs promoted points

9. Summary

The parcel_indirect model acts as a preparatory logic layer before optimization, applying intelligent clustering to divide deliveries over time and promote viable van stops. It ensures operational constraints (like darkspots, van capacity, and time slots) are respected while preparing data for downstream logistics decision-making.