<div align="center">
<img src="https://user-images.githubusercontent.com/58739961/187154444-fce76639-ac8d-429b-9354-c6fac64b7ef8.jpg" width="600"/>
<div> </div>
<div align="center">
<b><font size="5">OpenMMLab website</font></b>
<sup>
<a href="https://openmmlab.com">
<i><font size="4">HOT</font></i>
</a>
</sup>
<b><font size="5">OpenMMLab platform</font></b>
<sup>
<a href="https://platform.openmmlab.com">
<i><font size="4">TRY IT OUT</font></i>
</a>
</sup>
</div>
<div> </div>
[](https://pypi.org/project/mmengine/)
[](https://pypi.org/project/mmengine)
[](https://github.com/open-mmlab/mmengine/blob/main/LICENSE)
[](https://github.com/open-mmlab/mmengine/issues)
[](https://github.com/open-mmlab/mmengine/issues)
[📘Documentation](https://mmengine.readthedocs.io/en/latest/) |
[🛠️Installation](https://mmengine.readthedocs.io/en/latest/get_started/installation.html) |
[🤔Reporting Issues](https://github.com/open-mmlab/mmengine/issues/new/choose)
</div>
<div align="center">
English | [简体中文](README_zh-CN.md)
</div>
<div align="center">
<a href="https://openmmlab.medium.com/" style="text-decoration:none;">
<img src="https://user-images.githubusercontent.com/25839884/219255827-67c1a27f-f8c5-46a9-811d-5e57448c61d1.png" width="3%" alt="" /></a>
<img src="https://user-images.githubusercontent.com/25839884/218346358-56cc8e2f-a2b8-487f-9088-32480cceabcf.png" width="3%" alt="" />
<a href="https://discord.com/channels/1037617289144569886/1073056342287323168" style="text-decoration:none;">
<img src="https://user-images.githubusercontent.com/25839884/218347213-c080267f-cbb6-443e-8532-8e1ed9a58ea9.png" width="3%" alt="" /></a>
<img src="https://user-images.githubusercontent.com/25839884/218346358-56cc8e2f-a2b8-487f-9088-32480cceabcf.png" width="3%" alt="" />
<a href="https://twitter.com/OpenMMLab" style="text-decoration:none;">
<img src="https://user-images.githubusercontent.com/25839884/218346637-d30c8a0f-3eba-4699-8131-512fb06d46db.png" width="3%" alt="" /></a>
<img src="https://user-images.githubusercontent.com/25839884/218346358-56cc8e2f-a2b8-487f-9088-32480cceabcf.png" width="3%" alt="" />
<a href="https://www.youtube.com/openmmlab" style="text-decoration:none;">
<img src="https://user-images.githubusercontent.com/25839884/218346691-ceb2116a-465a-40af-8424-9f30d2348ca9.png" width="3%" alt="" /></a>
<img src="https://user-images.githubusercontent.com/25839884/218346358-56cc8e2f-a2b8-487f-9088-32480cceabcf.png" width="3%" alt="" />
<a href="https://space.bilibili.com/1293512903" style="text-decoration:none;">
<img src="https://user-images.githubusercontent.com/25839884/219026751-d7d14cce-a7c9-4e82-9942-8375fca65b99.png" width="3%" alt="" /></a>
<img src="https://user-images.githubusercontent.com/25839884/218346358-56cc8e2f-a2b8-487f-9088-32480cceabcf.png" width="3%" alt="" />
<a href="https://www.zhihu.com/people/openmmlab" style="text-decoration:none;">
<img src="https://user-images.githubusercontent.com/25839884/219026120-ba71e48b-6e94-4bd4-b4e9-b7d175b5e362.png" width="3%" alt="" /></a>
</div>
## What's New
v0.10.1 was released on 2023-11-22.
Highlights:
- Support installing mmengine-lite with no dependency on opencv. Refer to the [Installation](https://mmengine.readthedocs.io/en/latest/get_started/installation.html#install-mmengine) for more details.
- Support training with [ColossalAI](https://colossalai.org/). Refer to the [Training Large Models](https://mmengine.readthedocs.io/en/latest/common_usage/large_model_training.html#colossalai) for more detailed usages.
- Support gradient checkpointing. Refer to the [Save Memory on GPU](https://mmengine.readthedocs.io/en/latest/common_usage/save_gpu_memory.html#gradient-checkpointing) for more details.
- Supports multiple visualization backends, including `NeptuneVisBackend`, `DVCLiveVisBackend` and `AimVisBackend`. Refer to [Visualization Backends](https://mmengine.readthedocs.io/en/latest/common_usage/visualize_training_log.html) for more details.
Read [Changelog](./docs/en/notes/changelog.md#v0101-22112023) for more details.
## Table of Contents
- [Introduction](#introduction)
- [Installation](#installation)
- [Get Started](#get-started)
- [Learn More](#learn-more)
- [Contributing](#contributing)
- [Citation](#citation)
- [License](#license)
- [Ecosystem](#ecosystem)
- [Projects in OpenMMLab](#projects-in-openmmlab)
## Introduction
MMEngine is a foundational library for training deep learning models based on PyTorch. It provides a solid engineering foundation and frees developers from writing redundant codes on workflows. It serves as the training engine of all OpenMMLab codebases, which support hundreds of algorithms in various research areas. Moreover, MMEngine is also generic to be applied to non-OpenMMLab projects.
Major features:
1. **A universal and powerful runner**:
- Supports training different tasks with a small amount of code, e.g., ImageNet can be trained with only 80 lines of code (400 lines of the original PyTorch example).
- Easily compatible with models from popular algorithm libraries such as TIMM, TorchVision, and Detectron2.
2. **Open architecture with unified interfaces**:
- Handles different algorithm tasks with unified APIs, e.g., implement a method and apply it to all compatible models.
- Provides a unified abstraction for upper-level algorithm libraries, which supports various back-end devices such as Nvidia CUDA, Mac MPS, AMD, MLU, and more for model training.
3. **Customizable training process**:
- Defines the training process just like playing with Legos.
- Provides rich components and strategies.
- Complete controls on the training process with different levels of APIs.
## Installation
Before installing MMEngine, please ensure that PyTorch has been successfully installed following the [official guide](https://pytorch.org/get-started/locally/).
Install MMEngine
```bash
pip install -U openmim
mim install mmengine
```
Verify the installation
```bash
python -c 'from mmengine.utils.dl_utils import collect_env;print(collect_env())'
```
## Get Started
Taking the training of a ResNet-50 model on the CIFAR-10 dataset as an example, we will use MMEngine to build a complete, configurable training and validation process in less than 80 lines of code.
<details>
<summary>Build Models</summary>
First, we need to define a **model** which 1) inherits from `BaseModel` and 2) accepts an additional argument `mode` in the `forward` method, in addition to those arguments related to the dataset.
- During training, the value of `mode` is "loss", and the `forward` method should return a `dict` containing the key "loss".
- During validation, the value of `mode` is "predict", and the forward method should return results containing both predictions and labels.
```python
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
```
</details>
<details>
<summary>Build Datasets</summary>
Next, we need to create **Dataset**s and **DataLoader**s for training and validation.
In this case, we simply use built-in datasets supported in TorchVision.
```python
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)
])))
```
</details>
<details>
<summary>Build Metrics</summary>
To validate and test the model, we need to define a **Metric** called accuracy to evaluate the model. This metric needs to inherit from `BaseMetric` and implements the `process` and `compute_metrics` methods.
```python
from mmengine.evaluator import BaseMetric
class Accuracy(BaseMetric):
def process(self, data_batch, data_samples):
score, gt = data_samples
# Save the results 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)
# Returns a dictionary with the results of the evaluated metrics,
# where the key is the name of the metric
return dict(accuracy=100 * total_correct / total_size)
```
</details>
<details>
<summary>Build a Runner</summary>
Finally, we can construct a **Runner** with previously defined `Model`, `DataLoader`, and `Metrics`, with some other configs, as shown below.
```python
from torch.optim import SGD
from mmengine.runner import Runner
runner = Runner(
model=MMResNet50(),
work_dir='./work_dir',
train_dataloader=train_dataloader,
# a wrapper to execute back propagation and gradient update, etc.
optim_wrapper=dict(optimizer=dict(type=SGD, lr=0.001, momentum=0.9)),
# set some training configs like epochs
train_cfg=dict(by_epoch=True, max_epochs=5, val_interval=1),
val_dataloader=val_dataloader,
val_cfg=dict(),
val_evaluator=dict(type=Accuracy),
)
```
</details>
<details>
<summary>Launch Training</summary>
```python
runner.train()
```
</details>
## Learn More
<details>
<summary>Tutorials</summary>
- [Runner](https://mmengine.readthedocs.io/en/latest/tutorials/runner.html)
- [Dataset and DataLoader](https://mmengine.readthedocs.io/en/latest/tutorials/dataset.html)
- [Model](https://mmengine.readthedocs.io/en/latest/tutorials/model.html)
- [Evaluation](https://mmengine.readthedocs.io/en/latest/tutorials/evaluation.html)
- [OptimWrapper](https://mmengine.readthedocs.io/en/latest/tutorials/optim_wrapper.html)
- [Parameter Scheduler](https://mmengine.readthedocs.io/en/latest/tutorials/param_scheduler.html)
- [Hook](https://mmengine.readthedocs.io/en/latest/tutorials/hook.html)
</details>
<details>
<summary>Advanced tutorials</summary>
- [Registry](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/registry.html)
- [Config](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/config.html)
- [BaseDataset](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/basedataset.html)
- [Data Transform](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/data_transform.html)
- [Weight Initialization](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/initialize.html)
- [Visualization](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/visualization.html)
- [Abstract Data Element](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/data_element.html)
- [Distribution Communication](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/distributed.html)
- [Logging](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/logging.html)
- [File IO](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/fileio.html)
- [Global manager (ManagerMixin)](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/manager_mixin.html)
- [Use modules from other libraries](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/cross_library.html)
- [Test Time Agumentation](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/test_time_augmentation.html)
</details>
<details>
<summary>Examples</summary>
- [Train a GAN](https://mmengine.readthedocs.io/en/latest/examples/train_a_gan.html)
</details>
<details>
<summary>Common Usage</summary>
- [Resume Training](https://mmengine.readthedocs.io/en/latest/common_usage/resume_training.html)
- [Speed up Training](https://mmengine.readthedocs.io/en/latest/common_usage/speed_up_training.html)
- [Save Memory on GPU](https://mmengine.readthedocs.io/en/latest/common_usage/save_gpu_memory.html)
</details>
<details>
<summary>Design</summary>
- [Hook](https://mmengine.readthedocs.io/en/latest/design/hook.html)
- [Runner](https://mmengine.readthedocs.io/en/latest/design/runner.html)
- [Evaluation](https://mmengine.readthedocs.io/en/latest/design/evaluation.html)
- [Visualization](https://mmengine.readthedocs.io/en/latest/design/visualization.html)
- [Logging](https://mmengine.readthedocs.io/en/latest/design/logging.html)
- [Infer](https://mmengine.readthedocs.io/en/latest/design/infer.html)
</details>
<details>
<summary>Migration guide</summary>
- [Migrate Runner from MMCV to MMEngine](https://mmengine.readthedocs.io/en/latest/migration/runner.html)
- [Migrate Hook from MMCV to MMEngine](https://mmengine.readthedocs.io/en/latest/migration/hook.html)
- [Migrate Model from MMCV to MMEngine](https://mmengine.readthedocs.io/en/latest/migration/model.html)
- [Migrate Parameter Scheduler from MMCV to MMEngine](https://mmengine.readthedocs.io/en/latest/migration/param_scheduler.html)
- [Migrate Data Transform to OpenMMLab 2.0](https://mmengine.readthedocs.io/en/latest/migration/transform.html)
</details>
## Contributing
We appreciate all contributions to improve MMEngine. Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for the contributing guideline.
## Citation
If you find this project useful in your research, please consider cite:
```
@article{mmengine2022,
title = {{MMEngine}: OpenMMLab Foundational Library for Training Deep Learning Models},
author = {MMEngine Contributors},
howpublished = {\url{https://github.com/open-mmlab/mmengine}},
year={2022}
}
```
## License
This project is released under the [Apache 2.0 license](LICENSE).
## Ecosystem
- [APES: Attention-based Point Cloud Edge Sampling](https://github.com/JunweiZheng93/APES)
- [DiffEngine: diffusers training toolbox with mmengine](https://github.com/okotaku/diffengine)
## Projects in OpenMMLab
- [MIM](https://github.com/open-mmlab/mim): MIM installs OpenMMLab packages.
- [MMCV](https://github.com/open-mmlab/mmcv): OpenMMLab foundational library for computer vision.
- [MMEval](https://github.com/open-mmlab/mmeval): A unified evaluation library for multiple machine learning libraries.
- [MMPreTrain](https://github.com/open-mmlab/mmpretrain): OpenMMLab pre-training toolbox and benchmark.
- [MMagic](https://github.com/open-mmlab/mmagic): Open**MM**Lab **A**dvanced, **G**enerative and **I**ntelligent **C**reation toolbox.
- [MMDetection](https://github.com/open-mmlab/mmdetection): OpenMMLab detection toolbox and benchmark.
- [MMYOLO](https://github.com/open-mmlab/mmyolo): OpenMMLab YOLO series toolbox and benchmark.
- [MMDetection3D](https://github.com/open-mmlab/mmdetection3d): OpenMMLab's next-generation platform for general 3D object detection.
- [MMRotate](https://github.com/open-mmlab/mmrotate): OpenMMLab rotated object detection toolbox and benchmark.
- [MMTracking](https://github.com/open-mmlab/mmtracking): OpenMMLab video perception toolbox and benchmark.
- [MMPose](https://github.com/open-mmlab/mmpose): OpenMMLab pose estimation toolbox and benchmark.
- [MMSegmentation](https://github.com/open-mmlab/mmsegmentation): OpenMMLab semantic segmentation toolbox and benchmark.
- [MMOCR](https://github.com/open-mmlab/mmocr): OpenMMLab text detection, recognition, and understanding toolbox.
- [MMHuman3D](https://github.com/open-mmlab/mmhuman3d): OpenMMLab 3D human parametric model toolbox and benchmark.
- [MMSelfSup](https://github.com/open-mmlab/mmselfsup): OpenMMLab self-supervised learning toolbox and benchmark.
- [MMFewShot](https://github.com/open-mmlab/mmfewshot): OpenMMLab fewshot learning toolbox and benchmark.
- [MMAction2](https://github.com/open-mmlab/mmaction2): OpenMMLab's next-generation action understanding toolbox and benchmark.
- [MMFlow](https://github.com/open-mmlab/mmflow): OpenMMLab optical flow toolbox and benchmark.
- [MMDeploy](https://github.com/open-mmlab/mmdeploy): OpenMMLab model deployment framework.
- [MMRazor](https://github.com/open-mmlab/mmrazor): OpenMMLab model compression toolbox and benchmark.
- [Playground](https://github.com/open-mmlab/playground): A central hub for gathering and showcasing amazing projects built upon OpenMMLab.
Raw data
{
"_id": null,
"home_page": "https://github.com/open-mmlab/mmengine",
"name": "mmengine",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "MMEngine Authors",
"author_email": "openmmlab@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/54/81/328b9a35c6f8bfc9abcca0ca38ea224a6ab90e8245d41ff26510a37e5474/mmengine-0.10.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://user-images.githubusercontent.com/58739961/187154444-fce76639-ac8d-429b-9354-c6fac64b7ef8.jpg\" width=\"600\"/>\n <div> </div>\n <div align=\"center\">\n <b><font size=\"5\">OpenMMLab website</font></b>\n <sup>\n <a href=\"https://openmmlab.com\">\n <i><font size=\"4\">HOT</font></i>\n </a>\n </sup>\n \n <b><font size=\"5\">OpenMMLab platform</font></b>\n <sup>\n <a href=\"https://platform.openmmlab.com\">\n <i><font size=\"4\">TRY IT OUT</font></i>\n </a>\n </sup>\n </div>\n <div> </div>\n\n[](https://pypi.org/project/mmengine/)\n[](https://pypi.org/project/mmengine)\n[](https://github.com/open-mmlab/mmengine/blob/main/LICENSE)\n[](https://github.com/open-mmlab/mmengine/issues)\n[](https://github.com/open-mmlab/mmengine/issues)\n\n[\ud83d\udcd8Documentation](https://mmengine.readthedocs.io/en/latest/) |\n[\ud83d\udee0\ufe0fInstallation](https://mmengine.readthedocs.io/en/latest/get_started/installation.html) |\n[\ud83e\udd14Reporting Issues](https://github.com/open-mmlab/mmengine/issues/new/choose)\n\n</div>\n\n<div align=\"center\">\n\nEnglish | [\u7b80\u4f53\u4e2d\u6587](README_zh-CN.md)\n\n</div>\n\n<div align=\"center\">\n <a href=\"https://openmmlab.medium.com/\" style=\"text-decoration:none;\">\n <img src=\"https://user-images.githubusercontent.com/25839884/219255827-67c1a27f-f8c5-46a9-811d-5e57448c61d1.png\" width=\"3%\" alt=\"\" /></a>\n <img src=\"https://user-images.githubusercontent.com/25839884/218346358-56cc8e2f-a2b8-487f-9088-32480cceabcf.png\" width=\"3%\" alt=\"\" />\n <a href=\"https://discord.com/channels/1037617289144569886/1073056342287323168\" style=\"text-decoration:none;\">\n <img src=\"https://user-images.githubusercontent.com/25839884/218347213-c080267f-cbb6-443e-8532-8e1ed9a58ea9.png\" width=\"3%\" alt=\"\" /></a>\n <img src=\"https://user-images.githubusercontent.com/25839884/218346358-56cc8e2f-a2b8-487f-9088-32480cceabcf.png\" width=\"3%\" alt=\"\" />\n <a href=\"https://twitter.com/OpenMMLab\" style=\"text-decoration:none;\">\n <img src=\"https://user-images.githubusercontent.com/25839884/218346637-d30c8a0f-3eba-4699-8131-512fb06d46db.png\" width=\"3%\" alt=\"\" /></a>\n <img src=\"https://user-images.githubusercontent.com/25839884/218346358-56cc8e2f-a2b8-487f-9088-32480cceabcf.png\" width=\"3%\" alt=\"\" />\n <a href=\"https://www.youtube.com/openmmlab\" style=\"text-decoration:none;\">\n <img src=\"https://user-images.githubusercontent.com/25839884/218346691-ceb2116a-465a-40af-8424-9f30d2348ca9.png\" width=\"3%\" alt=\"\" /></a>\n <img src=\"https://user-images.githubusercontent.com/25839884/218346358-56cc8e2f-a2b8-487f-9088-32480cceabcf.png\" width=\"3%\" alt=\"\" />\n <a href=\"https://space.bilibili.com/1293512903\" style=\"text-decoration:none;\">\n <img src=\"https://user-images.githubusercontent.com/25839884/219026751-d7d14cce-a7c9-4e82-9942-8375fca65b99.png\" width=\"3%\" alt=\"\" /></a>\n <img src=\"https://user-images.githubusercontent.com/25839884/218346358-56cc8e2f-a2b8-487f-9088-32480cceabcf.png\" width=\"3%\" alt=\"\" />\n <a href=\"https://www.zhihu.com/people/openmmlab\" style=\"text-decoration:none;\">\n <img src=\"https://user-images.githubusercontent.com/25839884/219026120-ba71e48b-6e94-4bd4-b4e9-b7d175b5e362.png\" width=\"3%\" alt=\"\" /></a>\n</div>\n\n## What's New\n\nv0.10.1 was released on 2023-11-22.\n\nHighlights:\n\n- Support installing mmengine-lite with no dependency on opencv. Refer to the [Installation](https://mmengine.readthedocs.io/en/latest/get_started/installation.html#install-mmengine) for more details.\n\n- Support training with [ColossalAI](https://colossalai.org/). Refer to the [Training Large Models](https://mmengine.readthedocs.io/en/latest/common_usage/large_model_training.html#colossalai) for more detailed usages.\n\n- Support gradient checkpointing. Refer to the [Save Memory on GPU](https://mmengine.readthedocs.io/en/latest/common_usage/save_gpu_memory.html#gradient-checkpointing) for more details.\n\n- Supports multiple visualization backends, including `NeptuneVisBackend`, `DVCLiveVisBackend` and `AimVisBackend`. Refer to [Visualization Backends](https://mmengine.readthedocs.io/en/latest/common_usage/visualize_training_log.html) for more details.\n\nRead [Changelog](./docs/en/notes/changelog.md#v0101-22112023) for more details.\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Get Started](#get-started)\n- [Learn More](#learn-more)\n- [Contributing](#contributing)\n- [Citation](#citation)\n- [License](#license)\n- [Ecosystem](#ecosystem)\n- [Projects in OpenMMLab](#projects-in-openmmlab)\n\n## Introduction\n\nMMEngine is a foundational library for training deep learning models based on PyTorch. It provides a solid engineering foundation and frees developers from writing redundant codes on workflows. It serves as the training engine of all OpenMMLab codebases, which support hundreds of algorithms in various research areas. Moreover, MMEngine is also generic to be applied to non-OpenMMLab projects.\n\nMajor features:\n\n1. **A universal and powerful runner**:\n\n - Supports training different tasks with a small amount of code, e.g., ImageNet can be trained with only 80 lines of code (400 lines of the original PyTorch example).\n - Easily compatible with models from popular algorithm libraries such as TIMM, TorchVision, and Detectron2.\n\n2. **Open architecture with unified interfaces**:\n\n - Handles different algorithm tasks with unified APIs, e.g., implement a method and apply it to all compatible models.\n - Provides a unified abstraction for upper-level algorithm libraries, which supports various back-end devices such as Nvidia CUDA, Mac MPS, AMD, MLU, and more for model training.\n\n3. **Customizable training process**:\n\n - Defines the training process just like playing with Legos.\n - Provides rich components and strategies.\n - Complete controls on the training process with different levels of APIs.\n\n\n\n## Installation\n\nBefore installing MMEngine, please ensure that PyTorch has been successfully installed following the [official guide](https://pytorch.org/get-started/locally/).\n\nInstall MMEngine\n\n```bash\npip install -U openmim\nmim install mmengine\n```\n\nVerify the installation\n\n```bash\npython -c 'from mmengine.utils.dl_utils import collect_env;print(collect_env())'\n```\n\n## Get Started\n\nTaking the training of a ResNet-50 model on the CIFAR-10 dataset as an example, we will use MMEngine to build a complete, configurable training and validation process in less than 80 lines of code.\n\n<details>\n<summary>Build Models</summary>\n\nFirst, we need to define a **model** which 1) inherits from `BaseModel` and 2) accepts an additional argument `mode` in the `forward` method, in addition to those arguments related to the dataset.\n\n- During training, the value of `mode` is \"loss\", and the `forward` method should return a `dict` containing the key \"loss\".\n- During validation, the value of `mode` is \"predict\", and the forward method should return results containing both predictions and labels.\n\n```python\nimport torch.nn.functional as F\nimport torchvision\nfrom mmengine.model import BaseModel\n\nclass MMResNet50(BaseModel):\n def __init__(self):\n super().__init__()\n self.resnet = torchvision.models.resnet50()\n\n def forward(self, imgs, labels, mode):\n x = self.resnet(imgs)\n if mode == 'loss':\n return {'loss': F.cross_entropy(x, labels)}\n elif mode == 'predict':\n return x, labels\n```\n\n</details>\n\n<details>\n<summary>Build Datasets</summary>\n\nNext, we need to create **Dataset**s and **DataLoader**s for training and validation.\nIn this case, we simply use built-in datasets supported in TorchVision.\n\n```python\nimport torchvision.transforms as transforms\nfrom torch.utils.data import DataLoader\n\nnorm_cfg = dict(mean=[0.491, 0.482, 0.447], std=[0.202, 0.199, 0.201])\ntrain_dataloader = DataLoader(batch_size=32,\n shuffle=True,\n dataset=torchvision.datasets.CIFAR10(\n 'data/cifar10',\n train=True,\n download=True,\n transform=transforms.Compose([\n transforms.RandomCrop(32, padding=4),\n transforms.RandomHorizontalFlip(),\n transforms.ToTensor(),\n transforms.Normalize(**norm_cfg)\n ])))\nval_dataloader = DataLoader(batch_size=32,\n shuffle=False,\n dataset=torchvision.datasets.CIFAR10(\n 'data/cifar10',\n train=False,\n download=True,\n transform=transforms.Compose([\n transforms.ToTensor(),\n transforms.Normalize(**norm_cfg)\n ])))\n```\n\n</details>\n\n<details>\n<summary>Build Metrics</summary>\n\nTo validate and test the model, we need to define a **Metric** called accuracy to evaluate the model. This metric needs to inherit from `BaseMetric` and implements the `process` and `compute_metrics` methods.\n\n```python\nfrom mmengine.evaluator import BaseMetric\n\nclass Accuracy(BaseMetric):\n def process(self, data_batch, data_samples):\n score, gt = data_samples\n # Save the results of a batch to `self.results`\n self.results.append({\n 'batch_size': len(gt),\n 'correct': (score.argmax(dim=1) == gt).sum().cpu(),\n })\n def compute_metrics(self, results):\n total_correct = sum(item['correct'] for item in results)\n total_size = sum(item['batch_size'] for item in results)\n # Returns a dictionary with the results of the evaluated metrics,\n # where the key is the name of the metric\n return dict(accuracy=100 * total_correct / total_size)\n```\n\n</details>\n\n<details>\n<summary>Build a Runner</summary>\n\nFinally, we can construct a **Runner** with previously defined `Model`, `DataLoader`, and `Metrics`, with some other configs, as shown below.\n\n```python\nfrom torch.optim import SGD\nfrom mmengine.runner import Runner\n\nrunner = Runner(\n model=MMResNet50(),\n work_dir='./work_dir',\n train_dataloader=train_dataloader,\n # a wrapper to execute back propagation and gradient update, etc.\n optim_wrapper=dict(optimizer=dict(type=SGD, lr=0.001, momentum=0.9)),\n # set some training configs like epochs\n train_cfg=dict(by_epoch=True, max_epochs=5, val_interval=1),\n val_dataloader=val_dataloader,\n val_cfg=dict(),\n val_evaluator=dict(type=Accuracy),\n)\n```\n\n</details>\n\n<details>\n<summary>Launch Training</summary>\n\n```python\nrunner.train()\n```\n\n</details>\n\n## Learn More\n\n<details>\n<summary>Tutorials</summary>\n\n- [Runner](https://mmengine.readthedocs.io/en/latest/tutorials/runner.html)\n- [Dataset and DataLoader](https://mmengine.readthedocs.io/en/latest/tutorials/dataset.html)\n- [Model](https://mmengine.readthedocs.io/en/latest/tutorials/model.html)\n- [Evaluation](https://mmengine.readthedocs.io/en/latest/tutorials/evaluation.html)\n- [OptimWrapper](https://mmengine.readthedocs.io/en/latest/tutorials/optim_wrapper.html)\n- [Parameter Scheduler](https://mmengine.readthedocs.io/en/latest/tutorials/param_scheduler.html)\n- [Hook](https://mmengine.readthedocs.io/en/latest/tutorials/hook.html)\n\n</details>\n\n<details>\n<summary>Advanced tutorials</summary>\n\n- [Registry](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/registry.html)\n- [Config](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/config.html)\n- [BaseDataset](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/basedataset.html)\n- [Data Transform](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/data_transform.html)\n- [Weight Initialization](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/initialize.html)\n- [Visualization](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/visualization.html)\n- [Abstract Data Element](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/data_element.html)\n- [Distribution Communication](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/distributed.html)\n- [Logging](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/logging.html)\n- [File IO](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/fileio.html)\n- [Global manager (ManagerMixin)](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/manager_mixin.html)\n- [Use modules from other libraries](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/cross_library.html)\n- [Test Time Agumentation](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/test_time_augmentation.html)\n\n</details>\n\n<details>\n<summary>Examples</summary>\n\n- [Train a GAN](https://mmengine.readthedocs.io/en/latest/examples/train_a_gan.html)\n\n</details>\n\n<details>\n<summary>Common Usage</summary>\n\n- [Resume Training](https://mmengine.readthedocs.io/en/latest/common_usage/resume_training.html)\n- [Speed up Training](https://mmengine.readthedocs.io/en/latest/common_usage/speed_up_training.html)\n- [Save Memory on GPU](https://mmengine.readthedocs.io/en/latest/common_usage/save_gpu_memory.html)\n\n</details>\n\n<details>\n<summary>Design</summary>\n\n- [Hook](https://mmengine.readthedocs.io/en/latest/design/hook.html)\n- [Runner](https://mmengine.readthedocs.io/en/latest/design/runner.html)\n- [Evaluation](https://mmengine.readthedocs.io/en/latest/design/evaluation.html)\n- [Visualization](https://mmengine.readthedocs.io/en/latest/design/visualization.html)\n- [Logging](https://mmengine.readthedocs.io/en/latest/design/logging.html)\n- [Infer](https://mmengine.readthedocs.io/en/latest/design/infer.html)\n\n</details>\n\n<details>\n<summary>Migration guide</summary>\n\n- [Migrate Runner from MMCV to MMEngine](https://mmengine.readthedocs.io/en/latest/migration/runner.html)\n- [Migrate Hook from MMCV to MMEngine](https://mmengine.readthedocs.io/en/latest/migration/hook.html)\n- [Migrate Model from MMCV to MMEngine](https://mmengine.readthedocs.io/en/latest/migration/model.html)\n- [Migrate Parameter Scheduler from MMCV to MMEngine](https://mmengine.readthedocs.io/en/latest/migration/param_scheduler.html)\n- [Migrate Data Transform to OpenMMLab 2.0](https://mmengine.readthedocs.io/en/latest/migration/transform.html)\n\n</details>\n\n## Contributing\n\nWe appreciate all contributions to improve MMEngine. Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for the contributing guideline.\n\n## Citation\n\nIf you find this project useful in your research, please consider cite:\n\n```\n@article{mmengine2022,\n title = {{MMEngine}: OpenMMLab Foundational Library for Training Deep Learning Models},\n author = {MMEngine Contributors},\n howpublished = {\\url{https://github.com/open-mmlab/mmengine}},\n year={2022}\n}\n```\n\n## License\n\nThis project is released under the [Apache 2.0 license](LICENSE).\n\n## Ecosystem\n\n- [APES: Attention-based Point Cloud Edge Sampling](https://github.com/JunweiZheng93/APES)\n- [DiffEngine: diffusers training toolbox with mmengine](https://github.com/okotaku/diffengine)\n\n## Projects in OpenMMLab\n\n- [MIM](https://github.com/open-mmlab/mim): MIM installs OpenMMLab packages.\n- [MMCV](https://github.com/open-mmlab/mmcv): OpenMMLab foundational library for computer vision.\n- [MMEval](https://github.com/open-mmlab/mmeval): A unified evaluation library for multiple machine learning libraries.\n- [MMPreTrain](https://github.com/open-mmlab/mmpretrain): OpenMMLab pre-training toolbox and benchmark.\n- [MMagic](https://github.com/open-mmlab/mmagic): Open**MM**Lab **A**dvanced, **G**enerative and **I**ntelligent **C**reation toolbox.\n- [MMDetection](https://github.com/open-mmlab/mmdetection): OpenMMLab detection toolbox and benchmark.\n- [MMYOLO](https://github.com/open-mmlab/mmyolo): OpenMMLab YOLO series toolbox and benchmark.\n- [MMDetection3D](https://github.com/open-mmlab/mmdetection3d): OpenMMLab's next-generation platform for general 3D object detection.\n- [MMRotate](https://github.com/open-mmlab/mmrotate): OpenMMLab rotated object detection toolbox and benchmark.\n- [MMTracking](https://github.com/open-mmlab/mmtracking): OpenMMLab video perception toolbox and benchmark.\n- [MMPose](https://github.com/open-mmlab/mmpose): OpenMMLab pose estimation toolbox and benchmark.\n- [MMSegmentation](https://github.com/open-mmlab/mmsegmentation): OpenMMLab semantic segmentation toolbox and benchmark.\n- [MMOCR](https://github.com/open-mmlab/mmocr): OpenMMLab text detection, recognition, and understanding toolbox.\n- [MMHuman3D](https://github.com/open-mmlab/mmhuman3d): OpenMMLab 3D human parametric model toolbox and benchmark.\n- [MMSelfSup](https://github.com/open-mmlab/mmselfsup): OpenMMLab self-supervised learning toolbox and benchmark.\n- [MMFewShot](https://github.com/open-mmlab/mmfewshot): OpenMMLab fewshot learning toolbox and benchmark.\n- [MMAction2](https://github.com/open-mmlab/mmaction2): OpenMMLab's next-generation action understanding toolbox and benchmark.\n- [MMFlow](https://github.com/open-mmlab/mmflow): OpenMMLab optical flow toolbox and benchmark.\n- [MMDeploy](https://github.com/open-mmlab/mmdeploy): OpenMMLab model deployment framework.\n- [MMRazor](https://github.com/open-mmlab/mmrazor): OpenMMLab model compression toolbox and benchmark.\n- [Playground](https://github.com/open-mmlab/playground): A central hub for gathering and showcasing amazing projects built upon OpenMMLab.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Engine of OpenMMLab projects",
"version": "0.10.1",
"project_urls": {
"Homepage": "https://github.com/open-mmlab/mmengine"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "290e08d9151b5e773fbb9691c4d7a47e6b6d583086581c819fd65083a1a73d30",
"md5": "5729936a5692acb6774ebe7740d1a808",
"sha256": "06e2e790f5b6952c5f00927e26bb5e5f5fd91e1d1468423eb8c4861fc479cc10"
},
"downloads": -1,
"filename": "mmengine-0.10.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5729936a5692acb6774ebe7740d1a808",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 450276,
"upload_time": "2023-11-22T03:15:40",
"upload_time_iso_8601": "2023-11-22T03:15:40.654939Z",
"url": "https://files.pythonhosted.org/packages/29/0e/08d9151b5e773fbb9691c4d7a47e6b6d583086581c819fd65083a1a73d30/mmengine-0.10.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5481328b9a35c6f8bfc9abcca0ca38ea224a6ab90e8245d41ff26510a37e5474",
"md5": "6a1a89a920d03a7c89c494d6387625b7",
"sha256": "0b07e0a3db969da3ee70ab8ba37f68f2f28660e631e73d6f7bbb8ee58e3995e1"
},
"downloads": -1,
"filename": "mmengine-0.10.1.tar.gz",
"has_sig": false,
"md5_digest": "6a1a89a920d03a7c89c494d6387625b7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 365547,
"upload_time": "2023-11-22T03:15:42",
"upload_time_iso_8601": "2023-11-22T03:15:42.910564Z",
"url": "https://files.pythonhosted.org/packages/54/81/328b9a35c6f8bfc9abcca0ca38ea224a6ab90e8245d41ff26510a37e5474/mmengine-0.10.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-22 03:15:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "open-mmlab",
"github_project": "mmengine",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"circle": true,
"requirements": [],
"lcname": "mmengine"
}
JSON
