# Source code for fvcore.nn.precise_bn

```
# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
# pyre-ignore-all-errors[2,6,16]
import itertools
import logging
from typing import Any, Dict, Iterable, List, Optional, Tuple, Type
import torch
import tqdm
from torch import nn
BN_MODULE_TYPES: Tuple[Type[nn.Module]] = (
torch.nn.BatchNorm1d,
torch.nn.BatchNorm2d,
torch.nn.BatchNorm3d,
torch.nn.SyncBatchNorm,
)
logger: logging.Logger = logging.getLogger(__name__)
class _MeanOfBatchVarianceEstimator:
"""
Note that PyTorch's running_var means "running average of
bessel-corrected batch variance". (PyTorch's BN normalizes by biased
variance, but updates EMA by unbiased (bessel-corrected) variance).
So we estimate population variance by "simple average of bessel-corrected
batch variance". This is the same as in the BatchNorm paper, Sec 3.1.
This estimator converges to population variance as long as batch size
is not too small, and total #samples for PreciseBN is large enough.
Its convergence is affected by small batch size.
In this implementation, we also don't distinguish differences in batch size.
We assume every batch contributes equally to the population statistics.
"""
def __init__(self, mean_buffer: torch.Tensor, var_buffer: torch.Tensor) -> None:
self.pop_mean: torch.Tensor = torch.zeros_like(mean_buffer)
self.pop_var: torch.Tensor = torch.zeros_like(var_buffer)
self.ind = 0
def update(
self, batch_mean: torch.Tensor, batch_var: torch.Tensor, batch_size: int
) -> None:
self.ind += 1
self.pop_mean += (batch_mean - self.pop_mean) / self.ind
self.pop_var += (batch_var - self.pop_var) / self.ind
class _PopulationVarianceEstimator:
"""
Alternatively, one can estimate population variance by the sample variance
of all batches combined. This needs to use the batch size of each batch
in this function to undo the bessel-correction.
This produces better estimation when each batch is small.
See Appendix of the paper "Rethinking Batch in BatchNorm" for details.
In this implementation, we also take into account varying batch sizes.
A batch of N1 samples with a mean of M1 and a batch of N2 samples with a
mean of M2 will produce a population mean of (N1M1+N2M2)/(N1+N2) instead
of (M1+M2)/2.
"""
def __init__(self, mean_buffer: torch.Tensor, var_buffer: torch.Tensor) -> None:
self.pop_mean: torch.Tensor = torch.zeros_like(mean_buffer)
self.pop_square_mean: torch.Tensor = torch.zeros_like(var_buffer)
self.tot = 0
def update(
self, batch_mean: torch.Tensor, batch_var: torch.Tensor, batch_size: int
) -> None:
self.tot += batch_size
batch_square_mean = batch_mean.square() + batch_var * (
(batch_size - 1) / batch_size
)
self.pop_mean += (batch_mean - self.pop_mean) * (batch_size / self.tot)
self.pop_square_mean += (batch_square_mean - self.pop_square_mean) * (
batch_size / self.tot
)
@property
def pop_var(self) -> torch.Tensor:
return self.pop_square_mean - self.pop_mean.square()
[docs]@torch.no_grad()
def update_bn_stats(
model: nn.Module,
data_loader: Iterable[Any],
num_iters: int = 200,
progress: Optional[str] = None,
) -> None:
"""
Recompute and update the batch norm stats to make them more precise. During
training both BN stats and the weight are changing after every iteration, so
the running average can not precisely reflect the actual stats of the
current model.
In this function, the BN stats are recomputed with fixed weights, to make
the running average more precise. Specifically, it computes the true average
of per-batch mean/variance instead of the running average.
See Sec. 3 of the paper "Rethinking Batch in BatchNorm" for details.
Args:
model (nn.Module): the model whose bn stats will be recomputed.
Note that:
1. This function will not alter the training mode of the given model.
Users are responsible for setting the layers that needs
precise-BN to training mode, prior to calling this function.
2. Be careful if your models contain other stateful layers in
addition to BN, i.e. layers whose state can change in forward
iterations. This function will alter their state. If you wish
them unchanged, you need to either pass in a submodule without
those layers, or backup the states.
data_loader (iterator): an iterator. Produce data as inputs to the model.
num_iters (int): number of iterations to compute the stats.
progress: None or "tqdm". If set, use tqdm to report the progress.
"""
bn_layers = get_bn_modules(model)
if len(bn_layers) == 0:
return
logger.info(f"Computing precise BN statistics for {len(bn_layers)} BN layers ...")
# In order to make the running stats only reflect the current batch, the
# momentum is disabled.
# bn.running_mean = (1 - momentum) * bn.running_mean + momentum * batch_mean
# Setting the momentum to 1.0 to compute the stats without momentum.
momentum_actual = [bn.momentum for bn in bn_layers]
for bn in bn_layers:
bn.momentum = 1.0
batch_size_per_bn_layer: Dict[nn.Module, int] = {}
def get_bn_batch_size_hook(
module: nn.Module, input: Tuple[torch.Tensor]
) -> Tuple[torch.Tensor]:
assert (
module not in batch_size_per_bn_layer
), "Some BN layers are reused. This is not supported and probably not desired."
x = input[0]
assert isinstance(
x, torch.Tensor
), f"BN layer should take tensor as input. Got {input}"
# consider spatial dimensions as batch as well
batch_size = x.numel() // x.shape[1]
batch_size_per_bn_layer[module] = batch_size
return (x,)
hooks_to_remove = [
# pyre-ignore
bn.register_forward_pre_hook(get_bn_batch_size_hook)
for bn in bn_layers
]
estimators = [
_PopulationVarianceEstimator(bn.running_mean, bn.running_var)
for bn in bn_layers
]
ind = -1
for inputs in tqdm.tqdm(
itertools.islice(data_loader, num_iters),
total=num_iters,
disable=progress != "tqdm",
):
ind += 1
batch_size_per_bn_layer.clear()
model(inputs)
for i, bn in enumerate(bn_layers):
# Accumulates the bn stats.
batch_size = batch_size_per_bn_layer.get(bn, None)
if batch_size is None:
continue # the layer was unused in this forward
estimators[i].update(bn.running_mean, bn.running_var, batch_size)
assert ind == num_iters - 1, (
"update_bn_stats is meant to run for {} iterations, "
"but the dataloader stops at {} iterations.".format(num_iters, ind)
)
for i, bn in enumerate(bn_layers):
# Sets the precise bn stats.
bn.running_mean = estimators[i].pop_mean
bn.running_var = estimators[i].pop_var
bn.momentum = momentum_actual[i]
for hook in hooks_to_remove:
hook.remove()
[docs]def get_bn_modules(model: nn.Module) -> List[nn.Module]:
"""
Find all BatchNorm (BN) modules that are in training mode. See
fvcore.precise_bn.BN_MODULE_TYPES for a list of all modules that are
included in this search.
Args:
model (nn.Module): a model possibly containing BN modules.
Returns:
list[nn.Module]: all BN modules in the model.
"""
# Finds all the bn layers.
bn_layers = [
m for m in model.modules() if m.training and isinstance(m, BN_MODULE_TYPES)
]
return bn_layers
```