convolution.hpp
Go to the documentation of this file.
1 
12 #ifndef MLPACK_METHODS_ANN_LAYER_CONVOLUTION_HPP
13 #define MLPACK_METHODS_ANN_LAYER_CONVOLUTION_HPP
14 
15 #include <mlpack/prereqs.hpp>
16 
22 
23 #include "layer_types.hpp"
24 #include "padding.hpp"
25 
26 namespace mlpack {
27 namespace ann {
28 
70 template <
71  typename ForwardConvolutionRule = NaiveConvolution<ValidConvolution>,
72  typename BackwardConvolutionRule = NaiveConvolution<FullConvolution>,
73  typename GradientConvolutionRule = NaiveConvolution<ValidConvolution>,
74  typename InputDataType = arma::mat,
75  typename OutputDataType = arma::mat
76 >
78 {
79  public:
81  Convolution();
82 
99  Convolution(const size_t inSize,
100  const size_t outSize,
101  const size_t kernelWidth,
102  const size_t kernelHeight,
103  const size_t strideWidth = 1,
104  const size_t strideHeight = 1,
105  const size_t padW = 0,
106  const size_t padH = 0,
107  const size_t inputWidth = 0,
108  const size_t inputHeight = 0,
109  const std::string& paddingType = "None");
110 
131  Convolution(const size_t inSize,
132  const size_t outSize,
133  const size_t kernelWidth,
134  const size_t kernelHeight,
135  const size_t strideWidth,
136  const size_t strideHeight,
137  const std::tuple<size_t, size_t>& padW,
138  const std::tuple<size_t, size_t>& padH,
139  const size_t inputWidth = 0,
140  const size_t inputHeight = 0,
141  const std::string& paddingType = "None");
142 
143  /*
144  * Set the weight and bias term.
145  */
146  void Reset();
147 
155  template<typename eT>
156  void Forward(const arma::Mat<eT>& input, arma::Mat<eT>& output);
157 
167  template<typename eT>
168  void Backward(const arma::Mat<eT>& /* input */,
169  const arma::Mat<eT>& gy,
170  arma::Mat<eT>& g);
171 
172  /*
173  * Calculate the gradient using the output delta and the input activation.
174  *
175  * @param input The input parameter used for calculating the gradient.
176  * @param error The calculated error.
177  * @param gradient The calculated gradient.
178  */
179  template<typename eT>
180  void Gradient(const arma::Mat<eT>& /* input */,
181  const arma::Mat<eT>& error,
182  arma::Mat<eT>& gradient);
183 
185  OutputDataType const& Parameters() const { return weights; }
187  OutputDataType& Parameters() { return weights; }
188 
190  arma::cube const& Weight() const { return weight; }
192  arma::cube& Weight() { return weight; }
193 
195  arma::mat const& Bias() const { return bias; }
197  arma::mat& Bias() { return bias; }
198 
200  InputDataType const& InputParameter() const { return inputParameter; }
202  InputDataType& InputParameter() { return inputParameter; }
203 
205  OutputDataType const& OutputParameter() const { return outputParameter; }
207  OutputDataType& OutputParameter() { return outputParameter; }
208 
210  OutputDataType const& Delta() const { return delta; }
212  OutputDataType& Delta() { return delta; }
213 
215  OutputDataType const& Gradient() const { return gradient; }
217  OutputDataType& Gradient() { return gradient; }
218 
220  size_t InputWidth() const { return inputWidth; }
222  size_t& InputWidth() { return inputWidth; }
223 
225  size_t InputHeight() const { return inputHeight; }
227  size_t& InputHeight() { return inputHeight; }
228 
230  size_t OutputWidth() const { return outputWidth; }
232  size_t& OutputWidth() { return outputWidth; }
233 
235  size_t OutputHeight() const { return outputHeight; }
237  size_t& OutputHeight() { return outputHeight; }
238 
240  size_t InputSize() const { return inSize; }
241 
243  size_t OutputSize() const { return outSize; }
244 
246  size_t KernelWidth() const { return kernelWidth; }
248  size_t& KernelWidth() { return kernelWidth; }
249 
251  size_t KernelHeight() const { return kernelHeight; }
253  size_t& KernelHeight() { return kernelHeight; }
254 
256  size_t StrideWidth() const { return strideWidth; }
258  size_t& StrideWidth() { return strideWidth; }
259 
261  size_t StrideHeight() const { return strideHeight; }
263  size_t& StrideHeight() { return strideHeight; }
264 
266  size_t PadHTop() const { return padHTop; }
268  size_t& PadHTop() { return padHTop; }
269 
271  size_t PadHBottom() const { return padHBottom; }
273  size_t& PadHBottom() { return padHBottom; }
274 
276  size_t PadWLeft() const { return padWLeft; }
278  size_t& PadWLeft() { return padWLeft; }
279 
281  size_t PadWRight() const { return padWRight; }
283  size_t& PadWRight() { return padWRight; }
284 
286  size_t WeightSize() const
287  {
288  return (outSize * inSize * kernelWidth * kernelHeight) + outSize;
289  }
290 
292  size_t InputShape() const
293  {
294  return inputHeight * inputWidth * inSize;
295  }
296 
300  template<typename Archive>
301  void serialize(Archive& ar, const uint32_t /* version */);
302 
303  private:
304  /*
305  * Return the convolution output size.
306  *
307  * @param size The size of the input (row or column).
308  * @param k The size of the filter (width or height).
309  * @param s The stride size (x or y direction).
310  * @param pSideOne The size of the padding (width or height) on one side.
311  * @param pSideTwo The size of the padding (width or height) on another side.
312  * @return The convolution output size.
313  */
314  size_t ConvOutSize(const size_t size,
315  const size_t k,
316  const size_t s,
317  const size_t pSideOne,
318  const size_t pSideTwo)
319  {
320  return std::floor(size + pSideOne + pSideTwo - k) / s + 1;
321  }
322 
323  /*
324  * Function to assign padding such that output size is same as input size.
325  */
326  void InitializeSamePadding();
327 
328  /*
329  * Rotates a 3rd-order tensor counterclockwise by 180 degrees.
330  *
331  * @param input The input data to be rotated.
332  * @param output The rotated output.
333  */
334  template<typename eT>
335  void Rotate180(const arma::Cube<eT>& input, arma::Cube<eT>& output)
336  {
337  output = arma::Cube<eT>(input.n_rows, input.n_cols, input.n_slices);
338 
339  // * left-right flip, up-down flip */
340  for (size_t s = 0; s < output.n_slices; s++)
341  output.slice(s) = arma::fliplr(arma::flipud(input.slice(s)));
342  }
343 
344  /*
345  * Rotates a dense matrix counterclockwise by 180 degrees.
346  *
347  * @param input The input data to be rotated.
348  * @param output The rotated output.
349  */
350  template<typename eT>
351  void Rotate180(const arma::Mat<eT>& input, arma::Mat<eT>& output)
352  {
353  // * left-right flip, up-down flip */
354  output = arma::fliplr(arma::flipud(input));
355  }
356 
358  size_t inSize;
359 
361  size_t outSize;
362 
364  size_t batchSize;
365 
367  size_t kernelWidth;
368 
370  size_t kernelHeight;
371 
373  size_t strideWidth;
374 
376  size_t strideHeight;
377 
379  size_t padWLeft;
380 
382  size_t padWRight;
383 
385  size_t padHBottom;
386 
388  size_t padHTop;
389 
391  OutputDataType weights;
392 
394  arma::cube weight;
395 
397  arma::mat bias;
398 
400  size_t inputWidth;
401 
403  size_t inputHeight;
404 
406  size_t outputWidth;
407 
409  size_t outputHeight;
410 
412  arma::cube outputTemp;
413 
415  arma::cube inputPaddedTemp;
416 
418  arma::cube gTemp;
419 
421  arma::cube gradientTemp;
422 
424  ann::Padding<> padding;
425 
427  OutputDataType delta;
428 
430  OutputDataType gradient;
431 
433  InputDataType inputParameter;
434 
436  OutputDataType outputParameter;
437 }; // class Convolution
438 
439 } // namespace ann
440 } // namespace mlpack
441 
442 // Include implementation.
443 #include "convolution_impl.hpp"
444 
445 #endif
size_t OutputWidth() const
Get the output width.
size_t & PadWLeft()
Modify the left padding width.
InputDataType const & InputParameter() const
Get the input parameter.
size_t InputShape() const
Get the shape of the input.
size_t & PadWRight()
Modify the right padding width.
OutputDataType const & Parameters() const
Get the parameters.
Linear algebra utility functions, generally performed on matrices or vectors.
Implementation of the Padding module class.
Definition: layer_types.hpp:84
size_t & OutputHeight()
Modify the output height.
The core includes that mlpack expects; standard C++ includes and Armadillo.
OutputDataType const & OutputParameter() const
Get the output parameter.
Implementation of the Convolution class.
Definition: convolution.hpp:77
size_t KernelHeight() const
Get the kernel height.
size_t PadWRight() const
Get the right padding width.
size_t KernelWidth() const
Get the kernel width.
size_t PadHTop() const
Get the top padding height.
OutputDataType & Gradient()
Modify the gradient.
size_t StrideHeight() const
Get the stride height.
InputDataType & InputParameter()
Modify the input parameter.
size_t InputSize() const
Get the number of input maps.
size_t & KernelHeight()
Modify the kernel height.
size_t & InputHeight()
Modify the input height.
arma::mat & Bias()
Modify the bias of the layer.
size_t & PadHTop()
Modify the top padding height.
size_t StrideWidth() const
Get the stride width.
arma::mat const & Bias() const
Get the bias of the layer.
size_t InputWidth() const
Get the input width.
size_t InputHeight() const
Get the input height.
void Forward(const arma::Mat< eT > &input, arma::Mat< eT > &output)
Ordinary feed forward pass of a neural network, evaluating the function f(x) by propagating the activ...
void serialize(Archive &ar, const uint32_t)
Serialize the layer.
OutputDataType const & Delta() const
Get the delta.
void Backward(const arma::Mat< eT > &, const arma::Mat< eT > &gy, arma::Mat< eT > &g)
Ordinary feed backward pass of a neural network, calculating the function f(x) by propagating x backw...
size_t & InputWidth()
Modify input the width.
OutputDataType & Parameters()
Modify the parameters.
size_t & PadHBottom()
Modify the bottom padding height.
size_t PadWLeft() const
Get the left padding width.
size_t WeightSize() const
Get size of weights for the layer.
arma::cube const & Weight() const
Get the weight of the layer.
size_t & StrideHeight()
Modify the stride height.
size_t & OutputWidth()
Modify the output width.
arma::cube & Weight()
Modify the weight of the layer.
size_t OutputHeight() const
Get the output height.
OutputDataType & Delta()
Modify the delta.
OutputDataType & OutputParameter()
Modify the output parameter.
Convolution()
Create the Convolution object.
size_t & KernelWidth()
Modify the kernel width.
size_t & StrideWidth()
Modify the stride width.
size_t PadHBottom() const
Get the bottom padding height.
OutputDataType const & Gradient() const
Get the gradient.
size_t OutputSize() const
Get the number of output maps.