From 5a2b0d63199e00af64124d3ca8a55fa742034de2 Mon Sep 17 00:00:00 2001 From: Kaushik B <45285388+kaushikb11@users.noreply.github.com> Date: Tue, 1 Mar 2022 19:05:35 +0530 Subject: [PATCH] Add Lightning Ecosystem to docs (#11399) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rohit Gupta Co-authored-by: Jirka Borovec Co-authored-by: Adrian Wälchli --- docs/source/ecosystem/bolts.rst | 7 +- docs/source/ecosystem/ecosystem-ci.rst | 28 ++++++++ docs/source/ecosystem/flash.rst | 76 +++++++++++++++++++++ docs/source/ecosystem/metrics.rst | 91 ++++++++++++++++++++++++++ docs/source/ecosystem/transformers.rst | 45 +++++++++++++ docs/source/index.rst | 8 ++- 6 files changed, 250 insertions(+), 5 deletions(-) create mode 100644 docs/source/ecosystem/ecosystem-ci.rst create mode 100644 docs/source/ecosystem/flash.rst create mode 100644 docs/source/ecosystem/metrics.rst create mode 100644 docs/source/ecosystem/transformers.rst diff --git a/docs/source/ecosystem/bolts.rst b/docs/source/ecosystem/bolts.rst index 7b75f7aa1c..77604a53b1 100644 --- a/docs/source/ecosystem/bolts.rst +++ b/docs/source/ecosystem/bolts.rst @@ -1,6 +1,7 @@ -Bolts -===== -`PyTorch Lightning Bolts `_, is our official collection +Lightning Bolts +=============== + +`PyTorch Lightning Bolts `_, is our official collection of prebuilt models across many research domains. .. code-block:: bash diff --git a/docs/source/ecosystem/ecosystem-ci.rst b/docs/source/ecosystem/ecosystem-ci.rst new file mode 100644 index 0000000000..4c5c2e32b9 --- /dev/null +++ b/docs/source/ecosystem/ecosystem-ci.rst @@ -0,0 +1,28 @@ +Ecosystem CI +============ + +`Ecosystem CI `_ automates issue discovery for your projects against Lightning nightly and releases. +It is a lightweight repository that provides easy configuration of Continues Integration running on CPUs and GPUs. +Any user who wants to keep their project aligned with current and future Lightning releases can use the EcoSystem CI to configure their integrations. +Read more: `Stay Ahead of Breaking Changes with the New Lightning Ecosystem CI `_ + +-------------- + +*********************** +Integrate a New Project +*********************** + +Follow the instructions below to add a new project to the PyTorch Lightning ecosystem. + +1. Fork the ecosystem CI repository to be able to create a `new Pull Request `_ and work within a specific branch. +2. Create a new config file in ``configs/`` folder and call it ``.yaml``. +3. Define runtime for CPU and link the config for GPU: + For CPU integrations, list OS and Python version combination to be running with GitHub actions. + For GPU integrations, you only add the path to the config (OS/Linux and Python version is fixed) to be running with Azure pipelines. +4. Add a Contact to the ``.github/CODEOWNERS`` list for your organization folder or just a single project. +5. Create a Draft PR with all mentioned requirements. +6. Join our `Slack `_ (Optional) channel ``#alerts-ecosystem-ci`` to be notified if your project is breaking. + + +To learn more about Ecosystem CI, please refer to the `Ecosystem CI repo `_. +Also, note that some particular implementation details described above may evolve over time. diff --git a/docs/source/ecosystem/flash.rst b/docs/source/ecosystem/flash.rst new file mode 100644 index 0000000000..24d91115e1 --- /dev/null +++ b/docs/source/ecosystem/flash.rst @@ -0,0 +1,76 @@ +Lightning Flash +=============== + +`Lightning Flash `_ is a high-level deep learning framework for fast prototyping, baselining, fine-tuning, and solving deep learning problems. +Flash makes complex AI recipes for over 15 tasks across 7 data domains accessible to all. +It is built for beginners with a simple API that requires very little deep learning background, and for data scientists, Kagglers, applied ML practitioners, and deep learning researchers that +want a quick way to get a deep learning baseline with advanced features PyTorch Lightning offers. + +.. code-block:: bash + + pip install lightning-flash + +----------------- + +********************************* +Using Lightning Flash in 3 Steps! +********************************* + +1. Load your Data +----------------- + +All data loading in Flash is performed via a ``from_*`` classmethod of a ``DataModule``. +Which ``DataModule`` to use and which ``from_*`` methods are available depends on the task you want to perform. +For example, for image segmentation where your data is stored in folders, you would use the ``SemanticSegmentationData``'s `from_folders `_ method: + +.. code-block:: python + + from flash.image import SemanticSegmentationData + + dm = SemanticSegmentationData.from_folders( + train_folder="data/CameraRGB", + train_target_folder="data/CameraSeg", + val_split=0.1, + image_size=(256, 256), + num_classes=21, + ) + +------------ + +2. Configure your Model +----------------------- + +Our tasks come loaded with pre-trained backbones and (where applicable) heads. +You can view the available backbones to use with your task using `available_backbones `_. +Once you've chosen, create the model: + +.. code-block:: python + + from flash.image import SemanticSegmentation + + print(SemanticSegmentation.available_heads()) + # ['deeplabv3', 'deeplabv3plus', 'fpn', ..., 'unetplusplus'] + + print(SemanticSegmentation.available_backbones("fpn")) + # ['densenet121', ..., 'xception'] # + 113 models + + print(SemanticSegmentation.available_pretrained_weights("efficientnet-b0")) + # ['imagenet', 'advprop'] + + model = SemanticSegmentation(head="fpn", backbone="efficientnet-b0", pretrained="advprop", num_classes=dm.num_classes) + +------------ + +3. Finetune! +------------ + +.. code-block:: python + + from flash import Trainer + + trainer = Trainer(max_epochs=3) + trainer.finetune(model, datamodule=datamodule, strategy="freeze") + trainer.save_checkpoint("semantic_segmentation_model.pt") + + +To learn more about Lightning Flash, please refer to the `Lightning Flash documentation `_. diff --git a/docs/source/ecosystem/metrics.rst b/docs/source/ecosystem/metrics.rst new file mode 100644 index 0000000000..15378fa217 --- /dev/null +++ b/docs/source/ecosystem/metrics.rst @@ -0,0 +1,91 @@ +TorchMetrics +============ + +`TorchMetrics `_ is a collection of machine learning metrics for distributed, +scalable PyTorch models and an easy-to-use API to create custom metrics. It has a collection of 60+ PyTorch metrics implementations and +is rigorously tested for all edge cases. + +.. code-block:: bash + + pip install torchmetrics + +In TorchMetrics, we offer the following benefits: + +- A standardized interface to increase reproducibility +- Reduced Boilerplate +- Distributed-training compatible +- Rigorously tested +- Automatic accumulation over batches +- Automatic synchronization across multiple devices + +----------------- + +Example 1: Functional Metrics +----------------------------- + +Below is a simple example for calculating the accuracy using the functional interface: + +.. code-block:: python + + import torch + import torchmetrics + + # simulate a classification problem + preds = torch.randn(10, 5).softmax(dim=-1) + target = torch.randint(5, (10,)) + + acc = torchmetrics.functional.accuracy(preds, target) + +------------ + +Example 2: Module Metrics +------------------------- + +The example below shows how to use the class-based interface: + +.. code-block:: python + + import torch + import torchmetrics + + # initialize metric + metric = torchmetrics.Accuracy() + + n_batches = 10 + for i in range(n_batches): + # simulate a classification problem + preds = torch.randn(10, 5).softmax(dim=-1) + target = torch.randint(5, (10,)) + # metric on current batch + acc = metric(preds, target) + print(f"Accuracy on batch {i}: {acc}") + + # metric on all batches using custom accumulation + acc = metric.compute() + print(f"Accuracy on all data: {acc}") + + # Reseting internal state such that metric ready for new data + metric.reset() + +------------ + +Example 3: TorchMetrics with Lightning +-------------------------------------- + +The example below shows how to use a metric in your :doc:`LightningModule <../common/lightning_module>`: + +.. code-block:: python + + class MyModel(LightningModule): + def __init__(self): + ... + self.accuracy = torchmetrics.Accuracy() + + def training_step(self, batch, batch_idx): + x, y = batch + preds = self(x) + ... + # log step metric + self.accuracy(preds, y) + self.log("train_acc_step", self.accuracy, on_epoch=True) + ... diff --git a/docs/source/ecosystem/transformers.rst b/docs/source/ecosystem/transformers.rst new file mode 100644 index 0000000000..bad06d65e6 --- /dev/null +++ b/docs/source/ecosystem/transformers.rst @@ -0,0 +1,45 @@ +Lightning Transformers +====================== + +`Lightning Transformers `_ offers a flexible interface for training and fine-tuning SOTA Transformer models +using the :doc:`PyTorch Lightning Trainer <../common/trainer>`. + +.. code-block:: bash + + pip install lightning-transformers + +In Lightning Transformers, we offer the following benefits: + +- Powered by `PyTorch Lightning `_ - Accelerators, custom Callbacks, Loggers, and high performance scaling with minimal changes. +- Backed by `HuggingFace Transformers `_ models and datasets, spanning multiple modalities and tasks within NLP/Audio and Vision. +- Task Abstraction for Rapid Research & Experimentation - Build your own custom transformer tasks across all modalities with little friction. +- Powerful config composition backed by `Hydra `_ - simply swap out models, optimizers, schedulers task, and many more configurations without touching the code. +- Seamless Memory and Speed Optimizations - Out-of-the-box training optimizations such as `DeepSpeed ZeRO `_ or `FairScale Sharded Training `_ with no code changes. + +----------------- + +Using Lightning-Transformers +---------------------------- + +Lightning Transformers has a collection of tasks for common NLP problems such as `language_modeling `_, +`translation `_ and more. To use, simply: + +1. Pick a task to train (passed to ``train.py`` as ``task=``) + +2. Pick a dataset (passed to ``train.py`` as ``dataset=``) + +3. Customize the backbone, optimizer, or any component within the config + +4. Add any :doc:`Lightning supported parameters and optimizations <../common/trainer>` + +.. code-block:: bash + + python train.py \ + task= \ + dataset= + backbone.pretrained_model_name_or_path= # Optionally change the HF backbone + optimizer= # Optionally specify optimizer (Default AdamW) + trainer. # Optionally specify Lightning trainer arguments + + +To learn more about Lightning Transformers, please refer to the `Lightning Transformers documentation `_. diff --git a/docs/source/index.rst b/docs/source/index.rst index 68bd904776..0646ae2d35 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -110,10 +110,14 @@ PyTorch Lightning .. toctree:: :maxdepth: 1 - :name: Bolts - :caption: Bolts + :name: Lightning Ecosystem + :caption: Lightning Ecosystem + ecosystem/metrics + ecosystem/flash ecosystem/bolts + ecosystem/transformers + ecosystem/ecosystem-ci .. toctree:: :maxdepth: 1