You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.md 5.6KB

3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154
  1. [![Build Status](https://travis-ci.org/codeplea/genann.svg?branch=master)](https://travis-ci.org/codeplea/genann)
  2. <img alt="Genann logo" src="https://codeplea.com/public/content/genann_logo.png" align="right" />
  3. # Genann
  4. Genann is a minimal, well-tested library for training and using feedforward
  5. artificial neural networks (ANN) in C. Its primary focus is on being simple,
  6. fast, reliable, and hackable. It achieves this by providing only the necessary
  7. functions and little extra.
  8. ## Features
  9. - **ANSI C with no dependencies**.
  10. - Contained in a single source code and header file.
  11. - Simple.
  12. - Fast and thread-safe.
  13. - Easily extendible.
  14. - Implements backpropagation training.
  15. - *Compatible with alternative training methods* (classic optimization, genetic algorithms, etc)
  16. - Includes examples and test suite.
  17. - Released under the zlib license - free for nearly any use.
  18. ## Building
  19. Genann is self-contained in two files: `genann.c` and `genann.h`. To use Genann, simply add those two files to your project.
  20. ## Example Code
  21. Four example programs are included with the source code.
  22. - [`example1.c`](./example1.c) - Trains an ANN on the XOR function using backpropagation.
  23. - [`example2.c`](./example2.c) - Trains an ANN on the XOR function using random search.
  24. - [`example3.c`](./example3.c) - Loads and runs an ANN from a file.
  25. - [`example4.c`](./example4.c) - Trains an ANN on the [IRIS data-set](https://archive.ics.uci.edu/ml/datasets/Iris) using backpropagation.
  26. ## Quick Example
  27. We create an ANN taking 2 inputs, having 1 layer of 3 hidden neurons, and
  28. providing 2 outputs. It has the following structure:
  29. ![NN Example Structure](./doc/e1.png)
  30. We then train it on a set of labeled data using backpropagation and ask it to
  31. predict on a test data point:
  32. ```C
  33. #include "genann.h"
  34. /* Not shown, loading your training and test data. */
  35. double **training_data_input, **training_data_output, **test_data_input;
  36. /* New network with 2 inputs,
  37. * 1 hidden layer of 3 neurons each,
  38. * and 2 outputs. */
  39. genann *ann = genann_init(2, 1, 3, 2);
  40. /* Learn on the training set. */
  41. for (i = 0; i < 300; ++i) {
  42. for (j = 0; j < 100; ++j)
  43. genann_train(ann, training_data_input[j], training_data_output[j], 0.1);
  44. }
  45. /* Run the network and see what it predicts. */
  46. double const *prediction = genann_run(ann, test_data_input[0]);
  47. printf("Output for the first test data point is: %f, %f\n", prediction[0], prediction[1]);
  48. genann_free(ann);
  49. ```
  50. This example is to show API usage, it is not showing good machine learning
  51. techniques. In a real application you would likely want to learn on the test
  52. data in a random order. You would also want to monitor the learning to prevent
  53. over-fitting.
  54. ## Usage
  55. ### Creating and Freeing ANNs
  56. ```C
  57. genann *genann_init(int inputs, int hidden_layers, int hidden, int outputs);
  58. genann *genann_copy(genann const *ann);
  59. void genann_free(genann *ann);
  60. ```
  61. Creating a new ANN is done with the `genann_init()` function. Its arguments
  62. are the number of inputs, the number of hidden layers, the number of neurons in
  63. each hidden layer, and the number of outputs. It returns a `genann` struct pointer.
  64. Calling `genann_copy()` will create a deep-copy of an existing `genann` struct.
  65. Call `genann_free()` when you're finished with an ANN returned by `genann_init()`.
  66. ### Training ANNs
  67. ```C
  68. void genann_train(genann const *ann, double const *inputs,
  69. double const *desired_outputs, double learning_rate);
  70. ```
  71. `genann_train()` will preform one update using standard backpropogation. It
  72. should be called by passing in an array of inputs, an array of expected outputs,
  73. and a learning rate. See *example1.c* for an example of learning with
  74. backpropogation.
  75. A primary design goal of Genann was to store all the network weights in one
  76. contigious block of memory. This makes it easy and efficient to train the
  77. network weights using direct-search numeric optimizion algorthims,
  78. such as [Hill Climbing](https://en.wikipedia.org/wiki/Hill_climbing),
  79. [the Genetic Algorithm](https://en.wikipedia.org/wiki/Genetic_algorithm), [Simulated
  80. Annealing](https://en.wikipedia.org/wiki/Simulated_annealing), etc.
  81. These methods can be used by searching on the ANN's weights directly.
  82. Every `genann` struct contains the members `int total_weights;` and
  83. `double *weight;`. `*weight` points to an array of `total_weights`
  84. size which contains all weights used by the ANN. See *example2.c* for
  85. an example of training using random hill climbing search.
  86. ### Saving and Loading ANNs
  87. ```C
  88. genann *genann_read(FILE *in);
  89. void genann_write(genann const *ann, FILE *out);
  90. ```
  91. Genann provides the `genann_read()` and `genann_write()` functions for loading or saving an ANN in a text-based format.
  92. ### Evaluating
  93. ```C
  94. double const *genann_run(genann const *ann, double const *inputs);
  95. ```
  96. Call `genann_run()` on a trained ANN to run a feed-forward pass on a given set of inputs. `genann_run()`
  97. will provide a pointer to the array of predicted outputs (of `ann->outputs` length).
  98. ## Hints
  99. - All functions start with `genann_`.
  100. - The code is simple. Dig in and change things.
  101. ## Extra Resources
  102. The [comp.ai.neural-nets
  103. FAQ](http://www.faqs.org/faqs/ai-faq/neural-nets/part1/) is an excellent
  104. resource for an introduction to artificial neural networks.
  105. If you need an even smaller neural network library, check out the excellent single-hidden-layer library [tinn](https://github.com/glouw/tinn).
  106. If you're looking for a heavier, more opinionated neural network library in C,
  107. I recommend the [FANN library](http://leenissen.dk/fann/wp/). Another
  108. good library is Peter van Rossum's [Lightweight Neural
  109. Network](http://lwneuralnet.sourceforge.net/), which despite its name, is
  110. heavier and has more features than Genann.