torchcnnbuilder.models 

  1from collections import OrderedDict
  2from typing import Optional, Sequence, Union
  3
  4import torch.nn as nn
  5
  6from torchcnnbuilder._constants import (
  7    DEFAULT_CONV_PARAMS,
  8    DEFAULT_TRANSPOSE_CONV_PARAMS,
  9)
 10from torchcnnbuilder._validation import _validate_conv_dim, _validate_sequence_length
 11from torchcnnbuilder.builder import Builder
 12
 13
 14# ------------------------------------
 15# CNN Forecaster pattern class
 16# ------------------------------------
 17class ForecasterBase(nn.Module):
 18    """
 19    A base class for CNN-based time series forecasting architectures. This class serves as a template for building
 20    time series prediction models with an encoder-decoder architecture.
 21
 22    Original source:
 23    [article code](https://github.com/ITMO-NSS-team/ice-concentration-prediction-paper?ysclid=lrhxbvsk8s328492826).
 24    """
 25
 26    def __init__(
 27        self,
 28        input_size: Sequence[int],
 29        n_layers: int,
 30        in_time_points: int,
 31        out_time_points: int,
 32        conv_dim: int = 2,
 33        n_transpose_layers: Optional[int] = None,
 34        convolve_params: Optional[dict] = None,
 35        transpose_convolve_params: Optional[dict] = None,
 36        activation_function: nn.Module = nn.ReLU(inplace=True),
 37        finish_activation_function: Union[Optional[nn.Module], str] = None,
 38        normalization: Optional[str] = None,
 39        latent_shape: Optional[Sequence[int]] = None,
 40        latent_n_layers: int = 1,
 41        latent_activation_function: Union[Optional[nn.Module], str] = None,
 42    ) -> None:
 43        """
 44        Initializes the ForecasterBase with the encoder-decoder structure and specified layer parameters.
 45        See the model diagram below:
 46
 47        ![image](../.docs/media/ForecasterBase.png)
 48
 49        Args:
 50            input_size (Sequence[int]): The shape of the input tensor for one time point.
 51            n_layers (int): The number of convolution layers in the encoder.
 52            in_time_points (int): The number of time points (channels) in the input tensor (prehistory size).
 53            out_time_points (int): The number of time points (channels) in the output tensor (forecasting size).
 54            conv_dim (int): The dimension of the convolution operation (1, 2, or 3). If set to 2, `in_time_points` is
 55                used as the number of channels. Default is 2.
 56            n_transpose_layers (Optional[int]): The number of transpose convolution layers in the decoder.
 57                If None, uses the same value as `n_layers`. Default is None.
 58            convolve_params (Optional[dict]): Parameters for convolution layers. If None, defaults to PyTorch’s default
 59                values. Default is None.
 60            transpose_convolve_params (Optional[dict]): Parameters for transpose convolution layers. If None, defaults
 61                to PyTorch’s default values. Default is None.
 62            activation_function (nn.Module): Activation function used in each layer. Default is `nn.ReLU(inplace=True)`.
 63            finish_activation_function (Union[Optional[nn.Module], str]): Final activation function. If 'same',
 64                uses the same activation function as `activation_function`. Default is None.
 65            normalization (Optional[str]): Type of normalization ('dropout', 'batchnorm', or 'instancenorm').
 66                Default is None.
 67            latent_shape (Optional[Sequence[int]]): The shape of the latent space. If None, no latent space
 68            transformation is applied. Default is None.
 69            latent_n_layers (int): Number of layers in the latent space transformation. Default is 1.
 70            latent_activation_function (Union[Optional[nn.Module], str]): Activation function for latent space.
 71                If 'same', uses the same activation function as the model. Default is None.
 72        """
 73        super(ForecasterBase, self).__init__()
 74        _validate_conv_dim(conv_dim)
 75
 76        if conv_dim == 3:
 77            _validate_sequence_length(input_size, 2)
 78
 79            channel_growth_rate = "power"
 80            out_size = [out_time_points] + list(input_size)
 81            input_size = [in_time_points] + list(input_size)
 82
 83            # time_points is a 3d dimension like channels
 84            in_time_points, out_time_points = 1, 1
 85
 86        if conv_dim == 2:
 87            _validate_sequence_length(input_size, 2)
 88
 89            channel_growth_rate = "proportion"
 90            out_size = None
 91
 92        if conv_dim == 1:
 93            _validate_sequence_length(input_size, 1)
 94
 95            channel_growth_rate = "proportion"
 96            out_size = None
 97
 98        builder = Builder(
 99            input_size=input_size,
100            activation_function=activation_function,
101            finish_activation_function=finish_activation_function,
102        )
103
104        if n_transpose_layers is None:
105            n_transpose_layers = n_layers
106
107        if convolve_params is None:
108            convolve_params = DEFAULT_CONV_PARAMS
109
110        if transpose_convolve_params is None:
111            transpose_convolve_params = DEFAULT_TRANSPOSE_CONV_PARAMS
112
113        convolution = builder.build_convolve_sequence(
114            n_layers=n_layers,
115            in_channels=in_time_points,
116            params=convolve_params,
117            conv_dim=conv_dim,
118            normalization=normalization,
119            channel_growth_rate=channel_growth_rate,
120        )
121
122        transpose_convolution = builder.build_transpose_convolve_sequence(
123            n_layers=n_transpose_layers,
124            in_channels=builder._conv_channels[-1],
125            out_channels=out_time_points,
126            out_size=out_size,
127            params=transpose_convolve_params,
128            conv_dim=conv_dim,
129            normalization=normalization,
130            channel_growth_rate=channel_growth_rate,
131        )
132
133        if latent_shape is not None:
134            self.encoder = nn.Sequential(
135                OrderedDict(
136                    [
137                        ("convolution", convolution),
138                        (
139                            "to-latent",
140                            builder.latent_block(
141                                input_shape=(builder.conv_channels[-1], *builder.conv_layers[-1]),
142                                output_shape=latent_shape,
143                                n_layers=latent_n_layers,
144                                activation_function=latent_activation_function,
145                            ),
146                        ),
147                    ]
148                )
149            )
150            self.decoder = nn.Sequential(
151                OrderedDict(
152                    [
153                        (
154                            "from-latent",
155                            builder.latent_block(
156                                input_shape=latent_shape,
157                                output_shape=(builder.transpose_conv_channels[0], *builder.transpose_conv_layers[0]),
158                                n_layers=latent_n_layers,
159                                activation_function=latent_activation_function,
160                            ),
161                        ),
162                        ("transpose convolution", transpose_convolution),
163                    ]
164                )
165            )
166        else:
167            self.encoder = convolution
168            self.decoder = transpose_convolution
169
170        self.conv_channels = builder.conv_channels
171        self.transpose_conv_channels = builder.transpose_conv_channels
172        self.conv_layers = builder.conv_layers
173        self.transpose_conv_layers = builder.transpose_conv_layers
174
175    def forward(self, x):
176        """
177        Performs the forward pass of the encoder-decoder model, transforming the input tensor.
178
179        Args:
180            x (torch.Tensor): The input tensor to be transformed by the model.
181
182        Returns:
183            The output tensor after passing through the encoder and decoder layers.
184        """
185        x = self.encoder(x)
186        x = self.decoder(x)
187        return x
class ForecasterBase(torch.nn.modules.module.Module): 
 18class ForecasterBase(nn.Module):
 19    """
 20    A base class for CNN-based time series forecasting architectures. This class serves as a template for building
 21    time series prediction models with an encoder-decoder architecture.
 22
 23    Original source:
 24    [article code](https://github.com/ITMO-NSS-team/ice-concentration-prediction-paper?ysclid=lrhxbvsk8s328492826).
 25    """
 26
 27    def __init__(
 28        self,
 29        input_size: Sequence[int],
 30        n_layers: int,
 31        in_time_points: int,
 32        out_time_points: int,
 33        conv_dim: int = 2,
 34        n_transpose_layers: Optional[int] = None,
 35        convolve_params: Optional[dict] = None,
 36        transpose_convolve_params: Optional[dict] = None,
 37        activation_function: nn.Module = nn.ReLU(inplace=True),
 38        finish_activation_function: Union[Optional[nn.Module], str] = None,
 39        normalization: Optional[str] = None,
 40        latent_shape: Optional[Sequence[int]] = None,
 41        latent_n_layers: int = 1,
 42        latent_activation_function: Union[Optional[nn.Module], str] = None,
 43    ) -> None:
 44        """
 45        Initializes the ForecasterBase with the encoder-decoder structure and specified layer parameters.
 46        See the model diagram below:
 47
 48        ![image](../.docs/media/ForecasterBase.png)
 49
 50        Args:
 51            input_size (Sequence[int]): The shape of the input tensor for one time point.
 52            n_layers (int): The number of convolution layers in the encoder.
 53            in_time_points (int): The number of time points (channels) in the input tensor (prehistory size).
 54            out_time_points (int): The number of time points (channels) in the output tensor (forecasting size).
 55            conv_dim (int): The dimension of the convolution operation (1, 2, or 3). If set to 2, `in_time_points` is
 56                used as the number of channels. Default is 2.
 57            n_transpose_layers (Optional[int]): The number of transpose convolution layers in the decoder.
 58                If None, uses the same value as `n_layers`. Default is None.
 59            convolve_params (Optional[dict]): Parameters for convolution layers. If None, defaults to PyTorch’s default
 60                values. Default is None.
 61            transpose_convolve_params (Optional[dict]): Parameters for transpose convolution layers. If None, defaults
 62                to PyTorch’s default values. Default is None.
 63            activation_function (nn.Module): Activation function used in each layer. Default is `nn.ReLU(inplace=True)`.
 64            finish_activation_function (Union[Optional[nn.Module], str]): Final activation function. If 'same',
 65                uses the same activation function as `activation_function`. Default is None.
 66            normalization (Optional[str]): Type of normalization ('dropout', 'batchnorm', or 'instancenorm').
 67                Default is None.
 68            latent_shape (Optional[Sequence[int]]): The shape of the latent space. If None, no latent space
 69            transformation is applied. Default is None.
 70            latent_n_layers (int): Number of layers in the latent space transformation. Default is 1.
 71            latent_activation_function (Union[Optional[nn.Module], str]): Activation function for latent space.
 72                If 'same', uses the same activation function as the model. Default is None.
 73        """
 74        super(ForecasterBase, self).__init__()
 75        _validate_conv_dim(conv_dim)
 76
 77        if conv_dim == 3:
 78            _validate_sequence_length(input_size, 2)
 79
 80            channel_growth_rate = "power"
 81            out_size = [out_time_points] + list(input_size)
 82            input_size = [in_time_points] + list(input_size)
 83
 84            # time_points is a 3d dimension like channels
 85            in_time_points, out_time_points = 1, 1
 86
 87        if conv_dim == 2:
 88            _validate_sequence_length(input_size, 2)
 89
 90            channel_growth_rate = "proportion"
 91            out_size = None
 92
 93        if conv_dim == 1:
 94            _validate_sequence_length(input_size, 1)
 95
 96            channel_growth_rate = "proportion"
 97            out_size = None
 98
 99        builder = Builder(
100            input_size=input_size,
101            activation_function=activation_function,
102            finish_activation_function=finish_activation_function,
103        )
104
105        if n_transpose_layers is None:
106            n_transpose_layers = n_layers
107
108        if convolve_params is None:
109            convolve_params = DEFAULT_CONV_PARAMS
110
111        if transpose_convolve_params is None:
112            transpose_convolve_params = DEFAULT_TRANSPOSE_CONV_PARAMS
113
114        convolution = builder.build_convolve_sequence(
115            n_layers=n_layers,
116            in_channels=in_time_points,
117            params=convolve_params,
118            conv_dim=conv_dim,
119            normalization=normalization,
120            channel_growth_rate=channel_growth_rate,
121        )
122
123        transpose_convolution = builder.build_transpose_convolve_sequence(
124            n_layers=n_transpose_layers,
125            in_channels=builder._conv_channels[-1],
126            out_channels=out_time_points,
127            out_size=out_size,
128            params=transpose_convolve_params,
129            conv_dim=conv_dim,
130            normalization=normalization,
131            channel_growth_rate=channel_growth_rate,
132        )
133
134        if latent_shape is not None:
135            self.encoder = nn.Sequential(
136                OrderedDict(
137                    [
138                        ("convolution", convolution),
139                        (
140                            "to-latent",
141                            builder.latent_block(
142                                input_shape=(builder.conv_channels[-1], *builder.conv_layers[-1]),
143                                output_shape=latent_shape,
144                                n_layers=latent_n_layers,
145                                activation_function=latent_activation_function,
146                            ),
147                        ),
148                    ]
149                )
150            )
151            self.decoder = nn.Sequential(
152                OrderedDict(
153                    [
154                        (
155                            "from-latent",
156                            builder.latent_block(
157                                input_shape=latent_shape,
158                                output_shape=(builder.transpose_conv_channels[0], *builder.transpose_conv_layers[0]),
159                                n_layers=latent_n_layers,
160                                activation_function=latent_activation_function,
161                            ),
162                        ),
163                        ("transpose convolution", transpose_convolution),
164                    ]
165                )
166            )
167        else:
168            self.encoder = convolution
169            self.decoder = transpose_convolution
170
171        self.conv_channels = builder.conv_channels
172        self.transpose_conv_channels = builder.transpose_conv_channels
173        self.conv_layers = builder.conv_layers
174        self.transpose_conv_layers = builder.transpose_conv_layers
175
176    def forward(self, x):
177        """
178        Performs the forward pass of the encoder-decoder model, transforming the input tensor.
179
180        Args:
181            x (torch.Tensor): The input tensor to be transformed by the model.
182
183        Returns:
184            The output tensor after passing through the encoder and decoder layers.
185        """
186        x = self.encoder(x)
187        x = self.decoder(x)
188        return x

A base class for CNN-based time series forecasting architectures. This class serves as a template for building time series prediction models with an encoder-decoder architecture.

Original source: article code.

ForecasterBase( input_size: Sequence[int], n_layers: int, in_time_points: int, out_time_points: int, conv_dim: int = 2, n_transpose_layers: Optional[int] = None, convolve_params: Optional[dict] = None, transpose_convolve_params: Optional[dict] = None, activation_function: torch.nn.modules.module.Module = ReLU(inplace=True), finish_activation_function: Union[torch.nn.modules.module.Module, NoneType, str] = None, normalization: Optional[str] = None, latent_shape: Optional[Sequence[int]] = None, latent_n_layers: int = 1, latent_activation_function: Union[torch.nn.modules.module.Module, NoneType, str] = None) 
 27    def __init__(
 28        self,
 29        input_size: Sequence[int],
 30        n_layers: int,
 31        in_time_points: int,
 32        out_time_points: int,
 33        conv_dim: int = 2,
 34        n_transpose_layers: Optional[int] = None,
 35        convolve_params: Optional[dict] = None,
 36        transpose_convolve_params: Optional[dict] = None,
 37        activation_function: nn.Module = nn.ReLU(inplace=True),
 38        finish_activation_function: Union[Optional[nn.Module], str] = None,
 39        normalization: Optional[str] = None,
 40        latent_shape: Optional[Sequence[int]] = None,
 41        latent_n_layers: int = 1,
 42        latent_activation_function: Union[Optional[nn.Module], str] = None,
 43    ) -> None:
 44        """
 45        Initializes the ForecasterBase with the encoder-decoder structure and specified layer parameters.
 46        See the model diagram below:
 47
 48        ![image](../.docs/media/ForecasterBase.png)
 49
 50        Args:
 51            input_size (Sequence[int]): The shape of the input tensor for one time point.
 52            n_layers (int): The number of convolution layers in the encoder.
 53            in_time_points (int): The number of time points (channels) in the input tensor (prehistory size).
 54            out_time_points (int): The number of time points (channels) in the output tensor (forecasting size).
 55            conv_dim (int): The dimension of the convolution operation (1, 2, or 3). If set to 2, `in_time_points` is
 56                used as the number of channels. Default is 2.
 57            n_transpose_layers (Optional[int]): The number of transpose convolution layers in the decoder.
 58                If None, uses the same value as `n_layers`. Default is None.
 59            convolve_params (Optional[dict]): Parameters for convolution layers. If None, defaults to PyTorch’s default
 60                values. Default is None.
 61            transpose_convolve_params (Optional[dict]): Parameters for transpose convolution layers. If None, defaults
 62                to PyTorch’s default values. Default is None.
 63            activation_function (nn.Module): Activation function used in each layer. Default is `nn.ReLU(inplace=True)`.
 64            finish_activation_function (Union[Optional[nn.Module], str]): Final activation function. If 'same',
 65                uses the same activation function as `activation_function`. Default is None.
 66            normalization (Optional[str]): Type of normalization ('dropout', 'batchnorm', or 'instancenorm').
 67                Default is None.
 68            latent_shape (Optional[Sequence[int]]): The shape of the latent space. If None, no latent space
 69            transformation is applied. Default is None.
 70            latent_n_layers (int): Number of layers in the latent space transformation. Default is 1.
 71            latent_activation_function (Union[Optional[nn.Module], str]): Activation function for latent space.
 72                If 'same', uses the same activation function as the model. Default is None.
 73        """
 74        super(ForecasterBase, self).__init__()
 75        _validate_conv_dim(conv_dim)
 76
 77        if conv_dim == 3:
 78            _validate_sequence_length(input_size, 2)
 79
 80            channel_growth_rate = "power"
 81            out_size = [out_time_points] + list(input_size)
 82            input_size = [in_time_points] + list(input_size)
 83
 84            # time_points is a 3d dimension like channels
 85            in_time_points, out_time_points = 1, 1
 86
 87        if conv_dim == 2:
 88            _validate_sequence_length(input_size, 2)
 89
 90            channel_growth_rate = "proportion"
 91            out_size = None
 92
 93        if conv_dim == 1:
 94            _validate_sequence_length(input_size, 1)
 95
 96            channel_growth_rate = "proportion"
 97            out_size = None
 98
 99        builder = Builder(
100            input_size=input_size,
101            activation_function=activation_function,
102            finish_activation_function=finish_activation_function,
103        )
104
105        if n_transpose_layers is None:
106            n_transpose_layers = n_layers
107
108        if convolve_params is None:
109            convolve_params = DEFAULT_CONV_PARAMS
110
111        if transpose_convolve_params is None:
112            transpose_convolve_params = DEFAULT_TRANSPOSE_CONV_PARAMS
113
114        convolution = builder.build_convolve_sequence(
115            n_layers=n_layers,
116            in_channels=in_time_points,
117            params=convolve_params,
118            conv_dim=conv_dim,
119            normalization=normalization,
120            channel_growth_rate=channel_growth_rate,
121        )
122
123        transpose_convolution = builder.build_transpose_convolve_sequence(
124            n_layers=n_transpose_layers,
125            in_channels=builder._conv_channels[-1],
126            out_channels=out_time_points,
127            out_size=out_size,
128            params=transpose_convolve_params,
129            conv_dim=conv_dim,
130            normalization=normalization,
131            channel_growth_rate=channel_growth_rate,
132        )
133
134        if latent_shape is not None:
135            self.encoder = nn.Sequential(
136                OrderedDict(
137                    [
138                        ("convolution", convolution),
139                        (
140                            "to-latent",
141                            builder.latent_block(
142                                input_shape=(builder.conv_channels[-1], *builder.conv_layers[-1]),
143                                output_shape=latent_shape,
144                                n_layers=latent_n_layers,
145                                activation_function=latent_activation_function,
146                            ),
147                        ),
148                    ]
149                )
150            )
151            self.decoder = nn.Sequential(
152                OrderedDict(
153                    [
154                        (
155                            "from-latent",
156                            builder.latent_block(
157                                input_shape=latent_shape,
158                                output_shape=(builder.transpose_conv_channels[0], *builder.transpose_conv_layers[0]),
159                                n_layers=latent_n_layers,
160                                activation_function=latent_activation_function,
161                            ),
162                        ),
163                        ("transpose convolution", transpose_convolution),
164                    ]
165                )
166            )
167        else:
168            self.encoder = convolution
169            self.decoder = transpose_convolution
170
171        self.conv_channels = builder.conv_channels
172        self.transpose_conv_channels = builder.transpose_conv_channels
173        self.conv_layers = builder.conv_layers
174        self.transpose_conv_layers = builder.transpose_conv_layers

Initializes the ForecasterBase with the encoder-decoder structure and specified layer parameters. See the model diagram below:

image

Arguments:
  • input_size (Sequence[int]): The shape of the input tensor for one time point.
  • n_layers (int): The number of convolution layers in the encoder.
  • in_time_points (int): The number of time points (channels) in the input tensor (prehistory size).
  • out_time_points (int): The number of time points (channels) in the output tensor (forecasting size).
  • conv_dim (int): The dimension of the convolution operation (1, 2, or 3). If set to 2, in_time_points is used as the number of channels. Default is 2.
  • n_transpose_layers (Optional[int]): The number of transpose convolution layers in the decoder. If None, uses the same value as n_layers. Default is None.
  • convolve_params (Optional[dict]): Parameters for convolution layers. If None, defaults to PyTorch’s default values. Default is None.
  • transpose_convolve_params (Optional[dict]): Parameters for transpose convolution layers. If None, defaults to PyTorch’s default values. Default is None.
  • activation_function (nn.Module): Activation function used in each layer. Default is nn.ReLU(inplace=True).
  • finish_activation_function (Union[Optional[nn.Module], str]): Final activation function. If 'same', uses the same activation function as activation_function. Default is None.
  • normalization (Optional[str]): Type of normalization ('dropout', 'batchnorm', or 'instancenorm'). Default is None.
  • latent_shape (Optional[Sequence[int]]): The shape of the latent space. If None, no latent space
  • transformation is applied. Default is None.
  • latent_n_layers (int): Number of layers in the latent space transformation. Default is 1.
  • latent_activation_function (Union[Optional[nn.Module], str]): Activation function for latent space. If 'same', uses the same activation function as the model. Default is None.
def forward(self, x): 
176    def forward(self, x):
177        """
178        Performs the forward pass of the encoder-decoder model, transforming the input tensor.
179
180        Args:
181            x (torch.Tensor): The input tensor to be transformed by the model.
182
183        Returns:
184            The output tensor after passing through the encoder and decoder layers.
185        """
186        x = self.encoder(x)
187        x = self.decoder(x)
188        return x

Performs the forward pass of the encoder-decoder model, transforming the input tensor.

Arguments:
  • x (torch.Tensor): The input tensor to be transformed by the model.
Returns:

The output tensor after passing through the encoder and decoder layers.