DeepLearningExamples/PyTorch/Classification/ConvNets/se-resnext101-32x4d
2020-06-27 09:32:20 +02:00
..
img Adding SE-ResNext and ResNext / PyT 2019-12-15 05:13:59 +01:00
training [ConvNets/PyT] Adding support for Ampere and 20.06 container 2020-06-27 09:32:20 +02:00
README.md [ConvNets/PyT] Adding support for Ampere and 20.06 container 2020-06-27 09:32:20 +02:00

SE-ResNeXt101-32x4d For PyTorch

This repository provides a script and recipe to train the SE-ResNeXt101-32x4d model to achieve state-of-the-art accuracy, and is tested and maintained by NVIDIA.

Table Of Contents

Model overview

The SE-ResNeXt101-32x4d is a ResNeXt101-32x4d model with added Squeeze-and-Excitation module introduced in Squeeze-and-Excitation Networks paper.

Squeeze and Excitation module architecture for ResNet-type models:

This model is trained with mixed precision using Tensor Cores on Volta, Turing, and the NVIDIA Ampere GPU architectures. Therefore, researchers can get results 3x faster than training without Tensor Cores, while experiencing the benefits of mixed precision training. This model is tested against each NGC monthly container release to ensure consistent accuracy and performance over time.

We use NHWC data layout when training using Mixed Precision.

Model architecture

SEArch

Image source: Squeeze-and-Excitation Networks

Image shows the architecture of SE block and where is it placed in ResNet bottleneck block.

Default configuration

The following sections highlight the default configurations for the SE-ResNeXt101-32x4d model.

Optimizer

This model uses SGD with momentum optimizer with the following hyperparameters:

  • Momentum (0.875)
  • Learning rate (LR) = 0.256 for 256 batch size, for other batch sizes we linearly scale the learning rate.
  • Learning rate schedule - we use cosine LR schedule
  • For bigger batch sizes (512 and up) we use linear warmup of the learning rate during the first couple of epochs according to Training ImageNet in 1 hour. Warmup length depends on the total training length.
  • Weight decay (WD)= 6.103515625e-05 (1/16384).
  • We do not apply WD on Batch Norm trainable parameters (gamma/bias)
  • Label smoothing = 0.1
  • We train for:
    • 90 Epochs -> 90 epochs is a standard for ImageNet networks
    • 250 Epochs -> best possible accuracy.
  • For 250 epoch training we also use MixUp regularization.

Data augmentation

This model uses the following data augmentation:

  • For training:
    • Normalization
    • Random resized crop to 224x224
      • Scale from 8% to 100%
      • Aspect ratio from 3/4 to 4/3
    • Random horizontal flip
  • For inference:
    • Normalization
    • Scale to 256x256
    • Center crop to 224x224

Feature support matrix

The following features are supported by this model:

Feature ResNeXt101-32x4d
DALI Yes
APEX AMP Yes

Features

  • NVIDIA DALI - DALI is a library accelerating data preparation pipeline. To accelerate your input pipeline, you only need to define your data loader with the DALI library. For more information about DALI, refer to the DALI product documentation.

  • APEX is a PyTorch extension that contains utility libraries, such as Automatic Mixed Precision (AMP), which require minimal network code changes to leverage Tensor Cores performance. Refer to the Enabling mixed precision section for more details.

DALI

We use NVIDIA DALI, which speeds up data loading when CPU becomes a bottleneck. DALI can use CPU or GPU, and outperforms the PyTorch native dataloader.

Run training with --data-backends dali-gpu or --data-backends dali-cpu to enable DALI. For ResNeXt101-32x4d, for DGX1 and DGX2 we recommend --data-backends dali-cpu.

Mixed precision training

Mixed precision is the combined use of different numerical precisions in a computational method. Mixed precision training offers significant computational speedup by performing operations in half-precision format, while storing minimal information in single-precision to retain as much information as possible in critical parts of the network. Since the introduction of Tensor Cores in the Volta and Turing architecture, significant training speedups are experienced by switching to mixed precision -- up to 3x overall speedup on the most arithmetically intense model architectures. Using mixed precision training requires two steps:

  1. Porting the model to use the FP16 data type where appropriate.
  2. Adding loss scaling to preserve small gradient values.

The ability to train deep learning networks with lower precision was introduced in the Pascal architecture and first supported in CUDA 8 in the NVIDIA Deep Learning SDK.

For information about:

Enabling mixed precision

Mixed precision is enabled in PyTorch by using the Automatic Mixed Precision (AMP), a library from APEX that casts variables to half-precision upon retrieval, while storing variables in single-precision format. Furthermore, to preserve small gradient magnitudes in backpropagation, a loss scaling step must be included when applying gradients. In PyTorch, loss scaling can be easily applied by using scale_loss() method provided by AMP. The scaling value to be used can be dynamic or fixed.

For an in-depth walk through on AMP, check out sample usage here. APEX is a PyTorch extension that contains utility libraries, such as AMP, which require minimal network code changes to leverage tensor cores performance.

To enable mixed precision, you can:

  • Import AMP from APEX:

    from apex import amp
    
  • Wrap model and optimizer in amp.initialize:

    model, optimizer = amp.initialize(model, optimizer, opt_level="O1", loss_scale="dynamic")
    
  • Scale loss before backpropagation:

    with amp.scale_loss(loss, optimizer) as scaled_loss:
      scaled_loss.backward()
    

Enabling TF32

TensorFloat-32 (TF32) is the new math mode in NVIDIA A100 GPUs for handling the matrix math also called tensor operations. TF32 running on Tensor Cores in A100 GPUs can provide up to 10x speedups compared to single-precision floating-point math (FP32) on Volta GPUs.

TF32 Tensor Cores can speed up networks using FP32, typically with no loss of accuracy. It is more robust than FP16 for models which require high dynamic range for weights or activations.

For more information, refer to the TensorFloat-32 in the A100 GPU Accelerates AI Training, HPC up to 20x blog post.

TF32 is supported in the NVIDIA Ampere GPU architecture and is enabled by default.

Setup

The following section lists the requirements that you need to meet in order to start training the SE-ResNeXt101-32x4d model.

Requirements

This repository contains Dockerfile which extends the PyTorch NGC container and encapsulates some dependencies. Aside from these dependencies, ensure you have the following components:

For more information about how to get started with NGC containers, see the following sections from the NVIDIA GPU Cloud Documentation and the Deep Learning DGX Documentation:

For those unable to use the PyTorch NGC container, to set up the required environment or create your own container, see the versioned NVIDIA Container Support Matrix.

Quick Start Guide

1. Clone the repository.

git clone https://github.com/NVIDIA/DeepLearningExamples
cd DeepLearningExamples/PyTorch/Classification/

2. Download and preprocess the dataset.

The ResNeXt101-32x4d script operates on ImageNet 1k, a widely popular image classification dataset from the ILSVRC challenge.

PyTorch can work directly on JPEGs, therefore, preprocessing/augmentation is not needed.

To train your model using mixed or TF32 precision with Tensor Cores or using FP32, perform the following steps using the default parameters of the se-resnext101-32x4d model on the ImageNet dataset. For the specifics concerning training and inference, see the Advanced section.

  1. Download the images.

  2. Extract the training data:

mkdir train && mv ILSVRC2012_img_train.tar train/ && cd train
tar -xvf ILSVRC2012_img_train.tar && rm -f ILSVRC2012_img_train.tar
find . -name "*.tar" | while read NAME ; do mkdir -p "${NAME%.tar}"; tar -xvf "${NAME}" -C "${NAME%.tar}"; rm -f "${NAME}"; done
cd ..
  1. Extract the validation data and move the images to subfolders:
mkdir val && mv ILSVRC2012_img_val.tar val/ && cd val && tar -xvf ILSVRC2012_img_val.tar
wget -qO- https://raw.githubusercontent.com/soumith/imagenetloader.torch/master/valprep.sh | bash

The directory in which the train/ and val/ directories are placed, is referred to as <path to imagenet> in this document.

3. Build the SE-RNXT101-32x4d PyTorch NGC container.

docker build . -t nvidia_se-rnxt101-32x4d

4. Start an interactive session in the NGC container to run training/inference.

nvidia-docker run --rm -it -v <path to imagenet>:/imagenet --ipc=host nvidia_se-rnxt101-32x4d

5. Start training

To run training for a standard configuration (DGXA100/DGX1/DGX2, AMP/TF32/FP32, 90/250 Epochs), run one of the scripts in the ./se-resnext101-32x4d/training directory called ./se-resnext101-32x4d/training/{AMP, TF32, FP32}/{DGXA100, DGX1, DGX2}_SE-RNXT101-32x4d_{AMP, TF32, FP32}_{90,250}E.sh.

Ensure ImageNet is mounted in the /imagenet directory.

Example: bash ./se-resnext101-32x4d/training/AMP/DGX1_SE-RNXT101-32x4d_AMP_250E.sh <path were to store checkpoints and logs>

6. Start inference

To run inference on ImageNet on a checkpointed model, run:

python ./main.py --arch se-resnext101-32x4d --evaluate --epochs 1 --resume <path to checkpoint> -b <batch size> <path to imagenet>

To run inference on JPEG image, you have to first extract the model weights from checkpoint:

python checkpoint2model.py --checkpoint-path <path to checkpoint> --weight-path <path where weights will be stored>

Then run classification script:

python classify.py --arch se-resnext101-32x4d -c fanin --weights <path to weights from previous step> --precision AMP|FP32 --image <path to JPEG image>

Advanced

The following sections provide greater details of the dataset, running training and inference, and the training results.

Scripts and sample code

To run a non standard configuration use:

  • For 1 GPU

    • FP32 python ./main.py --arch se-resnext101-32x4d -c fanin --label-smoothing 0.1 <path to imagenet> python ./main.py --arch se-resnext101-32x4d -c fanin --label-smoothing 0.1 --amp --static-loss-scale 256 <path to imagenet>
  • For multiple GPUs

    • FP32 python ./multiproc.py --nproc_per_node 8 ./main.py --arch se-resnext101-32x4d -c fanin --label-smoothing 0.1 <path to imagenet>
    • AMP python ./multiproc.py --nproc_per_node 8 ./main.py --arch se-resnext101-32x4d -c fanin --label-smoothing 0.1 --amp --static-loss-scale 256 <path to imagenet>

Use python ./main.py -h to obtain the list of available options in the main.py script.

Command-line options:

To see the full list of available options and their descriptions, use the -h or --help command-line option, for example:

python main.py -h

usage: main.py [-h] [--data-backend BACKEND] [--arch ARCH]
               [--model-config CONF] [--num-classes N] [-j N] [--epochs N]
               [--run-epochs N] [-b N] [--optimizer-batch-size N] [--lr LR]
               [--lr-schedule SCHEDULE] [--warmup E] [--label-smoothing S]
               [--mixup ALPHA] [--momentum M] [--weight-decay W]
               [--bn-weight-decay] [--nesterov] [--print-freq N]
               [--resume PATH] [--pretrained-weights PATH] [--fp16]
               [--static-loss-scale STATIC_LOSS_SCALE] [--dynamic-loss-scale]
               [--prof N] [--amp] [--seed SEED] [--gather-checkpoints]
               [--raport-file RAPORT_FILE] [--evaluate] [--training-only]
               [--no-checkpoints] [--checkpoint-filename CHECKPOINT_FILENAME]
               [--workspace DIR] [--memory-format {nchw,nhwc}]
               DIR

PyTorch ImageNet Training

positional arguments:
  DIR                   path to dataset

optional arguments:
  -h, --help            show this help message and exit
  --data-backend BACKEND
                        data backend: pytorch | syntetic | dali-gpu | dali-cpu
                        (default: dali-cpu)
  --arch ARCH, -a ARCH  model architecture: resnet18 | resnet34 | resnet50 |
                        resnet101 | resnet152 | resnext101-32x4d | se-
                        resnext101-32x4d (default: resnet50)
  --model-config CONF, -c CONF
                        model configs: classic | fanin | grp-fanin | grp-
                        fanout(default: classic)
  --num-classes N       number of classes in the dataset
  -j N, --workers N     number of data loading workers (default: 5)
  --epochs N            number of total epochs to run
  --run-epochs N        run only N epochs, used for checkpointing runs
  -b N, --batch-size N  mini-batch size (default: 256) per gpu
  --optimizer-batch-size N
                        size of a total batch size, for simulating bigger
                        batches using gradient accumulation
  --lr LR, --learning-rate LR
                        initial learning rate
  --lr-schedule SCHEDULE
                        Type of LR schedule: step, linear, cosine
  --warmup E            number of warmup epochs
  --label-smoothing S   label smoothing
  --mixup ALPHA         mixup alpha
  --momentum M          momentum
  --weight-decay W, --wd W
                        weight decay (default: 1e-4)
  --bn-weight-decay     use weight_decay on batch normalization learnable
                        parameters, (default: false)
  --nesterov            use nesterov momentum, (default: false)
  --print-freq N, -p N  print frequency (default: 10)
  --resume PATH         path to latest checkpoint (default: none)
  --pretrained-weights PATH
                        load weights from here
  --fp16                Run model fp16 mode.
  --static-loss-scale STATIC_LOSS_SCALE
                        Static loss scale, positive power of 2 values can
                        improve fp16 convergence.
  --dynamic-loss-scale  Use dynamic loss scaling. If supplied, this argument
                        supersedes --static-loss-scale.
  --prof N              Run only N iterations
  --amp                 Run model AMP (automatic mixed precision) mode.
  --seed SEED           random seed used for numpy and pytorch
  --gather-checkpoints  Gather checkpoints throughout the training, without
                        this flag only best and last checkpoints will be
                        stored
  --raport-file RAPORT_FILE
                        file in which to store JSON experiment raport
  --evaluate            evaluate checkpoint/model
  --training-only       do not evaluate
  --no-checkpoints      do not store any checkpoints, useful for benchmarking
  --checkpoint-filename CHECKPOINT_FILENAME
  --workspace DIR       path to directory where checkpoints will be stored
  --memory-format {nchw,nhwc}
                        memory layout, nchw or nhwc

Dataset guidelines

To use your own dataset, divide it in directories as in the following scheme:

  • Training images - train/<class id>/<image>
  • Validation images - val/<class id>/<image>

If your dataset's has number of classes different than 1000, you need to add a custom config in the image_classification/resnet.py file.

resnet_versions = {
    ...
    'se-resnext101-32x4d-custom' : {
        'net' : ResNet,
        'block' : SEBottleneck,
        'cardinality' : 32,
        'layers' : [3, 4, 23, 3],
        'widths' : [128, 256, 512, 1024],
        'expansion' : 2,
        'num_classes' : <custom number of classes>,
    }
}

After adding the config, run the training script with --arch resnext101-32x4d-custom flag.

Training process

All the results of the training will be stored in the directory specified with --workspace argument. Script will store:

  • most recent checkpoint - checkpoint.pth.tar (unless --no-checkpoints flag is used).
  • checkpoint with best validation accuracy - model_best.pth.tar (unless --no-checkpoints flag is used).
  • JSON log - in the file specified with --raport-file flag.

Metrics gathered through training:

  • train.loss - training loss
  • train.total_ips - training speed measured in images/second
  • train.compute_ips - training speed measured in images/second, not counting data loading
  • train.data_time - time spent on waiting on data
  • train.compute_time - time spent in forward/backward pass

Inference process

Validation is done every epoch, and can be also run separately on a checkpointed model.

python ./main.py --arch se-resnext101-32x4d --evaluate --epochs 1 --resume <path to checkpoint> -b <batch size> <path to imagenet>

Metrics gathered through training:

  • val.loss - validation loss
  • val.top1 - validation top1 accuracy
  • val.top5 - validation top5 accuracy
  • val.total_ips - inference speed measured in images/second
  • val.compute_ips - inference speed measured in images/second, not counting data loading
  • val.data_time - time spent on waiting on data
  • val.compute_time - time spent on inference

To run inference on JPEG image, you have to first extract the model weights from checkpoint:

python checkpoint2model.py --checkpoint-path <path to checkpoint> --weight-path <path where weights will be stored>

Then run classification script:

python classify.py --arch se-resnext101-32x4d -c fanin --weights <path to weights from previous step> --precision AMP|FP32 --image <path to JPEG image>

Performance

Benchmarking

The following section shows how to run benchmarks measuring the model performance in training and inference modes.

Training performance benchmark

To benchmark training, run:

  • For 1 GPU
    • FP32 python ./main.py --arch se-resnext101-32x4d -b <batch_size> --training-only -p 1 --raport-file benchmark.json --epochs 1 --prof 100 <path to imagenet>
    • AMP python ./main.py --arch se-resnext101-32x4d -b <batch_size> --training-only -p 1 --raport-file benchmark.json --epochs 1 --prof 100 --amp --static-loss-scale 256 --memory-format nhwc <path to imagenet>
  • For multiple GPUs
    • FP32 python ./multiproc.py --nproc_per_node 8 ./main.py --arch se-resnext101-32x4d -b <batch_size> --training-only -p 1 --raport-file benchmark.json --epochs 1 --prof 100 <path to imagenet>
    • AMP python ./multiproc.py --nproc_per_node 8 ./main.py --arch se-resnext101-32x4d -b <batch_size> --training-only -p 1 --raport-file benchmark.json --amp --static-loss-scale 256 --memory-format nhwc --epochs 1 --prof 100 <path to imagenet>

Each of these scripts will run 100 iterations and save results in the benchmark.json file.

Batch size should be picked appropriately depending on the hardware configuration.

Platform Precision Batch Size
DGXA100 AMP 128
DGXA100 TF32 128
DGX-1 AMP 128
DGX-1 FP32 64

Inference performance benchmark

To benchmark inference, run:

  • FP32

python ./main.py --arch se-resnext101-32x4d -b <batch_size> -p 1 --raport-file benchmark.json --epochs 1 --prof 100 --evaluate <path to imagenet>

  • AMP

python ./main.py --arch se-resnext101-32x4d -b <batch_size> -p 1 --raport-file benchmark.json --epochs 1 --prof 100 --evaluate --amp --memory-format nhwc <path to imagenet>

Each of these scripts will run 100 iterations and save results in the benchmark.json file.

Batch size should be picked appropriately depending on the hardware configuration.

Platform Precision Batch Size
DGXA100 AMP 128
DGXA100 TF32 128
DGX-1 AMP 128
DGX-1 FP32 64

Results

Our results were obtained by running the applicable training script in the pytorch-20.06 NGC container.

To achieve these same results, follow the steps in the Quick Start Guide.

Training accuracy results

Training accuracy: NVIDIA DGX A100 (8x A100 40GB)
epochs Mixed Precision Top1 TF32 Top1
90 79.95 +/- 0.09 79.97 +/- 0.08
Training accuracy: NVIDIA DGX-1 (8x V100 16GB)
epochs Mixed Precision Top1 FP32 Top1
90 80.04 +/- 0.10 79.93 +/- 0.10
250 80.96 +/- 0.04 80.97 +/- 0.09
Example plots

The following images show a 250 epochs configuration on a DGX-1V.

ValidationLoss

ValidationTop1

ValidationTop5

Training performance results

Training performance: NVIDIA DGX A100 (8x A100 40GB)
GPUs Mixed Precision TF32 Mixed Precision Speedup Mixed Precision Strong Scaling Mixed Precision Training Time (90E) TF32 Strong Scaling TF32 Training Time (90E)
1 641.57 img/s 258.75 img/s 2.48x 1.00x ~52 hours 1.00x ~129 hours
8 4758.40 img/s 2038.03 img/s 2.33x 7.42x ~7 hours 7.88x ~17 hours
Training performance: NVIDIA DGX-1 16GB (8x V100 16GB)
GPUs Mixed Precision FP32 Mixed Precision Speedup Mixed Precision Strong Scaling Mixed Precision Training Time (90E) FP32 Strong Scaling FP32 Training Time (90E)
1 383.15 img/s 130.48 img/s 2.94x 1.00x ~87 hours 1.00x ~255 hours
8 2695.10 img/s 996.04 img/s 2.71x 7.03x ~13 hours 7.63x ~34 hours
Training performance: NVIDIA DGX-1 32GB (8x V100 32GB)
GPUs Mixed Precision FP32 Mixed Precision Speedup Mixed Precision Strong Scaling Mixed Precision Training Time (90E) FP32 Strong Scaling FP32 Training Time (90E)
1 364.65 img/s 123.46 img/s 2.95x 1.00x ~92 hours 1.00x ~270 hours
8 2540.49 img/s 959.94 img/s 2.65x 6.97x ~13 hours 7.78x ~35 hours

Inference performance results

Inference performance: NVIDIA DGX-1 (1x V100 16GB)
FP32 Inference Latency
batch size Throughput Avg Latency Avg Latency 90% Latency 95% Latency 99%
1 33.58 img/s 29.72ms 30.92ms 31.77ms 34.65ms
2 66.47 img/s 29.94ms 31.30ms 32.74ms 34.79ms
4 135.31 img/s 29.36ms 29.78ms 32.61ms 33.90ms
8 261.52 img/s 30.42ms 32.73ms 33.99ms 35.61ms
16 356.05 img/s 44.61ms 44.93ms 45.17ms 46.90ms
32 391.83 img/s 80.91ms 81.28ms 81.64ms 82.69ms
64 443.91 img/s 142.70ms 142.99ms 143.46ms 145.01ms
128 N/A N/A N/A N/A N/A
Mixed Precision Inference Latency
batch size Throughput Avg Latency Avg Latency 90% Latency 95% Latency 99%
1 35.08 img/s 28.40ms 29.75ms 31.77ms 35.85ms
2 68.85 img/s 28.92ms 30.24ms 31.46ms 37.07ms
4 131.78 img/s 30.17ms 31.39ms 32.66ms 37.17ms
8 260.21 img/s 30.52ms 31.20ms 32.92ms 34.46ms
16 506.62 img/s 31.36ms 32.48ms 34.13ms 36.49ms
32 778.92 img/s 40.69ms 40.90ms 41.07ms 43.67ms
64 880.49 img/s 72.10ms 72.29ms 72.34ms 76.46ms
128 977.86 img/s 130.19ms 130.34ms 130.41ms 131.12ms
Inference performance: NVIDIA T4
FP32 Inference Latency
batch size Throughput Avg Latency Avg Latency 90% Latency 95% Latency 99%
1 40.47 img/s 24.72ms 26.94ms 29.33ms 33.03ms
2 84.16 img/s 23.66ms 24.53ms 25.96ms 29.42ms
4 165.10 img/s 24.08ms 24.59ms 25.75ms 27.57ms
8 266.04 img/s 29.90ms 30.51ms 30.84ms 33.07ms
16 325.89 img/s 48.57ms 48.91ms 49.02ms 51.01ms
32 365.99 img/s 86.94ms 87.15ms 87.41ms 90.74ms
64 410.43 img/s 155.30ms 156.07ms 156.36ms 164.74ms
128 N/A N/A N/A N/A N/A
Mixed Precision Inference Latency
batch size Throughput Avg Latency Avg Latency 90% Latency 95% Latency 99%
1 38.80 img/s 25.74ms 26.10ms 29.28ms 31.72ms
2 78.79 img/s 25.29ms 25.83ms 27.18ms 33.07ms
4 160.22 img/s 24.81ms 25.58ms 26.25ms 27.93ms
8 298.01 img/s 26.69ms 27.59ms 29.13ms 32.69ms
16 567.48 img/s 28.05ms 28.36ms 31.28ms 34.44ms
32 709.56 img/s 44.58ms 44.69ms 44.98ms 47.99ms
64 799.72 img/s 79.32ms 79.40ms 79.49ms 84.34ms
128 856.19 img/s 147.92ms 149.02ms 149.13ms 151.90ms

Release notes

Changelog

  1. October 2019
  • Initial release
  1. July 2020
  • Added A100 scripts
  • Updated README

Known issues

There are no known issues with this model.