maintain-data-structures

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

By Layer

• Problem Layer → [problem_layer.md](references/problem_layer.md)

- Instance, PDPTWInstance, Solution, Node, Constraint

- When: Defining or working with problem instances

• Algorithm Layer → [algorithm_layer.md](references/algorithm_layer.md)

- Solver, ALNSSolver, Operators, SearchState, ALNSConfig

- When: Implementing or understanding algorithms

• Data Layer → [data_layer.md](references/data_layer.md)

- OSMnx graphs, GeoDataFrame, distance matrices, data generators

- When: Loading data, working with OSMnx, benchmarks

• Runtime Formats → [runtime_formats.md](references/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 |

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

[problem_layer.md](references/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](references/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](references/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](references/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

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](references/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](references/problem_layer.md) → PDPTWInstance

Answer:

```python

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](references/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](references/data_layer.md) → Node Attributes

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

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

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.

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.