Giter VIP home page Giter VIP logo

pytorch-lightning's Introduction

Logo

PyTorch Lightning

The lightweight PyTorch wrapper for ML researchers. Scale your models. Write less boilerplate.

PyPI Status PyPI Status Build Status Build status Coverage CodeFactor

ReadTheDocs Gitter license Next Release

Simple installation from PyPI

pip install pytorch-lightning  

Docs

View the docs here

What is it?

Lightning is a very lightweight wrapper on PyTorch. This means you don't have to learn a new library. To use Lightning, simply refactor your research code into the LightningModule format and Lightning will automate the rest. Lightning guarantees tested, correct, modern best practices for the automated parts.

Starting a new project?

Use our seed-project aimed at reproducibility!

Why do I want to use lightning?

Every research project starts the same, a model, a training loop, validation loop, etc. As your research advances, you're likely to need distributed training, 16-bit precision, checkpointing, gradient accumulation, etc.

Lightning sets up all the boilerplate state-of-the-art training for you so you can focus on the research.


README Table of Contents


How do I do use it?

Think about Lightning as refactoring your research code instead of using a new framework. The research code goes into a LightningModule which you fit using a Trainer.

The LightningModule defines a system such as seq-2-seq, GAN, etc... It can ALSO define a simple classifier such as the example below.

To use lightning do 2 things:

  1. Define a LightningModule

WARNING: This syntax is for version 0.5.0+ where abbreviations were removed.

import os
import torch
from torch.nn import functional as F
from torch.utils.data import DataLoader
from torchvision.datasets import MNIST
import torchvision.transforms as transforms

import pytorch_lightning as pl

class CoolSystem(pl.LightningModule):

    def __init__(self):
        super(CoolSystem, self).__init__()
        # not the best model...
        self.l1 = torch.nn.Linear(28 * 28, 10)

    def forward(self, x):
        return torch.relu(self.l1(x.view(x.size(0), -1)))

    def training_step(self, batch, batch_nb):
        # REQUIRED
        x, y = batch
        y_hat = self.forward(x)
        loss = F.cross_entropy(y_hat, y)
        tensorboard_logs = {'train_loss': loss}
        return {'loss': loss, 'log': tensorboard_logs}

    def validation_step(self, batch, batch_nb):
        # OPTIONAL
        x, y = batch
        y_hat = self.forward(x)
        return {'val_loss': F.cross_entropy(y_hat, y)}

    def validation_end(self, outputs):
        # OPTIONAL
        avg_loss = torch.stack([x['val_loss'] for x in outputs]).mean()
        tensorboard_logs = {'val_loss': avg_loss}
        return {'avg_val_loss': avg_loss, 'log': tensorboard_logs}

    def configure_optimizers(self):
        # REQUIRED
        # can return multiple optimizers and learning_rate schedulers
        # (LBFGS it is automatically supported, no need for closure function)
        return torch.optim.Adam(self.parameters(), lr=0.02)

    @pl.data_loader
    def train_dataloader(self):
        # REQUIRED
        return DataLoader(MNIST(os.getcwd(), train=True, download=True, transform=transforms.ToTensor()), batch_size=32)

    @pl.data_loader
    def val_dataloader(self):
        # OPTIONAL
        return DataLoader(MNIST(os.getcwd(), train=True, download=True, transform=transforms.ToTensor()), batch_size=32)

    @pl.data_loader
    def test_dataloader(self):
        # OPTIONAL
        return DataLoader(MNIST(os.getcwd(), train=True, download=True, transform=transforms.ToTensor()), batch_size=32)
  1. Fit with a trainer
from pytorch_lightning import Trainer

model = CoolSystem()

# most basic trainer, uses good defaults
trainer = Trainer()    
trainer.fit(model)   

Trainer sets up a tensorboard logger, early stopping and checkpointing by default (you can modify all of them or use something other than tensorboard).

Here are more advanced examples

# train on cpu using only 10% of the data (for demo purposes)
trainer = Trainer(max_nb_epochs=1, train_percent_check=0.1)

# train on 4 gpus (lightning chooses GPUs for you)
# trainer = Trainer(max_nb_epochs=1, gpus=4, distributed_backend='ddp')  

# train on 4 gpus (you choose GPUs)
# trainer = Trainer(max_nb_epochs=1, gpus=[0, 1, 3, 7], distributed_backend='ddp')   

# train on 32 gpus across 4 nodes (make sure to submit appropriate SLURM job)
# trainer = Trainer(max_nb_epochs=1, gpus=8, nb_gpu_nodes=4, distributed_backend='ddp')

# train (1 epoch only here for demo)
trainer.fit(model)

# view tensorboard logs 
print('View tensorboard logs by running\ntensorboard --logdir %s' % os.getcwd())
print('and going to http://localhost:6006 on your browser')

When you're all done you can even run the test set separately.

trainer.test()

What does lightning control for me?

Everything in gray!
You define the blue parts using the LightningModule interface:

Overview

# what to do in the training loop
def training_step(self, batch, batch_nb):

# what to do in the validation loop
def validation_step(self, batch, batch_nb):

# how to aggregate validation_step outputs
def validation_end(self, outputs):

# and your dataloaders
def train_dataloader():
def val_dataloader():
def test_dataloader():

Could be as complex as seq-2-seq + attention

# define what happens for training here
def training_step(self, batch, batch_nb):
    x, y = batch
    
    # define your own forward and loss calculation
    hidden_states = self.encoder(x)
     
    # even as complex as a seq-2-seq + attn model
    # (this is just a toy, non-working example to illustrate)
    start_token = '<SOS>'
    last_hidden = torch.zeros(...)
    loss = 0
    for step in range(max_seq_len):
        attn_context = self.attention_nn(hidden_states, start_token)
        pred = self.decoder(start_token, attn_context, last_hidden) 
        last_hidden = pred
        pred = self.predict_nn(pred)
        loss += self.loss(last_hidden, y[step])
        
    #toy example as well
    loss = loss / max_seq_len
    return {'loss': loss} 

Or as basic as CNN image classification

# define what happens for validation here
def validation_step(self, batch, batch_nb):    
    x, y = batch
    
    # or as basic as a CNN classification
    out = self.forward(x)
    loss = my_loss(out, y)
    return {'loss': loss} 

And you also decide how to collate the output of all validation steps

def validation_end(self, outputs):
    """
    Called at the end of validation to aggregate outputs
    :param outputs: list of individual outputs of each validation step
    :return:
    """
    val_loss_mean = 0
    val_acc_mean = 0
    for output in outputs:
        val_loss_mean += output['val_loss']
        val_acc_mean += output['val_acc']

    val_loss_mean /= len(outputs)
    val_acc_mean /= len(outputs)
    logs = {'val_loss': val_loss_mean.item(), 'val_acc': val_acc_mean.item()}
    result = {'log': logs}
    return result

Tensorboard

Lightning is fully integrated with tensorboard, MLFlow and supports any logging module.

tensorboard-support

Lightning also adds a text column with all the hyperparameters for this experiment.

tensorboard-support

Lightning automates all of the following (each is also configurable):

Checkpointing

Computing cluster (SLURM)

Debugging

Distributed training

Experiment Logging

Training loop

Validation loop

Testing loop

Examples

Tutorials


Asking for help

Welcome to the Lightning community!

If you have any questions, feel free to:

  1. read the docs.
  2. Search through the issues.
  3. Ask on stackoverflow with the tag pytorch-lightning.

If no one replies to you quickly enough, feel free to post the stackoverflow link to our Gitter chat!

To chat with the rest of us visit our gitter channel!


FAQ

How do I use Lightning for rapid research?
Here's a walk-through

Why was Lightning created?
Lightning has 3 goals in mind:

  1. Maximal flexibility while abstracting out the common boilerplate across research projects.
  2. Reproducibility. If all projects use the LightningModule template, it will be much much easier to understand what's going on and where to look! It will also mean every implementation follows a standard format.
  3. Democratizing PyTorch power user features. Distributed training? 16-bit? know you need them but don't want to take the time to implement? All good... these come built into Lightning.

How does Lightning compare with Ignite and fast.ai?
Here's a thorough comparison.

Is this another library I have to learn?
Nope! We use pure Pytorch everywhere and don't add unecessary abstractions!

Are there plans to support Python 2?
Nope.

Are there plans to support virtualenv?
Nope. Please use anaconda or miniconda.

Which PyTorch versions do you support?

  • PyTorch 1.1.0
    # install pytorch 1.1.0 using the official instructions   
    
    # install test-tube 0.6.7.6 which supports 1.1.0   
    pip install test-tube==0.6.7.6   
    
    # install latest Lightning version without upgrading deps    
    pip install -U --no-deps pytorch-lightning
  • PyTorch 1.2.0 Install via pip as normal

Custom installation

Bleeding edge

If you can't wait for the next release, install the most up to date code with:

  • using GIT (locally clone whole repo with full history)
    pip install git+https://github.com/williamFalcon/pytorch-lightning.git@master --upgrade
  • using instant zip (last state of the repo without git history)
    pip install https://github.com/williamFalcon/pytorch-lightning/archive/master.zip --upgrade

Any release installation

You can also install any past release from this repository:

pip install https://github.com/williamFalcon/pytorch-lightning/archive/0.4.4.zip --upgrade

pytorch-lightning's People

Contributors

alok avatar ananyahjha93 avatar antvconst avatar astariul avatar borda avatar cdump avatar cinjon avatar codap avatar derek-wds avatar eqs avatar expectationmax avatar expectopatronum avatar festeh avatar ir1d avatar jtamir avatar kvhooreb avatar lewisacidic avatar neggert avatar rikorose avatar rmccorm4 avatar sebftw avatar separius avatar sholalkere avatar shreyasbapat avatar stas6626 avatar thestonemx avatar thomasjpfan avatar vanamsterdam avatar williamfalcon avatar yassersouri avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.