Project Name

Accompanying code for the paper Paper Title.

Add a brief description of your project here. You can use Markdown syntax for formatting, such as bold, italics, and links.

Make sure you:

• Replace the Project Name with the name of your project
• Add a brief description of your project
• Remove the 🤔 Why ? section
• Rename the project appropriately
• Change the project details (e.g. name, description, URLs) in the following files:
  • pyproject.toml
  • mkdocs.yml
  • README.md
• Update CITATION.cff (and the 📑 Citation section below)
• Update the arXiv badge in the README.md with the correct arXiv ID (when available)
• Update the logo in the README.md

🤔 Why ?

When working on a new project, we frequently encountered challenges such as:

1. Reproducibility: How can we ensure that our results are reproducible across different environments?
2. Boilerplate Code: We often find ourselves writing the same boilerplate code over and over again.

To address these challenges, we have created a template for PyTorch projects that streamlines the setup process and helps you focus on your research.

Main Technologies

• PyTorch Lightning: A lightweight wrapper for PyTorch that streamlines high-performance AI research. It serves as a structured framework for organizing PyTorch code.
• Hydra: A powerful configuration framework for managing complex applications. It enables dynamic composition of hierarchical configurations, allowing overrides via config files and the command line.

🚀 Getting Started

Click Use this template to create a new repository.

Once your repository is set up using the template, clone it and start working with the following commands (We use the Rye Python package manager):

# Install Rye (https://rye.astral.sh/guide/installation/)
curl -sSf https://rye.astral.sh/get | bash

# Clone the repository & cd into it
git clone https://github.com/insane-group/<YOUR-PROJECT-NAME>
cd <YOUR-PROJECT-NAME>

# Rename the project and make sure you change the project details (e.g. name, description, URLs) in the following files:
# 1. pyproject.toml
# 2. mkdocs.yml
# 3. README.md
mv src/project src/<YOUR-PROJECT-NAME>

# Install dependencies using Rye
rye sync

# Activate the virtual environment
source .venv/bin/activate

# Install the pre-commit hooks
poe hooks

# Run the training/evaluation script
# Override any config parameter from command line
python src/project/train.py trainer.max_epochs=20 model.optimizer.lr=1e-4
# train on CPU
python src/project/train.py trainer=cpu
# train on 1 GPU
python src/project/train.py trainer=gpu
# test checkpoint on test dataset
python src/project/test.py checkpoint="/path/to/ckpt/name.ckpt"

Feel free to share any relevant details to help others get started, for example, content similar to the Setup and Quickstart sections in Google’s Prompt-to-Prompt.

Performing tasks using poethepoet

We are using poethepoet, to perform various development oriented tasks. Formatting, type-checking, as well as a few other operations, can be performed by running

poe <task>

where <task> is one of the tasks listed by running:

poe --help
Poe the Poet - A task runner that works well with poetry.
version 0.28.0

Result: No task specified.

Usage:
  poe [global options] task [task arguments]

Global options:
  -h, --help            Show this help page and exit
  --version             Print the version and exit
  -v, --verbose         Increase command output (repeatable)
  -q, --quiet           Decrease command output (repeatable)
  -d, --dry-run         Print the task contents but don't actually run it
  -C PATH, --directory PATH
                        Specify where to find the pyproject.toml
  -e EXECUTOR, --executor EXECUTOR
                        Override the default task executor
  --ansi                Force enable ANSI output
  --no-ansi             Force disable ANSI output

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

Consider installing poe as global dependency to make your life easier using rye install poethepoet 😛.

📂 Project Structure

The project follows a standard structure for a Python project.

├── CITATION.cff                                 <- Citation file for referencing the project
├── configs                                      <- Hydra configuration files
│   ├── callbacks                                  <- Configs for training callbacks
│   ├── data                                       <- Configs for loading the dataset
│   ├── hydra                                      <- Hydra-specific settings
│   ├── loggers                                    <- Configs for logging
│   ├── model                                      <- Model-specific config
│   ├── test.yaml                                  <- Test configuration file
│   ├── trainer                                    <- Configs for the training loop
│   └── train.yaml                                 <- Training configuration file
├── data                                         <- Dataset storage directory
├── docs                                         <- Project documentation
│   ├── code                                       <- Source code documentation
│   ├── CODE_OF_CONDUCT.md                         <- Guidelines for community behavior
│   ├── CONTRIBUTING.md                            <- Instructions for contributing to the project
│   ├── images                                     <- Images used in documentation
│   ├── LICENSE.md                                 <- License information
│   ├── index.md                                   <- Main documentation page
│   └── welcome.md                                 <- Welcome page for the project
├── .editorconfig                                <- Editor configuration for consistent formatting
├── .github                                      <- GitHub-specific configurations
│   └── workflows                                  <- CI/CD workflow definitions for GitHub Actions
├── .gitignore                                   <- Files and directories to ignore in Git
├── logs                                         <- Logs generated during training/testing
├── models                                       <- Trained models and related files
├── notebooks                                    <- Jupyter notebooks for experiments and analysis
│   └── template.ipynb                             <- Notebook template for new experiments
├── .pre-commit-config.yaml                      <- Pre-commit hook configurations
├── src                                          <- Source code directory
│   └── project                                    <- Main project codebase
├── tests                                        <- Unit tests for the project
│   ├── __init__.py                                <- Init file for test module
│   └── test_model.py                              <- Tests for model functionality
├── LICENSE                                      <- License information for the project
├── README.md                                    <- Main project README file
├── mkdocs.yml                                   <- Configuration for MkDocs documentation site
├── pyproject.toml                               <- Python project configuration file
├── .python-version                              <- Python version specification
├── requirements-dev.lock                        <- Locked dependencies for development
├── requirements.lock                            <- Locked dependencies for production
└── .vscode                                      <- VS Code workspace settings
    ├── extensions.json                            <- Recommended extensions for VS Code
    ├── launch.json                                <- Debugging configurations
    └── settings.json                              <- VS Code-specific settings

📖 Exploring the Documentation

The documentation is generated from Python docstrings using MkDocs and mkdocstrings for the source code, while the rest is written in standard Markdown. To view it, run poe docs in the terminal or visit https://insane-group.github.io/pytorch-lightning-template/.

📑 Citation

Please use the following citation if you use this project in your work:

@software{Sioros_scikit-learn-template,
  author = {Sioros, Vassilis},
  license = {Apache-2.0},
  title = {{scikit-learn-template}},
  url = {https://github.com/insane-group/scikit-learn-template}
}

🪙 Credits

This template was created by INSANE Group and is based on the following projects:

• NN-Template by Grok AI
• Lightning Hydra Template by ashleve
• Pytorch Lightning Template by DavidZhang73
• MNIST Classifier by kengz