PLearn 0.1
RBMLayer.h
Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 // RBMLayer.h
00004 //
00005 // Copyright (C) 2006 Dan Popovici
00006 //
00007 // Redistribution and use in source and binary forms, with or without
00008 // modification, are permitted provided that the following conditions are met:
00009 //
00010 //  1. Redistributions of source code must retain the above copyright
00011 //     notice, this list of conditions and the following disclaimer.
00012 //
00013 //  2. Redistributions in binary form must reproduce the above copyright
00014 //     notice, this list of conditions and the following disclaimer in the
00015 //     documentation and/or other materials provided with the distribution.
00016 //
00017 //  3. The name of the authors may not be used to endorse or promote
00018 //     products derived from this software without specific prior written
00019 //     permission.
00020 //
00021 // THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
00022 // IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
00023 // OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
00024 // NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
00025 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
00026 // TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00027 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00028 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00029 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00030 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00031 //
00032 // This file is part of the PLearn library. For more information on the PLearn
00033 // library, go to the PLearn Web site at www.plearn.org
00034 
00035 // Authors: Dan Popovici
00036 
00040 #ifndef RBMLayer_INC
00041 #define RBMLayer_INC
00042 
00043 #include <plearn/base/Object.h>
00044 #include "OnlineLearningModule.h"
00045 
00046 namespace PLearn {
00047 using namespace std;
00048 
00049 // forward declarations
00050 class RBMConnection;
00051 
00056 class RBMLayer: public OnlineLearningModule
00057 {
00058     typedef OnlineLearningModule inherited;
00059 
00060 public:
00061     //#####  Public Build Options  ############################################
00062 
00064     real learning_rate;
00065 
00067     real momentum;
00068 
00070     int size;
00071 
00073     string units_types;
00074 
00076     string bias_decay_type;
00077 
00079     real bias_decay_parameter;
00080 
00086     Vec gibbs_ma_schedule;
00087     real gibbs_ma_increment;
00088     real gibbs_initial_ma_coefficient;
00089 
00090     //#####  Learnt Options  ##################################################
00091 
00092     // stores the bias of the unit
00093     Vec bias;
00094 
00096     real gibbs_ma_coefficient;
00097 
00098     //#####  Not Options  #####################################################
00099 
00101     int batch_size;
00102 
00104     Vec activation;
00105     Mat activations; // for mini-batch operations
00106 
00108     Vec sample;
00109     Mat samples;
00110 
00112     Vec expectation;
00113 
00116     bool expectation_is_up_to_date;
00117 
00120     bool expectations_are_up_to_date;
00121 
00122     static const int INFINITE_CONFIGURATIONS = 0x7fffffff;
00123 
00124 public:
00125     //#####  Public Member Functions  #########################################
00126 
00128     RBMLayer( real the_learning_rate=0. );
00129 
00130     // Your other public member functions go here
00131 
00133     virtual void setLearningRate( real the_learning_rate );
00134 
00136     virtual void setMomentum( real the_momentum );
00137 
00139     virtual void setBatchSize( int the_batch_size );
00140 
00142     virtual void setExpectation(const Vec& the_expectation);
00143 
00146     virtual void setExpectationByRef(const Vec& the_expectation);
00147 
00149     virtual void setExpectations(const Mat& the_expectations);
00150 
00153     virtual void setExpectationsByRef(const Mat& the_expectations);
00154 
00156     const Mat& getExpectations();
00157 
00160     virtual void getUnitActivation( int i, PP<RBMConnection> rbmc,
00161                                     int offset=0 );
00162 
00165     virtual void getAllActivations( PP<RBMConnection> rbmc, int offset = 0,
00166                                     bool minibatch = false);
00167 
00168     //change the flag of expectation_is_up_to_date to false
00169     virtual void expectation_is_not_up_to_date();
00170 
00172     virtual void generateSample() = 0 ;
00173 
00175     virtual void generateSamples() = 0;
00176 
00178     virtual void computeExpectation() = 0 ;
00179 
00181     virtual void computeExpectations() = 0 ;
00182 
00185     virtual void fprop(const Vec& input, Vec& output) const;
00186     virtual void fprop(const Mat& inputs, Mat& outputs);
00187 
00190     virtual void fprop( const Vec& input, const Vec& rbm_bias,
00191                         Vec& output ) const;
00192 
00195     virtual void bpropUpdate(const Vec& input, const Vec& output,
00196                              Vec& input_gradient,
00197                              const Vec& output_gradient,
00198                              bool accumulate=false) = 0 ;
00199 
00201     virtual void bpropUpdate(const Mat& inputs, const Mat& outputs,
00202                              Mat& input_gradients,
00203                              const Mat& output_gradients,
00204                              bool accumulate=false) = 0;
00205 
00207     virtual void bpropUpdate(const Vec& input, const Vec& rbm_bias,
00208                              const Vec& output,
00209                              Vec& input_gradient, Vec& rbm_bias_gradient,
00210                              const Vec& output_gradient);
00211 
00214     virtual real fpropNLL(const Vec& target);
00215     virtual void fpropNLL(const Mat& targets, const Mat& costs_column);
00216     virtual real fpropNLL(const Vec& target, const Vec& cost_weights);
00217 
00220     virtual void bpropNLL(const Vec& target, real nll, Vec& bias_gradient);
00221     virtual void bpropNLL(const Mat& targets, const Mat& costs_column,
00222                           Mat& bias_gradients);
00223 
00225     virtual void accumulatePosStats( const Vec& pos_values );
00226     virtual void accumulatePosStats( const Mat& ps_values);
00227 
00229     virtual void accumulateNegStats( const Vec& neg_values );
00230     virtual void accumulateNegStats( const Mat& neg_values );
00231 
00233     virtual void update();
00234 
00236     virtual void update( const Vec& grad );
00237     virtual void update( const Mat& grad );
00238 
00240     virtual void update( const Vec& pos_values, const Vec& neg_values );
00241 
00243     virtual void update( const Mat& pos_values, const Mat& neg_values );
00244 
00245     // neg_stats <-- gibbs_chain_statistics_forgetting_factor * neg_stats
00246     //              +(1-gibbs_chain_statistics_forgetting_factor)
00247     //               * gibbs_neg_values
00248     // delta w = -lrate * ( pos_values
00249     //                  - ( background_gibbs_update_ratio*neg_stats
00250     //                     +(1-background_gibbs_update_ratio)
00251     //                      * cd_neg_values ) )
00252     virtual void updateCDandGibbs( const Mat& pos_values,
00253                                    const Mat& cd_neg_values,
00254                                    const Mat& gibbs_neg_values,
00255                                    real background_gibbs_update_ratio );
00256 
00257     // neg_stats <-- gibbs_chain_statistics_forgetting_factor * neg_stats
00258     //              +(1-gibbs_chain_statistics_forgetting_factor)
00259     //               * \sum_i gibbs_neg_values_i / minibatch_size
00260     // delta bias = -lrate * \sum_i (pos_values_i - neg_stats) / minibatch_size
00261     virtual void updateGibbs( const Mat& pos_values,
00262                               const Mat& gibbs_neg_values );
00263 
00265     virtual void reset();
00266 
00268     virtual void clearStats();
00269 
00271     virtual void forget();
00272 
00274     virtual void setAllBias(const Vec& rbm_bias);
00275 
00279     virtual void bpropCD(Vec& bias_gradient);
00280 
00284     virtual void bpropCD(const Vec& pos_values, const Vec& neg_values,
00285                          Vec& bias_gradient);
00286 
00287     virtual real energy(const Vec& unit_values) const;
00288 
00292     virtual real freeEnergyContribution(const Vec& unit_activations) const;
00293 
00298     virtual void freeEnergyContributionGradient(const Vec& unit_activations,
00299                                                 Vec& unit_activations_gradient,
00300                                                 real output_gradient = 1,
00301                                                 bool accumulate = false )
00302         const;
00303 
00305     virtual int getConfigurationCount();
00306 
00308     virtual void getConfiguration(int conf_index, Vec& output);
00309 
00311     virtual void applyBiasDecay();
00312 
00314     virtual void addBiasDecay(Vec& bias_gradient);
00315 
00317     virtual void addBiasDecay(Mat& bias_gradient);
00318 
00319     //#####  PLearn::Object Protocol  #########################################
00320 
00321     // Declares other standard object methods.
00322     PLEARN_DECLARE_ABSTRACT_OBJECT(RBMLayer);
00323 
00324     // Simply calls inherited::build() then build_()
00325     virtual void build();
00326 
00328     virtual void makeDeepCopyFromShallowCopy(CopiesMap& copies);
00329 
00330 
00331     //#####  Not Options  #####################################################
00332 public:
00334     Vec bias_pos_stats;
00336     Vec bias_neg_stats;
00337 protected:
00339     Vec bias_inc;
00340 
00343     Vec ones;
00344 
00346     int pos_count;
00348     int neg_count;
00349 
00352     Mat expectations;
00353 
00354     Vec tmp;
00355 
00356 protected:
00357     //#####  Protected Member Functions  ######################################
00358 
00360     static void declareOptions(OptionList& ol);
00361 
00363     static void declareMethods(RemoteMethodMap& rmm);
00364 
00365 private:
00366     //#####  Private Member Functions  ########################################
00367 
00369     void build_();
00370 
00371 private:
00372     //#####  Private Data Members  ############################################
00373 
00374 };
00375 
00376 // Declares a few other classes and functions related to this class
00377 DECLARE_OBJECT_PTR(RBMLayer);
00378 
00379 } // end of namespace PLearn
00380 
00381 #endif
00382 
00383 
00384 /*
00385   Local Variables:
00386   mode:c++
00387   c-basic-offset:4
00388   c-file-style:"stroustrup"
00389   c-file-offsets:((innamespace . 0)(inline-open . 0))
00390   indent-tabs-mode:nil
00391   fill-column:79
00392   End:
00393 */
00394 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=79 :
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines