mod-002a-experimental-models-belong-in-experimental

When creating new model or layer classes, rule MOD-002a must be followed. Explicitly reference "Following rule MOD-002a, which states that new models should start in physicsnemo/experimental/..." when explaining where to place new code.

MOD-002a: New models and layers belong in physicsnemo.experimental

Description:

For the vast majority of models, new classes are created either in physicsnemo/experimental/nn for reusable layers, or in physicsnemo/experimental/models for more complete models. The experimental folder is used to store models that are still under development (beta or alpha releases) during this stage, backward compatibility is not guaranteed.

One exception is when the developer is highly confident that the model is sufficiently mature and applicable to many domains or use cases. In this case the model class can be created in the physicsnemo/nn or physicsnemo/models folders directly, and backward compatibility is guaranteed.

Another exception is when the model class is highly specific to a single example. In this case, it may be acceptable to place it in a module specific to the example code, such as examples/<example_name>/utils/nn.py.

After staying in experimental for a sufficient amount of time (typically at least 1 release cycle), the model class can be promoted to production. It is then moved to the physicsnemo/nn or physicsnemo/models folders, based on whether it's a reusable layer or complete model (see MOD-000a and MOD-000b).

Note: Per MOD-008a, MOD-008b, and MOD-008c, it is forbidden to move a model out of the experimental stage/directory without the required CI tests.

Rationale:

The experimental stage allows rapid iteration without backward compatibility constraints, enabling developers to refine APIs based on user feedback. This protects users from unstable APIs while allowing innovation.

Example:

# Good: Stage 1 - New experimental model
# File: physicsnemo/experimental/models/new_diffusion.py
class DiffusionModel(Module):
    """New diffusion model under active development. API may change."""
    pass

# Good: After 1+ release cycles, promoted to production
# File: physicsnemo/models/diffusion.py (moved from experimental/)
class DiffusionModel(Module):
    """Stable diffusion model with backward compatibility guarantees."""
    pass

Anti-pattern:

# WRONG: New model directly in production folder
# File: physicsnemo/models/brand_new_model.py (should be in experimental/ first)
class BrandNewModel(Module):
    """Skipped experimental stage - risky for stability"""
    pass