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

/***************************************************************************
 *   Copyright (C) 2011 by Yann LeCun and Pierre Sermanet *
 *   yann@cs.nyu.edu, pierre.sermanet@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_NORMALIZATION_H_
#define EBL_NORMALIZATION_H_

#include "ebl_defines.h"
#include "libidx.h"
#include "ebl_states.h"
#include "ebl_basic.h"
#include "ebl_arch.h"
#include "ebl_nonlinearity.h"

namespace ebl {

  template <typename T, class Tstate = bbstate_idx<T> >
    class divisive_norm_module : public module_1_1<T, Tstate> {
  public:
    divisive_norm_module(idxdim &kerdim, int nf, bool mirror = false,
                         bool threshold = true, parameter<T,Tstate> *p = NULL,
                         const char *name = "divisive_norm",
                         bool across_features = true, double cgauss = 2.0,
                         bool fsum_div = false, float fsum_split = 1.0,
                         double epsilon = 1e-6);
    virtual ~divisive_norm_module();    
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
    virtual void dump_fprop(Tstate &in, Tstate &out);
    virtual divisive_norm_module<T,Tstate>* copy(parameter<T,Tstate> *p = NULL);
    virtual bool optimize_fprop(Tstate &in, Tstate &out);
    virtual std::string describe();

    // friends
    friend class divisive_norm_module_gui;
    friend class contrast_norm_module_gui;
    template <typename T1, class Tstate1> friend class contrast_norm_module;

    // members ////////////////////////////////////////////////////////
  public:
    bool                                 mirror; 
  protected:
    parameter<T,Tstate>                 *param;
    layers<T, Tstate>                    convvar;
    power_module<T,Tstate>               sqrtmod;       
    power_module<T,Tstate>               invmod;        
    power_module<T,Tstate>               sqmod; 
    thres_module<T,Tstate>               thres; 
    mul_module<T,Tstate>                 mcw;
    convolution_module<T,Tstate>        *divconv;
    module_1_1<T,Tstate>                *padding;
    idx<T>                               w;     
    Tstate                               insq, invar, instd, thstd, invstd;
    bool                                 threshold;
    int                                  nfeatures;
    idxdim                               kerdim;
    bool                                 across_features;
    double                               epsilon; 
  };

  template <typename T, class Tstate = bbstate_idx<T> >
    class subtractive_norm_module : public module_1_1<T, Tstate> {
  public:
    subtractive_norm_module(idxdim &kerdim, int nf, bool mirror = false,
                            bool global_norm = false,
                            parameter<T,Tstate> *p = NULL,
                            const char *name = "subtractive_norm",
                            bool across_features = true,
                            double cgauss = 2.0, bool fsum_div = false,
                            float fsum_split = 1.0);
    virtual ~subtractive_norm_module();    
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
    virtual void dump_fprop(Tstate &in, Tstate &out);
    virtual subtractive_norm_module<T,Tstate>*
      copy(parameter<T,Tstate> *p = NULL);
    virtual bool optimize_fprop(Tstate &in, Tstate &out);
    virtual std::string describe();

    // friends
    friend class contrast_norm_module_gui;
    template <typename T1, class Tstate1> friend class contrast_norm_module;
  
    // members ////////////////////////////////////////////////////////
  protected:
    parameter<T,Tstate>                 *param;
    layers<T, Tstate>                    convmean;
    convolution_module<T,Tstate>        *meanconv;
    module_1_1<T,Tstate>                *padding;
    idx<T>                               w;     
    diff_module<T,Tstate>                difmod;
    Tstate                               inmean;
    bool                                 global_norm;
    int                                  nfeatures;
    idxdim                               kerdim;
    bool                                 across_features;
    bool                                 mirror; 
  };

  template <typename T, class Tstate = bbstate_idx<T> >
    class contrast_norm_module : public module_1_1<T,Tstate> {
  public:
    contrast_norm_module(idxdim &kerdim, int nf, bool mirror = false,
                         bool threshold = true, bool global_norm = false,
                         parameter<T,Tstate> *p = NULL,
                         const char *name = "contrast_norm",
                         bool across_features = true, bool learn_mean = false,
                         double cnorm = 2.0, bool fsum_div = false,
                         float fsum_split = 1.0, double epsilon = 1e-6);
    virtual ~contrast_norm_module();    
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
    virtual void dump_fprop(Tstate &in, Tstate &out);
    virtual contrast_norm_module<T,Tstate>* copy(parameter<T,Tstate> *p = NULL);
    virtual bool optimize_fprop(Tstate &in, Tstate &out);
    virtual std::string describe();

    // friends
    friend class contrast_norm_module_gui;

    // members ////////////////////////////////////////////////////////
  protected:
    subtractive_norm_module<T, Tstate>  subnorm;
    divisive_norm_module<T, Tstate>     divnorm;
    Tstate                              tmp;
    bool                                global_norm;
    bool                                learn_mean;
  };

  // laplacian_module
  template <typename T, class Tstate = bbstate_idx<T> >
    class laplacian_module : public module_1_1<T, Tstate> {
  public:
    laplacian_module(int nf, bool mirror = false, bool global_norm = false,
                     const char *name = "laplacian_module");
    virtual ~laplacian_module();    
    virtual void fprop(Tstate &in, Tstate &out);
    virtual laplacian_module<T,Tstate>* copy();
    virtual std::string describe();

    // members ////////////////////////////////////////////////////////
  private:
    bool                mirror; 
    convolution_module<T,Tstate> *conv;
    module_1_1<T,Tstate> *pad;
    diff_module<T,Tstate> diff;
    Tstate              padded, filtered;
    parameter<T,Tstate> param;
    idx<T>              filter; 
    bool                global_norm; 
    int                 nfeatures;
    idxdim              kerdim;
  };

} // namespace ebl {

#include "ebl_normalization.hpp"

#endif /* EBL_NORMALIZATION_H_ */