.. _convolutive-template:

==============================
Convolutional Dynamic Template
==============================

The Convolutional Dynamic template creates convolutional neural network models that learn input-output relationships with time dependencies using a sliding window over the past inputs. These models are ideal for systems where outputs depend on a finite history of inputs.

In the GUI this template is called **CNN Dynamic**. In the Python API it is the ``ConvolutiveDynamic`` class.

.. contents:: On this page
   :local:
   :depth: 2

Overview
========

Convolutional Dynamic models learn to map a window of past inputs to current outputs:

.. math::

   y(t) = f(u(t), u(t-1), ..., u(t-w+1))

where:

- :math:`u` is the input (excitation) vector
- :math:`y` is the output vector
- :math:`w` is the window size
- :math:`f` is the learned function

**Key characteristics:**

- Uses a sliding window to capture temporal dependencies
- Simpler architecture than ODE models
- Faster training for many applications
- No explicit state initialization required
- Exports to FMU format for simulation tools

When to Use Convolutional Dynamic
=================================

The Convolutional Dynamic template is ideal for:

- **Input-output systems with time delays**: Where output depends on recent input history
- **Signal processing**: Filtering, prediction, transformation
- **Systems without explicit state**: When you don't need to model internal dynamics
- **Faster training**: When training time is a priority

**Example applications:**

- Time-series forecasting
- Signal filtering and denoising
- Sensor data processing
- Short-term prediction tasks
- Systems with bounded memory effects

Model Architecture
==================

A NeurEco Convolutional Dynamic model is a convolutional neural network applied to a
sliding window of the inputs. At each time step it reads the last ``window_size``
input samples and predicts the outputs at the last time step of the window:

1. **Sliding window**: the last ``window_size`` time steps of all the inputs
2. **Convolutional layers**: a stack of 1-D convolutional layers whose kernels slide
   along the time axis inside the window. ``hidden_layer_number`` is the maximum
   number of these layers, and each layer has ``layer_multiplier`` times more kernels
   than the layer after it. ``last_layer_grid_number`` sets the number of kernels of
   the last convolutional layer (``0``: chosen automatically).
3. **Tabular regression**: a NeurEco Tabular regression network maps the features
   computed by the convolutional layers to the outputs. NeurEco sizes it
   automatically.

NeurEco builds the network in stages. It first builds a single convolutional layer
followed by dense layers, then adds convolutional layers one at a time, up to
``hidden_layer_number``, and keeps the network with the best validation error. Finally
it replaces the dense layers with the Tabular regression network and trains the whole
network.

Because the same network is applied to the window at every time step, the model as a
whole also acts as a nonlinear, causal convolution of the input signals over time.

**Padding.** Near the two edges of the window (its first and last time steps), a
convolution kernel would reach past the window. Before each convolutional layer,
NeurEco therefore extends the layer input at both edges. ``padding_mode`` and
``padding_value`` choose how these extra values are filled (see
:ref:`convolutive-building`). Padding acts inside each window only: it does not let the
model predict before the first full window.

The model automatically handles:

- Multi-sequence processing
- Variable-length input sequences

.. _convolutive-window-stride:

Window Size and Stride
----------------------

Two parameters control the sliding window: ``window_size``, a setting of the model, and
``window_stride``, which only affects how the training windows are cut from the build
data.

**Window size** (``window_size``, integer, at least ``3``, default ``32``)

``window_size`` is the number of consecutive input time steps the model looks at to
produce a single output — the :math:`w` in
:math:`y(t) = f(u(t), u(t-1), \ldots, u(t-w+1))`. It is effectively the model's
**memory length**: how far into the past each prediction can reach. Because the
Convolutional Dynamic template uses a uniform time step :math:`\Delta t`, this memory
corresponds to a physical duration of ``window_size`` :math:`\times\ \Delta t`.
``window_size`` also fixes the input length of the convolutional network, so it is a
network setting as well.

- **Larger window**: captures longer-term dependencies, but increases model size and computation.
- **Smaller window**: faster training and a smaller model, but may miss temporal patterns that span more steps.

The minimum is ``3``: a smaller ``window_size`` is rejected with an error. If the
outputs depend on fewer than 3 time steps of the inputs, the data has (almost) no
time dependence: it is a Tabular regression problem, so use the Tabular regression
template instead (see :ref:`tabular-building-regression`).

Two practical consequences:

- The model needs a full window before it can predict, so the first ``window_size - 1`` time steps of every sequence are a warm-up and are not predicted: the first prediction is for the ``window_size``-th time step, and a sequence of :math:`N` time steps gives :math:`N - w + 1` predictions (see :ref:`convolutive-evaluating`).
- Every training and evaluation sequence must contain at least ``window_size`` time steps.

**Window stride** (``window_stride``, positive integer, default ``1``)

``window_stride`` is a training-data setting only. It is the step between two
consecutive windows that NeurEco cuts from the training data during the build. With
the default of ``1`` every possible window is used. A larger value keeps fewer
windows, so the build is faster but learns from less data. Validation and test data
always use every window. The stride cannot exceed 30% of the number of time steps of
any training trajectory.

The stride is not part of the model, and it is not the stride of the convolutional
layers (NeurEco chooses those itself). Whatever ``window_stride`` was used for
training, the model predicts every time step after the warm-up when it is evaluated.

.. tip::

   Start with a moderate window size (32 to 64) and keep ``window_stride`` at ``1``,
   then adjust based on your data characteristics and validation performance.
   Increase the stride only to speed up the build on long trajectories.

Native File Format
==================

Convolutional Dynamic models use the ``.ecnn`` extension:

- Preserves complete model information
- Supports loading and continued training
- Can be exported to FMU format

Workflow
========

1. **Prepare data**: Format time-series data with time, inputs, and outputs
2. **Build model**: Train the Convolutional Dynamic model on your data
3. **Evaluate**: Run predictions on new data
4. **Export**: Save in native format or export to FMU

.. toctree::
   :maxdepth: 1
   :caption: Convolutional Dynamic Template

   building
   evaluating