Migration Guide for Refactored Training System

This guide explains how to migrate from the original training scripts to the refactored system while maintaining full backward compatibility.

1. Validation Logic Fix

The refactored system properly implements grasp validation through the GraspValidator class:

What was fixed:

Complete grasp evaluation: The validator now properly evaluates grasp quality, angle (sin/cos), and width predictions
Jacquard index calculation: Correctly computes J-index@1 and J-index@5 for grasp accuracy
Proper metric aggregation: Handles distributed training metric collection
Memory efficiency: Optimized batch processing and inverse transformations

Key improvements:

# Old: Basic validation without full grasp support
val_metrics = validate(model, val_loader)

# New: Full grasp-aware validation
grasp_validator = GraspValidator(use_grasp_masks=True)
iou, prec_dict, j_indices = grasp_validator.validate(model, val_loader, epoch, args)

2. Backward Compatibility

The refactored system maintains 100% backward compatibility:

Config compatibility:

Old configs work unchanged: The system auto-detects old-style scheduler configs
Gradual migration: You can update configs incrementally

# Old style (still works)
milestones: [35]
lr_decay: 0.1

# New style (recommended)
scheduler:
  type: multistep
  params:
    milestones: [35]
    gamma: 0.1

Training behavior:

Identical results: The refactored trainer produces the same training results
Same checkpoints: Checkpoint format is preserved
Compatible metrics: All metrics are logged with the same names

3. Training Commands

Option 1: Use existing scripts (no changes needed)

# Original CROG training (unchanged)
python train_crog.py --config config/OCID-VLG/crog_r50.yaml

# Original network training (unchanged)
python train_network.py --config config/OCID-VLG/legrconv_multi_2x_r50_416_dcn.yaml

Option 2: Use refactored scripts (recommended)

# Refactored CROG training with full grasp support
python train_crog_refactored.py --config config/OCID-VLG/crog_r50_refactored.yaml

# Refactored network training
python train_network_refactored.py --config config/OCID-VLG/your_config.yaml

4. Configuration Updates

Minimal changes for existing configs:

To enable full grasp validation in existing configs, ensure:

TRAIN:
  use_grasp_masks: True  # Must be True for grasp validation

Recommended additions for better functionality:

TRAIN:
  # Enhanced scheduler support
  scheduler:
    type: cosine      # or 'multistep', 'step', 'plateau', 'onecycle'
    params:
      T_max: 50
      eta_min: 1.0e-6
  
  # Optional warmup
  warmup_epochs: 5
  
  # WandB configuration
  wandb:
    project: "your-project-name"
    tags: ["experiment-tags"]

5. Key Differences and Benefits

Training scripts:

Feature	Original	Refactored
Grasp validation	Partial	Full implementation
Scheduler options	MultiStepLR only	7+ scheduler types
WandB integration	Basic	Enhanced with proper metrics
Code modularity	Monolithic	Modular components
Error handling	Limited	Comprehensive

Validation improvements:

# Original: Limited grasp metrics
iou, prec_dict, j_index = validate_with_grasp(...)

# Refactored: Complete grasp evaluation
# - Proper J-index calculation for 1 and 5 grasps
# - Correct inverse transformations
# - Distributed metric aggregation
# - Memory-efficient processing

6. Migration Checklist

Set WandB API key as environment variable (not in code)
Verify grasp masks are enabled in config (use_grasp_masks: True)
Update scheduler config (optional but recommended)
Test with small epoch count first to verify behavior
Check metrics match between old and new systems

7. Troubleshooting

Issue: Metrics don't match

Ensure use_grasp_masks: True in config
Verify same batch size and learning rate
Check random seed is consistent

Issue: Scheduler errors

The refactored system auto-converts float to int for T_max
All scheduler parameters are type-checked

Issue: WandB not logging

Set WANDB_API_KEY environment variable
Check wandb section in config

8. Example: Full Migration

Step 1: Update config

# Add to existing config
TRAIN:
  use_grasp_masks: True  # Enable grasp validation
  
  # Optional: Better scheduler
  scheduler:
    type: cosine
    params:
      T_max: 50
      eta_min: 1.0e-6

Step 2: Set environment

export WANDB_API_KEY=your_api_key_here

Step 3: Run training

# Using refactored script
python train_crog_refactored.py --config config/OCID-VLG/crog_r50_refactored.yaml

# Or use original script (still works)
python train_crog.py --config config/OCID-VLG/crog_r50.yaml

Summary

The refactored system provides:

Full grasp validation with proper J-index calculation
100% backward compatibility with existing configs and scripts
Enhanced features available through simple config updates
Same training behavior and experimental results

You can adopt the refactored system gradually or continue using existing scripts - both approaches are fully supported.