mod-002b-add-deprecation-warnings-to-model

When deprecating a model class, rule MOD-002b must be followed. Explicitly reference "Following rule MOD-002b, which requires adding deprecation warnings to both docstring and runtime..." when implementing deprecation.

MOD-002b: Add deprecation warnings to deprecating model class

Description:

For a model class in the pre-deprecation stage in physicsnemo/nn or physicsnemo/models, the developer should start planning its deprecation. This is done by adding a warning message to the model class, indicating that the model class is deprecated and will be removed in a future release.

The warning message should be a clear and concise message that explains why the model class is being deprecated and what the user should do instead. The deprecation message should be added to both the docstring and should be raised at runtime. The developer is free to choose the mechanism to raise the deprecation warning.

A model class cannot be deprecated without staying in the pre-deprecation stage for at least 1 release cycle before it can be deleted from the codebase.

Rationale:

Ensures users have sufficient time to migrate to newer alternatives, preventing breaking changes that could disrupt their workflows. This graduated approach balances innovation with stability, a critical requirement for a scientific computing framework.

Example:

# Good: Pre-deprecation with warning
# File: physicsnemo/models/old_diffusion.py
class DiffusionModel(Module):
    """
    Legacy diffusion model.

    .. deprecated:: 0.5.0
        ``OldDiffusionModel`` is deprecated and will be removed in version 0.7.0.
        Use :class:`~physicsnemo.models.NewDiffusionModel` instead.
    """
    def __init__(self):
        import warnings
        warnings.warn(
            "OldDiffusionModel is deprecated. Use NewDiffusionModel instead.",
            DeprecationWarning,
            stacklevel=2
        )
        super().__init__()

Anti-pattern:

# WRONG: No deprecation warning in code
# File: physicsnemo/models/old_model.py
class OldModel(Module):
    """Will be removed next release."""  # Docstring mentions it but no runtime warning
    def __init__(self):
        # Missing: warnings.warn(..., DeprecationWarning)
        super().__init__()

# WRONG: Deprecation without sufficient warning period
# (Model deprecated and removed in same release)