physicsnemo / rules

---
description: New model classes should start in physicsnemo/experimental/nn or physicsnemo/experimental/models during development, where backward compatibility is not guaranteed.
alwaysApply: false
---

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

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

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