super-gradients/docs/_sources/welcome.md.txt

<div align="center">
  <img src="assets/SG_img/SG - Horizontal Glow 2.png" width="600"/>
 <br/><br/>
  
**Build, train, and fine-tune production-ready deep learning  SOTA vision models**
[![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Easily%20train%20or%20fine-tune%20SOTA%20computer%20vision%20models%20from%20one%20training%20repository&url=https://github.com/Deci-AI/super-gradients&via=deci_ai&hashtags=AI,deeplearning,computervision,training,opensource)

#### Version 3 is out! Notebooks have been updated!
______________________________________________________________________
  
  <p align="center">
  <a href="https://www.supergradients.com/">Website</a> •
  <a href="https://deci-ai.github.io/super-gradients/user_guide.html#introducing-the-supergradients-library">User Guide</a> •
  <a href="https://deci-ai.github.io/super-gradients/super_gradients.common.html">Docs</a> •
  <a href="#getting-started">Getting Started</a> •
  <a href="#implemented-model-architectures">Pretrained Models</a> •
  <a href="#community">Community</a> •
  <a href="#license">License</a> •
  <a href="#deci-platform">Deci Platform</a>
</p>
<p align="center">
  <a href="https://github.com/Deci-AI/super-gradients#prerequisites"><img src="https://img.shields.io/badge/python-3.7%20%7C%203.8%20%7C%203.9-blue" />
  <a href="https://github.com/Deci-AI/super-gradients#prerequisites"><img src="https://img.shields.io/badge/pytorch-1.9%20%7C%201.10-blue" />
  <a href="https://pypi.org/project/super-gradients/"><img src="https://img.shields.io/pypi/v/super-gradients" />
  <a href="https://github.com/Deci-AI/super-gradients#computer-vision-models-pretrained-checkpoints" ><img src="https://img.shields.io/badge/pre--trained%20models-34-brightgreen" />
  <a href="https://github.com/Deci-AI/super-gradients/releases"><img src="https://img.shields.io/github/v/release/Deci-AI/super-gradients" />
  <a href="https://join.slack.com/t/supergradients-comm52/shared_invite/zt-10vz6o1ia-b_0W5jEPEnuHXm087K~t8Q"><img src="https://img.shields.io/badge/slack-community-blueviolet" />
  <a href="https://github.com/Deci-AI/super-gradients/blob/master/LICENSE.md"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" />
  <a href="https://deci-ai.github.io/super-gradients/welcome.html"><img src="https://img.shields.io/badge/docs-sphinx-brightgreen" />
</p>    
</div>

[](https://deci-ai.github.io/super-gradients/user_guide.html#introducing-the-supergradients-library)

## Build with SuperGradients
__________________________________________________________________________________________________________

### Support various computer vision tasks
<div align="center">
<img src="./assets/SG_img/Segmentation 1500x900 .png" width="250px">
<img src="./assets/SG_img/Object detection 1500X900.png" width="250px">
<img src="./assets/SG_img/Classification 1500x900.png" width="250px">
</div>


### Ready to deploy pre-trained SOTA models
```python
# Load model with pretrained weights
from super_gradients.common.object_names import Models
from super_gradients.training import models

model = models.get(Models.YOLOX_S, pretrained_weights="coco")
```

#### Classification
<div align="center">
<img src="./assets/SG_img/Classification@2xDark.png" width="800px">
</div>

#### Semantic Segmentation
<div align="center">
<img src="./assets/SG_img/Semantic Segmentation@2xDark.png" width="800px">
</div>

#### Object Detection 
<div align="center">
<img src="./assets/SG_img/Object Detection@2xDark.png" width="800px">
</div>



All Computer Vision Models - Pretrained Checkpoints can be found [here](src/super_gradients/training/Computer_Vision_Models_Pretrained_Checkpoints.md)


### Easy to train SOTA Models

Easily load and fine-tune production-ready, pre-trained SOTA models that incorporate best practices and validated hyper-parameters for achieving best-in-class accuracy. 
For more information on how to do it go to [Getting Started](#getting-started)
    

### Plug and play recipes
```python
python -m super_gradients.train_from_recipe --config-name=imagenet_regnetY architecture=regnetY800 dataset_interface.data_dir=<YOUR_Imagenet_LOCAL_PATH> ckpt_root_dir=<CHEKPOINT_DIRECTORY>
```
More example on how and why to use recipes can be found in [Recipes](#recipes)


### Production readiness
All SuperGradients models’ are production ready in the sense that they are compatible with deployment tools such as TensorRT (Nvidia) and OpenVINO (Intel) and can be easily taken into production. With a few lines of code you can easily integrate the models into your codebase.
```python
# Load model with pretrained weights
from super_gradients.training import models
from super_gradients.common.object_names import Models

model = models.get(Models.YOLOX_S, pretrained_weights="coco")

# Prepare model for conversion
# Input size is in format of [Batch x Channels x Width x Height] where 640 is the standart COCO dataset dimensions
model.eval()
model.prep_model_for_conversion(input_size=[1, 3, 640, 640])
    
# Create dummy_input

# Convert model to onnx
torch.onnx.export(model, dummy_input,  "yolox_s.onnx")
```
More information on how to take your model to production can be found in [Getting Started](#getting-started) notebooks

## Quick Installation

__________________________________________________________________________________________________________

 
```bash
pip install super-gradients
```

## What's New
__________________________________________________________________________________________________________
* 【06/9/2022】 PP-LiteSeg - new pre-trained [checkpoints](src/super_gradients/training/Computer_Vision_Models_Pretrained_Checkpoints.md)  for Cityscapes with SOTA mIoU scores (~1.5% above paper)🎯
* 【07/08/2022】DDRNet23 -  new pre-trained [checkpoints](src/super_gradients/training/Computer_Vision_Models_Pretrained_Checkpoints.md) and [recipes](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/recipes) for Cityscapes with SOTA mIoU scores (~1% above paper)🎯
* 【27/07/2022】YOLOX models (object detection) - recipes and pre-trained checkpoints.
* 【07/07/2022】SSD Lite MobileNet V2,V1 - Training [recipes](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/recipes/coco_ssd_lite_mobilenet_v2.yaml) and pre-trained [checkpoints](src/super_gradients/training/Computer_Vision_Models_Pretrained_Checkpoints.md) on COCO - Tailored for edge devices! 📱
* 【07/07/2022】 STDC  - new pre-trained [checkpoints](src/super_gradients/training/Computer_Vision_Models_Pretrained_Checkpoints.md) and [recipes](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/recipes) for Cityscapes with super SOTA mIoU scores (~2.5% above paper)🎯

Check out SG full [release notes](https://github.com/Deci-AI/super-gradients/releases).

## Coming soon
__________________________________________________________________________________________________________
- [ ] PP-LiteSeg recipes for Cityscapes with SOTA mIoU scores (~1.5% above paper)🎯
- [ ] Single class detectors (recipes, pre-trained checkpoints) for edge devices deployment.
- [ ] Single class segmentation (recipes, pre-trained checkpoints) for edge devices deployment.
- [ ] QAT capabilities (Quantization Aware Training).
- [ ] Integration with more professional tools.


## Table of Content
__________________________________________________________________________________________________________
<!-- toc -->

- [Getting Started](#getting-started)
- [Advanced Features](#advanced-features)
- [Installation Methods](#installation-methods)
    - [Prerequisites](#prerequisites)
    - [Quick Installation](#quick-installation)
- [Implemented Model Architectures](#implemented-model-architectures)
- [Contributing](#contributing)
- [Citation](#citation)
- [Community](#community)
- [License](#license)
- [Deci Platform](#deci-platform)

<!-- tocstop -->

## Getting Started
__________________________________________________________________________________________________________

### Start Training with Just 1 Command Line
The most simple and straightforward way to start training SOTA performance models with SuperGradients reproducible recipes. Just define your dataset path and where you want your checkpoints to be saved and you are good to go from your terminal!
    
```bash
python -m super_gradients.train_from_recipe --config-name=imagenet_regnetY architecture=regnetY800 dataset_interface.data_dir=<YOUR_Imagenet_LOCAL_PATH> ckpt_root_dir=<CHEKPOINT_DIRECTORY>
```
### Quickly Load Pre-Trained Weights for Your Desired Model with SOTA Performance
Want to try our pre-trained models on your machine? Import SuperGradients, initialize your Trainer, and load your desired architecture and pre-trained weights from our [SOTA model zoo](src/super_gradients/training/Computer_Vision_Models_Pretrained_Checkpoints.md)

```python
# The pretrained_weights argument will load a pre-trained architecture on the provided dataset
    
import super_gradients

model = models.get("model-name", pretrained_weights="pretrained-model-name")

```   
###  Classification

#### Transfer Learning 
  <table class="tfo-notebook-buttons" align="left">
 <td width="500">  
  <a target="_blank" href="https://bit.ly/3xzIutb"><img src="./assets/SG_img/colab_logo.png" /> Classification Transfer Learning</a>
  </td>
 <td width="200">    
 <a target="_blank" href="https://bit.ly/3xwYEn1"><img src="./assets/SG_img/GitHub_logo.png" /> GitHub source</a>
 </td>
</table>
 </br></br>


###  Semantic Segmentation

####  Quick Start 
<table class="tfo-notebook-buttons" align="left">
 <td width="500">
<a target="_blank" href="https://bit.ly/3qKx9m8"><img src="./assets/SG_img/colab_logo.png" /> Segmentation Quick Start</a>
 </td>
 <td width="200">
<a target="_blank" href="https://bit.ly/3qJjxYq"><img src="./assets/SG_img/GitHub_logo.png" /> GitHub source </a>
 </td>
</table>
 </br></br>


 
 ####  Transfer Learning 
<table class="tfo-notebook-buttons" align="left">
 <td width="500">
<a target="_blank" href="https://bit.ly/3qKwMbe"><img src="./assets/SG_img/colab_logo.png" /> Segmentation Transfer Learning</a>
 </td>
 <td width="200">
<a target="_blank" href="https://bit.ly/3ShJlXn"><img src="./assets/SG_img/GitHub_logo.png" /> GitHub source</a>
 </td>
</table>
 </br></br>



####  How to Connect Custom Dataset 
  <table class="tfo-notebook-buttons" align="left">
 <td width="500"> 
<a target="_blank" href="https://bit.ly/3QQBVJp"><img src="./assets/SG_img/colab_logo.png" /> Segmentation How to Connect Custom Dataset</a>
   </td>
 <td width="200">
 <a target="_blank" href="https://bit.ly/3Us2WGi"><img src="./assets/SG_img/GitHub_logo.png" /> GitHub source</a>
 </td>
</table>
 </br></br>



###  Object Detection


#### Transfer Learning
  <table class="tfo-notebook-buttons" align="left">
 <td width="500">   
<a target="_blank" href="https://bit.ly/3SkMohx"><img src="./assets/SG_img/colab_logo.png" /> Detection Transfer Learning</a>
   </td>
 <td width="200">   
<a target="_blank" href="https://bit.ly/3DF8siG"><img src="./assets/SG_img/GitHub_logo.png" /> GitHub source</a>
 </td>
</table>
 </br></br>

#### How to Connect Custom Dataset 
  <table class="tfo-notebook-buttons" align="left">
 <td width="500">  
  <a target="_blank" href="https://bit.ly/3dqDlg3"><img src="./assets/SG_img/colab_logo.png" /> Detection How to Connect Custom Dataset</a>
  </td>
 <td width="200">      
<a target="_blank" href="https://bit.ly/3xBlcmq"><img src="./assets/SG_img/GitHub_logo.png" /> GitHub source</a>
 </td>
</table>
 </br></br>



### How to Predict Using Pre-trained Model

#### Segmentation, Detection and Classification Prediction 
  <table class="tfo-notebook-buttons" align="left">
 <td width="500">    
<a target="_blank" href="https://bit.ly/3f4mssd"><img src="./assets/SG_img/colab_logo.png" /> How to Predict Using Pre-trained Model</a>
  </td>
 <td width="200">   
<a target="_blank" href="https://bit.ly/3Sf59Tr"><img src="./assets/SG_img/GitHub_logo.png" /> GitHub source</a>
 </td>
</table>
 </br></br>


## Advanced Features
__________________________________________________________________________________________________________
### Knowledge Distillation Training
Knowledge Distillation is a training technique that uses a large model, teacher model, to improve the performance of a smaller model, the student model.
Learn more about SuperGradients knowledge distillation training with our pre-trained BEiT base teacher model and Resnet18 student model on CIFAR10 example notebook on Google Colab for an easy to use tutorial using free GPU hardware
  <table class="tfo-notebook-buttons" align="left">
 <td width="500">   
   <a target="_blank" href="https://bit.ly/3BLA5oR"><img src="./assets/SG_img/colab_logo.png" /> Knowledge Distillation Training</a>
  </td>
 <td width="200">   
<a target="_blank" href="https://bit.ly/3S9UlG4"><img src="./assets/SG_img/GitHub_logo.png" /> GitHub source</a>
 </td>
</table>
 </br></br>

### Recipes
To train a model, it is necessary to configure 4 main components. These components are aggregated into a single "main" recipe `.yaml` file that inherits the aforementioned dataset, architecture, raining and checkpoint params. It is also possible (and recomended for flexibility) to override default settings with custom ones.
All recipes can be found [here](src/super_gradients/recipes/Training_Recipes.md)
  <table class="tfo-notebook-buttons" align="left">
 <td width="500">   
   <a target="_blank" href="https://bit.ly/3UiY5ab"><img src="./assets/SG_img/colab_logo.png" /> How to Use Recipes</a>
  </td>
 <td width="200">  
<a target="_blank" href="https://bit.ly/3QSrHbm"><img src="./assets/SG_img/GitHub_logo.png" /> GitHub source</a>
 </td>
</table>
 </br></br>


### Using DDP
```python
from super_gradients import init_trainer
from super_gradients.common import MultiGPUMode
from super_gradients.training.utils.distributed_training_utils import setup_gpu_mode

# Initialize the environment
init_trainer()

# Launch DDP on 1 device (node) of 4 GPU's
setup_gpu_mode(gpu_mode=MultiGPUMode.DISTRIBUTED_DATA_PARALLEL, num_gpus=4)

# Define the objects

# The trainer will run on DDP without anything else to change
```
### Easily change architectures parameters
```python
from super_gradients.training import models

# instantiate default pretrained resnet18
default_resnet18 = models.get(name="resnet18", num_classes=100, pretrained_weights="imagenet")

# instantiate pretrained resnet18, turning DropPath on with probability 0.5
droppath_resnet18 = models.get(name="resnet18", arch_params={"droppath_prob": 0.5}, num_classes=100, pretrained_weights="imagenet")

# instantiate pretrained resnet18, without classifier head. Output will be from the last stage before global pooling
backbone_resnet18 = models.get(name="resnet18", arch_params={"backbone_mode": True}, pretrained_weights="imagenet")
```

### Using phase callbacks
```python
from super_gradients import Trainer
from torch.optim.lr_scheduler import ReduceLROnPlateau
from super_gradients.training.utils.callbacks import Phase, LRSchedulerCallback
from super_gradients.training.metrics.classification_metrics import Accuracy

# define PyTorch train and validation loaders and optimizer

# define what to be called in the callback
rop_lr_scheduler = ReduceLROnPlateau(optimizer, mode="max", patience=10, verbose=True)

# define phase callbacks, they will fire as defined in Phase
phase_callbacks = [LRSchedulerCallback(scheduler=rop_lr_scheduler,
                                       phase=Phase.VALIDATION_EPOCH_END,
                                       metric_name="Accuracy")]

# create a trainer object, look the declaration for more parameters
trainer = Trainer("experiment_name")

# define phase_callbacks as part of the training parameters
train_params = {"phase_callbacks": phase_callbacks}
```
### Integration to Weights and Biases
```python
from super_gradients import Trainer

# create a trainer object, look the declaration for more parameters
trainer = Trainer("experiment_name")

train_params = { ... # training parameters
                "sg_logger": "wandb_sg_logger", # Weights&Biases Logger, see class WandBSGLogger for details
                "sg_logger_params": # paramenters that will be passes to __init__ of the logger 
                  {
                    "project_name": "project_name", # W&B project name
                    "save_checkpoints_remote": True
                    "save_tensorboard_remote": True
                    "save_logs_remote": True
                  } 
               }
```


## Installation Methods
__________________________________________________________________________________________________________
### Prerequisites
<details>
  
<summary>General requirements</summary>
  
- Python 3.7, 3.8 or 3.9 installed.
- torch>=1.9.0
  - https://pytorch.org/get-started/locally/
- The python packages that are specified in requirements.txt;

</details>
    
<details>
  
<summary>To train on nvidia GPUs</summary>
  
- [Nvidia CUDA Toolkit >= 11.2](https://developer.nvidia.com/cuda-11.2.0-download-archive?target_os=Linux&target_arch=x86_64&target_distro=Ubuntu)
- CuDNN >= 8.1.x
- Nvidia Driver with CUDA >= 11.2 support (≥460.x)
  
</details>
    
### Quick Installation

<details>
  
<summary>Install stable version using PyPi</summary>

See in [PyPi](https://pypi.org/project/super-gradients/)
```bash
pip install super-gradients
```

That's it !

</details>
    
<details>
  
<summary>Install using GitHub</summary>


```bash
pip install git+https://github.com/Deci-AI/super-gradients.git@stable
```

</details> 


## Implemented Model Architectures 
__________________________________________________________________________________________________________

Detailed list can be found [here](src/super_gradients/training/models/Implemented%20Model%20Architectures.md) 

### Image Classification
  
- [DensNet (Densely Connected Convolutional Networks)](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/densenet.py) 
- [DPN](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/dpn.py) 
- [EfficientNet](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/efficientnet.py)
- [LeNet](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/lenet.py) 
- [MobileNet](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/mobilenet.py)
- [MobileNet v2](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/mobilenetv2.py)  
- [MobileNet v3](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/mobilenetv3.py) 
- [PNASNet](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/pnasnet.py) 
- [Pre-activation ResNet](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/preact_resnet.py)  
- [RegNet](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/regnet.py)
- [RepVGG](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/repvgg.py)  
- [ResNet](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/resnet.py)
- [ResNeXt](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/resnext.py) 
- [SENet ](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/senet.py)
- [ShuffleNet](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/shufflenet.py)
- [ShuffleNet v2](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/shufflenetv2.py)
- [VGG](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/classification_models/vgg.py)
  
### Semantic Segmentation 

- [PP-LiteSeg](https://bit.ly/3RrtMMO)
- [DDRNet (Deep Dual-resolution Networks)](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/segmentation_models/ddrnet.py) 
- [LadderNet](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/segmentation_models/laddernet.py)
- [RegSeg](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/segmentation_models/regseg.py)
- [ShelfNet](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/segmentation_models/shelfnet.py) 
- [STDC](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/segmentation_models/stdc.py)
  

### Object Detection
  
- [CSP DarkNet](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/detection_models/csp_darknet53.py)
- [DarkNet-53](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/detection_models/darknet53.py)
- [SSD (Single Shot Detector)](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/detection_models/ssd.py) 
- [YOLOX](https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/training/models/detection_models/yolox.py)
  
  

__________________________________________________________________________________________________________


## Documentation

Check SuperGradients [Docs](https://deci-ai.github.io/super-gradients/welcome.html) for full documentation, user guide, and examples.
  
## Contributing

To learn about making a contribution to SuperGradients, please see our [Contribution page](CONTRIBUTING.md).

Our awesome contributors:
    
<a href="https://github.com/Deci-AI/super-gradients/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=Deci-AI/super-gradients" />
</a>


<br/>Made with [contrib.rocks](https://contrib.rocks).

## Citation

If you are using SuperGradients library or benchmarks in your research, please cite SuperGradients deep learning training library.

## Community

If you want to be a part of SuperGradients growing community, hear about all the exciting news and updates, need help, request for advanced features,
    or want to file a bug or issue report, we would love to welcome you aboard!

* Slack is the place to be and ask questions about SuperGradients and get support. [Click here to join our Slack](
  https://join.slack.com/t/supergradients-comm52/shared_invite/zt-10vz6o1ia-b_0W5jEPEnuHXm087K~t8Q)
    
* To report a bug, [file an issue](https://github.com/Deci-AI/super-gradients/issues) on GitHub.

* Join the [SG Newsletter](https://www.supergradients.com/#Newsletter)
  for staying up to date with new features and models, important announcements, and upcoming events.
    
* For a short meeting with us, use this [link](https://calendly.com/ofer-baratz-deci/15min) and choose your preferred time.

## License

This project is released under the [Apache 2.0 license](LICENSE).
    

    
__________________________________________________________________________________________________________


## Deci Platform

Deci Platform is our end to end platform for building, optimizing and deploying deep learning models to production.

[Request free trial](https://bit.ly/3qO3icq) to enjoy immediate improvement in throughput, latency, memory footprint and model size.

Features:
- Automatically compile and quantize your models with just a few clicks (TensorRT, OpenVINO).
- Gain up to 10X improvement in throughput, latency, memory and model size. 
- Easily benchmark your models’ performance on different hardware and batch sizes.
- Invite co-workers to collaborate on models and communicate your progress.
- Deci supports all common frameworks and Hardware, from Intel CPUs to Nvidia's GPUs and Jetsons.
ֿ

Request free trial [here](https://bit.ly/3qO3icq)