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:
- Understanding structures: "What attributes does X have?"
- Working with data: "How do I access Y in Z?"
- Migrating code: Need to understand existing data structures
- Implementing features: Need to know structure interfaces
- Debugging: Need to understand what data looks like
- 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
- Token Efficiency: Read structured docs once instead of code files repeatedly
- Quick Reference: Find information faster with organized structure
- Complete Coverage: All data structures in one place
- Practical Examples: Shows actual usage, not just definitions
- 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.