Dilated Convolutional Models#

Models that use dilated 1D convolutions for multi-scale time series representations. All three share PoolingEncodingMixin for sliding-window, multi-resolution encoding.

TS2Vec#

Hierarchical contrastive learning via progressively dilated convolutions.

class chronocratic.models.convolutional.dilated.ts2vec.model.TS2Vec(*, input_dim: int, augmentation: AugmentationProducer[AlignedPair] | None = None, hidden_dim: int = 64, representation_dim: int = 320, depth: int = 10, dropout_rate: float = 0.1, conv_kernel_size: int = 3, mask_mode: MaskMode = MaskMode.BINOMIAL, learning_rate: float = 0.001, max_train_length: int | None = None, temporal_unit: int = 0, sync_dist: bool = False)#

Bases: LightningModule, PoolingEncodingMixin

TS2Vec model.

Learns ordered representation through hierarchical contrastive learning at multiple scales. Uses dilated convolutions with masking strategies for self-supervised pretraining.

Parameters:

  • input_dim – Number of input features (channels).

  • augmentation – Custom augmentation producer. Defaults to CropShiftProducer.

  • hidden_dim – Number of hidden units in each encoder layer.

  • representation_dim – Number of output features produced by the encoder.

  • depth – Number of encoder layers.

  • dropout_rate – Dropout probability applied after each encoder layer.

  • conv_kernel_size – Size of the convolutional kernel in each layer.

  • mask_mode – Strategy for masking input tokens during training.

  • learning_rate – Base learning rate for the optimizer.

  • max_train_length – Maximum sequence length; longer samples are truncated. None means no limit.

  • temporal_unit – Token-level temporal unit index.

  • sync_dist – Whether to synchronize metrics across distributed processes.

Code source: zhihanyue/ts2vec

property representation_dim: int#

Return the feature dim of the encode() output.

This is the width of the representation vector produced by the encoder, matching the representation_dim configuration parameter.

property encoder: TS2VecTimeSeriesEncoder#

Return the averaged encoder used for inference.

Matches the module returned by _get_encoder() so that the HasEncoder protocol is consistent with the encode() path.

configure_optimizers() → AdamW#

Return the AdamW optimizer for the TS2Vec encoder.

training_step(batch: Tensor | tuple[Tensor, ...], batch_idx: int) → Tensor#

Run one TS2Vec training step with manual optimization.

validation_step(batch: Tensor | tuple[Tensor, ...], batch_idx: int) → Tensor#

Compute and log the TS2Vec validation loss.

Configuration for the TS2Vec model.

Provides TS2VecModelParameters with all TS2Vec-specific runtime settings: mask mode, learning rate, training length cap, temporal unit, and distributed-sync flag.

class chronocratic.models.convolutional.dilated.ts2vec.config.TS2VecModelParameters(*, input_dim: int, hidden_dim: int = 64, representation_dim: int = 320, depth: int = 10, dropout_rate: float = 0.1, conv_kernel_size: int = 3, mask_mode: MaskMode = MaskMode.BINOMIAL, learning_rate: float = 0.001, max_train_length: int | None = None, temporal_unit: int = 0, sync_dist: bool = False)#

Bases: object

Configuration for the TS2Vec model.

Parameters:

  • input_dim – Number of input features (channels) in the time series.

  • hidden_dim – Number of hidden units in each encoder layer.

  • representation_dim – Number of output features produced by the encoder.

  • depth – Number of encoder layers.

  • dropout_rate – Dropout probability applied after each encoder layer.

  • conv_kernel_size – Size of the convolutional kernel in each layer.

  • mask_mode – Strategy for masking input tokens during training.

  • learning_rate – Base learning rate for the optimizer.

  • max_train_length – Maximum sequence length; longer samples are truncated. None means no limit.

  • temporal_unit – Token-level temporal unit index.

  • sync_dist – Whether to synchronize metrics across distributed processes.

CoST#

Contrastive Seasonality-Trend decomposition for time series pretraining.

class chronocratic.models.convolutional.dilated.cost.model.CoST(*, input_dim: int, sequence_length: int, kernel_sizes: tuple[int, ...] = (1, 2, 4, 8, 16, 32, 64, 128), augmentation: AugmentationProducer[ViewPair] | None = None, max_train_length: int = 201, hidden_dim: int = 64, representation_dim: int = 320, depth: int = 10, dropout_rate: float = 0.1, conv_kernel_size: int = 3, mask_mode: MaskMode = MaskMode.BINOMIAL, learning_rate: float = 0.001, seasonal_loss_weight: float = 0.0005, queue_size: int = 256, momentum: float = 0.999, temperature: float = 0.07, sync_dist: bool = False)#

Bases: LightningModule, DecompositionEncodingMixin

CoST model.

Performs seasonal-trend decomposition via DWT-based multi-scale convolutions and learns representations through instance-level contrastive learning with a memory queue.

Parameters:

  • input_dim – Number of input features (channels).

  • sequence_length – Length of each input time series sample.

  • kernel_sizes – DWT decomposition levels as kernel sizes.

  • augmentation – Custom augmentation producer. Defaults to CosTRandomFunctionAugmentation.

  • max_train_length – Maximum sequence length for training samples.

  • hidden_dim – Number of hidden units in each encoder layer.

  • representation_dim – Number of output features produced by the encoder.

  • depth – Number of encoder layers.

  • dropout_rate – Dropout probability applied after each encoder layer.

  • conv_kernel_size – Convolutional kernel size in the dilated encoder.

  • mask_mode – Strategy for masking input tokens during training.

  • learning_rate – Base learning rate for the optimizer.

  • seasonal_loss_weight – Weight for the seasonal contrastive loss term.

  • queue_size – Size of the memory queue for contrastive learning.

  • momentum – Momentum coefficient for the key encoder update.

  • temperature – Temperature scaling for the contrastive loss.

  • sync_dist – Whether to synchronize metrics across distributed processes.

Code source: salesforce/CoST

property representation_dim: int#

Return the full width of the encode() representation.

For CoST, this is the representation_dim config value (trend + season concatenated internally), not component_dim.

on_fit_start() → None#

Initialize the numpy RNG after the trainer has set the PyTorch seed.

property encoder: Module#

Return the query encoder for inspection and checkpointing.

configure_optimizers() → SGD#

Return SGD optimizer over trainable query encoder and projection head parameters.

training_step(batch: Tensor | tuple[Tensor, ...], batch_idx: int) → Tensor#

Augment the batch twice, compute the contrastive loss, perform a manual update step.

validation_step(batch: Tensor | tuple[Tensor, ...], batch_idx: int) → Tensor#

Compute and log the contrastive validation loss without updating model parameters.

Configuration for the CoST model.

Provides CoSTModelParameters with CoST-specific settings including seasonal-trend decomposition encoder parameters and contrastive learning configuration.

class chronocratic.models.convolutional.dilated.cost.config.CoSTModelParameters(*, input_dim: int, sequence_length: int, kernel_sizes: tuple[int, ...] = (1, 2, 4, 8, 16, 32, 64, 128), max_train_length: int = 201, hidden_dim: int = 64, representation_dim: int = 320, depth: int = 10, dropout_rate: float = 0.1, conv_kernel_size: int = 3, mask_mode: MaskMode = MaskMode.BINOMIAL, learning_rate: float = 0.001, seasonal_loss_weight: float = 0.0005, queue_size: int = 256, momentum: float = 0.999, temperature: float = 0.07, sync_dist: bool = False)#

Bases: object

Configuration for the CoST model.

Parameters:

  • input_dim – Number of input features (channels) in the time series.

  • sequence_length – Length of each input time series sample.

  • kernel_sizes – DWT decomposition levels as kernel sizes.

  • max_train_length – Maximum sequence length for training samples.

  • hidden_dim – Number of hidden units in each encoder layer.

  • representation_dim – Number of output features produced by the encoder (the size of the encode() representation).

  • depth – Number of encoder layers.

  • dropout_rate – Dropout probability applied after each encoder layer.

  • conv_kernel_size – Convolutional kernel size in the dilated encoder. Defaults to 3 matching the source CoST implementation.

  • mask_mode – Strategy for masking input tokens during training.

  • learning_rate – Base learning rate for the optimizer.

  • seasonal_loss_weight – Weight for the seasonal contrastive loss term.

  • queue_size – Size of the memory queue for contrastive learning. The source repo’s CoSTModel class defines K=65536 as its constructor default, but the training wrapper always passes K=256 explicitly. We use 256 to match the authors’ actual usage rather than the unused class default.

  • momentum – Momentum coefficient for the key encoder update.

  • temperature – Temperature scaling for the contrastive loss.

  • sync_dist – Whether to synchronize metrics across distributed processes.

AutoTCL#

Adversarial unsupervised contrastive learning with trainable augmentation.

class chronocratic.models.convolutional.dilated.autotcl.model.AutoTCL(*, input_dim: int, kernel_sizes: tuple[int, ...] = (3, 5, 7), augmentation: AugmentationProducer[SingleView] | None = None, hidden_dim: int = 64, representation_dim: int = 320, depth: int = 10, dropout_rate: float = 0.1, conv_kernel_size: int = 3, mask_mode: MaskMode = MaskMode.BINOMIAL, learning_rate: float = 0.001, max_train_length: int | None = None, meta_learning_rate: float = 0.01, local_loss_weight: float = 0.1, info_nce_loss_temperature: float = 1.0, sync_dist: bool = False)#

Bases: LightningModule, PoolingEncodingMixin

AutoTCL model.

Learns representations via hierarchical contrastive loss and a trainable neural augmentation network. Uses DWT-based multi-scale decomposition for feature extraction.

Parameters:

  • input_dim – Number of input features (channels).

  • kernel_sizes – DWT decomposition levels as kernel sizes.

  • augmentation – Custom augmentation producer. Defaults to a trainable neural augmentation network.

  • hidden_dim – Number of hidden units in each encoder layer.

  • representation_dim – Width of the vector encode() returns.

  • depth – Number of encoder layers.

  • dropout_rate – Dropout probability applied after each encoder layer.

  • conv_kernel_size – Size of the convolutional kernel in each layer.

  • mask_mode – Strategy for masking input tokens during training.

  • learning_rate – Base learning rate for the optimizer.

  • max_train_length – Maximum sequence length; longer samples are truncated. None means no limit.

  • meta_learning_rate – Learning rate for the augmentation network optimizer.

  • local_loss_weight – Weight for the local InfoNCE loss term in the encoder contrastive loss.

  • info_nce_loss_temperature – Temperature scaling for the global InfoNCE contrastive loss.

  • sync_dist – Whether to synchronize metrics across distributed processes.

Code source: AslanDing/AutoTCL

property representation_dim: int#

Return the feature dim of the encode() output.

property encoder: AutoTCLTimeSeriesEncoder#

Return the averaged encoder used for inference.

Matches the module returned by _get_encoder() so that the HasEncoder protocol is consistent with the encode() path.

configure_optimizers() → AdamW | list[AdamW]#

Return encoder optimizer(s); two optimizers when using trainable aug.

training_step(batch: Tensor | tuple[Tensor, ...], batch_idx: int) → Tensor | None#

Run one AutoTCL training step with manual optimization.

Two-phase training: 1. Aug network self-training (via centralized maybe_train_augmentation gate). 2. Uniform encoder training (all augmentation types).

validation_step(batch: Tensor | tuple[Tensor, ...], batch_idx: int) → Tensor#

Compute validation contrastive loss using the averaged encoder.

Configuration for the AutoTCL model.

Provides AutoTCLModelParameters with AutoTCL-specific settings: DWT kernel sizes for multi-scale feature extraction, mask mode, learning rate, training length cap, and distributed-sync flag.

class chronocratic.models.convolutional.dilated.autotcl.config.AutoTCLModelParameters(*, input_dim: int, kernel_sizes: tuple[int, ...] = (1, 2, 4, 8, 16, 32, 64, 128), hidden_dim: int = 64, representation_dim: int = 320, depth: int = 10, dropout_rate: float = 0.1, conv_kernel_size: int = 3, mask_mode: MaskMode = MaskMode.BINOMIAL, learning_rate: float = 0.001, max_train_length: int | None = None, info_nce_loss_temperature: float = 1.0, meta_learning_rate: float = 0.01, local_loss_weight: float = 0.1, sync_dist: bool = False)#

Bases: object

Configuration for the AutoTCL model.

Parameters:

  • input_dim – Number of input features (channels) in the time series.

  • kernel_sizes – DWT decomposition levels as kernel sizes.

  • hidden_dim – Number of hidden units in each encoder layer.

  • representation_dim – Width of the vector encode() returns.

  • depth – Number of encoder layers.

  • dropout_rate – Dropout probability applied after each encoder layer.

  • conv_kernel_size – Size of the convolutional kernel in each layer.

  • mask_mode – Strategy for masking input tokens during training.

  • learning_rate – Base learning rate for the optimizer.

  • max_train_length – Maximum sequence length; longer samples are truncated. None means no limit.

  • meta_learning_rate – Learning rate for the augmentation network optimizer.

  • local_loss_weight – Weight for the local InfoNCE loss term in the encoder contrastive loss.

  • info_nce_loss_temperature – Temperature scaling for the global InfoNCE contrastive loss. Defaults to 1.0 matching the source AutoTCL implementation.

  • sync_dist – Whether to synchronize metrics across distributed processes.