neuralpp/include/neural++.hpp

550 lines
16 KiB
C++
Raw Normal View History

2009-02-18 00:12:03 +01:00
/**************************************************************************************************
2009-08-16 11:09:42 +02:00
* LibNeural++ v.0.4 - All-purpose library for managing neural networks *
2009-02-18 00:12:03 +01:00
* Copyright (C) 2009, BlackLight *
* *
* This program is free software: you can redistribute it and/or modify it under the terms of the *
* GNU General Public License as published by the Free Software Foundation, either version 3 of *
* the License, or (at your option) any later version. This program is distributed in the hope *
* that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for *
* more details. You should have received a copy of the GNU General Public License along with *
* this program. If not, see <http://www.gnu.org/licenses/>. *
**************************************************************************************************/
#ifndef __cplusplus
#error "This is a C++ library, you know, so you'd better use a C++ compiler to compile it"
#else
2009-02-18 00:12:03 +01:00
#ifndef __NEURALPP
#define __NEURALPP
#include <vector>
#include <string>
#include <cmath>
#include "neural++_exception.hpp"
2009-02-18 00:12:03 +01:00
2009-08-09 10:24:52 +02:00
//! Default rand value: |sin(rand)|, always >= 0 and <= 1
2009-08-10 18:06:52 +02:00
#define RAND (double) ( (rand() / (RAND_MAX/2)) - 1)
2009-08-09 10:24:52 +02:00
//! Initial value for the inertial momentum of the synapses
2009-08-10 18:06:52 +02:00
#define BETA0 0.8
2009-08-09 11:17:39 +02:00
/**
* @namespace neuralpp
* @brief Main namespace for the library
*/
2009-08-09 10:24:52 +02:00
namespace neuralpp {
2009-02-18 00:12:03 +01:00
class Synapsis;
class Neuron;
class Layer;
class NeuralNet;
2009-08-15 02:59:09 +02:00
double df (double (*f)(double), double x);
2009-08-16 18:02:24 +02:00
double __actv(double prop);
2009-08-15 02:59:09 +02:00
2009-02-18 00:12:03 +01:00
/**
* @class NeuralNet
* @brief Main project's class. Use *ONLY* this class, unless you know what you're doing
*/
class NeuralNet {
int epochs;
int ref_epochs;
double l_rate;
2009-08-16 18:02:24 +02:00
double threshold;
2009-08-16 15:29:54 +02:00
std::vector<double> expect;
2009-02-18 00:12:03 +01:00
/**
* @brief It updates the weights of the net's synapsis through back-propagation.
* In-class use only
*/
void updateWeights();
/**
* @brief It commits the changes made by updateWeights() to the layer l.
* In-class use only
* @param l Layer to commit the changes
*/
2009-08-16 11:09:42 +02:00
void commitChanges (Layer& l);
2009-02-18 00:12:03 +01:00
/**
2009-08-16 11:09:42 +02:00
* @brief Get the error made on the expected result as squared deviance
2009-08-09 11:17:39 +02:00
* @param ex Expected value
2009-02-18 00:12:03 +01:00
* @return Mean error
*/
2009-08-16 15:29:54 +02:00
double error (double ex);
2009-02-18 00:12:03 +01:00
2009-08-09 11:17:39 +02:00
/**
* @brief Private pointer to function, containing the function to
* be used as activation function
*/
double (*actv_f)(double);
2009-08-09 11:17:39 +02:00
2009-02-18 00:12:03 +01:00
public:
2009-08-09 19:53:21 +02:00
Layer* input;
Layer* hidden;
Layer* output;
2009-02-18 00:12:03 +01:00
/**
* @brief Enum to choose the eventual training source for our network (XML from a file or from a string)
*/
typedef enum { file, str } source;
2009-08-09 11:17:39 +02:00
/**
* @brief Empty constructor for the class - it just makes nothing
*/
2009-02-18 00:12:03 +01:00
NeuralNet() {}
/**
* @brief Constructor
* @param in_size Size of the input layer
* @param hidden_size Size of the hidden layer
* @param out_size Size of the output layer
* @param l learn rate (get it after doing some experiments, but generally try to
* keep its value quite low to be more accurate)
* @param e Epochs (cycles) to execute (the most you execute, the most the network
* can be accurate for its purpose)
2009-08-16 18:02:24 +02:00
* @param th Threshold, value in [0,1] that establishes how much a neuron must be
* 'sensitive' on variations of the input values
* @param a Activation function to use (default: f(x)=x)
2009-02-18 00:12:03 +01:00
*/
2009-08-16 18:02:24 +02:00
NeuralNet (size_t in_size, size_t hidden_size, size_t out_size, double l, int e, double th = 0.0, double (*a)(double) = __actv);
2009-02-18 00:12:03 +01:00
/**
* @brief Constructor
* @param file Binary file containing a neural network previously saved by save() method
* @throw NetworkFileNotFoundException
*/
2009-08-16 11:09:42 +02:00
NeuralNet (const std::string file) throw(NetworkFileNotFoundException);
2009-02-18 00:12:03 +01:00
/**
* @brief Constructor
* @param in_size Size of the input layer
* @param hidden_size Size of the hidden layer
* @param out_size Size of the output layer
* @param actv Activation function to use (default: f(x)=x)
* @param l learn rate (get it after doing some experiments, but generally try to
* keep its value quite low to be more accurate)
* @param e Epochs (cycles) to execute (the most you execute, the most the network
* can be accurate for its purpose)
2009-08-16 18:02:24 +02:00
* @param th Threshold, value in [0,1] that establishes how much a neuron must be
* 'sensitive' on variations of the input values
2009-02-18 00:12:03 +01:00
*/
2009-08-16 18:02:24 +02:00
//NeuralNet (size_t in_size, size_t hidden_size, size_t out_size,
// double(*actv)(double), double l, int e, double th);
2009-02-18 00:12:03 +01:00
/**
* @brief It gets the output of the network (note: the layer output should contain
2009-08-09 11:17:39 +02:00
* an only neuron)
* @return The output value of the network
2009-02-18 00:12:03 +01:00
*/
2009-08-10 18:06:52 +02:00
double getOutput() const;
2009-02-18 00:12:03 +01:00
2009-08-16 18:02:24 +02:00
/**
* @brief Get the threshold of the neurons in the network
* @return The threshold of the neurons
*/
double getThreshold() const;
2009-02-18 00:12:03 +01:00
/**
* @brief It gets the output of the network in case the output layer contains more neurons
2009-08-09 11:17:39 +02:00
* @return A vector containing the output values of the network
2009-02-18 00:12:03 +01:00
*/
2009-08-16 11:09:42 +02:00
std::vector<double> getOutputs();
2009-02-18 00:12:03 +01:00
/**
2009-08-16 11:09:42 +02:00
* @brief Get the expected value (in case you have an only neuron in output layer). Of course you should specify this when you
2009-08-09 11:17:39 +02:00
* build your network by using setExpected.
* @return The expected output value for a certain training phase
2009-02-18 00:12:03 +01:00
*/
2009-08-10 18:06:52 +02:00
double expected() const;
2009-02-18 00:12:03 +01:00
/**
2009-08-16 11:09:42 +02:00
* @brief Get the expected value (in case you have an only neuron in output layer). Of course you should specify this when you
* build your network by using setExpected.
* @return The expected output value for a certain training phase
*/
std::vector<double> getExpected() const;
/**
* @brief It sets the value you expect from your network (in case the network has an only neuron in its output layer)
2009-08-09 11:17:39 +02:00
* @param ex Expected output value
2009-02-18 00:12:03 +01:00
*/
2009-08-09 11:17:39 +02:00
void setExpected(double ex);
2009-02-18 00:12:03 +01:00
2009-08-16 11:09:42 +02:00
/**
* @brief Set the values you expect from your network
* @param ex Expected output values
*/
void setExpected(std::vector<double> ex);
2009-02-18 00:12:03 +01:00
/**
* @brief It updates through back-propagation the weights of the synapsis and
2009-08-09 11:17:39 +02:00
* computes again the output value for <i>epochs</i> times, calling back
* updateWeights and commitChanges functions
2009-02-18 00:12:03 +01:00
*/
void update();
/**
* @brief It propagates values through the network. Use this when you want to give
2009-08-09 11:17:39 +02:00
* an already trained network some new values the get to the output
2009-02-18 00:12:03 +01:00
*/
void propagate();
/**
* @brief It sets the input for the network
* @param v Vector of doubles, containing the values to give to your network
2009-02-18 00:12:03 +01:00
*/
2009-08-16 11:09:42 +02:00
void setInput (std::vector<double> v);
2009-02-18 00:12:03 +01:00
/**
* @brief It links the layers of the network (input, hidden, output). Don't use unless
2009-08-09 11:17:39 +02:00
* you exactly know what you're doing, it is already called by the constructor
2009-02-18 00:12:03 +01:00
*/
void link();
/**
* @brief Save a trained neural network to a binary file
2009-08-09 11:17:39 +02:00
* @param fname Binary file where you're going to save your network
2009-08-10 18:06:52 +02:00
* @throws NetworkFileWriteException When you get an error writing the network's information to
* a file
2009-02-18 00:12:03 +01:00
*/
2009-08-16 11:09:42 +02:00
void save (const char* fname) throw(NetworkFileWriteException);
2009-02-18 00:12:03 +01:00
/**
* @brief Train a network using a training set loaded from an XML file. A sample XML file
* is available in examples/adder.xml
* @param xml XML file containing our training set
* @param src Source type from which the XML will be loaded (from a file [default] or from a string)
* @throw InvalidXMLException
*/
2009-08-16 11:09:42 +02:00
void train (std::string xml, source src) throw(InvalidXMLException);
2009-02-18 00:12:03 +01:00
/**
* @brief Initialize the training XML for the neural network
* @param xml String that will contain the XML
*/
2009-08-16 11:09:42 +02:00
static void initXML (std::string& xml);
2009-02-18 00:12:03 +01:00
/**
* @brief Splits a string into a vector of doubles, given a delimitator
2009-02-18 00:12:03 +01:00
* @param delim Delimitator
* @param str String to be splitted
* @return Vector of doubles containing splitted values
2009-02-18 00:12:03 +01:00
*/
2009-08-16 11:09:42 +02:00
static std::vector<double> split (char delim, std::string str);
2009-02-18 00:12:03 +01:00
/**
* @brief Get a training set from a string and copies it to an XML
* For example, these strings could be training sets for making sums:
* "2,3;5" - "5,6;11" - "2,2;4" - "4,5:9"
* This method called on the first string will return an XML such this:
* '&lt;training id="0"&gt;&lt;input id="0"&gt;2&lt;/input&gt;&lt;input id="1"&gt;3&lt;/input&gt;&lt;output id="0"&gt;5&lt;/output&gt;
* &lt/training&gt;'
*
* @param id ID for the given training set (0,1,..,n)
* @param set String containing input values and expected outputs
* @return XML string
*/
2009-08-16 18:02:24 +02:00
static std::string XMLFromSet (int& id, std::string set);
2009-02-18 00:12:03 +01:00
/**
* @brief Closes an open XML document generated by "initXML" and "XMLFromSet"
2009-08-09 11:17:39 +02:00
* @param xml XML string to be closed
2009-02-18 00:12:03 +01:00
*/
2009-08-16 11:09:42 +02:00
static void closeXML(std::string& xml);
2009-02-18 00:12:03 +01:00
};
/**
* @class Synapsis
* @brief Class for managing synapsis. Don't use this class directly unless you know what
* you're doing, use NeuralNet instead
*/
class Synapsis {
double delta;
double prev_delta;
double weight;
2009-02-18 00:12:03 +01:00
Neuron *in;
Neuron *out;
double (*actv_f)(double);
2009-02-18 00:12:03 +01:00
public:
/**
* @brief Constructor
* @param i Input neuron
* @param o Output neuron
* @param w Weight for the synapsis
* @param d Delta for the synapsis
*/
Synapsis(Neuron* i, Neuron* o, double w, double d);
2009-02-18 00:12:03 +01:00
/**
* @brief Constructor
* @param i Input neuron
* @param o Output neuron
* @param a Activation function
*/
2009-08-15 02:59:09 +02:00
Synapsis (Neuron* i, Neuron* o, double(*a)(double));
2009-02-18 00:12:03 +01:00
/**
* @brief Constructor
* @param i Input neuron
* @param o Output neuron
* @param w Weight for the synapsis (default: random)
* @param a Activation function
*/
Synapsis (Neuron* i, Neuron* o,
2009-08-15 02:59:09 +02:00
double w, double(*a)(double));
2009-02-18 00:12:03 +01:00
/**
* @return Reference to input neuron of the synapsis
*/
Neuron* getIn() const;
2009-02-18 00:12:03 +01:00
/**
* @return Reference to output neuron of the synapsis
*/
Neuron* getOut() const;
2009-02-18 00:12:03 +01:00
/**
2009-08-09 11:17:39 +02:00
* @brief Set the weight of the synapsis
* @param w Weight to be set
2009-02-18 00:12:03 +01:00
*/
2009-08-10 18:06:52 +02:00
void setWeight(double w) throw(InvalidSynapticalWeightException);
2009-02-18 00:12:03 +01:00
/**
* @brief It sets the delta (how much to change the weight after an update)
2009-08-09 11:17:39 +02:00
* of the synapsis
* @param d Delta to be set
2009-02-18 00:12:03 +01:00
*/
2009-08-10 18:06:52 +02:00
void setDelta(double d) throw(InvalidSynapticalWeightException);
2009-02-18 00:12:03 +01:00
/**
2009-08-09 11:17:39 +02:00
* @brief Return the weight of the synapsis
2009-02-18 00:12:03 +01:00
* @return Weight of the synapsis
*/
double getWeight() const;
2009-02-18 00:12:03 +01:00
/**
2009-08-09 11:17:39 +02:00
* @brief Return the delta of the synapsis
2009-02-18 00:12:03 +01:00
* @return Delta of the synapsis
*/
double getDelta() const;
/**
* @brief Get the delta of the synapsis at the previous iteration
* @return The previous delta
*/
double getPrevDelta() const;
/**
* @brief Get the inertial momentum of a synapsis. This value is inversely proportional
* to the number of steps done in the learning phase (quite high at the beginning, decreasing
* to zero towards the end of the learning algorithm), and is needed to avoid strong
* oscillations in output values at the beginning, caused by the random values assigned to
* the synaptical weights
* @param N The number of iterations the network must have to adjust the output values
* @param x The number of iterations already taken
* @return The inertial momentum of the synapsis
*/
double momentum (int N, int x) const;
2009-02-18 00:12:03 +01:00
};
/**
* @class Neuron
* @brief Class for managing neurons. Don't use this class directly unless you know what
* you're doing, use NeuralNet instead
*/
class Neuron {
double actv_val;
double prop_val;
2009-08-16 18:02:24 +02:00
double threshold;
2009-02-18 00:12:03 +01:00
2009-08-16 11:09:42 +02:00
std::vector< Synapsis > in;
std::vector< Synapsis > out;
2009-02-18 00:12:03 +01:00
double (*actv_f)(double);
2009-08-15 02:59:09 +02:00
2009-02-18 00:12:03 +01:00
public:
/**
* @brief Constructor
* @param a Activation function
2009-08-16 18:02:24 +02:00
* @param th Threshold, value in [0,1] that establishes how much a neuron must be
* 'sensitive' on variations of the input values
2009-02-18 00:12:03 +01:00
*/
2009-08-16 18:02:24 +02:00
Neuron (double (*a)(double), double th = 0.0);
2009-02-18 00:12:03 +01:00
/**
* @brief Alternative constructor, that gets also the synapsis linked to the neuron
2009-08-09 11:17:39 +02:00
* @param in Input synapses
* @param out Output synapses
* @param a Activation function
2009-08-16 18:02:24 +02:00
* @param th Threshold, value in [0,1] that establishes how much a neuron must be
* 'sensitive' on variations of the input values
2009-02-18 00:12:03 +01:00
*/
2009-08-16 11:09:42 +02:00
Neuron (std::vector<Synapsis> in, std::vector<Synapsis> out,
2009-08-16 18:02:24 +02:00
double (*a)(double), double th = 0.0);
2009-02-18 00:12:03 +01:00
/**
2009-08-09 11:17:39 +02:00
* @brief Get the i-th synapsis connected on the input of the neuron
* @param i Index of the input synapsis to get
* @return Reference to the i-th synapsis
2009-02-18 00:12:03 +01:00
*/
Synapsis& synIn (size_t i);
/**
2009-08-09 11:17:39 +02:00
* @brief Get the i-th synapsis connected on the output of the neuron
* @param i Index of the output synapsis to get
* @return Reference to the i-th synapsis
2009-02-18 00:12:03 +01:00
*/
Synapsis& synOut (size_t i);
/**
* @brief It pushes a new input synapsis
2009-08-09 11:17:39 +02:00
* @param s Synapsis to be pushed
2009-02-18 00:12:03 +01:00
*/
2009-08-16 11:09:42 +02:00
void push_in (Synapsis s);
2009-02-18 00:12:03 +01:00
/**
* @brief It pushes a new output synapsis
2009-08-09 11:17:39 +02:00
* @param s Synapsis to be pushed
2009-02-18 00:12:03 +01:00
*/
2009-08-16 11:09:42 +02:00
void push_out (Synapsis s);
2009-02-18 00:12:03 +01:00
/**
* @brief Change the activation value of the neuron
2009-08-09 11:17:39 +02:00
* @param a Activation value
2009-02-18 00:12:03 +01:00
*/
2009-08-09 11:17:39 +02:00
void setActv (double a);
2009-02-18 00:12:03 +01:00
/**
* @brief Change the propagation value of the neuron
2009-08-09 11:17:39 +02:00
* @param p Propagation value
2009-02-18 00:12:03 +01:00
*/
2009-08-09 11:17:39 +02:00
void setProp (double p);
2009-02-18 00:12:03 +01:00
/**
2009-08-09 11:17:39 +02:00
* @brief Get the activation value of the neuron
* @return Activation value for the neuron
2009-02-18 00:12:03 +01:00
*/
double getActv();
2009-02-18 00:12:03 +01:00
/**
2009-08-09 11:17:39 +02:00
* @brief Get the propagation value of the neuron
* @return Propagation value for the neuron
2009-02-18 00:12:03 +01:00
*/
double getProp();
2009-02-18 00:12:03 +01:00
/**
2009-08-16 11:09:42 +02:00
* @brief Compute the propagation value of the neuron and set it
2009-02-18 00:12:03 +01:00
*/
2009-08-16 11:09:42 +02:00
void propagate();
2009-02-18 00:12:03 +01:00
/**
2009-08-09 11:17:39 +02:00
* @brief Get the number of input synapsis for the neuron
2009-02-18 00:12:03 +01:00
* @return Number of input synapsis
*/
size_t nIn();
/**
2009-08-09 11:17:39 +02:00
* @brief Get the number of output synapsis for the neuron
2009-02-18 00:12:03 +01:00
* @return Number of output synapsis
*/
size_t nOut();
/**
* @brief Remove input and output synapsis from a neuron
*/
2009-08-09 11:17:39 +02:00
void synClear();
2009-02-18 00:12:03 +01:00
};
/**
* @class Layer
* @brief Class for managing layers of neurons. Don't use this class directly unless you know what
* you're doing, use NeuralNet instead
*/
class Layer {
2009-08-16 11:09:42 +02:00
std::vector<Neuron> elements;
2009-08-16 18:02:24 +02:00
double threshold;
2009-02-18 00:12:03 +01:00
void (*update_weights)();
double (*actv_f)(double);
2009-02-18 00:12:03 +01:00
public:
/**
* @brief Constructor
* @param sz Size of the layer
* @param a Activation function
2009-08-16 18:02:24 +02:00
* @param th Threshold, value in [0,1] that establishes how much a neuron must be
* 'sensitive' on variations of the input values
2009-02-18 00:12:03 +01:00
*/
2009-08-16 18:02:24 +02:00
Layer (size_t sz, double (*a)(double), double th = 0.0);
2009-02-18 00:12:03 +01:00
/**
* @brief Alternative constructor. It directly gets a vector of neurons to build
2009-08-09 11:17:39 +02:00
* the layer
* @param neurons Vector of neurons to be included in the layer
* @param a Activation function
2009-08-16 18:02:24 +02:00
* @param th Threshold, value in [0,1] that establishes how much a neuron must be
* 'sensitive' on variations of the input values
2009-02-18 00:12:03 +01:00
*/
2009-08-16 18:02:24 +02:00
Layer (std::vector<Neuron>& neurons, double(*a)(double), double th = 0.0);
2009-02-18 00:12:03 +01:00
/**
* @brief Redefinition for operator []. It gets the neuron at <i>i</i>
2009-08-09 11:17:39 +02:00
* @param i Index of the neuron to get in the layer
* @return Reference to the i-th neuron
2009-02-18 00:12:03 +01:00
*/
2009-08-10 18:06:52 +02:00
Neuron& operator[] (size_t i) throw(NetworkIndexOutOfBoundsException);
2009-02-18 00:12:03 +01:00
/**
* @brief It links a layer to another
* @param l Layer to connect to the current as input layer
*/
2009-08-09 11:17:39 +02:00
void link (Layer& l);
2009-02-18 00:12:03 +01:00
/**
2009-08-16 11:09:42 +02:00
* @brief Set the input values for the neurons of the layer (just use it for the input layer)
* @param v Vector containing the input values
2009-02-18 00:12:03 +01:00
*/
2009-08-16 11:09:42 +02:00
void setInput (std::vector<double> v);
2009-02-18 00:12:03 +01:00
/**
* @brief It propagates its activation values to the output layers
*/
void propagate();
/**
* @return Number of neurons in the layer
*/
2009-08-10 18:06:52 +02:00
size_t size() const;
2009-02-18 00:12:03 +01:00
};
struct netrecord {
int input_size;
int hidden_size;
int output_size;
int epochs;
double l_rate;
double ex;
2009-02-18 00:12:03 +01:00
};
struct neuronrecord {
double prop;
double actv;
2009-02-18 00:12:03 +01:00
};
struct synrecord {
double w;
double d;
2009-02-18 00:12:03 +01:00
};
}
#endif
#endif