[FEAT] Add XLinear (#1445)

Co-authored-by: elephaint <osprangers@gmail.com>

Author: marcopeix

docs/mintlify/docs.json

@@ -120,7 +120,8 @@
               "models.timexer.html",
               "models.tsmixer.html",
               "models.tsmixerx.html",
-              "models.vanillatransformer.html"
+              "models.vanillatransformer.html",
+              "models.xlinear.html"
             ]
           },
           "models.html",

docs/mintlify/imgs_models/xlinear.png

@@ -0,0 +1,76 @@
+---
+description: >-
+  XLinear: A MLP-based model for multivariate forecasting with exogenous features.
+output-file: models.xlinear.html
+title: XLinear
+---
+
+XLinear is a MLP-based model for multivariate time series forecasting
+that uses gating mechanisms for temporal and cross-channel interactions.
+The architecture consists of temporal gating with a global token to capture
+global temporal patterns, followed by cross-channel gating to model
+dependencies between different time series.
+
+**References**
+
+- [Xinyang, C., et al. "XLinear: A Lightweight and Accurate MLP-Based Model for Long-Term Time Series Forecasting with Exogenous Inputs"](https://arxiv.org/abs/2601.09237)
+
+![Figure 1. Architecture of XLinear](imgs_models/xlinear.png)
+*Figure 1. Architecture of XLinear*
+
+## XLinear
+
+::: neuralforecast.models.xlinear.XLinear
+    options:
+      members:
+        - fit
+        - predict
+      heading_level: 3
+
+### Usage Example
+
+
+```python
+import pandas as pd
+import matplotlib.pyplot as plt
+
+from neuralforecast import NeuralForecast
+from neuralforecast.models import XLinear
+from neuralforecast.losses.pytorch import MAE
+from neuralforecast.utils import AirPassengersPanel, AirPassengersStatic
+
+Y_train_df = AirPassengersPanel[AirPassengersPanel.ds<AirPassengersPanel['ds'].values[-12]] # 132 train
+Y_test_df = AirPassengersPanel[AirPassengersPanel.ds>=AirPassengersPanel['ds'].values[-12]].reset_index(drop=True) # 12 test
+
+model = XLinear(h=12, 
+            input_size=24,
+            n_series=2,
+            stat_exog_list=['airline1'],
+            hist_exog_list=["y_[lag12]"],
+            futr_exog_list=['trend'],            
+            loss = MAE(),
+            scaler_type='robust',
+            learning_rate=1e-3,
+            max_steps=200,
+            val_check_steps=10,
+            early_stop_patience_steps=2)
+
+fcst = NeuralForecast(
+    models=[model],
+    freq='ME'
+)
+fcst.fit(df=Y_train_df, static_df=AirPassengersStatic, val_size=12)
+forecasts = fcst.predict(futr_df=Y_test_df)
+
+# Plot predictions
+Y_hat_df = forecasts.reset_index(drop=False).drop(columns=['unique_id','ds'])
+plot_df = pd.concat([Y_test_df, Y_hat_df], axis=1)
+plot_df = pd.concat([Y_train_df, plot_df])
+
+plot_df = plot_df[plot_df.unique_id=='Airline1'].drop('unique_id', axis=1)
+plt.plot(plot_df['ds'], plot_df['y'], c='black', label='True')
+plt.plot(plot_df['ds'], plot_df['XLinear'], c='blue', label='median')
+plt.grid()
+plt.legend()
+plt.plot()
+```

docs/models.xlinear.html.md

@@ -48,6 +48,7 @@
     "|`TSMixer` | `AutoTSMixer` | MLP | Multivariate | Direct  | - | \n",
     "|`TSMixerx` | `AutoTSMixerx` | MLP | Multivariate | Direct  | F/H/S | \n",
     "|`VanillaTransformer` | `AutoVanillaTransformer` | Transformer | Univariate | Direct  | F | \n",
+    "|`XLinear` | `AutoXLinear` | MLP | Multivariate| Direct | F/H/S |\n",
     "|`xLSTM` | `AutoxLSTM` | mLSTM | Univariate | Direct  | F/H/S | \n",
     "\n",
     "\n",

nbs/docs/capabilities/overview.ipynb

@@ -5,7 +5,7 @@
            'AutoNBEATS', 'AutoNBEATSx', 'AutoNHITS', 'AutoDLinear', 'AutoNLinear', 'AutoTiDE', 'AutoDeepNPTS',
            'AutoKAN', 'AutoTFT', 'AutoVanillaTransformer', 'AutoInformer', 'AutoAutoformer', 'AutoFEDformer',
            'AutoPatchTST', 'AutoiTransformer', 'AutoTimeXer', 'AutoTimesNet', 'AutoStemGNN', 'AutoHINT', 'AutoTSMixer',
-           'AutoTSMixerx', 'AutoMLPMultivariate', 'AutoSOFTS', 'AutoTimeMixer', 'AutoRMoK']
+           'AutoTSMixerx', 'AutoMLPMultivariate', 'AutoSOFTS', 'AutoTimeMixer', 'AutoRMoK', 'AutoXLinear']
 
 
 from os import cpu_count
@@ -50,6 +50,7 @@
 from .models.tsmixerx import TSMixerx
 from .models.vanillatransformer import VanillaTransformer
 from .models.xlstm import xLSTM
+from .models.xlinear import XLinear
 
 
 class AutoRNN(BaseAuto):
@@ -2556,3 +2557,88 @@ def get_default_config(cls, h, backend, n_series):
             config = cls._ray_config_to_optuna(config)
 
         return config
+
+
+class AutoXLinear(BaseAuto):
+
+    default_config = {
+        "input_size_multiplier": [1, 2, 3, 4, 5],
+        "h": None,
+        "n_series": None,
+        "hidden_size": tune.choice([64, 128, 256]),
+        "use_norm": tune.choice([True, False]),
+        "learning_rate": tune.loguniform(1e-4, 1e-1),
+        "scaler_type": tune.choice([None, "robust", "standard"]),
+        "max_steps": tune.choice([500, 1000]),
+        "batch_size": tune.choice([32, 64, 128, 256]),
+        "loss": None,
+        "random_seed": tune.randint(1, 20),
+    }
+
+    def __init__(
+        self,
+        h,
+        n_series,
+        loss=MAE(),
+        valid_loss=None,
+        config=None,
+        search_alg=BasicVariantGenerator(random_state=1),
+        num_samples=10,
+        refit_with_val=False,
+        cpus=cpu_count(),
+        gpus=torch.cuda.device_count(),
+        verbose=False,
+        alias=None,
+        backend="ray",
+        callbacks=None,
+    ):
+
+        # Define search space, input/output sizes
+        if config is None:
+            config = self.get_default_config(h=h, backend=backend, n_series=n_series)
+
+        # Always use n_series from parameters, raise exception with Optuna because we can't enforce it
+        if backend == "ray":
+            config["n_series"] = n_series
+        elif backend == "optuna":
+            mock_trial = MockTrial()
+            if (
+                "n_series" in config(mock_trial)
+                and config(mock_trial)["n_series"] != n_series
+            ) or ("n_series" not in config(mock_trial)):
+                raise Exception(f"config needs 'n_series': {n_series}")
+
+        super(AutoXLinear, self).__init__(
+            cls_model=XLinear,
+            h=h,
+            loss=loss,
+            valid_loss=valid_loss,
+            config=config,
+            search_alg=search_alg,
+            num_samples=num_samples,
+            refit_with_val=refit_with_val,
+            cpus=cpus,
+            gpus=gpus,
+            verbose=verbose,
+            alias=alias,
+            backend=backend,
+            callbacks=callbacks,
+        )
+
+    @classmethod
+    def get_default_config(cls, h, backend, n_series):
+        config = cls.default_config.copy()
+        config["input_size"] = tune.choice(
+            [h * x for x in config["input_size_multiplier"]]
+        )
+
+        # Rolling windows with step_size=1 or step_size=h
+        # See `BaseWindows` and `BaseRNN`'s create_windows
+        config["step_size"] = tune.choice([1, h])
+        del config["input_size_multiplier"]
+        if backend == "optuna":
+            # Always use n_series from parameters
+            config["n_series"] = n_series
+            config = cls._ray_config_to_optuna(config)
+
+        return config

neuralforecast/auto.py

@@ -3,7 +3,7 @@
            'TFT', 'VanillaTransformer', 'Informer', 'Autoformer', 'PatchTST', 'FEDformer',
            'StemGNN', 'HINT', 'TimesNet', 'TimeLLM', 'TSMixer', 'TSMixerx', 'MLPMultivariate',
            'iTransformer', 'BiTCN', 'TiDE', 'DeepNPTS', 'SOFTS', 'TimeMixer', 'KAN', 'RMoK',
-           'TimeXer', 'xLSTM'
+           'TimeXer', 'xLSTM', 'XLinear'
            ]
 
 from .rnn import RNN
@@ -41,3 +41,4 @@
 from .rmok import RMoK
 from .timexer import TimeXer
 from .xlstm import xLSTM
+from .xlinear import XLinear