pyshred.models package#
Subpackages#
- pyshred.models.decoder_models package
- pyshred.models.latent_forecaster_models package
- pyshred.models.sequence_models package
Submodules#
pyshred.models.shred module#
- class pyshred.models.shred.SHRED(sequence_model: AbstractSequence = None, decoder_model: AbstractDecoder = None, latent_forecaster: AbstractLatentForecaster = None)[source]#
Bases:
ModuleSHallow 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