Research Project Template

🚀 Get started on a new research project with a clean, robust and well-tested base that you can count on! 🚀

This is a project template for ML researchers developed at Mila. Our goal with this is to help you get started with a new research project.

See this introduction to the project for a detailed description of the context and motivations behind this project.

🚧 Please note: This is a work-in-progress and will get better over time! We want your feedback!🙏

Installation

Projects created with this template use uv to manage dependencies. First, follow the instructions here to install uv on your machine.

Once you have uv installed locally, use this command to create a new project from this template:

uvx copier copy --trust gh:mila-iqia/ResearchTemplate new_project

This will ask you a few questions to help set things up. Navigate to the new directory, open up your favorite IDE, and voila! You're all setup! 🎊

Use this command to see all available options:

cd new_project  # replace with your folder.
. .venv/bin/activate
python project/main.py --help

For more detailed instructions, take a look at this page.

Overview

This project makes use of the following libraries:

• Hydra is used to configure the project. It allows you to define configuration files and override them from the command line.
• PyTorch Lightning is used to as the training framework. It provides a high-level interface to organize ML research code.
  • 🔥 Please note: You can also use Jax with this repo, as is shown in the Jax example 🔥
• Weights & Biases is used to log metrics and visualize results.
• pytest is used for testing.

Who is this for? Why should you use this template?

This template comes with some unique features that can only be found here (for now)!

• Torch and Jax support
• Rich IDE support for Hydra config files
• Built-in automated tests (including reproducibility tests), including testing on SLURM clusters!
• And more! (see this page)

To make the best use of this template, you should ideally already have a good understanding of Python, some experience with PyTorch, and some basic experience with SLURM.

See this page for a list of other templates to choose from if this isn't for you.

Please consider making an issue on this repo if you feel like this could be improved, or something is confusing to you. We very much need and appreciate your feedback! 😊

Usage

To see all available options:

python project/main.py --help

For a detailed list of examples, see the examples page.

Project layout

pyproject.toml   # Project metadata and dependencies
project/
    main.py      # main entry-point
    algorithms/  # learning algorithms
    datamodules/ # datasets, processing and loading
    networks/    # Neural networks used by algorithms
    configs/     # configuration files
docs/            # documentation
conftest.py      # Test fixtures and utilities