<div align="center">
# Emerging Optimizers
</div>
<div align="center">
<!-- Get the codecov badge with a token direct from https://app.codecov.io/gh/NVIDIA-NeMo -->
[](https://codecov.io/gh/NVIDIA-NeMo/Emerging-Optimizers)
[](https://github.com/NVIDIA-NeMo/Emerging-Optimizers/actions/workflows/cicd-main.yml)
[](https://www.python.org/downloads/release/python-3120/)
[](https://docs.nvidia.com/nemo/emerging-optimizers/latest/index.html)
</div>
## Overview
Emerging Optimizers is a research project focused on understanding and optimizing the algorithmic behavior of emerging optimizers (including Shampoo, SOAP, Muon, and others) and their implications to performance of GPU systems in LLM training.
> ⚠️ Note: Emerging-Optimizers is under active development. All APIs are experimental and subject to change. New features, improvements, and documentation updates are released regularly. Your feedback and contributions are welcome, and we encourage you to follow along as new updates roll out.
## Background
### What are Emerging Optimizers?
Emerging optimizers represent a class of novel optimization algorithms that go beyond traditional first-order methods like Adam or SGD. These include optimizers that use matrix-based (non-diagonal) preconditioning, orthogonalization techniques, and other innovative approaches to achieve faster convergence and improved training efficiency.
Examples include Shampoo, which uses Kronecker-factored preconditioning ([arXiv:1802.09568](https://arxiv.org/abs/1802.09568)), and Muon, which uses Newton-Schulz orthogonalization ([arXiv:2502.16982](https://arxiv.org/abs/2502.16982)).
### Why They Matter
Emerging optimizers have demonstrated significant practical impact in large-scale language model training. Most notably, **Muon was used to train the Kimi K2 model** ([arXiv:2507.20534](https://arxiv.org/abs/2507.20534)), showcasing the effectiveness of these novel approaches at scale. These optimizers can:
- Achieve faster convergence, reducing the number of training steps required
- Improve final model quality through better conditioning of the optimization landscape
- Enable more efficient hyperparameter tuning due to reduced sensitivity to learning rates
## Installation
### Prerequisites
- Python 3.12 (Release v0.1.0 is the last version supports Python 3.10)
- PyTorch 2.0 or higher
### Install from Source
```bash
git clone https://github.com/NVIDIA-NeMo/Emerging-Optimizers.git
cd Emerging-Optimizers
pip install .
```
## Usage
### Example
Refer to tests for usage of different optimizers, e.g. [`tests/test_orthogonalized_optimizer.py::MuonTest`](tests/test_orthogonalized_optimizer.py).
Train the upstream nanoGPT model with absl flags and a choice of optimizers using the
[minimal-dependency nanoGPT example](examples/nanogpt/README.md). It supports checkpoint resume,
mixed precision, generation, and PyTorch DDP.
### Integration with Megatron Core
Emerging optimizer has been integrated into Megatron Core with tensor parallel support and many other features (split QKV for example), check out [emerging_optimizers.py](https://github.com/NVIDIA/Megatron-LM/blob/core_v0.18.0/megatron/core/optimizer/emerging_optimizers.py).
## Pitfalls
### Resuming bf16 training from an optimizer checkpoint
Several optimizers (SOAP, Shampoo, Iso and their KL variants, for example) keep their state in fp32 even when the
parameters are bf16. `torch.optim.Optimizer.load_state_dict` casts floating point state to the parameter dtype, so
after loading a checkpoint that state comes back as bf16 and the next `step()` fails with a dtype mismatch. From
PyTorch 2.16 this cast emits a `FutureWarning`, and loading inside `torch.optim.preserve_state_dtype_on_load()` keeps
the saved dtypes:
```python
with torch.optim.preserve_state_dtype_on_load():
optimizer.load_state_dict(state_dict)
```
On older PyTorch versions, copy the saved fp32 state tensors back into `optimizer.state` after loading.
## Benchmarks
Benchmark of Muon can be found in our [blog](https://developer.nvidia.com/blog/advancing-emerging-optimizers-for-accelerated-llm-training-with-nvidia-megatron/).
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.