fann_cpp.h

改进的人工神经网络源代码

#ifndef FANN_CPP_H_INCLUDED
#define FANN_CPP_H_INCLUDED

/**
 *
 *  @file   fann_cpp.h
 *
 *  @brief  Fast Artificial Neural Network (fann) C++ Wrapper
 *  Copyright (C) 2004 created by freegoldbar (at) yahoo dot com
 *
 *  This wrapper is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This wrapper 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
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 */

/**
 *  @mainpage  Fann C++ Wrapper
 *
 *  @section alert  Important
 *
 *  This is the first version of the Fann C++ Wrapper, as such it
 *  is not as stable an API as the C API and improvements may break
 *  backward compatibility.
 *
 *  @section overview  Overview
 *
 *  The C++ Fann Wrapper provides two classes: neural_net,
 *  encapsulates the struct fann pointer with the corresponding C
 *  API functions, and training_data, groups the struct
 *  fann_train_data pointer and associated C API functions.
 *
 *  @section download  Download
 *
 *  The Fann C++ Wrapper includes documentation, a sample and the
 *  Fann C Extensions header.
 *
 *  Download it here (88Kb): http://www.geocities.com/freegoldbar/fann_cpp.zip
 *
 *  @section notes  Notes and differences from C API
 *
 *  -#   It is a minimal wrapper: no templates, no exception handling,
 *       no name overloading for constructors or properties are used.
 *       Benefits include stricter type checking, simpler memory
 *       management and possibly code completion in program editor.
 *  -#   Method names are the same as the function names in the C
 *       API except the fann_ prefix has been removed. Enums in the
 *       namespace are similarly defined without the FANN_ prefix.
 *  -#   The arguments to the methods are the same as the C API
 *       except that the struct fann *ann/struct fann_train_data *data
 *       arguments are encapsulated so they are not present in the
 *       method signatures.
 *  -#   The various create methods return a boolean set to true to
 *       indicate that the neural network was created, false otherwise.
 *       The same goes for the read_train_from_file method.
 *  -#   The neural network and training data is automatically cleaned
 *       up in the destructors and create/read methods.
 *  -#   To make the destructors virtual define USE_VIRTUAL_DESTRUCTOR
 *       before including the header file.
 *  -#   To use the C++ wrapper include doublefann.h, floatfann.h or
 *       fixedfann.h first, then include the header file. To use the optional
 *       extensions include the fann_extensions.h before the fann_cpp.h
 *       see the xor_sample.cpp for an example (get_network_type).
 *  -#   Additional methods are available on the training_data class to
 *       give access to the underlying training data. They are get_num_data,
 *       get_num_input, get_num_output, get_input, get_output and
 *       set_train_data. Finally fann_duplicate_train_data has been
 *       replaced by a copy constructor.
 *  -#   For further usage documentation on the methods refer to the
 *       C API documentation. Functions marked in the C API as obsolete
 *       are not included.
 *
 */

/**
 *  @example xor_sample.cpp
 *  The example illustrates the XOR sample with functionality similar
 *  to xor_train.c
 *
 */

#include <stdarg.h>

/** The FANN namespace groups C++ Wrapper definitions together */
namespace FANN
{
    /*************************************************************************/

    /* The enums in the C API are unnamed(?) so they are defined again */
    /** @enum  error_function_enum
      * @brief Definition of error functions */
    enum error_function_enum {
        /** Standard linear error function */
        ERRORFUNC_LINEAR = 0,
        /** Tanh error function, usually better but can require a lower learning rate */
        ERRORFUNC_TANH
    };

    /** @enum  training_algorithm_enum
      * @brief Definition of training algorithms */
    enum training_algorithm_enum {
        /** Standard backpropagation incremental or online training */
        TRAIN_INCREMENTAL = 0,
        /** Standard backpropagation batch training */
        TRAIN_BATCH,
        /** The iRprop- training algorithm */
        TRAIN_RPROP,
        /** The quickprop training algorithm */
        TRAIN_QUICKPROP
    };

    /** @enum  activation_function_enum
      * @brief Definition of activation functions */
    enum activation_function_enum {
        /** Linear activation function.
        span: -inf < y < inf
        y = x*s, d = 1*s
        Can NOT be used in fixed point. */
        LINEAR = 0,
        /** Threshold activation function.
        x < 0 -> y = 0, x >= 0 -> y = 1
        Can NOT be used during training. */
        THRESHOLD,
        /** Threshold activation function.
        x < 0 -> y = 0, x >= 0 -> y = 1
        Can NOT be used during training. */
        THRESHOLD_SYMMETRIC,
        /** Sigmoid activation function.
        One of the most used activation functions.
        span: 0 < y < 1
        y = 1/(1 + exp(-2*s*x)), d = 2*s*y*(1 - y) */
        SIGMOID,
        /** Stepwise linear approximation to sigmoid.
        Faster than sigmoid but a bit less precise. */
        SIGMOID_STEPWISE, /* (default) */
        /** Symmetric sigmoid activation function, aka. tanh.
        One of the most used activation functions.
        span: -1 < y < 1
        y = tanh(s*x) = 2/(1 + exp(-2*s*x)) - 1, d = s*(1-(y*y)) */
        SIGMOID_SYMMETRIC,
        /** Stepwise linear approximation to symmetric sigmoid.
        Faster than symmetric sigmoid but a bit less precise. */
        SIGMOID_SYMMETRIC_STEPWISE
    };

#ifdef FANN_EXTENSIONS_H_INCLUDED
    /** @enum  network_type_enum
      * @brief EXTENSION Definition of network types */
    enum network_type_enum
    {
        /** Each layer only has connections to the next layer */
        LAYER = 0,
        /** Each layer has connections to all following layers */
        SHORTCUT
    };

    /** EXTENSION Describes a connection between two neurons and its weight */
    typedef struct fann_connection connection;
#endif /* FANN_EXTENSIONS_H_INCLUDED */

    /*************************************************************************/

    /** Encapsulation of training data and related functions */
    class training_data
    {
    public:
        /** Default constructor. Use read_train_from_file to initialize. */
        training_data() : train_data(NULL)
        {
        }

#ifndef FIXEDFANN
        /** Copy constructor. Constructs a copy of the training data.
            Corresponds to the C API duplicate_train_data function. */
        training_data(const training_data &data)
        {
            destroy_train();
            if (data.train_data != NULL)
            {
                train_data = fann_duplicate_train_data(data.train_data);
            }
        }
#endif /* NOT FIXEDFANN */

        /** Reads a file that stores training data, in the format:
        num_train_data num_input num_output\n
        inputdata seperated by space\n
        outputdata seperated by space\n
            ...
        inputdata seperated by space\n
        outputdata seperated by space\n  */
        bool read_train_from_file(char *filename)
        {
            destroy_train();
            train_data = fann_read_train_from_file(filename);
            return (train_data != NULL);
        }

        /** Destructor. Automatic cleanup. */
#ifdef USE_VIRTUAL_DESTRUCTOR
        virtual
#endif
        ~training_data()
        {
            destroy_train();
        }

        /** Destructs the training data. Called automatically by the destructor. */
        void destroy_train()
        {
            if (train_data != NULL)
            {
                fann_destroy_train(train_data);
                train_data = NULL;
            }
        }

        /** Save the training structure to a file. */
        void save_train(char *filename)
        {
            if (train_data != NULL)
            {
                fann_save_train(train_data, filename);
            }
        }

        /** Saves the training structure to a fixed point data file. */
        void save_train_to_fixed(char *filename, unsigned int decimal_point)
        {
            if (train_data != NULL)
            {
                fann_save_train_to_fixed(train_data, filename, decimal_point);
            }
        }

#ifndef FIXEDFANN
        /** Shuffles training data, randomizing the order */
        void shuffle_train_data()
        {
            if (train_data != NULL)
            {
                fann_shuffle_train_data(train_data);
            }
        }

        /** Merges training data. */
        void merge_train_data(const training_data &data)
        {
            fann_train_data *new_data = fann_merge_train_data(train_data, data.train_data);
            if (new_data != NULL)
            {
                destroy_train();
                train_data = new_data;
            }
        }
#endif /* NOT FIXEDFANN */

        /*********************************************************************/

#ifdef FANN_EXTENSIONS_H_INCLUDED
#ifdef USE_SAVE_EX
        /** EXTENSION Save training data to a file, return false when an error occurs */
        bool save_train_ex(char *filename)
        {
            if (train_data == NULL)
            {
                return false;
            }
            if (fann_save_train_ex(train_data, filename) == -1)
            {
                return false;
            }
            return true;
        }

        /** EXTENSION Save training data to a file in fixed point algebra, return false
            when an error occurs. (Good for testing a network in fixed point) */
        bool save_train_to_fixed_ex(char *filename, unsigned int decimal_point)
        {
            if (train_data == NULL)
            {
                return false;
            }
            if (fann_save_train_to_fixed_ex(train_data, filename, decimal_point) == -1)
            {
                return false;
            }
            return true;
        }
#endif /* USE_SAVE_EX */
#endif /* FANN_EXTENSIONS_H_INCLUDED */

        /*********************************************************************/

        /* Grant access to the encapsulated data since many situations
            and applications creates the data from sources other than files
            or uses the training data for testing and related functions */

        /** Number of data pairs in the training set */
        unsigned int get_num_data()
        {
            if (train_data == NULL)
            {
                return 0;
            }
            else
            {
                return train_data->num_data;
            }
        }

        /** Number of input data items in the training set */
        unsigned int get_num_input()
        {
            if (train_data == NULL)
            {
                return 0;
            }
            else
            {
                return train_data->num_input;
            }
        }

        /** Number of output data items in the training set */
        unsigned int get_num_output()
        {
            if (train_data == NULL)
            {
                return 0;
            }
            else
            {
                return train_data->num_output;
            }
        }

        /** Get a pointer to the array of input training data */
        fann_type **get_input()
        {
            if (train_data == NULL)
            {
                return NULL;
            }
            else
            {
                return train_data->input;
            }
        }

        /** Get a pointer to the array of output training data */
        fann_type **get_output()
        {
            if (train_data == NULL)
            {
                return NULL;
            }
            else
            {
                return train_data->output;
            }
        }

        /** Set the training data to the struct fann_training_data pointer.
            The struct has to be allocated with malloc to be compatible
            with fann_destroy. */
        void set_train_data(struct fann_train_data *data)
        {
            destroy_train();
            train_data = data;
        }

        /*********************************************************************/

    private:
        /** The neural_net class has direct access to the training data */
        friend class neural_net;
        /** Pointer to the encapsulated training data */
        struct fann_train_data* train_data;
    };

    /*************************************************************************/

    /** Encapsulation of a neural network and related functions */
    class neural_net