pyshred.models package#

Subpackages#

Submodules#

pyshred.models.shred module#

class pyshred.models.shred.SHRED(sequence_model: AbstractSequence = None, decoder_model: AbstractDecoder = None, latent_forecaster: AbstractLatentForecaster = None)[source]#

Bases: Module

SHallow REcurrent Decoder (SHRED) neural network architecture.

SHRED leverages a sequence model to learn a latent representation of the temporal dynamics of sensor measurements, a latent forecaster model to forecast the latent space into the future, and a decoder model to learn a mapping between the latent space and the high-dimensional full-state space. The SHRED architecture enables accurate full-state reconstructions and forecasts from limited sensors.

Parameters:
  • sequence_model (AbstractSequence or str, optional) – Sequence model instance (GRU, LSTM, Transformer) or its name. Default None → LSTM if not using SINDy_Forecaster, otherwise GRU.

  • decoder_model (AbstractDecoder or str, optional) – Decoder model instance (MLP, UNET) or its name. Default None → MLP.

  • latent_forecaster (AbstractLatentForecaster or str, optional) – Latent forecaster instance (SINDy_Forecaster, LSTM_Forecaster) or its name. Default None → no latent forecaster.

Variables:
  • sequence (AbstractSequence) – The sequence model that encodes the temporal dynamics of sensor measurements in the latent space.

  • decoder (AbstractDecoder) – The decoder model that maps the latent space back to the full‐state space.

  • latent_forecaster (AbstractLatentForecaster or None) – The latent forecaster that forecasts future latent space states. If None, no latent forecaster is used.

Examples

>>> # basic SHRED
>>> model = SHRED(sequence_model='LSTM', decoder_model='MLP', latent_forecaster='LSTM_Forecaster')
>>> # SINDy SHRED
>>> model = SHRED(sequence_model='GRU', decoder_model='MLP', latent_forecaster='SINDy_Forecaster')
evaluate(dataset: TimeSeriesDataset, batch_size: int = 64)[source]#

Compute mean squared error on a held‐out test dataset.

Parameters:
  • test_dataset (torch.utils.data.Dataset) – Should return (X, Y) pairs just like your train/val datasets.

  • batch_size (int, optional) – How many samples per batch. Defaults to 64.

Returns:

The MSE over all elements in the test set.

Return type:

float

fit(train_dataset, val_dataset, batch_size=64, num_epochs=200, lr=0.001, sindy_regularization=0, optimizer='AdamW', verbose=True, threshold=0.5, base_threshold=0.0, patience=20, sindy_thres_epoch=20, weight_decay=0.01)[source]#

Train the SHRED model on the provided datasets.

Parameters:
  • train_dataset (TimeSeriesDataset) – Training dataset containing sensor sequences and target reconstructions.

  • val_dataset (TimeSeriesDataset) – Validation dataset for monitoring training progress.

  • batch_size (int, optional) – Batch size for training. Defaults to 64.

  • num_epochs (int, optional) – Maximum number of training epochs. Defaults to 200.

  • lr (float, optional) – Learning rate. Defaults to 1e-3.

  • sindy_regularization (float, optional) – Weight for SINDy regularization term. Defaults to 0.

  • optimizer (str, optional) – Optimizer type. Defaults to “AdamW”.

  • verbose (bool, optional) – Whether to print training progress. Defaults to True.

  • threshold (float, optional) – SINDy thresholding value. Defaults to 0.5.

  • base_threshold (float, optional) – Base threshold for SINDy. Defaults to 0.0.

  • patience (int, optional) – Early stopping patience. Defaults to 20.

  • sindy_thres_epoch (int, optional) – Frequency of SINDy thresholding. Defaults to 20.

  • weight_decay (float, optional) – Weight decay for optimizer. Defaults to 0.01.

Returns:

Array of validation errors for each epoch.

Return type:

np.ndarray

forward(x, sindy=False)[source]#

Forward pass through the SHRED model.

Parameters:
  • x (torch.Tensor) – Input sensor sequences of shape (batch_size, lags, n_sensors).

  • sindy (bool, optional) – Whether to compute SINDy regularization terms. Defaults to False.

Returns:

If sindy=False: Reconstructed full-state tensor. If sindy=True: Tuple of (reconstruction, target_latents, predicted_latents).

Return type:

torch.Tensor or tuple

Module contents#