ylff/utils/distributed.py

"""
Distributed training utilities for multi-GPU training.

Supports both DDP (Distributed Data Parallel) and FSDP (Fully Sharded Data Parallel).
"""

import logging
import os
from typing import Optional
import torch
import torch.distributed as dist
from torch.nn.parallel import DistributedDataParallel as DDP
from torch.utils.data.distributed import DistributedSampler

logger = logging.getLogger(__name__)


def setup_ddp(rank: int, world_size: int, backend: str = "nccl"):
    """
    Initialize distributed training environment.

    Args:
        rank: Process rank (0 to world_size-1)
        world_size: Total number of processes
        backend: Communication backend ('nccl' for GPU, 'gloo' for CPU)
    """
    os.environ["MASTER_ADDR"] = os.environ.get("MASTER_ADDR", "localhost")
    os.environ["MASTER_PORT"] = os.environ.get("MASTER_PORT", "12355")

    dist.init_process_group(
        backend=backend,
        rank=rank,
        world_size=world_size,
    )

    torch.cuda.set_device(rank)
    logger.info(f"DDP initialized: rank={rank}, world_size={world_size}, backend={backend}")


def cleanup_ddp():
    """Clean up distributed training environment."""
    if dist.is_initialized():
        dist.destroy_process_group()
        logger.info("DDP cleaned up")


def get_ddp_info() -> dict:
    """
    Get current DDP configuration.

    Returns:
        Dict with rank, world_size, is_initialized, etc.
    """
    return {
        "is_initialized": dist.is_initialized(),
        "rank": dist.get_rank() if dist.is_initialized() else 0,
        "world_size": dist.get_world_size() if dist.is_initialized() else 1,
        "backend": dist.get_backend() if dist.is_initialized() else None,
    }


def wrap_model_ddp(
    model: torch.nn.Module,
    device: str = "cuda",
    find_unused_parameters: bool = False,
    gradient_as_bucket_view: bool = True,
) -> torch.nn.Module:
    """
    Wrap model with DDP for distributed training.

    Args:
        model: Model to wrap
        device: Device to use
        find_unused_parameters: Whether to find unused parameters (slower but more flexible)
        gradient_as_bucket_view: Use gradient as bucket view for memory efficiency

    Returns:
        DDP-wrapped model
    """
    if not dist.is_initialized():
        logger.warning("DDP not initialized, returning unwrapped model")
        return model

    rank = dist.get_rank()
    if device == "cuda":
        torch.cuda.set_device(rank)
        device_id = rank
    else:
        device_id = None

    ddp_model = DDP(
        model,
        device_ids=[device_id] if device_id is not None else None,
        output_device=device_id,
        find_unused_parameters=find_unused_parameters,
        gradient_as_bucket_view=gradient_as_bucket_view,
    )

    logger.info(f"Model wrapped with DDP (rank={rank})")
    return ddp_model


def create_distributed_sampler(
    dataset,
    shuffle: bool = True,
    seed: int = 0,
) -> Optional[DistributedSampler]:
    """
    Create distributed sampler for dataset.

    Args:
        dataset: Dataset to sample from
        shuffle: Whether to shuffle
        seed: Random seed

    Returns:
        DistributedSampler if DDP is initialized, None otherwise
    """
    if not dist.is_initialized():
        return None

    sampler = DistributedSampler(
        dataset,
        num_replicas=dist.get_world_size(),
        rank=dist.get_rank(),
        shuffle=shuffle,
        seed=seed,
    )

    logger.info(f"Created DistributedSampler (rank={dist.get_rank()}/{dist.get_world_size()})")
    return sampler


def all_reduce_mean(tensor: torch.Tensor) -> torch.Tensor:
    """
    All-reduce tensor and compute mean across all processes.

    Args:
        tensor: Tensor to reduce

    Returns:
        Mean value across all processes
    """
    if not dist.is_initialized():
        return tensor

    dist.all_reduce(tensor, op=dist.ReduceOp.SUM)
    tensor /= dist.get_world_size()
    return tensor


def save_checkpoint_ddp(
    model: torch.nn.Module,
    optimizer,
    scheduler,
    epoch: int,
    loss: float,
    checkpoint_path: str,
    is_main_process: bool = True,
):
    """
    Save checkpoint (only on main process to avoid conflicts).

    Args:
        model: Model to save
        optimizer: Optimizer state
        scheduler: Scheduler state
        epoch: Current epoch
        loss: Current loss
        checkpoint_path: Path to save checkpoint
        is_main_process: Whether this is the main process (rank 0)
    """
    if is_main_process:
        # Unwrap DDP model if needed
        if isinstance(model, DDP):
            model_state = model.module.state_dict()
        else:
            model_state = model.state_dict()

        torch.save(
            {
                "epoch": epoch,
                "model_state_dict": model_state,
                "optimizer_state_dict": optimizer.state_dict(),
                "scheduler_state_dict": scheduler.state_dict(),
                "loss": loss,
            },
            checkpoint_path,
        )
        logger.info(f"Saved checkpoint to {checkpoint_path}")

    # Synchronize all processes
    if dist.is_initialized():
        dist.barrier()


def load_checkpoint_ddp(
    model: torch.nn.Module,
    checkpoint_path: str,
    device: str = "cuda",
) -> dict:
    """
    Load checkpoint for distributed training.

    Args:
        model: Model to load into
        checkpoint_path: Path to checkpoint
        device: Device to load on

    Returns:
        Checkpoint dict
    """
    checkpoint = torch.load(checkpoint_path, map_location=device)

    # Handle DDP-wrapped models
    if isinstance(model, DDP):
        model.module.load_state_dict(checkpoint["model_state_dict"])
    else:
        model.load_state_dict(checkpoint["model_state_dict"])

    logger.info(f"Loaded checkpoint from {checkpoint_path}")
    return checkpoint


def run_distributed_training(
    rank: int,
    world_size: int,
    train_fn,
    *args,
    **kwargs,
):
    """
    Helper to run distributed training function.

    Args:
        rank: Process rank
        world_size: Total number of processes
        train_fn: Training function to run
        *args, **kwargs: Arguments to pass to train_fn
    """
    try:
        setup_ddp(rank, world_size)
        train_fn(rank, world_size, *args, **kwargs)
    finally:
        cleanup_ddp()


def launch_distributed_training(
    world_size: int,
    train_fn,
    *args,
    **kwargs,
):
    """
    Launch distributed training using torch.multiprocessing.

    Args:
        world_size: Number of GPUs to use
        train_fn: Training function (should accept rank and world_size as first args)
        *args, **kwargs: Additional arguments for train_fn
    """
    import torch.multiprocessing as mp

    mp.spawn(
        run_distributed_training,
        args=(world_size, train_fn) + args,
        nprocs=world_size,
        join=True,
    )