RBM.h

Go to the documentation of this file.

/*
 * Copyright (c) 2014, Shogun Toolbox Foundation
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:

 * 1. Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 *
 * 2. 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.
 *
 * 3. Neither the name of the copyright holder nor the names of its
 * contributors may be used to endorse or promote products derived from this
 * software without specific prior written permission.

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "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 COPYRIGHT HOLDER OR CONTRIBUTORS 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.
 *
 * Written (W) 2014 Khaled Nasr
 */

#ifndef __RBM_H__
#define __RBM_H__

#include <shogun/lib/config.h>

#include <shogun/lib/common.h>
#include <shogun/base/SGObject.h>
#include <shogun/lib/SGMatrix.h>
#include <shogun/lib/SGVector.h>
#include <shogun/features/DenseFeatures.h>
#include <shogun/lib/DynamicArray.h>

namespace shogun
{
enum ERBMMonitoringMethod
{
    RBMMM_RECONSTRUCTION_ERROR=0,
    RBMMM_PSEUDO_LIKELIHOOD=1
};

enum ERBMVisibleUnitType
{
    RBMVUT_BINARY=0,
    RBMVUT_GAUSSIAN=1,
    RBMVUT_SOFTMAX=2
};

class CRBM : public CSGObject
{
friend class CDeepBeliefNetwork;

public:
    CRBM();

    CRBM(int32_t num_hidden);

    CRBM(int32_t num_hidden, int32_t num_visible,
        ERBMVisibleUnitType visible_unit_type = RBMVUT_BINARY);

    virtual ~CRBM();

    virtual void add_visible_group(int32_t num_units, ERBMVisibleUnitType unit_type);

    virtual void initialize_neural_network(float64_t sigma=0.01);

    virtual void set_batch_size(int32_t batch_size);

    virtual void train(CDenseFeatures<float64_t>* features);

    virtual void sample(int32_t num_gibbs_steps=1, int32_t batch_size=1);

    virtual CDenseFeatures<float64_t>* sample_group(
            int32_t V,
            int32_t num_gibbs_steps=1, int32_t batch_size=1);

    virtual void sample_with_evidence(
            int32_t E, CDenseFeatures<float64_t>* evidence,
            int32_t num_gibbs_steps=1);

    virtual CDenseFeatures<float64_t>* sample_group_with_evidence(
            int32_t V,
            int32_t E, CDenseFeatures<float64_t>* evidence,
            int32_t num_gibbs_steps=1);

    virtual void reset_chain();

    virtual float64_t free_energy(SGMatrix<float64_t> visible,
            SGMatrix<float64_t> buffer = SGMatrix<float64_t>());

    virtual void free_energy_gradients(SGMatrix<float64_t> visible,
            SGVector<float64_t> gradients,
            bool positive_phase = true,
            SGMatrix<float64_t> hidden_mean_given_visible = SGMatrix<float64_t>());

    virtual void contrastive_divergence(SGMatrix<float64_t> visible_batch,
        SGVector<float64_t> gradients);

    virtual float64_t reconstruction_error(SGMatrix<float64_t> visible,
        SGMatrix<float64_t> buffer = SGMatrix<float64_t>());

    virtual float64_t pseudo_likelihood(SGMatrix<float64_t> visible,
        SGMatrix<float64_t> buffer = SGMatrix<float64_t>());

    virtual CDenseFeatures<float64_t>* visible_state_features()
    {
        return new CDenseFeatures<float64_t>(visible_state);
    }

    virtual SGVector<float64_t> get_parameters() { return m_params; }

    virtual SGMatrix<float64_t> get_weights(
        SGVector<float64_t> p = SGVector<float64_t>());

    virtual SGVector<float64_t> get_hidden_bias(
        SGVector<float64_t> p = SGVector<float64_t>());

    virtual SGVector<float64_t> get_visible_bias(
        SGVector<float64_t> p = SGVector<float64_t>());

    virtual int32_t get_num_parameters() { return m_num_params; }

    virtual const char* get_name() const { return "RBM"; }

protected:
    virtual void mean_hidden(SGMatrix<float64_t> visible, SGMatrix<float64_t> result);

    virtual void mean_visible(SGMatrix<float64_t> hidden, SGMatrix<float64_t> result);

    virtual void sample_hidden(SGMatrix<float64_t> mean, SGMatrix<float64_t> result);

    virtual void sample_visible(SGMatrix<float64_t> mean, SGMatrix<float64_t> result);

    virtual void sample_visible(int32_t index,
            SGMatrix<float64_t> mean, SGMatrix<float64_t> result);

private:
    void init();

public:
    int32_t cd_num_steps;

    bool cd_persistent;

    bool cd_sample_visible;

    float64_t l2_coefficient;

    float64_t l1_coefficient;

    int32_t monitoring_interval;

    ERBMMonitoringMethod monitoring_method;

    int32_t max_num_epochs;

    int32_t gd_mini_batch_size;

    float64_t gd_learning_rate;

    float64_t gd_learning_rate_decay;

    float64_t gd_momentum;

    SGMatrix<float64_t> hidden_state;

    SGMatrix<float64_t> visible_state;

protected:
    int32_t m_num_hidden;

    int32_t m_num_visible;

    int32_t m_batch_size;

    int32_t m_num_visible_groups;

    CDynamicArray<int32_t>* m_visible_group_types;

    CDynamicArray<int32_t>* m_visible_group_sizes;

    CDynamicArray<int32_t>* m_visible_state_offsets;

    int32_t m_num_params;

    SGVector<float64_t> m_params;
};

}
#endif