mixup 0.1.0

A unified PyTorch library for SOTA MixUp augmentations.

mixupentations

A unified PyTorch library for SOTA MixUp augmentations. It keeps popular image and label mixing methods in one place, making it extremely convenient for rapid experiments and training robust classification models.

Features

• VanillaMixUp — Classic linear mixing of two images and their labels.
• CutMix — Replaces a rectangular region of an image with a patch from another image.
• ResizeMix — Overlays a rescaled patch from another image.
• FMix — Blends images using a low-frequency noise mask generated via FFT.
• MixupPipeline — Randomly selects one method from a provided list for multi-mode training strategies.
• Easily extensible architecture via the BaseMixup abstract class.

Installation

Install directly from PyPI:

pip install mixup

Or install in development mode from the source:

git clone [https://github.com/your_username/mixup.git](https://github.com/your_username/mixupentations.git)
cd mixup
pip install -e .

Quick Start

import torch
import torch.nn.functional as F
from mixup import VanillaMixUp, CutMix, MixupPipeline

# Dummy batch of images [B, C, H, W] and labels [B]
images = torch.randn(8, 3, 224, 224)
labels = torch.randint(0, 10, (8,))

# Convert labels to one-hot encoding for mixing
labels_one_hot = F.one_hot(labels, num_classes=10).float()

# Use a single method
mixup = VanillaMixUp(alpha=1.0, probability=0.5)
mixed_images, mixed_labels = mixup(images, labels_one_hot)

# Or use a multi-mode pipeline
pipeline = MixupPipeline([
    VanillaMixUp(alpha=1.0),
    CutMix(alpha=1.0),
])
mixed_images, mixed_labels = pipeline(images, labels_one_hot)

Available Augmentations

VanillaMixUp

Standard MixUp: blends two images and their corresponding labels using a mixing coefficient λ sampled from a Beta(α, α) distribution.

from mixup import VanillaMixUp

mixup = VanillaMixUp(alpha=1.0, probability=1.0)

CutMix

Cuts a rectangular region from one image and pastes a patch from another. The λ coefficient is recalculated based on the actual patch area.

from mixup import CutMix

cutmix = CutMix(alpha=1.0, probability=0.5)

ResizeMix

Rescales a partner image and pastes the resulting patch into a random position on the original image.

from mixup.methods import ResizeMix

resizemix = ResizeMix(alpha=1.0)

FMix

Generates a binary mask via the inverse FFT of low-frequency noise and blends images according to this mask.

from mixup.methods import FMix

fmix = FMix(alpha=1.0, decay_power=3.0)

Parameters

All methods inherit from BaseMixup and accept the following common arguments:

Parameter	Type	Default	Description
alpha	float	1.0	Hyperparameter for the Beta distribution. If alpha=0, λ is set to 1.
probability	float	1.0	The probability (0.0 to 1.0) of applying the augmentation.

FMix accepts an additional parameter:

Parameter	Type	Default	Description
decay_power	float	3.0	The decay power applied in the frequency domain.

Integration into Training Loop

PyTorch's native CrossEntropyLoss supports soft-labels out of the box (since version 1.10).

import torch.nn as nn
import torch.nn.functional as F
import torch.optim as optim
from mixup import CutMix

model = ...  # Your PyTorch model
criterion = nn.CrossEntropyLoss()
optimizer = optim.Adam(model.parameters())

# Initialize augmentation
cutmix = CutMix(alpha=1.0, probability=0.5)
NUM_CLASSES = 100

model.train()
for images, labels in dataloader:
    images, labels = images.cuda(), labels.cuda()

    # 1. Convert targets to one-hot floats
    labels_one_hot = F.one_hot(labels, num_classes=NUM_CLASSES).float()

    # 2. Apply augmentation
    mixed_images, mixed_labels = cutmix(images, labels_one_hot)

    # 3. Standard forward & backward pass
    optimizer.zero_grad()
    outputs = model(mixed_images)

    loss = criterion(outputs, mixed_labels)
    loss.backward()
    optimizer.step()

References

• MixUp: Beyond Empirical Risk Minimization
• CutMix: Regularization Strategy to Train Strong Classifiers
• ResizeMix: Mixing Data with Preserved Object Information
• FMix: Enhancing Mixed Sample Data Augmentation

License

This project is licensed under the MIT License.