2 Fast Artificial Neural Network Library (fann)
3 Copyright (C) 2003 Steffen Nissen (lukesky@diku.dk)
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.
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.
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
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.
26 /* Section: FANN Creation/Execution
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>.
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.
37 /* Group: Creation, Destruction & Execution */
40 /* just to allow for inclusion of fann.h in normal stuations where only floats are needed */
42 #include "fixedfann.h"
44 #include "floatfann.h"
45 #endif /* FIXEDFANN */
49 /* COMPAT_TIME REPLACEMENT */
53 #if !defined(_MSC_EXTENSIONS) && !defined(_INC_WINDOWS)
54 extern unsigned long __stdcall GetTickCount(void);
56 #else /* _MSC_EXTENSIONS */
57 #define WIN32_LEAN_AND_MEAN
59 #endif /* _MSC_EXTENSIONS */
70 } /* to fool automatic indention engines */
72 #endif /* __cplusplus */
78 /* ----- Macros used to define DLL external entrypoints ----- */
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
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)
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
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
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.
116 #if (_MSC_VER > 1300)
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)
125 #define FANN_EXTERNAL __declspec(dllimport)
126 #endif /* FANN_DLL_EXPORTS*/
127 #define FANN_API __stdcall
129 #define FANN_EXTERNAL
131 #endif /* _MSC_VER */
132 /* ----- End of macros used to define DLL external entrypoints ----- */
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"
142 /* Function: fann_create_standard
144 Creates a standard fully connected backpropagation neural network.
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.
150 To destroy a <struct fann> use the <fann_destroy> function.
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.
158 A pointer to the newly created <struct fann>.
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);
166 <fann_create_standard_array>, <fann_create_sparse>, <fann_create_shortcut>
168 This function appears in FANN >= 2.0.0.
170 FANN_EXTERNAL struct fann *FANN_API fann_create_standard(unsigned int num_layers, ...);
172 /* Function: fann_create_standard_array
173 Just like <fann_create_standard>, but with an array of layer sizes
174 instead of individual parameters.
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);
183 <fann_create_standard>, <fann_create_sparse>, <fann_create_shortcut>
185 This function appears in FANN >= 2.0.0.
187 FANN_EXTERNAL struct fann *FANN_API fann_create_standard_array(unsigned int num_layers,
188 unsigned int *layers);
190 /* Function: fann_create_sparse
192 Creates a standard backpropagation neural network, which is not fully connected.
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.
204 A pointer to the newly created <struct fann>.
207 <fann_create_sparse_array>, <fann_create_standard>, <fann_create_shortcut>
209 This function appears in FANN >= 2.0.0.
211 FANN_EXTERNAL struct fann *FANN_API fann_create_sparse(float connection_rate,
212 unsigned int num_layers, ...);
215 /* Function: fann_create_sparse_array
216 Just like <fann_create_sparse>, but with an array of layer sizes
217 instead of individual parameters.
219 See <fann_create_standard_array> for a description of the parameters.
222 <fann_create_sparse>, <fann_create_standard>, <fann_create_shortcut>
224 This function appears in FANN >= 2.0.0.
226 FANN_EXTERNAL struct fann *FANN_API fann_create_sparse_array(float connection_rate,
227 unsigned int num_layers,
228 unsigned int *layers);
230 /* Function: fann_create_shortcut
232 Creates a standard backpropagation neural network, which is not fully connected and which
233 also has shortcut connections.
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.
239 See <fann_create_standard> for a description of the parameters.
242 <fann_create_shortcut_array>, <fann_create_standard>, <fann_create_sparse>,
244 This function appears in FANN >= 2.0.0.
246 FANN_EXTERNAL struct fann *FANN_API fann_create_shortcut(unsigned int num_layers, ...);
248 /* Function: fann_create_shortcut_array
249 Just like <fann_create_shortcut>, but with an array of layer sizes
250 instead of individual parameters.
252 See <fann_create_standard_array> for a description of the parameters.
255 <fann_create_shortcut>, <fann_create_standard>, <fann_create_sparse>
257 This function appears in FANN >= 2.0.0.
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.
264 This function appears in FANN >= 1.0.0.
266 FANN_EXTERNAL void FANN_API fann_destroy(struct fann *ann);
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.
276 This function appears in FANN >= 1.0.0.
278 FANN_EXTERNAL fann_type * FANN_API fann_run(struct fann *ann, fann_type * input);
280 /* Function: fann_randomize_weights
281 Give each connection a random weight between *min_weight* and *max_weight*
283 From the beginning the weights are random between -0.1 and 0.1.
288 This function appears in FANN >= 1.0.0.
290 FANN_EXTERNAL void FANN_API fann_randomize_weights(struct fann *ann, fann_type min_weight,
291 fann_type max_weight);
293 /* Function: fann_init_weights
294 Initialize the weights using Widrow + Nguyen's algorithm.
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.
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
306 <fann_randomize_weights>, <fann_read_train_from_file>
308 This function appears in FANN >= 1.1.0.
310 FANN_EXTERNAL void FANN_API fann_init_weights(struct fann *ann, struct fann_train_data *train_data);
312 /* Function: fann_print_connections
313 Will print the connections of the ann in a compact matrix, for easy viewing of the internals
316 The output from fann_print_connections on a small (2 2 1) network trained on the xor problem
317 >Layer / Neuron 012345
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.
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.
335 This function appears in FANN >= 1.2.0.
337 FANN_EXTERNAL void FANN_API fann_print_connections(struct fann *ann);
339 /* Group: Parameters */
340 /* Function: fann_print_parameters
342 Prints all of the parameters and options of the ANN
344 This function appears in FANN >= 1.2.0.
346 FANN_EXTERNAL void FANN_API fann_print_parameters(struct fann *ann);
349 /* Function: fann_get_num_input
351 Get the number of input neurons.
353 This function appears in FANN >= 1.0.0.
355 FANN_EXTERNAL unsigned int FANN_API fann_get_num_input(struct fann *ann);
358 /* Function: fann_get_num_output
360 Get the number of output neurons.
362 This function appears in FANN >= 1.0.0.
364 FANN_EXTERNAL unsigned int FANN_API fann_get_num_output(struct fann *ann);
367 /* Function: fann_get_total_neurons
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.
372 This function appears in FANN >= 1.0.0.
374 FANN_EXTERNAL unsigned int FANN_API fann_get_total_neurons(struct fann *ann);
377 /* Function: fann_get_total_connections
379 Get the total number of connections in the entire network.
381 This function appears in FANN >= 1.0.0.
383 FANN_EXTERNAL unsigned int FANN_API fann_get_total_connections(struct fann *ann);
387 /* Function: fann_get_decimal_point
389 Returns the position of the decimal point in the ann.
391 This function is only available when the ANN is in fixed point mode.
393 The decimal point is described in greater detail in the tutorial <Fixed Point Usage>.
396 <Fixed Point Usage>, <fann_get_multiplier>, <fann_save_to_fixed>, <fann_save_train_to_fixed>
398 This function appears in FANN >= 1.0.0.
400 FANN_EXTERNAL unsigned int FANN_API fann_get_decimal_point(struct fann *ann);
403 /* Function: fann_get_multiplier
405 returns the multiplier that fix point data is multiplied with.
407 This function is only available when the ANN is in fixed point mode.
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.
413 The multiplier is described in greater detail in the tutorial <Fixed Point Usage>.
416 <Fixed Point Usage>, <fann_get_decimal_point>, <fann_save_to_fixed>, <fann_save_train_to_fixed>
418 This function appears in FANN >= 1.0.0.
420 FANN_EXTERNAL unsigned int FANN_API fann_get_multiplier(struct fann *ann);
422 #endif /* FIXEDFANN */
426 /* to fool automatic indention engines */
431 #endif /* __cplusplus */
433 #endif /* __fann_h__ */
435 #endif /* NOT FANN_INCLUDE */