🏃‍♀️‍➡️ Treadmill Documentation 🏃‍♀️‍➡️

A Clean and Modular PyTorch Training Framework

Welcome to Treadmill, a lightweight, modular training framework specifically designed for PyTorch. Treadmill provides clean, easy-to-understand training loops with beautiful output formatting while maintaining the power and flexibility of vanilla PyTorch.

Note

Treadmill is designed with simplicity and modularity in mind. Whether you’re a beginner learning PyTorch or an experienced practitioner, Treadmill helps you focus on your model and data rather than boilerplate training code.

Features Overview

✨ Core Features

🎯 Pure PyTorch: Built specifically for PyTorch with no forced abstractions
🔧 Modular Design: Easy to customize and extend with comprehensive callback system
📊 Beautiful Output: Rich formatting with progress bars and detailed metrics tables
⚡ Performance Optimizations: Mixed precision, gradient accumulation, gradient clipping
🎛️ Flexible Configuration: Dataclass-based configuration system for easy parameter management

✨ Advanced Features

📈 Comprehensive Metrics: Built-in metrics with support for custom metrics
💾 Smart Checkpointing: Automatic model saving with customizable triggers
🛑 Early Stopping: Configurable early stopping to prevent overfitting
🔄 Resumable Training: Easy checkpoint loading and training resumption
🚀 Mixed Precision: Automatic mixed precision for faster training
📝 Extensive Logging: Rich logging with metrics tracking and visualization

Quick Start

Get started with Treadmill in just a few lines of code:

import torch
import torch.nn as nn
from torch.utils.data import DataLoader
from treadmill import Trainer, TrainingConfig

# Define your model
model = nn.Sequential(
    nn.Linear(784, 128),
    nn.ReLU(),
    nn.Linear(128, 10)
)

# Create training configuration
config = TrainingConfig(
    epochs=10,
    device="auto",
    mixed_precision=True
)

# Initialize trainer and start training
trainer = Trainer(
    model=model,
    config=config,
    train_dataloader=train_loader,
    val_dataloader=val_loader
)

# Train your model
trainer.train()

Installation

From Source (Recommended)

git clone https://github.com/MayukhSobo/treadmill.git
cd treadmill
pip install -e .

Install with Examples

pip install -e ".[examples]"  # Includes additional dependencies for examples

Install Full Version

pip install -e ".[full]"  # Includes all optional dependencies and development tools

Documentation Structure

This documentation is organized into several sections to help you get the most out of Treadmill:

📚 Learning Path

Getting Started - New to Treadmill? Start here!
User Guide - Comprehensive guides for common use cases
Tutorials - Step-by-step tutorials with real examples
API Reference - Detailed API documentation
Examples - Ready-to-run examples and best practices

Community and Support

🤝 Get Involved

GitHub: Source code and issues
Discussions: Join our community discussions
Contributing: See our <no title> guide

📊 Project Status

License

This project is licensed under the MIT License - see the LICENSE file for details.