timeseries

package
v1.38.1 Latest Latest
Warning

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

 Go to latest Published: Mar 30, 2026 License: Apache-2.0 Imports: 20 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) BackwardSample added in v1.38.0 

func (c *CfC) BackwardSample(dOutput []float64, cacheIface interface{}) error

BackwardSample accumulates parameter gradients for a single sample.

func (*CfC) FlatGrads added in v1.38.0 

func (c *CfC) FlatGrads() []float64

FlatGrads returns the internal gradient accumulator.

func (*CfC) FlatParams added in v1.38.0 

func (c *CfC) FlatParams() []*float64

FlatParams returns pointers to all trainable parameters (exported for TrainableBackend).

func (*CfC) ForwardBatch added in v1.37.0 

func (c *CfC) ForwardBatch(windows [][][]float64) [][]float64

ForwardBatch runs the CfC forward pass on a batch of windowed samples. windows: [batch][channels][inputLen], returns: [batch][outputSize * outputLen]. Each sample maintains an independent hidden state. The ODE integration is batched across samples at each time step to reduce allocation overhead.

func (*CfC) ForwardSample added in v1.38.0 

func (c *CfC) ForwardSample(input [][]float64) ([]float64, interface{}, error)

ForwardSample runs the CfC forward pass on a single sample and returns a flat output with cached activations for BackwardSample.

func (*CfC) ParamCount added in v1.38.0 

func (c *CfC) ParamCount() int

ParamCount returns the total number of trainable parameters (exported for TrainableBackend).

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.

func (*CfC) ZeroGrads added in v1.38.0 

func (c *CfC) ZeroGrads()

ZeroGrads resets all accumulated gradients to zero.

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) BackwardSample added in v1.38.0 

func (d *DLinear) BackwardSample(dOutput []float64, cacheIface interface{}) error

BackwardSample accumulates parameter gradients for a single sample.

func (*DLinear) FlatGrads added in v1.38.0 

func (d *DLinear) FlatGrads() []float64

FlatGrads returns the internal gradient accumulator.

func (*DLinear) FlatParams added in v1.38.0 

func (d *DLinear) FlatParams() []*float64

FlatParams returns pointers to all trainable parameters (exported for TrainableBackend).

func (*DLinear) ForwardSample added in v1.38.0 

func (d *DLinear) ForwardSample(input [][]float64) ([]float64, interface{}, error)

ForwardSample runs the DLinear forward pass on a single sample and returns a flat output with cached activations for BackwardSample.

func (*DLinear) ParamCount added in v1.38.0 

func (d *DLinear) ParamCount() int

ParamCount returns the total number of trainable parameters (exported for TrainableBackend).

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).

func (*DLinear) ZeroGrads added in v1.38.0 

func (d *DLinear) ZeroGrads()

ZeroGrads resets all accumulated gradients to zero.

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 DataLoader added in v1.37.0 

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

DataLoader iterates over windowed time-series data in mini-batches, producing tensors suitable for training loops. It converts [][][]float64 windows and []float64 labels into float32 tensors.

func NewDataLoader added in v1.37.0 

func NewDataLoader(windows [][][]float64, labels []float64, batchSize int, shuffle bool) *DataLoader

NewDataLoader creates a DataLoader that yields mini-batches from the given windows and labels. windows has shape [nSamples][channels][inputLen] and labels has shape [nSamples * outputDim]. When shuffle is true, sample order is randomized using Fisher-Yates on each Reset.

func (*DataLoader) Len added in v1.37.0 

func (dl *DataLoader) Len() int

Len returns the number of batches per epoch, including a possible partial final batch.

func (*DataLoader) Next added in v1.37.0 

func (dl *DataLoader) Next() (inputBatch *tensor.TensorNumeric[float32], labelBatch *tensor.TensorNumeric[float32], ok bool)

Next returns the next batch of input and label tensors. The input tensor has shape [batchSize, channels, inputLen] and the label tensor has shape [batchSize, outputDim]. The final batch may have fewer than batchSize samples. ok is false when all batches have been consumed.

func (*DataLoader) NextIndices added in v1.37.0 

func (dl *DataLoader) NextIndices() (indices []int, ok bool)

NextIndices returns the indices of the next batch of samples without constructing tensors. ok is false when all batches have been consumed.

func (*DataLoader) Reset added in v1.37.0 

func (dl *DataLoader) Reset()

Reset reshuffles (if enabled) and restarts iteration from the beginning.

type FineTuneConfig added in v1.37.0 

type FineTuneConfig struct {
	Epochs         int     // number of training epochs
	LearningRate   float64 // AdamW learning rate
	BatchSize      int     // mini-batch size (0 = full batch)
	FreezeBackbone bool    // if true, only train output head
}

FineTuneConfig configures foundation model fine-tuning.

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 FoundationForecaster added in v1.37.0 

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

FoundationForecaster provides zero-shot time-series forecasting using a pre-trained foundation model (TiRex). It handles input normalization (instance norm), graph execution, and output denormalization.

func LoadFoundationModel added in v1.37.0 

func LoadFoundationModel(path string, engine compute.Engine[float32]) (*FoundationForecaster, error)

LoadFoundationModel loads a TiRex foundation model from a GGUF file and returns a forecaster ready for zero-shot inference.

func NewTestForecaster added in v1.37.0 

func NewTestForecaster(numVars, horizon int) (*FoundationForecaster, error)

NewTestForecaster creates a FoundationForecaster with a stub graph for use in tests outside this package. numVars is the expected number of input variates and horizon is the maximum forecast horizon.

func (*FoundationForecaster) BatchForecast added in v1.37.0 

func (f *FoundationForecaster) BatchForecast(ctx context.Context, inputs [][][]float64, horizon int) ([][][]float64, error)

BatchForecast produces zero-shot forecasts for multiple time series.

Input shape: [batch][seq_len][num_vars] as [][][]float64. Output shape: [batch][horizon][num_vars] as [][][]float64.

func (*FoundationForecaster) FineTune added in v1.37.0 

func (f *FoundationForecaster) FineTune(ctx context.Context, data [][]float64, labels [][]float64, cfg FineTuneConfig) (*TrainResult, error)

FineTune adapts the foundation model on task-specific data using AdamW. When cfg.FreezeBackbone is true, only the output head is trained (few-shot adaptation). data contains input sequences [sample][seq_len*num_vars] and labels contains target outputs [sample][horizon*num_vars], both flattened row-major.

Input data layout: each data[i] has length seq_len * num_vars, representing a [seq_len][num_vars] input flattened row-major. Each labels[i] has length horizon * num_vars, representing [horizon][num_vars] target flattened.

func (*FoundationForecaster) Forecast added in v1.37.0 

func (f *FoundationForecaster) Forecast(ctx context.Context, input [][]float64, horizon int) ([][]float64, error)

Forecast produces a zero-shot forecast for a single time series.

Input shape: [seq_len][num_vars] as [][]float64. Output shape: [horizon][num_vars] as [][]float64.

The pipeline:

  1. Per-channel instance normalization: x_norm = (x - mean) / (std + eps)
  2. Forward pass through TiRex graph
  3. Denormalize predictions: y = y_norm * (std + eps) + mean

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) BackwardSample added in v1.38.0 

func (f *FreTS) BackwardSample(dOutput []float64, cacheIface interface{}) error

BackwardSample accumulates parameter gradients for a single sample.

func (*FreTS) FlatGrads added in v1.38.0 

func (f *FreTS) FlatGrads() []float64

FlatGrads returns the internal gradient accumulator.

func (*FreTS) FlatParams added in v1.38.0 

func (f *FreTS) FlatParams() []*float64

FlatParams returns pointers to all trainable parameters (exported for TrainableBackend).

func (*FreTS) ForwardSample added in v1.38.0 

func (f *FreTS) ForwardSample(input [][]float64) ([]float64, interface{}, error)

ForwardSample runs the FreTS forward pass on a single sample and returns a flat output [channels*outputLen] with cached activations for BackwardSample.

func (*FreTS) ParamCount added in v1.38.0 

func (f *FreTS) ParamCount() int

ParamCount returns the total number of trainable parameters (exported for TrainableBackend).

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).

func (*FreTS) ZeroGrads added in v1.38.0 

func (f *FreTS) ZeroGrads()

ZeroGrads resets all accumulated gradients to zero.

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) BackwardSample added in v1.38.0 

func (m *ITransformer) BackwardSample(dOutput []float64, cacheIface interface{}) error

BackwardSample accumulates parameter gradients for a single sample.

func (*ITransformer) FlatGrads added in v1.38.0 

func (m *ITransformer) FlatGrads() []float64

FlatGrads returns the internal gradient accumulator.

func (*ITransformer) FlatParams added in v1.38.0 

func (m *ITransformer) FlatParams() []*float64

FlatParams returns pointers to all trainable parameters (exported for TrainableBackend).

func (*ITransformer) ForwardSample added in v1.38.0 

func (m *ITransformer) ForwardSample(input [][]float64) ([]float64, interface{}, error)

ForwardSample runs the iTransformer forward pass on a single sample and returns a flat output with cached activations for BackwardSample.

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) ParamCount added in v1.38.0 

func (m *ITransformer) ParamCount() int

ParamCount returns the total number of trainable parameters (exported for TrainableBackend).

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.

func (*ITransformer) ZeroGrads added in v1.38.0 

func (m *ITransformer) ZeroGrads()

ZeroGrads resets all accumulated gradients to zero.

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) BackwardSample added in v1.38.0 

func (m *Mamba) BackwardSample(dOutput []float64, cacheIface interface{}) error

BackwardSample accumulates parameter gradients for a single sample.

func (*Mamba) FlatGrads added in v1.38.0 

func (m *Mamba) FlatGrads() []float64

FlatGrads returns the internal gradient accumulator.

func (*Mamba) FlatParams added in v1.38.0 

func (m *Mamba) FlatParams() []*float64

FlatParams returns pointers to all trainable parameters as float64 pointers. Uses a shadow float64 array that is synced from/to the float32 graph parameters.

func (*Mamba) ForwardSample added in v1.38.0 

func (m *Mamba) ForwardSample(input [][]float64) ([]float64, interface{}, error)

ForwardSample runs the Mamba forward pass on a single sample and returns a flat float64 output with cached activations for BackwardSample.

func (*Mamba) ParamCount added in v1.38.0 

func (m *Mamba) ParamCount() int

ParamCount returns the total number of trainable scalar parameters.

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.

func (*Mamba) ZeroGrads added in v1.38.0 

func (m *Mamba) ZeroGrads()

ZeroGrads resets all accumulated gradients to zero (TrainableBackend).

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 MultiScaleOutput added in v1.37.0 

type MultiScaleOutput struct {
	// Scales contains the mixed trend and seasonal components at each scale.
	// Scales[s].trend and Scales[s].seasonal are [numFeatures][inputLen].
	Scales []scaleDecomposition
}

MultiScaleOutput holds the decomposed and mixed multi-scale representation.

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.

func (*NBEATS) ForwardBatched added in v1.37.0 

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

ForwardBatched runs the N-BEATS forward pass on a 3D input tensor. Input x has shape [batch, channels, inputLen]. The channels are averaged to produce a [batch, inputLen] tensor which is then passed through the standard Forward path. Returns NBEATSOutput with forecast of shape [batch, outputLen].

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) BackwardSample added in v1.38.0 

func (n *NHiTS) BackwardSample(dOutput []float64, cacheIface interface{}) error

BackwardSample accumulates parameter gradients for a single sample.

func (*NHiTS) FlatGrads added in v1.38.0 

func (n *NHiTS) FlatGrads() []float64

FlatGrads returns the internal gradient accumulator.

func (*NHiTS) FlatParams added in v1.38.0 

func (n *NHiTS) FlatParams() []*float64

FlatParams returns pointers to all trainable parameters.

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) ForwardSample added in v1.38.0 

func (n *NHiTS) ForwardSample(input [][]float64) ([]float64, interface{}, error)

ForwardSample runs the N-HiTS forward pass on a single sample using float64 params. Input: [channels][inputLen], returns (flatOutput [outputLen], cache, error).

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) ParamCount added in v1.38.0 

func (n *NHiTS) ParamCount() int

ParamCount returns the total number of trainable parameters.

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.

func (*NHiTS) ZeroGrads added in v1.38.0 

func (n *NHiTS) ZeroGrads()

ZeroGrads resets all accumulated gradients to zero.

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) BackwardSample added in v1.38.0 

func (m *PatchTST) BackwardSample(dOutput []float64, cacheIface interface{}) error

BackwardSample accumulates parameter gradients for a single sample.

func (*PatchTST) FlatGrads added in v1.38.0 

func (m *PatchTST) FlatGrads() []float64

FlatGrads returns the internal gradient accumulator.

func (*PatchTST) FlatParams added in v1.38.0 

func (m *PatchTST) FlatParams() []*float64

FlatParams returns pointers to all trainable parameters (exported for TrainableBackend).

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) ForwardSample added in v1.38.0 

func (m *PatchTST) ForwardSample(input [][]float64) ([]float64, interface{}, error)

ForwardSample runs the PatchTST forward pass on a single sample and returns a flat output with cached activations for BackwardSample.

func (*PatchTST) ParamCount added in v1.38.0 

func (m *PatchTST) ParamCount() int

ParamCount returns the total number of trainable parameters (exported for TrainableBackend).

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.

func (*PatchTST) ZeroGrads added in v1.38.0 

func (m *PatchTST) ZeroGrads()

ZeroGrads resets all accumulated gradients to zero.

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) BackwardSample added in v1.38.0 

func (m *TTM) BackwardSample(dOutput []float64, cacheIface interface{}) error

BackwardSample accumulates parameter gradients for a single sample.

func (*TTM) FlatGrads added in v1.38.0 

func (m *TTM) FlatGrads() []float64

FlatGrads returns the internal gradient accumulator.

func (*TTM) FlatParams added in v1.38.0 

func (m *TTM) FlatParams() []*float64

FlatParams returns pointers to all trainable parameters (exported for TrainableBackend).

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) ForwardSample added in v1.38.0 

func (m *TTM) ForwardSample(input [][]float64) ([]float64, interface{}, error)

ForwardSample runs the TTM forward pass on a single sample and returns a flat output [forecastLen] with cached activations for BackwardSample.

func (*TTM) ParamCount added in v1.38.0 

func (m *TTM) ParamCount() int

ParamCount returns the total number of trainable parameters (exported for TrainableBackend).

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.

func (*TTM) ZeroGrads added in v1.38.0 

func (m *TTM) ZeroGrads()

ZeroGrads resets all accumulated gradients to zero.

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 TimeMixer added in v1.37.0 

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

TimeMixer implements the TimeMixer time-series forecasting model (ICLR 2024). It decomposes input into trend and seasonal components at multiple scales using learnable moving average weights, then produces forecasts via scale-specific linear heads combined with learned mixing weights.

func NewTimeMixer added in v1.37.0 

func NewTimeMixer(cfg TimeMixerConfig, opts ...TimeMixerOption) *TimeMixer

NewTimeMixer creates a new TimeMixer model with the given configuration.

func (*TimeMixer) BackwardSample added in v1.38.0 

func (m *TimeMixer) BackwardSample(dOutput []float64, cacheIface interface{}) error

BackwardSample accumulates parameter gradients for a single sample.

func (*TimeMixer) FlatGrads added in v1.38.0 

func (m *TimeMixer) FlatGrads() []float64

FlatGrads returns the internal gradient accumulator.

func (*TimeMixer) FlatParams added in v1.38.0 

func (m *TimeMixer) FlatParams() []*float64

FlatParams returns pointers to all trainable parameters (exported for TrainableBackend).

func (*TimeMixer) Forward added in v1.37.0 

func (m *TimeMixer) Forward(input [][]float64) (*TimeMixerOutput, error)

Forward takes input [numFeatures][inputLen] and produces a forecast [numFeatures][outputLen] by decomposing at multiple scales, projecting each scale's trend and seasonal components via learned linear heads, and combining with softmax-gated mixing weights.

func (*TimeMixer) ForwardEngine added in v1.37.0 

func (m *TimeMixer) ForwardEngine(ctx context.Context, input [][]float64) (*TimeMixerOutput, error)

ForwardEngine runs the engine-accelerated forward pass, producing the same MultiScaleOutput as Forward. The weighted moving average at each scale is computed via engine.MatMul by constructing a causal convolution (Toeplitz) matrix from the learnable kernel weights. Falls back to the CPU path on any engine error.

func (*TimeMixer) ForwardSample added in v1.38.0 

func (m *TimeMixer) ForwardSample(input [][]float64) ([]float64, interface{}, error)

ForwardSample runs the TimeMixer forward pass on a single sample and returns a flat output with cached activations for BackwardSample.

func (*TimeMixer) MAWeights added in v1.37.0 

func (m *TimeMixer) MAWeights(scale int) []float64

MAWeights returns the learnable moving average weights for the given scale. This is exported for testing and inspection.

func (*TimeMixer) ParamCount added in v1.38.0 

func (m *TimeMixer) ParamCount() int

ParamCount returns the total number of trainable parameters (exported for TrainableBackend).

func (*TimeMixer) TrainWindowed added in v1.37.0 

func (m *TimeMixer) TrainWindowed(windows [][][]float64, labels []float64, epochs int) (*TrainResult, error)

TrainWindowed trains the TimeMixer on windowed time-series data using AdamW with gradient clipping and linear LR warmup.

func (*TimeMixer) ZeroGrads added in v1.38.0 

func (m *TimeMixer) ZeroGrads()

ZeroGrads resets all accumulated gradients to zero.

type TimeMixerAdapter added in v1.37.0 

type TimeMixerAdapter struct {
	Model *TimeMixer
	// contains filtered or unexported fields
}

TimeMixerAdapter wraps a TimeMixer model to satisfy training.Model[float32]. The Forward method takes a flat [batch, channels * inputLen] tensor, decomposes each sample at multiple scales, averages the trend components, and returns the last outputLen timesteps as [batch, channels * outputLen].

func NewTimeMixerAdapter added in v1.37.0 

func NewTimeMixerAdapter(m *TimeMixer) (*TimeMixerAdapter, error)

NewTimeMixerAdapter creates a trainable adapter for the given TimeMixer model.

func (*TimeMixerAdapter) Backward added in v1.37.0 

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

Backward is not implemented for timeseries models.

func (*TimeMixerAdapter) Forward added in v1.37.0 

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

Forward runs the TimeMixer forward pass. Expects a single input tensor of shape [batch, channels * inputLen]. Returns [batch, channels * outputLen].

func (*TimeMixerAdapter) Parameters added in v1.37.0 

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

Parameters returns all trainable parameters from the TimeMixer model.

type TimeMixerConfig added in v1.37.0 

type TimeMixerConfig struct {
	InputLen    int     // lookback window
	OutputLen   int     // forecast horizon
	NumFeatures int     // number of variates
	NumScales   int     // number of decomposition scales (default 4)
	HiddenSize  int     // hidden dimension (default 256)
	NumLayers   int     // number of mixer layers (default 3)
	Dropout     float64 // dropout rate (unused in CPU path, reserved for GPU)
}

TimeMixerConfig holds configuration for a TimeMixer model.

type TimeMixerOption added in v1.37.0 

type TimeMixerOption func(*TimeMixer)

TimeMixerOption configures a TimeMixer model.

func WithTimeMixerEngine added in v1.37.0 

func WithTimeMixerEngine(engine compute.Engine[float32], ops numeric.Arithmetic[float32]) TimeMixerOption

WithTimeMixerEngine sets the compute engine for GPU-accelerated forward pass. When nil (the default), TimeMixer uses the pure-Go CPU path.

type TimeMixerOutput added in v1.37.0 

type TimeMixerOutput struct {
	// Forecast is the final combined forecast: [numFeatures][outputLen].
	Forecast [][]float64
	// Scales contains the mixed decomposition (for inspection/debugging).
	MultiScaleOutput
}

TimeMixerOutput holds the forecast output and decomposed multi-scale representation.

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.

func TrainLoop added in v1.38.0 

func TrainLoop(backend TrainableBackend, windows [][][]float64, labels []float64, config TrainConfig) (*TrainResult, error)

TrainLoop implements the shared AdamW training loop for any TrainableBackend. It handles batching, gradient clipping, LR warmup, and loss tracking.

type TrainableBackend added in v1.38.0 

type TrainableBackend interface {
	// ForwardSample runs the model on a single input window [channels][inputLen]
	// and returns (flatOutput, cache, error). flatOutput is [channels*outputLen].
	// cache holds activations needed by BackwardSample.
	ForwardSample(input [][]float64) ([]float64, interface{}, error)

	// BackwardSample computes parameter gradients for a single sample.
	// dOutput is the loss gradient w.r.t. the flat output [channels*outputLen].
	// cache is the value returned by the corresponding ForwardSample call.
	// It accumulates gradients into the internal gradient buffer and returns
	// the gradient norm contribution (unused, reserved for future use).
	BackwardSample(dOutput []float64, cache interface{}) error

	// FlatGrads returns a pointer to the internal gradient accumulator.
	// The slice has length ParamCount(). The caller is responsible for
	// zeroing it before each batch via ZeroGrads.
	FlatGrads() []float64

	// ZeroGrads resets all accumulated gradients to zero.
	ZeroGrads()

	// FlatParams returns pointers to all trainable parameters.
	FlatParams() []*float64

	// ParamCount returns the total number of trainable parameters.
	ParamCount() int
}

TrainableBackend is the interface that windowed time-series models implement to participate in the shared TrainLoop. Each model provides a per-sample forward/backward pass and exposes its parameters as a flat slice.

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.