Research Project Template#

Work-in-Progress

Please note: This is a Work-in-Progress. The goal is to make a first release by the end of fall 2024.

This is a research project template. It is meant to be a starting point for ML researchers at Mila.

For more context, see this introduction to the project..

Set up in 5 minutes

Get started quickly with a single installation script and get up and running in minutes

Getting started
Well-tested, robust codebase

Focus on your research! Let tests take care of detecting bugs and broken configs!

Check out the included tests
Support for both PyTorch and Jax

You can use both PyTorch and Jax for your algorithms! (Lightning handles the rest.)

Check out the Jax example
Ready-to-use examples

Includes examples for Supervised learning(1) and NLP 🤗, with unsupervised learning and RL coming soon.
1. The source code for the example is available here
Check out the examples here

Starting a new project#

To create a new project using this template, Click Here or on the green "Use this template" button on the template's GitHub repository.

Setting up your environment#

Here are two recommended ways to setup your development environment:

Using the uv package manager
Using a development container (recommended if you are able to install Docker on your machine)

Locally (Linux / Mac)Locally (Windows)On a SLURM cluster

Clone your new repo and navigate into it

git clone https://www.github.com/your-username/your-repo-name
cd your-repo-name

Install the package manager

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env

Install dependencies

uv sync  # Creates a virtual environment and installs dependencies in it.

Install WSL following this guide
Follow the installation instructions for Linux

Clone your new repo and navigate into it

git clone https://www.github.com/your-username/your-repo-name
cd your-repo-name

(Mila cluster) - Launch the setup script

If you're on the mila cluster, you can run the setup script on a compute node, just to be nice:
```
srun --pty --gres=gpu:1 --cpus-per-task=4 --mem=16G --time=00:10:00 scripts/mila_setup.sh
```

Usage#

To see all available options:

uv run python project/main.py --help

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

Developing inside a container (advanced)#

This repo provides a Devcontainer configuration for Visual Studio Code to use a Docker container as a pre-configured development environment. This avoids struggles setting up a development environment and makes them reproducible and consistent.

If that sounds useful to you, we recommend you first make yourself familiar with the container tutorials if you want to use them. The devcontainer.json file assumes that you have a GPU locally by default. If not, you can simply comment out the "--gpus" flag in the .devcontainer/devcontainer.json file.

Setup Docker on your local machine

On an Linux machine where you have root access, you can install Docker using the following commands:
```
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```
On Windows or Mac, follow these installation instructions
(optional) Install the nvidia-container-toolkit to use your local machine's GPU(s).
Install the Dev Containers extension for Visual Studio Code.
When opening repository in Visual Studio Code, you should be prompted to reopen the repository in a container:

Alternatively, you can open the command palette (Ctrl+Shift+P) and select Dev Containers: Rebuild and Reopen in Container.