fann/src/include/fann.h

   1 /*
   2 Fast Artificial Neural Network Library (fann)
   3 Copyright (C) 2003 Steffen Nissen (lukesky@diku.dk)
   4
   5 This library is free software; you can redistribute it and/or
   6 modify it under the terms of the GNU Lesser General Public
   7 License as published by the Free Software Foundation; either
   8 version 2.1 of the License, or (at your option) any later version.
   9
  10 This library is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 Lesser General Public License for more details.
  14
  15 You should have received a copy of the GNU Lesser General Public
  16 License along with this library; if not, write to the Free Software
  17 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18 */
  19
  20 /* This file defines the user interface to the fann library.
  21    It is included from fixedfann.h, floatfann.h and doublefann.h and should
  22    NOT be included directly. If included directly it will react as if
  23    floatfann.h was included.
  24 */
  25
  26 /* Section: FANN Creation/Execution
  27
  28    The FANN library is designed to be very easy to use.
  29    A feedforward ann can be created by a simple <fann_create_standard> function, while
  30    other ANNs can be created just as easily. The ANNs can be trained by <fann_train_on_file>
  31    and executed by <fann_run>.
  32
  33    All of this can be done without much knowledge of the internals of ANNs, although the ANNs created will
  34    still be powerfull and effective. If you have more knowledge about ANNs, and desire more control, almost
  35    every part of the ANNs can be parametized to create specialized and highly optimal ANNs.
  36  */
  37 /* Group: Creation, Destruction & Execution */
  38
  39 #ifndef FANN_INCLUDE
  40 /* just to allow for inclusion of fann.h in normal stuations where only floats are needed */
  41 #ifdef FIXEDFANN
  42 #include "fixedfann.h"
  43 #else
  44 #include "floatfann.h"
  45 #endif  /* FIXEDFANN  */
  46
  47 #else
  48
  49 /* COMPAT_TIME REPLACEMENT */
  50 #ifndef _WIN32
  51 #include <sys/time.h>
  52 #else   /* _WIN32 */
  53 #if !defined(_MSC_EXTENSIONS) && !defined(_INC_WINDOWS)
  54 extern unsigned long __stdcall GetTickCount(void);
  55
  56 #else   /* _MSC_EXTENSIONS */
  57 #define WIN32_LEAN_AND_MEAN
  58 #include <windows.h>
  59 #endif  /* _MSC_EXTENSIONS */
  60 #endif  /* _WIN32 */
  61
  62 #ifndef __fann_h__
  63 #define __fann_h__
  64
  65 #ifdef __cplusplus
  66 extern "C"
  67 {
  68
  69 #ifndef __cplusplus
  70 } /* to fool automatic indention engines */
  71 #endif
  72 #endif  /* __cplusplus */
  73
  74 #ifndef NULL
  75 #define NULL 0
  76 #endif  /* NULL */
  77
  78 /* ----- Macros used to define DLL external entrypoints ----- */
  79 /*
  80  DLL Export, import and calling convention for Windows.
  81  Only defined for Microsoft VC++ FANN_EXTERNAL indicates
  82  that a function will be exported/imported from a dll
  83  FANN_API ensures that the DLL calling convention
  84  will be used for  a function regardless of the calling convention
  85  used when compiling.
  86
  87  For a function to be exported from a DLL its prototype and
  88  declaration must be like this:
  89     FANN_EXTERNAL void FANN_API function(char *argument)
  90
  91  The following ifdef block is a way of creating macros which
  92  make exporting from a DLL simple. All files within a DLL are
  93  compiled with the FANN_DLL_EXPORTS symbol defined on the
  94  command line. This symbol should not be defined on any project
  95  that uses this DLL. This way any other project whose source
  96  files include this file see FANN_EXTERNAL functions as being imported
  97  from a DLL, whereas a DLL sees symbols defined with this
  98  macro as being exported which makes calls more efficient.
  99  The __stdcall calling convention is used for functions in a
 100  windows DLL.
 101
 102  The callback functions for fann_set_callback must be declared as FANN_API
 103  so the DLL and the application program both use the same
 104  calling convention.
 105 */
 106
 107 /*
 108  The following sets the default for MSVC++ 2003 or later to use
 109  the fann dll's. To use a lib or fixedfann.c, floatfann.c or doublefann.c
 110  with those compilers FANN_NO_DLL has to be defined before
 111  including the fann headers.
 112  The default for previous MSVC compilers such as VC++ 6 is not
 113  to use dll's. To use dll's FANN_USE_DLL has to be defined before
 114  including the fann headers.
 115 */
 116 #if (_MSC_VER > 1300)
 117 #ifndef FANN_NO_DLL
 118 #define FANN_USE_DLL
 119 #endif  /* FANN_USE_LIB */
 120 #endif  /* _MSC_VER */
 121 #if defined(_MSC_VER) && (defined(FANN_USE_DLL) || defined(FANN_DLL_EXPORTS))
 122 #ifdef FANN_DLL_EXPORTS
 123 #define FANN_EXTERNAL __declspec(dllexport)
 124 #else                                                   /*  */
 125 #define FANN_EXTERNAL __declspec(dllimport)
 126 #endif  /* FANN_DLL_EXPORTS*/
 127 #define FANN_API __stdcall
 128 #else                                                   /*  */
 129 #define FANN_EXTERNAL
 130 #define FANN_API
 131 #endif  /* _MSC_VER */
 132 /* ----- End of macros used to define DLL external entrypoints ----- */
 133
 134 #include "fann_error.h"
 135 #include "fann_activation.h"
 136 #include "fann_data.h"
 137 #include "fann_internal.h"
 138 #include "fann_train.h"
 139 #include "fann_cascade.h"
 140 #include "fann_io.h"
 141
 142 /* Function: fann_create_standard
 143
 144         Creates a standard fully connected backpropagation neural network.
 145
 146         There will be a bias neuron in each layer (except the output layer),
 147         and this bias neuron will be connected to all neurons in the next layer.
 148         When running the network, the bias nodes always emits 1.
 149
 150         To destroy a <struct fann> use the <fann_destroy> function.
 151
 152         Parameters:
 153                 num_layers - The total number of layers including the input and the output layer.
 154                 ... - Integer values determining the number of neurons in each layer starting with the
 155                         input layer and ending with the output layer.
 156
 157         Returns:
 158                 A pointer to the newly created <struct fann>.
 159
 160         Example:
 161                 > // Creating an ANN with 2 input neurons, 1 output neuron,
 162                 > // and two hidden neurons with 8 and 9 neurons
 163                 > struct fann *ann = fann_create_standard(4, 2, 8, 9, 1);
 164
 165         See also:
 166                 <fann_create_standard_array>, <fann_create_sparse>, <fann_create_shortcut>
 167
 168         This function appears in FANN >= 2.0.0.
 169 */
 170 FANN_EXTERNAL struct fann *FANN_API fann_create_standard(unsigned int num_layers, ...);
 171
 172 /* Function: fann_create_standard_array
 173    Just like <fann_create_standard>, but with an array of layer sizes
 174    instead of individual parameters.
 175
 176         Example:
 177                 > // Creating an ANN with 2 input neurons, 1 output neuron,
 178                 > // and two hidden neurons with 8 and 9 neurons
 179                 > unsigned int layers[4] = {2, 8, 9, 1};
 180                 > struct fann *ann = fann_create_standard_array(4, layers);
 181
 182         See also:
 183                 <fann_create_standard>, <fann_create_sparse>, <fann_create_shortcut>
 184
 185         This function appears in FANN >= 2.0.0.
 186 */
 187 FANN_EXTERNAL struct fann *FANN_API fann_create_standard_array(unsigned int num_layers,
 188                                                                                                                    unsigned int *layers);
 189
 190 /* Function: fann_create_sparse
 191
 192         Creates a standard backpropagation neural network, which is not fully connected.
 193
 194         Parameters:
 195                 connection_rate - The connection rate controls how many connections there will be in the
 196                         network. If the connection rate is set to 1, the network will be fully
 197                         connected, but if it is set to 0.5 only half of the connections will be set.
 198                         A connection rate of 1 will yield the same result as <fann_create_standard>
 199                 num_layers - The total number of layers including the input and the output layer.
 200                 ... - Integer values determining the number of neurons in each layer starting with the
 201                         input layer and ending with the output layer.
 202
 203         Returns:
 204                 A pointer to the newly created <struct fann>.
 205
 206         See also:
 207                 <fann_create_sparse_array>, <fann_create_standard>, <fann_create_shortcut>
 208
 209         This function appears in FANN >= 2.0.0.
 210 */
 211 FANN_EXTERNAL struct fann *FANN_API fann_create_sparse(float connection_rate,
 212                                                            unsigned int num_layers, ...);
 213
 214
 215 /* Function: fann_create_sparse_array
 216    Just like <fann_create_sparse>, but with an array of layer sizes
 217    instead of individual parameters.
 218
 219         See <fann_create_standard_array> for a description of the parameters.
 220
 221         See also:
 222                 <fann_create_sparse>, <fann_create_standard>, <fann_create_shortcut>
 223
 224         This function appears in FANN >= 2.0.0.
 225 */
 226 FANN_EXTERNAL struct fann *FANN_API fann_create_sparse_array(float connection_rate,
 227                                                                  unsigned int num_layers,
 228                                                                                                                          unsigned int *layers);
 229
 230 /* Function: fann_create_shortcut
 231
 232         Creates a standard backpropagation neural network, which is not fully connected and which
 233         also has shortcut connections.
 234
 235         Shortcut connections are connections that skip layers. A fully connected network with shortcut
 236         connections, is a network where all neurons are connected to all neurons in later layers.
 237         Including direct connections from the input layer to the output layer.
 238
 239         See <fann_create_standard> for a description of the parameters.
 240
 241         See also:
 242                 <fann_create_shortcut_array>, <fann_create_standard>, <fann_create_sparse>,
 243
 244         This function appears in FANN >= 2.0.0.
 245 */
 246 FANN_EXTERNAL struct fann *FANN_API fann_create_shortcut(unsigned int num_layers, ...);
 247
 248 /* Function: fann_create_shortcut_array
 249    Just like <fann_create_shortcut>, but with an array of layer sizes
 250    instead of individual parameters.
 251
 252         See <fann_create_standard_array> for a description of the parameters.
 253
 254         See also:
 255                 <fann_create_shortcut>, <fann_create_standard>, <fann_create_sparse>
 256
 257         This function appears in FANN >= 2.0.0.
 258 */
 259 FANN_EXTERNAL struct fann *FANN_API fann_create_shortcut_array(unsigned int num_layers,
 260                                                                                                                            unsigned int *layers);
 261 /* Function: fann_destroy
 262    Destroys the entire network and properly freeing all the associated memmory.
 263
 264         This function appears in FANN >= 1.0.0.
 265 */
 266 FANN_EXTERNAL void FANN_API fann_destroy(struct fann *ann);
 267
 268
 269 /* Function: fann_run
 270         Will run input through the neural network, returning an array of outputs, the number of which being
 271         equal to the number of neurons in the output layer.
 272
 273         See also:
 274                 <fann_test>
 275
 276         This function appears in FANN >= 1.0.0.
 277 */
 278 FANN_EXTERNAL fann_type * FANN_API fann_run(struct fann *ann, fann_type * input);
 279
 280 /* Function: fann_randomize_weights
 281         Give each connection a random weight between *min_weight* and *max_weight*
 282
 283         From the beginning the weights are random between -0.1 and 0.1.
 284
 285         See also:
 286                 <fann_init_weights>
 287
 288         This function appears in FANN >= 1.0.0.
 289 */
 290 FANN_EXTERNAL void FANN_API fann_randomize_weights(struct fann *ann, fann_type min_weight,
 291                                                                                                    fann_type max_weight);
 292
 293 /* Function: fann_init_weights
 294         Initialize the weights using Widrow + Nguyen's algorithm.
 295
 296         This function behaves similarly to fann_randomize_weights. It will use the algorithm developed
 297         by Derrick Nguyen and Bernard Widrow to set the weights in such a way
 298         as to speed up training. This technique is not always successful, and in some cases can be less
 299         efficient than a purely random initialization.
 300
 301         The algorithm requires access to the range of the input data (ie, largest and smallest input),
 302         and therefore accepts a second argument, data, which is the training data that will be used to
 303         train the network.
 304
 305         See also:
 306                 <fann_randomize_weights>, <fann_read_train_from_file>
 307
 308         This function appears in FANN >= 1.1.0.
 309 */
 310 FANN_EXTERNAL void FANN_API fann_init_weights(struct fann *ann, struct fann_train_data *train_data);
 311
 312 /* Function: fann_print_connections
 313         Will print the connections of the ann in a compact matrix, for easy viewing of the internals
 314         of the ann.
 315
 316         The output from fann_print_connections on a small (2 2 1) network trained on the xor problem
 317         >Layer / Neuron 012345
 318         >L   1 / N    3 BBa...
 319         >L   1 / N    4 BBA...
 320         >L   1 / N    5 ......
 321         >L   2 / N    6 ...BBA
 322         >L   2 / N    7 ......
 323
 324         This network have five real neurons and two bias neurons. This gives a total of seven neurons
 325         named from 0 to 6. The connections between these neurons can be seen in the matrix. "." is a
 326         place where there is no connection, while a character tells how strong the connection is on a
 327         scale from a-z. The two real neurons in the hidden layer (neuron 3 and 4 in layer 1) has
 328         connection from the three neurons in the previous layer as is visible in the first two lines.
 329         The output neuron (6) has connections form the three neurons in the hidden layer 3 - 5 as is
 330         visible in the fourth line.
 331
 332         To simplify the matrix output neurons is not visible as neurons that connections can come from,
 333         and input and bias neurons are not visible as neurons that connections can go to.
 334
 335         This function appears in FANN >= 1.2.0.
 336 */
 337 FANN_EXTERNAL void FANN_API fann_print_connections(struct fann *ann);
 338
 339 /* Group: Parameters */
 340 /* Function: fann_print_parameters
 341
 342         Prints all of the parameters and options of the ANN
 343
 344         This function appears in FANN >= 1.2.0.
 345 */
 346 FANN_EXTERNAL void FANN_API fann_print_parameters(struct fann *ann);
 347
 348
 349 /* Function: fann_get_num_input
 350
 351    Get the number of input neurons.
 352
 353         This function appears in FANN >= 1.0.0.
 354 */
 355 FANN_EXTERNAL unsigned int FANN_API fann_get_num_input(struct fann *ann);
 356
 357
 358 /* Function: fann_get_num_output
 359
 360    Get the number of output neurons.
 361
 362         This function appears in FANN >= 1.0.0.
 363 */
 364 FANN_EXTERNAL unsigned int FANN_API fann_get_num_output(struct fann *ann);
 365
 366
 367 /* Function: fann_get_total_neurons
 368
 369    Get the total number of neurons in the entire network. This number does also include the
 370         bias neurons, so a 2-4-2 network has 2+4+2 +2(bias) = 10 neurons.
 371
 372         This function appears in FANN >= 1.0.0.
 373 */
 374 FANN_EXTERNAL unsigned int FANN_API fann_get_total_neurons(struct fann *ann);
 375
 376
 377 /* Function: fann_get_total_connections
 378
 379    Get the total number of connections in the entire network.
 380
 381         This function appears in FANN >= 1.0.0.
 382 */
 383 FANN_EXTERNAL unsigned int FANN_API fann_get_total_connections(struct fann *ann);
 384
 385 #ifdef FIXEDFANN
 386
 387 /* Function: fann_get_decimal_point
 388
 389         Returns the position of the decimal point in the ann.
 390
 391         This function is only available when the ANN is in fixed point mode.
 392
 393         The decimal point is described in greater detail in the tutorial <Fixed Point Usage>.
 394
 395         See also:
 396                 <Fixed Point Usage>, <fann_get_multiplier>, <fann_save_to_fixed>, <fann_save_train_to_fixed>
 397
 398         This function appears in FANN >= 1.0.0.
 399 */
 400 FANN_EXTERNAL unsigned int FANN_API fann_get_decimal_point(struct fann *ann);
 401
 402
 403 /* Function: fann_get_multiplier
 404
 405     returns the multiplier that fix point data is multiplied with.
 406
 407         This function is only available when the ANN is in fixed point mode.
 408
 409         The multiplier is the used to convert between floating point and fixed point notation.
 410         A floating point number is multiplied with the multiplier in order to get the fixed point
 411         number and visa versa.
 412
 413         The multiplier is described in greater detail in the tutorial <Fixed Point Usage>.
 414
 415         See also:
 416                 <Fixed Point Usage>, <fann_get_decimal_point>, <fann_save_to_fixed>, <fann_save_train_to_fixed>
 417
 418         This function appears in FANN >= 1.0.0.
 419 */
 420 FANN_EXTERNAL unsigned int FANN_API fann_get_multiplier(struct fann *ann);
 421
 422 #endif  /* FIXEDFANN */
 423
 424 #ifdef __cplusplus
 425 #ifndef __cplusplus
 426 /* to fool automatic indention engines */
 427 {
 428
 429 #endif
 430 }
 431 #endif  /* __cplusplus */
 432
 433 #endif  /* __fann_h__ */
 434
 435 #endif /* NOT FANN_INCLUDE */