# open-mmlab/mmengine architecture

> Architecture diagram of the GitHub repository open-mmlab/mmengine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open-mmlab/mmengine
- Repository: https://github.com/open-mmlab/mmengine

## Overview

#### Purpose and entry points
MMEngine is a Python/PyTorch foundation library for configurable deep-learning training, validation, testing, inference, and experiment operations. Consumers import its public package (`mmengine/__init__.py`) and typically construct `Runner` programmatically or from configuration; examples include `examples/segmentation/train.py` and `examples/llama2/fsdp_finetune.py`. It is a reusable library, not a standalone service or web application.

#### Configuration and dependency construction
The configuration layer loads/merges Python, JSON, and YAML configurations, including lazy Python configuration support. The registry and default-scope system turn typed config dictionaries into project or third-party objects, decoupling engine orchestration from model, dataset, metric, hook, and optimizer implementations.
- `mmengine/config/config.py`
- `mmengine/config/lazy.py`
- `mmengine/registry/registry.py`

#### Training orchestration
`Runner` is the central control-plane object: it owns runtime state and coordinates model execution, dataloaders, loops, evaluators, optimization, hooks, checkpointing, and logging. Standard and flexible runner implementations delegate iteration/epoch behavior to loop classes. Primary flow is: configuration/objects → runner → train/validation/test loops → model and optimizer steps → hooks, evaluators, and output backends.
- `mmengine/runner/runner.py`
- `mmengine/runner/_flexible_runner.py`
- `mmengine/runner/loops.py`

#### Model, data, and evaluation boundary
Applications supply PyTorch-compatible models through `BaseModel`, which standardizes forward modes such as loss and prediction plus data preprocessing. Dataset abstractions, wrappers, and samplers provide data to PyTorch dataloaders. Evaluation converts per-batch predictions into metric state/results; application-specific models and metrics remain outside the engine.
- `mmengine/model/base_model/base_model.py`
- `mmengine/dataset/base_dataset.py`
- `mmengine/evaluator/evaluator.py`

#### Optimization and extensibility lifecycle
Optimizer wrappers encapsulate backward propagation, gradient accumulation/clipping, AMP, and parameter updates; schedulers change optimization parameters over time. Hooks are ordered lifecycle extensions around runner and loop events, covering checkpointing, scheduling, timers, EMA, profiling, and logging without embedding these concerns in core loops.
- `mmengine/optim/optimizer/optimizer_wrapper.py`
- `mmengine/optim/scheduler/param_scheduler.py`
- `mmengine/hooks/hook.py`

#### Scale-out strategies and distributed execution
PyTorch distributed utilities and model wrappers support multi-process/device execution. The strategy subsystem abstracts single-device, standard distributed, FSDP, DeepSpeed, and ColossalAI setup, allowing the runner to operate across differing large-model runtimes. Activation checkpointing and AMP live near runner execution.
- `mmengine/_strategy/base.py`
- `mmengine/_strategy/deepspeed.py`
- `mmengine/_strategy/fsdp.py`

#### Persistence, observability, and external integrations
Checkpoint facilities persist and resume training state. Logging aggregates scalar/runtime state through a message hub; visualization routes artifacts and metrics through pluggable backends. File I/O abstracts local files, HTTP, LMDB, Memcached, and Petrel storage. Supported integrations include TensorBoard, Weights & Biases, MLflow, ClearML, Neptune, DVCLive, and Aim through visualization/logging backends; PyTorch is the primary runtime, with optional DeepSpeed, FSDP, and ColossalAI.
- `mmengine/runner/checkpoint.py`
- `mmengine/visualization/vis_backend.py`
- `mmengine/fileio/io.py`

Main entry points: [`mmengine/runner/runner.py`](https://github.com/open-mmlab/mmengine/blob/main/mmengine/runner/runner.py) (Runner), [`mmengine/runner/loops.py`](https://github.com/open-mmlab/mmengine/blob/main/mmengine/runner/loops.py) (Train / Val / Test Loops), [`mmengine/hooks/hook.py`](https://github.com/open-mmlab/mmengine/blob/main/mmengine/hooks/hook.py) (Hooks), [`mmengine/config/config.py`](https://github.com/open-mmlab/mmengine/blob/main/mmengine/config/config.py) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_construction["Configuration &amp; Construction"]
  node_config["Configuration<br/>config loader<br/>[config.py]"]
  node_lazy_config["Lazy Config<br/>config support<br/>[lazy.py]"]
  node_registry["Registry &amp; Scope<br/>object factory<br/>[registry.py]"]
end

subgraph group_execution["Runner Execution"]
  node_runner["Runner<br/>control plane<br/>[runner.py]"]
  node_flexible_runner["Flexible Runner<br/>runner variant"]
  node_loops["Train / Val / Test Loops<br/>execution loops<br/>[loops.py]"]
  node_model["BaseModel<br/>model boundary<br/>[base_model.py]"]
  node_dataset["BaseDataset<br/>data boundary<br/>[base_dataset.py]"]
  node_evaluator["Evaluator<br/>evaluation<br/>[evaluator.py]"]
  node_strategy["Execution Strategies<br/>distributed runtime<br/>[base.py]"]
  node_deepspeed["DeepSpeed Strategy<br/>strategy implementation<br/>[deepspeed.py]"]
  node_fsdp["FSDP Strategy<br/>strategy implementation<br/>[fsdp.py]"]
end

subgraph group_extension["Optimization &amp; Extensions"]
  node_optimizer["Optimizer Wrapper<br/>optimization"]
  node_scheduler["Parameter Scheduler<br/>optimization schedule<br/>[param_scheduler.py]"]
  node_hooks["Hooks<br/>lifecycle extensions<br/>[hook.py]"]
end

subgraph group_platform["Persistence &amp; Integrations"]
  node_checkpoint[("Checkpointing<br/>state persistence<br/>[checkpoint.py]")]
  node_visualization["Visualization Backends<br/>observability<br/>[vis_backend.py]"]
  node_fileio["File I/O<br/>storage abstraction<br/>[io.py]"]
end

node_consumer(("Applications<br/>consumer code"))

node_consumer -->|"loads"| node_config
node_consumer -->|"constructs"| node_runner
node_config -->|"supports"| node_lazy_config
node_config -->|"provides specs to"| node_registry
node_registry -->|"builds components for"| node_runner
node_runner -.->|"offers variant"| node_flexible_runner
node_runner -->|"delegates execution to"| node_loops
node_runner -->|"selects runtime"| node_strategy
node_strategy -.->|"implements"| node_deepspeed
node_strategy -.->|"implements"| node_fsdp
node_loops -->|"reads batches from"| node_dataset
node_loops -->|"executes"| node_model
node_loops -->|"updates through"| node_optimizer
node_loops -->|"submits predictions to"| node_evaluator
node_runner -->|"emits lifecycle events to"| node_hooks
node_hooks -->|"drives"| node_scheduler
node_hooks -->|"triggers"| node_checkpoint
node_hooks -->|"reports through"| node_visualization
node_checkpoint -->|"stores via"| node_fileio

click node_config "https://github.com/open-mmlab/mmengine/blob/main/mmengine/config/config.py"
click node_lazy_config "https://github.com/open-mmlab/mmengine/blob/main/mmengine/config/lazy.py"
click node_registry "https://github.com/open-mmlab/mmengine/blob/main/mmengine/registry/registry.py"
click node_runner "https://github.com/open-mmlab/mmengine/blob/main/mmengine/runner/runner.py"
click node_flexible_runner "https://github.com/open-mmlab/mmengine/blob/main/mmengine/runner/_flexible_runner.py"
click node_loops "https://github.com/open-mmlab/mmengine/blob/main/mmengine/runner/loops.py"
click node_model "https://github.com/open-mmlab/mmengine/blob/main/mmengine/model/base_model/base_model.py"
click node_dataset "https://github.com/open-mmlab/mmengine/blob/main/mmengine/dataset/base_dataset.py"
click node_evaluator "https://github.com/open-mmlab/mmengine/blob/main/mmengine/evaluator/evaluator.py"
click node_strategy "https://github.com/open-mmlab/mmengine/blob/main/mmengine/_strategy/base.py"
click node_deepspeed "https://github.com/open-mmlab/mmengine/blob/main/mmengine/_strategy/deepspeed.py"
click node_fsdp "https://github.com/open-mmlab/mmengine/blob/main/mmengine/_strategy/fsdp.py"
click node_optimizer "https://github.com/open-mmlab/mmengine/blob/main/mmengine/optim/optimizer/optimizer_wrapper.py"
click node_scheduler "https://github.com/open-mmlab/mmengine/blob/main/mmengine/optim/scheduler/param_scheduler.py"
click node_hooks "https://github.com/open-mmlab/mmengine/blob/main/mmengine/hooks/hook.py"
click node_checkpoint "https://github.com/open-mmlab/mmengine/blob/main/mmengine/runner/checkpoint.py"
click node_visualization "https://github.com/open-mmlab/mmengine/blob/main/mmengine/visualization/vis_backend.py"
click node_fileio "https://github.com/open-mmlab/mmengine/blob/main/mmengine/fileio/io.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_lazy_config,node_registry toneBlue
class node_runner,node_flexible_runner,node_loops,node_model,node_dataset,node_evaluator,node_strategy,node_deepspeed,node_fsdp toneAmber
class node_optimizer,node_scheduler,node_hooks toneMint
class node_checkpoint,node_visualization,node_fileio toneRose
class node_consumer toneNeutral
```

## Components

### Configuration & Construction

- [Configuration](https://github.com/open-mmlab/mmengine/blob/main/mmengine/config/config.py): config loader · Loads and merges Python, JSON, YAML, and lazy configs. · `mmengine/config/config.py`
- [Lazy Config](https://github.com/open-mmlab/mmengine/blob/main/mmengine/config/lazy.py): config support · `mmengine/config/lazy.py`
- [Registry & Scope](https://github.com/open-mmlab/mmengine/blob/main/mmengine/registry/registry.py): object factory · Builds typed configuration objects and resolves project scopes. · `mmengine/registry/registry.py`

### Runner Execution

- [Runner](https://github.com/open-mmlab/mmengine/blob/main/mmengine/runner/runner.py): control plane · Owns runtime state and coordinates execution components. · `mmengine/runner/runner.py`
- [Flexible Runner](https://github.com/open-mmlab/mmengine/blob/main/mmengine/runner/_flexible_runner.py): runner variant · `mmengine/runner/_flexible_runner.py`
- [Train / Val / Test Loops](https://github.com/open-mmlab/mmengine/blob/main/mmengine/runner/loops.py): execution loops · Implements iteration and epoch behavior. · `mmengine/runner/loops.py`
- [BaseModel](https://github.com/open-mmlab/mmengine/blob/main/mmengine/model/base_model/base_model.py): model boundary · Standardizes preprocessing, loss, and prediction forward modes. · `mmengine/model/base_model/base_model.py`
- [BaseDataset](https://github.com/open-mmlab/mmengine/blob/main/mmengine/dataset/base_dataset.py): data boundary · Supplies dataset abstractions for PyTorch dataloaders. · `mmengine/dataset/base_dataset.py`
- [Evaluator](https://github.com/open-mmlab/mmengine/blob/main/mmengine/evaluator/evaluator.py): evaluation · Accumulates predictions into metric results. · `mmengine/evaluator/evaluator.py`
- [Execution Strategies](https://github.com/open-mmlab/mmengine/blob/main/mmengine/_strategy/base.py): distributed runtime · Abstracts single-device, distributed, FSDP, DeepSpeed, and ColossalAI setup. · `mmengine/_strategy/base.py`
- [DeepSpeed Strategy](https://github.com/open-mmlab/mmengine/blob/main/mmengine/_strategy/deepspeed.py): strategy implementation · `mmengine/_strategy/deepspeed.py`
- [FSDP Strategy](https://github.com/open-mmlab/mmengine/blob/main/mmengine/_strategy/fsdp.py): strategy implementation · `mmengine/_strategy/fsdp.py`

### Optimization & Extensions

- [Optimizer Wrapper](https://github.com/open-mmlab/mmengine/blob/main/mmengine/optim/optimizer/optimizer_wrapper.py): optimization · Manages backward pass, AMP, gradients, and parameter updates. · `mmengine/optim/optimizer/optimizer_wrapper.py`
- [Parameter Scheduler](https://github.com/open-mmlab/mmengine/blob/main/mmengine/optim/scheduler/param_scheduler.py): optimization schedule · `mmengine/optim/scheduler/param_scheduler.py`
- [Hooks](https://github.com/open-mmlab/mmengine/blob/main/mmengine/hooks/hook.py): lifecycle extensions · Ordered callbacks for runner and loop events. · `mmengine/hooks/hook.py`

### Persistence & Integrations

- [Checkpointing](https://github.com/open-mmlab/mmengine/blob/main/mmengine/runner/checkpoint.py): state persistence · Persists and resumes training state. · `mmengine/runner/checkpoint.py`
- [Visualization Backends](https://github.com/open-mmlab/mmengine/blob/main/mmengine/visualization/vis_backend.py): observability · Routes metrics and artifacts to pluggable integrations. · `mmengine/visualization/vis_backend.py`
- [File I/O](https://github.com/open-mmlab/mmengine/blob/main/mmengine/fileio/io.py): storage abstraction · Accesses local and remote storage backends. · `mmengine/fileio/io.py`

### Other components

- **Applications**: consumer code · Programs construct and run MMEngine training workflows.

## Connections

- Applications → Configuration: loads
- Applications → Runner: constructs
- Configuration → Lazy Config: supports
- Configuration → Registry & Scope: provides specs to
- Registry & Scope → Runner: builds components for
- Runner → Flexible Runner: offers variant
- Runner → Train / Val / Test Loops: delegates execution to
- Runner → Execution Strategies: selects runtime
- Execution Strategies → DeepSpeed Strategy: implements
- Execution Strategies → FSDP Strategy: implements
- Train / Val / Test Loops → BaseDataset: reads batches from
- Train / Val / Test Loops → BaseModel: executes
- Train / Val / Test Loops → Optimizer Wrapper: updates through
- Train / Val / Test Loops → Evaluator: submits predictions to
- Runner → Hooks: emits lifecycle events to
- Hooks → Parameter Scheduler: drives
- Hooks → Checkpointing: triggers
- Hooks → Visualization Backends: reports through
- Checkpointing → File I/O: stores via
