ResNet

The ResNet model is based on the "Deep Residual Learning for Image Recognition" paper.

Architecture overview

This paper introduces a few tricks to maximize the depth of convolutional architectures that can be trained.

The key takeaways from the paper are the following:

• add a shortcut connection in bottleneck blocks to ease the gradient flow
• extensive use of batch normalization layers

Model builders

The following model builders can be used to instantiate a ResNeXt model, with or without pre-trained weights. All the model builders internally rely on the ResNet base class.

ResNet

ResNet(block: type[BasicBlock | Bottleneck], num_blocks: list[int], planes: list[int], num_classes: int = 10, in_channels: int = 3, zero_init_residual: bool = False, width_per_group: int = 64, conv_layer: Callable[..., Module] | None = None, act_layer: Module | None = None, norm_layer: Callable[[int], Module] | None = None, drop_layer: Callable[..., Module] | None = None, deep_stem: bool = False, stem_pool: bool = True, avg_downsample: bool = False, num_repeats: int = 1, block_args: dict[str, Any] | list[dict[str, Any]] | None = None)

Bases: Sequential

Source code in holocron/models/classification/resnet.py

def __init__(  # noqa: PLR0912
    self,
    block: type[BasicBlock | Bottleneck],
    num_blocks: list[int],
    planes: list[int],
    num_classes: int = 10,
    in_channels: int = 3,
    zero_init_residual: bool = False,
    width_per_group: int = 64,
    conv_layer: Callable[..., nn.Module] | None = None,
    act_layer: nn.Module | None = None,
    norm_layer: Callable[[int], nn.Module] | None = None,
    drop_layer: Callable[..., nn.Module] | None = None,
    deep_stem: bool = False,
    stem_pool: bool = True,
    avg_downsample: bool = False,
    num_repeats: int = 1,
    block_args: dict[str, Any] | list[dict[str, Any]] | None = None,
) -> None:
    if conv_layer is None:
        conv_layer = nn.Conv2d
    if norm_layer is None:
        norm_layer = nn.BatchNorm2d
    if act_layer is None:
        act_layer = nn.ReLU(inplace=True)
    self.dilation: int = 1

    in_planes = 64
    # Deep stem from ResNet-C
    if deep_stem:
        layers = [
            *conv_sequence(
                in_channels,
                in_planes // 2,
                act_layer,
                norm_layer,
                drop_layer,
                conv_layer,
                kernel_size=3,
                stride=2,
                padding=1,
                bias=(norm_layer is None),
            ),
            *conv_sequence(
                in_planes // 2,
                in_planes // 2,
                act_layer,
                norm_layer,
                drop_layer,
                conv_layer,
                kernel_size=3,
                stride=1,
                padding=1,
                bias=(norm_layer is None),
            ),
            *conv_sequence(
                in_planes // 2,
                in_planes,
                act_layer,
                norm_layer,
                drop_layer,
                conv_layer,
                kernel_size=3,
                stride=1,
                padding=1,
                bias=(norm_layer is None),
            ),
        ]
    else:
        layers = conv_sequence(
            in_channels,
            in_planes,
            act_layer,
            norm_layer,
            drop_layer,
            conv_layer,
            kernel_size=7,
            stride=2,
            padding=3,
            bias=(norm_layer is None),
        )
    if stem_pool:
        layers.append(nn.MaxPool2d(kernel_size=3, stride=2, padding=1))

    # Optional tensor repetitions along channel axis (mainly for TridentNet)
    if num_repeats > 1:
        layers.append(ChannelRepeat(num_repeats))

    # Consecutive convolutional blocks
    stride = 1
    # Block args
    if block_args is None:
        block_args = {"groups": 1}
    if not isinstance(block_args, list):
        block_args = [block_args] * len(num_blocks)
    for _num_blocks, _planes, _block_args in zip(num_blocks, planes, block_args, strict=True):
        layers.append(
            self._make_layer(
                block,
                _num_blocks,
                in_planes,
                _planes,
                stride,
                width_per_group,
                act_layer=act_layer,
                norm_layer=norm_layer,
                drop_layer=drop_layer,
                avg_downsample=avg_downsample,
                num_repeats=num_repeats,
                block_args=_block_args,
            )
        )
        in_planes = block.expansion * _planes
        stride = 2

    super().__init__(
        OrderedDict([
            ("features", nn.Sequential(*layers)),
            ("pool", GlobalAvgPool2d(flatten=True)),
            ("head", nn.Linear(num_repeats * in_planes, num_classes)),
        ])
    )

    # Init all layers
    init.init_module(self, nonlinearity="relu")

    # Init shortcut
    if zero_init_residual:
        for m in self.modules():
            if isinstance(m, Bottleneck):
                m.convs[2][1].weight.data.zero_()  # ty: ignore[non-subscriptable,possibly-missing-attribute]
            elif isinstance(m, BasicBlock):
                m.convs[1][1].weight.data.zero_()  # ty: ignore[non-subscriptable,possibly-missing-attribute]

resnet18

resnet18(pretrained: bool = False, checkpoint: Checkpoint | None = None, progress: bool = True, **kwargs: Any) -> ResNet

ResNet-18 from "Deep Residual Learning for Image Recognition"

PARAMETER	DESCRIPTION
pretrained	If True, returns a model pre-trained on ImageNet TYPE: bool DEFAULT: False
checkpoint	If specified, loads that checkpoint TYPE: Checkpoint | None DEFAULT: None
progress	If True, displays a progress bar of the download to stderr TYPE: bool DEFAULT: True
kwargs	keyword args of ResNet TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
ResNet	classification model

ResNet18_Checkpoint

Bases: Enum

IMAGENETTE class-attribute instance-attribute

IMAGENETTE = _checkpoint(arch='resnet18', url='https://github.com/frgfm/Holocron/releases/download/v0.2.1/resnet18_224-fc07006c.pth', acc1=0.9361, acc5=0.9946, sha256='fc07006c894cac8cf380fed699bc5a68463698753c954632f52bb8595040f781', size=44787043, num_params=11181642, commit='6e32c5b578711a2ef3731a8f8c61760ed9f03e58', train_args='./imagenette2-320/ --arch resnet18 --batch-size 64 --mixup-alpha 0.2 --amp --device 0 --epochs 100 --lr 1e-3 --label-smoothing 0.1 --random-erase 0.1 --train-crop-size 176 --val-resize-size 232 --opt adamw --weight-decay 5e-2')

DEFAULT class-attribute instance-attribute

DEFAULT = IMAGENETTE

Source code in holocron/models/classification/resnet.py

def resnet18(
    pretrained: bool = False,
    checkpoint: Checkpoint | None = None,
    progress: bool = True,
    **kwargs: Any,
) -> ResNet:
    """ResNet-18 from
    ["Deep Residual Learning for Image Recognition"](https://arxiv.org/pdf/1512.03385.pdf)

    Args:
        pretrained: If True, returns a model pre-trained on ImageNet
        checkpoint: If specified, loads that checkpoint
        progress: If True, displays a progress bar of the download to stderr
        kwargs: keyword args of [`ResNet`][holocron.models.ResNet]

    Returns:
        classification model

    ::: holocron.models.ResNet18_Checkpoint
        options:
            heading_level: 4
            show_if_no_docstring: true
    """
    checkpoint = _handle_legacy_pretrained(
        pretrained,
        checkpoint,
        ResNet18_Checkpoint.DEFAULT.value,
    )
    return _resnet(checkpoint, progress, BasicBlock, [2, 2, 2, 2], [64, 128, 256, 512], **kwargs)

resnet34

resnet34(pretrained: bool = False, checkpoint: Checkpoint | None = None, progress: bool = True, **kwargs: Any) -> ResNet

ResNet-34 from "Deep Residual Learning for Image Recognition"

PARAMETER	DESCRIPTION
pretrained	If True, returns a model pre-trained on ImageNet TYPE: bool DEFAULT: False
checkpoint	If specified, load that checkpoint on the model TYPE: Checkpoint | None DEFAULT: None
progress	If True, displays a progress bar of the download to stderr TYPE: bool DEFAULT: True
kwargs	keyword args of ResNet TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
ResNet	classification model

ResNet34_Checkpoint

Bases: Enum

IMAGENETTE class-attribute instance-attribute

IMAGENETTE = _checkpoint(arch='resnet34', url='https://github.com/frgfm/Holocron/releases/download/v0.2.1/resnet34_224-412b0792.pth', acc1=0.9381, acc5=0.9949, sha256='412b07927cc1938ee3add8d0f6bb18b42786646182f674d75f1433d086914485', size=85267035, num_params=21289802, commit='6e32c5b578711a2ef3731a8f8c61760ed9f03e58', train_args='./imagenette2-320/ --arch resnet34 --batch-size 64 --mixup-alpha 0.2 --amp --device 0 --epochs 100 --lr 1e-3 --label-smoothing 0.1 --random-erase 0.1 --train-crop-size 176 --val-resize-size 232 --opt adamw --weight-decay 5e-2')

DEFAULT class-attribute instance-attribute

DEFAULT = IMAGENETTE

Source code in holocron/models/classification/resnet.py

def resnet34(
    pretrained: bool = False,
    checkpoint: Checkpoint | None = None,
    progress: bool = True,
    **kwargs: Any,
) -> ResNet:
    """ResNet-34 from
    ["Deep Residual Learning for Image Recognition"](https://arxiv.org/pdf/1512.03385.pdf)

    Args:
        pretrained: If True, returns a model pre-trained on ImageNet
        checkpoint: If specified, load that checkpoint on the model
        progress: If True, displays a progress bar of the download to stderr
        kwargs: keyword args of [`ResNet`][holocron.models.ResNet]

    Returns:
        classification model

    ::: holocron.models.ResNet34_Checkpoint
        options:
            heading_level: 4
            show_if_no_docstring: true
    """
    return _resnet(checkpoint, progress, BasicBlock, [3, 4, 6, 3], [64, 128, 256, 512], **kwargs)

resnet50

resnet50(pretrained: bool = False, checkpoint: Checkpoint | None = None, progress: bool = True, **kwargs: Any) -> ResNet

ResNet-50 from "Deep Residual Learning for Image Recognition"

PARAMETER	DESCRIPTION
pretrained	If True, returns a model pre-trained on ImageNet TYPE: bool DEFAULT: False
checkpoint	If specified, load that checkpoint on the model TYPE: Checkpoint | None DEFAULT: None
progress	If True, displays a progress bar of the download to stderr TYPE: bool DEFAULT: True
kwargs	keyword args of ResNet TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
ResNet	classification model

ResNet50_Checkpoint

Bases: Enum

IMAGENETTE class-attribute instance-attribute

IMAGENETTE = _checkpoint(arch='resnet50', url='https://github.com/frgfm/Holocron/releases/download/v0.2.1/resnet50_224-5b913f0b.pth', acc1=0.9378, acc5=0.9954, sha256='5b913f0b8148b483ba15541ab600cf354ca42b326e4896c4c3dbc51eb1e80e70', size=94384682, num_params=23528522, commit='6e32c5b578711a2ef3731a8f8c61760ed9f03e58', train_args='./imagenette2-320/ --arch resnet50 --batch-size 64 --mixup-alpha 0.2 --amp --device 0 --epochs 100 --lr 1e-3 --label-smoothing 0.1 --random-erase 0.1 --train-crop-size 176 --val-resize-size 232 --opt adamw --weight-decay 5e-2')

DEFAULT class-attribute instance-attribute

DEFAULT = IMAGENETTE

Source code in holocron/models/classification/resnet.py

def resnet50(
    pretrained: bool = False,
    checkpoint: Checkpoint | None = None,
    progress: bool = True,
    **kwargs: Any,
) -> ResNet:
    """ResNet-50 from
    ["Deep Residual Learning for Image Recognition"](https://arxiv.org/pdf/1512.03385.pdf)

    Args:
        pretrained: If True, returns a model pre-trained on ImageNet
        checkpoint: If specified, load that checkpoint on the model
        progress: If True, displays a progress bar of the download to stderr
        kwargs: keyword args of [`ResNet`][holocron.models.ResNet]

    Returns:
        classification model

    ::: holocron.models.ResNet50_Checkpoint
        options:
            heading_level: 4
            show_if_no_docstring: true
    """
    checkpoint = _handle_legacy_pretrained(
        pretrained,
        checkpoint,
        ResNet50_Checkpoint.DEFAULT.value,
    )
    return _resnet(checkpoint, progress, Bottleneck, [3, 4, 6, 3], [64, 128, 256, 512], **kwargs)

resnet50d

resnet50d(pretrained: bool = False, checkpoint: Checkpoint | None = None, progress: bool = True, **kwargs: Any) -> ResNet

ResNet-50-D from "Bag of Tricks for Image Classification with Convolutional Neural Networks" https://arxiv.org/pdf/1812.01187.pdf`_

PARAMETER	DESCRIPTION
pretrained	If True, returns a model pre-trained on ImageNet TYPE: bool DEFAULT: False
checkpoint	If specified, load that checkpoint on the model TYPE: Checkpoint | None DEFAULT: None
progress	If True, displays a progress bar of the download to stderr TYPE: bool DEFAULT: True
kwargs	keyword args of ResNet TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
ResNet	classification model

ResNet50D_Checkpoint

Bases: Enum

IMAGENETTE class-attribute instance-attribute

IMAGENETTE = _checkpoint(arch='resnet50d', url='https://github.com/frgfm/Holocron/releases/download/v0.2.1/resnet50d_224-6218d936.pth', acc1=0.9465, acc5=0.9952, sha256='6218d936fa67c0047f1ec65564213db538aa826d84f2df1d4fa3224531376e6c', size=94464810, num_params=23547754, commit='6e32c5b578711a2ef3731a8f8c61760ed9f03e58', train_args='./imagenette2-320/ --arch resnet50d --batch-size 64 --mixup-alpha 0.2 --amp --device 0 --epochs 100 --lr 1e-3 --label-smoothing 0.1 --random-erase 0.1 --train-crop-size 176 --val-resize-size 232 --opt adamw --weight-decay 5e-2')

DEFAULT class-attribute instance-attribute

DEFAULT = IMAGENETTE

Source code in holocron/models/classification/resnet.py

def resnet50d(
    pretrained: bool = False,
    checkpoint: Checkpoint | None = None,
    progress: bool = True,
    **kwargs: Any,
) -> ResNet:
    """ResNet-50-D from
    ["Bag of Tricks for Image Classification with Convolutional Neural Networks"](https://arxiv.org/pdf/1812.01187.pdf)
    <https://arxiv.org/pdf/1812.01187.pdf>`_

    Args:
        pretrained: If True, returns a model pre-trained on ImageNet
        checkpoint: If specified, load that checkpoint on the model
        progress: If True, displays a progress bar of the download to stderr
        kwargs: keyword args of [`ResNet`][holocron.models.classification.resnet.ResNet]

    Returns:
        classification model

    ::: holocron.models.ResNet50D_Checkpoint
        options:
            heading_level: 4
            show_if_no_docstring: true
    """
    return _resnet(
        checkpoint,
        progress,
        Bottleneck,
        [3, 4, 6, 3],
        [64, 128, 256, 512],
        deep_stem=True,
        avg_downsample=True,
        **kwargs,
    )

resnet101

resnet101(pretrained: bool = False, checkpoint: Checkpoint | None = None, progress: bool = True, **kwargs: Any) -> ResNet

ResNet-101 from "Deep Residual Learning for Image Recognition"

PARAMETER	DESCRIPTION
pretrained	If True, returns a model pre-trained on ImageNet TYPE: bool DEFAULT: False
checkpoint	If specified, load that checkpoint on the model TYPE: Checkpoint | None DEFAULT: None
progress	If True, displays a progress bar of the download to stderr TYPE: bool DEFAULT: True
kwargs	keyword args of _resnet TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
ResNet	torch.nn.Module: classification model

Source code in holocron/models/classification/resnet.py

def resnet101(
    pretrained: bool = False,
    checkpoint: Checkpoint | None = None,
    progress: bool = True,
    **kwargs: Any,
) -> ResNet:
    """ResNet-101 from
    ["Deep Residual Learning for Image Recognition"](https://arxiv.org/pdf/1512.03385.pdf)

    Args:
        pretrained: If True, returns a model pre-trained on ImageNet
        checkpoint: If specified, load that checkpoint on the model
        progress: If True, displays a progress bar of the download to stderr
        kwargs: keyword args of _resnet

    Returns:
        torch.nn.Module: classification model
    """
    return _resnet(checkpoint, progress, Bottleneck, [3, 4, 23, 3], [64, 128, 256, 512], **kwargs)

resnet152

resnet152(pretrained: bool = False, checkpoint: Checkpoint | None = None, progress: bool = True, **kwargs: Any) -> ResNet

ResNet-152 from "Deep Residual Learning for Image Recognition"

PARAMETER	DESCRIPTION
pretrained	If True, returns a model pre-trained on ImageNet TYPE: bool DEFAULT: False
checkpoint	If specified, load that checkpoint on the model TYPE: Checkpoint | None DEFAULT: None
progress	If True, displays a progress bar of the download to stderr TYPE: bool DEFAULT: True
kwargs	keyword args of ResNet TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
ResNet	classification model

Source code in holocron/models/classification/resnet.py

def resnet152(
    pretrained: bool = False,
    checkpoint: Checkpoint | None = None,
    progress: bool = True,
    **kwargs: Any,
) -> ResNet:
    """ResNet-152 from
    ["Deep Residual Learning for Image Recognition"](https://arxiv.org/pdf/1512.03385.pdf)

    Args:
        pretrained: If True, returns a model pre-trained on ImageNet
        checkpoint: If specified, load that checkpoint on the model
        progress: If True, displays a progress bar of the download to stderr
        kwargs: keyword args of [`ResNet`][holocron.models.classification.resnet.ResNet]

    Returns:
        classification model
    """
    return _resnet(checkpoint, progress, Bottleneck, [3, 8, 86, 3], [64, 128, 256, 512], **kwargs)