Neuron.h

/**
 * DESCRIPTION OF THE CLASS
 *
 * @author Martin Beseda
 * @author Martin Mrovec
 * @author Michal Kravčenko
 * @date 2017 - 2018
 */

 #ifndef NEURON_H_
 #define NEURON_H_

#include <boost/serialization/base_object.hpp>
#include <vector>
#include "../NetConnection/Connection.h"

class Connection;

/**
  * Abstract class representing a general neuron
  */
class Neuron{
    friend class boost::serialization::access;

protected:
    /**
     * Inner potential of the neuron (input of the activation function)
     */
    double potential = 0.0;

    /**
     * State of the neuron (output of the activation function)
     */
    double state = 0.0;

    /**
     * array of the activation function parameters
     */
    double *activation_function_parameters = nullptr;

    /**
     * Number of parameters of the activation function
     */
    unsigned int n_activation_function_parameters = 0;

    /**
     * Keeps track of the number of saturated INCOMING connections
     */
    unsigned int n_saturated_connections_in = 0;

    /**
     * Keeps track of the number of saturated OUTGOING connections
     */
    unsigned int n_saturated_connections_out = 0;

    /**
     * Index of this neuron among the neurons in the neural network
     */
    size_t neural_net_index;

    /**
     * A pointer to a vector containing pointers to incoming connections
     */
    std::vector<Connection*> *edges_in = nullptr;

    /**
     * A pointer to a vector containing pointers to outgoing connections
     */
    std::vector<Connection*> *edges_out = nullptr;

    template<class Archive>
    void serialize(Archive & ar, const unsigned int version){
        //TODO separate implementation to Neuron.cpp!
        ar & this->potential;
        ar & this->state;

        for(unsigned short int i = 0; i < this->n_activation_function_parameters; i++) {
            ar & this->activation_function_parameters[i];
        }
    };

public:

    /**
     * Instantiates a copy of this object and returns a pointer to it
     * @return
     */
    virtual Neuron* get_copy( ) = 0;

    /**
     * Destructor of the Neuron object
     * this level deallocates the array 'activation_function_parameters'
     * also deallocates the OUTGOING connections
     */
    virtual ~Neuron();

    /**
     * Performs the activation function and stores the result into the 'state' property
     */
    virtual void activate( ) = 0;

    /**
     * Sets the number of saturated INPUT connections to the prescribed value
     * @param[in] value The number of saturated INCOMING connections
     */
    virtual void set_saturation_in(int value) final;

    /**
     * Increases the saturation counter of the INCOMING connections by the specified amount
     * @param value Amount to be added to the counter
     */
    virtual void adjust_saturation_in(int value) final;

    /**
     * Returns true if the neuron is saturated via the INCOMING connections
     * @return true/false
     */
    virtual bool is_saturated_in() final;

    /**
     * Returns true if the neuron is saturated via the OUTGOING connections
     * @return true/false
     */
    virtual bool is_saturated_out() final;

    /**
     * Sets the number of saturated OUTPUT connections to the prescribed value
     * @param[in] value The number of saturated OUTGOING connections
     */
    virtual void set_saturation_out(int value) final;

    /**
     * Increases the saturation counter of the OUTGOING connections by the specified amount
     * @param value Amount to be added to the counter
     */
    virtual void adjust_saturation_out(int value) final;

    /**
     * Adds the input signal value to the current potential
     * @param[in] input_signal Input value
     */
    virtual void adjust_potential(double input_signal);

    /**
     * Getter to the 'potential' property
     * @return Value of the neuron's potential (real number)
     */
    virtual double get_potential();

    /**
     * Setter to the 'potential' property
     * @param[in] value Value of the neuron's potential (real number)
     */
    virtual void set_potential(double value);

    /**
     * Getter to the 'state' property
     * @return Value of the current neuron's state
     */
    virtual double get_state();

    /**
     * Setter to the 'state' component
     * @param[in] value Value of the current neuron's state
     */
    virtual void set_state(double value);

    /**
     * Returns the number of parameters the activation function relies on
     * @return Number of the parameters
     */
    virtual int activation_function_get_n_parameters();

    /**
     * Adjusts the parameter with index 'param_idx' of the activation function
     * by the value prescribed by 'value'
     * @param[in] param_idx Index of the parameter to be adjusted
     * @param[in] value Value of the adjustment
     */
    virtual void activation_function_adjust_parameter(int param_idx, double value);

    /**
     * Sets the parameter with index 'param_idx' of the activation function
     * to the value prescribed by 'value'
     * @param[in] param_idx
     * @param[in] value
     */
    virtual void activation_function_set_parameter(int param_idx, double value);

    /**
     * Gets the parameter with index 'param_idx' of the activation function
     * @param[in] param_idx
     */
    virtual double activation_function_get_parameter(int param_idx);

    /**
     * Adds a new incoming connection with this neuron as its end-point
     * @param[in] con Incoming connection
     */
    virtual void add_connection_in(Connection *con) final;

    /**
     * Adds a new outgoing connection with this neuron as its source-point
     * @param[in] con Outgoing connection
     */
    virtual void add_connection_out(Connection *con) final;

    /**
     * Returns the pointer to the incoming connection vector
     * @return
     */
    virtual std::vector<Connection*>* get_connections_in( ) final;

    /**
     * Returns the pointer to the outgoing connection vector
     * @return
     */
    virtual std::vector<Connection*>* get_connections_out( ) final;

    /**
     *
     * @return
     */
    size_t get_idx();

    /**
     *
     * @param value
     */
    void set_idx(size_t value);

}; /* end of Neuron class */


/**
 * Class serving as an interface providing 'activation_function_eval_partial_derivative',
 * 'activation_function_eval_derivative',  'get_partial_derivative' and
 * 'get_derivative' methods.
 */
class IDifferentiable {
    /**
     * Calculates the partial derivative of the activation function
     * with respect to the parameter and the current potential
     * @param[in] param_idx Index of the parameter to calculate derivative of
     * @return Partial derivative of the activation function according to the
     * 'param_idx'-th parameter
     */
    virtual double activation_function_eval_partial_derivative(int param_idx) = 0;

    /**
     * Calculates the derivative with respect to the argument, ie the 'potential'
     * @return f'(x), where 'f(x)' is the activation function and 'x' = 'potential'
     */
    virtual double activation_function_eval_derivative( ) = 0;

    /**
     * Returns a Neuron pointer object with activation function being the partial derivative of
     * the activation function of this Neuron object with respect to the argument, i.e. 'potential'
     * @return
     */
    virtual Neuron* get_derivative( );

}; /* end of IDifferentiable class */

 #endif /* NEURON_H_ */