Time Series Condition

Module for the TimeSeriesCondition class.

class TimeSeriesCondition(input, n_windows, unroll_length, randomize=False)

Bases: BaseCondition

The TimeSeriesCondition class represents an autoregressive time series condition defined by temporal input data. The input is expected to have shape [trajectories, time_steps, *features], where the second dimension corresponds to the temporal evolution of each trajectory.

During training, the condition automatically extracts overlapping temporal windows from the trajectories. The parameter unroll_length defines the number of consecutive time steps contained in each temporal window, while n_windows controls how many temporal windows are created from the available trajectories.

Internally, the unrolled data is stored as a tensor of shape [trajectories, n_windows, unroll_length, *features].

Supported data types include LabelTensor and torch.Tensor.

Example:

>>> from pina import Condition, LabelTensor
>>> import torch

>>> data = LabelTensor(torch.rand(5, 10, 2), labels=["u", "v"])
>>> condition = Condition(input=data, unroll_length=5, n_windows=3)

Initialization of the BaseCondition class.

Parameters:

kwargs (dict) – The keyword arguments representing the data to be stored in the condition.

store_data(**kwargs)

Store the unrolled time-series input data.

The method extracts the time-series input data and creates the temporal windows based on the specified unroll_length and n_windows.

Parameters:

kwargs (dict) – The keyword arguments containing the data to be stored.

Returns:

A dictionary-like structure containing the stored data.

Return type:

_DataManager

evaluate(batch, solver)

Evaluate the residual of the condition on the given batch using the solver.

This method computes the per-step residuals through autoregressive unrolling. A forward pass of the solver’s model is performed at each time step, and the per-step residuals (predicted - target) are returned as a stacked tensor.

The returned tensor preserves all per-step residual values without reduction or loss aggregation.

Parameters:

• batch (dict) – The batch containing the data required by the condition evaluation.

• solver (BaseSolver) – The solver used to perform the forward pass and compute the residual. The solver provides access to the model and its parameters, which may be necessary for evaluating the condition residual.

Raises:

ValueError – If the input tensor in the batch has less than 4 dimensions.

Returns:

The stacked per-step residual tensor of shape [time_steps - 1, trajectories, windows, *features].

Return type:

torch.Tensor | LabelTensor

property input

The unrolled temporal input data.

Returns:

The input data.

Return type:

torch.Tensor | LabelTensor