diff --git a/docs/en/advanced_tutorials/manager_mixin.md b/docs/en/advanced_tutorials/manager_mixin.md new file mode 100644 index 00000000..15f3ef84 --- /dev/null +++ b/docs/en/advanced_tutorials/manager_mixin.md @@ -0,0 +1,74 @@ +# Global manager (ManagerMixin) + +During the training process, it is inevitable that we need to access some variables globally. Here are some examples: + +- Accessing the [logger](mmengine.logging.MMLogger) in model to print some initialization information +- Accessing the [Visualizer](mmengine.config.Config) anywhere to visualize the predictions and feature maps. +- Accessing the scope in [Registry](mmengine.registry.Registry) to get the current scope. + +In order to unify the mechanism to get the global variable built from different classes, MMEngine designs the [ManagerMixin](mmengine.utils.ManagerMixin). + +## Interface introduction + +- get_instance(name='', \*\*kwargs): Create or get the instance by name. +- get_current_instance(): Get the currently built instance. +- instance_name: Get the name of the instance. + +## How to use + +1. Define a class inherited from `ManagerMixin` + +```python +from mmengine.utils import ManagerMixin + + +class GlobalClass(ManagerMixin): + def __init__(self, name, value): + super().__init__(name) + self.value = value +``` + +```{note} +Subclasses of `ManagerMixin` must accept `name` argument in `__init__`. The `name` argument is used to identify the instance, and you can get the instance by `get_instance(name)`. +``` + +2. Instantiate the instance anywhere. let's take the hook as an example: + +```python +from mmengine import Hook + +class CustomHook(Hook): + def before_run(self, runner): + GlobalClass.get_instance('mmengine', value=50) + GlobalClass.get_instance(runner.experiment_name, value=100) +``` + +`GlobalClass.get_instance({name})` will first check whether the instance with the name `{name}` has been built. If not, it will build a new instance with the name `{name}`, otherwise it will return the existing instance. As the above example shows, when we call `GlobalClass.get_instance('mmengine')` at the first time, it will build a new instance with the name `mmengine`. Then we call `GlobalClass.get_instance(runner.experiment_name)`, it will also build a new instance with a different name. + +Here we build two instances for the convenience of the subsequent introduction of `get_current_instance`. + +3. Accessing the instance anywhere + +```python +import torch.nn as nn + + +class CustomModule(nn.Module): + def forward(self, x): + value = GlobalClass.get_current_instance().value + # Since the name of the latest built instance is + # `runner.experiment_name`, value will be 100. + + value = GlobalClass.get_instance('mmengine').value + # The value of instance with the name mmengine is 50. + + value = GlobalClass.get_instance('mmengine', 1000).value + # `mmengine` instance has been built, an error will be raised + # if `get_instance` accepts other parameters. +``` + +We can get the instance with the specified name by `get_instance(name)`, or get the currently built instance by `get_current_instance` anywhere. + +```{warning} +If the instance with the specified name has already been built, `get_instance` will raise an error if it accepts its construct parameters. +``` diff --git a/docs/en/advanced_tutorials/utils.md b/docs/en/advanced_tutorials/utils.md deleted file mode 100644 index 58f14248..00000000 --- a/docs/en/advanced_tutorials/utils.md +++ /dev/null @@ -1,3 +0,0 @@ -# utils - -Coming soon. Please refer to [chinese documentation](https://mmengine.readthedocs.io/zh_CN/latest/advanced_tutorials/utils.html). diff --git a/docs/en/index.rst b/docs/en/index.rst index a54b5eec..fdab224e 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -45,7 +45,7 @@ You can switch between Chinese and English documents in the lower-left corner of advanced_tutorials/distributed.md advanced_tutorials/logging.md advanced_tutorials/fileio.md - advanced_tutorials/utils.md + advanced_tutorials/manager_mixin.md advanced_tutorials/cross_library.md .. toctree:: diff --git a/docs/zh_cn/advanced_tutorials/utils.md b/docs/zh_cn/advanced_tutorials/manager_mixin.md similarity index 90% rename from docs/zh_cn/advanced_tutorials/utils.md rename to docs/zh_cn/advanced_tutorials/manager_mixin.md index 06da2782..b90f70ea 100644 --- a/docs/zh_cn/advanced_tutorials/utils.md +++ b/docs/zh_cn/advanced_tutorials/manager_mixin.md @@ -1,19 +1,16 @@ -# 辅助类 +# 全局管理器(ManagerMixin) -## 全局管理器(ManagerMixin) - -Runner 在训练过程中,难免会使用全局变量来共享信息,例如我们会在 model 中获取全局的 [logger](mmengine.logging.MMLogger) 来打印初始化信息;在 model 中获取全局的 [Visualizer](./visualization.md) 来可视化预测结果、特征图;在 [Registry](../tutorials/registry.md) 中获取全局的 [DefaultScope](mmengine.registry.DefaultScope) 来确定注册域。为了管理这些功能相似的模块,MMEngine 实现了管理器(ManagerMix)来统一全局变量的创建和获取方式。 +Runner 在训练过程中,难免会使用全局变量来共享信息,例如我们会在 model 中获取全局的 [logger](mmengine.logging.MMLogger) 来打印初始化信息;在 model 中获取全局的 [Visualizer](./visualization.md) 来可视化预测结果、特征图;在 [Registry](../tutorials/registry.md) 中获取全局的 [DefaultScope](mmengine.registry.DefaultScope) 来确定注册域。为了管理这些功能相似的模块,MMEngine 设计了管理器 [ManagerMix](mmengine.utils.ManagerMixin) 来统一全局变量的创建和获取方式。 ![ManagerMixin](https://user-images.githubusercontent.com/57566630/163429552-3c901fc3-9cc1-4b71-82b6-d051f452a538.png) -### 接口介绍 +## 接口介绍 -- \_instance_name:被创建的全局实例名 - get_instance(name='', \*\*kwargs):创建或者返回对应名字的的实例。 - get_current_instance():返回最近被创建的实例。 -- instance_name::获取对应实例的 name。 +- instance_name:获取对应实例的 name。 -### 使用方法 +## 使用方法 1. 定义有全局访问需求的类 diff --git a/docs/zh_cn/index.rst b/docs/zh_cn/index.rst index 389a62ee..11869ab0 100644 --- a/docs/zh_cn/index.rst +++ b/docs/zh_cn/index.rst @@ -45,7 +45,7 @@ advanced_tutorials/distributed.md advanced_tutorials/logging.md advanced_tutorials/fileio.md - advanced_tutorials/utils.md + advanced_tutorials/manager_mixin.md advanced_tutorials/cross_library.md .. toctree::