docstr: PyTorch Lightning-based Forecasting Module.
  
  This class is meant to be inherited to create a new PyTorch Lightning-based forecasting module.
  When subclassing this class, please make sure to add the following methods with the given signatures:
      - :func:`PLTorchForecastingModel.__init__()`
      - :func:`PLTorchForecastingModel.forward()`
      - :func:`PLTorchForecastingModel._produce_train_output()`
      - :func:`PLTorchForecastingModel._get_batch_prediction()`
  
  In subclass `MyModel`'s :func:`__init__` function call ``super(MyModel, self).__init__(**kwargs)`` where
  ``kwargs`` are the parameters of :class:`PLTorchForecastingModel`.
  
  Parameters
  ----------
  input_chunk_length
      Number of time steps in the past to take as a model input (per chunk). Applies to the target
      series, and past and/or future covariates (if the model supports it).
  output_chunk_length
      Number of time steps predicted at once (per chunk) by the internal model. Also, the number of future values
      from future covariates to use as a model input (if the model supports future covariates). It is not the same
      as forecast horizon `n` used in `predict()`, which is the desired number of prediction points generated
      using either a one-shot- or auto-regressive forecast. Setting `n <= output_chunk_length` prevents
      auto-regression. This is useful when the covariates don't extend far enough into the future, or to prohibit
      the model from using future values of past and / or future covariates for prediction (depending on the
      model's covariate support).
  train_sample_shape
      Shape of the model's input, used to instantiate model without calling ``fit_from_dataset`` and
      perform sanity check on new training/inference datasets used for re-training or prediction.
  loss_fn
      PyTorch loss function used for training.
      This parameter will be ignored for probabilistic models if the ``likelihood`` parameter is specified.
      Default: ``torch.nn.MSELoss()``.
  torch_metrics
      A torch metric or a ``MetricCollection`` used for evaluation. A full list of available metrics can be found
      at https://torchmetrics.readthedocs.io/en/latest/. Default: ``None``.
  likelihood
      One of Darts' :meth:`Likelihood <darts.utils.likelihood_models.Likelihood>` models to be used for
      probabilistic forecasts. Default: ``None``.
  optimizer_cls
      The PyTorch optimizer class to be used. Default: ``torch.optim.Adam``.
  optimizer_kwargs
      Optionally, some keyword arguments for the PyTorch optimizer (e.g., ``{'lr': 1e-3}``
      for specifying a learning rate). Otherwise the default values of the selected ``optimizer_cls``
      will be used. Default: ``None``.
  lr_scheduler_cls
      Optionally, the PyTorch learning rate scheduler class to be used. Specifying ``None`` corresponds
      to using a constant learning rate. Default: ``None``.
  lr_scheduler_kwargs
      Optionally, some keyword arguments for the PyTorch learning rate scheduler. Default: ``None``.
  use_reversible_instance_norm
      Whether to use reversible instance normalization `RINorm` against distribution shift as shown in [1]_.
      It is only applied to the features of the target series and not the covariates.
  
  References
  ----------
  .. [1] T. Kim et al. "Reversible Instance Normalization for Accurate Time-Series Forecasting against
          Distribution Shift", https://openreview.net/forum?id=cGDAkQo1C0p
docstr_tok: ["PyTorch","Lightning-based","Forecasting","Module",".","This","class","is","meant","to","be","inherited","to","create","a","new","PyTorch","Lightning-based","forecasting","module",".","When","subclassing","this","class",",","please","make","sure","to","add","the","following","methods","with","the","given","signatures",":","-",":","func",":","`","PLTorchForecastingModel.__init__","(",")","`","-",":","func",":","`","PLTorchForecastingModel.forward","(",")","`","-",":","func",":","`","PLTorchForecastingModel._produce_train_output","(",")","`","-",":","func",":","`","PLTorchForecastingModel._get_batch_prediction","(",")","`","In","subclass","`","MyModel","`","'s",":","func",":","`","__init__","`","function","call","``","super","(","MyModel",",","self",")",".__init__","(","*","*","kwargs",")","``","where","``","kwargs","``","are","the","parameters","of",":","class",":","`","PLTorchForecastingModel","`",".","Parameters","--","--","--","--","--","input_chunk_length","Number","of","time","steps","in","the","past","to","take","as","a","model","input","(","per","chunk",")",".","Applies","to","the","target","series",",","and","past","and\/or","future","covariates","(","if","the","model","supports","it",")",".","output_chunk_length","Number","of","time","steps","predicted","at","once","(","per","chunk",")","by","the","internal","model",".","Also",",","the","number","of","future","values","from","future","covariates","to","use","as","a","model","input","(","if","the","model","supports","future","covariates",")",".","It","is","not","the","same","as","forecast","horizon","`","n","`","used","in","`","predict","(",")","`",",","which","is","the","desired","number","of","prediction","points","generated","using","either","a","one-shot-","or","auto-regressive","forecast",".","Setting","`","n","<","=","output_chunk_length","`","prevents","auto-regression",".","This","is","useful","when","the","covariates","do","n't","extend","far","enough","into","the","future",",","or","to","prohibit","the","model","from","using","future","values","of","past","and","\/","or","future","covariates","for","prediction","(","depending","on","the","model","'s","covariate","support",")",".","train_sample_shape","Shape","of","the","model","'s","input",",","used","to","instantiate","model","without","calling","``","fit_from_dataset","``","and","perform","sanity","check","on","new","training\/inference","datasets","used","for","re-training","or","prediction",".","loss_fn","PyTorch","loss","function","used","for","training",".","This","parameter","will","be","ignored","for","probabilistic","models","if","the","``","likelihood","``","parameter","is","specified",".","Default",":","``","torch.nn.MSELoss","(",")","``",".","torch_metrics","A","torch","metric","or","a","``","MetricCollection","``","used","for","evaluation",".","A","full","list","of","available","metrics","can","be","found","at","https",":","\/\/torchmetrics.readthedocs.io\/en\/latest\/",".","Default",":","``","None","``",".","likelihood","One","of","Darts","'",":","meth",":","`","Likelihood","<","darts.utils.likelihood_models.Likelihood",">","`","models","to","be","used","for","probabilistic","forecasts",".","Default",":","``","None","``",".","optimizer_cls","The","PyTorch","optimizer","class","to","be","used",".","Default",":","``","torch.optim.Adam","``",".","optimizer_kwargs","Optionally",",","some","keyword","arguments","for","the","PyTorch","optimizer","(","e.g.",",","``","{","'lr","'",":","1e-3","}","``","for","specifying","a","learning","rate",")",".","Otherwise","the","default","values","of","the","selected","``","optimizer_cls","``","will","be","used",".","Default",":","``","None","``",".","lr_scheduler_cls","Optionally",",","the","PyTorch","learning","rate","scheduler","class","to","be","used",".","Specifying","``","None","``","corresponds","to","using","a","constant","learning","rate",".","Default",":","``","None","``",".","lr_scheduler_kwargs","Optionally",",","some","keyword","arguments","for","the","PyTorch","learning","rate","scheduler",".","Default",":","``","None","``",".","use_reversible_instance_norm","Whether","to","use","reversible","instance","normalization","`","RINorm","`","against","distribution","shift","as","shown","in","[","1","]","_",".","It","is","only","applied","to","the","features","of","the","target","series","and","not","the","covariates",".","References","--","--","--","--","--","..","[","1","]","T.","Kim","et","al",".","``","Reversible","Instance","Normalization","for","Accurate","Time-Series","Forecasting","against","Distribution","Shift","''",",","https",":","\/\/openreview.net\/forum","?","id=cGDAkQo1C0p"]
code: def __init__(
      self,
      input_chunk_length: int,
      output_chunk_length: int,
      train_sample_shape: Optional[Tuple] = None,
      loss_fn: nn.modules.loss._Loss = nn.MSELoss(),
      torch_metrics: Optional[
          Union[torchmetrics.Metric, torchmetrics.MetricCollection]
      ] = None,
      likelihood: Optional[Likelihood] = None,
      optimizer_cls: torch.optim.Optimizer = torch.optim.Adam,
      optimizer_kwargs: Optional[Dict] = None,
      lr_scheduler_cls: Optional[
          torch.optim.lr_scheduler._LRScheduler
      ] = None,
      lr_scheduler_kwargs: Optional[Dict] = None,
      use_reversible_instance_norm: bool = False,
  ) -> None:
      """
      PyTorch Lightning-based Forecasting Module.
  
      This class is meant to be inherited to create a new PyTorch Lightning-based forecasting module.
      When subclassing this class, please make sure to add the following methods with the given signatures:
          - :func:`PLTorchForecastingModel.__init__()`
          - :func:`PLTorchForecastingModel.forward()`
          - :func:`PLTorchForecastingModel._produce_train_output()`
          - :func:`PLTorchForecastingModel._get_batch_prediction()`
  
      In subclass `MyModel`'s :func:`__init__` function call ``super(MyModel, self).__init__(**kwargs)`` where
      ``kwargs`` are the parameters of :class:`PLTorchForecastingModel`.
  
      Parameters
      ----------
      input_chunk_length
          Number of time steps in the past to take as a model input (per chunk). Applies to the target
          series, and past and/or future covariates (if the model supports it).
      output_chunk_length
          Number of time steps predicted at once (per chunk) by the internal model. Also, the number of future values
          from future covariates to use as a model input (if the model supports future covariates). It is not the same
          as forecast horizon `n` used in `predict()`, which is the desired number of prediction points generated
          using either a one-shot- or auto-regressive forecast. Setting `n <= output_chunk_length` prevents
          auto-regression. This is useful when the covariates don't extend far enough into the future, or to prohibit
          the model from using future values of past and / or future covariates for prediction (depending on the
          model's covariate support).
      train_sample_shape
          Shape of the model's input, used to instantiate model without calling ``fit_from_dataset`` and
          perform sanity check on new training/inference datasets used for re-training or prediction.
      loss_fn
          PyTorch loss function used for training.
          This parameter will be ignored for probabilistic models if the ``likelihood`` parameter is specified.
          Default: ``torch.nn.MSELoss()``.
      torch_metrics
          A torch metric or a ``MetricCollection`` used for evaluation. A full list of available metrics can be found
          at https://torchmetrics.readthedocs.io/en/latest/. Default: ``None``.
      likelihood
          One of Darts' :meth:`Likelihood <darts.utils.likelihood_models.Likelihood>` models to be used for
          probabilistic forecasts. Default: ``None``.
      optimizer_cls
          The PyTorch optimizer class to be used. Default: ``torch.optim.Adam``.
      optimizer_kwargs
          Optionally, some keyword arguments for the PyTorch optimizer (e.g., ``{'lr': 1e-3}``
          for specifying a learning rate). Otherwise the default values of the selected ``optimizer_cls``
          will be used. Default: ``None``.
      lr_scheduler_cls
          Optionally, the PyTorch learning rate scheduler class to be used. Specifying ``None`` corresponds
          to using a constant learning rate. Default: ``None``.
      lr_scheduler_kwargs
          Optionally, some keyword arguments for the PyTorch learning rate scheduler. Default: ``None``.
      use_reversible_instance_norm
          Whether to use reversible instance normalization `RINorm` against distribution shift as shown in [1]_.
          It is only applied to the features of the target series and not the covariates.
  
      References
      ----------
      .. [1] T. Kim et al. "Reversible Instance Normalization for Accurate Time-Series Forecasting against
              Distribution Shift", https://openreview.net/forum?id=cGDAkQo1C0p
      """
      super().__init__()
  
      # save hyper parameters for saving/loading
      self.save_hyperparameters(ignore=["loss_fn", "torch_metrics"])
  
      raise_if(
          input_chunk_length is None or output_chunk_length is None,
          "Both `input_chunk_length` and `output_chunk_length` must be passed to `PLForecastingModule`",
          logger,
      )
  
      self.input_chunk_length = input_chunk_length
      # output_chunk_length is a property
      self._output_chunk_length = output_chunk_length
  
      # define the loss function
      self.criterion = loss_fn
      # by default models are deterministic (i.e. not probabilistic)
      self.likelihood = likelihood
  
      # saved in checkpoint to be able to instantiate a model without calling fit_from_dataset
      self.train_sample_shape = train_sample_shape
      self.n_targets = (
          train_sample_shape[0][1]
          if train_sample_shape is not None
          else 1
      )
  
      # persist optimiser and LR scheduler parameters
      self.optimizer_cls = optimizer_cls
      self.optimizer_kwargs = (
          dict() if optimizer_kwargs is None else optimizer_kwargs
      )
      self.lr_scheduler_cls = lr_scheduler_cls
      self.lr_scheduler_kwargs = (
          dict() if lr_scheduler_kwargs is None else lr_scheduler_kwargs
      )
  
      # convert torch_metrics to torchmetrics.MetricCollection
      torch_metrics = self.configure_torch_metrics(torch_metrics)
      self.train_metrics = torch_metrics.clone(prefix="train_")
      self.val_metrics = torch_metrics.clone(prefix="val_")
  
      # reversible instance norm
      self.use_reversible_instance_norm = use_reversible_instance_norm
      if use_reversible_instance_norm:
          self.rin = RINorm(input_dim=self.n_targets)
      else:
          self.rin = None
  
      # initialize prediction parameters
      self.pred_n: Optional[int] = None
      self.pred_num_samples: Optional[int] = None
      self.pred_roll_size: Optional[int] = None
      self.pred_batch_size: Optional[int] = None
      self.pred_n_jobs: Optional[int] = None
      self.predict_likelihood_parameters: Optional[bool] = None
  
imports: from abc import ABC, abstractmethod
  from functools import wraps
  from typing import Any, Dict, Optional, Sequence, Tuple, Union
  import pytorch_lightning
  import torch
  import torch.nn
  import torchmetrics
  from joblib import Parallel, delayed
  from darts.logging import get_logger, raise_if, raise_log
  from darts.models.components.layer_norm_variants import RINorm
  from darts.timeseries import TimeSeries
  from darts.utils.likelihood_models import Likelihood
  from darts.utils.timeseries_generation import _build_forecast_series
  from darts.utils.torch import MonteCarloDropout
label_desc: Use image node_id 1 to create a new PLForecastingModule object from inherited base classes: pl, ABC with example: obj = PLForecastingModule(input_chunk_length, output_chunk_length, train_sample_shape, loss_fn, torch_metrics, likelihood, optimizer_cls, optimizer_kwargs, lr_scheduler_cls, lr_scheduler_kwargs, use_reversible_instance_norm)