Fix state_dict handling for max_iters in Engine

[TahaZahid05]

Fixes #1521

Description:
This PR builds up on #3439 to implement max_iters handling in state serialization and deserialization during Engine runs.

Key Changes:

• Engine.state_dict() now correctly exports exactly one of max_iters or max_epochs depending on which condition the Engine run was configured with.
• Reconstructed _state_dict_one_of_opt_keys to accept groups of mutually exclusive requirements, enabling Engine.load_state_dict() to cleanly accept either iteration/max_iters or epoch/max_epochs and correctly continue the engine's resume state from either.
• Added validation checks directly to Engine to prevent loading impossible future iterations while safely resuming training.
• Added local execution and Checkpointer tests that verify mutually exclusive cross-parameter resumption.

Check list:

• New tests are added (if a new feature is added)
• New doc strings: description and/or example code are in RST format
• Documentation is updated (if required)

[TahaZahid05]

@vfdev-5 done!

[vfdev-5]

Yes, it is fine, let's provide appropriate type hint for the structure

…

On Sat, Apr 11, 2026, 21:49 Taha Zahid ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In tests/ignite/base/test_mixins.py <#3729 (comment)>: > + s.load_state_dict({"a": 1, "b": 2}) + + # Test one-of optional keys - having all from one group + with pytest.raises(ValueError, match=r"should contain only one of '\('c', 'd'\)'"): + s.load_state_dict({"a": 1, "b": 2, "c": 3, "d": 4, "e": 5}) + + # Test one-of optional keys - having all from another group + with pytest.raises(ValueError, match=r"should contain only one of '\('e', 'f'\)'"): + s.load_state_dict({"a": 1, "b": 2, "c": 3, "e": 5, "f": 6}) + + # Valid state dict + s.load_state_dict({"a": 1, "b": 2, "c": 3, "e": 5}) + print("Valid state dict loaded successfully") + + +def test_empty_optional_groups(): @vfdev-5 <https://github.com/vfdev-5> If we raise error for _state_dict_one_of_opt_keys containing empty tuples then we should also change its initialization to a single tuple as well for it to pass the test? Is that fine? # _state_dict_one_of_opt_keys: tuple = ((),) _state_dict_one_of_opt_keys: tuple = () — Reply to this email directly, view it on GitHub <#3729 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AASYOH7G6AKEJFLSUMD2POL4VKOTNAVCNFSM6AAAAACXTJ6XTKVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHM2DAOJUGE2TIMZUGY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[vfdev-5]

Why we do not add it to self._state_dict_all_req_keys directly ?

[TahaZahid05]

@vfdev-5 @aaishwarymishra Won't it be BC? any existing code that relies only on epoch rather than iteration may fail?

[Copilot]

Pull request overview

This PR extends Ignite’s Engine state (de)serialization to properly support runs terminated by max_iters, including mutually-exclusive termination/progress keys and additional validation to prevent invalid resume states.

Changes:

• Update Engine.state_dict() to serialize exactly one termination key (max_epochs or max_iters) alongside progress.
• Update Serializable.load_state_dict() to validate groups of mutually exclusive optional keys (e.g., (iteration|epoch) and (max_epochs|max_iters)).
• Add/expand tests covering max_iters serialization, resumption, validation errors, and checkpointing.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
ignite/engine/engine.py	Adds max_iters serialization/deserialization support, validation helpers, and run-time handling of mutually exclusive termination params.
ignite/base/mixins.py	Changes optional-key validation to support grouped “one-of” requirements.
tests/ignite/engine/test_engine_state_dict.py	Expands integration/unit tests for max_iters state dict behavior, resume cases, and error validation.
tests/ignite/base/test_mixins.py	Adds tests for the new grouped optional-key validation logic in Serializable.load_state_dict().

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[aaishwarymishra]

If iteration is always getting included why not we just add it to _state_dict_all_req_keys