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:

• [MIGRATIONGUIDE.md](references/MIGRATIONGUIDE.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:

• [migrationmap.md](references/migrationmap.md) - File mappings only
• [architecture.md](references/architecture.md) - Three-layer architecture

Migration Workflow

Step 1: Identify and Plan

1. Determine the module to migrate

- Check [migrationmap.md](references/migrationmap.md) for file mappings - Identify source file in /SDR_stochastic/new version/ - Note the destination path and refactoring requirements

1. 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

1. 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: ```python # Before def solve(): capacity = 100 # Hardcoded

# After def solve(capacity: float = 100): ```

1. Decouple architecture layers

- Separate problem definitions from algorithms - Extract algorithm-specific code to appropriate layer - Follow interfaces in [architecture.md](references/architecture.md)

1. Generalize data structures

- Replace paper-specific types with generic abstractions - Ensure compatibility with Instance, Solution, Solver interfaces

Step 3: Implement in New Location

1. 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)

1. Add documentation

- Add docstrings to public functions/classes - Use Google or NumPy docstring style - Include parameters, return values, and examples

```python 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 """ ```

1. 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

1. Check imports resolve correctly

- Try importing the new module - Verify no circular dependencies

1. Run the test case

- Ensure basic functionality works - Compare behavior with original code if needed

1. 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:

1. Clean up for educational clarity

- Add markdown explanations between code cells - Remove debugging/experimental code - Structure: Problem → Setup → Solve → Visualize → Interpret

1. Ensure reproducibility

- Keep examples runnable in <30 seconds - Use small test instances - Include all necessary imports

1. Follow tutorial naming convention

- Format: 0Xdescriptivename.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):

1. Identify common functionality
2. Create unified interface
3. Preserve all unique features from each source
4. Organize as separate classes or functions within the same module

Key References

• File mappings: See [migrationmap.md](references/migrationmap.md)
• Architecture patterns: See [architecture.md](references/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