timeseries

package
v1.25.2 Latest Latest
Warning

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

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

Documentation

Overview

Package timeseries provides time-series specific neural network layers.

Stability: alpha

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type DualSpaceEncoder added in v1.21.0 

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

DualSpaceEncoder processes time series in both time and frequency domains, following the dual-space masked reconstruction approach from IBM Granite TSPulse.

The encoder splits input into patches, then processes them through two parallel paths — one in the time domain and one in the frequency domain (via DFT). The results are fused via concatenation and linear projection to produce embeddings that capture both temporal patterns and spectral characteristics.

func NewDualSpaceEncoder added in v1.21.0 

func NewDualSpaceEncoder[T tensor.Float](
	engine compute.Engine[T],
	ops numeric.Arithmetic[T],
	dModel, patchLen, numLayers int,
) (*DualSpaceEncoder[T], error)

NewDualSpaceEncoder creates a new dual-space encoder.

Parameters:

  • engine: compute engine for tensor operations
  • ops: arithmetic operations for the numeric type
  • dModel: model embedding dimension
  • patchLen: length of each time-domain patch
  • numLayers: number of transformer encoder layers in each path

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

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

Forward processes the input through both time and frequency domain paths, fuses the results, and returns fine-grained and semantic embeddings.

Input shape: [batch, seqLen] where seqLen is divisible by patchLen (or will be padded). Output: DualSpaceOutput with FineGrained [batch, numPatches, dModel] and Semantic [batch, dModel].

func (*DualSpaceEncoder[T]) Parameters added in v1.21.0 

func (e *DualSpaceEncoder[T]) Parameters() []*graph.Parameter[T]

Parameters returns all trainable parameters of the dual-space encoder.

type DualSpaceOutput added in v1.21.0 

type DualSpaceOutput[T tensor.Float] struct {
	// FineGrained is the full patch-level representation [batch, numPatches, dModel].
	// Used for anomaly detection and imputation where per-timestep detail is needed.
	FineGrained *tensor.TensorNumeric[T]

	// Semantic is the mean-pooled series-level representation [batch, dModel].
	// Used for classification and similarity search.
	Semantic *tensor.TensorNumeric[T]
}

DualSpaceOutput contains both fine-grained and semantic embeddings produced by the DualSpaceEncoder.

type GRN 

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

GRN implements a Gated Residual Network: 

GRN(x) = LayerNorm(x + ELU(W1*x + b1) * sigmoid(W2*x + b2))

where LayerNorm is approximated as mean-subtraction and variance-normalization.

func NewGRN 

func NewGRN[T tensor.Numeric](
	name string,
	engine compute.Engine[T],
	ops numeric.Arithmetic[T],
	inputDim, hiddenDim, outputDim int,
) (*GRN[T], error)

NewGRN creates a new Gated Residual Network layer.

func (*GRN[T]) Forward 

func (g *GRN[T]) Forward(ctx context.Context, x *tensor.TensorNumeric[T]) (*tensor.TensorNumeric[T], error)

Forward computes GRN(x) = LayerNorm(residual + ELU(W1*x + b1) * sigmoid(W2*x + b2)) projected through wOut to outputDim. Input x: [batch, inputDim]. Output: [batch, outputDim].

func (*GRN[T]) Parameters 

func (g *GRN[T]) Parameters() []*graph.Parameter[T]

Parameters returns the trainable parameters.

type PatchEmbed 

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

PatchEmbed splits a 1D time series into non-overlapping patches and projects each patch to embed_dim using a learned linear projection.

func NewPatchEmbed 

func NewPatchEmbed[T tensor.Numeric](
	name string,
	engine compute.Engine[T],
	ops numeric.Arithmetic[T],
	patchSize, embedDim int,
) (*PatchEmbed[T], error)

NewPatchEmbed creates a new PatchEmbed layer.

func (*PatchEmbed[T]) Attributes 

func (pe *PatchEmbed[T]) Attributes() map[string]interface{}

Attributes returns the attributes of the layer.

func (*PatchEmbed[T]) Backward 

func (pe *PatchEmbed[T]) Backward(ctx context.Context, mode types.BackwardMode, outputGradient *tensor.TensorNumeric[T], inputs ...*tensor.TensorNumeric[T]) ([]*tensor.TensorNumeric[T], error)

Backward computes the gradients for the patch embedding layer.

func (*PatchEmbed[T]) Forward 

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

Forward takes [batch, seq_len] input and returns [batch, num_patches, embed_dim]. seq_len is padded with zeros if not divisible by PatchSize.

func (*PatchEmbed[T]) Name 

func (pe *PatchEmbed[T]) Name() string

Name returns the name of the layer.

func (*PatchEmbed[T]) OpType 

func (pe *PatchEmbed[T]) OpType() string

OpType returns the operation type of the layer.

func (*PatchEmbed[T]) OutputShape 

func (pe *PatchEmbed[T]) OutputShape() []int

OutputShape returns the output shape of the layer.

func (*PatchEmbed[T]) Parameters 

func (pe *PatchEmbed[T]) Parameters() []*graph.Parameter[T]

Parameters returns the trainable parameters.

func (*PatchEmbed[T]) SetName 

func (pe *PatchEmbed[T]) SetName(name string)

SetName sets the name of the layer.

type SSMLayer added in v1.21.0 

type SSMLayer[T tensor.Float] struct {

	// Learnable parameters.
	// A is stored in log-space so that the actual diagonal is -exp(A),
	// guaranteeing stability (negative real eigenvalues).
	A  *graph.Parameter[T] // [d_state]
	B  *graph.Parameter[T] // [d_state, d_input]
	C  *graph.Parameter[T] // [d_output, d_state]
	D  *graph.Parameter[T] // [d_output, d_input] feedthrough (skip connection)
	Dt *graph.Parameter[T] // [1] discretisation step size (log-space)
	// contains filtered or unexported fields
}

SSMLayer implements a State Space Model layer with diagonal state matrix.

The continuous-time system is: 

x'(t) = A*x(t) + B*u(t)   (state equation)
y(t)  = C*x(t) + D*u(t)   (output equation)

For efficient computation, the layer uses a discretized recurrence with Zero-Order Hold (ZOH). Because A is diagonal (stored as a 1-D vector), all matrix operations reduce to element-wise products: 

A_bar = exp(A * dt)
B_bar = (A_bar - 1) / A * B
x[k+1] = A_bar * x[k] + B_bar * u[k]
y[k]   = C * x[k] + D * u[k]

This is the S4D/S5-style parameterisation used by IBM Granite FlowState for time-series forecasting.

func NewSSMLayer added in v1.21.0 

func NewSSMLayer[T tensor.Float](engine compute.Engine[T], dState, dInput, dOutput int) (*SSMLayer[T], error)

NewSSMLayer creates a new State Space Model layer with diagonal state matrix.

Parameters:

  • engine: the compute engine for tensor operations
  • dState: dimensionality of the hidden state
  • dInput: dimensionality of the input at each time step
  • dOutput: dimensionality of the output at each time step

func (*SSMLayer[T]) Attributes added in v1.21.0 

func (s *SSMLayer[T]) Attributes() map[string]interface{}

Attributes returns the attributes of the layer.

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

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

Forward processes an input sequence through the SSM.

Input shape: [batch, seq_len, d_input] Output shape: [batch, seq_len, d_output]

The method performs a sequential scan (one time step at a time). A parallel scan variant can be added later for GPU optimisation.

func (*SSMLayer[T]) OpType added in v1.21.0 

func (s *SSMLayer[T]) OpType() string

OpType returns the operation type of the layer.

func (*SSMLayer[T]) OutputShape added in v1.21.0 

func (s *SSMLayer[T]) OutputShape() []int

OutputShape returns the output shape of the layer.

func (*SSMLayer[T]) Parameters added in v1.21.0 

func (s *SSMLayer[T]) Parameters() []*graph.Parameter[T]

Parameters returns all learnable parameters of the SSM layer.

type TSMixerBlock added in v1.21.0 

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

TSMixerBlock implements a single TSMixer block with time-mixing and feature-mixing MLPs. This is the backbone layer used by IBM Granite TinyTimeMixer (TTM) for time series forecasting.

Each block contains:

  • Time-mixing MLP: mixes information across the patch/time dimension
  • Feature-mixing MLP: mixes information across the feature/channel dimension
  • LayerNorm after each mixing step
  • Residual connections around each mixing step

Time-mixing transposes the input so the MLP operates along the time axis, while feature-mixing applies the MLP along the last (feature) axis directly.

func NewTSMixerBlock added in v1.21.0 

func NewTSMixerBlock[T tensor.Float](
	engine compute.Engine[T],
	ops numeric.Arithmetic[T],
	numPatches, dModel, expansion int,
	channelMixing bool,
) (*TSMixerBlock[T], error)

NewTSMixerBlock creates a new TSMixer block.

Parameters:

  • engine: the compute engine for tensor operations
  • ops: arithmetic operations for the numeric type
  • numPatches: the number of time patches (time dimension size)
  • dModel: the model/feature dimension size
  • expansion: expansion factor for the feature-mixing MLP hidden dim
  • channelMixing: if true, include the feature-mixing MLP; if false, channel-independent mode

func (*TSMixerBlock[T]) Attributes added in v1.21.0 

func (b *TSMixerBlock[T]) Attributes() map[string]interface{}

Attributes returns the attributes of the layer.

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

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

Forward computes the forward pass of the TSMixer block.

Input shape: [batch, numPatches, dModel] Output shape: [batch, numPatches, dModel]

Steps:

  1. Time-mixing: LayerNorm -> transpose -> MLP(GELU) -> transpose -> residual add
  2. Feature-mixing (if enabled): LayerNorm -> MLP(GELU) -> residual add

func (*TSMixerBlock[T]) OpType added in v1.21.0 

func (b *TSMixerBlock[T]) OpType() string

OpType returns the operation type of the layer.

func (*TSMixerBlock[T]) OutputShape added in v1.21.0 

func (b *TSMixerBlock[T]) OutputShape() []int

OutputShape returns the output shape of the layer.

func (*TSMixerBlock[T]) Parameters added in v1.21.0 

func (b *TSMixerBlock[T]) Parameters() []*graph.Parameter[T]

Parameters returns all trainable parameters of the block.

type VSN 

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

VSN implements a Variable Selection Network for the Temporal Fusion Transformer.

Each of N input variables is projected to d_model via a learned linear projection. The flat concatenation of all variable embeddings is passed through a GRN and softmax to produce N importance weights. The output is the weighted sum of the variable embeddings.

func NewVSN 

func NewVSN[T tensor.Numeric](
	name string,
	engine compute.Engine[T],
	ops numeric.Arithmetic[T],
	numVars, varInputDim, dModel int,
) (*VSN[T], error)

NewVSN creates a new Variable Selection Network. numVars is the number of input variables. varInputDim is the input dimension of each variable. dModel is the projection/output dimension.

func (*VSN[T]) Attributes 

func (v *VSN[T]) Attributes() map[string]interface{}

Attributes returns the attributes of the layer.

func (*VSN[T]) Backward 

func (v *VSN[T]) Backward(ctx context.Context, mode types.BackwardMode, outputGradient *tensor.TensorNumeric[T], inputs ...*tensor.TensorNumeric[T]) ([]*tensor.TensorNumeric[T], error)

Backward computes gradients for the VSN layer.

func (*VSN[T]) Forward 

func (v *VSN[T]) Forward(ctx context.Context, inputs []*tensor.TensorNumeric[T]) (*tensor.TensorNumeric[T], []float32, error)

Forward computes the variable selection network. inputs is a slice of N tensors, each [batch, varInputDim]. Returns (weighted_embedding [batch, dModel], importance_weights [numVars], error).

func (*VSN[T]) Name 

func (v *VSN[T]) Name() string

Name returns the name of the layer.

func (*VSN[T]) OpType 

func (v *VSN[T]) OpType() string

OpType returns the operation type of the layer.

func (*VSN[T]) OutputShape 

func (v *VSN[T]) OutputShape() []int

OutputShape returns the output shape of the layer.

func (*VSN[T]) Parameters 

func (v *VSN[T]) Parameters() []*graph.Parameter[T]

Parameters returns the trainable parameters.

func (*VSN[T]) SetName 

func (v *VSN[T]) SetName(name string)

SetName sets the name of the layer.

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.