Module dlkoopman.state_pred

State Predictor.

StatePred can be used to train on given states of a system at given indexes, then predict unknown states of the system at new indexes. See a specific example and tutorial here.

Classes

class StatePredDataHandler (Xtr, ttr, Xva=None, tva=None, Xte=None, tte=None, cfg=None)

State predictor data handler. Used to provide data to train (and optionally validate and test) the StatePred model.

Parameters

• Xtr (Array[float], shape=(num_training_indexes, input_size)) - Input states to be used as training data. Array can be any data type such as numpy.array, torch.Tensor, list etc.

• ttr (Array[int,float], shape=(num_training_indexes,)) - Indexes of the states in Xtr. Array can be any data type such as numpy.array, torch.Tensor, list, range, etc.

  • ttr must be in ascending order and should ideally be equally spaced. The 1st value of ttr will be used as the baseline index.
  • Small deviations are okay, e.g. [100, 203, 298, 400, 500] will become [100, 200, 300, 400, 500], but larger deviations that cannot be unambiguously rounded will lead to errors.

• Xva (Array[float], shape=(num_validation_indexes, input_size), optional) - Input states to be used as validation data. Same data type requirements as Xtr.

• tva (Array[int,float], shape=(num_validation_indexes,), optional) - Indexes of the states in Xva. Same data type requirements as ttr.

  • The order and spacing restrictions on ttr do not apply. The values of these indexes can be anything.

• Xte (Array[float], shape=(num_test_indexes, input_size), optional) - Input states to be used as test data. Same data type requirements as Xtr.

• tte (Array[int,float], shape=(num_test_indexes,), optional) - Indexes of the states in Xte. Same data type requirements as ttr.

  • The order and spacing restrictions on ttr do not apply. The values of these indexes can be anything.

• cfg (dlkoopan.config.Config, optional) - Leave this as None to use the default configuration options. If changing any configuration option(s) is desired, create a separate Config instance and pass that as an argument (see example below).

Example

# Provide data of a system with 3-dimensional states (i.e. input_size=3)
# Provide data at 4 indexes for training, and 2 indexes each for validation and testing
# Use a custom configuration with double data types on CPU only

from dlkoopman.config import Config
cfg = Config(precision="double", use_cuda=False)

dh = StatePredDataHandler(
    ttr = [100, 203, 298, 400], # ascending order, (almost) equally spaced
    Xtr = numpy.array([
        [0.7, 2.1, 9.2], # state at index 100
        [1.1, 5. , 6.1], # state at index 203
        [4.3, 2. , 7.3], # state at index 298
        [6.1, 4.2, 0.3]  # state at index 400
    ]),
    tva = [66, 238], # anything
    Xva = numpy.array([
        [3.8, 1.7, 0.4], # state at index 66
        [7.6, 6.5, 9.3]  # state at index 238
    ]),
    tte = [-32, 784], # anything
    Xte = numpy.array([
        [9.8, 8.9, 0.2], # state at index -32
        [7.3, 4.8, 7.5]  # state at index 784
    ]),
    cfg = cfg
)

class StatePred (dh, rank, encoded_size, encoder_hidden_layers=[100], decoder_hidden_layers=[], batch_norm=False)

State predictor. Used to train on given states of a system at given indexes, then predict unknown states of the system at new indexes.

Parameters

• dh (StatePredDataHandler) - Data handler that feeds data. Configuration options of a StatePred instance are identical to dh.cfg.

• rank (int) - Rank of SVD operation to compute Koopman matrix. Use 0 for full rank. Will be set to min(encoded_size, num_training_indexes-1) if the provided value is greater.

• Parameters for AutoEncoder:

  • encoded_size (int).

  • encoder_hidden_layers (list[int], optional).

  • decoder_hidden_layers (list[int], optional).

  • batch_norm (bool, optional).

Attributes

• uuid (str) - Unique ID assigned to this instance. Results will include uuid in their filename.

• log_file (Path) - Path to log file = ./log_<uuid>.log.

• input_size (int) - Dimensionality of input states. Inferred from dh.Xtr.

• encoded_size (int) - Dimensionality of encoded states. As given in input.

• ae (nets.AutoEncoder) - AutoEncoder neural network to encode input states into a linearizable domain where the Koopman matrix can be learnt, then decode them back into original domain.

• Omega (torch.Tensor), eigvecs (torch.Tensor) - Eigenvalues, and eigenvectors of the trained Koopman matrix that characterizes the continuous index system $\frac{dy}{di} = Ky_i$. These are used to make predictions.

• y0 (torch.Tensor) - Encoded state at the baseline index, which is evolved using Omega and eigvecs to get predictions for any index.

• stats (dict[list]) - Stores different metrics from training and testing. Useful for checking performance and plotting.

• error_flag (bool) - Signals if any error has occurred in training.

Methods

def train_net(self, numepochs=500, early_stopping=0, early_stopping_metric='pred_anae', lr=0.001, weight_decay=0.0, decoder_loss_weight=0.01, Kreg=0.001, cond_threshold=100.0, clip_grad_norm=None, clip_grad_value=None)

Train the model using dh.Xtr and dh.ttr, and validate it on dh.Xva and dh.tva.

Parameters

• numepochs (int, optional) - Number of epochs for which to train. Each epoch uses the complete training data to learn the Koopman matrix.

• early_stopping (int/float, optional) - Whether to terminate training early due to no improvement in validation metric.

  • If 0, no early stopping. The model will run for the complete numepochs epochs.
  • If an integer, early stop if validation metric doesn't improve for that many epochs.
  • If a float, early stop if validation performance doesn't improve for that fraction of epochs, rounded up.

• early_stopping_metric (str, optional) - Which validation metric to use for early stopping. Ignored if early_stopping=False. Possible metrics are '<recon/lin/pred/total>_loss', and '<recon/lin/pred>_anae'.

• lr (float, optional) - Learning rate for optimizer.

• weight_decay (float, optional) - L2 coefficient for weights of the neural nets.

• decoder_loss_weight (float, optional) - Weight the losses between autoencoder decoder outputs (recon and pred) by this number. This is to account for the scaling effect of the decoder.

• Kreg (float, optional) - L1 penalty for the Ktilde matrix.

• cond_threshold (float, optional) - Condition number of the eigenvector matrix greater than this will be reported, and singular values smaller than this fraction of the largest will be ignored for the pseudo-inverse operation.

• clip_grad_norm (float, optional) - If not None, clip the norm of gradients to this value.

• clip_grad_value (float, optional) - If not None, clip the values of gradients to [-clip_grad_value,clip_grad_value].

Effects

• self.stats is populated.
• self.Omega and self.eigvecs hold the eigendecomposition of the Koopman matrix learnt during training, which can be used to predict any state by evolving self.y0.

def test_net(self)

Run the trained model on test data - dh.Xte and dh.tte.

Effects

• self.stats is populated further.

def predict_new(self, t) ‑> torch.Tensor

Use the trained model to predict the states for new indexes that are unknown.

This is different from testing because the ground truth values are not present, thus losses and errors are not computed. This method can be used to make predictions for interpolated and extrapolated indexes.

Parameters

• t (Array[int,float], shape=(num_new_indexes,)) - Indexes for which unknown states should be predicted. Array can be any data type such as numpy.array, torch.Tensor, list, range, etc.

Returns

Xpred (torch.Tensor, shape=(len(t), input_size)) - Predicted states for the new indexes.