catalyst: A Python repository from AndreySheka

Accelerated DL R&D

PyTorch framework for DL research and development. It was developed with a focus on reproducibility, fast experimentation and code/ideas reusing. Being able to research/develop something new, rather than write another regular train loop.
Break the cycle - use the Catalyst!

Part of PyTorch Ecosystem. Part of Catalyst Ecosystem. Project manifest.

Installation

Common installation:

pip install -U catalyst

Specific versions with additional requirements

pip install catalyst[ml]         # installs DL+ML based catalyst
pip install catalyst[cv]         # installs DL+CV based catalyst
pip install catalyst[nlp]        # installs DL+NLP based catalyst
pip install catalyst[ecosystem]  # installs Catalyst.Ecosystem for DL R&D
pip install catalyst[contrib]    # installs DL+contrib based catalyst
pip install catalyst[all]        # installs everything. Very convenient to deploy on a new server

Catalyst is compatible with: Python 3.6+. PyTorch 1.0.0+.

Getting started

import torch
from catalyst.dl import SupervisedRunner

# experiment setup
logdir = "./logdir"
num_epochs = 42

# data
loaders = {"train": ..., "valid": ...}

# model, criterion, optimizer
model = Net()
criterion = torch.nn.CrossEntropyLoss()
optimizer = torch.optim.Adam(model.parameters())
scheduler = torch.optim.lr_scheduler.ReduceLROnPlateau(optimizer)

# model runner
runner = SupervisedRunner()

# model training
runner.train(
    model=model,
    criterion=criterion,
    optimizer=optimizer,
    scheduler=scheduler,
    loaders=loaders,
    logdir=logdir,
    num_epochs=num_epochs,
    verbose=True,
)

For Catalyst.RL introduction, please follow Catalyst.RL repo.

Docs and examples

Demo with minimal examples for CV, NLP, RecSys and GANs
Detailed classification tutorial
Advanced segmentation tutorial
Comprehensive classification pipeline
Binary and semantic segmentation pipeline

API documentation and an overview of the library can be found here .
In the examples folder of the repository, you can find advanced tutorials and Catalyst best practices.

Infos

To learn more about Catalyst internals and to be aware of the most important features, you can read Catalyst-info – our blog where we regularly write facts about the framework.

We also supervise Awesome Catalyst list – Catalyst-powered projects, tutorials and talks.
Feel free to make a PR with your project to the list. And don't forget to check out current list, there are many interesting projects.

Releases

We deploy a major release once a month with a name like YY.MM.
And micro-releases with framework improvements during a month in the format YY.MM.#.

You can view the changelog on the GitHub Releases page.
Current version:

Overview

Catalyst helps you write compact but full-featured DL pipelines in a few lines of code. You get a training loop with metrics, early-stopping, model checkpointing and other features without the boilerplate.

Features

Universal train/inference loop.
Configuration files for model/data hyperparameters.
Reproducibility – all source code and environment variables will be saved.
Callbacks – reusable train/inference pipeline parts.
Training stages support.
Easy customization.
PyTorch best practices (SWA, AdamW, Ranger optimizer, OneCycle, and more).
Developments best practices - fp16 support, distributed training, slurm.

Structure

core - framework core with main abstractions - Experiment, Runner, State, Callback.
DL – runner for training and inference, all of the classic ML and CV/NLP metrics and a variety of callbacks for training, validation and inference of neural networks.
contrib - additional modules contributed by Catalyst users.
data - useful tools and scripts for data processing.

Docker

Catalyst has its own DockerHub page:

catalystteam/catalyst:{CATALYST_VERSION} – simple image with Catalyst
catalystteam/catalyst:{CATALYST_VERSION}-fp16 – Catalyst with FP16
catalystteam/catalyst:{CATALYST_VERSION}-dev – Catalyst for development with all the requirements
catalystteam/catalyst:{CATALYST_VERSION}-dev-fp16 – Catalyst for development with FP16

To build a docker from the sources and get more information and examples, please visit docker folder.

Contribution guide

We appreciate all contributions. If you are planning to contribute back bug-fixes, please do so without any further discussion. If you plan to contribute new features, utility functions or extensions, please first open an issue and discuss the feature with us.

Please see the contribution guide for more information.
By participating in this project, you agree to abide by its Code of Conduct.

License

This project is licensed under the Apache License, Version 2.0 see the LICENSE file for details

Citation

Please use this bibtex if you want to cite this repository in your publications:

@misc{catalyst,
    author = {Kolesnikov, Sergey},
    title = {Accelerated DL R&D},
    year = {2018},
    publisher = {GitHub},
    journal = {GitHub repository},
    howpublished = {\url{https://github.com/catalyst-team/catalyst}},
}

AndreySheka/catalyst