Migrate Module

Automate the migration of research code modules from the SDR_stochastic project into the reusable vrp-toolkit architecture.

Migration Resources

For complete migration guide, see:

• MIGRATION_GUIDE.md - Comprehensive technical guide

• Source code locations

• Complete file mapping (9 files)

• Migration phases (Phase 1-3)

• Refactoring guidelines and patterns

• Common issues and solutions

Quick references:

• migration_map.md - File mappings only

• architecture.md - Three-layer architecture

Migration Workflow

Step 1: Identify and Plan

Determine the module to migrate

• Check migration_map.md for file mappings

• Identify source file in /SDR_stochastic/new version/

• Note the destination path and refactoring requirements

Read and analyze the source code

• Read the entire source file

• Identify dependencies and imports

• Note any paper-specific hardcoded values

• Understand the module's purpose and interface

Step 2: Refactor for Generalization

Extract hardcoded values

• Identify magic numbers, file paths, dataset names

• Convert to function parameters or config objects

• Common patterns: battery capacity, time windows, location names

Example transformation:

Before

def solve(): capacity = 100 # Hardcoded

After

def solve(capacity: float = 100):

Decouple architecture layers

• Separate problem definitions from algorithms

• Extract algorithm-specific code to appropriate layer

• Follow interfaces in architecture.md

Generalize data structures

• Replace paper-specific types with generic abstractions

• Ensure compatibility with Instance , Solution , Solver interfaces

Step 3: Implement in New Location

Create or update the destination file

• Place code in the correct layer (Problem/Algorithm/Data)

• Follow vrp-toolkit directory structure

• Use appropriate naming conventions (see architecture guide)

Add documentation

• Add docstrings to public functions/classes

• Use Google or NumPy docstring style

• Include parameters, return values, and examples

def solve_pdptw(instance: PDPTWInstance, config: ALNSConfig) -> Solution: """Solve PDPTW using ALNS algorithm.

Args:
    instance: Problem instance to solve
    config: Algorithm configuration parameters

Returns:
    Solution object containing routes and objective value
"""

- Update imports

• Change import paths to new package structure

• Use relative imports within vrp_toolkit

• Update any external dependencies

Step 4: Create Test Case

Create a simple test to verify functionality:

def test_basic_functionality(): """Basic smoke test for migrated module""" # Create minimal instance instance = create_test_instance()

# Run migrated function
result = migrated_function(instance)

# Verify basic properties
assert result is not None
assert result.is_feasible()

Step 5: Verify Migration

Check imports resolve correctly

• Try importing the new module

• Verify no circular dependencies

Run the test case

• Ensure basic functionality works

• Compare behavior with original code if needed

Verify architectural compliance

• Check layer separation (no Problem code in Algorithm layer, etc.)

• Ensure following the Solver/Instance/Solution interfaces

Special Cases

Migrating Jupyter Notebooks

When migrating .ipynb files to tutorials:

Clean up for educational clarity

• Add markdown explanations between code cells

• Remove debugging/experimental code

• Structure: Problem → Setup → Solve → Visualize → Interpret

Ensure reproducibility

• Keep examples runnable in <30 seconds

• Use small test instances

• Include all necessary imports

Follow tutorial naming convention

• Format: 0X_descriptive_name.ipynb

• Update README with tutorial description

Merging Multiple Files

When multiple source files map to one destination (e.g., order_info.py

• demands.py → generators.py ):

• Identify common functionality

• Create unified interface

• Preserve all unique features from each source

• Organize as separate classes or functions within the same module

Key References

• File mappings: See migration_map.md

• Architecture patterns: See architecture.md

• Project guidelines: See CLAUDE.md in project root

Design Principles

• ✅ Minimal viable clarity over perfection

• ✅ Generalize from specific to reusable

• ✅ Decouple layers cleanly

• ❌ No over-engineering before 2+ use cases

• ❌ No documentation before code works