Ensure restarting from checkpoints leads to consistent internal counters #20379

lantiga · 2024-10-31T15:18:18Z

What does this PR do?

The following code

import torch
from torch.utils.data import DataLoader, Dataset
 
import lightning as L
from lightning.pytorch.callbacks import ModelCheckpoint

 
class RandomDataset(Dataset):
   def __init__(self, size, length):
       self.len = length
       self.data = torch.randn(length, size)
 
   def __getitem__(self, index):
       return self.data[index]
 
   def __len__(self):
       return self.len
 
 
class BoringModel(L.LightningModule):
   def __init__(self):
       super().__init__()
       self.layer = torch.nn.Linear(32, 2)
 
   def forward(self, x):
       return self.layer(x)
 
   def training_step(self, batch, batch_idx):
       loss = self(batch).sum()
       return {"loss": loss}
 
   def configure_optimizers(self):
       return torch.optim.SGD(self.layer.parameters(), lr=0.1)

 
train_data = DataLoader(RandomDataset(32, 24), batch_size=2)
 
model = BoringModel()

trainer = L.Trainer(
   default_root_dir=".",
   max_steps=10,
   enable_model_summary=False,
   accelerator="cpu",
   callbacks=ModelCheckpoint(dirpath="./lightning_logs/checkpoints", save_last=True, save_top_k=-1, every_n_train_steps=10),
)
trainer.fit(model, train_data)

trainer = L.Trainer(
   default_root_dir=".",
   max_steps=20,
   enable_model_summary=False,
   accelerator="cpu",
   callbacks=ModelCheckpoint(dirpath="./lightning_logs/checkpoints", save_last=True, save_top_k=-1, every_n_train_steps=10),
)
trainer.fit(model, train_data, ckpt_path='last')

will produce skewed progress information in the checkpoints, compared to the case where there is no restart.

This is due to the fact that when ModelCheckpoint is triggered on on_train_batch_end, it won't see batch_progress.total.completed updated to the latest batch that was processed, because progress is updated right after the hook is called.

However, upon restart, there won't be any opportunity to register the actual completion of the batch, causing a skew that is proportional to the number of restarts. This impacts the time at which validation is called, which itself becomes dependent from restarts.

This PR addresses this issue by reconciling progress upon restart.

It adds tests and tightens the behavior when restarting in multiple cases, namely when checkpoints are saved:

on batch end
on batch end with validation
on epoch end
on epoch end with validation
on last
on last with validation
on exception

Before submitting

Was this discussed/agreed via a GitHub issue? (not for typos and docs)
Did you read the contributor guideline, Pull Request section?
Did you make sure your PR does only one thing, instead of bundling different changes together?
Did you make sure to update the documentation with your changes? (if necessary)
Did you write any new necessary tests? (not for typos and docs)
Did you verify new and existing tests pass locally with your changes?
Did you list all the breaking changes introduced by this pull request?
Did you update the CHANGELOG? (not for typos, docs, test updates, or minor internal changes/refactors)

PR review

Anyone in the community is welcome to review the PR.
Before you start reviewing, make sure you have read the review guidelines. In short, see the following bullet-list:

Reviewer checklist

Is this pull request ready for review? (if not, please submit in draft mode)
Check that all items from Before submitting are resolved
Make sure the title is self-explanatory and the description concisely explains the PR
Add labels and milestones (and optionally projects) to the PR so it can be classified

📚 Documentation preview 📚: https://pytorch-lightning--20379.org.readthedocs.build/en/20379/

cc @Borda

github-actions · 2024-10-31T15:18:45Z

⚡ Required checks status: All passing 🟢

Groups summary

🟢 pytorch_lightning: Tests workflow

Check ID	Status
pl-cpu (macOS-13, lightning, 3.9, 2.1, oldest)	success	✅
pl-cpu (macOS-14, lightning, 3.10, 2.1)	success	✅
pl-cpu (macOS-14, lightning, 3.11, 2.2.2)	success	✅
pl-cpu (macOS-14, lightning, 3.11, 2.3)	success	✅
pl-cpu (macOS-14, lightning, 3.12, 2.4.1)	success	✅
pl-cpu (macOS-14, lightning, 3.12, 2.5.1)	success	✅
pl-cpu (ubuntu-20.04, lightning, 3.9, 2.1, oldest)	success	✅
pl-cpu (ubuntu-20.04, lightning, 3.10, 2.1)	success	✅
pl-cpu (ubuntu-20.04, lightning, 3.11, 2.2.2)	success	✅
pl-cpu (ubuntu-20.04, lightning, 3.11, 2.3)	success	✅
pl-cpu (ubuntu-22.04, lightning, 3.12, 2.4.1)	success	✅
pl-cpu (ubuntu-22.04, lightning, 3.12, 2.5.1)	success	✅
pl-cpu (windows-2022, lightning, 3.9, 2.1, oldest)	success	✅
pl-cpu (windows-2022, lightning, 3.10, 2.1)	success	✅
pl-cpu (windows-2022, lightning, 3.11, 2.2.2)	success	✅
pl-cpu (windows-2022, lightning, 3.11, 2.3)	success	✅
pl-cpu (windows-2022, lightning, 3.12, 2.4.1)	success	✅
pl-cpu (windows-2022, lightning, 3.12, 2.5.1)	success	✅
pl-cpu (macOS-14, pytorch, 3.9, 2.1)	success	✅
pl-cpu (ubuntu-20.04, pytorch, 3.9, 2.1)	success	✅
pl-cpu (windows-2022, pytorch, 3.9, 2.1)	success	✅
pl-cpu (macOS-13, pytorch, 3.10, 2.1)	success	✅
pl-cpu (ubuntu-22.04, pytorch, 3.10, 2.1)	success	✅
pl-cpu (windows-2022, pytorch, 3.10, 2.1)	success	✅

These checks are required after the changes to src/lightning/pytorch/loops/evaluation_loop.py, src/lightning/pytorch/loops/fit_loop.py, src/lightning/pytorch/loops/loop.py, src/lightning/pytorch/loops/progress.py, src/lightning/pytorch/loops/training_epoch_loop.py, tests/tests_pytorch/loops/test_loops.py, tests/tests_pytorch/models/test_hooks.py.

🟢 pytorch_lightning: Azure GPU

Check ID	Status
pytorch-lightning (GPUs) (testing Lightning \| latest)	success	✅
pytorch-lightning (GPUs) (testing PyTorch \| latest)	success	✅

These checks are required after the changes to src/lightning/pytorch/loops/evaluation_loop.py, src/lightning/pytorch/loops/fit_loop.py, src/lightning/pytorch/loops/loop.py, src/lightning/pytorch/loops/progress.py, src/lightning/pytorch/loops/training_epoch_loop.py, tests/tests_pytorch/loops/test_loops.py, tests/tests_pytorch/models/test_hooks.py.

🟢 pytorch_lightning: Benchmarks

Check ID	Status
lightning.Benchmarks	success	✅

These checks are required after the changes to src/lightning/pytorch/loops/evaluation_loop.py, src/lightning/pytorch/loops/fit_loop.py, src/lightning/pytorch/loops/loop.py, src/lightning/pytorch/loops/progress.py, src/lightning/pytorch/loops/training_epoch_loop.py.

🟢 pytorch_lightning: Docs

Check ID	Status
docs-make (pytorch, doctest)	success	✅
docs-make (pytorch, html)	success	✅

These checks are required after the changes to src/lightning/pytorch/loops/evaluation_loop.py, src/lightning/pytorch/loops/fit_loop.py, src/lightning/pytorch/loops/loop.py, src/lightning/pytorch/loops/progress.py, src/lightning/pytorch/loops/training_epoch_loop.py.

🟢 mypy

Check ID	Status
mypy	success	✅

These checks are required after the changes to src/lightning/pytorch/loops/evaluation_loop.py, src/lightning/pytorch/loops/fit_loop.py, src/lightning/pytorch/loops/loop.py, src/lightning/pytorch/loops/progress.py, src/lightning/pytorch/loops/training_epoch_loop.py.

🟢 install

Check ID	Status
install-pkg (ubuntu-22.04, fabric, 3.9)	success	✅
install-pkg (ubuntu-22.04, fabric, 3.11)	success	✅
install-pkg (ubuntu-22.04, pytorch, 3.9)	success	✅
install-pkg (ubuntu-22.04, pytorch, 3.11)	success	✅
install-pkg (ubuntu-22.04, lightning, 3.9)	success	✅
install-pkg (ubuntu-22.04, lightning, 3.11)	success	✅
install-pkg (ubuntu-22.04, notset, 3.9)	success	✅
install-pkg (ubuntu-22.04, notset, 3.11)	success	✅
install-pkg (macOS-13, fabric, 3.9)	success	✅
install-pkg (macOS-13, fabric, 3.11)	success	✅
install-pkg (macOS-13, pytorch, 3.9)	success	✅
install-pkg (macOS-13, pytorch, 3.11)	success	✅
install-pkg (macOS-13, lightning, 3.9)	success	✅
install-pkg (macOS-13, lightning, 3.11)	success	✅
install-pkg (macOS-13, notset, 3.9)	success	✅
install-pkg (macOS-13, notset, 3.11)	success	✅
install-pkg (windows-2022, fabric, 3.9)	success	✅
install-pkg (windows-2022, fabric, 3.11)	success	✅
install-pkg (windows-2022, pytorch, 3.9)	success	✅
install-pkg (windows-2022, pytorch, 3.11)	success	✅
install-pkg (windows-2022, lightning, 3.9)	success	✅
install-pkg (windows-2022, lightning, 3.11)	success	✅
install-pkg (windows-2022, notset, 3.9)	success	✅
install-pkg (windows-2022, notset, 3.11)	success	✅

These checks are required after the changes to src/lightning/pytorch/loops/evaluation_loop.py, src/lightning/pytorch/loops/fit_loop.py, src/lightning/pytorch/loops/loop.py, src/lightning/pytorch/loops/progress.py, src/lightning/pytorch/loops/training_epoch_loop.py.

Thank you for your contribution! 💜

Note
This comment is automatically generated and updates for 60 minutes every 180 seconds. If you have any other questions, contact carmocca for help.

src/lightning/pytorch/loops/evaluation_loop.py

codecov · 2024-11-12T15:22:53Z

Codecov Report

Attention: Patch coverage is 97.20280% with 4 lines in your changes missing coverage. Please review.

Project coverage is 81%. Comparing base (61a403a) to head (8aa1b9a).
Report is 68 commits behind head on master.

❗ There is a different number of reports uploaded between BASE (61a403a) and HEAD (8aa1b9a). Click for more details.

HEAD has 102 uploads less than BASE

Flag BASE (61a403a) HEAD (8aa1b9a)

cpu 48 24

python3.10 12 6

lightning_fabric 7 0

pytest 28 2

lightning 38 19

python3.9 12 6

gpu 4 2

python3.11 12 6

python3.12 12 6

Additional details and impacted files

@@            Coverage Diff            @@
##           master   #20379     +/-   ##
=========================================
- Coverage      89%      81%     -8%     
=========================================
  Files         267      264      -3     
  Lines       23070    23147     +77     
=========================================
- Hits        20579    18739   -1840     
- Misses       2491     4408   +1917

src/lightning/pytorch/loops/fit_loop.py

…ers (Lightning-AI#20379) * Fix checkpoint progress for fit loop and batch loop * Check loss parity * Rename test * Fix validation loop handling on restart * Fix loop reset test * Avoid skipping to val end if saved mid validation * Fix type checks in compare state dicts * Fix edge cases and start from last with and without val * Clean up * Formatting * Avoid running validation when restarting from last * Fix type annotations * Fix formatting * Ensure int max_batch * Fix condition on batches that stepped * Remove expected on_train_epoch_start when restarting mid epoch

- removed `_maybe_sync_loops` after Lightning-AI/pytorch-lightning#20379 obviated the need for it

Boltzmachine · 2024-12-19T02:40:04Z

Does this also fix the same issue appearing when check_val_every_n_epoch > 1

ryxli · 2025-09-09T22:00:40Z

@lantiga

I think I may have hit an isolated edge case here and would like your thoughts.

Using the Nvidia NeMo framework which doesn’t implement a dataloader state_dict; instead, it saves state via its custom batch sampler on the LightningDataModule level:
https://github.com/NVIDIA-NeMo/NeMo/blob/547359ea1d280fb1a752f94c5c5d0486dcea9e7d/nemo/collections/llm/gpt/data/pre_training.py#L455

When resuming typically lightning warns:

/usr/local/lib/python3.12/dist-packages/lightning/pytorch/loops/training_epoch_loop.py:225: 
You're resuming from a checkpoint that ended before the epoch ended and your dataloader is not resumable. 
This can cause unreliable results if further training is done. 
Consider using an end-of-epoch checkpoint or make your dataloader resumable by implementing the `state_dict` / `load_state_dict` interface.

NeMo overrides this behavior:

*** Loaded DataModule state dict successfully. 
IGNORE PTL's warning below about the dataloader not being resumable. 
This warning is expected because we handle dataloader resumption manually in NeMo. ***

The NeMo design assumes a single-epoch use case inside Lightning, with custom logic for sampling beyond dataset size.

Here’s the edge case:

Dataset: 100 training batches total for a single epoch
Resume from checkpoint at step 60.

On resume:

self.trainer.num_training_batches == 40 (remaining batches from restored sampler).
self.batch_progress.current.completed == 60.

Because Lightning interprets num_training_batches as “epoch length,” the internal loop states reset unintentionally.
However in this case, I wouldn’t want to reset loop progress since the sampler has already advanced and not reached end of epoch

lantiga requested review from Borda, justusschock and tchaton as code owners October 31, 2024 15:18

github-actions bot added the pl Generic label for PyTorch Lightning package label Oct 31, 2024

lantiga added 7 commits November 5, 2024 18:19

Fix checkpoint progress for fit loop and batch loop

ac73938

Check loss parity

2d5576d

Rename test

0750b2e

Fix validation loop handling on restart

cbb9fb5

Fix loop reset test

7d0b5a1

Avoid skipping to val end if saved mid validation

e8bd2d7

Fix type checks in compare state dicts

0012dcb

lantiga force-pushed the luca/restart-batch-fix branch from 5e313ee to 0012dcb Compare November 6, 2024 13:39

lantiga added 3 commits November 7, 2024 18:44

Fix edge cases and start from last with and without val

e64c200

Clean up

59e41de

Formatting

c3469be

lantiga force-pushed the luca/restart-batch-fix branch from d303d27 to c3469be Compare November 8, 2024 10:39

sichu2023 mentioned this pull request Nov 8, 2024

Update NeMo/Megatron NVIDIA/bionemo-framework#302

Closed

lantiga added 3 commits November 11, 2024 20:00

Avoid running validation when restarting from last

9c58810

Fix type annotations

fae3aa5

Fix formatting

c111f25

lantiga changed the title ~~Bump completed progress on load with checkpoints saved on_train_batch_end~~ Ensure restarting from checkpoints leads to consistent internal counters Nov 11, 2024

lantiga added 3 commits November 11, 2024 20:33

Ensure int max_batch

bf6b17d

Fix condition on batches that stepped

c59ab40

Remove expected on_train_epoch_start when restarting mid epoch

9ad4200

lantiga added the ready PRs ready to be merged label Nov 12, 2024

mergify bot removed the ready PRs ready to be merged label Nov 12, 2024

Merge branch 'master' into luca/restart-batch-fix

8aa1b9a

Borda reviewed Nov 12, 2024

View reviewed changes

src/lightning/pytorch/loops/evaluation_loop.py Show resolved Hide resolved

Borda reviewed Nov 12, 2024

View reviewed changes

src/lightning/pytorch/loops/fit_loop.py Show resolved Hide resolved

Borda approved these changes Nov 12, 2024

View reviewed changes

lantiga added the ready PRs ready to be merged label Nov 12, 2024

lantiga mentioned this pull request Nov 12, 2024

Mid-epoch resume causes a single unwanted validation step (which is not a sanity check) #20288

Open

lantiga merged commit 9358898 into master Nov 13, 2024
78 of 79 checks passed

lantiga deleted the luca/restart-batch-fix branch November 13, 2024 10:51

speediedan added a commit to speediedan/finetuning-scheduler that referenced this pull request Nov 23, 2024

- bumped lightning dev sha

6b1da2d

- removed `_maybe_sync_loops` after Lightning-AI/pytorch-lightning#20379 obviated the need for it

lantiga mentioned this pull request Jan 14, 2025

Generic weight averaging callback that supports EMA #20545

Merged

12 tasks

adamreeve mentioned this pull request Mar 12, 2025

Fix OverflowError when resuming from checkpoint with an iterable dataset #20624

Merged

7 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Ensure restarting from checkpoints leads to consistent internal counters #20379

Ensure restarting from checkpoints leads to consistent internal counters #20379

Uh oh!

lantiga commented Oct 31, 2024 •

edited by github-actions bot

Loading

Uh oh!

github-actions bot commented Oct 31, 2024 •

edited

Loading

Uh oh!

Uh oh!

codecov bot commented Nov 12, 2024 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Boltzmachine commented Dec 19, 2024

Uh oh!

ryxli commented Sep 9, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Ensure restarting from checkpoints leads to consistent internal counters #20379

Ensure restarting from checkpoints leads to consistent internal counters #20379

Uh oh!

Conversation

lantiga commented Oct 31, 2024 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

PR review

Uh oh!

github-actions bot commented Oct 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚡ Required checks status: All passing 🟢

Groups summary

Uh oh!

Uh oh!

codecov bot commented Nov 12, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Boltzmachine commented Dec 19, 2024

Uh oh!

ryxli commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lantiga commented Oct 31, 2024 •

edited by github-actions bot

Loading

github-actions bot commented Oct 31, 2024 •

edited

Loading

codecov bot commented Nov 12, 2024 •

edited

Loading

ryxli commented Sep 9, 2025 •

edited

Loading