convolution.rst 5.78 KB
Newer Older
L.S. Cook's avatar
L.S. Cook committed
1 2 3 4 5 6
.. convolution.rst:

###########
Convolution
###########

7 8 9 10 11
.. code-block:: cpp

   Convolution  // A batched convolution operation


Scott Cyphers's avatar
Scott Cyphers committed
12 13 14
Description
===========

15 16 17 18 19
.. TODO 

Long description


L.S. Cook's avatar
L.S. Cook committed
20

Scott Cyphers's avatar
Scott Cyphers committed
21 22
Inputs
------
L.S. Cook's avatar
L.S. Cook committed
23 24

+-----------------+-------------------------+--------------------------------+
Scott Cyphers's avatar
Scott Cyphers committed
25
| Name            | Element Type            | Shape                          |
L.S. Cook's avatar
L.S. Cook committed
26 27 28 29 30 31
+=================+=========================+================================+
| ``image_batch`` | Any                     | ``(N, C_in, d_1, ..., d_n)``   |
+-----------------+-------------------------+--------------------------------+
| ``filters``     | Same as ``image_batch`` | ``(N, C_in, df_1, ..., df_n)`` |
+-----------------+-------------------------+--------------------------------+

Scott Cyphers's avatar
Scott Cyphers committed
32 33 34
Attributes
----------

35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
+-----------------------------+-----------------------------+----------------------------------------+
| Name                        | Type                        | Notes                                  |
+=============================+=============================+========================================+
| ``window_movement_strides`` | ``Strides[n]``              | How far to slide the                   |
|                             |                             | window along each axis at each step    |
+-----------------------------+-----------------------------+----------------------------------------+
| ``window_dilation_strides`` | ``Strides[n]``              | Per-axis dilation to apply to the      |
|                             |                             | filters                                |
+-----------------------------+-----------------------------+----------------------------------------+
| ``padding_below``           | ``Shape[n]``                | How many padding elements to add       |
|                             |                             | below the 0-coordinate on each axis    |
+-----------------------------+-----------------------------+----------------------------------------+
| ``padding_above``           | ``Shape[n]``                | How many padding elements to add above |
|                             |                             | the max-coordinate on each axis        |
+-----------------------------+-----------------------------+----------------------------------------+
| ``image_dilation_strides``  | ``Strides[n]``              | Per-axis dilation to apply to the      |
|                             |                             | image batch                            |
+-----------------------------+-----------------------------+----------------------------------------+
Scott Cyphers's avatar
Scott Cyphers committed
53 54 55 56 57


Outputs
-------

L.S. Cook's avatar
L.S. Cook committed
58
+------------------+-------------------------+----------------------------------------------------+
Scott Cyphers's avatar
Scott Cyphers committed
59
| Name             | Element Type            | Shape                                              |
L.S. Cook's avatar
L.S. Cook committed
60 61 62 63 64 65
+==================+=========================+====================================================+
| ``features_out`` | Same as ``image_batch`` | ``(N, C_in, d_1 - df_1 + 1, ..., d_n - df_n + 1)`` |
+------------------+-------------------------+----------------------------------------------------+

It must be the case that after dilation and padding are applied, the filter fits within the image.

L.S. Cook's avatar
L.S. Cook committed
66
.. TODO image add
L.S. Cook's avatar
L.S. Cook committed
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112


Mathematical Definition
=======================

Padding
-------

Let :math:`p` (the padding below) and :math:`q` (the padding above) be a sequence of :math:`n`
integers, and :math:`T` be a tensor of shape :math:`(d_1,\dots,d_n)`, such that for all :math:`i`,
:math:`p_i + d_i + q_i \ge 0`. Then :math:`\mathit{Pad}[p,q](T)` is the tensor of shape
:math:`(p_1 + d_1 + q_1,\dots,p_n + d_n + q_n)` such that

.. math::

   \mathit{Pad}[p,q](T)_{i_1,\dots,i_n} \triangleq \begin{cases}
                                                      T_{i_1 - p_1,\dots,i_n - p_n} &\mbox{if for all }j, i_j \ge p_j\mbox{ and }i_j < p_j + d_j \\
                                                      0                             &\mbox{otherwise.}
                                                   \end{cases}

Dilation
--------

Let :math:`l` (the dilation strides) be a sequence of :math:`n` positive integers, and :math:`T`
be a tensor of shape :math:`(d_1,\dots,d_n)`. Then :math:`\mathit{Dilate}[l](T)` is the tensor of
shape :math:`(d'_1,\dots,d'_n)` where :math:`d'_i = \mathit{max}(0,l_i(d_i - 1) + 1)` such that

.. math::

   \mathit{Dilate}[l](T)_{i_1,\dots,i_n} \triangleq \begin{cases}
                                                       T_{i_1/l_1,\dots,i_n/l_n} &\mbox{if for all }j, i_j\mbox{ is a multiple of }l_j \\
                                                       0                         &\mbox{otherwise.}
                                                    \end{cases}

Striding
--------

Let :math:`s` (the strides) be a sequence of :math:`n` positive integers, and :math:`T` be a
tensor of shape :math:`(d_1,\dots,d_n)`. Then :math:`\mathit{Stride}[s](T)` is the tensor of
shape :math:`(d'_1,\dots,d'_n)` where :math:`d'_i = \left\lceil \frac{d_i}{s_i} \right\rceil`
such that

.. math::

   \mathit{Stride}[s](T)_{i_1,\dots,i_n} \triangleq T_{s_1i_1,\dots,s_ni_n}

113 114 115

:math:`s` is the how far, not the unit of farness.

L.S. Cook's avatar
L.S. Cook committed
116 117 118
Convolution
-----------

119 120 121 122 123 124
.. image possibly imported soon; they are not big files but they are svg 

.. 
 figure:: ../graphics/classngraph_1_1op_1_1Convolution__coll__graph_org.svg
 :height: 500px

L.S. Cook's avatar
L.S. Cook committed
125 126 127 128 129 130 131 132 133 134 135

Padded, Dilated, Strided Convolution
------------------------------------

.. math::

   \mathit{PDSConv}[g,p,q,l,s](T_\mathit{image},T_\mathit{filter} \triangleq \mathit{Stride}[s](\mathit{Conv}(\mathit{Pad}[p,q](\mathit{Dilate}[g](T_\mathit{batch})),\mathit{Dilate}[l](T_\mathit{filter})))

Batched, Padded, Dilated, Strided Convolution
---------------------------------------------

L.S. Cook's avatar
L.S. Cook committed
136
.. TODO
L.S. Cook's avatar
L.S. Cook committed
137 138 139 140

C++ Interface
=============

L.S. Cook's avatar
L.S. Cook committed
141
  .. doxygenclass:: ngraph::op::Convolution
142
     :project: ngraph
L.S. Cook's avatar
L.S. Cook committed
143
     :members:
L.S. Cook's avatar
L.S. Cook committed
144

L.S. Cook's avatar
L.S. Cook committed
145