FANN Creation/Execution

The FANN library is designed to be very easy to use.  A feedforward ann can be created by a simple fann_create_standard function, while other ANNs can be created just as easily.  The ANNs can be trained by fann_train_on_file and executed by fann_run.

All of this can be done without much knowledge of the internals of ANNs, although the ANNs created will still be powerful and effective.  If you have more knowledge about ANNs, and desire more control, almost every part of the ANNs can be parametrized to create specialized and highly optimal ANNs.

Summary
FANN Creation/ExecutionThe FANN library is designed to be very easy to use.
Creation, Destruction & Execution
fann_create_standardCreates a standard fully connected backpropagation neural network.
fann_create_standard_arrayJust like fann_create_standard, but with an array of layer sizes instead of individual parameters.
fann_create_sparseCreates a standard backpropagation neural network, which is not fully connected.
fann_create_sparse_arrayJust like fann_create_sparse, but with an array of layer sizes instead of individual parameters.
fann_create_shortcutCreates a standard backpropagation neural network, which is fully connected and which also has shortcut connections.
fann_create_shortcut_arrayJust like fann_create_shortcut, but with an array of layer sizes instead of individual parameters.
fann_destroyDestroys the entire network, properly freeing all the associated memory.
fann_copyCreates a copy of a fann structure.
fann_runWill run input through the neural network, returning an array of outputs, the number of which being equal to the number of neurons in the output layer.
fann_randomize_weightsGive each connection a random weight between min_weight and max_weight
fann_init_weightsInitialize the weights using Widrow + Nguyen’s algorithm.
fann_print_connectionsWill print the connections of the ann in a compact matrix, for easy viewing of the internals of the ann.
Parameters
fann_print_parametersPrints all of the parameters and options of the ANN
fann_get_num_inputGet the number of input neurons.
fann_get_num_outputGet the number of output neurons.
fann_get_total_neuronsGet the total number of neurons in the entire network.
fann_get_total_connectionsGet the total number of connections in the entire network.
fann_get_network_typeGet the type of neural network it was created as.
fann_get_connection_rateGet the connection rate used when the network was created
fann_get_num_layersGet the number of layers in the network
fann_get_layer_arrayGet the number of neurons in each layer in the network.
fann_get_bias_arrayGet the number of bias in each layer in the network.
fann_get_connection_arrayGet the connections in the network.
fann_set_weight_arraySet connections in the network.
fann_set_weightSet a connection in the network.
fann_get_weightsGet all the network weights.
fann_set_weightsSet network weights.
fann_set_user_dataStore a pointer to user defined data.
fann_get_user_dataGet a pointer to user defined data that was previously set with fann_set_user_data.
fann_disable_seed_randDisables the automatic random generator seeding that happens in FANN.
fann_enable_seed_randEnables the automatic random generator seeding that happens in FANN.
fann_get_decimal_pointReturns the position of the decimal point in the ann.
fann_get_multiplierreturns the multiplier that fix point data is multiplied with.

Creation, Destruction & Execution

fann_create_standard

FANN_EXTERNAL struct fann *FANN_API fann_create_standard(
   unsigned int num_layers,
    ...
)

Creates a standard fully connected backpropagation neural network.

There will be a bias neuron in each layer (except the output layer), and this bias neuron will be connected to all neurons in the next layer.  When running the network, the bias nodes always emits 1.

To destroy a struct fann use the fann_destroy function.

Parameters

num_layersThe total number of layers including the input and the output layer.
...Integer values determining the number of neurons in each layer starting with the input layer and ending with the output layer.

Returns

A pointer to the newly created struct fann.

Example

// Creating an ANN with 2 input neurons, 1 output neuron,
// and two hidden layers with 8 and 9 neurons
struct fann *ann = fann_create_standard(4, 2, 8, 9, 1);

See also

fann_create_standard_array, fann_create_sparse, fann_create_shortcut

This function appears in FANN >= 2.0.0.

fann_create_standard_array

FANN_EXTERNAL struct fann *FANN_API fann_create_standard_array(
   unsigned int num_layers,
   const unsigned int *layers
)

Just like fann_create_standard, but with an array of layer sizes instead of individual parameters.

Example

// Creating an ANN with 2 input neurons, 1 output neuron,
// and two hidden layers with 8 and 9 neurons
unsigned int layers[4] = {2, 8, 9, 1};
struct fann *ann = fann_create_standard_array(4, layers);

See also

fann_create_standard, fann_create_sparse, fann_create_shortcut

This function appears in FANN >= 2.0.0.

fann_create_sparse

FANN_EXTERNAL struct fann *FANN_API fann_create_sparse(
   float connection_rate,
   unsigned int num_layers,
    ...
)

Creates a standard backpropagation neural network, which is not fully connected.

Parameters

connection_rateThe connection rate controls how many connections there will be in the network.  If the connection rate is set to 1, the network will be fully connected, but if it is set to 0.5 only half of the connections will be set.  A connection rate of 1 will yield the same result as fann_create_standard
num_layersThe total number of layers including the input and the output layer.
...Integer values determining the number of neurons in each layer starting with the input layer and ending with the output layer.

Returns

A pointer to the newly created struct fann.

See also

fann_create_sparse_array, fann_create_standard, fann_create_shortcut

This function appears in FANN >= 2.0.0.

fann_create_sparse_array

FANN_EXTERNAL struct fann *FANN_API fann_create_sparse_array(
   float connection_rate,
   unsigned int num_layers,
   const unsigned int *layers
)

Just like fann_create_sparse, but with an array of layer sizes instead of individual parameters.

See fann_create_standard_array for a description of the parameters.

See also

fann_create_sparse, fann_create_standard, fann_create_shortcut

This function appears in FANN >= 2.0.0.

fann_create_shortcut

FANN_EXTERNAL struct fann *FANN_API fann_create_shortcut(
   unsigned int num_layers,
    ...
)

Creates a standard backpropagation neural network, which is fully connected and which also has shortcut connections.

Shortcut connections are connections that skip layers.  A fully connected network with shortcut connections is a network where all neurons are connected to all neurons in later layers.  Including direct connections from the input layer to the output layer.

See fann_create_standard for a description of the parameters.

See also

fann_create_shortcut_array, fann_create_standard, fann_create_sparse,

This function appears in FANN >= 2.0.0.

fann_create_shortcut_array

FANN_EXTERNAL struct fann *FANN_API fann_create_shortcut_array(
   unsigned int num_layers,
   const unsigned int *layers
)

Just like fann_create_shortcut, but with an array of layer sizes instead of individual parameters.

See fann_create_standard_array for a description of the parameters.

See also

fann_create_shortcut, fann_create_standard, fann_create_sparse

This function appears in FANN >= 2.0.0.

fann_destroy

FANN_EXTERNAL void FANN_API fann_destroy(struct fann *ann)

Destroys the entire network, properly freeing all the associated memory.

This function appears in FANN >= 1.0.0.

fann_copy

FANN_EXTERNAL struct fann * FANN_API fann_copy(struct fann *ann)

Creates a copy of a fann structure.

Data in the user data fann_set_user_data is not copied, but the user data pointer is copied.

This function appears in FANN >= 2.2.0.

fann_run

FANN_EXTERNAL fann_type * FANN_API fann_run(struct fann *ann,
fann_type *input)

Will run input through the neural network, returning an array of outputs, the number of which being equal to the number of neurons in the output layer.

See also

fann_test

This function appears in FANN >= 1.0.0.

fann_randomize_weights

FANN_EXTERNAL void FANN_API fann_randomize_weights(struct fann *ann,
fann_type min_weight,
fann_type max_weight)

Give each connection a random weight between min_weight and max_weight

From the beginning the weights are random between -0.1 and 0.1.

See also

fann_init_weights

This function appears in FANN >= 1.0.0.

fann_init_weights

FANN_EXTERNAL void FANN_API fann_init_weights(
   struct fann *ann,
   struct fann_train_data *train_data
)

Initialize the weights using Widrow + Nguyen’s algorithm.

This function behaves similarly to fann_randomize_weights.  It will use the algorithm developed by Derrick Nguyen and Bernard Widrow to set the weights in such a way as to speed up training.  This technique is not always successful, and in some cases can be less efficient than a purely random initialization.

The algorithm requires access to the range of the input data (ie, largest and smallest input), and therefore accepts a second argument, data, which is the training data that will be used to train the network.

See also

fann_randomize_weights, fann_read_train_from_file

This function appears in FANN >= 1.1.0.

fann_print_connections

FANN_EXTERNAL void FANN_API fann_print_connections(struct fann *ann)

Will print the connections of the ann in a compact matrix, for easy viewing of the internals of the ann.

The output from fann_print_connections on a small (2 2 1) network trained on the xor problem

Layer / Neuron 012345
L   1 / N    3 BBa...
L   1 / N    4 BBA...
L   1 / N    5 ......
L   2 / N    6 ...BBA
L   2 / N    7 ......

This network has five real neurons and two bias neurons.  This gives a total of seven neurons named from 0 to 6.  The connections between these neurons can be seen in the matrix.  “.” is a place where there is no connection, while a character tells how strong the connection is on a scale from a-z.  The two real neurons in the hidden layer (neuron 3 and 4 in layer 1) have connections from the three neurons in the previous layer as is visible in the first two lines.  The output neuron (6) has connections from the three neurons in the hidden layer 3 - 5 as is visible in the fourth line.

To simplify the matrix output neurons are not visible as neurons that connections can come from, and input and bias neurons are not visible as neurons that connections can go to.

This function appears in FANN >= 1.2.0.

Parameters

fann_print_parameters

FANN_EXTERNAL void FANN_API fann_print_parameters(struct fann *ann)

Prints all of the parameters and options of the ANN

This function appears in FANN >= 1.2.0.

fann_get_num_input

FANN_EXTERNAL unsigned int FANN_API fann_get_num_input(struct fann *ann)

Get the number of input neurons.

This function appears in FANN >= 1.0.0.

fann_get_num_output

FANN_EXTERNAL unsigned int FANN_API fann_get_num_output(struct fann *ann)

Get the number of output neurons.

This function appears in FANN >= 1.0.0.

fann_get_total_neurons

FANN_EXTERNAL unsigned int FANN_API fann_get_total_neurons(struct fann *ann)

Get the total number of neurons in the entire network.  This number does also include the bias neurons, so a 2-4-2 network has 2+4+2 +2(bias) = 10 neurons.

This function appears in FANN >= 1.0.0.

fann_get_total_connections

FANN_EXTERNAL unsigned int FANN_API fann_get_total_connections(
   struct fann *ann
)

Get the total number of connections in the entire network.

This function appears in FANN >= 1.0.0.

fann_get_network_type

FANN_EXTERNAL enum fann_nettype_enum FANN_API fann_get_network_type(
   struct fann *ann
)

Get the type of neural network it was created as.

Parameters

annA previously created neural network structure of type struct fann pointer.

Returns

The neural network type from enum fann_network_type_enum

See Also

fann_network_type_enum

This function appears in FANN >= 2.1.0

fann_get_connection_rate

FANN_EXTERNAL float FANN_API fann_get_connection_rate(struct fann *ann)

Get the connection rate used when the network was created

Parameters

annA previously created neural network structure of type struct fann pointer.

Returns

The connection rate

This function appears in FANN >= 2.1.0

fann_get_num_layers

FANN_EXTERNAL unsigned int FANN_API fann_get_num_layers(struct fann *ann)

Get the number of layers in the network

Parameters

annA previously created neural network structure of type struct fann pointer.

Returns

The number of layers in the neural network

Example

// Obtain the number of layers in a neural network
struct fann *ann = fann_create_standard(4, 2, 8, 9, 1);
unsigned int num_layers = fann_get_num_layers(ann);

This function appears in FANN >= 2.1.0

fann_get_layer_array

FANN_EXTERNAL void FANN_API fann_get_layer_array(struct fann *ann,
unsigned int *layers)

Get the number of neurons in each layer in the network.

Bias is not included so the layers match the fann_create functions.

Parameters

annA previously created neural network structure of type struct fann pointer.

The layers array must be preallocated to at least sizeof(unsigned int) * fann_num_layers() long.

This function appears in FANN >= 2.1.0

fann_get_bias_array

FANN_EXTERNAL void FANN_API fann_get_bias_array(struct fann *ann,
unsigned int *bias)

Get the number of bias in each layer in the network.

Parameters

annA previously created neural network structure of type struct fann pointer.

The bias array must be preallocated to at least sizeof(unsigned int) * fann_num_layers() long.

This function appears in FANN >= 2.1.0

fann_get_connection_array

FANN_EXTERNAL void FANN_API fann_get_connection_array(
   struct fann *ann,
   struct fann_connection *connections
)

Get the connections in the network.

Parameters

annA previously created neural network structure of type struct fann pointer.

The connections array must be preallocated to at least sizeof(struct fann_connection) * fann_get_total_connections() long.

This function appears in FANN >= 2.1.0

fann_set_weight_array

FANN_EXTERNAL void FANN_API fann_set_weight_array(
   struct fann *ann,
   struct fann_connection *connections,
   unsigned int num_connections
)

Set connections in the network.

Parameters

annA previously created neural network structure of type struct fann pointer.

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.

This function appears in FANN >= 2.1.0

fann_set_weight

FANN_EXTERNAL void FANN_API fann_set_weight(struct fann *ann,
unsigned int from_neuron,
unsigned int to_neuron,
fann_type weight)

Set a connection in the network.

Parameters

annA previously created neural network structure of type struct fann pointer.

Only the weights can be changed.  The connection/weight is ignored if it does not already exist in the network.

This function appears in FANN >= 2.1.0

fann_get_weights

FANN_EXTERNAL void FANN_API fann_get_weights(struct fann *ann,
fann_type *weights)

Get all the network weights.

Parameters

annA previously created neural network structure of type struct fann pointer.
weightsA fann_type pointer to user data.  It is the responsibility of the user to allocate sufficient space to store all the weights.

This function appears in FANN >= x.y.z

fann_set_weights

FANN_EXTERNAL void FANN_API fann_set_weights(struct fann *ann,
fann_type *weights)

Set network weights.

Parameters

annA previously created neural network structure of type struct fann pointer.
weightsA fann_type pointer to user data.  It is the responsibility of the user to make the weights array sufficient long to store all the weights.

This function appears in FANN >= x.y.z

fann_set_user_data

FANN_EXTERNAL void FANN_API fann_set_user_data(struct fann *ann,
void *user_data)

Store a pointer to user defined data.  The pointer can be retrieved with fann_get_user_data for example in a callback.  It is the user’s responsibility to allocate and deallocate any data that the pointer might point to.

Parameters

annA previously created neural network structure of type struct fann pointer.
user_dataA void pointer to user defined data.

This function appears in FANN >= 2.1.0

fann_get_user_data

FANN_EXTERNAL void * FANN_API fann_get_user_data(struct fann *ann)

Get a pointer to user defined data that was previously set with fann_set_user_data.  It is the user’s responsibility to allocate and deallocate any data that the pointer might point to.

Parameters

annA previously created neural network structure of type struct fann pointer.

Returns

A void pointer to user defined data.

This function appears in FANN >= 2.1.0

fann_disable_seed_rand

FANN_EXTERNAL void FANN_API fann_disable_seed_rand()

Disables the automatic random generator seeding that happens in FANN.

Per default FANN will always seed the random generator when creating a new network, unless FANN_NO_SEED is defined during compilation of the library.  This method can disable this at runtime.

This function appears in FANN >= 2.3.0

fann_enable_seed_rand

FANN_EXTERNAL void FANN_API fann_enable_seed_rand()

Enables the automatic random generator seeding that happens in FANN.

Per default FANN will always seed the random generator when creating a new network, unless FANN_NO_SEED is defined during compilation of the library.  This method can disable this at runtime.

This function appears in FANN >= 2.3.0

fann_get_decimal_point

FANN_EXTERNAL unsigned int FANN_API fann_get_decimal_point(struct fann *ann)

Returns the position of the decimal point in the ann.

This function is only available when the ANN is in fixed point mode.

The decimal point is described in greater detail in the tutorial <Fixed Point Usage>.

See also

<Fixed Point Usage>, fann_get_multiplier, fann_save_to_fixed, fann_save_train_to_fixed

This function appears in FANN >= 1.0.0.

fann_get_multiplier

FANN_EXTERNAL unsigned int FANN_API fann_get_multiplier(struct fann *ann)

returns the multiplier that fix point data is multiplied with.

This function is only available when the ANN is in fixed point mode.

The multiplier is the used to convert between floating point and fixed point notation.  A floating point number is multiplied with the multiplier in order to get the fixed point number and visa versa.

The multiplier is described in greater detail in the tutorial <Fixed Point Usage>.

See also

<Fixed Point Usage>, fann_get_decimal_point, fann_save_to_fixed, fann_save_train_to_fixed

This function appears in FANN >= 1.0.0.

FANN_EXTERNAL struct fann *FANN_API fann_create_standard(
   unsigned int num_layers,
    ...
)
Creates a standard fully connected backpropagation neural network.
FANN_EXTERNAL struct fann *FANN_API fann_create_standard_array(
   unsigned int num_layers,
   const unsigned int *layers
)
Just like fann_create_standard, but with an array of layer sizes instead of individual parameters.
FANN_EXTERNAL struct fann *FANN_API fann_create_sparse(
   float connection_rate,
   unsigned int num_layers,
    ...
)
Creates a standard backpropagation neural network, which is not fully connected.
FANN_EXTERNAL struct fann *FANN_API fann_create_sparse_array(
   float connection_rate,
   unsigned int num_layers,
   const unsigned int *layers
)
Just like fann_create_sparse, but with an array of layer sizes instead of individual parameters.
FANN_EXTERNAL struct fann *FANN_API fann_create_shortcut(
   unsigned int num_layers,
    ...
)
Creates a standard backpropagation neural network, which is fully connected and which also has shortcut connections.
FANN_EXTERNAL struct fann *FANN_API fann_create_shortcut_array(
   unsigned int num_layers,
   const unsigned int *layers
)
Just like fann_create_shortcut, but with an array of layer sizes instead of individual parameters.
FANN_EXTERNAL void FANN_API fann_destroy(struct fann *ann)
Destroys the entire network, properly freeing all the associated memory.
FANN_EXTERNAL struct fann * FANN_API fann_copy(struct fann *ann)
Creates a copy of a fann structure.
FANN_EXTERNAL fann_type * FANN_API fann_run(struct fann *ann,
fann_type *input)
Will run input through the neural network, returning an array of outputs, the number of which being equal to the number of neurons in the output layer.
FANN_EXTERNAL void FANN_API fann_randomize_weights(struct fann *ann,
fann_type min_weight,
fann_type max_weight)
Give each connection a random weight between min_weight and max_weight
FANN_EXTERNAL void FANN_API fann_init_weights(
   struct fann *ann,
   struct fann_train_data *train_data
)
Initialize the weights using Widrow + Nguyen’s algorithm.
FANN_EXTERNAL void FANN_API fann_print_connections(struct fann *ann)
Will print the connections of the ann in a compact matrix, for easy viewing of the internals of the ann.
FANN_EXTERNAL void FANN_API fann_print_parameters(struct fann *ann)
Prints all of the parameters and options of the ANN
FANN_EXTERNAL unsigned int FANN_API fann_get_num_input(struct fann *ann)
Get the number of input neurons.
FANN_EXTERNAL unsigned int FANN_API fann_get_num_output(struct fann *ann)
Get the number of output neurons.
FANN_EXTERNAL unsigned int FANN_API fann_get_total_neurons(struct fann *ann)
Get the total number of neurons in the entire network.
FANN_EXTERNAL unsigned int FANN_API fann_get_total_connections(
   struct fann *ann
)
Get the total number of connections in the entire network.
FANN_EXTERNAL enum fann_nettype_enum FANN_API fann_get_network_type(
   struct fann *ann
)
Get the type of neural network it was created as.
FANN_EXTERNAL float FANN_API fann_get_connection_rate(struct fann *ann)
Get the connection rate used when the network was created
FANN_EXTERNAL unsigned int FANN_API fann_get_num_layers(struct fann *ann)
Get the number of layers in the network
FANN_EXTERNAL void FANN_API fann_get_layer_array(struct fann *ann,
unsigned int *layers)
Get the number of neurons in each layer in the network.
FANN_EXTERNAL void FANN_API fann_get_bias_array(struct fann *ann,
unsigned int *bias)
Get the number of bias in each layer in the network.
FANN_EXTERNAL void FANN_API fann_get_connection_array(
   struct fann *ann,
   struct fann_connection *connections
)
Get the connections in the network.
FANN_EXTERNAL void FANN_API fann_set_weight_array(
   struct fann *ann,
   struct fann_connection *connections,
   unsigned int num_connections
)
Set connections in the network.
FANN_EXTERNAL void FANN_API fann_set_weight(struct fann *ann,
unsigned int from_neuron,
unsigned int to_neuron,
fann_type weight)
Set a connection in the network.
FANN_EXTERNAL void FANN_API fann_get_weights(struct fann *ann,
fann_type *weights)
Get all the network weights.
FANN_EXTERNAL void FANN_API fann_set_weights(struct fann *ann,
fann_type *weights)
Set network weights.
FANN_EXTERNAL void FANN_API fann_set_user_data(struct fann *ann,
void *user_data)
Store a pointer to user defined data.
FANN_EXTERNAL void * FANN_API fann_get_user_data(struct fann *ann)
Get a pointer to user defined data that was previously set with fann_set_user_data.
FANN_EXTERNAL void FANN_API fann_disable_seed_rand()
Disables the automatic random generator seeding that happens in FANN.
FANN_EXTERNAL void FANN_API fann_enable_seed_rand()
Enables the automatic random generator seeding that happens in FANN.
FANN_EXTERNAL unsigned int FANN_API fann_get_decimal_point(struct fann *ann)
Returns the position of the decimal point in the ann.
FANN_EXTERNAL unsigned int FANN_API fann_get_multiplier(struct fann *ann)
returns the multiplier that fix point data is multiplied with.
FANN_EXTERNAL void FANN_API fann_train_on_file(
   struct fann *ann,
   const char *filename,
   unsigned int max_epochs,
   unsigned int epochs_between_reports,
   float desired_error
)
Does the same as fann_train_on_data, but reads the training data directly from a file.
struct fann
The fast artificial neural network (fann) structure.
FANN_EXTERNAL fann_type * FANN_API fann_test(struct fann *ann,
fann_type *input,
fann_type *desired_output)
Test with a set of inputs, and a set of desired outputs.
FANN_EXTERNAL struct fann_train_data *FANN_API fann_read_train_from_file(
   const char *filename
)
Reads a file that stores training data.
Definition of network types used by fann_get_network_type
FANN_EXTERNAL int FANN_API fann_save_to_fixed(struct fann *ann,
const char *configuration_file)
Saves the entire network to a configuration file.
FANN_EXTERNAL int FANN_API fann_save_train_to_fixed(
   struct fann_train_data *data,
   const char *filename,
   unsigned int decimal_point
)
Saves the training structure to a fixed point data file.
Close