timeseries

package
v1.35.0 Latest Latest
Warning

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

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

Documentation

Overview

Package timeseries implements time-series model builders.

Package timeseries implements time-series model builders.

Package timeseries implements time-series model builders.

Package timeseries implements time-series model builders.

Package timeseries provides time-series model architecture builders.

Stability: alpha

Package timeseries implements GGUF metadata loading for time-series models.

Index

Constants

This section is empty.

Variables

View Source 
var FrequencyScaleFactors = map[string]float32{
	"15min":          0.25,
	"quarter_hourly": 0.25,
	"hourly":         1.0,
	"daily":          3.43,
	"weekly":         24.0,
	"monthly":        104.0,
}

FrequencyScaleFactors maps sampling frequency strings to their temporal scale factors used by the FlowState Functional Basis Decoder.

Functions

func BuildFlowState added in v1.21.0 

func BuildFlowState[T tensor.Float](
	cfg *FlowStateConfig,
	engine compute.Engine[T],
) (*graph.Graph[T], error)

BuildFlowState constructs a FlowState computation graph.

Input: [batch, context_len, num_channels] Output: [batch, forecast_len, num_channels]

The architecture is:

  1. Patch input per channel -> patch embedding
  2. SSM encoder (N layers with residual + LayerNorm)
  3. Mean pool over patches
  4. Functional Basis Decoder (Fourier sin/cos)

func BuildPatchTST 

func BuildPatchTST[T tensor.Numeric](cfg PatchTSTConfig, engine compute.Engine[T]) (*graph.Graph[T], error)

BuildPatchTST constructs a PatchTST computation graph. Input: [batch, seq_len, num_vars] time series. Output: [batch, horizon, num_vars] predictions.

func BuildTFT 

func BuildTFT[T tensor.Numeric](cfg TFTConfig, engine compute.Engine[T]) (*graph.Graph[T], error)

BuildTFT constructs a TFT computation graph. Input 0: [batch, seq_len, num_temporal_features] temporal features. Input 1: [batch, num_static_features] static covariates. Output: [batch, H, len(quantiles)] quantile predictions.

func BuildTTM added in v1.21.0 

func BuildTTM[T tensor.Float](
	tensors map[string]*tensor.TensorNumeric[T],
	cfg *TTMConfig,
	engine compute.Engine[T],
) (*graph.Graph[T], error)

BuildTTM constructs a TTM computation graph from GGUF tensor weights.

The graph accepts input of shape [batch, context_len, channels] and produces output of shape [batch, forecast_len, channels].

The TTM pipeline is:

  1. Input normalization (standard scaling per channel)
  2. Adaptive patching: reshape input into patches
  3. Patch embedding: linear projection [patch_len] -> [d_model]
  4. TSMixer backbone: N stacked TSMixer blocks
  5. Decoder: project encoder output to forecast patches
  6. Forecast head: linear [d_model] -> [forecast_len / num_forecast_patches * channels]
  7. Output denormalization

func SelectTTMVariant added in v1.21.0 

func SelectTTMVariant(contextLen, forecastLen int) string

SelectTTMVariant returns the recommended model variant name for the given context and forecast lengths. TTM variants: 512-96, 1024-96, 1536-96, 512-192, 512-336, 512-720.

Selection logic:

  1. If an exact match exists, return it.
  2. Otherwise, select the variant with the smallest context_len >= requested and smallest forecast_len >= requested.
  3. If no variant can cover the requested lengths, return the largest variant.

Types

type FlowStateConfig added in v1.21.0 

type FlowStateConfig struct {
	ContextLen   int     // input context window length
	ForecastLen  int     // prediction horizon
	NumChannels  int     // number of input/output variates
	PatchLen     int     // patch size for input patching
	DModel       int     // model dimension (SSM input/output)
	NumSSMLayers int     // number of stacked SSM layers
	DState       int     // SSM hidden state dimension
	NumBasis     int     // number of Fourier basis functions
	ScaleFactor  float32 // temporal scale for sampling rate adaptation
}

FlowStateConfig holds configuration for the FlowState SSM-based time series forecasting model. FlowState uses an SSM encoder with a Functional Basis Decoder (Fourier basis) for continuous forecasting.

type FlowStateModel added in v1.21.0 

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

FlowStateModel wraps a compiled FlowState computation graph for inference.

func LoadFlowState added in v1.21.0 

func LoadFlowState(path string, opts ...Option) (*FlowStateModel, error)

LoadFlowState loads a FlowState model from a GGUF file and returns an inference-ready model. The GGUF metadata must contain ts.signal.model_type set to "flowstate" along with the required FlowState configuration fields.

func (*FlowStateModel) Config added in v1.21.0 

func (m *FlowStateModel) Config() *FlowStateConfig

Config returns the FlowState configuration.

func (*FlowStateModel) Forecast added in v1.21.0 

func (m *FlowStateModel) Forecast(input [][]float64) ([][]float64, error)

Forecast produces time series forecasts using the loaded FlowState model. Input shape: [context_len][channels] as [][]float64. Output shape: [forecast_len][channels] as [][]float64.

func (*FlowStateModel) ForecastWithFreq added in v1.21.0 

func (m *FlowStateModel) ForecastWithFreq(input [][]float64, freq string) ([][]float64, error)

ForecastWithFreq produces forecasts adapted to a specific sampling frequency. The frequency string adjusts the internal scale_factor used by the Fourier basis decoder. Supported values: "15min", "quarter_hourly", "hourly", "daily", "weekly", "monthly".

type GraniteTimeSeriesConfig added in v1.21.0 

type GraniteTimeSeriesConfig struct {
	TimeSeriesSignalConfig // embed existing config

	// Common Granite TS fields
	ModelType   string // ts.signal.model_type — "ttm", "flowstate", "tspulse" (required)
	ContextLen  int    // ts.signal.context_len — context window (512, 1024, 1536)
	ForecastLen int    // ts.signal.forecast_len — prediction horizon

	// TTM-specific
	NumMixerLayers int  // ts.signal.num_mixer_layers — TSMixer backbone depth
	ChannelMixing  bool // ts.signal.channel_mixing — TTM decoder channel mixing enabled
	PatchLen       int  // ts.signal.patch_len — patch length for adaptive patching
	NumPatches     int  // ts.signal.num_patches — number of patches

	// FlowState-specific
	ScaleFactor  float32 // ts.signal.scale_factor — temporal scale for sampling rate adaptation
	NumSSMLayers int     // ts.signal.num_ssm_layers — SSM encoder depth

	// TSPulse-specific
	MaskType string // ts.signal.mask_type — "hybrid" or "block"
	HeadType string // ts.signal.head_type — "allhead" or "dualhead"
}

GraniteTimeSeriesConfig extends TimeSeriesSignalConfig with Granite-specific fields for IBM Granite Time Series models (TTM, FlowState, TSPulse).

func LoadGraniteTimeSeriesConfig added in v1.21.0 

func LoadGraniteTimeSeriesConfig(meta map[string]interface{}) (*GraniteTimeSeriesConfig, error)

LoadGraniteTimeSeriesConfig extracts GraniteTimeSeriesConfig from a GGUF metadata map. Only ts.signal.model_type is required; all other fields have sensible defaults.

type Option added in v1.21.0 

type Option func(*options)

Option configures TTM model loading.

type PatchTSTBuilder 

type PatchTSTBuilder[T tensor.Numeric] func(cfg TimeSeriesSignalConfig, engine compute.Engine[T]) (*graph.Graph[T], error)

PatchTSTBuilder constructs a PatchTST computation graph from a signal config and compute engine. This allows callers to supply their own graph builder without creating a circular import.

type PatchTSTConfig 

type PatchTSTConfig struct {
	PatchLen  int // patch size (e.g., 16)
	Stride    int // patch stride (e.g., 8)
	NumLayers int // transformer encoder depth (e.g., 3)
	NumHeads  int // attention heads (e.g., 8)
	DModel    int // model dim (e.g., 128)
	Horizon   int // prediction horizon H
	NumVars   int // number of input features D
}

PatchTSTConfig holds configuration for the PatchTST model.

type RegimeConfig 

type RegimeConfig struct {
	InputDim   int // number of input features per timestep
	HiddenDim  int // GRU hidden size (e.g., 128)
	NumLayers  int // GRU depth (e.g., 2)
	SeqLen     int // input sequence length (e.g., 60 days)
	NumClasses int // number of regime classes (default: 4)
}

RegimeConfig holds configuration for the regime detection model.

type RegimeDetector 

type RegimeDetector[T tensor.Numeric] struct {
	// contains filtered or unexported fields
}

RegimeDetector is a GRU-based regime classification model. It processes sequential input through stacked GRU layers and classifies the final hidden state into one of NumClasses regimes (bull/bear/sideways/volatile).

func BuildRegimeDetector 

func BuildRegimeDetector[T tensor.Numeric](
	cfg RegimeConfig,
	engine compute.Engine[T],
	ops numeric.Arithmetic[T],
) (*RegimeDetector[T], error)

BuildRegimeDetector constructs a regime detection model. The model consists of stacked GRU layers followed by a linear classifier with softmax output producing 4-class probabilities (bull/bear/sideways/volatile).

func (*RegimeDetector[T]) Attributes 

func (rd *RegimeDetector[T]) Attributes() map[string]interface{}

Attributes returns the model configuration.

func (*RegimeDetector[T]) Backward 

func (rd *RegimeDetector[T]) Backward(_ context.Context, _ types.BackwardMode, _ *tensor.TensorNumeric[T], _ ...*tensor.TensorNumeric[T]) ([]*tensor.TensorNumeric[T], error)

Backward is not implemented for inference-only use.

func (*RegimeDetector[T]) Forward 

func (rd *RegimeDetector[T]) Forward(ctx context.Context, inputs ...*tensor.TensorNumeric[T]) (*tensor.TensorNumeric[T], error)

Forward runs the regime detection model. Input shape: [batch, seqLen, inputDim] Output shape: [batch, numClasses] with softmax probabilities.

func (*RegimeDetector[T]) OpType 

func (rd *RegimeDetector[T]) OpType() string

OpType returns the operation type.

func (*RegimeDetector[T]) OutputShape 

func (rd *RegimeDetector[T]) OutputShape() []int

OutputShape returns [batch, numClasses].

func (*RegimeDetector[T]) Parameters 

func (rd *RegimeDetector[T]) Parameters() []*graph.Parameter[T]

Parameters returns all trainable parameters.

type TFTConfig 

type TFTConfig struct {
	NumStaticFeatures   int       // static covariates (e.g. asset metadata)
	NumTemporalFeatures int       // time-varying inputs
	HiddenDim           int       // d_model
	NumHeads            int       // attention heads
	NumLSTMLayers       int       // LSTM encoder layers
	HorizonLen          int       // forecast steps H
	Quantiles           []float32 // e.g. [0.1, 0.5, 0.9]
}

TFTConfig holds configuration for the Temporal Fusion Transformer.

type TSPulseConfig added in v1.21.0 

type TSPulseConfig struct {
	ContextLen  int    // input context window length
	NumChannels int    // number of input channels (variables)
	PatchLen    int    // patch size for the dual-space encoder
	DModel      int    // model embedding dimension
	NumLayers   int    // number of transformer encoder layers per path
	MaskType    string // "hybrid" or "block"
	HeadType    string // "allhead" or "dualhead"
	NumClasses  int    // for classification head (0 if not used)
}

TSPulseConfig holds configuration for the TSPulse multi-task time series model.

type TSPulseInference added in v1.21.0 

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

TSPulseInference provides high-level TSPulse inference with preprocessing. It wraps a TSPulseModel and handles input normalization, context length adjustment, and output denormalization automatically.

func NewTSPulseInference added in v1.21.0 

func NewTSPulseInference(modelPath string, opts ...Option) (*TSPulseInference, error)

NewTSPulseInference creates a TSPulse inference instance from a GGUF model path. The model is loaded and ready for multi-task inference upon return.

func (*TSPulseInference) AnomalyDetect added in v1.21.0 

func (t *TSPulseInference) AnomalyDetect(input [][]float64) ([]float64, error)

AnomalyDetect returns anomaly scores per timestep. Input is preprocessed with per-channel normalization. For robust scoring, a sliding window with stride = context_len/2 is used and reconstruction errors are averaged across overlapping windows.

Input: [][]float64 with shape [timesteps][channels]. Output: []float64 with shape [timesteps] (anomaly score per timestep).

func (*TSPulseInference) Classify added in v1.21.0 

func (t *TSPulseInference) Classify(input [][]float64) ([]float64, error)

Classify returns class probabilities. Input is preprocessed with per-channel normalization and optionally resampled to 512 steps via linear interpolation if the input length differs from context_len.

Input: [][]float64 with shape [timesteps][channels]. Output: []float64 with shape [num_classes].

func (*TSPulseInference) Config added in v1.21.0 

func (t *TSPulseInference) Config() *TSPulseConfig

Config returns the TSPulse configuration.

func (*TSPulseInference) Embed added in v1.21.0 

func (t *TSPulseInference) Embed(input [][]float64) ([]float64, error)

Embed returns the semantic embedding vector for similarity search. Input is preprocessed with per-channel normalization.

Input: [][]float64 with shape [timesteps][channels]. Output: []float64 with shape [d_model].

func (*TSPulseInference) Impute added in v1.21.0 

func (t *TSPulseInference) Impute(input [][]float64, mask []bool) ([][]float64, error)

Impute fills missing values in the time series. Input is preprocessed with per-channel normalization, and the output is denormalized back to the original scale.

Input: [][]float64 with shape [context_len][channels]. mask: []bool with shape [context_len] where true indicates missing values. Output: [][]float64 with shape [context_len][channels].

type TSPulseModel added in v1.21.0 

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

TSPulseModel wraps the TSPulse architecture for multi-task inference.

func LoadTSPulse added in v1.21.0 

func LoadTSPulse(path string, opts ...Option) (*TSPulseModel, error)

LoadTSPulse loads a TSPulse model from a GGUF file and returns an inference-ready multi-task model.

func (*TSPulseModel) AnomalyDetect added in v1.21.0 

func (m *TSPulseModel) AnomalyDetect(input [][]float64) ([]float64, error)

AnomalyDetect returns anomaly scores per timestep. Input: [][]float64 [context_len][channels] Output: []float64 [context_len] (reconstruction error per timestep)

func (*TSPulseModel) Classify added in v1.21.0 

func (m *TSPulseModel) Classify(input [][]float64) ([]float64, error)

Classify returns class probabilities. Input: [][]float64 [context_len][channels] Output: []float64 [num_classes]

func (*TSPulseModel) Config added in v1.21.0 

func (m *TSPulseModel) Config() *TSPulseConfig

Config returns the TSPulse configuration.

func (*TSPulseModel) Embed added in v1.21.0 

func (m *TSPulseModel) Embed(input [][]float64) ([]float64, error)

Embed returns the semantic embedding vector for similarity search. Input: [][]float64 [context_len][channels] Output: []float64 [d_model]

func (*TSPulseModel) Impute added in v1.21.0 

func (m *TSPulseModel) Impute(input [][]float64, mask []bool) ([][]float64, error)

Impute fills missing values in the time series. Input: [][]float64 [context_len][channels], mask []bool [context_len] (true=missing) Output: [][]float64 [context_len][channels] (reconstructed at masked positions, original elsewhere)

type TSPulseTask added in v1.21.0 

type TSPulseTask int

TSPulseTask identifies which inference task to run. 

const (
	// TSPulseAnomalyDetect computes per-timestep anomaly scores via reconstruction error.
	TSPulseAnomalyDetect TSPulseTask = iota
	// TSPulseClassify produces class probabilities from semantic embeddings.
	TSPulseClassify
	// TSPulseImpute fills missing values using reconstruction from fine-grained embeddings.
	TSPulseImpute
	// TSPulseEmbed returns the semantic embedding vector for similarity search.
	TSPulseEmbed
)

type TTMConfig added in v1.21.0 

type TTMConfig struct {
	ContextLen     int  // input context window length
	ForecastLen    int  // output forecast horizon
	NumChannels    int  // number of input/output channels (variables)
	PatchLen       int  // patch size for adaptive patching
	NumPatches     int  // number of patches (ContextLen / PatchLen)
	DModel         int  // model hidden dimension
	NumMixerLayers int  // number of TSMixer blocks in the encoder backbone
	ChannelMixing  bool // if true, include feature-mixing MLP in TSMixer blocks
	Expansion      int  // MLP expansion factor, default 2
	NumExogenous   int  // number of future exogenous channels (0 = none)
	NumStatic      int  // number of static categorical features (0 = none)
}

TTMConfig holds configuration for building a TTM computation graph.

type TTMInference added in v1.21.0 

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

TTMInference provides high-level TTM inference with per-channel standard scaling normalization and batch support. It wraps a compiled TTMModel and handles input normalization, forward pass, and output denormalization.

func NewTTMInference added in v1.21.0 

func NewTTMInference(modelPath string, opts ...Option) (*TTMInference, error)

NewTTMInference creates a TTM inference instance from a GGUF model path. The model is loaded, compiled, and ready for inference upon return.

func (*TTMInference) Config added in v1.21.0 

func (t *TTMInference) Config() *TTMConfig

Config returns the TTM configuration.

func (*TTMInference) Forecast added in v1.21.0 

func (t *TTMInference) Forecast(input [][]float64) ([][]float64, error)

Forecast produces normalized forecasts from raw time series input. Input shape: [context_len][channels] as [][]float64. Output shape: [forecast_len][channels] as [][]float64.

The pipeline:

  1. Per-channel standard scaling: x_norm = (x - mean) / (std + 1e-8)
  2. Forward pass through TTM graph
  3. Denormalize forecast: y = y_norm * (std + 1e-8) + mean

func (*TTMInference) ForecastBatch added in v1.21.0 

func (t *TTMInference) ForecastBatch(inputs [][][]float64) ([][][]float64, error)

ForecastBatch produces forecasts for multiple time series in a batch. Input shape: [batch][context_len][channels] as [][][]float64. Output shape: [batch][forecast_len][channels] as [][][]float64.

func (*TTMInference) ForecastWithExogenous added in v1.21.0 

func (t *TTMInference) ForecastWithExogenous(input [][]float64, exogenous [][]float64) ([][]float64, error)

ForecastWithExogenous produces forecasts using future known exogenous variables. Input shape: [context_len][channels] as [][]float64. Exogenous shape: [forecast_len][num_exog] as [][]float64. Output shape: [forecast_len][channels] as [][]float64.

type TTMModel added in v1.21.0 

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

TTMModel wraps a compiled TTM computation graph for inference.

func LoadTTM added in v1.21.0 

func LoadTTM(path string, opts ...Option) (*TTMModel, error)

LoadTTM loads a TTM model from a GGUF file and returns an inference-ready model.

func (*TTMModel) Config added in v1.21.0 

func (m *TTMModel) Config() *TTMConfig

Config returns the TTM configuration.

func (*TTMModel) Forecast added in v1.21.0 

func (m *TTMModel) Forecast(input [][]float64) ([][]float64, error)

Forecast runs inference on the loaded TTM model. Input is [context_len][channels] and output is [forecast_len][channels].

func (*TTMModel) ForecastWithExogenous added in v1.21.0 

func (m *TTMModel) ForecastWithExogenous(input [][]float64, exogenous [][]float64) ([][]float64, error)

ForecastWithExogenous runs inference with future exogenous variables. Input is [context_len][channels], exogenous is [forecast_len][num_exog]. Output is [forecast_len][channels].

type TTMVariant added in v1.21.0 

type TTMVariant struct {
	Name        string // e.g., "ttm-512-96"
	ContextLen  int
	ForecastLen int
}

TTMVariant describes a known TTM model variant with its context and forecast lengths.

type TimeSeriesSignalConfig 

type TimeSeriesSignalConfig struct {
	PatchLen      int // ts.signal.patch_len
	Stride        int // ts.signal.stride (defaults to PatchLen if absent)
	InputFeatures int // ts.signal.input_features
	HiddenDim     int // ts.signal.hidden_dim (default 128)
	NumHeads      int // ts.signal.num_heads (default 8)
	NumLayers     int // ts.signal.num_layers (default 6)
	HorizonLen    int // ts.signal.horizon_len (default 1)
}

TimeSeriesSignalConfig holds signal processing parameters loaded from GGUF metadata for time-series models.

func LoadPatchTSTFromGGUF 

func LoadPatchTSTFromGGUF[T tensor.Numeric](path string, engine compute.Engine[T], build PatchTSTBuilder[T]) (*graph.Graph[T], TimeSeriesSignalConfig, error)

LoadPatchTSTFromGGUF loads a PatchTST model from a GGUF file. It parses the file header, extracts ts.signal.* metadata, and delegates graph construction to the provided builder function.

func LoadTimeSeriesSignalConfig 

func LoadTimeSeriesSignalConfig(meta map[string]interface{}) (TimeSeriesSignalConfig, error)

LoadTimeSeriesSignalConfig extracts TimeSeriesSignalConfig from a GGUF metadata map. Required keys are ts.signal.patch_len and ts.signal.input_features; all others have defaults.

Source Files

View all Source files

Directories

Path Synopsis
Package features provides a feature store for the Wolf time-series ML platform.
 Package features provides a feature store for the Wolf time-series ML platform.

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.