fann_extensions.h

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

#ifndef FANN_EXTENSIONS_H_INCLUDED
#define FANN_EXTENSIONS_H_INCLUDED

/**
 *
 *  @file   fann_extensions.h
 *
 *  @brief  Fast Artificial Neural Network (fann) C Extensions
 *  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 library 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 Extensions
 *
 *  @section alert  Important information
 *
 *  The Fann C Extensions are subject to change at any time and only work
 *  with Fann version 1.2.0. The extensions will change as similar
 *  functionality becomes available in the Fann Library. The changes may very
 *  well require code changes.
 *
 *  @section overview  Overview
 *  Fann C Extensions gives access to neural network layout, connections,
 *  weights, and save functions that return -1 when an error occurs. The
 *  save_ex functions are only available when USE_SAVE_EX is defined. The
 *  save_ex functions are not compatible with having the Fann Library in a DLL.
 *
 *  Fann C Extensions are Fann Library version 1.2.0 implementation specific.
 *
 *  @section download  Download
 *
 *  The Fann C Extensions header and documentation is included in the Fann C++ Wrapper.
 *
 *  Download it here (88Kb): http://www.geocities.com/freegoldbar/fann_cpp.zip
 *
 *  @section usage  Usage
 *  See the Examples section for a small example. The Fann for Mathematica
 *  extension uses the Fann C Extensions.
 *  Sourcecode is available at http://www.geocities.com/freegoldbar/index.html
 *
 */

/** Definition of network types */
enum fann_network_types
{
    /** Each layer only has connections to the next layer */
    FANN_LAYER = 0,
    /** Each layer has connections to all following layers */
    FANN_SHORTCUT
};

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

/** Get the type of network as defined in fann_network_types */
unsigned int fann_get_network_type(struct fann *ann);
/** Get the connection rate used when the network was created */
float fann_get_connection_rate(struct fann *ann);

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

/** Describes a connection between two neurons and its weight */
struct fann_connection
{
    /** Unique number used to identify source neuron */
    unsigned int from_neuron;
    /** Unique number used to identify destination neuron */
    unsigned int to_neuron;
    /** The numerical value of the weight */
    fann_type weight;
};

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

/** Get the number of layers in the network */
unsigned int fann_get_num_layers(struct fann *ann);

/** Get the number of neurons in each layer in the network.
    Bias is not included so the layers match the fann_create functions
    The layers array must be preallocated to at least
    sizeof(unsigned int) * fann_num_layers() long. */
void fann_get_layer_array(struct fann *ann, unsigned int *layers);

/** Get the number of bias in each layer in the network.
    The bias array must be preallocated to at least
    sizeof(unsigned int) * fann_num_layers() long. */
void fann_get_bias_array(struct fann *ann, unsigned int *bias);

/** Get the connections in the network.
    The connections array must be preallocated to at least
    sizeof(struct fann_connection) * fann_get_total_connections() long. */
void fann_get_connection_array(struct fann *ann, struct fann_connection *connections);

/** Set connections in the network.
    Only the weights can be changed, connections and weights are ignored
    if they do not already exist in the network.
    The array must have sizeof(struct fann_connection) * num_connections size. */
void fann_set_weight_array(struct fann *ann,
    struct fann_connection *connections, unsigned int num_connections);

/** Set a connection in the network.
    Only the weights can be changed. The connection/weight is
    ignored if it does not already exist in the network. */
void fann_set_weight(struct fann *ann,
    unsigned int from_neuron, unsigned int to_neuron, fann_type weight);

/*****************************************************************************/
/* FIX: Save_..._ex functions return -1 when an error occurs. */

#ifdef USE_SAVE_EX
/** Save the network, return -1 when an error occurs. */
FANN_EXTERNAL int FANN_API fann_save_ex(struct fann *ann, const char *configuration_file);

/** Save training data to a file, return -1 when an error occurs */
FANN_EXTERNAL int FANN_API fann_save_train_ex(struct fann_train_data* data, char *filename);

/** Save training data to a file in fixed point algebra, return -1 when an error occurs.
    (Good for testing a network in fixed point) */
FANN_EXTERNAL int FANN_API fann_save_train_to_fixed_ex(struct fann_train_data* data, char *filename, unsigned int decimal_point);

/** INTERNAL FUNCTION
    Save the train data structure, return -1 when an error occurs. */
int fann_save_train_internal_ex(struct fann_train_data* data, char *filename, unsigned int save_as_fixed, unsigned int decimal_point);
#endif /* USE_SAVE_EX */

/*****************************************************************************/
/* Split here to place the rest in a .c file */
/*****************************************************************************/

/** Get the type of network as defined in fann_network_types */
unsigned int fann_get_network_type(struct fann *ann)
{
    /* Currently two types: LAYER = 0, SHORTCUT = 1 */
    /* Enum network_types must be set to match the return values  */
    return ann->shortcut_connections;
}

/** Get the connection rate used when the network was created */
float fann_get_connection_rate(struct fann *ann)
{
    return ann->connection_rate;
}

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

/** Get the number of layers in the network */
unsigned int fann_get_num_layers(struct fann *ann)
{
    return ann->last_layer - ann->first_layer;
}

/** Get the number of neurons in each layer in the network.
    Bias is not included so the layers match the fann_create functions
    The layers array must be preallocated to at least
    sizeof(unsigned int) * fann_num_layers() long. */
void fann_get_layer_array(struct fann *ann, unsigned int *layers)
{
    struct fann_layer *layer_it;

    for (layer_it = ann->first_layer; layer_it != ann->last_layer; layer_it++) {
        unsigned int count = layer_it->last_neuron - layer_it->first_neuron;
        /* Remove the bias from the count of neurons. */
        switch (fann_get_network_type(ann)) {
            case FANN_LAYER: {
                --count;
                break;
            }
            case FANN_SHORTCUT: {
                --count;
                break;
            }
            default: {
                /* Unknown network type, assume no bias present  */
                break;
            }
        }
        *layers++ = count;
    }
}

/** Get the number of bias in each layer in the network.
    The bias array must be preallocated to at least
    sizeof(unsigned int) * fann_num_layers() long. */
void fann_get_bias_array(struct fann *ann, unsigned int *bias)
{
    struct fann_layer *layer_it;

    for (layer_it = ann->first_layer; layer_it != ann->last_layer; ++layer_it, ++bias) {
        switch (fann_get_network_type(ann)) {
            case FANN_LAYER: {
                /* Report one bias in each layer except the last */
                if (layer_it != ann->last_layer-1)
                    *bias = 1;
                else
                    *bias = 0;
                break;