---

name: maintain-data-structures description: Comprehensive reference documentation for all data structures in the VRP toolkit project. Use when needing to understand data structure definitions, attributes, formats, or representations to avoid repeatedly reading code. Covers Problem layer (Instance, Solution, Node), Algorithm layer (Solver, Operators, ALNS), Data layer (OSMnx, distance matrices), and runtime formats (routes as lists, time windows as tuples).

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:

Copyinstance = 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.