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: ***@***.***>