timeseries

package
v1.32.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 28, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

README

timeseries — Time-Series Forecasting Models

This package provides three time-series forecasting architectures built on ztensor:

Model Paper Use Case
N-BEATS Neural Basis Expansion Analysis Univariate forecasting with interpretable trend/seasonality decomposition
PatchTST Patch Time-Series Transformer Univariate/multivariate forecasting via patch-based attention
TFT Temporal Fusion Transformer Multi-horizon probabilistic forecasting with static/temporal covariates

Training Patterns

The timeseries models return rich, domain-specific outputs that are essential for interpretability — N-BEATS produces per-stack decompositions (trend vs. seasonality), and TFT provides quantile forecasts with variable importance weights. These outputs do not fit naturally into the single-tensor training.Model[T] interface.

For full control over the training loop and access to all model outputs, use the models directly:

model, _ := timeseries.NewNBEATS(config, engine, ops)

for epoch := range epochs {
    out, _ := model.Forward(ctx, batchInput)

    // Access decomposition for interpretability loss terms.
    trendForecast := out.StackForecasts[0]
    seasonForecast := out.StackForecasts[1]

    // Compute loss on out.Forecast, backpropagate manually.
}
Trainer Integration (via Adapter)

When training.Trainer[T] integration is needed (e.g., to reuse optimizer and scheduling infrastructure), use the adapter wrappers:

model, _ := timeseries.NewNBEATS(config, engine, ops)
adapter, _ := timeseries.NewNBEATSAdapter(model)

// adapter satisfies training.Model[float32]
trainer := training.NewTrainer(adapter, optimizer, lossFn)
trainer.Train(data)

Available adapters:

Adapter Wraps Forward Input Forward Output
NBEATSAdapter *NBEATS [batch, inputLen] [batch, outputLen] (forecast only)
PatchTSTAdapter *PatchTST [batch, inputLen] or [batch, channels, inputLen] [batch, outputDim] or [batch, channels, outputDim]
TFTAdapter *TFT Two tensors: static [batch, features], time [batch, seqLen, features] [batch, nHorizons * nQuantiles]

Trade-offs of the adapter approach:

  • The adapters extract only the primary forecast tensor, discarding decomposition and interpretability outputs. Use standalone loops when these are needed.
  • Backward() is not implemented on the adapters. The training infrastructure should use engine-level autograd or numerical gradients.
  • All adapters expose Parameters() for optimizer integration (weight updates, learning rate scheduling, gradient clipping).
When to Use Which
Scenario Approach
Custom loss with decomposition terms Standalone
Quantile loss with variable importance Standalone
Standard MSE/MAE training with existing Trainer Adapter
Hyperparameter search with Trainer infrastructure Adapter

Documentation

Overview

Package timeseries provides time-series forecasting models built on ztensor.

Models in this package accept static covariates and temporal features, producing multi-horizon forecasts with optional quantile estimates.

Package timeseries provides time-series forecasting models built on ztensor.

Stability: alpha

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func QuantileLoss 

func QuantileLoss(predicted [][]float64, targets []float64, quantiles []float64) (float64, error)

QuantileLoss computes the asymmetric quantile loss (pinball loss) for a set of predictions. predicted has shape [nHorizons][nQuantiles], targets has shape [nHorizons].

Types

type CfC added in v1.9.0 

type CfC struct {
	// contains filtered or unexported fields
}

CfC implements Closed-form Continuous-time neural networks (Hasani et al., Nature Machine Intelligence 2022).

CfC uses liquid time-constant neurons with analytical ODE solutions, avoiding numerical solvers entirely. The closed-form update is: 

tau = sigmoid(W_tau * [x, h] + b_tau)
f = exp(-dt / tau)
h_new = f * h_old + (1 - f) * tanh(W_x * x + W_h * h_old + b_h)

For uniformly sampled time series, dt = 1.0.

func NewCfC added in v1.9.0 

func NewCfC(config CfCConfig, opts ...CfCOption) (*CfC, error)

NewCfC creates a new CfC model with the given configuration.

func (*CfC) PredictWindowed added in v1.9.0 

func (c *CfC) PredictWindowed(modelPath string, windows [][][]float64) ([]float64, error)

PredictWindowed runs inference on windowed data. windows: [nSamples][channels][inputLen]. Returns flat predictions of length nSamples * outputSize * outputLen.

func (*CfC) SaveWeights added in v1.9.0 

func (c *CfC) SaveWeights(path string) error

SaveWeights writes the model weights to a JSON file.

func (*CfC) TrainWindowed added in v1.9.0 

func (c *CfC) TrainWindowed(windows [][][]float64, labels []float64, config TrainConfig) (*TrainResult, error)

TrainWindowed trains the CfC model on windowed data using AdamW with BPTT. windows: [nSamples][channels][inputLen] — input windows. labels: flat slice of length nSamples * outputSize * outputLen.

type CfCConfig added in v1.9.0 

type CfCConfig struct {
	InputSize  int // number of input features per time step
	HiddenSize int // hidden state dimension
	OutputSize int // output dimension per time step
	NumLayers  int // number of stacked CfC layers
	OutputLen  int // forecast horizon (number of output time steps)
}

CfCConfig holds the configuration for a CfC model.

type CfCOption added in v1.13.0 

type CfCOption func(*CfC)

CfCOption configures a CfC model.

func WithCfCEngine added in v1.13.0 

func WithCfCEngine(engine compute.Engine[float32], ops numeric.Arithmetic[float32]) CfCOption

WithCfCEngine sets the compute engine and arithmetic ops for GPU-accelerated training. When set, TrainWindowed dispatches to the engine-based path.

type CrossAsset added in v1.23.0 

type CrossAsset struct {
	// contains filtered or unexported fields
}

CrossAsset wraps a crossasset.Model for the timeseries windowed training interface. It adapts the multi-source classification model to the TrainWindowed / PredictWindowed contract used by other backends (DLinear, FreTS, PatchTST, etc.).

Mapping between timeseries and crossasset conventions:

  • windows[sample][channel][inputLen] <-> data[sample][source][features]
  • labels: flat float64 with 3 values per source (one-hot encoded direction)
  • predictions: flat float64 with 3 values per source (softmax probabilities)

func NewCrossAsset added in v1.23.0 

func NewCrossAsset(config CrossAssetConfig) (*CrossAsset, error)

NewCrossAsset creates a new CrossAsset engine with the given configuration.

func (*CrossAsset) PredictWindowed added in v1.23.0 

func (ca *CrossAsset) PredictWindowed(modelPath string, windows [][][]float64) ([]float64, error)

PredictWindowed runs inference on windowed data.

windows shape: [nSamples][nSources][featuresPerSource]. Returns flat predictions of length nSamples * nSources * 3 where each triplet is the softmax probability for [Long, Short, Flat].

func (*CrossAsset) TrainWindowed added in v1.23.0 

func (ca *CrossAsset) TrainWindowed(windows [][][]float64, labels []float64, config TrainConfig) (*TrainResult, error)

TrainWindowed trains the cross-asset model on windowed data.

windows shape: [nSamples][nSources][featuresPerSource]. labels shape: flat slice of length nSamples * nSources, where each value is the integer direction class (0=Long, 1=Short, 2=Flat) encoded as float64.

The TrainConfig.LR and TrainConfig.Epochs fields override the config defaults if set. Other TrainConfig fields (Beta1, Beta2, etc.) are not used because the underlying crossasset.Model uses its own SGD optimizer.

type CrossAssetConfig added in v1.23.0 

type CrossAssetConfig struct {
	NSources          int     // number of asset sources (maps to channels)
	FeaturesPerSource int     // features per source (maps to input length)
	DModel            int     // transformer hidden dimension
	NHeads            int     // number of attention heads
	NLayers           int     // number of cross-attention layers
	LearningRate      float64 // training learning rate
	Epochs            int     // training epochs
	BatchSize         int     // mini-batch size (0 = full batch)
}

CrossAssetConfig holds configuration for a cross-asset attention engine that wraps the crossasset.Model for the timeseries training interface.

type DLinear added in v1.9.0 

type DLinear struct {
	// contains filtered or unexported fields
}

DLinear implements the DLinear time-series forecasting model (AAAI 2023). It decomposes input into trend and seasonal components using moving average, then applies separate linear projections for each component per channel.

func NewDLinear added in v1.9.0 

func NewDLinear(inputLen, outputLen, channels, kernelSize int, opts ...DLinearOption) (*DLinear, error)

NewDLinear creates a new DLinear model with the given configuration.

func (*DLinear) PredictWindowed added in v1.9.0 

func (d *DLinear) PredictWindowed(modelPath string, windows [][][]float64) ([]float64, error)

PredictWindowed runs inference on windowed data. windows: [nSamples][channels][inputLen]. Returns flat predictions of length nSamples * channels * outputLen.

func (*DLinear) SaveWeights added in v1.9.0 

func (d *DLinear) SaveWeights(path string) error

SaveWeights writes the model weights to a JSON file.

func (*DLinear) TrainWindowed added in v1.9.0 

func (d *DLinear) TrainWindowed(windows [][][]float64, labels []float64, config TrainConfig) (*TrainResult, error)

TrainWindowed trains the DLinear model on windowed data using AdamW. windows: [nSamples][channels][inputLen] input windows. labels: flat slice of length nSamples * channels * outputLen (row-major: sample, channel, time).

type DLinearConfig added in v1.9.0 

type DLinearConfig struct {
	InputLen   int // input sequence length (lookback window)
	OutputLen  int // forecast horizon
	Channels   int // number of channels/features
	KernelSize int // moving average kernel size (must be odd)
}

DLinearConfig holds the configuration for a DLinear model.

type DLinearOption added in v1.12.0 

type DLinearOption func(*DLinear)

DLinearOption configures a DLinear model.

func WithEngine added in v1.12.0 

func WithEngine(engine compute.Engine[float32]) DLinearOption

WithEngine sets the compute engine for GPU-accelerated training. When nil (the default), DLinear uses the pure-Go CPU training path.

type Forecast 

type Forecast struct {
	Horizons  []float64             // point forecasts per horizon
	Quantiles map[float64][]float64 // quantile -> values per horizon (nil if no quantiles)
}

Forecast represents a multi-horizon forecast with optional quantile estimates.

type FreTS added in v1.13.0 

type FreTS struct {
	// contains filtered or unexported fields
}

FreTS implements the Frequency-enhanced Time Series forecasting model (ICML 2023). FreTS uses discrete Fourier transform for channel and temporal mixing:

  1. Real FFT on input -> select top-K frequency components
  2. Channel mixing MLP (mix across channels in frequency domain)
  3. Temporal mixing MLP (mix across time in frequency domain)
  4. Inverse FFT -> linear projection to outputLen

func NewFreTS added in v1.13.0 

func NewFreTS(config FreTSConfig, opts ...FreTSOption) (*FreTS, error)

NewFreTS creates a new FreTS model with the given configuration.

func (*FreTS) PredictWindowed added in v1.13.0 

func (f *FreTS) PredictWindowed(modelPath string, windows [][][]float64) ([]float64, error)

PredictWindowed runs inference on windowed data. windows: [nSamples][channels][inputLen]. Returns flat predictions of length nSamples * channels * outputLen.

func (*FreTS) SaveWeights added in v1.13.0 

func (f *FreTS) SaveWeights(path string) error

SaveWeights writes the model weights to a JSON file.

func (*FreTS) TrainWindowed added in v1.13.0 

func (f *FreTS) TrainWindowed(windows [][][]float64, labels []float64, config TrainConfig) (*TrainResult, error)

TrainWindowed trains the FreTS model on windowed data using AdamW. windows: [nSamples][channels][inputLen] input windows. labels: flat slice of length nSamples * channels * outputLen (row-major: sample, channel, time).

type FreTSConfig added in v1.13.0 

type FreTSConfig struct {
	Channels   int // number of input channels/features
	InputLen   int // input sequence length (lookback window)
	OutputLen  int // forecast horizon
	TopK       int // number of frequency components to keep
	HiddenSize int // hidden size for channel/temporal mixing MLPs
}

FreTSConfig holds the configuration for a FreTS model.

type FreTSOption added in v1.15.0 

type FreTSOption func(*FreTS)

FreTSOption configures a FreTS model.

func WithFreTSEngine added in v1.15.0 

func WithFreTSEngine(engine compute.Engine[float32], ops numeric.Arithmetic[float32]) FreTSOption

WithFreTSEngine sets the compute engine for GPU-accelerated training. When nil (the default), FreTS uses the pure-Go CPU training path.

type ITransformer added in v1.13.0 

type ITransformer struct {
	// contains filtered or unexported fields
}

ITransformer implements the iTransformer model (ICLR 2024). It inverts the standard transformer by treating each variate (channel) as a token and computing attention across variates rather than across time steps.

func NewITransformer added in v1.13.0 

func NewITransformer(config ITransformerConfig, engine compute.Engine[float32], ops numeric.Arithmetic[float32]) (*ITransformer, error)

NewITransformer creates a new iTransformer model. The engine and ops parameters are optional — pass nil to use the pure-Go CPU training path.

func (*ITransformer) Load added in v1.13.0 

func (m *ITransformer) Load(path string) error

Load reads model weights from a JSON file.

func (*ITransformer) PredictWindowed added in v1.13.0 

func (m *ITransformer) PredictWindowed(modelPath string, windows [][][]float64) ([]float64, error)

PredictWindowed runs inference on windowed data. windows: [nSamples][channels][inputLen]. Returns flat predictions of length nSamples * channels * outputLen.

func (*ITransformer) Save added in v1.13.0 

func (m *ITransformer) Save(path string) error

Save writes the model weights to a JSON file.

func (*ITransformer) TrainWindowed added in v1.13.0 

func (m *ITransformer) TrainWindowed(windows [][][]float64, labels []float64, config TrainConfig) (*TrainResult, error)

TrainWindowed trains the iTransformer model on windowed data using AdamW. windows: [nSamples][channels][inputLen]. labels: flat slice of length nSamples * channels * outputLen.

type ITransformerConfig added in v1.13.0 

type ITransformerConfig struct {
	Channels  int // number of input channels/variates
	InputLen  int // lookback window length
	OutputLen int // forecast horizon
	DModel    int // model dimension
	DFF       int // feed-forward dimension
	NHeads    int // number of attention heads
	NLayers   int // number of encoder layers
}

ITransformerConfig holds the configuration for an iTransformer model.

type Mamba added in v1.13.0 

type Mamba struct {
	// contains filtered or unexported fields
}

Mamba implements the Mamba selective state space model (NeurIPS 2023) for time-series forecasting. It wraps layers/ssm.MambaBlock[float32].

func NewMamba added in v1.13.0 

func NewMamba(config MambaConfig, engine compute.Engine[float32], ops numeric.Arithmetic[float32]) (*Mamba, error)

NewMamba creates a new Mamba model with the given configuration.

func (*Mamba) PredictWindowed added in v1.13.0 

func (m *Mamba) PredictWindowed(modelPath string, windows [][][]float64) ([]float64, error)

PredictWindowed runs inference on windowed data. windows: [nSamples][channels][inputLen]. Returns flat predictions of length nSamples * channels * outputLen.

func (*Mamba) SaveWeights added in v1.13.0 

func (m *Mamba) SaveWeights(path string) error

SaveWeights writes the model weights to a JSON file.

func (*Mamba) TrainWindowed added in v1.13.0 

func (m *Mamba) TrainWindowed(windows [][][]float64, labels []float64, config TrainConfig) (*TrainResult, error)

TrainWindowed trains the Mamba model on windowed data using AdamW.

type MambaConfig added in v1.13.0 

type MambaConfig struct {
	Channels     int // number of input channels
	InputLen     int // lookback window
	OutputLen    int // forecast horizon
	DModel       int // model dimension
	DState       int // SSM state dimension (typically 16)
	DConv        int // convolution kernel size (typically 4)
	ExpandFactor int // expansion factor (typically 2)
	NLayers      int // number of Mamba blocks
}

MambaConfig holds the configuration for a Mamba model.

type NBEATS 

type NBEATS struct {
	// contains filtered or unexported fields
}

NBEATS implements the N-BEATS (Neural Basis Expansion Analysis for Interpretable Time Series Forecasting) architecture.

The model consists of stacks of blocks. Each block applies FC layers to produce theta parameters, which are expanded through a basis function (polynomial for trend, Fourier for seasonality, learned for generic) to produce backcast and forecast signals. Double residual stacking subtracts the backcast from the input and accumulates forecasts.

func NewNBEATS 

func NewNBEATS(config NBEATSConfig, engine compute.Engine[float32], ops numeric.Arithmetic[float32]) (*NBEATS, error)

NewNBEATS creates a new N-BEATS model with the given configuration.

func (*NBEATS) Decompose 

func (m *NBEATS) Decompose(ctx context.Context, x *tensor.TensorNumeric[float32]) (map[StackType]*tensor.TensorNumeric[float32], error)

Decompose runs forward and returns the per-stack decomposition of the forecast. This is useful for interpretable forecasting: separating trend from seasonality.

func (*NBEATS) Forward 

func (m *NBEATS) Forward(ctx context.Context, x *tensor.TensorNumeric[float32]) (*NBEATSOutput, error)

Forward runs the N-BEATS forward pass. Input x has shape [batch, inputLen]. Returns NBEATSOutput with forecast of shape [batch, outputLen] and per-stack decomposition.

type NBEATSAdapter 

type NBEATSAdapter struct {
	Model *NBEATS
	// contains filtered or unexported fields
}

NBEATSAdapter wraps an NBEATS model to satisfy training.Model[float32]. The Forward method extracts the Forecast tensor from NBEATSOutput, discarding per-stack decomposition. Use NBEATS.Forward directly when interpretability (stack-level forecasts/backcasts) is needed.

func NewNBEATSAdapter 

func NewNBEATSAdapter(m *NBEATS) (*NBEATSAdapter, error)

NewNBEATSAdapter creates a trainable adapter for the given NBEATS model.

func (*NBEATSAdapter) Backward 

func (a *NBEATSAdapter) Backward(_ context.Context, _ *tensor.TensorNumeric[float32], _ ...*tensor.TensorNumeric[float32]) ([]*tensor.TensorNumeric[float32], error)

Backward is not implemented for timeseries models. Timeseries models use standalone training loops with numerical or engine-level gradient computation rather than manual backward passes.

func (*NBEATSAdapter) Forward 

func (a *NBEATSAdapter) Forward(ctx context.Context, inputs ...*tensor.TensorNumeric[float32]) (*tensor.TensorNumeric[float32], error)

Forward runs the NBEATS forward pass and returns the forecast tensor. Expects a single input tensor of shape [batch, inputLen].

func (*NBEATSAdapter) Parameters 

func (a *NBEATSAdapter) Parameters() []*graph.Parameter[float32]

Parameters returns all trainable parameters from the NBEATS model.

type NBEATSConfig 

type NBEATSConfig struct {
	InputLength     int         // length of the lookback window
	OutputLength    int         // forecast horizon
	StackTypes      []StackType // types of stacks (e.g., [StackTrend, StackSeasonality])
	NBlocksPerStack int         // number of blocks in each stack
	HiddenDim       int         // hidden dimension of FC layers in each block
	NHarmonics      int         // number of Fourier harmonics for seasonality stacks
}

NBEATSConfig holds the configuration for an NBEATS model.

type NBEATSOutput 

type NBEATSOutput struct {
	Forecast       *tensor.TensorNumeric[float32]   // [batch, outputLen]
	StackForecasts []*tensor.TensorNumeric[float32] // per-stack forecasts for decomposition
	StackBackcasts []*tensor.TensorNumeric[float32] // per-stack backcasts
}

NBEATSOutput holds the result of an N-BEATS forward pass.

type NHiTS added in v1.9.0 

type NHiTS struct {
	// contains filtered or unexported fields
}

NHiTS implements the N-HiTS (Neural Hierarchical Interpolation for Time Series Forecasting) model from AAAI 2023.

N-HiTS extends N-BEATS by adding multi-rate temporal pooling. Each stack first downsamples the input via max-pooling with a different kernel, then processes through an MLP, and interpolates back to the forecast horizon. The hierarchical design lets different stacks capture patterns at different temporal granularities.

func NewNHiTS added in v1.9.0 

func NewNHiTS(config NHiTSConfig, engine compute.Engine[float32], ops numeric.Arithmetic[float32]) (*NHiTS, error)

NewNHiTS creates a new N-HiTS model with the given configuration.

func (*NHiTS) Forward added in v1.9.0 

func (m *NHiTS) Forward(ctx context.Context, x *tensor.TensorNumeric[float32]) (*tensor.TensorNumeric[float32], error)

Forward runs the N-HiTS forward pass. Input x has shape [batch, inputLen] (single channel) or [batch, channels * inputLen]. Returns forecast tensor of shape [batch, outputLen].

func (*NHiTS) Load added in v1.9.0 

func (n *NHiTS) Load(path string) error

Load reads model weights from a JSON file.

func (*NHiTS) PredictWindowed added in v1.9.0 

func (n *NHiTS) PredictWindowed(modelPath string, windows [][][]float64) ([]float64, error)

PredictWindowed loads a model from disk and runs inference. windows: [numSamples][channels][inputLen]. Returns flattened predictions [numSamples * outputLen].

func (*NHiTS) Save added in v1.9.0 

func (n *NHiTS) Save(path string) error

Save writes the N-HiTS model to a JSON file.

func (*NHiTS) TrainWindowed added in v1.9.0 

func (n *NHiTS) TrainWindowed(windows [][][]float64, labels []float64, config TrainConfig) (*TrainResult, error)

TrainWindowed trains the N-HiTS model on pre-windowed data using AdamW with analytical gradient computation.

windows: [numSamples][channels][inputLen] — input windows. labels: [numSamples * outputLen] — flattened target values.

type NHiTSAdapter added in v1.9.0 

type NHiTSAdapter struct {
	Model *NHiTS
	// contains filtered or unexported fields
}

NHiTSAdapter wraps an NHiTS model to satisfy training.Model[float32]. The Forward method runs the N-HiTS forward pass, producing a forecast tensor.

func NewNHiTSAdapter added in v1.9.0 

func NewNHiTSAdapter(m *NHiTS) (*NHiTSAdapter, error)

NewNHiTSAdapter creates a trainable adapter for the given NHiTS model.

func (*NHiTSAdapter) Backward added in v1.9.0 

func (a *NHiTSAdapter) Backward(_ context.Context, _ *tensor.TensorNumeric[float32], _ ...*tensor.TensorNumeric[float32]) ([]*tensor.TensorNumeric[float32], error)

Backward is not implemented for timeseries models.

func (*NHiTSAdapter) Forward added in v1.9.0 

func (a *NHiTSAdapter) Forward(ctx context.Context, inputs ...*tensor.TensorNumeric[float32]) (*tensor.TensorNumeric[float32], error)

Forward runs the NHiTS forward pass and returns the forecast tensor. Expects a single input tensor of shape [batch, channels * inputLen].

func (*NHiTSAdapter) Parameters added in v1.9.0 

func (a *NHiTSAdapter) Parameters() []*graph.Parameter[float32]

Parameters returns all trainable parameters from the NHiTS model.

type NHiTSConfig added in v1.9.0 

type NHiTSConfig struct {
	InputLength  int   // length of the lookback window
	OutputLength int   // forecast horizon
	Channels     int   // number of input channels (variates)
	PoolKernels  []int // downsampling factor per stack (e.g., [2, 4, 8])
	HiddenSize   int   // hidden dimension of MLP layers in each stack
	NumMLPLayers int   // number of hidden MLP layers per stack (default 2)
}

NHiTSConfig holds the configuration for an NHiTS model.

type PatchTST 

type PatchTST struct {
	// contains filtered or unexported fields
}

PatchTST implements the Patch Time-Series Transformer.

func NewPatchTST 

func NewPatchTST(config PatchTSTConfig, engine compute.Engine[float32], ops numeric.Arithmetic[float32]) (*PatchTST, error)

NewPatchTST creates a new PatchTST model with the given configuration.

func (*PatchTST) Forward 

func (m *PatchTST) Forward(ctx context.Context, input *tensor.TensorNumeric[float32]) (*tensor.TensorNumeric[float32], error)

Forward runs the PatchTST forward pass on input time series data. input shape: [batch, channels, input_length] for multivariate, or [batch, input_length] for univariate (treated as 1 channel). Returns predictions of shape [batch, channels, output_dim] if channel_independent, or [batch, output_dim] if not channel_independent.

func (*PatchTST) Predict 

func (m *PatchTST) Predict(input [][]float64) ([][]float64, error)

Predict runs inference on multivariate time series data using float64 slices. input[channel]time has one sub-slice per channel, each of length InputLength. Returns output[channel][horizon] with OutputDim predictions per channel. For single-channel input, pass a single sub-slice.

func (*PatchTST) PredictWindowed added in v1.10.0 

func (m *PatchTST) PredictWindowed(modelPath string, windows [][][]float64) ([]float64, error)

PredictWindowed runs inference on windowed data. windows: [nSamples][channels][inputLen]. Returns flat predictions of length nSamples * outputDim.

func (*PatchTST) SaveWeights added in v1.10.0 

func (m *PatchTST) SaveWeights(path string) error

SaveWeights writes the model weights to a JSON file.

func (*PatchTST) TrainWindowed added in v1.10.0 

func (m *PatchTST) TrainWindowed(windows [][][]float64, labels []float64, config TrainConfig) (*TrainResult, error)

TrainWindowed trains the PatchTST model on windowed data using AdamW. windows: [nSamples][channels][inputLen] input windows. labels: flat slice of length nSamples * outputDim.

type PatchTSTAdapter 

type PatchTSTAdapter struct {
	Model *PatchTST
	// contains filtered or unexported fields
}

PatchTSTAdapter wraps a PatchTST model to satisfy training.Model[float32]. PatchTST.Forward already returns a tensor, so the adapter is a thin pass-through.

func NewPatchTSTAdapter 

func NewPatchTSTAdapter(m *PatchTST) (*PatchTSTAdapter, error)

NewPatchTSTAdapter creates a trainable adapter for the given PatchTST model.

func (*PatchTSTAdapter) Backward 

func (a *PatchTSTAdapter) Backward(_ context.Context, _ *tensor.TensorNumeric[float32], _ ...*tensor.TensorNumeric[float32]) ([]*tensor.TensorNumeric[float32], error)

Backward is not implemented for timeseries models.

func (*PatchTSTAdapter) Forward 

func (a *PatchTSTAdapter) Forward(ctx context.Context, inputs ...*tensor.TensorNumeric[float32]) (*tensor.TensorNumeric[float32], error)

Forward runs the PatchTST forward pass. Expects a single input tensor of shape [batch, input_length] or [batch, channels, input_length].

func (*PatchTSTAdapter) Parameters 

func (a *PatchTSTAdapter) Parameters() []*graph.Parameter[float32]

Parameters returns all trainable parameters from the PatchTST model.

type PatchTSTConfig 

type PatchTSTConfig struct {
	InputLength        int  // length of input time series
	PatchLength        int  // length of each patch
	Stride             int  // stride between patches
	DModel             int  // transformer hidden dimension
	NHeads             int  // number of attention heads
	NLayers            int  // number of transformer encoder layers
	OutputDim          int  // output prediction dimension
	ChannelIndependent bool // process each channel independently through same transformer
}

PatchTSTConfig holds configuration for a PatchTST model.

func (PatchTSTConfig) NumPatches 

func (c PatchTSTConfig) NumPatches() int

NumPatches returns the number of patches produced by the patching configuration.

type StackType 

type StackType int

StackType identifies the type of basis expansion used in an N-BEATS stack. 

const (
	// StackTrend uses polynomial basis expansion for trend modeling.
	StackTrend StackType = iota
	// StackSeasonality uses Fourier basis expansion for seasonal patterns.
	StackSeasonality
	// StackGeneric uses learned linear projections as basis functions.
	StackGeneric
)

func (StackType) String 

func (s StackType) String() string

String returns the string representation of a StackType.

type TFT 

type TFT struct {
	// contains filtered or unexported fields
}

TFT implements the Temporal Fusion Transformer for multi-horizon probabilistic forecasting.

func NewTFT 

func NewTFT(config TFTConfig, engine compute.Engine[float32], ops numeric.Arithmetic[float32]) (*TFT, error)

NewTFT creates a new Temporal Fusion Transformer with the given configuration.

func (*TFT) Predict 

func (m *TFT) Predict(staticFeatures []float64, timeFeatures [][]float64) ([][]float64, error)

Predict runs the TFT forward pass and returns multi-horizon quantile forecasts. staticFeatures has shape [numStaticFeatures]. timeFeatures has shape [seqLen][numTimeFeatures]. Returns a slice of shape [nHorizons][nQuantiles].

func (*TFT) VariableSelectionWeights 

func (m *TFT) VariableSelectionWeights(featureType string, features []float64) ([]float64, error)

VariableSelectionWeights returns the softmax variable importance weights for the static or time variable selection network. This enables interpretability — a key feature of TFT. Pass "static" or "time" as featureType.

type TFTAdapter 

type TFTAdapter struct {
	Model *TFT
	// contains filtered or unexported fields
}

TFTAdapter wraps a TFT model to satisfy training.Model[float32]. The Forward method expects two inputs: static features [batch, numStaticFeatures] and time features [batch, seqLen, numTimeFeatures]. It processes each batch element individually through TFT.Predict and returns the stacked output.

func NewTFTAdapter 

func NewTFTAdapter(m *TFT) (*TFTAdapter, error)

NewTFTAdapter creates a trainable adapter for the given TFT model.

func (*TFTAdapter) Backward 

func (a *TFTAdapter) Backward(_ context.Context, _ *tensor.TensorNumeric[float32], _ ...*tensor.TensorNumeric[float32]) ([]*tensor.TensorNumeric[float32], error)

Backward is not implemented for timeseries models.

func (*TFTAdapter) Forward 

func (a *TFTAdapter) Forward(ctx context.Context, inputs ...*tensor.TensorNumeric[float32]) (*tensor.TensorNumeric[float32], error)

Forward runs the TFT forward pass. Expects two inputs: static features [batch, numStaticFeatures] and time features [batch, seqLen, numTimeFeatures]. Returns [batch, nHorizons * nQuantiles].

func (*TFTAdapter) Parameters 

func (a *TFTAdapter) Parameters() []*graph.Parameter[float32]

Parameters returns all trainable parameters from the TFT model.

type TFTConfig 

type TFTConfig struct {
	NumStaticFeatures int
	NumTimeFeatures   int
	DModel            int
	NHeads            int
	NHorizons         int
	Quantiles         []float64
}

TFTConfig holds the configuration for a Temporal Fusion Transformer.

type TTM added in v1.21.0 

type TTM struct {
	// contains filtered or unexported fields
}

TTM implements the TinyTimeMixer model for time series forecasting. It supports zero-shot inference and few-shot fine-tuning.

func NewTTM added in v1.21.0 

func NewTTM(config TTMTrainConfig, engine compute.Engine[float32], ops numeric.Arithmetic[float32]) (*TTM, error)

NewTTM creates a new TTM model with the given configuration.

func (*TTM) Forward added in v1.21.0 

func (m *TTM) Forward(ctx context.Context, input *tensor.TensorNumeric[float32]) (*tensor.TensorNumeric[float32], error)

Forward runs the TTM forward pass on input time series. input shape: [batch, channels, contextLen] or [batch, contextLen]. Returns predictions of shape [batch, forecastLen].

func (*TTM) PredictWindowed added in v1.21.0 

func (m *TTM) PredictWindowed(modelPath string, windows [][][]float64) ([]float64, error)

PredictWindowed runs inference on windowed data. Returns flat predictions of length nSamples * forecastLen.

func (*TTM) SaveWeights added in v1.21.0 

func (m *TTM) SaveWeights(path string) error

SaveWeights writes the model weights to a JSON file.

func (*TTM) TrainWindowed added in v1.21.0 

func (m *TTM) TrainWindowed(windows [][][]float64, labels []float64, config TrainConfig) (*TrainResult, error)

TrainWindowed trains the TTM model on windowed time series data. windows: [nSamples][channels][contextLen]. labels: flat slice of length nSamples * forecastLen.

type TTMEngine added in v1.21.0 

type TTMEngine[T tensor.Float] struct {
	// contains filtered or unexported fields
}

TTMEngine implements the TTM forward pass using typed tensor operations and TSMixerBlock layers for inference. This is the compute.Engine-based inference path, separate from the float64 analytical training path in ttm.go.

func NewTTMEngine added in v1.21.0 

func NewTTMEngine[T tensor.Float](
	config TTMTrainConfig,
	engine compute.Engine[T],
	ops numeric.Arithmetic[T],
) (*TTMEngine[T], error)

NewTTMEngine creates a new TTMEngine with initialized layers.

func (*TTMEngine[T]) DecoderParameters added in v1.21.0 

func (e *TTMEngine[T]) DecoderParameters() []*tensor.TensorNumeric[T]

DecoderParameters returns all trainable parameters from the decoder blocks.

func (*TTMEngine[T]) EncoderParameters added in v1.21.0 

func (e *TTMEngine[T]) EncoderParameters() []*tensor.TensorNumeric[T]

EncoderParameters returns all trainable parameters from the encoder blocks.

func (*TTMEngine[T]) ExtractPatches added in v1.21.0 

func (e *TTMEngine[T]) ExtractPatches(_ context.Context, input *tensor.TensorNumeric[T]) (*tensor.TensorNumeric[T], error)

ExtractPatches converts raw time series into non-overlapping patches.

Input shape: [batch, contextLen] Output shape: [batch, numPatches, patchLen]

func (*TTMEngine[T]) Forward added in v1.21.0 

func (e *TTMEngine[T]) Forward(ctx context.Context, input *tensor.TensorNumeric[T]) (*tensor.TensorNumeric[T], error)

Forward runs the TTM forward pass through encoder and decoder TSMixer blocks.

Input shape: [batch, numPatches, patchLen] Output shape: [batch, forecastLen]

The input should already be patched. If you have raw time series of shape [batch, contextLen], use ExtractPatches first.

type TTMTrainConfig added in v1.21.0 

type TTMTrainConfig struct {
	ContextLen     int     // length of input time series context window
	ForecastLen    int     // number of future steps to predict
	NumChannels    int     // number of input channels/features
	PatchLen       int     // length of each patch
	DModel         int     // model hidden dimension
	NumMixerLayers int     // number of TSMixer blocks per encoder/decoder
	ChannelMixing  bool    // enable feature-mixing MLPs (false = channel-independent)
	LearningRate   float64 // AdamW learning rate
	Epochs         int     // training epochs
	BatchSize      int     // mini-batch size (0 = full batch)
	FreezeEncoder  bool    // freeze encoder weights for few-shot fine-tuning
}

TTMTrainConfig holds configuration for a TTM (TinyTimeMixer) model.

func (TTMTrainConfig) ForecastPatches added in v1.21.0 

func (c TTMTrainConfig) ForecastPatches() int

ForecastPatches returns the number of forecast patches.

func (TTMTrainConfig) NumPatches added in v1.21.0 

func (c TTMTrainConfig) NumPatches() int

NumPatches returns the number of patches from the context window.

type TrainConfig added in v1.9.0 

type TrainConfig struct {
	Epochs       int     // number of training epochs
	LR           float64 // learning rate
	WeightDecay  float64 // AdamW weight decay
	GradClip     float64 // max gradient norm (0 = no clipping)
	BatchSize    int     // mini-batch size (0 = full batch)
	Beta1        float64 // AdamW beta1
	Beta2        float64 // AdamW beta2
	Epsilon      float64 // AdamW epsilon
	WarmupEpochs int     // linear LR warmup over this many epochs (0 = no warmup)
}

TrainConfig holds training hyperparameters for windowed time-series backends.

func DefaultTrainConfig added in v1.9.0 

func DefaultTrainConfig() TrainConfig

DefaultTrainConfig returns sensible defaults for training.

type TrainResult added in v1.9.0 

type TrainResult struct {
	FinalLoss   float64            // loss at last epoch
	LossHistory []float64          // loss per epoch
	ModelPath   string             // path where model weights were saved
	Metrics     map[string]float64 // e.g., "mse", "correlation", "directional_accuracy"
}

TrainResult holds training metrics.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.