Expand description
Raw bindings to C functions of the Fast Artificial Neural Network library
§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.
§Training
There are many different ways of training neural networks and the FANN library supports a number of different approaches.
Two fundementally different approaches are the most commonly used:
-
Fixed topology training - The size and topology of the ANN is determined in advance and the training alters the weights in order to minimize the difference between the desired output values and the actual output values. This kind of training is supported by
fann_train_on_data
. -
Evolving topology training - The training start out with an empty ANN, only consisting of input and output neurons. Hidden neurons and connections are added during training, in order to achieve the same goal as for fixed topology training. This kind of training is supported by FANN Cascade Training.
§Cascade Training
Cascade training differs from ordinary training in the sense that it starts with an empty neural network and then adds neurons one by one, while it trains the neural network. The main benefit of this approach is that you do not have to guess the number of hidden layers and neurons prior to training, but cascade training has also proved better at solving some problems.
The basic idea of cascade training is that a number of candidate neurons are trained separate from the real network, then the most promising of these candidate neurons is inserted into the neural network. Then the output connections are trained and new candidate neurons are prepared. The candidate neurons are created as shortcut connected neurons in a new hidden layer, which means that the final neural network will consist of a number of hidden layers with one shortcut connected neuron in each.
§File Input/Output
It is possible to save an entire ann to a file with fann_save
for future loading with
fann_create_from_file
.
§Error Handling
Errors from the FANN library are usually reported on stderr
.
It is however possible to redirect these error messages to a file,
or completely ignore them with the fann_set_error_log
function.
It is also possible to inspect the last error message by using the
fann_get_errno
and fann_get_errstr
functions.
§Datatypes
The two main datatypes used in the FANN library are fann
,
which represents an artificial neural network, and fann_train_data
,
which represents training data.
Re-exports§
pub use fann_activationfunc_enum::*;
pub use fann_errno_enum::*;
pub use fann_errorfunc_enum::*;
pub use fann_nettype_enum::*;
pub use fann_stopfunc_enum::*;
pub use fann_train_enum::*;
Structs§
- The fast artificial neural network (
fann
) structure. - Describes a connection between two neurons and its weight.
- Structure used to store error-related information, both
fann
andfann_train_data
can be cast to this type. - Structure used to store data, for use with training.
Enums§
- The activation functions used for the neurons during training. The activation functions can either be defined for a group of neurons by
fann_set_activation_function_hidden
andfann_set_activation_function_output
, or it can be defined for a single neuron byfann_set_activation_function
. - Error events on
fann
andfann_train_data
. - Error function used during training.
- Definition of network types used by
fann_get_network_type
. - Stop criteria used during training.
- The Training algorithms used when training on
fann_train_data
with functions likefann_train_on_data
orfann_train_on_file
. The incremental training alters the weights after each time it is presented an input pattern, while batch only alters the weights once after it has been presented to all the patterns.
Statics§
Functions§
- Trains on an entire dataset, for a period of time using the Cascade2 training algorithm. This algorithm adds neurons to the neural network while training, which means that it needs to start with an ANN without any hidden layers. The neural network should also use shortcut connections, so
fann_create_shortcut
should be used to create the ANN like this: - Does the same as
fann_cascadetrain_on_data
, but reads the training data directly from a file. - Clears scaling parameters.
- Creates a copy of a fann structure.
- Constructs a backpropagation neural network from a configuration file, which has been saved by
fann_save
. - Creates a standard backpropagation neural network, which is not fully connected and which also has shortcut connections.
- Just like
fann_create_shortcut
, but with an array of layer sizes instead of individual parameters. - Creates a standard backpropagation neural network, which is not fully connected.
- Just like
fann_create_sparse
, but with an array of layer sizes instead of individual parameters. - Creates a standard fully connected backpropagation neural network.
- Just like
fann_create_standard
, but with an array of layer sizes instead of individual parameters. - Creates the training data struct from a user supplied function. As the training data are numerable (data 1, data 2…), the user must write a function that receives the number of the training data set (input,output) and returns the set.
- Scale data in input vector after getting it from the ANN based on previously calculated parameters.
- Scale data in output vector after getting it from the ANN based on previously calculated parameters.
- Descale input and output data based on previously calculated parameters.
- Destroys the entire network, properly freeing all the associated memory.
- Destructs the training data and properly deallocates all of the associated data. Be sure to call this function when finished using the training data.
- Returns an exact copy of a
fann_train_data
. - Reads the mean square error from the network.
- Get the activation function for neuron number
neuron
in layer numberlayer
, counting the input layer as layer 0. - Get the activation steepness for neuron number
neuron
in layer numberlayer
, counting the input layer as layer 0. - Get the number of bias in each layer in the network.
- The number of fail bits; means the number of output neurons which differ more than the bit fail limit (see
fann_get_bit_fail_limit
,fann_set_bit_fail_limit
). The bits are counted in all of the training data, so this number can be higher than the number of training data. - Returns the bit fail limit used during training.
- The cascade activation functions array is an array of the different activation functions used by the candidates.
- The number of activation functions in the
fann_get_cascade_activation_functions
array. - The cascade activation steepnesses array is an array of the different activation functions used by the candidates.
- The number of activation steepnesses in the
fann_get_cascade_activation_functions
array. - The cascade candidate change fraction is a number between 0 and 1 determining how large a fraction the
fann_get_MSE
value should change withinfann_get_cascade_candidate_stagnation_epochs
during training of the candidate neurons, in order for the training not to stagnate. If the training stagnates, the training of the candidate neurons will be ended and the best candidate will be selected. - The candidate limit is a limit for how much the candidate neuron may be trained. The limit is a limit on the proportion between the MSE and candidate score.
- The number of cascade candidate stagnation epochs determines the number of epochs training is allowed to continue without changing the MSE by a fraction of
fann_get_cascade_candidate_change_fraction
. - The maximum candidate epochs determines the maximum number of epochs the input connections to the candidates may be trained before adding a new candidate neuron.
- The maximum out epochs determines the maximum number of epochs the output connections may be trained after adding a new candidate neuron.
- The number of candidate groups is the number of groups of identical candidates which will be used during training.
- The number of candidates used during training (calculated by multiplying
fann_get_cascade_activation_functions_count
,fann_get_cascade_activation_steepnesses_count
andfann_get_cascade_num_candidate_groups
). - The cascade output change fraction is a number between 0 and 1 determining how large a fraction the
fann_get_MSE
value should change withinfann_get_cascade_output_stagnation_epochs
during training of the output connections, in order for the training not to stagnate. If the training stagnates, the training of the output connections will be ended and new candidates will be prepared. - The number of cascade output stagnation epochs determines the number of epochs training is allowed to continue without changing the MSE by a fraction of
fann_get_cascade_output_change_fraction
. - The weight multiplier is a parameter which is used to multiply the weights from the candidate neuron before adding the neuron to the neural network. This parameter is usually between 0 and 1, and is used to make the training a bit less aggressive.
- Get the connections in the network.
- Get the connection rate used when the network was created.
- Returns the last error number.
- Returns the last error string.
- Get the number of neurons in each layer in the network.
- Get the learning momentum.
- Return the learning rate.
- Get the type of neural network it was created as.
- Get the number of input neurons.
- Get the number of layers in the network.
- Get the number of output neurons.
- The decay is a small negative valued number which is the factor that the weights should become smaller in each iteration during quickprop training. This is used to make sure that the weights do not become too high during training.
- The mu factor is used to increase and decrease the step size during quickprop training. The mu factor should always be above 1, since it would otherwise decrease the step size when it was supposed to increase it.
- The decrease factor is a value smaller than 1, which is used to decrease the step size during RPROP training.
- The maximum step size is a positive number determining how large the maximum step size may be.
- The minimum step size is a small positive number determining how small the minimum step size may be.
- The initial step size is a positive number determining the initial step size.
- The increase factor is a value larger than 1, which is used to increase the step size during RPROP training.
- Get the total number of connections in the entire network.
- 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.
- Returns the error function used during training.
- Returns the the stop function used during training.
- Return the training algorithm as described by
fann_train_enum
. This training algorithm is used byfann_train_on_data
and associated functions. - 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. - Initialize the weights using Widrow + Nguyen’s algorithm.
- Returns the number of training patterns in the
fann_train_data
. - Merges the data from
data1
anddata2
into a newfann_train_data
. - Returns the number of inputs in each of the training patterns in the
fann_train_data
. - Returns the number of outputs in each of the training patterns in the
fann_train_data
. - Prints the connections of the ANN in a compact matrix, for easy viewing of the internals of the ANN.
- Prints the last error to
stderr
. - Prints all of the parameters and options of the ANN.
- Give each connection a random weight between
min_weight
andmax_weight
. - Reads a file that stores training data.
- Resets the mean square error from the network.
- Resets the last error number.
- Resets the last error string.
- Runs 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.
- Save the entire network to a configuration file.
- Saves the entire network to a configuration file. But it is saved in fixed point format no matter which format it is currently in.
- Save the training structure to a file, with the format specified in
fann_read_train_from_file
- Saves the training structure to a fixed point data file.
- Scale data in input vector before feeding it to the ANN based on previously calculated parameters.
- Scales the inputs in the training data to the specified range.
- Scale data in output vector before feeding it to the ANN based on previously calculated parameters.
- Scales the outputs in the training data to the specified range.
- Scale input and output data based on previously calculated parameters.
- Scales the inputs and outputs in the training data to the specified range.
- Set the activation function for neuron number
neuron
in layer numberlayer
, counting the input layer as layer 0. - Set the activation function for all of the hidden layers.
- Set the activation function for all the neurons in the layer number
layer
, counting the input layer as layer 0. - Set the activation function for the output layer.
- Set the activation steepness for neuron number
neuron
in layer numberlayer
, counting the input layer as layer 0. - Set the steepness of the activation steepness in all of the hidden layers.
- Set the activation steepness for all neurons in layer number
layer
, counting the input layer as layer 0. - Set the steepness of the activation steepness in the output layer.
- Set the bit fail limit used during training.
- Sets the callback function for use during training.
- Sets the array of cascade candidate activation functions. The array must be just as long as defined by the count.
- Sets the array of cascade candidate activation steepnesses. The array must be just as long as defined by the count.
- Sets the cascade candidate change fraction.
- Sets the candidate limit.
- Sets the number of cascade candidate stagnation epochs.
- Sets the max candidate epochs.
- Sets the maximum out epochs.
- Sets the number of candidate groups.
- Sets the cascade output change fraction.
- Sets the number of cascade output stagnation epochs.
- Sets the weight multiplier.
- Change where errors are logged to. Both
fann
andfann_data
can be cast tofann_error
, so this function can be used to set either of these. - Calculate input scaling parameters for future use based on training data.
- Set the learning momentum.
- Set the learning rate.
- Calculate output scaling parameters for future use based on training data.
- Sets the quickprop decay factor.
- Sets the quickprop mu factor.
- The decrease factor is a value smaller than 1, which is used to decrease the step size during RPROP training.
- The maximum step size is a positive number determining how large the maximum step size may be.
- The minimum step size is a small positive number determining how small the minimum step size may be.
- The initial step size is a positive number determining the initial step size.
- The increase factor used during RPROP training.
- Calculate input and output scaling parameters for future use based on training data.
- Set the error function used during training.
- Set the stop function used during training.
- Set the training algorithm.
- 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. - Set a connection in the network.
- Set connections in the network.
- Shuffles training data, randomizing the order. This is recommended for incremental training, while it has no influence during batch training.
- Returns an copy of a subset of the
fann_train_data
, starting at positionpos
andlength
elements forward. - Test with a set of inputs, and a set of desired outputs. This operation updates the mean square error, but does not change the network in any way.
- Tests a set of training data and calculates the MSE for the training data.
- Train one iteration with a set of inputs, and a set of desired outputs. This training is always incremental training (see
fann_train_enum
), since only one pattern is presented. - Train one epoch with a set of training data.
- Trains on an entire dataset, for a period of time.
- Does the same as
fann_train_on_data
, but reads the training data directly from a file.
Type Aliases§
- This callback function can be called during training when using
fann_train_on_data
,fann_train_on_file
orfann_cascadetrain_on_data
. - The type of weights, inputs and outputs in a neural network. In the Rust bindings, it is defined as
c_float
by default, and asc_double
, if thedouble
feature is configured.