Welcome to MMEngine’s documentation!¶

You can switch between Chinese and English documents in the lower-left corner of the layout.

Introduction¶

Coming soon. Please refer to chinese documentation.

Installation¶

Prerequisites¶

Python 3.6+
PyTorch 1.6+
CUDA 9.2+
GCC 5.4+

Prepare the Environment¶

Use conda and activate the environment:

conda create -n open-mmlab python=3.7 -y
conda activate open-mmlab

Install PyTorch

Before installing MMEngine, please make sure that PyTorch has been successfully installed in the environment. You can refer to PyTorch official installation documentation. Verify the installation with the following command:
```
python -c 'import torch;print(torch.__version__)'
```

Install MMEngine¶

Install with mim¶

mim is a package management tool for OpenMMLab projects, which can be used to install the OpenMMLab project easily.

pip install -U openmim
mim install mmengine

Install with pip¶

pip install mmengine

Use docker images¶

Build the image

docker build -t mmengine https://github.com/open-mmlab/mmengine.git#main:docker/release

More information can be referred from mmengine/docker.

Run the image

docker run --gpus all --shm-size=8g -it mmengine

Build from source¶

# if cloning speed is too slow, you can switch the source to https://gitee.com/open-mmlab/mmengine.git
git clone https://github.com/open-mmlab/mmengine.git
cd mmengine
pip install -e . -v

Verify the Installation¶

To verify if MMEngine and the necessary environment are successfully installed, we can run this command:

python -c 'import mmengine;print(mmengine.__version__)'

15 minutes to get started with MMEngine¶

In this tutorial, we’ll take training a ResNet-50 model on CIFAR-10 dataset as an example. We will build a complete and configurable pipeline for both training and validation in only 80 lines of code with MMEgnine. The whole process includes the following steps:

Build a Model
Build a Dataset and DataLoader
Build a Evaluation Metrics
Build a Runner and Run the Task

Build a Model¶

First, we need to build a model. In MMEngine, the model should inherit from BaseModel. Aside from parameters representing inputs from the dataset, its forward method needs to accept an extra argument called mode:

for training, the value of mode is “loss,” and the forward method should return a dict containing the key “loss”.
for validation, the value of mode is “predict”, and the forward method should return results containing both predictions and labels.

import torch.nn.functional as F
import torchvision
from mmengine.model import BaseModel


class MMResNet50(BaseModel):
    def __init__(self):
        super().__init__()
        self.resnet = torchvision.models.resnet50()

    def forward(self, imgs, labels, mode):
        x = self.resnet(imgs)
        if mode == 'loss':
            return {'loss': F.cross_entropy(x, labels)}
        elif mode == 'predict':
            return x, labels

Build a Dataset and DataLoader¶

Next, we need to create Dataset and DataLoader for training and validation. For basic training and validation, we can simply use built-in datasets supported in TorchVision.

import torchvision.transforms as transforms
from torch.utils.data import DataLoader

norm_cfg = dict(mean=[0.491, 0.482, 0.447], std=[0.202, 0.199, 0.201])
train_dataloader = DataLoader(batch_size=32,
                              shuffle=True,
                              dataset=torchvision.datasets.CIFAR10(
                                  'data/cifar10',
                                  train=True,
                                  download=True,
                                  transform=transforms.Compose([
                                      transforms.RandomCrop(32, padding=4),
                                      transforms.RandomHorizontalFlip(),
                                      transforms.ToTensor(),
                                      transforms.Normalize(**norm_cfg)
                                  ])))

val_dataloader = DataLoader(batch_size=32,
                            shuffle=False,
                            dataset=torchvision.datasets.CIFAR10(
                                'data/cifar10',
                                train=False,
                                download=True,
                                transform=transforms.Compose([
                                    transforms.ToTensor(),
                                    transforms.Normalize(**norm_cfg)
                                ])))

Build a Evaluation Metrics¶

To validate and test the model, we need to define a Metric called accuracy to evaluate the model. This metric needs inherit from BaseMetric and implements the process and compute_metrics methods where the process method accepts the output of the dataset and other outputs when mode="predict". The output data at this scenario is a batch of data. After processing this batch of data, we save the information to self.results property. compute_metrics accepts a results parameter. The input results of compute_metrics is all the information saved in process (In the case of a distributed environment, results are the information collected from all process in all the processes). Use these information to calculate and return a dict that holds the results of the evaluation metrics

from mmengine.evaluator import BaseMetric

class Accuracy(BaseMetric):
    def process(self, data_batch, data_samples):
        score, gt = data_samples
        # save the middle result of a batch to `self.results`
        self.results.append({
            'batch_size': len(gt),
            'correct': (score.argmax(dim=1) == gt).sum().cpu(),
        })

    def compute_metrics(self, results):
        total_correct = sum(item['correct'] for item in results)
        total_size = sum(item['batch_size'] for item in results)
        # return the dict containing the eval results
        # the key is the name of the metric name
        return dict(accuracy=100 * total_correct / total_size)

Build a Runner and Run the Task¶

Now we can build a Runner with previously defined Model, DataLoader, and Metrics, and some other configs shown as follows:

from torch.optim import SGD
from mmengine.runner import Runner

runner = Runner(
    # the model used for training and validation.
    # Needs to meet specific interface requirements
    model=MMResNet50(),
    # working directory which saves training logs and weight files
    work_dir='./work_dir',
    # train dataloader needs to meet the PyTorch data loader protocol
    train_dataloader=train_dataloader,
    # optimize wrapper for optimization with additional features like
    # AMP, gradtient accumulation, etc
    optim_wrapper=dict(optimizer=dict(type=SGD, lr=0.001, momentum=0.9)),
    # trainging coinfs for specifying training epoches, verification intervals, etc
    train_cfg=dict(by_epoch=True, max_epochs=5, val_interval=1),
    # validation dataloaer also needs to meet the PyTorch data loader protocol
    val_dataloader=val_dataloader,
    # validation configs for specifying additional parameters required for validation
    val_cfg=dict(),
    # validation evaluator. The default one is used here
    val_evaluator=dict(type=Accuracy),
)

runner.train()

Finally, let’s put all the codes above together into a complete script that uses the MMEngine executor for training and validation:

import torch.nn.functional as F
import torchvision
import torchvision.transforms as transforms
from torch.optim import SGD
from torch.utils.data import DataLoader

from mmengine.evaluator import BaseMetric
from mmengine.model import BaseModel
from mmengine.runner import Runner


class MMResNet50(BaseModel):
    def __init__(self):
        super().__init__()
        self.resnet = torchvision.models.resnet50()

    def forward(self, imgs, labels, mode):
        x = self.resnet(imgs)
        if mode == 'loss':
            return {'loss': F.cross_entropy(x, labels)}
        elif mode == 'predict':
            return x, labels


class Accuracy(BaseMetric):
    def process(self, data_batch, data_samples):
        score, gt = data_samples
        self.results.append({
            'batch_size': len(gt),
            'correct': (score.argmax(dim=1) == gt).sum().cpu(),
        })

    def compute_metrics(self, results):
        total_correct = sum(item['correct'] for item in results)
        total_size = sum(item['batch_size'] for item in results)
        return dict(accuracy=100 * total_correct / total_size)


norm_cfg = dict(mean=[0.491, 0.482, 0.447], std=[0.202, 0.199, 0.201])
train_dataloader = DataLoader(batch_size=32,
                              shuffle=True,
                              dataset=torchvision.datasets.CIFAR10(
                                  'data/cifar10',
                                  train=True,
                                  download=True,
                                  transform=transforms.Compose([
                                      transforms.RandomCrop(32, padding=4),
                                      transforms.RandomHorizontalFlip(),
                                      transforms.ToTensor(),
                                      transforms.Normalize(**norm_cfg)
                                  ])))

val_dataloader = DataLoader(batch_size=32,
                            shuffle=False,
                            dataset=torchvision.datasets.CIFAR10(
                                'data/cifar10',
                                train=False,
                                download=True,
                                transform=transforms.Compose([
                                    transforms.ToTensor(),
                                    transforms.Normalize(**norm_cfg)
                                ])))

runner = Runner(
    model=MMResNet50(),
    work_dir='./work_dir',
    train_dataloader=train_dataloader,
    optim_wrapper=dict(optimizer=dict(type=SGD, lr=0.001, momentum=0.9)),
    train_cfg=dict(by_epoch=True, max_epochs=5, val_interval=1),
    val_dataloader=val_dataloader,
    val_cfg=dict(),
    val_evaluator=dict(type=Accuracy),
)
runner.train()

Training log would be similar to this:

2022/08/22 15:51:53 - mmengine - INFO -
------------------------------------------------------------
System environment:
    sys.platform: linux
    Python: 3.8.12 (default, Oct 12 2021, 13:49:34) [GCC 7.5.0]
    CUDA available: True
    numpy_random_seed: 1513128759
    GPU 0: NVIDIA GeForce GTX 1660 SUPER
    CUDA_HOME: /usr/local/cuda
...

2022/08/22 15:51:54 - mmengine - INFO - Checkpoints will be saved to /home/mazerun/work_dir by HardDiskBackend.
2022/08/22 15:51:56 - mmengine - INFO - Epoch(train) [1][10/1563]  lr: 1.0000e-03  eta: 0:18:23  time: 0.1414  data_time: 0.0077  memory: 392  loss: 5.3465
2022/08/22 15:51:56 - mmengine - INFO - Epoch(train) [1][20/1563]  lr: 1.0000e-03  eta: 0:11:29  time: 0.0354  data_time: 0.0077  memory: 392  loss: 2.7734
2022/08/22 15:51:56 - mmengine - INFO - Epoch(train) [1][30/1563]  lr: 1.0000e-03  eta: 0:09:10  time: 0.0352  data_time: 0.0076  memory: 392  loss: 2.7789
2022/08/22 15:51:57 - mmengine - INFO - Epoch(train) [1][40/1563]  lr: 1.0000e-03  eta: 0:08:00  time: 0.0353  data_time: 0.0073  memory: 392  loss: 2.5725
2022/08/22 15:51:57 - mmengine - INFO - Epoch(train) [1][50/1563]  lr: 1.0000e-03  eta: 0:07:17  time: 0.0347  data_time: 0.0073  memory: 392  loss: 2.7382
2022/08/22 15:51:57 - mmengine - INFO - Epoch(train) [1][60/1563]  lr: 1.0000e-03  eta: 0:06:49  time: 0.0347  data_time: 0.0072  memory: 392  loss: 2.5956
2022/08/22 15:51:58 - mmengine - INFO - Epoch(train) [1][70/1563]  lr: 1.0000e-03  eta: 0:06:28  time: 0.0348  data_time: 0.0072  memory: 392  loss: 2.7351
...
2022/08/22 15:52:50 - mmengine - INFO - Saving checkpoint at 1 epochs
2022/08/22 15:52:51 - mmengine - INFO - Epoch(val) [1][10/313]    eta: 0:00:03  time: 0.0122  data_time: 0.0047  memory: 392
2022/08/22 15:52:51 - mmengine - INFO - Epoch(val) [1][20/313]    eta: 0:00:03  time: 0.0122  data_time: 0.0047  memory: 308
2022/08/22 15:52:51 - mmengine - INFO - Epoch(val) [1][30/313]    eta: 0:00:03  time: 0.0123  data_time: 0.0047  memory: 308
...
2022/08/22 15:52:54 - mmengine - INFO - Epoch(val) [1][313/313]  accuracy: 35.7000

In addition to these basic components, you can also use executor to easily combine and configure various training techniques, such as enabling mixed-precision training and gradient accumulation (see OptimWrapper), configuring the learning rate decay curve (see Metrics & Evaluator), and etc.

Registry¶

Coming soon. Please refer to chinese documentation.

Config¶

Coming soon. Please refer to chinese documentation.

Runner¶

Coming soon. Please refer to chinese documentation.

Hook¶

Coming soon. Please refer to chinese documentation.

Model¶

Coming soon. Please refer to chinese documentation.

Evaluation¶

Coming soon. Please refer to chinese documentation.

OptimWrapper¶

Coming soon. Please refer to chinese documentation.

Parameter Scheduler¶

Coming soon. Please refer to chinese documentation.

Data transform¶

Coming soon. Please refer to chinese documentation.

BaseDataset¶

Coming soon. Please refer to chinese documentation.

Abstract Data Element¶

Coming soon. Please refer to chinese documentation.

Visualization¶

Coming soon. Please refer to chinese documentation.

Initialization¶

Coming soon. Please refer to chinese documentation.

Distribution communication¶

Coming soon. Please refer to chinese documentation.

Logging¶

Coming soon. Please refer to chinese documentation.

File IO¶

Coming soon. Please refer to chinese documentation.

utils¶

Coming soon. Please refer to chinese documentation.

Resume training¶

Coming soon. Please refer to chinese documentation.

Speed up training¶

Coming soon. Please refer to chinese documentation.

Save memory on GPU¶

Coming soon. Please refer to chinese documentation.

Use modules from other libraries¶

Coming soon. Please refer to chinese documentation.

Train a GAN¶

Coming soon. Please refer to chinese documentation.

Hook¶

Coming soon. Please refer to chinese documentation.

Runner¶

Coming soon. Please refer to chinese documentation.

Evaluation¶

Coming soon. Please refer to chinese documentation.

Visualization¶

Coming soon. Please refer to chinese documentation.

Logging¶

Coming soon. Please refer to chinese documentation.

Migrate Runner from MMCV to MMEngine¶

Coming soon. Please refer to chinese documentation.

Migrate Hook from MMCV to MMEngine¶

Coming soon. Please refer to chinese documentation.

Migrate Model from MMCV to MMEngine¶

Coming soon. Please refer to chinese documentation.

Migrate Parameter Scheduler from MMCV to MMEngine¶

Coming soon. Please refer to chinese documentation.

Migrate Transform from MMCV to MMEngine¶

Coming soon. Please refer to chinese documentation.

mmengine.registry¶

`Registry`	A registry to map strings to classes or functions.
`DefaultScope`	Scope of current task used to reset the current registry, which can be accessed globally.

`build_from_cfg`	Build a module from config dict when it is a class configuration, or call a function from config dict when it is a function configuration.
`build_model_from_cfg`	Build a PyTorch model from config dict(s).
`build_runner_from_cfg`	Build a Runner object.
`build_scheduler_from_cfg`	Builds a `ParamScheduler` instance from config.
`count_registered_modules`	Scan all modules in MMEngine’s root and child registries and dump to json.
`traverse_registry_tree`	Traverse the whole registry tree from any given node, and collect information of all registered modules in this registry tree.

mmengine.config¶

`Config`	A facility for config and config files.
`ConfigDict`	A dictionary for config which has the same interface as python’s built- in dictionary and can be used as a normal dictionary.
`DictAction`	argparse action to split an argument into KEY=VALUE form on the first = and append to a dictionary.

mmengine.runner¶

mmengine.runner

Runner
Loop
Checkpoints
AMP
Miscellaneous

Runner ¶

Runner

A training helper for PyTorch.

Loop ¶

`BaseLoop`	Base loop class.
`EpochBasedTrainLoop`	Loop for epoch-based training.
`IterBasedTrainLoop`	Loop for iter-based training.
`ValLoop`	Loop for validation.
`TestLoop`	Loop for test.

Checkpoints ¶

CheckpointLoader

A general checkpoint loader to manage all schemes.

`find_latest_checkpoint`	Find the latest checkpoint from the given path.
`get_deprecated_model_names`
`get_external_models`
`get_mmcls_models`
`get_state_dict`	Returns a dictionary containing a whole state of the module.
`get_torchvision_models`
`load_checkpoint`	Load checkpoint from a file or URI.
`load_state_dict`	Load state_dict to a module.
`save_checkpoint`	Save checkpoint to file.
`weights_to_cpu`	Copy a model state_dict to cpu.

AMP ¶

autocast

A wrapper of torch.autocast and toch.cuda.amp.autocast.

Miscellaneous ¶

`LogProcessor`	A log processor used to format log information collected from `runner.message_hub.log_scalars`.
`Priority`	Hook priority levels.

get_priority

Get priority value.

mmengine.hooks¶

`Hook`	Base hook class.
`CheckpointHook`	Save checkpoints periodically.
`EMAHook`	A Hook to apply Exponential Moving Average (EMA) on the model during training.
`LoggerHook`	Collect logs from different components of `Runner` and write them to terminal, JSON file, tensorboard and wandb .etc.
`NaiveVisualizationHook`	Show or Write the predicted results during the process of testing.
`ParamSchedulerHook`	A hook to update some hyper-parameters in optimizer, e.g., learning rate and momentum.
`RuntimeInfoHook`	A hook that updates runtime information into message hub.
`DistSamplerSeedHook`	Data-loading sampler for distributed training.
`IterTimerHook`	A hook that logs the time spent during iteration.
`SyncBuffersHook`	Synchronize model buffers such as running_mean and running_var in BN at the end of each epoch.
`EmptyCacheHook`	Releases all unoccupied cached GPU memory during the process of training.

mmengine.model¶

mmengine.model

Module
Model
EMA
Model Wrapper
Weight Initialization
Utils

Module ¶

`BaseModule`	Base module for all modules in openmmlab.
`ModuleDict`	ModuleDict in openmmlab.
`ModuleList`	ModuleList in openmmlab.
`Sequential`	Sequential module in openmmlab.

Model ¶

`BaseModel`	Base class for all algorithmic models.
`BaseDataPreprocessor`	Base data pre-processor used for copying data to the target device.
`ImgDataPreprocessor`	Image pre-processor for normalization and bgr to rgb conversion.
`BaseTTAModel`	Base model for inference with test-time augmentation.

EMA ¶

`BaseAveragedModel`	A base class for averaging model weights.
`ExponentialMovingAverage`	Implements the exponential moving average (EMA) of the model.
`MomentumAnnealingEMA`	Exponential moving average (EMA) with momentum annealing strategy.
`StochasticWeightAverage`	Implements the stochastic weight averaging (SWA) of the model.

Model Wrapper ¶

`MMDistributedDataParallel`	A distributed model wrapper used for training,testing and validation in loop.
`MMSeparateDistributedDataParallel`	A DistributedDataParallel wrapper for models in MMGeneration.
`MMFullyShardedDataParallel`	A wrapper for sharding Module parameters across data parallel workers.

is_model_wrapper

Check if a module is a model wrapper.

Weight Initialization ¶

`BaseInit`
`Caffe2XavierInit`
`ConstantInit`	Initialize module parameters with constant values.
`KaimingInit`	Initialize module parameters with the values according to the method described in `Delving deep into rectifiers: Surpassing human-level performance on ImageNet classification - He, K.
`NormalInit`	Initialize module parameters with the values drawn from the normal distribution \(\mathcal{N}(\text{mean}, \text{std}^2)\).
`PretrainedInit`	Initialize module by loading a pretrained model.
`TruncNormalInit`	Initialize module parameters with the values drawn from the normal distribution \(\mathcal{N}(\text{mean}, \text{std}^2)\) with values outside \([a, b]\).
`UniformInit`	Initialize module parameters with values drawn from the uniform distribution \(\mathcal{U}(a, b)\).
`XavierInit`	Initialize module parameters with values according to the method described in `Understanding the difficulty of training deep feedforward neural networks - Glorot, X.

`bias_init_with_prob`	initialize conv/fc bias value according to a given probability value.
`caffe2_xavier_init`
`constant_init`
`initialize`	Initialize a module.
`kaiming_init`
`normal_init`
`trunc_normal_init`
`uniform_init`
`update_init_info`	Update the _params_init_info in the module if the value of parameters are changed.
`xavier_init`

Utils ¶

`detect_anomalous_params`
`merge_dict`	Merge all dictionaries into one dictionary.
`stack_batch`	Stack multiple tensors to form a batch and pad the tensor to the max shape use the right bottom padding mode in these images.
`revert_sync_batchnorm`	Helper function to convert all SyncBatchNorm (SyncBN) and mmcv.ops.sync_bn.SyncBatchNorm`(MMSyncBN) layers in the model to `BatchNormXd layers.
`convert_sync_batchnorm`	Helper function to convert all BatchNorm layers in the model to SyncBatchNorm (SyncBN) or `mmcv.ops.sync_bn.SyncBatchNorm`(MMSyncBN) layers. Adapted from <https://pytorch.org/docs/stable/generated/torch.nn.Sy ncBatchNorm.html#torch.nn.SyncBatchNorm.convert_sync_batchnorm>_.

mmengine.optim¶

mmengine.optim

Optimizer
Scheduler

Optimizer ¶

`AmpOptimWrapper`	A subclass of `OptimWrapper` that supports automatic mixed precision training based on torch.cuda.amp.
`OptimWrapper`	Optimizer wrapper provides a common interface for updating parameters.
`OptimWrapperDict`	A dictionary container of `OptimWrapper`.
`DefaultOptimWrapperConstructor`	Default constructor for optimizers.

build_optim_wrapper

Build function of OptimWrapper.

Scheduler ¶

`_ParamScheduler`	Base class for parameter schedulers.
`ConstantLR`	Decays the learning rate value of each parameter group by a small constant factor until the number of epoch reaches a pre-defined milestone: `end`.
`ConstantMomentum`	Decays the momentum value of each parameter group by a small constant factor until the number of epoch reaches a pre-defined milestone: `end`.
`ConstantParamScheduler`	Decays the parameter value of each parameter group by a small constant factor until the number of epoch reaches a pre-defined milestone: `end`.
`CosineAnnealingLR`	Set the learning rate of each parameter group using a cosine annealing schedule, where \(\eta_{max}\) is set to the initial value and \(T_{cur}\) is the number of epochs since the last restart in SGDR:
`CosineAnnealingMomentum`	Set the momentum of each parameter group using a cosine annealing schedule, where \(\eta_{max}\) is set to the initial value and \(T_{cur}\) is the number of epochs since the last restart in SGDR:
`CosineAnnealingParamScheduler`	Set the parameter value of each parameter group using a cosine annealing schedule, where \(\eta_{max}\) is set to the initial value and \(T_{cur}\) is the number of epochs since the last restart in SGDR:
`ExponentialLR`	Decays the learning rate of each parameter group by gamma every epoch.
`ExponentialMomentum`	Decays the momentum of each parameter group by gamma every epoch.
`ExponentialParamScheduler`	Decays the parameter value of each parameter group by gamma every epoch.
`LinearLR`	Decays the learning rate of each parameter group by linearly changing small multiplicative factor until the number of epoch reaches a pre-defined milestone: `end`.
`LinearMomentum`	Decays the momentum of each parameter group by linearly changing small multiplicative factor until the number of epoch reaches a pre-defined milestone: `end`.
`LinearParamScheduler`	Decays the parameter value of each parameter group by linearly changing small multiplicative factor until the number of epoch reaches a pre-defined milestone: `end`.
`MultiStepLR`	Decays the specified learning rate in each parameter group by gamma once the number of epoch reaches one of the milestones.
`MultiStepMomentum`	Decays the specified momentum in each parameter group by gamma once the number of epoch reaches one of the milestones.
`MultiStepParamScheduler`	Decays the specified parameter in each parameter group by gamma once the number of epoch reaches one of the milestones.
`OneCycleLR`	Sets the learning rate of each parameter group according to the 1cycle learning rate policy.
`OneCycleParamScheduler`	Sets the parameters of each parameter group according to the 1cycle learning rate policy.
`PolyLR`	Decays the learning rate of each parameter group in a polynomial decay scheme.
`PolyMomentum`	Decays the momentum of each parameter group in a polynomial decay scheme.
`PolyParamScheduler`	Decays the parameter value of each parameter group in a polynomial decay scheme.
`StepLR`	Decays the learning rate of each parameter group by gamma every step_size epochs.
`StepMomentum`	Decays the momentum of each parameter group by gamma every step_size epochs.
`StepParamScheduler`	Decays the parameter value of each parameter group by gamma every step_size epochs.

mmengine.evaluator¶

mmengine.evaluator

Evaluator
Metric
Utils

Evaluator ¶

Evaluator

Wrapper class to compose multiple BaseMetric instances.

Metric ¶

`BaseMetric`	Base class for a metric.
`DumpResults`	Dump model predictions to a pickle file for offline evaluation.

Utils ¶

get_metric_value

Get the metric value specified by an indicator, which can be either a metric name or a full name with evaluator prefix.

mmengine.structures¶

`BaseDataElement`	A base data interface that supports Tensor-like and dict-like operations.
`InstanceData`	Data structure for instance-level annotations or predictions.
`LabelData`	Data structure for label-level annotations or predictions.
`PixelData`	Data structure for pixel-level annotations or predictions.

mmengine.dataset¶

mmengine.dataset

Dataset
Dataset Wrapper
Sampler
Utils

Dataset ¶

`BaseDataset`	BaseDataset for open source projects in OpenMMLab.
`Compose`	Compose multiple transforms sequentially.

Dataset Wrapper ¶

`ClassBalancedDataset`	A wrapper of class balanced dataset.
`ConcatDataset`	A wrapper of concatenated dataset.
`RepeatDataset`	A wrapper of repeated dataset.

Sampler ¶

`DefaultSampler`	The default data sampler for both distributed and non-distributed environment.
`InfiniteSampler`	It’s designed for iteration-based runner and yields a mini-batch indices each time.

Utils ¶

`default_collate`	Convert list of data sampled from dataset into a batch of data, of which type consistent with the type of each data_itement in `data_batch`.
`pseudo_collate`	Convert list of data sampled from dataset into a batch of data, of which type consistent with the type of each data_itement in `data_batch`.
`worker_init_fn`	This function will be called on each worker subprocess after seeding and before data loading.

mmengine.device¶

`get_device`	Returns the currently existing device type.
`get_max_cuda_memory`	Returns the maximum GPU memory occupied by tensors in megabytes (MB) for a given device.
`is_cuda_available`	Returns True if cuda devices exist.
`is_npu_available`	Returns True if Ascend PyTorch and npu devices exist.
`is_mlu_available`	Returns True if Cambricon PyTorch and mlu devices exist.
`is_mps_available`	Return True if mps devices exist.

mmengine.hub¶

`get_config`	Get config from external package.
`get_model`	Get built model from external package.

mmengine.logging¶

`MMLogger`	Formatted logger used to record messages.
`MessageHub`	Message hub for component interaction.
`HistoryBuffer`	Unified storage format for different log types.

print_log

Print a log message.

mmengine.visualization¶

mmengine.visualization

Visualizer
visualization Backend

Visualizer ¶

Visualizer

MMEngine provides a Visualizer class that uses the Matplotlib library as the backend.

visualization Backend ¶

`BaseVisBackend`	Base class for visualization backend.
`LocalVisBackend`	Local visualization backend class.
`TensorboardVisBackend`	Tensorboard visualization backend class.
`WandbVisBackend`	Wandb visualization backend class.

mmengine.fileio¶

mmengine.fileio

File Backend
File Handler
File IO
Parse File

File Backend ¶

`BaseStorageBackend`	Abstract class of storage backends.
`FileClient`	A general file client to access files in different backends.
`HardDiskBackend`	Raw hard disks storage backend.
`LocalBackend`	Raw local storage backend.
`HTTPBackend`	HTTP and HTTPS storage bachend.
`LmdbBackend`	Lmdb storage backend.
`MemcachedBackend`	Memcached storage backend.
`PetrelBackend`	Petrel storage backend (for internal usage).

register_backend

Register a backend.

File Handler ¶

`BaseFileHandler`
`JsonHandler`
`PickleHandler`
`YamlHandler`

register_handler

File IO ¶

`dump`	Dump data to json/yaml/pickle strings or files.
`load`	Load data from json/yaml/pickle files.
`copy_if_symlink_fails`	Create a symbolic link pointing to src named dst.
`copyfile`	Copy a file src to dst and return the destination file.
`copyfile_from_local`	Copy a local file src to dst and return the destination file.
`copyfile_to_local`	Copy the file src to local dst and return the destination file.
`copytree`	Recursively copy an entire directory tree rooted at src to a directory named dst and return the destination directory.
`copytree_from_local`	Recursively copy an entire directory tree rooted at src to a directory named dst and return the destination directory.
`copytree_to_local`	Recursively copy an entire directory tree rooted at src to a local directory named dst and return the destination directory.
`exists`	Check whether a file path exists.
`generate_presigned_url`	Generate the presigned url of video stream which can be passed to mmcv.VideoReader.
`get`	Read bytes from a given `filepath` with ‘rb’ mode.
`get_file_backend`	Return a file backend based on the prefix of uri or backend_args.
`get_local_path`	Download data from `filepath` and write the data to local path.
`get_text`	Read text from a given `filepath` with ‘r’ mode.
`isdir`	Check whether a file path is a directory.
`isfile`	Check whether a file path is a file.
`join_path`	Concatenate all file paths.
`list_dir_or_file`	Scan a directory to find the interested directories or files in arbitrary order.
`put`	Write bytes to a given `filepath` with ‘wb’ mode.
`put_text`	Write text to a given `filepath` with ‘w’ mode.
`remove`	Remove a file.
`rmtree`	Recursively delete a directory tree.

Parse File ¶

`dict_from_file`	Load a text file and parse the content as a dict.
`list_from_file`	Load a text file and parse the content as a list of strings.

mmengine.dist¶

mmengine.dist

dist
utils

dist ¶

`gather`	Gather data from the whole group to `dst` process.
`gather_object`	Gathers picklable objects from the whole group in a single process.
`all_gather`	Gather data from the whole group in a list.
`all_gather_object`	Gather picklable objects from the whole group into a list.
`all_reduce`	Reduces the tensor data across all machines in such a way that all get the final result.
`all_reduce_dict`	Reduces the dict across all machines in such a way that all get the final result.
`all_reduce_params`	All-reduce parameters.
`broadcast`	Broadcast the data from `src` process to the whole group.
`sync_random_seed`	Synchronize a random seed to all processes.
`broadcast_object_list`	Broadcasts picklable objects in `object_list` to the whole group.
`collect_results`	Collected results in distributed environments.
`collect_results_cpu`	Collect results under cpu mode.
`collect_results_gpu`	Collect results under gpu mode.

utils ¶

`get_dist_info`	Get distributed information of the given process group.
`init_dist`	Initialize distributed environment.
`init_local_group`	Setup the local process group.
`get_backend`	Return the backend of the given process group.
`get_world_size`	Return the number of the given process group.
`get_rank`	Return the rank of the given process group.
`get_local_size`	Return the number of the current node.
`get_local_rank`	Return the rank of current process in the current node.
`is_main_process`	Whether the current rank of the given process group is equal to 0.
`master_only`	Decorate those methods which should be executed in master process.
`barrier`	Synchronize all processes from the given process group.
`is_distributed`	Return True if distributed environment has been initialized.
`get_local_group`	Return local process group.
`get_default_group`	Return default process group.
`get_data_device`	Return the device of `data`.
`get_comm_device`	Return the device for communication among groups.
`cast_data_device`	Recursively convert Tensor in `data` to `device`.

mmengine.utils¶

mmengine.utils

Manager
Path
Package
Version
Progress Bar
Miscellaneous

Manager ¶

`ManagerMeta`	The metaclass for global accessible class.
`ManagerMixin`	`ManagerMixin` is the base class for classes that have global access requirements.

Path ¶

`check_file_exist`
`fopen`
`is_abs`	Check if path is an absolute path in different backends.
`is_filepath`
`mkdir_or_exist`
`scandir`	Scan a directory to find the interested files.
`symlink`

Package ¶

`call_command`
`install_package`
`get_installed_path`	Get installed path of package.
`is_installed`	Check package whether installed.

Version ¶

`digit_version`	Convert a version string into a tuple of integers.
`get_git_hash`	Get the git hash of the current repo.

Progress Bar ¶

ProgressBar

A progress bar which can print the progress.

`track_iter_progress`	Track the progress of tasks iteration or enumeration with a progress bar.
`track_parallel_progress`	Track the progress of parallel task execution with a progress bar.
`track_progress`	Track the progress of tasks execution with a progress bar.

Miscellaneous ¶

`Timer`	A flexible Timer class.
`TimerError`

`is_list_of`	Check whether it is a list of some type.
`is_tuple_of`	Check whether it is a tuple of some type.
`is_seq_of`	Check whether it is a sequence of some type.
`is_str`	Whether the input is an string instance.
`iter_cast`	Cast elements of an iterable object into some type.
`list_cast`	Cast elements of an iterable object into a list of some type.
`tuple_cast`	Cast elements of an iterable object into a tuple of some type.
`concat_list`	Concatenate a list of list into a single list.
`slice_list`	Slice a list into several sub lists by a list of given length.
`to_1tuple`
`to_2tuple`
`to_3tuple`
`to_4tuple`
`to_ntuple`
`check_prerequisites`	A decorator factory to check if prerequisites are satisfied.
`deprecated_api_warning`	A decorator to check if some arguments are deprecate and try to replace deprecate src_arg_name to dst_arg_name.
`deprecated_function`	Marks functions as deprecated.
`has_method`	Check whether the object has a method.
`is_method_overridden`	Check if a method of base class is overridden in derived class.
`import_modules_from_strings`	Import modules from the given list of strings.
`requires_executable`	A decorator to check if some executable files are installed.
`requires_package`	A decorator to check if some python packages are installed.
`check_time`	Add check points in a single line.

mmengine.utils.dl_utils¶

TimeCounter

A tool that counts the average running time of a function or a method.

`collect_env`	Collect the information of the running environments.
`load_url`	Loads the Torch serialized object at the given URL.
`has_batch_norm`	Detect whether model has a BatchNormalization layer.
`is_norm`	Check if a layer is a normalization layer.
`mmcv_full_available`	Check whether mmcv-full is installed.
`tensor2imgs`	Convert tensor to 3-channel images or 1-channel gray images.
`TORCH_VERSION`	A string with magic powers to compare to both Version and iterables! Prior to 1.10.0 torch.__version__ was stored as a str and so many did comparisons against torch.__version__ as if it were a str.
`set_multi_processing`	Set multi-processing related environment.
`torch_meshgrid`	A wrapper of torch.meshgrid to compat different PyTorch versions.
`is_jit_tracing`

Changelog of v0.x¶

v0.3.0 (11/02/2022)¶

New Features & Enhancements¶

Support running on Ascend chip by @wangjiangben-hw in https://github.com/open-mmlab/mmengine/pull/572
Support torch ZeroRedundancyOptimizer by @nijkah in https://github.com/open-mmlab/mmengine/pull/551
Add non-blocking feature to BaseDataPreprocessor by @shenmishajing in https://github.com/open-mmlab/mmengine/pull/618
Add documents for clip_grad, and support clip grad by value. by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/513
Add ROCm info when collecting env by @zhouzaida in https://github.com/open-mmlab/mmengine/pull/633
Add a function to mark the deprecated function. by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/609
Call register_all_modules in Registry.get() by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/541
Deprecate _save_to_state_dict implemented in mmengine by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/610
Add ignore_keys in ConcatDataset by @BIGWangYuDong in https://github.com/open-mmlab/mmengine/pull/556

Docs¶

Fix cannot show changelog.md in chinese documents. by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/606
Fix Chinese docs whitespaces by @C1rN09 in https://github.com/open-mmlab/mmengine/pull/521
Translate installation and 15_min by @xin-li-67 in https://github.com/open-mmlab/mmengine/pull/629
Refine chinese doc by @Tau-J in https://github.com/open-mmlab/mmengine/pull/516
Add MMYOLO link in README by @Xiangxu-0103 in https://github.com/open-mmlab/mmengine/pull/634
Add MMEngine logo in docs by @zhouzaida in https://github.com/open-mmlab/mmengine/pull/641
Fix docstring of BaseDataset by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/656
Fix docstring and documentation used for hub.get_model by @zengyh1900 in https://github.com/open-mmlab/mmengine/pull/659
Fix typo in docs/zh_cn/advanced_tutorials/visualization.md by @MambaWong in https://github.com/open-mmlab/mmengine/pull/616
Fix typo docstring of DefaultOptimWrapperConstructor by @triple-Mu in https://github.com/open-mmlab/mmengine/pull/644
Fix typo in advanced tutorial by @cxiang26 in https://github.com/open-mmlab/mmengine/pull/650
Fix typo in Config docstring by @sanbuphy in https://github.com/open-mmlab/mmengine/pull/654
Fix typo in docs/zh_cn/tutorials/config.md by @Xiangxu-0103 in https://github.com/open-mmlab/mmengine/pull/596
Fix typo in docs/zh_cn/tutorials/model.md by @C1rN09 in https://github.com/open-mmlab/mmengine/pull/598

Bug Fixes¶

Fix error calculation of eta_min in CosineRestartParamScheduler by @Z-Fran in https://github.com/open-mmlab/mmengine/pull/639
Fix BaseDataPreprocessor.cast_data could not handle string data by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/602
Make autocast compatible with mps by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/587
Fix error format of log message by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/508
Fix error implementation of is_model_wrapper by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/640
Fix VisBackend.add_config is not called by @shenmishajing in https://github.com/open-mmlab/mmengine/pull/613
Change strict_load of EMAHook to False by default by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/642
Fix open encoding problem of Config in Windows by @sanbuphy in https://github.com/open-mmlab/mmengine/pull/648
Fix the total number of iterations in log is a float number. by @jbwang1997 in https://github.com/open-mmlab/mmengine/pull/604
Fix pip upgrade CI by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/622

New Contributors¶

@shenmishajing made their first contribution in https://github.com/open-mmlab/mmengine/pull/618
@Xiangxu-0103 made their first contribution in https://github.com/open-mmlab/mmengine/pull/596
@Tau-J made their first contribution in https://github.com/open-mmlab/mmengine/pull/516
@wangjiangben-hw made their first contribution in https://github.com/open-mmlab/mmengine/pull/572
@triple-Mu made their first contribution in https://github.com/open-mmlab/mmengine/pull/644
@sanbuphy made their first contribution in https://github.com/open-mmlab/mmengine/pull/648
@Z-Fran made their first contribution in https://github.com/open-mmlab/mmengine/pull/639
@BIGWangYuDong made their first contribution in https://github.com/open-mmlab/mmengine/pull/556
@zengyh1900 made their first contribution in https://github.com/open-mmlab/mmengine/pull/659

v0.2.0 (11/10/2022)¶

New Features & Enhancements¶

Add SMDDP backend and support running on AWS by @austinmw in https://github.com/open-mmlab/mmengine/pull/579
Refactor FileIO but without breaking bc by @zhouzaida in https://github.com/open-mmlab/mmengine/pull/533
Add test time augmentation base model by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/538
Use torch.lerp\_() to speed up EMA by @RangiLyu in https://github.com/open-mmlab/mmengine/pull/519
Support converting BN to SyncBN by config by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/506
Support defining metric name in wandb backend by @okotaku in https://github.com/open-mmlab/mmengine/pull/509
Add dockerfile by @zhouzaida in https://github.com/open-mmlab/mmengine/pull/347

Docs¶

Fix API files of English documentation by @zhouzaida in https://github.com/open-mmlab/mmengine/pull/525
Fix typo in instance_data.py by @Dai-Wenxun in https://github.com/open-mmlab/mmengine/pull/530
Fix the docstring of the model sub-package by @zhouzaida in https://github.com/open-mmlab/mmengine/pull/573
Fix a spelling error in docs/zh_cn by @cxiang26 in https://github.com/open-mmlab/mmengine/pull/548
Fix typo in docstring by @MengzhangLI in https://github.com/open-mmlab/mmengine/pull/527
Update config.md by @Zhengfei-0311 in https://github.com/open-mmlab/mmengine/pull/562

Bug Fixes¶

Fix LogProcessor does not smooth loss if the name of loss doesn’t start with loss by @liuyanyi in https://github.com/open-mmlab/mmengine/pull/539
Fix failed to enable detect_anomalous_params in MMSeparateDistributedDataParallel by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/588
Fix CheckpointHook behavior unexpected if given filename_tmpl argument by @C1rN09 in https://github.com/open-mmlab/mmengine/pull/518
Fix error argument sequence in FSDP by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/520
Fix uploading image in wandb backend @okotaku in https://github.com/open-mmlab/mmengine/pull/510
Fix loading state dictionary in EMAHook by @okotaku in https://github.com/open-mmlab/mmengine/pull/507
Fix circle import in EMAHook by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/523
Fix unit test could fail caused by MultiProcessTestCase by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/535
Remove unnecessary “if statement” in Registry by @MambaWong in https://github.com/open-mmlab/mmengine/pull/536
Fix _save_to_state_dict by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/542
Support comparing NumPy array dataset meta in Runner.resume by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/511
Use get instead of pop to dump runner_type in build_runner_from_cfg by @nijkah in https://github.com/open-mmlab/mmengine/pull/549
Upgrade pre-commit hooks by @zhouzaida in https://github.com/open-mmlab/mmengine/pull/576
Delete the error comment in registry.md by @vansin in https://github.com/open-mmlab/mmengine/pull/514
Fix Some out-of-date unit tests by @C1rN09 in https://github.com/open-mmlab/mmengine/pull/586
Fix typo in MMFullyShardedDataParallel by @yhna940 in https://github.com/open-mmlab/mmengine/pull/569
Update Github Action CI and CircleCI by @zhouzaida in https://github.com/open-mmlab/mmengine/pull/512
Fix unit test in windows by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/515
Fix merge ci & multiprocessing unit test by @HAOCHENYE in https://github.com/open-mmlab/mmengine/pull/529

New Contributors¶

@okotaku made their first contribution in https://github.com/open-mmlab/mmengine/pull/510
@MengzhangLI made their first contribution in https://github.com/open-mmlab/mmengine/pull/527
@MambaWong made their first contribution in https://github.com/open-mmlab/mmengine/pull/536
@cxiang26 made their first contribution in https://github.com/open-mmlab/mmengine/pull/548
@nijkah made their first contribution in https://github.com/open-mmlab/mmengine/pull/549
@Zhengfei-0311 made their first contribution in https://github.com/open-mmlab/mmengine/pull/562
@austinmw made their first contribution in https://github.com/open-mmlab/mmengine/pull/579
@yhna940 made their first contribution in https://github.com/open-mmlab/mmengine/pull/569
@liuyanyi made their first contribution in https://github.com/open-mmlab/mmengine/pull/539

Welcome to MMEngine’s documentation!¶

Introduction¶

Installation¶

Prerequisites¶

Prepare the Environment¶

Install MMEngine¶

Install with mim¶

Install with pip¶

Use docker images¶

Build from source¶

Verify the Installation¶

15 minutes to get started with MMEngine¶

Build a Model¶

Build a Dataset and DataLoader¶

Build a Evaluation Metrics¶

Build a Runner and Run the Task¶

Registry¶

Config¶

Runner¶

Hook¶

Model¶

Evaluation¶

OptimWrapper¶

Parameter Scheduler¶

Data transform¶

BaseDataset¶

Abstract Data Element¶

Visualization¶

Initialization¶

Distribution communication¶

Logging¶

File IO¶

utils¶

Resume training¶

Speed up training¶

Save memory on GPU¶

Use modules from other libraries¶

Train a GAN¶

Hook¶

Runner¶

Evaluation¶

Visualization¶

Logging¶

Migrate Runner from MMCV to MMEngine¶

Migrate Hook from MMCV to MMEngine¶

Migrate Model from MMCV to MMEngine¶

Migrate Parameter Scheduler from MMCV to MMEngine¶

Migrate Transform from MMCV to MMEngine¶

mmengine.registry¶

mmengine.config¶

mmengine.runner¶

mmengine.hooks¶

mmengine.model¶

mmengine.optim¶

mmengine.evaluator¶

mmengine.structures¶

mmengine.dataset¶

mmengine.device¶

mmengine.hub¶

mmengine.logging¶

mmengine.visualization¶

mmengine.fileio¶

mmengine.dist¶

mmengine.utils¶

mmengine.utils.dl_utils¶

Changelog of v0.x¶

v0.3.0 (11/02/2022)¶

New Features & Enhancements¶

Docs¶

Bug Fixes¶

New Contributors¶

v0.2.0 (11/10/2022)¶

New Features & Enhancements¶

Docs¶

Bug Fixes¶

New Contributors¶

Indices and tables¶