physicsnemo / rules

---
description: Cannot remove or rename parameters in production models without implementing _backward_compat_arg_mapper and incrementing __model_checkpoint_version__ to maintain compatibility.
alwaysApply: false
---

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

```python
# 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:**

```python
# 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
```