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

/***************************************************************************
 *   Copyright (C) 2008 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_ARCH_H_
#define EBL_ARCH_H_

#include "libidx.h"
#include "ebl_defines.h"
#include "ebl_states.h"

#ifndef __NOSTL__
#include <vector>
#endif

using namespace std;

namespace ebl {

#define check_bstate(ptr) \
  if (!ptr) eblerror("module buffers should be bstate_idx")
#define check_bbstate(ptr) \
  if (!ptr) eblerror("module buffers should be bbstate_idx")


  // module

  class EXPORT module {
  public:
    module(const char *name = "module");
    virtual ~module();
    virtual const char* name();
    virtual void set_name(const char *name);
    virtual void set_output_streams(std::ostream &out, std::ostream &err);
    virtual std::string describe();
    virtual std::string describe(uint indent);
    virtual void enable();
    virtual void disable();
    // members /////////////////////////////////////////////////////////////////
  protected:
    std::string _name; 
    std::ostream *mout, *merr; 
    bool silent;
    bool _enabled;
  };

  // module_1_1

  template<typename T, class Tin = bbstate_idx<T>, class Tout = Tin>
    class EXPORT module_1_1 : public module {
  public:
    module_1_1(const char *name = "module_1_1", bool bresize = true);
    virtual ~module_1_1();
    // generic states methods //////////////////////////////////////////////////
    virtual void fprop(Tin &in, Tout &out);
    virtual void bprop(Tin &in, Tout &out);
    virtual void bbprop(Tin &in, Tout &out);
    virtual void dump_fprop(Tin &in, Tout &out);
    // multi-states methods ////////////////////////////////////////////////////
    virtual void fprop(mstate<Tin> &in, mstate<Tout> &out);
    virtual void bprop(mstate<Tin> &in, mstate<Tout> &out);
    virtual void bbprop(mstate<Tin> &in, mstate<Tout> &out);
    virtual void dump_fprop(mstate<Tin> &in, mstate<Tout> &out);
    // multi-states to single-state methods ////////////////////////////////////
    virtual void fprop(mstate<Tin> &in, Tout &out);
    virtual void bprop(mstate<Tin> &in, Tout &out);
    virtual void bbprop(mstate<Tin> &in, Tout &out);
    virtual void dump_fprop(mstate<Tin> &in, Tout &out);
    // single-states to multi-state methods ////////////////////////////////////
    virtual void fprop(Tin &in, mstate<Tout> &out);
    virtual void bprop(Tin &in, mstate<Tout> &out);
    virtual void bbprop(Tin &in, mstate<Tout> &out);
    virtual void dump_fprop(Tin &in, mstate<Tout> &out);
    virtual void forget(forget_param_linear& fp);
    virtual void normalize();
    virtual int  replicable_order();
    // resizing ////////////////////////////////////////////////////////////////
    virtual bool ignored(Tin &in, Tout &out);
    virtual bool resize_output(Tin &in, Tout &out, idxdim *d = NULL);
    virtual bool resize_output(Tin &in, idx<T> &out, idxdim *d = NULL);
    virtual fidxdim fprop_size(fidxdim &isize);
    virtual fidxdim bprop_size(const fidxdim &osize);
    virtual mfidxdim fprop_size(mfidxdim &isize);
    /* //! Returns input dimensions corresponding to multiple output dimensions */
    /* //! 'osize'. Implementation of this method helps automatic scaling of input */
    /* //! data but is optional. */
    /* virtual mfidxdim bprop_size(const mfidxdim &osize); */
    virtual mfidxdim bprop_size(mfidxdim &osize);
    virtual std::string pretty(idxdim &isize);
    virtual std::string pretty(mfidxdim &isize);
    virtual module_1_1<T, Tin, Tout>* copy();
    virtual module_1_1<T, Tin, Tout>* copy(parameter<T,Tin> *p);
    virtual bool optimize_fprop(Tin &in, Tout &out);
    virtual bool optimize_fprop(mstate<Tin> &in, mstate<Tout> &out);
    virtual void load_x(idx<T> &weights);
    virtual module_1_1<T,Tin,Tout>* last_module();
    virtual bool mstate_input();
    virtual bool mstate_output();
    virtual uint get_ninputs();
    virtual uint get_noutputs();

  // variable members //////////////////////////////////////////////////////////
  public:
    // these variables describe internal buffers declared to be displayed
    // by external display objects.
    std::vector<idx<T> >     internals; 
    std::vector<std::string>    internals_str;  
  protected:
    bool                        bresize; 
    bool                        memoptimized; 
    bool                        bmstate_input;  
    bool                        bmstate_output; 
    uint                        ninputs, noutputs; 
  };

  // module_2_1

  template<typename T, class Tin1 = bbstate_idx<T>, class Tin2 = Tin1,
    class Tout = Tin1>
    class EXPORT module_2_1 : public module {
  public:
    module_2_1(const char *name = "module_2_1");
    virtual ~module_2_1();
    // generic states methods
    virtual void fprop(Tin1 &in1, Tin2 &in2, Tout &out);
    virtual void bprop(Tin1 &in1, Tin2 &in2, Tout &out);
    virtual void bbprop(Tin1 &in1, Tin2 &in2, Tout &out);
    // multi-states methods
    virtual void fprop(mstate<Tin1> &in1, mstate<Tin2> &in2,
                       mstate<Tout> &out);
    virtual void bprop(mstate<Tin1> &in1, mstate<Tin2> &in2,
                       mstate<Tout> &out);
    virtual void bbprop(mstate<Tin1> &in1, mstate<Tin2> &in2,
                        mstate<Tout> &out);
    virtual void forget(forget_param &fp);
    virtual void normalize();
    virtual bool resize_output(Tin1 &in1, Tin2 &in2, Tout &out,
                               idxdim *d = NULL);

  protected:
    bool         bresize;       
  };

  template<typename T, class Tin = bbstate_idx<T>, class Ten = Tin>
    class ebm_1 : public module {
  public:
    ebm_1(const char *name = "ebm_1");
    virtual ~ebm_1();
    virtual void fprop(Tin &in, Ten &energy);
    virtual void bprop(Tin &in, Ten &energy);
    virtual void bbprop(Tin &in, Ten &energy);
    virtual void forget(forget_param &fp);
    virtual void normalize();
  };

  // ebm_module_1_1 ////////////////////////////////////////////////////////////

  template<typename T, class Tin = bbstate_idx<T>, class Tout = Tin,
    class Ten = Tin>
    class ebm_module_1_1 : public module_1_1<T,Tin,Tout> {
  public:
    ebm_module_1_1(module_1_1<T,Tin,Tout> *m, ebm_1<T,Ten> *e,
                   const char *name = "ebm_module_1_1");
    virtual ~ebm_module_1_1();
    virtual void fprop(Tin &in, Tout &out);
    virtual void bprop(Tin &in, Tout &out);
    virtual void bbprop(Tin &in, Tout &out);
    virtual void forget(forget_param_linear &fp);
    virtual Ten& get_energy();
    virtual fidxdim fprop_size(fidxdim &isize);
    virtual fidxdim bprop_size(const fidxdim &osize);
    virtual std::string describe();
  protected:
    module_1_1<T,Tin,Tout>      *module;
    ebm_1<T,Ten>                *ebm;
    Ten                          energy;
  };

  // ebm_2

  template<class Tin1, class Tin2 = Tin1, class Ten = Tin1>
    class ebm_2 : public module {
  public:
    ebm_2(const char *name = "ebm_2");
    virtual ~ebm_2();
    virtual void fprop(Tin1 &i1, Tin2 &i2, Ten &energy);
    virtual void bprop(Tin1 &i1, Tin2 &i2, Ten &energy);
    virtual void bbprop(Tin1 &i1, Tin2 &i2, Ten &energy);

    virtual void bprop1_copy(Tin1 &i1, Tin2 &i2, Ten &energy);
    virtual void bprop2_copy(Tin1 &i1, Tin2 &i2, Ten &energy);
    virtual void bbprop1_copy(Tin1 &i1, Tin2 &i2, Ten &energy);
    virtual void bbprop2_copy(Tin1 &i1, Tin2 &i2, Ten &energy);
    virtual void forget(forget_param_linear &fp);
    virtual void normalize();
    virtual double infer1(Tin1 &i1, Tin2 &i2, Ten &energy, infer_param &ip);
    virtual double infer2(Tin1 &i1, Tin2 &i2, infer_param &ip,
                          Tin2 *label = NULL, Ten *energy = NULL);
    virtual void infer2_copy(Tin1 &i1, Tin2 &i2, Ten &energy);
  };

  // layers

  template<typename T, class Tstate = bbstate_idx<T> >
    class layers : public module_1_1<T, Tstate, Tstate> {
  public:
    layers(bool oc = true, const char *name = "layers",
           bool is_branch = false, bool narrow = false,
           intg dim = 0, intg sz = 0, intg offset = 0);
    virtual ~layers();
    virtual void add_module(module_1_1<T, Tstate, Tstate>* module);
  // TODO: fix optimize fprop
  //virtual bool optimize_fprop(Mstate &in, Mstate &out);
    // single states methods ///////////////////////////////////////////////////
    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);
    // multi to single states methods //////////////////////////////////////////
    virtual void fprop(mstate<Tstate> &in, Tstate &out);
    virtual void bprop(mstate<Tstate> &in, Tstate &out);
    virtual void bbprop(mstate<Tstate> &in, Tstate &out);
    virtual void dump_fprop(mstate<Tstate> &in, Tstate &out);
    // single to multi states methods //////////////////////////////////////////
    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 void dump_fprop(Tstate &in, mstate<Tstate> &out);
    // multi to multi methods //////////////////////////////////////////////////
    virtual void fprop(mstate<Tstate> &in, mstate<Tstate> &out);
    virtual void bprop(mstate<Tstate> &in, mstate<Tstate> &out);
    virtual void bbprop(mstate<Tstate> &in, mstate<Tstate> &out);
    virtual void dump_fprop(mstate<Tstate> &in, mstate<Tstate> &out);
    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 mfidxdim fprop_size(mfidxdim &isize);
    virtual mfidxdim bprop_size(mfidxdim &o_size);
    virtual std::string pretty(idxdim &isize);
    virtual std::string pretty(mfidxdim &isize);
    virtual layers<T,Tstate>* copy();
    virtual void swap_buffers();
    virtual uint size();
    virtual void clear_dx();
    virtual void clear_ddx();
    bool is_branch();
    module_1_1<T, Tstate, Tstate>* find(const char *name);
    virtual module_1_1<T,Tstate>* last_module();
    virtual std::string describe(uint indent = 0);
    virtual bool mstate_input();
    virtual bool mstate_output();
    virtual void set_output_streams(std::ostream &out, std::ostream &err);

    // friends /////////////////////////////////////////////////////////////////
    friend class layers_gui;

    // member variables ////////////////////////////////////////////////////////
  public:
    std::vector<module_1_1<T, Tstate, Tstate>*> modules;
    std::vector<mstate<Tstate>*>                        hiddens;
    mstate<Tstate>* intern_out; 
  protected:
    bool own_contents;
    mstate<Tstate>* hi; 
    mstate<Tstate>* ho; 
    mstate<Tstate>* htmp; 
    // used for parallelism ///////////////////////////////////////////////////
    bool branch; 
    mstate<Tstate>* intern_h0; 
    mstate<Tstate>* intern_h1; 
    bool branch_narrow; 
    intg narrow_dim; 
    intg narrow_size; 
    intg narrow_offset; 
    mstate<Tstate> msin, msout; 
  };

  // layers_2

  template<typename T, class Tin = bbstate_idx<T>, class Thid = Tin,
    class Tout = Tin>
    class EXPORT layers_2 : public module_1_1<T, Tin, Tout> {
  public:
    module_1_1<T, Tin, Thid>    &layer1;
    Thid                        &hidden;
    module_1_1<T, Thid, Tout>   &layer2;

    layers_2(module_1_1<T, Tin, Thid> &l1, Thid &h,
             module_1_1<T, Thid, Tout> &l2);
    virtual ~layers_2();
    virtual void fprop(Tin &in, Tout &out);
    virtual void bprop(Tin &in, Tout &out);
    virtual void bbprop(Tin &in, Tout &out);
    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 std::string pretty(idxdim &isize);
  };

  template<typename T, class Tin = bbstate_idx<T>, class Thid = Tin,
    class Ten = Tin>
    class EXPORT fc_ebm1 : public ebm_1<T, Tin, Ten> {
  public:
    module_1_1<T,Tin,Thid>      &fmod;
    Thid                        &fout;
    ebm_1<T,Thid,Ten>           &fcost;

    fc_ebm1(module_1_1<T,Tin,Thid> &fm, Thid &fo, ebm_1<T,Thid,Ten> &fc);
    virtual ~fc_ebm1();

    virtual void fprop(Tin &in, Ten &energy);
    virtual void bprop(Tin &in, Ten &energy);
    virtual void bbprop(Tin &in, Ten &energy);
    virtual void forget(forget_param &fp);
  };

  template<typename T, class Tin1 = bbstate_idx<T>, class Tin2 = Tin1,
    class Ten = Tin1>
    class EXPORT fc_ebm2 : public ebm_2<Tin1, Tin2, Ten> {
  public:
    module_1_1<T, Tin1, Tin1>   &fmod;
    Tin1                        &fout;
    ebm_2<Tin1, Tin2, Ten>      &fcost;

    fc_ebm2(module_1_1<T, Tin1> &fm, Tin1 &fo, ebm_2<Tin1, Tin2, Ten> &fc);
    virtual ~fc_ebm2();

    virtual void fprop(Tin1 &in1, Tin2 &in2, Ten &energy);
    virtual void bprop(Tin1 &in1, Tin2 &in2, Ten &energy);
    virtual void bbprop(Tin1 &in1, Tin2 &in2, Ten &energy);
    virtual void forget(forget_param_linear &fp);
    virtual double infer2(Tin1 &i1, Tin2 &i2, infer_param &ip,
                          Tin2 *label = NULL, Ten *energy = NULL);
  };

  // helper functions

  template<typename T, class Tstate>
    void check_replicable_orders(module_1_1<T,Tstate> &m, Tstate& in);

  // generic replicable module classes

  template<class Tmodule, typename T, class Tstate = bbstate_idx<T> >
    class EXPORT module_1_1_replicable {
  public:
    Tmodule &module;
    module_1_1_replicable(Tmodule &m);
    virtual ~module_1_1_replicable();
    virtual void fprop(Tstate &in, Tstate &out);
    virtual void bprop(Tstate &in, Tstate &out);
    virtual void bbprop(Tstate &in, Tstate &out);
  };

#define DECLARE_REPLICABLE_MODULE_1_1(replicable_module, base_module,   \
                                      T, Tstate,                        \
                                      types_arguments, arguments)       \
  template <typename T, class Tstate = bbstate_idx<T> >                 \
    class EXPORT replicable_module : public base_module<T,Tstate> {             \
  public:                                                               \
    module_1_1_replicable<base_module<T,Tstate>,T,Tstate> *rep;         \
    replicable_module types_arguments : base_module<T,Tstate> arguments { \
      rep = new module_1_1_replicable<base_module<T,Tstate>,T,Tstate>(*this); \
      this->bresize = false;                                            \
      if (this->replicable_order() <= 0)                                \
        eblerror("this module is not replicable"); }                    \
    virtual ~replicable_module() { delete rep; }                        \
    virtual void fprop(Tstate &in, Tstate &out)                         \
    { rep->fprop(in, out); }                                            \
    virtual void bprop(Tstate &in, Tstate &out)                         \
    { rep->bprop(in, out); }                                            \
    virtual void bbprop(Tstate &in, Tstate &out)                        \
    { rep->bbprop(in, out); }                                           \
  }

  template<typename T, class Tstate = bbstate_idx<T> >
    class EXPORT narrow_module : public module_1_1<T,Tstate,Tstate> {
  public:
    narrow_module(int d, intg size, intg offset, bool narrow_states = false);
    narrow_module(int d, intg size, vector<intg> &offsets,
                  bool narrow_states = false, const char *name = "narrow");
    virtual ~narrow_module();
    // multi-state inputs and outputs //////////////////////////////////////////
    virtual void fprop(mstate<Tstate> &in, mstate<Tstate> &out);
    virtual void bprop(mstate<Tstate> &in, mstate<Tstate> &out);
    virtual void bbprop(mstate<Tstate> &in, mstate<Tstate> &out);
    // single-state inputs and outputs /////////////////////////////////////////
    virtual void fprop(Tstate &in, Tstate &out);
    virtual std::string describe();
    virtual narrow_module<T,Tstate>* copy();
    virtual mfidxdim fprop_size(mfidxdim &isize);
    virtual mfidxdim bprop_size(mfidxdim &osize);
  protected:
    int dim; 
    intg size; 
    vector<intg> offsets; 
    bool narrow_states; 
  };

  template<typename T, class Tstate = bbstate_idx<T> >
    class EXPORT table_module : public module_1_1<T,Tstate,Tstate> {
  public:
    table_module(vector<intg> &inputs, intg total,
                 const char *name = "table_module");
    virtual ~table_module();
    // multi-state inputs and outputs //////////////////////////////////////////
    virtual void fprop(mstate<Tstate> &in, mstate<Tstate> &out);
    virtual void bprop(mstate<Tstate> &in, mstate<Tstate> &out);
    virtual void bbprop(mstate<Tstate> &in, mstate<Tstate> &out);
    virtual std::string describe();
    virtual table_module<T,Tstate>* copy();
    virtual mfidxdim fprop_size(mfidxdim &isize);
    virtual mfidxdim bprop_size(mfidxdim &osize);
  protected:
    vector<intg> table; 
    intg total; 
  };

  // network sizes methods /////////////////////////////////////////////////////

  template <typename T, class Tstate>
    EXPORT idxdim network_mindims(module_1_1<T,Tstate> &m, uint order);

} // namespace ebl {

#include "ebl_arch.hpp"

#endif /* EBL_ARCH_H_ */