/home/rex/ebltrunk/core/libeblearn/include/ebl_basic.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_BASIC_H_
#define EBL_BASIC_H_

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

namespace ebl {

  // linear_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class linear_module: public module_1_1<T, Tstate> {
  public:
    linear_module(parameter<T,Tstate> *p, intg in, intg out,
                  const char *name = "linear");
    virtual ~linear_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
    virtual int replicable_order() { return 1; }
    virtual void forget(forget_param_linear &fp);
    virtual void normalize();
    virtual fidxdim fprop_size(fidxdim &i_size);
    virtual fidxdim bprop_size(const fidxdim &o_size);
    virtual linear_module<T,Tstate>* copy(parameter<T,Tstate> *p = NULL);
    virtual void load_x(idx<T> &weights);
    virtual std::string describe();
    virtual void dump_fprop(Tstate &in, Tstate &out);

  /* bool resize_output(Tstate &in, Tstate &out); */


    // members ////////////////////////////////////////////////////////
  public:
    Tstate w;
  };

  DECLARE_REPLICABLE_MODULE_1_1(linear_module_replicable,
                                linear_module, T, Tstate,
                                (parameter<T,Tstate> *p, intg in, intg out,
                                 const char *name = "linear_replicable"),
                                (p, in, out, name));

  // convolution_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class convolution_module : public module_1_1<T, Tstate> {
  public:
    convolution_module(parameter<T,Tstate> *p, idxdim &ker, idxdim &stride,
                       idx<intg> &table, const char *name = "convolution",
                       bool crop = true);
    virtual ~convolution_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 convolution_module<T,Tstate>* copy(parameter<T,Tstate> *p = NULL);
    virtual void load_x(idx<T> &weights);
    virtual std::string describe();
    virtual void dump_fprop(Tstate &in, Tstate &out);

    // members ////////////////////////////////////////////////////////
  public:
    intg                tablemax;
    Tstate              kernel;
    intg                thickness;
    idxdim              ker;
    idxdim              stride;
    idx<intg>           table;  
  protected:
    bool                warnings_shown;
    bool                fulltable; 
    bool                float_precision; 
    bool                double_precision; 
    bool                crop; 
  // IPP members ////////////////////////////////////////////////////////
    idx<T>              revkernel; 
    idx<T>              outtmp; 
    bool                ipp_err_printed; 
    bool                use_ipp; 
  };

  DECLARE_REPLICABLE_MODULE_1_1(convolution_module_replicable,
                                convolution_module, T, Tstate,
                                (parameter<T,Tstate> *p,
                                 idxdim &ker, idxdim &stride, idx<intg> &table,
                                 const char *name = "convolution_replicable"),
                                (p, ker, stride, table, name));

  // addc_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class addc_module: public module_1_1<T, Tstate> {
  public:
    addc_module(parameter<T,Tstate> *p, intg size, const char *name = "addc");
    virtual ~addc_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 addc_module<T,Tstate>* copy(parameter<T,Tstate> *p = NULL);
    virtual void load_x(idx<T> &weights);
    virtual std::string describe();
    virtual void dump_fprop(Tstate &in, Tstate &out);

    // members ////////////////////////////////////////////////////////
  public:
    Tstate  bias; 
  };

  // power_module
  // TODO: write specialized modules square and sqrt to run faster
  template <typename T, class Tstate = bbstate_idx<T> >
    class power_module : public module_1_1<T,Tstate> {
  public:
    power_module(T p);
    virtual ~power_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);

    // members ////////////////////////////////////////////////////////
  private:
    T p;
    idx<T> tt; 
  };

  // diff_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class diff_module : public module_2_1<T, Tstate> {
  public:
    diff_module();
    virtual ~diff_module();
    virtual void fprop(Tstate &in1, Tstate &in2, Tstate &out);
    virtual void bprop(Tstate &in1, Tstate &in2, Tstate &out);
    virtual void bbprop(Tstate &in1, Tstate &in2, Tstate &out);
  };

  // mul_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class mul_module : public module_2_1<T, Tstate> {
  private:
    idx<T> tmp; 

  public:
    mul_module();
    virtual ~mul_module();
    virtual void fprop(Tstate &in1, Tstate &in2, Tstate &out);
    virtual void bprop(Tstate &in1, Tstate &in2, Tstate &out);
    virtual void bbprop(Tstate &in1, Tstate &in2, Tstate &out);
  };

  // thres_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class thres_module : public module_1_1<T,Tstate> {
  public:
    T thres;
    T val;

  public:
    thres_module(T thres, T val);
    virtual ~thres_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
  };


  // cutborder_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class cutborder_module : module_1_1<T,Tstate> {
  private:
    int nrow, ncol;

  public:
    cutborder_module(int nr, int nc);
    virtual ~cutborder_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
  };

  // zpad_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class zpad_module : public module_1_1<T,Tstate> {
  public:
    zpad_module(const char *name = "zpad");
    zpad_module(int nrows, int ncolumns);
    zpad_module(int top, int left, int bottom, int right);
    zpad_module(idxdim &kernel_size, const char *name = "zpad");
    zpad_module(midxdim &kernels, const char *name = "zpad");
    virtual ~zpad_module();
    virtual void fprop(mstate<Tstate> &in, mstate<Tstate> &out);
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void fprop(Tstate &in, idx<T> &out);
    virtual void fprop(idx<T> &in, idx<T> &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
    virtual idxdim get_paddings();
    virtual idxdim get_paddings(idxdim &kernel);
    virtual midxdim get_paddings(midxdim &kernels);
    virtual void set_paddings(int top, int left, int bottom, int right);
    virtual void set_paddings(idxdim &pads);
    virtual void set_kernel(idxdim &kernel);
    virtual void set_kernels(midxdim &kernels);
    virtual fidxdim fprop_size(fidxdim &i_size);
    virtual fidxdim bprop_size(const fidxdim &o_size);
    virtual mfidxdim fprop_size(mfidxdim &isize);
    virtual mfidxdim bprop_size(mfidxdim &osize);
    virtual std::string describe();
    virtual zpad_module<T,Tstate>* copy(parameter<T,Tstate> *p = NULL);

  protected:
    idxdim pad; 
    midxdim pads; 
  };

  // mirrorpad_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class mirrorpad_module : public zpad_module<T,Tstate> {
  public:
    mirrorpad_module(int nr, int nc);
    mirrorpad_module(idxdim &kernel_size);
    virtual ~mirrorpad_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void fprop(Tstate &in, idx<T> &out);
    virtual mirrorpad_module<T,Tstate>* copy(parameter<T,Tstate> *p = NULL);
  protected:
    using zpad_module<T,Tstate>::pad;
  };

  // fsum_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class fsum_module : public module_1_1<T,Tstate> {
  public:
    fsum_module(bool div = false, float split = 1.0);
    virtual ~fsum_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
  protected:
    bool div; 
    float split; 
  };

  // range_lut_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class range_lut_module : public module_1_1<T,Tstate> {
  public:
    range_lut_module(idx<T> *value_range);
    virtual ~range_lut_module();
    virtual void fprop(Tstate &in, Tstate &out);
    /* //! backward propagation from out to in */
    /* virtual void bprop(Tstate &in, Tstate &out); */
    /* //! second-derivative backward propagation from out to in */
    /* virtual void bbprop(Tstate &in, Tstate &out); */
  protected:
    idx<T>      value_range;
  };

  // binarize_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class binarize_module : public module_1_1<T,Tstate> {
  public:
    binarize_module(T threshold, T false_value, T true_value);
    virtual ~binarize_module();
    virtual void fprop(Tstate &in, Tstate &out);
    /* //! backward propagation from out to in */
    /* virtual void bprop(Tstate &in, Tstate &out); */
    /* //! second-derivative backward propagation from out to in */
    /* virtual void bbprop(Tstate &in, Tstate &out); */
  protected:
    T   threshold;
    T   false_value;
    T   true_value;
  };

  // diag_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class diag_module : public module_1_1<T,Tstate> {
  public:
    diag_module(parameter<T,Tstate> *p, intg thickness,
                const char *name = "diag");
    virtual ~diag_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 void load_x(idx<T> &weights);
    virtual std::string describe();
    virtual diag_module<T,Tstate>* copy(parameter<T,Tstate> *p = NULL);
  protected:
    Tstate      coeff;
  };

  // copy_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class copy_module : public module_1_1<T,Tstate> {
  public:
    copy_module(const char *name = "copy");
    virtual ~copy_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
    virtual std::string describe();
  };

  // back_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class back_module : public module_1_1<T,Tstate> {
  public:
    back_module(const char *name = "back");
    virtual ~back_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual bool resize_output(Tstate &in, Tstate &out);
    virtual std::string describe();
    virtual fidxdim bprop_size(const fidxdim &o_size);
    void bb(std::vector<bbox*> &boxes);

  protected:
    idx<T>      *s0;
    idx<T>      *s1;
    idx<T>      *s2;
    idxdim       pixel_size;
  };

  // printer_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class printer_module : module_1_1<T,Tstate> {

  public:
    printer_module(const char *name = "printer");
    virtual ~printer_module();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
  };



} // namespace ebl {

#include "ebl_basic.hpp"

#endif /* EBL_BASIC_H_ */