mod-007b-cannot-remove-or-rename-parameters-without-compat-mapper

When removing or renaming parameters in production models, rule MOD-007b must be strictly followed. Explicitly reference "Following rule MOD-007b, which requires _backward_compat_arg_mapper for parameter changes..." when modifying model signatures.

MOD-007b: Cannot remove or rename parameters without compat mapper

Description:

For any model in physicsnemo/nn or physicsnemo/models, removing or renaming parameters is strictly forbidden without proper backward compatibility support.

If a parameter must be renamed or removed, the developer must:

1. Increment __model_checkpoint_version__
2. Add the old version to __supported_model_checkpoint_version__ dict
3. Implement _backward_compat_arg_mapper classmethod to handle the mapping
4. Maintain support for the old API for at least 2 release cycles

Rationale:

Removing or renaming parameters breaks existing checkpoints and user code. Proper version management and argument mapping ensures old checkpoints can still be loaded and users have time to migrate to the new API.

Example:

# Good: Proper backward compatibility for parameter rename
class MyModel(Module):
    __model_checkpoint_version__ = "2.0"
    __supported_model_checkpoint_version__ = {
        "1.0": (
            "Loading checkpoint from version 1.0 (current is 2.0). "
            "Parameter 'hidden_dim' renamed to 'hidden_size'."
        )
    }

    @classmethod
    def _backward_compat_arg_mapper(
        cls, version: str, args: Dict[str, Any]
    ) -> Dict[str, Any]:
        """Map arguments from older versions."""
        args = super()._backward_compat_arg_mapper(version, args)

        if version == "1.0":
            # Map old parameter name to new name
            if "hidden_dim" in args:
                args["hidden_size"] = args.pop("hidden_dim")

            # Remove deprecated parameters
            if "legacy_param" in args:
                _ = args.pop("legacy_param")

        return args

    def __init__(
        self,
        input_dim: int,
        hidden_size: int = 128,  # Renamed from 'hidden_dim'
    ):
        super().__init__(meta=MyModelMetaData())

Anti-pattern:

# WRONG: Renaming without backward compat
class MyModel(Module):
    __model_checkpoint_version__ = "2.0"
    # Missing: __supported_model_checkpoint_version__ and _backward_compat_arg_mapper

    def __init__(self, input_dim: int, hidden_size: int):  # Renamed!
        super().__init__(meta=MyModelMetaData())
        # WRONG: Old checkpoints with 'hidden_dim' will fail!

# WRONG: Not calling super() in mapper
class MyModel(Module):
    @classmethod
    def _backward_compat_arg_mapper(cls, version: str, args: Dict[str, Any]) -> Dict[str, Any]:
        # WRONG: Missing super()._backward_compat_arg_mapper(version, args)
        if "hidden_dim" in args:
            args["hidden_size"] = args.pop("hidden_dim")
        return args