MIGRATION_GUIDE.md

# 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:
```python
# 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

```yaml
# 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)
```bash
# 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)
```bash
# 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:

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

### Recommended additions for better functionality:

```yaml
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:
```python
# 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
```yaml
# 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
```bash
export WANDB_API_KEY=your_api_key_here
```

### Step 3: Run training
```bash
# 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:
1. **Full grasp validation** with proper J-index calculation
2. **100% backward compatibility** with existing configs and scripts
3. **Enhanced features** available through simple config updates
4. **Same training behavior** and experimental results

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