nemo_automodel.components.optim
nemo_automodel.components.optim
Submodules
nemo_automodel.components.optim.dionnemo_automodel.components.optim.optimizernemo_automodel.components.optim.precision_warningsnemo_automodel.components.optim.scheduler
Package Contents
Classes
Functions
Data
API
Bases: _DionConfigBase
dion.Dion2 — recommended successor to the legacy Dion optimizer.
Bases: _DionConfigBase
dion.Dion — legacy low-rank optimizer (prefer Dion2Config).
Legacy Dion takes separate replicate/outer/inner shard meshes; for FSDP2 the
resolved 1-D shard submesh maps to outer_shard_mesh.
Bases: OptimizerConfig
transformer_engine.pytorch.optimizers.FusedAdam.
LR scheduler configuration. None fields are computed by
build from the training schedule (total steps, optimizer base LR/WD).
Build one LR scheduler per optimizer.
None fields are filled from the training schedule and each
optimizer’s base LR/WD.
Parameters:
The optimizer(s) to schedule.
The step scheduler, used to derive total steps.
Returns: list[OptimizerParamScheduler]
class:OptimizerParamScheduler per optimizer.
Bases: _DionConfigBase
dion.Muon — matrix-aware update for 2D+ params, scalar fallback for 1D.
Bases: _DionConfigBase
dion.NorMuon — Muon variant with neuron-wise normalization.
Base optimizer config.
Subclasses expose their full field surface and implement
_build_optimizer, the per-part hook that constructs a single
optimizer from a list of parameters. build owns the shared
orchestration (per-part loop, TP foreach, per-group LR overrides) and is
rarely overridden — only by configs whose construction does not fit the
parameters -> optimizer shape (e.g. MuonConfig). Megatron-FSDP
optimizer sharding is no longer applied here; the recipe layer re-applies it
via shard_optimizers_for_megatron_fsdp(...).
Construct a single optimizer for params (one model part).
asdict(self) with non-constructor (grouping) fields removed.
Build one optimizer per model.parts (or [model]).
Applies the shared per-part concerns (TP foreach disabling, per-group
LR/WD overrides) and delegates the actual optimizer instantiation to
_build_optimizer. Megatron-FSDP optimizer sharding is applied by
the recipe layer, not here.
Parameters:
Model (or model with .parts) to optimize.
Device mesh used for tensor/data parallelism.
Whether the model is being trained with PEFT (suppresses the bf16 torch-Adam precision warning).
Returns: list[torch.optim.Optimizer]
One optimizer per model part.
Build one optimizer from caller-defined parameter groups.
Bases: OptimizerConfig
Build an optimizer from an arbitrary factory callable plus kwargs.
The integration escape hatch (e.g. veRL): rather than exposing typed fields,
it wraps an optimizer class/callable and the **kwargs to construct it.
This keeps the factory path on the same config.build(model, ...) contract
as the typed configs, so build_optimizer never has to special-case it.
Hyperparameters live in kwargs; the inherited lr/weight_decay
fields are unused. The factory is called as factory(params=..., **kwargs);
Dion-family optimizers (which need parameter grouping) should use the typed
MuonConfig instead. A param_group_overrides entry in
kwargs is consumed here (not forwarded to the factory) to drive
per-group LR/WD, matching the typed-config behavior.
Anneals learning rate and weight decay.
Parameters:
the optimizer to be used
initial learning rate
maximum learning rate
minimum learning rate
number of warmup steps
number of decay steps
decay style for learning rate
initial weight decay
final weight decay
number of weight decay increment steps
weight decay increment style
whether to use the checkpoint values for the optimizer param scheduler. Defaults to True.
whether to override the optimizer param scheduler values with the class values. Defaults to False.
number of weight decay decay steps. Defaults to None.
decay style for learning rate during weight decay decay steps. Defaults to None.
Return a string representation of the OptimizerParamScheduler.
Auxiliary function for checking the values in the checkpoint and setting them.
Parameters:
class value
checkpoint value
name of the parameter
Learning rate decay functions from: https://openreview.net/pdf?id=BJYwwY9ll pg. 4.
Argsa: param_group (dict): parameter group from the optimizer.
Weight decay incr functions.
Load the state dict.
Every restored field is applied before the final step call, so the
learning rate and weight decay written into optimizer.param_groups both
reflect the checkpoint’s schedule rather than the constructor’s. The step
count is treated as absolute, so loading is idempotent.
Parameters:
state dict to be load
Return the state dict.
Set lr and weight decay for all parameter groups.
Each group gets the scheduled value times its lr_mult / wd_mult (see _set_group_mults).
Parameters:
number of steps to increment
Per-parameter-group learning-rate / weight-decay override.
Parameters whose (module-qualified) name matches pattern are placed
in their own optimizer parameter group carrying lr_mult /
wd_mult, which the LR scheduler multiplies into the group’s learning
rate and weight decay every step (see
OptimizerParamScheduler.step). This mirrors Megatron-LM’s per-group
lr_mult scaling of max_lr / min_lr.
Multiplier applied to this group’s learning rate.
Python regular expression matched against each parameter name
with re.search (so a plain substring like "router" also
works).
Multiplier applied to this group’s weight decay.
Build the parameter groups and resolve the device mesh for a Dion-family optimizer.
This does not instantiate the optimizer; it returns (param_groups, mesh_kwargs) so the caller (a typed config in
nemo_automodel.components.optim.optimizer) can assemble its own
constructor kwargs and instantiate the optimizer itself. mesh_kwargs is a
dict that maps mesh_kwarg to the resolved mesh (or is empty when there is
no mesh), ready to splat into the optimizer constructor.
The parameter-grouping settings are read off config: lr,
weight_decay, scalar_opt, scalar_betas, scalar_eps
(required), and the optional scalar_lr, embed_lr, lm_head_lr and
no_compile.
Parameters:
The dion-family config (see _DionFamilyConfig) to read settings from.
Model whose parameters are to be optimized.
Optional DeviceMesh for FSDP/TP. When non-empty it is resolved to a 1-D Dion submesh.
Name of the constructor argument that receives the resolved
mesh ("distributed_mesh" for Muon/Dion2/NorMuon,
"outer_shard_mesh" for legacy Dion). Set to None to never
include the mesh.
Returns: list[dict[str, Any]]
A (param_groups, mesh_kwargs) tuple: the per-group parameter dicts and
Build one optimizer per model.parts (or [model]).
Thin dispatcher: it normalizes config to an OptimizerConfig and
returns config.build(model, ...). Per-part concerns (TP foreach,
Dion param grouping) live on the config. Megatron-FSDP optimizer sharding is
re-applied separately by the recipe layer.
config is one of:
- a typed
OptimizerConfiginstance — the Automodel-native path. - a
(name_or_path, kwargs)tuple, wherename_or_pathis a short registry name (seeOPTIMIZER_CONFIG_REGISTRY, e.g."adamw") or a dotted import path (e.g."torch.optim.AdamW"), andkwargsare the constructor arguments. A registry/import-path that resolves to anOptimizerConfigsubclass is built from its typed fields; any other callable is wrapped in anOptimizerFromFactoryConfig(the escape hatch for external integrations, e.g. veRL).
Parameters:
Model (or model with .parts) to optimize.
An OptimizerConfig instance or a (name_or_path, kwargs) tuple.
Device mesh used for tensor/data parallelism.
Returns: list[torch.optim.Optimizer]
One optimizer per model part.
Normalize an optimizer target plus kwargs into an OptimizerConfig.
This is the single normalization entry point shared by the recipe layer
(which resolves a YAML _target_ to a Python object) and
build_optimizer (which accepts (name_or_path, kwargs) tuples).
target is one of:
- an
OptimizerConfiginstance — returned as-is (kwargsignored, since the instance already carries its typed fields). - an
OptimizerConfigsubclass — instantiated from its typed fields with**kwargs. - a string — a registry short name (see
OPTIMIZER_CONFIG_REGISTRY, e.g."adamw") or a dotted import path (e.g."torch.optim.AdamW"); it is resolved and then handled as a subclass or callable. - any other optimizer callable/class — wrapped in an
OptimizerFromFactoryConfig(the escape hatch for external integrations, e.g. veRL).
Parameters:
The optimizer config instance/subclass, registry name or import path, or optimizer callable to normalize.
Constructor arguments for the resolved config/callable.
Returns: OptimizerConfig
class:OptimizerConfig ready to build(...).
Return whether an optimizer factory targets a Dion-family optimizer.