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

By Data Type

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.