Example 00: Your First Model in 5 Lines¶

System identification is the problem of learning a mathematical model of a dynamical system from measured input-output data. Think of it as teaching a neural network to predict how a physical system responds to a given input signal. TSFast helps you do exactly that: load time-series data, train a recurrent neural network, and evaluate predictions -- all in a few lines of code. In this example, you will load a benchmark dataset, train an LSTM, and evaluate its predictions -- a core workflow of just 5 lines: create DataLoaders, build a Learner, fit, plot results, validate.

Prerequisites¶

This is the entry point to the TSFast curriculum -- no prior examples required. Make sure the library is installed:

uv sync --extra dev

Setup¶

We use explicit imports so you can see exactly where each function comes from.

In [1]:

from tsfast.tsdata.benchmark import create_dls_silverbox
from tsfast.training import RNNLearner

from tsfast.tsdata.benchmark import create_dls_silverbox from tsfast.training import RNNLearner

Load the Silverbox Dataset¶

The Silverbox is a benchmark electronic circuit that exhibits nonlinear behaviour. It is widely used in the system identification community to evaluate modelling approaches. create_dls_silverbox downloads the dataset (on first use) and creates PyTorch DataLoaders with sliding windows.

Key parameters:

• bs=16 -- batch size, the number of windows processed in parallel during each training step.
• win_sz=500 -- window length in time steps. Each training sample is a 500-step slice of the full signal.
• stp_sz=10 -- step size (stride) between consecutive windows. Smaller values produce more overlapping windows and thus more training samples.

In [2]:

dls = create_dls_silverbox(bs=16, win_sz=500, stp_sz=10)

dls = create_dls_silverbox(bs=16, win_sz=500, stp_sz=10)

Create and Train an LSTM Model¶

RNNLearner creates a recurrent neural network wrapped in a Learner, ready for training. Setting rnn_type='lstm' selects Long Short-Term Memory cells, which are effective at capturing temporal dependencies. The model maps input sequences to output sequences of the same length.

In [3]:

lrn = RNNLearner(dls, rnn_type='lstm')

lrn = RNNLearner(dls, rnn_type='lstm')

Inspect the Data¶

show_batch displays a few random windows from the validation set. Each subplot shows one window: the bottom panel is the input signal and the upper panel is the output signal that we want the model to learn to predict.

In [4]:

lrn.show_batch(max_n=4)

lrn.show_batch(max_n=4)

fit_flat_cos trains the model with a flat-then-cosine-annealing learning rate schedule: the learning rate stays constant for most of training, then smoothly decays to zero. n_epoch=5 means 5 complete passes through the training data.

In [5]:

lrn.fit_flat_cos(n_epoch=5)

lrn.fit_flat_cos(n_epoch=5)

Epoch 1/5:   0%|          | 0/300 [00:00<?, ?it/s]

Epoch 1/5:  48%|████▊     | 145/300 [00:00<00:00, 289.71it/s]

Epoch 1/5: 100%|██████████| 300/300 [00:00<00:00, 289.71it/s, train=0.0119 | valid=0.0066 | fun_rmse=0.0112]

Epoch 1/5: 100%|██████████| 300/300 [00:00<00:00, 333.92it/s, train=0.0119 | valid=0.0066 | fun_rmse=0.0112]

Epoch 2/5:   0%|          | 0/300 [00:00<?, ?it/s]

Epoch 2/5:  66%|██████▋   | 199/300 [00:00<00:00, 397.37it/s]

Epoch 2/5: 100%|██████████| 300/300 [00:00<00:00, 397.37it/s, train=0.0056 | valid=0.0073 | fun_rmse=0.0117]

Epoch 2/5: 100%|██████████| 300/300 [00:00<00:00, 399.09it/s, train=0.0056 | valid=0.0073 | fun_rmse=0.0117]

Epoch 3/5:   0%|          | 0/300 [00:00<?, ?it/s]

Epoch 3/5:  66%|██████▋   | 199/300 [00:00<00:00, 397.35it/s]

Epoch 3/5: 100%|██████████| 300/300 [00:00<00:00, 397.35it/s, train=0.0055 | valid=0.0068 | fun_rmse=0.0114]

Epoch 3/5: 100%|██████████| 300/300 [00:00<00:00, 394.36it/s, train=0.0055 | valid=0.0068 | fun_rmse=0.0114]

Epoch 4/5:   0%|          | 0/300 [00:00<?, ?it/s]

Epoch 4/5:  69%|██████▊   | 206/300 [00:00<00:00, 410.40it/s]

Epoch 4/5: 100%|██████████| 300/300 [00:00<00:00, 410.40it/s, train=0.0049 | valid=0.0077 | fun_rmse=0.0118]

Epoch 4/5: 100%|██████████| 300/300 [00:00<00:00, 408.59it/s, train=0.0049 | valid=0.0077 | fun_rmse=0.0118]

Epoch 5/5:   0%|          | 0/300 [00:00<?, ?it/s]

Epoch 5/5:  66%|██████▌   | 198/300 [00:00<00:00, 394.60it/s]

Epoch 5/5: 100%|██████████| 300/300 [00:00<00:00, 394.60it/s, train=0.0035 | valid=0.0029 | fun_rmse=0.0095]

Epoch 5/5: 100%|██████████| 300/300 [00:00<00:00, 395.66it/s, train=0.0035 | valid=0.0029 | fun_rmse=0.0095]

Visualize Predictions¶

show_results overlays model predictions (orange) on ground truth (blue). Good predictions closely track the true output signal.

In [6]:

lrn.show_results(max_n=3)

lrn.show_results(max_n=3)

Evaluate the Model¶

validate runs the model on the full validation set and returns a tuple of (loss, {metric_name: value}) -- RMSE by default.

In [7]:

val_loss, val_metrics = lrn.validate()
print(f"Validation loss: {val_loss}")
print(f"Validation metrics: {val_metrics}")

val_loss, val_metrics = lrn.validate() print(f"Validation loss: {val_loss}") print(f"Validation metrics: {val_metrics}")

Validation loss: 0.0029002041555941105
Validation metrics: {'fun_rmse': 0.009543506428599358}

Key Takeaways¶

• Loaded a benchmark dataset with create_dls_silverbox, which handles downloading, windowing, and splitting into train/validation sets.
• Trained an LSTM for system identification using RNNLearner and fit_flat_cos.
• Visualized predictions with show_results to qualitatively assess model performance.
• Evaluated metrics with validate to get quantitative results on the validation set.

For convenience, you can also use from tsfast.basics import * which re-exports everything, but this tutorial uses explicit imports so you can see where each function comes from.