examples/examples.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "initial_id",
   "metadata": {
    "collapsed": true,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:43:51.169399Z",
     "start_time": "2024-07-26T09:43:51.166063Z"
    }
   },
   "outputs": [],
   "source": [
    "# set up an absolute path to the project \n",
    "# not needed in case of `pip install`\n",
    "%run -i tools/setup_env.py"
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Usage examples of `torchcnnbuilder`"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "ed843dda94907c8a"
  },
  {
   "cell_type": "markdown",
   "source": [
    "There are some functions for the calculation of the sizes of tensors after convolutional layers. Moreover, you can find here some constants values"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "1121f3db290499c8"
  },
  {
   "cell_type": "markdown",
   "source": [
    "### `convNd_out`"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "37fbd3415302cc40"
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "outputs": [],
   "source": [
    "from torchcnnbuilder import (\n",
    "    conv1d_out, \n",
    "    conv2d_out, \n",
    "    conv3d_out,\n",
    ")"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:43:53.851721Z",
     "start_time": "2024-07-26T09:43:53.136683Z"
    }
   },
   "id": "2432fe2b1f46184a"
  },
  {
   "cell_type": "markdown",
   "source": [
    "Params:\n",
    "\n",
    "- **input_size**: size of the input tensor/vector\n",
    "- **kernel_size**: size of the convolution kernel. Default: 3\n",
    "- **stride**: stride of the convolution. Default: 1\n",
    "- **padding**: padding added to all four sides of the input. Default: 0\n",
    "- **dilation**: spacing between kernel elements. Default: 1\n",
    "- **n_layers**: number of conv layers\n",
    "\n",
    "Returns: one tuple as a size of the output tensor"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "df1023ce4864d65"
  },
  {
   "cell_type": "markdown",
   "source": [
    "The size calculation after the convolutional layer is carried out according to the formula from the `torch` module *(the default parameters are the same as in `nn.ConvNd`)*. Counting functions are implemented for convolutions of dimensions from 1 to 3. At the same time, depending on the dimension, one number or the corresponding tuple of dimensions can be supplied to the parameters of each function. If it is necessary to calculate the convolution for tensors of N dimensions, then it is enough to simply apply a one-dimensional convolution N times. Some result values **can be negative** (due to the formula) which means you **should choose another conv params** (tensor dimensions degenerates to zero). The formula for calculating the size of the tensor after convolution for one dimension is presented below:\n",
    "\n",
    "$$\n",
    "H_{out} = \\lfloor \\frac{H_{in} + 2 \\times padding[0] - dilation[0] \\times (kernel[0] - 1) + 1}{stride[0]} \\rfloor + 1\n",
    "$$\n"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "25b7a5b76b420487"
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Tensor size after nn.Conv1d: (15,)\n"
     ]
    }
   ],
   "source": [
    "new_size = conv1d_out(input_size=33, \n",
    "                      kernel_size=5,\n",
    "                      stride=2)\n",
    "\n",
    "print(f'Tensor size after nn.Conv1d: {new_size}') "
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:43:54.913080Z",
     "start_time": "2024-07-26T09:43:54.907715Z"
    }
   },
   "id": "47d619fb5c21edda"
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Tensor size after nn.Conv2d: (51, 32)\n"
     ]
    }
   ],
   "source": [
    "new_size = conv2d_out(input_size=(55, 40), \n",
    "                      kernel_size=(4, 5),\n",
    "                      padding=(1, 0),\n",
    "                      dilation=(2, 2))\n",
    "\n",
    "print(f'Tensor size after nn.Conv2d: {new_size}') "
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:43:55.239902Z",
     "start_time": "2024-07-26T09:43:55.233383Z"
    }
   },
   "id": "a772f2aeeb967c8b"
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Tensor size after nn.Conv1d: (25, 25, 25)\n"
     ]
    }
   ],
   "source": [
    "new_size = conv3d_out(input_size=33, \n",
    "                      n_layers=4)\n",
    "\n",
    "print(f'Tensor size after nn.Conv1d: {new_size}') "
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:43:55.553304Z",
     "start_time": "2024-07-26T09:43:55.546639Z"
    }
   },
   "id": "c3bb2c8979f18670"
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Tensor size after nn.Conv1d: (39, 8)\n"
     ]
    }
   ],
   "source": [
    "# this equals to the output shape after 4 nn.Conv2d layers\n",
    "new_size = conv2d_out(input_size=(55, 40), \n",
    "                      kernel_size=(4, 5),\n",
    "                      padding=(1, 0),\n",
    "                      dilation=(2, 2),\n",
    "                      n_layers=4)\n",
    "\n",
    "print(f'Tensor size after nn.Conv1d: {new_size}') "
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:43:55.807093Z",
     "start_time": "2024-07-26T09:43:55.802907Z"
    }
   },
   "id": "ae3e285291563e59"
  },
  {
   "cell_type": "markdown",
   "source": [
    "### `conv_transposeNd_out`"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "b25846666f451d1c"
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "outputs": [],
   "source": [
    "from torchcnnbuilder import (\n",
    "    conv_transpose1d_out, \n",
    "    conv_transpose2d_out, \n",
    "    conv_transpose3d_out,\n",
    ")"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:43:56.519236Z",
     "start_time": "2024-07-26T09:43:56.515598Z"
    }
   },
   "id": "ace12c7419f370c7"
  },
  {
   "cell_type": "markdown",
   "source": [
    "Params:\n",
    "\n",
    "- **input_size**: size of the input tensor/vector\n",
    "- **kernel_size**: size of the convolution kernel. Default: 3\n",
    "- **stride**: stride of the convolution. Default: 1\n",
    "- **padding**: padding added to all four sides of the input. Default: 0\n",
    "- **output_padding**: controls the additional size added to one side of the output shape. Default: 0\n",
    "- **dilation**: spacing between kernel elements. Default: 1\n",
    "- **n_layers**: number of conv layers\n",
    "\n",
    "Returns: one tuple as a size of the output tensor"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "d0ead8c3695ab725"
  },
  {
   "cell_type": "markdown",
   "source": [
    "The size calculation after the transposed convolutional layer is carried out according to the formula from the torch module *(the default parameters are the same as in `nn.ConvTransposeNd`)*. Counting functions are implemented for transposed convolutions of dimensions from 1 to 3. At the same time, depending on the dimension, one number or the corresponding tuple of dimensions can be supplied to the parameters of each function. If it is necessary to calculate the transposed convolution for tensors of N dimensions, then it is enough to simply apply a one-dimensional transposed convolution N times. Some result values **can be negative** (due to the formula) which means you **should choose another conv params** (tensor dimensions degenerates to zero). The formula for calculating the size of the tensor after transposed convolution for one dimension is presented below:\n",
    "\n",
    "$$\n",
    "H_{out} = (H_{in} - 1) \\times stride[0] - 2 \\times padding[0] + dilation[0] \\times (kernel\\_size[0] - 1) + output\\_padding[0] + 1\n",
    "$$"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "97e97d80febc0202"
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Tensor size after nn.ConvTranspose1d: (33,)\n"
     ]
    }
   ],
   "source": [
    "new_size = conv_transpose1d_out(input_size=15, \n",
    "                                kernel_size=5,\n",
    "                                stride=2)\n",
    "\n",
    "print(f'Tensor size after nn.ConvTranspose1d: {new_size}') "
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:43:57.607943Z",
     "start_time": "2024-07-26T09:43:57.602901Z"
    }
   },
   "id": "5d94960f3683a1cb"
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Tensor size after nn.ConvTranspose2d: (55, 40)\n"
     ]
    }
   ],
   "source": [
    "new_size = conv_transpose2d_out(input_size=(51, 32), \n",
    "                                kernel_size=(4, 5),\n",
    "                                padding=(1, 0),\n",
    "                                dilation=(2, 2))\n",
    "\n",
    "print(f'Tensor size after nn.ConvTranspose2d: {new_size}') "
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:44:00.061644Z",
     "start_time": "2024-07-26T09:44:00.053329Z"
    }
   },
   "id": "410779c1abe4ecfb"
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Tensor size after nn.ConvTranspose2d: (23, 23, 24)\n"
     ]
    }
   ],
   "source": [
    "# this equals to the output shape after 3 nn.ConvTranspose3d layers\n",
    "new_size = conv_transpose3d_out(input_size=(11, 11, 12), \n",
    "                                kernel_size=3,\n",
    "                                dilation=(2, 2, 1),\n",
    "                                n_layers=3)\n",
    "\n",
    "print(f'Tensor size after nn.ConvTranspose2d: {new_size}') "
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:44:00.533559Z",
     "start_time": "2024-07-26T09:44:00.530208Z"
    }
   },
   "id": "ac4e92a7b7f019e5"
  },
  {
   "cell_type": "markdown",
   "source": [
    "### `DEFAULT_CONV_PARAMS`"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "d42e4f1224ed0899"
  },
  {
   "cell_type": "markdown",
   "source": [
    "You can check default `torch` convolution params:"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "7cc6058c34121dfd"
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'kernel_size': 3, 'stride': 1, 'padding': 0, 'dilation': 1}\n"
     ]
    }
   ],
   "source": [
    "from torchcnnbuilder import DEFAULT_CONV_PARAMS\n",
    "\n",
    "print(DEFAULT_CONV_PARAMS)"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:44:02.000029Z",
     "start_time": "2024-07-26T09:44:01.994040Z"
    }
   },
   "id": "de201159f90e02eb"
  },
  {
   "cell_type": "markdown",
   "source": [
    "### `DEFAULT_TRANSPOSE_CONV_PARAMS`"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "838becf8dbdfdeb2"
  },
  {
   "cell_type": "markdown",
   "source": [
    "You can check default `torch` transpose convolution params:"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "76df8db23816b8a2"
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'kernel_size': 3, 'stride': 1, 'padding': 0, 'output_padding': 0, 'dilation': 1}\n"
     ]
    }
   ],
   "source": [
    "from torchcnnbuilder import DEFAULT_TRANSPOSE_CONV_PARAMS\n",
    "\n",
    "print(DEFAULT_TRANSPOSE_CONV_PARAMS)"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:44:03.446794Z",
     "start_time": "2024-07-26T09:44:03.439569Z"
    }
   },
   "id": "b2bf919efac5baca"
  },
  {
   "cell_type": "markdown",
   "source": [
    "### `__version__`"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "2b3cba66bb8d8170"
  },
  {
   "cell_type": "markdown",
   "source": [
    "You can check current package version by using constant `__version__`"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "4a3e8d7ba7b34776"
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0.1.2\n"
     ]
    }
   ],
   "source": [
    "from torchcnnbuilder import __version__\n",
    "\n",
    "print(__version__)"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-26T09:44:05.099565Z",
     "start_time": "2024-07-26T09:44:05.097365Z"
    }
   },
   "id": "b9f010b464fd939b"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [],
   "metadata": {
    "collapsed": false
   },
   "id": "7e97add7a2a8e5e"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}