fann/src/include/fann_cascade.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 #ifndef __fann_cascade_h__
  21 #define __fann_cascade_h__
  22
  23 /* Section: FANN Cascade Training
  24    Cascade training differs from ordinary training in the sense that it starts with an empty neural network
  25    and then adds neurons one by one, while it trains the neural network. The main benefit of this approach,
  26    is that you do not have to guess the number of hidden layers and neurons prior to training, but cascade
  27    training have also proved better at solving some problems.
  28
  29    The basic idea of cascade training is that a number of candidate neurons are trained separate from the
  30    real network, then the most promissing of these candidate neurons is inserted into the neural network.
  31    Then the output connections are trained and new candidate neurons is prepared. The candidate neurons are
  32    created as shorcut connected neurons in a new hidden layer, which means that the final neural network
  33    will consist of a number of hidden layers with one shorcut connected neuron in each.
  34 */
  35
  36 /* Group: Cascade Training */
  37
  38 /* Function: fann_cascadetrain_on_data
  39
  40    Trains on an entire dataset, for a period of time using the Cascade2 training algorithm.
  41    This algorithm adds neurons to the neural network while training, which means that it
  42    needs to start with an ANN without any hidden layers. The neural network should also use
  43    shortcut connections, so <fann_create_shortcut> should be used to create the ANN like this:
  44    >struct fann *ann = fann_create_shortcut(2, fann_num_input_train_data(train_data), fann_num_input_train_data(train_data));
  45
  46    This training uses the parameters set using the fann_set_cascade_..., but it also uses another
  47    training algorithm as it's internal training algorithm. This algorithm can be set to either
  48    FANN_TRAIN_RPROP or FANN_TRAIN_QUICKPROP by <fann_set_training_algorithm>, and the parameters
  49    set for these training algorithms will also affect the cascade training.
  50
  51    Parameters:
  52                 ann - The neural network
  53                 data - The data, which should be used during training
  54                 max_neuron - The maximum number of neurons to be added to neural network
  55                 neurons_between_reports - The number of neurons between printing a status report to stdout.
  56                         A value of zero means no reports should be printed.
  57                 desired_error - The desired <fann_get_MSE> or <fann_get_bit_fail>, depending on which stop function
  58                         is chosen by <fann_set_train_stop_function>.
  59
  60         Instead of printing out reports every neurons_between_reports, a callback function can be called
  61         (see <fann_set_callback>).
  62
  63         See also:
  64                 <fann_train_on_data>, <fann_cascadetrain_on_file>, <Parameters>
  65
  66         This function appears in FANN >= 2.0.0.
  67 */
  68 FANN_EXTERNAL void FANN_API fann_cascadetrain_on_data(struct fann *ann,
  69                                                                                                           struct fann_train_data *data,
  70                                                                                                           unsigned int max_neurons,
  71                                                                                                           unsigned int neurons_between_reports,
  72                                                                                                           float desired_error);
  73
  74 /* Function: fann_cascadetrain_on_file
  75
  76    Does the same as <fann_cascadetrain_on_data>, but reads the training data directly from a file.
  77
  78    See also:
  79                 <fann_cascadetrain_on_data>
  80
  81         This function appears in FANN >= 2.0.0.
  82 */
  83 FANN_EXTERNAL void FANN_API fann_cascadetrain_on_file(struct fann *ann, const char *filename,
  84                                                                                                           unsigned int max_neurons,
  85                                                                                                           unsigned int neurons_between_reports,
  86                                                                                                           float desired_error);
  87
  88 /* Group: Parameters */
  89
  90 /* Function: fann_get_cascade_output_change_fraction
  91
  92    The cascade output change fraction is a number between 0 and 1 determining how large a fraction
  93    the <fann_get_MSE> value should change within <fann_get_cascade_output_stagnation_epochs> during
  94    training of the output connections, in order for the training not to stagnate. If the training
  95    stagnates, the training of the output connections will be ended and new candidates will be prepared.
  96
  97    This means:
  98    If the MSE does not change by a fraction of <fann_get_cascade_output_change_fraction> during a
  99    period of <fann_get_cascade_output_stagnation_epochs>, the training of the output connections
 100    is stopped because the training has stagnated.
 101
 102    If the cascade output change fraction is low, the output connections will be trained more and if the
 103    fraction is high they will be trained less.
 104
 105    The default cascade output change fraction is 0.01, which is equalent to a 1% change in MSE.
 106
 107    See also:
 108                 <fann_set_cascade_output_change_fraction>, <fann_get_MSE>, <fann_get_cascade_output_stagnation_epochs>
 109
 110         This function appears in FANN >= 2.0.0.
 111  */
 112 FANN_EXTERNAL float FANN_API fann_get_cascade_output_change_fraction(struct fann *ann);
 113
 114
 115 /* Function: fann_set_cascade_output_change_fraction
 116
 117    Sets the cascade output change fraction.
 118
 119    See also:
 120                 <fann_get_cascade_output_change_fraction>
 121
 122         This function appears in FANN >= 2.0.0.
 123  */
 124 FANN_EXTERNAL void FANN_API fann_set_cascade_output_change_fraction(struct fann *ann,
 125                                                                                                                          float cascade_output_change_fraction);
 126
 127 /* Function: fann_get_cascade_output_stagnation_epochs
 128
 129    The number of cascade output stagnation epochs determines the number of epochs training is allowed to
 130    continue without changing the MSE by a fraction of <fann_get_cascade_output_change_fraction>.
 131
 132    See more info about this parameter in <fann_get_cascade_output_change_fraction>.
 133
 134    The default number of cascade output stagnation epochs is 12.
 135
 136    See also:
 137                 <fann_set_cascade_output_stagnation_epochs>, <fann_get_cascade_output_change_fraction>
 138
 139         This function appears in FANN >= 2.0.0.
 140  */
 141 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_output_stagnation_epochs(struct fann *ann);
 142
 143
 144 /* Function: fann_set_cascade_output_stagnation_epochs
 145
 146    Sets the number of cascade output stagnation epochs.
 147
 148    See also:
 149                 <fann_get_cascade_output_stagnation_epochs>
 150
 151         This function appears in FANN >= 2.0.0.
 152  */
 153 FANN_EXTERNAL void FANN_API fann_set_cascade_output_stagnation_epochs(struct fann *ann,
 154                                                                                                                          unsigned int cascade_output_stagnation_epochs);
 155
 156
 157 /* Function: fann_get_cascade_candidate_change_fraction
 158
 159    The cascade candidate change fraction is a number between 0 and 1 determining how large a fraction
 160    the <fann_get_MSE> value should change within <fann_get_cascade_candidate_stagnation_epochs> during
 161    training of the candidate neurons, in order for the training not to stagnate. If the training
 162    stagnates, the training of the candidate neurons will be ended and the best candidate will be selected.
 163
 164    This means:
 165    If the MSE does not change by a fraction of <fann_get_cascade_candidate_change_fraction> during a
 166    period of <fann_get_cascade_candidate_stagnation_epochs>, the training of the candidate neurons
 167    is stopped because the training has stagnated.
 168
 169    If the cascade candidate change fraction is low, the candidate neurons will be trained more and if the
 170    fraction is high they will be trained less.
 171
 172    The default cascade candidate change fraction is 0.01, which is equalent to a 1% change in MSE.
 173
 174    See also:
 175                 <fann_set_cascade_candidate_change_fraction>, <fann_get_MSE>, <fann_get_cascade_candidate_stagnation_epochs>
 176
 177         This function appears in FANN >= 2.0.0.
 178  */
 179 FANN_EXTERNAL float FANN_API fann_get_cascade_candidate_change_fraction(struct fann *ann);
 180
 181
 182 /* Function: fann_set_cascade_candidate_change_fraction
 183
 184    Sets the cascade candidate change fraction.
 185
 186    See also:
 187                 <fann_get_cascade_candidate_change_fraction>
 188
 189         This function appears in FANN >= 2.0.0.
 190  */
 191 FANN_EXTERNAL void FANN_API fann_set_cascade_candidate_change_fraction(struct fann *ann,
 192                                                                                                                          float cascade_candidate_change_fraction);
 193
 194 /* Function: fann_get_cascade_candidate_stagnation_epochs
 195
 196    The number of cascade candidate stagnation epochs determines the number of epochs training is allowed to
 197    continue without changing the MSE by a fraction of <fann_get_cascade_candidate_change_fraction>.
 198
 199    See more info about this parameter in <fann_get_cascade_candidate_change_fraction>.
 200
 201    The default number of cascade candidate stagnation epochs is 12.
 202
 203    See also:
 204                 <fann_set_cascade_candidate_stagnation_epochs>, <fann_get_cascade_candidate_change_fraction>
 205
 206         This function appears in FANN >= 2.0.0.
 207  */
 208 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_candidate_stagnation_epochs(struct fann *ann);
 209
 210
 211 /* Function: fann_set_cascade_candidate_stagnation_epochs
 212
 213    Sets the number of cascade candidate stagnation epochs.
 214
 215    See also:
 216                 <fann_get_cascade_candidate_stagnation_epochs>
 217
 218         This function appears in FANN >= 2.0.0.
 219  */
 220 FANN_EXTERNAL void FANN_API fann_set_cascade_candidate_stagnation_epochs(struct fann *ann,
 221                                                                                                                          unsigned int cascade_candidate_stagnation_epochs);
 222
 223
 224 /* Function: fann_get_cascade_weight_multiplier
 225
 226    The weight multiplier is a parameter which is used to multiply the weights from the candidate neuron
 227    before adding the neuron to the neural network. This parameter is usually between 0 and 1, and is used
 228    to make the training a bit less aggressive.
 229
 230    The default weight multiplier is 0.4
 231
 232    See also:
 233                 <fann_set_cascade_weight_multiplier>
 234
 235         This function appears in FANN >= 2.0.0.
 236  */
 237 FANN_EXTERNAL fann_type FANN_API fann_get_cascade_weight_multiplier(struct fann *ann);
 238
 239
 240 /* Function: fann_set_cascade_weight_multiplier
 241
 242    Sets the weight multiplier.
 243
 244    See also:
 245                 <fann_get_cascade_weight_multiplier>
 246
 247         This function appears in FANN >= 2.0.0.
 248  */
 249 FANN_EXTERNAL void FANN_API fann_set_cascade_weight_multiplier(struct fann *ann,
 250                                                                                                                          fann_type cascade_weight_multiplier);
 251
 252
 253 /* Function: fann_get_cascade_candidate_limit
 254
 255    The candidate limit is a limit for how much the candidate neuron may be trained.
 256    The limit is a limit on the proportion between the MSE and candidate score.
 257
 258    Set this to a lower value to avoid overfitting and to a higher if overfitting is
 259    not a problem.
 260
 261    The default candidate limit is 1000.0
 262
 263    See also:
 264                 <fann_set_cascade_candidate_limit>
 265
 266         This function appears in FANN >= 2.0.0.
 267  */
 268 FANN_EXTERNAL fann_type FANN_API fann_get_cascade_candidate_limit(struct fann *ann);
 269
 270
 271 /* Function: fann_set_cascade_candidate_limit
 272
 273    Sets the candidate limit.
 274
 275    See also:
 276                 <fann_get_cascade_candidate_limit>
 277
 278         This function appears in FANN >= 2.0.0.
 279  */
 280 FANN_EXTERNAL void FANN_API fann_set_cascade_candidate_limit(struct fann *ann,
 281                                                                                                                          fann_type cascade_candidate_limit);
 282
 283
 284 /* Function: fann_get_cascade_max_out_epochs
 285
 286    The maximum out epochs determines the maximum number of epochs the output connections
 287    may be trained after adding a new candidate neuron.
 288
 289    The default max out epochs is 150
 290
 291    See also:
 292                 <fann_set_cascade_max_out_epochs>
 293
 294         This function appears in FANN >= 2.0.0.
 295  */
 296 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_max_out_epochs(struct fann *ann);
 297
 298
 299 /* Function: fann_set_cascade_max_out_epochs
 300
 301    Sets the maximum out epochs.
 302
 303    See also:
 304                 <fann_get_cascade_max_out_epochs>
 305
 306         This function appears in FANN >= 2.0.0.
 307  */
 308 FANN_EXTERNAL void FANN_API fann_set_cascade_max_out_epochs(struct fann *ann,
 309                                                                                                                          unsigned int cascade_max_out_epochs);
 310
 311
 312 /* Function: fann_get_cascade_max_cand_epochs
 313
 314    The maximum candidate epochs determines the maximum number of epochs the input
 315    connections to the candidates may be trained before adding a new candidate neuron.
 316
 317    The default max candidate epochs is 150
 318
 319    See also:
 320                 <fann_set_cascade_max_cand_epochs>
 321
 322         This function appears in FANN >= 2.0.0.
 323  */
 324 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_max_cand_epochs(struct fann *ann);
 325
 326
 327 /* Function: fann_set_cascade_max_cand_epochs
 328
 329    Sets the max candidate epochs.
 330
 331    See also:
 332                 <fann_get_cascade_max_cand_epochs>
 333
 334         This function appears in FANN >= 2.0.0.
 335  */
 336 FANN_EXTERNAL void FANN_API fann_set_cascade_max_cand_epochs(struct fann *ann,
 337                                                                                                                          unsigned int cascade_max_cand_epochs);
 338
 339
 340 /* Function: fann_get_cascade_num_candidates
 341
 342    The number of candidates used during training (calculated by multiplying <fann_get_cascade_activation_functions_count>,
 343    <fann_get_cascade_activation_steepnesses_count> and <fann_get_cascade_num_candidate_groups>).
 344
 345    The actual candidates is defined by the <fann_get_cascade_activation_functions> and
 346    <fann_get_cascade_activation_steepnesses> arrays. These arrays define the activation functions
 347    and activation steepnesses used for the candidate neurons. If there are 2 activation functions
 348    in the activation function array and 3 steepnesses in the steepness array, then there will be
 349    2x3=6 different candidates which will be trained. These 6 different candidates can be copied into
 350    several candidate groups, where the only difference between these groups is the initial weights.
 351    If the number of groups is set to 2, then the number of candidate neurons will be 2x3x2=12. The
 352    number of candidate groups is defined by <fann_set_cascade_num_candidate_groups>.
 353
 354    The default number of candidates is 6x4x2 = 48
 355
 356    See also:
 357                 <fann_get_cascade_activation_functions>, <fann_get_cascade_activation_functions_count>,
 358                 <fann_get_cascade_activation_steepnesses>, <fann_get_cascade_activation_steepnesses_count>,
 359                 <fann_get_cascade_num_candidate_groups>
 360
 361         This function appears in FANN >= 2.0.0.
 362  */
 363 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_num_candidates(struct fann *ann);
 364
 365 /* Function: fann_get_cascade_activation_functions_count
 366
 367    The number of activation functions in the <fann_get_cascade_activation_functions> array.
 368
 369    The default number of activation functions is 6.
 370
 371    See also:
 372                 <fann_get_cascade_activation_functions>, <fann_set_cascade_activation_functions>
 373
 374         This function appears in FANN >= 2.0.0.
 375  */
 376 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_activation_functions_count(struct fann *ann);
 377
 378
 379 /* Function: fann_get_cascade_activation_functions
 380
 381    The cascade activation functions array is an array of the different activation functions used by
 382    the candidates.
 383
 384    See <fann_get_cascade_num_candidates> for a description of which candidate neurons will be
 385    generated by this array.
 386
 387    The default activation functions is {FANN_SIGMOID, FANN_SIGMOID_SYMMETRIC, FANN_GAUSSIAN, FANN_GAUSSIAN_SYMMETRIC, FANN_ELLIOT, FANN_ELLIOT_SYMMETRIC}
 388
 389    See also:
 390                 <fann_get_cascade_activation_functions_count>, <fann_set_cascade_activation_functions>,
 391                 <fann_activationfunc_enum>
 392
 393         This function appears in FANN >= 2.0.0.
 394  */
 395 FANN_EXTERNAL enum fann_activationfunc_enum * FANN_API fann_get_cascade_activation_functions(
 396                                                                                                                         struct fann *ann);
 397
 398
 399 /* Function: fann_set_cascade_activation_functions
 400
 401    Sets the array of cascade candidate activation functions. The array must be just as long
 402    as defined by the count.
 403
 404    See <fann_get_cascade_num_candidates> for a description of which candidate neurons will be
 405    generated by this array.
 406
 407    See also:
 408                 <fann_get_cascade_activation_steepnesses_count>, <fann_get_cascade_activation_steepnesses>
 409
 410         This function appears in FANN >= 2.0.0.
 411  */
 412 FANN_EXTERNAL void fann_set_cascade_activation_functions(struct fann *ann,
 413                                                                                                                  enum fann_activationfunc_enum *
 414                                                                                                                  cascade_activation_functions,
 415                                                                                                                  unsigned int
 416                                                                                                                  cascade_activation_functions_count);
 417
 418
 419 /* Function: fann_get_cascade_activation_steepnesses_count
 420
 421    The number of activation steepnesses in the <fann_get_cascade_activation_functions> array.
 422
 423    The default number of activation steepnesses is 4.
 424
 425    See also:
 426                 <fann_get_cascade_activation_steepnesses>, <fann_set_cascade_activation_functions>
 427
 428         This function appears in FANN >= 2.0.0.
 429  */
 430 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_activation_steepnesses_count(struct fann *ann);
 431
 432
 433 /* Function: fann_get_cascade_activation_steepnesses
 434
 435    The cascade activation steepnesses array is an array of the different activation functions used by
 436    the candidates.
 437
 438    See <fann_get_cascade_num_candidates> for a description of which candidate neurons will be
 439    generated by this array.
 440
 441    The default activation steepnesses is {0.25, 0.50, 0.75, 1.00}
 442
 443    See also:
 444                 <fann_set_cascade_activation_steepnesses>, <fann_get_cascade_activation_steepnesses_count>
 445
 446         This function appears in FANN >= 2.0.0.
 447  */
 448 FANN_EXTERNAL fann_type * FANN_API fann_get_cascade_activation_steepnesses(struct fann *ann);
 449
 450
 451 /* Function: fann_set_cascade_activation_steepnesses
 452
 453    Sets the array of cascade candidate activation steepnesses. The array must be just as long
 454    as defined by the count.
 455
 456    See <fann_get_cascade_num_candidates> for a description of which candidate neurons will be
 457    generated by this array.
 458
 459    See also:
 460                 <fann_get_cascade_activation_steepnesses>, <fann_get_cascade_activation_steepnesses_count>
 461
 462         This function appears in FANN >= 2.0.0.
 463  */
 464 FANN_EXTERNAL void fann_set_cascade_activation_steepnesses(struct fann *ann,
 465                                                                                                                    fann_type *
 466                                                                                                                    cascade_activation_steepnesses,
 467                                                                                                                    unsigned int
 468                                                                                                                    cascade_activation_steepnesses_count);
 469
 470 /* Function: fann_get_cascade_num_candidate_groups
 471
 472    The number of candidate groups is the number of groups of identical candidates which will be used
 473    during training.
 474
 475    This number can be used to have more candidates without having to define new parameters for the candidates.
 476
 477    See <fann_get_cascade_num_candidates> for a description of which candidate neurons will be
 478    generated by this parameter.
 479
 480    The default number of candidate groups is 2
 481
 482    See also:
 483                 <fann_set_cascade_num_candidate_groups>
 484
 485         This function appears in FANN >= 2.0.0.
 486  */
 487 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_num_candidate_groups(struct fann *ann);
 488
 489
 490 /* Function: fann_set_cascade_num_candidate_groups
 491
 492    Sets the number of candidate groups.
 493
 494    See also:
 495                 <fann_get_cascade_num_candidate_groups>
 496
 497         This function appears in FANN >= 2.0.0.
 498  */
 499 FANN_EXTERNAL void FANN_API fann_set_cascade_num_candidate_groups(struct fann *ann,
 500                                                                                                                          unsigned int cascade_num_candidate_groups);
 501
 502
 503 #endif