# pytorch-lightning-template

**Repository Path**: somata/pytorch-lightning-template

## Basic Information

- **Project Name**: pytorch-lightning-template
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# PyTorch Lightning Template

A production-ready template for PyTorch Lightning projects with Hydra configuration management.

## Overview

This is a templated project structure for building machine learning projects using PyTorch Lightning and Hydra. It provides a well-organized foundation for research and production deep learning projects with built-in support for experiment tracking, configuration management, and best practices.

## Features

- **PyTorch Lightning Integration**: Simplified training loop with automatic device handling
- **Hydra Configuration**: Hierarchical configuration management with command-line overrides
- **MNIST Example**: Complete end-to-end example with data loading, model training, and testing
- **Modular Design**: Easy to customize and extend for new projects
- **Pre-commit Hooks**: Code formatting and linting automation
- **MkDocs Documentation**: Auto-generated documentation from docstrings

## Main Technologies

- [**PyTorch Lightning**](https://lightning.ai/docs/pytorch/stable/starter/introduction.html): A lightweight wrapper for PyTorch that streamlines high-performance AI research
- [**Hydra**](https://hydra.cc/): A powerful configuration framework for managing complex applications

## Installation

This project uses [Rye](https://rye.astral.sh/) for Python package management.

```shell
# Install Rye
curl -sSf https://rye.astral.sh/get | bash

# Clone the repository
git clone https://gitee.com/somata/pytorch-lightning-template
cd pytorch-lightning-template

# Install dependencies
rye sync

# Activate virtual environment
source .venv/bin/activate

# Install pre-commit hooks
poe hooks
```

## Usage

### Training

Run training with default configuration:
```shell
python src/project/train.py
```

Override configuration parameters via command line:
```shell
# Train with custom epochs and learning rate
python src/project/train.py trainer.max_epochs=20 model.optimizer.lr=1e-4
```

Train on specific hardware:
```shell
# Train on CPU
python src/project/train.py trainer=cpu

# Train on GPU
python src/project/train.py trainer=gpu
```

### Testing

Test a trained checkpoint:
```shell
python src/project/test.py checkpoint="/path/to/ckpt/name.ckpt"
```

### Available Tasks

Run tasks using poethepoet:
```shell
poe <task>
```

Available tasks:
- `clean` - Clean up auxiliary files
- `format` - Format codebase
- `hooks` - Run all pre-commit hooks
- `test` - Run test suite
- `type-check` - Run static type checking
- `lint` - Lint code for errors
- `docs` - Build and serve documentation

## Project Structure

```
pytorch-lightning-template/
├── configs/                    # Hydra configuration files
│   ├── callbacks/             # Training callbacks
│   ├── data/                  # Data module configs
│   ├── loggers/               # Logging configs
│   ├── model/                 # Model configs
│   ├── trainer/               # Trainer configs
│   ├── train.yaml
│   └── test.yaml
├── src/project/               # Main source code
│   ├── __init__.py
│   ├── config.py              # Configuration instantiation
│   ├── data/
│   │   └── mnist.py           # MNIST data module
│   ├── models/
│   │   └── mnist.py           # MNIST model
│   ├── train.py               # Training script
│   └── test.py                # Testing script
├── tests/                     # Unit tests
├── docs/                      # Documentation
├── pyproject.toml             # Project configuration
└── mkdocs.yml                 # MkDocs configuration
```

## Configuration

Configuration files are located in the `configs/` directory. Key configurations include:

- `configs/train.yaml` - Training configuration
- `configs/test.yaml` - Testing configuration
- `configs/model/mnist.yaml` - Model hyperparameters
- `configs/data/mnist.yaml` - Dataset configuration
- `configs/trainer/default.yaml` - Trainer settings

## Documentation

Build and view documentation locally:
```shell
poe docs
```

Or visit the [online documentation](https://insane-group.github.io/pytorch-lightning-template/).

## Citation

If you use this template in your work, please cite:

```bibtex
@software{pytorch-lightning-template,
  author = {Sioros, Vassilis},
  license = {Apache-2.0},
  title = {PyTorch Lightning Template},
  url = {https://gitee.com/somata/pytorch-lightning-template}
}
```

## Credits

This template is based on:

- [NN-Template by Grok AI](https://github.com/grok-ai/nn-template)
- [Lightning Hydra Template by ashleve](https://github.com/ashleve/lightning-hydra-template)
- [Pytorch Lightning Template by DavidZhang73](https://github.com/DavidZhang73/pytorch-lightning-template)

## License

Apache License 2.0 - See [LICENSE](LICENSE) for details.) for details.) for details.) for details.) for details.) for details.) for details.) for details.) for details.