1 /* 2 Fast Artificial Neural Network Library (fann) 3 Copyright (C) 2003-2012 Steffen Nissen (sn@leenissen.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_output_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_min_out_epochs 313 314 The minimum out epochs determines the minimum number of epochs the output connections 315 must be trained after adding a new candidate neuron. 316 317 The default min out epochs is 50 318 319 See also: 320 <fann_set_cascade_min_out_epochs> 321 322 This function appears in FANN >= 2.2.0. 323 */ 324 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_min_out_epochs(struct fann *ann); 325 326 327 /* Function: fann_set_cascade_min_out_epochs 328 329 Sets the minimum out epochs. 330 331 See also: 332 <fann_get_cascade_min_out_epochs> 333 334 This function appears in FANN >= 2.2.0. 335 */ 336 FANN_EXTERNAL void FANN_API fann_set_cascade_min_out_epochs(struct fann *ann, 337 unsigned int cascade_min_out_epochs); 338 339 /* Function: fann_get_cascade_max_cand_epochs 340 341 The maximum candidate epochs determines the maximum number of epochs the input 342 connections to the candidates may be trained before adding a new candidate neuron. 343 344 The default max candidate epochs is 150 345 346 See also: 347 <fann_set_cascade_max_cand_epochs> 348 349 This function appears in FANN >= 2.0.0. 350 */ 351 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_max_cand_epochs(struct fann *ann); 352 353 354 /* Function: fann_set_cascade_max_cand_epochs 355 356 Sets the max candidate epochs. 357 358 See also: 359 <fann_get_cascade_max_cand_epochs> 360 361 This function appears in FANN >= 2.0.0. 362 */ 363 FANN_EXTERNAL void FANN_API fann_set_cascade_max_cand_epochs(struct fann *ann, 364 unsigned int cascade_max_cand_epochs); 365 366 367 /* Function: fann_get_cascade_min_cand_epochs 368 369 The minimum candidate epochs determines the minimum number of epochs the input 370 connections to the candidates may be trained before adding a new candidate neuron. 371 372 The default min candidate epochs is 50 373 374 See also: 375 <fann_set_cascade_min_cand_epochs> 376 377 This function appears in FANN >= 2.2.0. 378 */ 379 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_min_cand_epochs(struct fann *ann); 380 381 382 /* Function: fann_set_cascade_min_cand_epochs 383 384 Sets the min candidate epochs. 385 386 See also: 387 <fann_get_cascade_min_cand_epochs> 388 389 This function appears in FANN >= 2.2.0. 390 */ 391 FANN_EXTERNAL void FANN_API fann_set_cascade_min_cand_epochs(struct fann *ann, 392 unsigned int cascade_min_cand_epochs); 393 394 /* Function: fann_get_cascade_num_candidates 395 396 The number of candidates used during training (calculated by multiplying <fann_get_cascade_activation_functions_count>, 397 <fann_get_cascade_activation_steepnesses_count> and <fann_get_cascade_num_candidate_groups>). 398 399 The actual candidates is defined by the <fann_get_cascade_activation_functions> and 400 <fann_get_cascade_activation_steepnesses> arrays. These arrays define the activation functions 401 and activation steepnesses used for the candidate neurons. If there are 2 activation functions 402 in the activation function array and 3 steepnesses in the steepness array, then there will be 403 2x3=6 different candidates which will be trained. These 6 different candidates can be copied into 404 several candidate groups, where the only difference between these groups is the initial weights. 405 If the number of groups is set to 2, then the number of candidate neurons will be 2x3x2=12. The 406 number of candidate groups is defined by <fann_set_cascade_num_candidate_groups>. 407 408 The default number of candidates is 6x4x2 = 48 409 410 See also: 411 <fann_get_cascade_activation_functions>, <fann_get_cascade_activation_functions_count>, 412 <fann_get_cascade_activation_steepnesses>, <fann_get_cascade_activation_steepnesses_count>, 413 <fann_get_cascade_num_candidate_groups> 414 415 This function appears in FANN >= 2.0.0. 416 */ 417 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_num_candidates(struct fann *ann); 418 419 /* Function: fann_get_cascade_activation_functions_count 420 421 The number of activation functions in the <fann_get_cascade_activation_functions> array. 422 423 The default number of activation functions is 6. 424 425 See also: 426 <fann_get_cascade_activation_functions>, <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_functions_count(struct fann *ann); 431 432 433 /* Function: fann_get_cascade_activation_functions 434 435 The cascade activation functions 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 functions is {FANN_SIGMOID, FANN_SIGMOID_SYMMETRIC, FANN_GAUSSIAN, FANN_GAUSSIAN_SYMMETRIC, FANN_ELLIOT, FANN_ELLIOT_SYMMETRIC} 442 443 See also: 444 <fann_get_cascade_activation_functions_count>, <fann_set_cascade_activation_functions>, 445 <fann_activationfunc_enum> 446 447 This function appears in FANN >= 2.0.0. 448 */ 449 FANN_EXTERNAL enum fann_activationfunc_enum * FANN_API fann_get_cascade_activation_functions( 450 struct fann *ann); 451 452 453 /* Function: fann_set_cascade_activation_functions 454 455 Sets the array of cascade candidate activation functions. The array must be just as long 456 as defined by the count. 457 458 See <fann_get_cascade_num_candidates> for a description of which candidate neurons will be 459 generated by this array. 460 461 See also: 462 <fann_get_cascade_activation_steepnesses_count>, <fann_get_cascade_activation_steepnesses> 463 464 This function appears in FANN >= 2.0.0. 465 */ 466 FANN_EXTERNAL void FANN_API fann_set_cascade_activation_functions(struct fann *ann, 467 enum fann_activationfunc_enum * 468 cascade_activation_functions, 469 unsigned int 470 cascade_activation_functions_count); 471 472 473 /* Function: fann_get_cascade_activation_steepnesses_count 474 475 The number of activation steepnesses in the <fann_get_cascade_activation_functions> array. 476 477 The default number of activation steepnesses is 4. 478 479 See also: 480 <fann_get_cascade_activation_steepnesses>, <fann_set_cascade_activation_functions> 481 482 This function appears in FANN >= 2.0.0. 483 */ 484 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_activation_steepnesses_count(struct fann *ann); 485 486 487 /* Function: fann_get_cascade_activation_steepnesses 488 489 The cascade activation steepnesses array is an array of the different activation functions used by 490 the candidates. 491 492 See <fann_get_cascade_num_candidates> for a description of which candidate neurons will be 493 generated by this array. 494 495 The default activation steepnesses is {0.25, 0.50, 0.75, 1.00} 496 497 See also: 498 <fann_set_cascade_activation_steepnesses>, <fann_get_cascade_activation_steepnesses_count> 499 500 This function appears in FANN >= 2.0.0. 501 */ 502 FANN_EXTERNAL fann_type * FANN_API fann_get_cascade_activation_steepnesses(struct fann *ann); 503 504 505 /* Function: fann_set_cascade_activation_steepnesses 506 507 Sets the array of cascade candidate activation steepnesses. The array must be just as long 508 as defined by the count. 509 510 See <fann_get_cascade_num_candidates> for a description of which candidate neurons will be 511 generated by this array. 512 513 See also: 514 <fann_get_cascade_activation_steepnesses>, <fann_get_cascade_activation_steepnesses_count> 515 516 This function appears in FANN >= 2.0.0. 517 */ 518 FANN_EXTERNAL void FANN_API fann_set_cascade_activation_steepnesses(struct fann *ann, 519 fann_type * 520 cascade_activation_steepnesses, 521 unsigned int 522 cascade_activation_steepnesses_count); 523 524 /* Function: fann_get_cascade_num_candidate_groups 525 526 The number of candidate groups is the number of groups of identical candidates which will be used 527 during training. 528 529 This number can be used to have more candidates without having to define new parameters for the candidates. 530 531 See <fann_get_cascade_num_candidates> for a description of which candidate neurons will be 532 generated by this parameter. 533 534 The default number of candidate groups is 2 535 536 See also: 537 <fann_set_cascade_num_candidate_groups> 538 539 This function appears in FANN >= 2.0.0. 540 */ 541 FANN_EXTERNAL unsigned int FANN_API fann_get_cascade_num_candidate_groups(struct fann *ann); 542 543 544 /* Function: fann_set_cascade_num_candidate_groups 545 546 Sets the number of candidate groups. 547 548 See also: 549 <fann_get_cascade_num_candidate_groups> 550 551 This function appears in FANN >= 2.0.0. 552 */ 553 FANN_EXTERNAL void FANN_API fann_set_cascade_num_candidate_groups(struct fann *ann, 554 unsigned int cascade_num_candidate_groups); 555 556 557 #endif 558