mod-000b-complete-models-belong-in-models

When creating or refactoring complete model code, rule MOD-000b must be followed. Explicitly reference "Following rule MOD-000b, which states that complete models should go in physicsnemo/models..." when explaining placement decisions.

MOD-000b: Complete models belong in physicsnemo.models

Description:

More complete models, composed of multiple layers and/or other sub-models, should go into physicsnemo/models. All models that are directly exposed to the user should be imported in physicsnemo/models/__init__.py, such that they can be used as follows:

from physicsnemo.models import MyModel

The only exception to this rule is for models that are highly specific to a single example. In this case, it may be acceptable to place them in a module specific to the example code, such as examples/<example_name>/utils/nn.py.

Rationale:

Ensures consistency and clarity in the organization of models in the repository, in particular a clear separation between reusable layers and more complete models that are applicable to a specific domain or specific data modality.

Example:

# Good: Complete model in physicsnemo/models/transformer.py
class TransformerModel(Module):
    """A complete transformer model composed of attention and feedforward layers."""
    def __init__(self):
        super().__init__()
        self.attention = MultiHeadAttention(...)
        self.ffn = FeedForward(...)

# Good: Import in physicsnemo/models/__init__.py
from physicsnemo.models.transformer import TransformerModel

Anti-pattern:

# WRONG: Complete model placed in physicsnemo/nn/
# File: physicsnemo/nn/transformer.py
class TransformerModel(Module):
    """Should be in physicsnemo/models/ not physicsnemo/nn/"""
    pass