Feature/wsd scheduler

[hawkoli1987]

Important

The Update branch button must only be pressed in very rare occassions.
An outdated branch is never blocking the merge of a PR.
Please reach out to the automation team before pressing that button.

What does this PR do ?

Implements the Weight Stable Decay (WSD) scheduler with both linear (https://arxiv.org/pdf/2404.06395) and one-minus-square-root decay options (https://arxiv.org/html/2408.11029) as described in recent research papers. This scheduler introduces a three-phase learning rate schedule: warmup, hold, and decay, which has been shown to improve training stability and performance for large language models.

Collection: [Note which collection this PR will affect]
Core

Changelog

• Added WarmupHoldAnnealOneMinusSquareRoot scheduler that implements the 1-sqrt(t) decay pattern
• Added WarmupHoldAnnealLinear scheduler that implements the linear decay pattern
• Added WarmupHoldAnnealScheduler Lightning wrapper class that supports both decay schedules
• Added unit tests for both scheduler implementations
• Updated scheduler registry to include the new schedulers

Usage

• You can potentially add a usage example below

# Using the Lightning wrapper
from nemo.core.optim.lr_scheduler import WarmupHoldAnneal

# One-minus-square-root decay (recommended in the paper)
scheduler = WarmupHoldAnneal(
    warmup_ratio=0.01,    # 1% of steps for warmup
    hold_ratio=0.19,      # 19% of steps for hold phase
    max_steps=10000,      # Total training steps
    decay_schedule="one_minus_square_root",  # Use 1-sqrt(t) decay
    min_lr=1e-6           # Minimum learning rate
)

# Linear decay option
scheduler = WarmupHoldAnneal(
    warmup_ratio=0.01,
    hold_ratio=0.19,
    max_steps=10000,
    decay_schedule="linear",  # Use linear decay
    min_lr=1e-6
)

# Direct usage with PyTorch optimizer
from nemo.core.optim.lr_scheduler import WarmupHoldAnnealOneMinusSquareRoot

optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
scheduler = WarmupHoldAnnealOneMinusSquareRoot(
    optimizer,
    warmup_ratio=0.01,
    hold_ratio=0.19,
    max_steps=10000,
    min_lr=1e-6
)

GitHub Actions CI

The Jenkins CI system has been replaced by GitHub Actions self-hosted runners.

The GitHub Actions CI will run automatically when the "Run CICD" label is added to the PR.
To re-run CI remove and add the label again.
To run CI on an untrusted fork, a NeMo user with write access must first click "Approve and run".

Before your PR is "Ready for review"

Pre checks:

• Make sure you read and followed Contributor guidelines
• Did you write any new necessary tests?
• Did you add or update any necessary documentation?
• Does the PR affect components that are optional to install? (Ex: Numba, Pynini, Apex etc)
• Reviewer: Does the PR have correct import guards for all optional libraries?

PR Type:

• New Feature
• Bugfix
• Documentation

If you haven't finished some of the above items you can still open "Draft" PR.

Who can review?

Anyone in the community is free to review the PR once the checks have passed.
Contributor guidelines contains specific people who can review PRs to various areas.

Additional Information

• Related to # (issue)

[titu1994]

Thank you for your contribution ! The PR looks correct and has tests that pass so it's good to merge from my end

[ericharper]

@hawkoli1987 , thanks for the contribution! Could you respond to the reviewer comments so we can merge this?

[hawkoli1987]

@hawkoli1987 , thanks for the contribution! Could you respond to the reviewer comments so we can merge this?

Thanks @ericharper for your review! Sorry for the delay, I have updated the docstring and updated the PR. First time making PR to NeMo, please guide me along!

[github-actions]

This PR is stale because it has been open for 14 days with no activity. Remove stale label or comment or update or this will be closed in 7 days.

[github-actions]

This PR was closed because it has been inactive for 7 days since being marked as stale.

[ashors1]

@marcromeyn Could you give this PR a final review? @hawkoli1987 It also looks like there's a merge conflict. Could you please help to resolve that so we can get this PR in? Thank you both!

[marcromeyn]

Doc string missing here

[ashors1]

@hawkoli1987 are you able to add a docstring here to address this comment?

[github-actions]

This PR is stale because it has been open for 14 days with no activity. Remove stale label or comment or update or this will be closed in 7 days.

[hawkoli1987]

will try to resolve the conflicts asap, sorry for the delay!

[hawkoli1987]

conflict resolved, thanks!

[github-actions]

This PR is stale because it has been open for 14 days with no activity. Remove stale label or comment or update or this will be closed in 7 days.

[github-actions]

This PR was closed because it has been inactive for 7 days since being marked as stale.