Data Structures Reference

Quick access to all data structure definitions in the VRP toolkit. This skill saves tokens by providing pre-documented structures instead of reading source code repeatedly.

Quick Navigation

Choose the appropriate reference based on what you're working with:

By Layer

• Problem Layer → problem_layer.md

  • Instance, PDPTWInstance, Solution, Node, Constraint
  • When: Defining or working with problem instances

• Algorithm Layer → algorithm_layer.md

  • Solver, ALNSSolver, Operators, SearchState, ALNSConfig
  • When: Implementing or understanding algorithms

• Data Layer → data_layer.md

  • OSMnx graphs, GeoDataFrame, distance matrices, data generators
  • When: Loading data, working with OSMnx, benchmarks

• Runtime Formats → runtime_formats.md

  • How routes, time windows, coordinates are actually represented in code
  • When: Understanding how to work with data structures in Python

By Common Questions

Question	Reference	Section
"What attributes does Instance have?"	problem_layer.md	Instance
"How are routes represented?"	runtime_formats.md	Route Representation
"What's in an OSMnx Graph?"	data_layer.md	Graph (NetworkX)
"How do I configure ALNS?"	algorithm_layer.md	ALNSConfig
"What's the structure of a Node?"	problem_layer.md	Node
"How are time windows stored?"	runtime_formats.md	Time Window Representation
"How do destroy operators work?"	algorithm_layer.md	DestroyOperator
"What's in a distance matrix?"	runtime_formats.md	Distance Matrix
"How do I work with OSMnx nodes?"	data_layer.md	GeoDataFrame
"What's a Solution object?"	problem_layer.md	Solution

By Data Type

Type	Reference	Description
Instance	problem_layer.md	Problem definition
Solution	problem_layer.md	Solution with routes
Node	problem_layer.md	Location/customer
Route	runtime_formats.md	List[int] format
TimeWindow	runtime_formats.md	Tuple[float, float] format
ALNSConfig	algorithm_layer.md	Algorithm configuration
Operator	algorithm_layer.md	Destroy/repair/local search
nx.MultiDiGraph	data_layer.md	OSMnx network graph
np.ndarray	runtime_formats.md	Distance/time matrices
GeoDataFrame	data_layer.md	OSMnx nodes/edges

When to Use This Skill

Trigger this skill when:

1. Understanding structures: "What attributes does X have?"
2. Working with data: "How do I access Y in Z?"
3. Migrating code: Need to understand existing data structures
4. Implementing features: Need to know structure interfaces
5. Debugging: Need to understand what data looks like
6. Avoiding repeated reads: Instead of reading source code files repeatedly

Reference Files Overview

problem_layer.md

Size: ~300 lines Contains:

• Instance, PDPTWInstance classes
• Solution class with methods
• Node class with all attributes
• Constraint types
• Type aliases
• Common usage patterns

Use when: Defining problems, creating instances, working with solutions

algorithm_layer.md

Size: ~350 lines Contains:

• Solver interface
• ALNSSolver and ALNSConfig
• Destroy/Repair/LocalSearch operators
• SearchState tracking
• Operator statistics
• ALNS main loop pattern

Use when: Implementing algorithms, understanding operators, configuring ALNS

data_layer.md

Size: ~300 lines Contains:

• OSMnx Graph structure (NetworkX)
• GeoDataFrame (nodes and edges)
• Distance/time matrix creation
• Data generators (OrderGenerator)
• Benchmark formats (Solomon)
• OSMnx → VRP conversions

Use when: Loading data, OSMnx integration, working with benchmarks

runtime_formats.md

Size: ~400 lines Contains:

• Route as List[int] with examples
• TimeWindow as Tuple[float, float]
• Coordinates as tuples
• Distance matrices as NumPy arrays
• Pickup-delivery pairs as list of tuples
• Configuration dictionaries
• Common type conversions
• Memory efficiency tips

Use when: Understanding practical code representations, writing/reading routes

Usage Examples

Example 1: Understanding a Route

Question: "I see route = [0, 5, 3, 7, 0] in the code. What does this mean?"

Action: Load runtime_formats.md → Route Representation

Answer:

• Route is a list of node IDs
• 0 = depot (start and end)
• [5, 3, 7] = customers visited in order
• This represents: Depot → Node 5 → Node 3 → Node 7 → Depot

Example 2: Creating an Instance

Question: "How do I create a PDPTW instance?"

Action: Load problem_layer.md → PDPTWInstance

Answer:

instance = PDPTWInstance(
    nodes=node_list,
    battery_capacity=100.0,
    max_route_time=480.0,
    vehicle_capacity=50.0
)

Example 3: Configuring ALNS

Question: "What parameters can I configure for ALNS?"

Action: Load algorithm_layer.md → ALNSConfig

Answer: See all parameters with defaults, explanations, and usage example.

Example 4: Working with OSMnx

Question: "What attributes does an OSMnx node have?"

Action: Load data_layer.md → Node Attributes

Answer: y (lat), x (lon), osmid, street_count, etc.

Benefits of This Skill

1. Token Efficiency: Read structured docs once instead of code files repeatedly
2. Quick Reference: Find information faster with organized structure
3. Complete Coverage: All data structures in one place
4. Practical Examples: Shows actual usage, not just definitions
5. Cross-Referenced: Easy to navigate between related structures

Integration with Other Skills

This skill is referenced by:

• migrate-module: Understanding structures when migrating code
• osmnx-integration: OSMnx data structure details (when created)
• add-algorithm: Algorithm layer structures for new implementations

When other skills need data structure information, they reference this skill instead of reading source code.

Maintenance

This reference should be updated when:

• New data structures are added to the codebase
• Existing structures change significantly
• New attributes or methods are added to core classes

Keep this as the single source of truth for data structure documentation.