diff --git a/README.md b/README.md index 98ab5d2d..cf80ca20 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +
+ # Research Project Template [![Build](https://github.com/mila-iqia/ResearchTemplate/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/mila-iqia/ResearchTemplate/actions/workflows/build.yml) @@ -5,12 +7,15 @@ [![hydra](https://img.shields.io/badge/Config-Hydra_1.3-89b8cd)](https://hydra.cc/) [![license](https://img.shields.io/badge/License-MIT-green.svg?labelColor=gray)](https://github.com/mila-iqia/ResearchTemplate#license) -Please note: This is a Work-in-Progress. The goal is to make a first release by the end of summer 2024. +πŸš€ Get started on a new research project with a clean, robust and well-tested base that you can count on! πŸš€ -This is a template repository for a research project in machine learning. It is meant to be a starting point for new ML researchers that run jobs on SLURM clusters. -The main target audience is [Mila](https://mila.quebec/en) researchers and students, but this should still be useful to anyone that uses PyTorch-Lightning with Hydra. +
-For more context, see [this introduction to the project.](https://mila-iqia.github.io/ResearchTemplate/intro). +This is a project template for ML researchers developed at [Mila](https://www.mila.quebec). Our goal with this is to help you get started with a new research project. + +See [this introduction to the project](https://mila-iqia.github.io/ResearchTemplate/intro) for a detailed description of the context and motivations behind this project. + +Please note: This is a Work-in-Progress. The goal is to make a first release by the end of summer 2024. ## Installation @@ -32,19 +37,20 @@ This project makes use of the following libraries: - [Weights & Biases](https://wandb.ai) is used to log metrics and visualize results. - [pytest](https://docs.pytest.org/en/stable/) is used for testing. -## Why use this template? +## 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)!](https://mila-iqia.github.io/ResearchTemplate/features/index.md) + +- [Torch and Jax support](https://mila-iqia.github.io/ResearchTemplate/features/jax/) +- [Rich IDE support for Hydra config files](https://mila-iqia.github.io/ResearchTemplate/features/auto_schema/) +- [Built-in automated tests (including reproducibility tests), including testing on SLURM clusters!](https://mila-iqia.github.io/ResearchTemplate/features/testing/) +- And more! (see [this page](https://mila-iqia.github.io/ResearchTemplate/features/)) -Why should you use this template (instead of another)? +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. -Here are some of the advantages to using this template compared to [some of the other templates out there](https://mila-iqia.github.io/ResearchTemplate/related): +See [this page](https://mila-iqia.github.io/ResearchTemplate/related) for a list of other templates to choose from if this isn't for you. -- ❗Can use both PyTorch and Jax with PyTorch-Lightning ❗ -- Neat Configs thanks to [Auto-Generated YAML schemas](https://mila-iqia.github.io/ResearchTemplate/features/auto_schema) -- Easy development inside a [Development Container](https://code.visualstudio.com/docs/remote/containers) with [VsCode](https://code.visualstudio.com/) -- Tailor-made for ML researchers that run their jobs on SLURM clusters (with default configurations for the [Mila](https://docs.mila.quebec) and [DRAC](https://docs.alliancecan.ca) clusters.) -- Rich typing and documentation of all parts of the source code using Python 3.12's new type annotation syntax -- A comprehensive suite of automated tests for all algorithms, datasets and networks that are easy to reuse and extend -- Automatically creates Yaml Schemas for your Hydra config files (as soon as #7 is merged) +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 @@ -54,7 +60,7 @@ To see all available options: python project/main.py --help ``` -For a detailed list of examples, see the [examples page](https://mila-iqia.github.io/ResearchTemplate/examples/examples). +For a detailed list of examples, see the [examples page](https://mila-iqia.github.io/ResearchTemplate/examples). +| Example link | Research Area | Reference link | Frameworks | +| --------------------------------------- | ------------------------------------------ | ------------------ | --------------- | +| [ExampleAlgorithm](torch_sl_example.md) | Supervised Learning (image classification) | `ExampleAlgorithm` | Torch + ⚑ | +| [JaxExample](jax_sl_example.md) | Supervised Learning (image classification) | `JaxExample` | Torch + Jax + ⚑ | +| [HFExample](nlp.md) | NLP (text classification) | `HFExample` | Torch + πŸ€— + ⚑ | +| [JaxRLExample](jax_rl_example.md) | RL | `JaxRLExample` | Jax | diff --git a/docs/examples/supervised_learning.md b/docs/examples/torch_sl_example.md similarity index 100% rename from docs/examples/supervised_learning.md rename to docs/examples/torch_sl_example.md