/home/rex/ebltrunk/core/libeblearn/include/ebl_pooling.h

/***************************************************************************
 *   Copyright (C) 2011 by Yann LeCun, Pierre Sermanet and Soumith Chintala*
 *   yann@cs.nyu.edu, pierre.sermanet@gmail.com, soumith@gmail.com  *
 *   All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Redistribution under a license not approved by the Open Source
 *       Initiative (http://www.opensource.org) must display the
 *       following acknowledgement in all advertising material:
 *        This product includes software developed at the Courant
 *        Institute of Mathematical Sciences (http://cims.nyu.edu).
 *     * The names of the authors may not be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL ThE AUTHORS BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ***************************************************************************/

#ifndef EBL_POOLING_H_
#define EBL_POOLING_H_

#include "ebl_defines.h"
#include "libidx.h"
#include "ebl_arch.h"
#include "ebl_states.h"
#include "ebl_utils.h"
#include "ebl_preprocessing.h"

namespace ebl {

  // subsampling_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class subsampling_module: public module_1_1<T, Tstate> {
  public:
    subsampling_module(parameter<T,Tstate> *p, uint thickness, idxdim &kernel,
                       idxdim &stride, const char *name = "subsampling",
                       bool crop = true, bool pad = true);
    virtual ~subsampling_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
    virtual void forget(forget_param_linear &fp);
    virtual int replicable_order() { return 3; }
    virtual bool resize_output(Tstate &in, Tstate &out);
    virtual fidxdim fprop_size(fidxdim &i_size);
    virtual fidxdim bprop_size(const fidxdim &o_size);
    virtual subsampling_module<T,Tstate>* copy();
    virtual std::string describe();
    virtual void dump_fprop(Tstate &in, Tstate &out);

    // members ////////////////////////////////////////////////////////
  public:
    Tstate              coeff; 
    Tstate              sub; 
    uint                thickness; 
    idxdim              kernel; 
    idxdim              stride; 
  protected:
    bool                crop; 
    bool                pad; 
  };

  DECLARE_REPLICABLE_MODULE_1_1(subsampling_module_replicable, 
                                subsampling_module, T, Tstate,
                                (parameter<T,Tstate> *p, uint thickness,
                                 idxdim &kernel, idxdim &strides,
                                 const char *name = "subsampling_replicable"),
                                (p, thickness, kernel, strides, name));
  
  // lppooling_module
  
  template <typename T, class Tstate = bbstate_idx<T> >
    class lppooling_module: public module_1_1<T, Tstate> {
  public:
  lppooling_module(uint thickness, idxdim &kernel, idxdim &stride,
                     uint lppower = 2, 
                     const char *name = "lppooling", 
                     bool crop = true);
    virtual ~lppooling_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
    virtual fidxdim fprop_size(fidxdim &i_size);
    virtual fidxdim bprop_size(const fidxdim &o_size);
    virtual lppooling_module<T,Tstate>* copy();
    virtual std::string describe();
    virtual void dump_fprop(Tstate &in, Tstate &out);

    // members ////////////////////////////////////////////////////////
  protected:
    uint                thickness; 
    idxdim              kernel; 
    idxdim              stride; 
    bool                crop; 
    uint                lp_pow; 
    convolution_module<T,Tstate> *conv;
    power_module<T,Tstate> sqmod;
    power_module<T,Tstate> sqrtmod;
    Tstate squared, convolved; 
    parameter<T,Tstate> param;
  };

  // wavg_pooling_module
  
  template <typename T, class Tstate = bbstate_idx<T> >
    class wavg_pooling_module: public module_1_1<T, Tstate> {
  public:
    wavg_pooling_module(uint thickness, idxdim &kernel, idxdim &stride,
                     const char *name = "wavg_pooling", bool crop = true);
    virtual ~wavg_pooling_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
    virtual fidxdim fprop_size(fidxdim &i_size);
    virtual fidxdim bprop_size(const fidxdim &o_size);
    virtual wavg_pooling_module<T,Tstate>* copy();
    virtual std::string describe();
    virtual void dump_fprop(Tstate &in, Tstate &out);

    // members ////////////////////////////////////////////////////////
  protected:
    uint                thickness; 
    idxdim              kernel; 
    idxdim              stride; 
    bool                crop; 
    convolution_module<T,Tstate> *conv;
    parameter<T,Tstate> param;
  };

  // pyramid_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class pyramid_module
    : public resizepp_module<T,Tstate>, public s2m_module<T,Tstate> {
  public:
    pyramid_module(uint nscales, float scaling_ratio, idxdim &dsize,
                   uint mode = MEAN_RESIZE, module_1_1<T,Tstate> *pp = NULL,
                   bool own_pp = false, idxdim *dzpad = NULL, 
                   const char *name = "pyramid_module");
    pyramid_module(uint nscales, float scaling_ratio, uint mode = MEAN_RESIZE,
                   module_1_1<T,Tstate> *pp = NULL, bool own_pp = false,
                   idxdim *dzpad = NULL, const char *name = "pyramid_module");
    virtual ~pyramid_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void fprop(Tstate &in, mstate<Tstate> &out);
    virtual void fprop(Tstate &in, midx<T> &out);
    virtual void bprop(Tstate &in, mstate<Tstate> &out);
    virtual void bbprop(Tstate &in, mstate<Tstate> &out);
    virtual mfidxdim bprop_size(mfidxdim &osize);
    virtual std::string describe();
    /* //! Returns bounding boxes of each scale in the input space. */
    /* const vector<rect<int> >& get_input_bboxes(); */
    /* //! Returns bounding boxes of each scale in the output space. */
    /* const vector<rect<int> >& get_original_bboxes(); */

    // members ////////////////////////////////////////////////////////
  protected:
    uint nscales; 
    float scaling_ratio; 
  };
  
  // average_pyramid_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class average_pyramid_module : public s2m_module<T,Tstate> {
  public:
    average_pyramid_module(parameter<T,Tstate> *p, uint thickness,
                           midxdim &strides, 
                           const char *name = "average_pyramid_module");
    virtual ~average_pyramid_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void fprop(Tstate &in, mstate<Tstate> &out);
    virtual void bprop(Tstate &in, mstate<Tstate> &out);
    virtual void bbprop(Tstate &in, mstate<Tstate> &out);
    virtual std::string describe();
    virtual mfidxdim bprop_size(mfidxdim &osize);

    // members ////////////////////////////////////////////////////////
  protected:
    midxdim strides; 
    std::vector<subsampling_module<T,Tstate>*> mods; 
    bool well_behaved; 
  };

  // maxss_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class maxss_module : public module_1_1<T,Tstate> {
  public:
    maxss_module(uint thickness, idxdim &kernel, idxdim &stride,
                 const char *name = "maxss");
    virtual ~maxss_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
    virtual bool resize_output(Tstate &in, Tstate &out);
    virtual int replicable_order() { return 3; }
    virtual fidxdim fprop_size(fidxdim &i_size);
    virtual fidxdim bprop_size(const fidxdim &o_size);
    virtual maxss_module<T,Tstate>* copy(parameter<T,Tstate> *p = NULL);
    virtual std::string describe();
    // members ////////////////////////////////////////////////////////
  protected:
    uint        thickness;    
    idxdim      kernel;       
    idxdim      stride;       
    idx<int>    switches;     
    bool float_precision;     
    bool double_precision;    
  //#ifdef __TH__
    idx<T>       indices;     
  //#endif
  };
  
} // namespace ebl {

#include "ebl_pooling.hpp"

#endif /* EBL_POOLING_H_ */