[DOC] Update v2 extension templates for forecaster API

docs/source/pkg_v2.rst

@@ -94,14 +94,14 @@ See the detailed API documentation for the available V2 Package classes below:
 .. autosummary::
    :toctree: api
 
-   models.temporal_fusion_transformer._tft_pkg_v2.TFT_pkg_v2
-   models.dlinear._dlinear_pkg_v2.DLinear_pkg_v2
-   models.samformer._samformer_v2_pkg.Samformer_pkg_v2
-   models.tide._tide_dsipts._tide_v2_pkg.TIDE_pkg_v2
-   models.timexer._timexer_pkg_v2.TimeXer_pkg_v2
-   models.xlstm._xlstm_pkg_v2.xLSTMTime_pkg_v2
-   models.mlp._decodermlp_pkg_v2.DecoderMLP_pkg_v2
-   models.softs._softs_pkg_v2.SOFTS_pkg_v2
-   models.scinet._scinet_pkg_v2.SCINet_pkg_v2
-   models.patch_tst._patch_tst_pkg_v2.PatchTST_pkg_v2
-   models.frets._frets_pkg_v2.FreTS_pkg_v2
+   models.temporal_fusion_transformer._tft_forecaster_v2.TFTForecaster
+   models.dlinear._dlinear_forecaster_v2.DLinearForecaster
+   models.samformer._samformer_forecaster_v2.SamformerForecaster
+   models.tide._tide_dsipts._tide_forecaster_v2.TIDEForecaster
+   models.timexer._timexer_forecaster_v2.TimeXerForecaster
+   models.xlstm._xlstm_forecaster_v2.xLSTMTimeForecaster
+   models.mlp._decodermlp_forecaster_v2.DecoderMLPForecaster
+   models.softs._softs_forecaster_v2.SOFTSForecaster
+   models.scinet._scinet_forecaster_v2.SCINetForecaster
+   models.patch_tst._patch_tst_forecaster_v2.PatchTSTForecaster
+   models.frets._frets_forecaster_v2.FreTSForecaster

extension_templates/metrics.py

@@ -1,4 +1,5 @@
-"""Extension Template for metrics
+"""Extension template for metrics.
+
 Purpose of this implementation template:
     quick implementation of new estimators following the template
     NOT a concrete class to import! This is NOT a base class or concrete class!
@@ -15,12 +16,9 @@
 - change docstrings for functions and the file
 - once complete: use as a local library, or contribute to pytorch-forecasting via PR
 
-Base Classes to choose from:
-Pytorch-forecasting provides different Base classes that can be used based upon what
-kind of metric is being implemented. Some supported Base Classes to choose from:
-- MultiHorizonMetric - If you want to implement point prediction metric or any genric
-    metric
-- DistributionLoss/MultivariateDistributionLoss - For DistributionLoss
+Base classes to choose from:
+- MultiHorizonMetric for point-prediction or other multi-horizon metrics.
+- DistributionLoss or MultivariateDistributionLoss for distribution losses.
 
 Mandatory methods to implement:
     loss - to calculate loss
@@ -34,19 +32,16 @@
     to_prediction - Convert network prediction into prediction as per the loss.
         Implemented if you need some special preprocessing to return the prediction
         Eg, for point prediction, we take argmax - y_pred.argmax(dim=-1)
-    to_quantile - Convert network prediction into a quantile prediction.
+    to_quantiles - Convert network prediction into quantile predictions.
         Implemented if you need some special preprocessing to return the quantile pred.
 """
 
-# todo: write an informative docstring for the file or module, remove the above
+from typing import Any
+
 import torch
-from torch import distributions
 
 from pytorch_forecasting.metrics import MultiHorizonMetric
 
-# todo: add any necessary imports here
-# import soft dependencies only inside methods of the class, not at the top of the file
-
 
 class MyMetric(MultiHorizonMetric):
     """Custom Metric.
@@ -65,57 +60,46 @@ class MyMetric(MultiHorizonMetric):
     and so on
     """
 
-    # OPTIONAL method
-    # create __init__() if you need specific args to be passed to initilialize the class
-    def __init__(self, parama, paramb, paramc):
-        # collect all the params passed to __init__() below
-        # todo: write any hyper-parameters and components to self
+    # Optional: add parameters specific to this metric.
+    def __init__(
+        self,
+        parama: Any = None,
+        paramb: str = "default",
+        paramc: Any = None,
+        **kwargs: Any,
+    ):
+        super().__init__(**kwargs)
         self.parama = parama
         self.paramb = paramb
-        # IMPORTANT: the self.params should never be overwritten or mutated from now on
-        # for handling defaults etc, write to other attributes, e.g., self._paramc
         self.paramc = paramc
-        # leave this as is
-        super().__init__()
-        # create anyother required params after this
 
-    # implement this is mandatory
-    def loss(self, paramx):
-        """loss computation.
-
-        todo: write a descriptive docstring
+    def loss(self, y_pred: torch.Tensor, target: torch.Tensor) -> torch.Tensor:
+        """Compute unreduced loss values for a batch.
 
         Parameters
         ----------
-        paramx : anytype
-          descriptive explanation of paramx
-        and so on
+        y_pred : torch.Tensor
+            Prediction tensor supplied by ``BaseModel``.
+        target : torch.Tensor
+            Target values corresponding to the model output.
+
+        Returns
+        -------
+        torch.Tensor
+            Loss values before the base metric applies masking and reduction.
         """
-        # implement the loss function
-
-    # todo implement the other optional methods if needed otherwise delete the following
-    # lines
-    # Other optional methods
-    # def rescale_parameters(self, param):
-    #     """rescale the parameter values so that the loss can be computed.
-    #     todo write docstring
-    #     """
-    #     # implement the method
+        # TODO: implement loss using the existing multi-horizon tensor contract.
+        raise NotImplementedError("Implement the metric loss.")
+
+    # Implement these only when the metric needs custom prediction conversion.
     #
-    # def map_x_to_distribution(self, x: torch.Tensor) -> distributions.Distribution:
-    #     """map x to distribution
-    #     todo write docstring
-    #     """
-    #     # implement the method
+    # def to_prediction(self, y_pred: torch.Tensor) -> torch.Tensor:
+    #     """Convert network output to a point prediction."""
     #
-    # def to_prediction(self, x: torch.Tensor) -> torch.Tensor:
-    #     """convert x to prediction
-    #     todo write docstring
-    #     """
-    #     # implement the method
+    # def to_quantiles(
+    #     self, y_pred: torch.Tensor, quantiles: list[float] | None = None
+    # ) -> torch.Tensor:
+    #     """Convert network output to quantile predictions."""
     #
-    # def to_quantile(self, x: torch.Tensor) -> torch.Tensor:
-    #     """convert x to quantile
-    #     todo write docstring
-    #     """
-    #     #implement the method
+    # DistributionLoss subclasses can additionally implement
+    # map_x_to_distribution and rescale_parameters as required by their base class.

extension_templates/v2/README.md

@@ -1,119 +1,71 @@
-# Extension Templates for PyTorch Forecasting (v2)
+# Extension templates for PyTorch Forecasting v2
 
-This folder contains implementation templates for quick implementation of new estimators and data modules.
-**These are NOT base classes or concrete classes to import. They are "fill-in" coding templates.**
+These are copy-and-adapt templates, not importable implementations. Start with
+`model.py` and `model_forecaster.py`; use the data-module and dataset templates only
+when no existing data module provides the inputs your model needs. The metrics
+template is a separate example for adding a metric.
 
-**How to use:**
-Make a copy of the template in a suitable location, give it a descriptive name, and fill in the mandatory methods designated by "todo" comments.
+## Model and forecaster
 
----
+`MyModel` in `model.py` contains the network and implements `forward`. Its `_pkg()`
+method returns the associated forecaster class, `MyModelForecaster`; it no longer
+returns a separate model-package class.
 
-## Architecture Overview
+`MyModelForecaster` in `model_forecaster.py` inherits from `BaseForecaster`. It:
 
-The v2 architecture strictly separates ML logic from framework metadata to allow lazy loading and lower memory footprints.
+- returns the model class from `get_cls()`;
+- returns a compatible concrete data-module class from `get_datamodule_cls()`;
+- maps forecaster parameters to model constructor arguments in `get_model_params()`;
+- accepts optional trainer, configured data module, and checkpoint arguments using
+  the `BaseForecaster` constructor contract.
 
-### 1. Model and Package (`model.py` and `model_pkg.py`)
+The forecaster owns the high-level `fit` and `predict` workflow. Both operate on the
+public `TimeSeries` data object. Use `TimeSeries` from `pytorch_forecasting.data` to
+wrap input data; this template set does not include a separate raw-data/TimeSeries
+template.
 
-* **Model Class (`MyModel`)**: Contains the PyTorch neural network, forward passes, and training logic.
-* **Package Class (`MyModel_pkg`)**: Contains metadata, tags, capabilities, and test parameters.
-* **Connection**:
-* `MyModel._pkg()` returns the package class.
-* `MyModel_pkg.get_cls()` returns the model class.
+## Custom data module
 
+Prefer an existing compatible class from `pytorch_forecasting.data.data_module`.
+`EncoderDecoderTimeSeriesDataModule` is used as the concrete example in
+`model_forecaster.py`; select a class whose batch keys and target format match your
+model's `forward`.
 
+When a custom module is needed, subclass `BaseTimeSeriesDataModule`, not
+`LightningDataModule` directly. The base class owns data attachment with `with_data`,
+metadata access, split setup, and dataloader creation. Implement its data-format hooks:
+`_prepare_metadata`, `_preprocess_data`, `_create_windows`, `_build_dataset`, and the
+static `collate_fn`. Override the constructor only to add configuration, and pass
+`time_series` and supported base options to `super().__init__`.
 
-### 2. Data Module and Dataset (`data_module.py` and `_dataset.py`)
+The private dataset should implement `__len__` and `__getitem__`. Each item is an
+`(x, y)` pair; collation turns these into the batch consumed by the model and its loss.
+Follow the signatures and tensor format expected by the selected base module and model.
 
-* **Data Module**: Manages the ML pipeline setup, data splits, and dataset metadata extraction. Inherits from `LightningDataModule`.
-* **Dataset**: Private PyTorch `Dataset` that handles `__getitem__` logic for the dataloaders.
+## Metrics
 
----
+`extension_templates/metrics.py` demonstrates a `MultiHorizonMetric`. Its loss receives
+the prediction tensor extracted from the model output and the target tensor; the base
+metric handles masking and reduction. Keep the existing metric tensor contract.
+Distribution metrics should use the relevant `DistributionLoss` base class and
+implement its distribution-specific hooks as needed.
 
-## Implementing a New Model
+## Validate an extension
 
-Copy `model.py` and `model_pkg.py` to your target directory.
-
-### Package Configuration (`model_pkg.py`)
-
-Inherits from `Base_pkg`. Implement the following:
-
-**Tags (`_tags`):**
-Dictionary defining framework integration rules. Tags are inherited from parent class if they are not set.
-
-- `info:name` (human-readable model name matching the class)
-- `info:pred_type` (prediction types: e.g. `["point"]`, `["quantile"]`, `["distr"]`)
-- `info:y_type` (target type: e.g. `["numeric"]`, `["category"]`)
-- `info:compute` (integer representing compute intensity, 1 to 5)
-- `authors` (GitHub username list)
-- `python_dependencies` (list of external packages if needed)
-- `capability:exogenous` (bool: whether model supports exogenous variables)
-- `capability:multivariate` (bool: whether model supports multivariate targets)
-- `capability:pred_int` (bool: whether model supports prediction intervals)
-- `capability:flexible_history_length` (bool: whether model works with variable-length history)
-- `capability:cold_start` (bool: whether model makes predictions with little/no history)
-
-**Mandatory Methods:**
-
-* `get_cls()`: Imports and returns `MyModel`.
-* `get_datamodule_cls()`: Imports and returns the compatible PyTorch Forecasting datamodule.
-  * **Determining compatibility:** Inspect the available classes in the [`pytorch_forecasting.data.data_module`](https://github.com/sktime/pytorch-forecasting/tree/main/pytorch_forecasting/data/data_module) directory. Select the data module that handles the data structures and outputs the tensor keys your model's forward pass expects. Every model must link to at least one compatible data module class.
-  * If there is no data module that serves your purpose for your model, you might need to implement a new data module. Please look at [Implementing a New Data Module](https://github.com/sktime/pytorch-forecasting/tree/main/extension_templates/v2/README.md#implementing-a-new-data-module) for more info.
-* `get_test_train_params()`: Returns a list of dicts for CI testing. The first element must be an empty dict `{}` to test defaults. Ensure test configurations yield low-compute models to prevent timeouts.
-
-### Model Configuration (`model.py`)
-
-Inherits from `BaseModel`. Implement the following:
-
-**Mandatory Methods:**
-
-* `__init__()`: Initialize network components. Must call `self.save_hyperparameters()` and `super().__init__()`.
-* `_pkg()`: Class method that imports and returns `MyModel_pkg`.
-* `forward(x: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]`: PyTorch forward pass.
-
----
-
-## Implementing a New Data Module
-
-#### When to Implement a Custom Data Module
-Do not create a new data module if an existing one in [`pytorch_forecasting.data.data_module`](https://github.com/sktime/pytorch-forecasting/tree/main/pytorch_forecasting/data/data_module) can format your data into the required inputs.
-Implement a custom data module only when your model requires:
-
-* Unique data structures or non-standard time-series features that existing modules cannot parse.
-* Custom metadata preparation steps (`_prepare_metadata`) to configure model architecture shapes.
-* Specialized sample-level preprocessing logic (`_preprocess_data`) or batch-collating mechanisms.
-
-If needed, copy data_module.py and _dataset.py to your target directory.
-
-### Data Module (`data_module.py`)
-
-Inherits from `LightningDataModule`. Implement the following:
-
-**Mandatory Methods:**
-
-* `_prepare_metadata()`: Derives the metadata required for model initialization from the raw data/parameters.
-* `metadata`: Property that returns `_metadata`, invoking `_prepare_metadata()` if null.
-* `_preprocess_data(series_idx)`: Contains logic to transform raw series before dataset consumption.
-* `setup(stage: str)`: Standard Lightning method to instantiate train/val/test splits.
-
-### Dataset (`_dataset.py`)
-
-Inherits from `torch.utils.data.Dataset`. Implement the following:
-
-**Mandatory Methods:**
-
-* `__init__(data_module, ...)`: Accepts the parent Data Module to read preprocessed data and states.
-* `__getitem__(idx)`: Returns the processed item dict exactly as required by the model's `forward` pass.
-
----
-
-## Interface Verification
-
-Ensure standard compatibility by running the builtin checks after implementation:
+Implement test parameters for the forecaster and keep default configurations small.
+After placing the model in an importable package and registering its forecaster, run
+the v2 estimator suite and the generic estimator checks:
 
 ```python
-from pytorch_forecasting.utils._estimator_checks import check_estimator
-from pytorch_forecasting.models,my_model import MyModel
+from pytorch_forecasting.utils import check_estimator
+from my_package.model import MyModel
 
 check_estimator(MyModel)
+```
 
+```powershell
+python -m pytest pytorch_forecasting/tests/test_all_v2/test_all_estimators_v2.py
 ```
+
+Use the v2 integration tests as a guide for fitting, prediction modes, and checkpoint
+round trips. These templates do not change the tensor-shape contract.