# Neat-Ex
This [Elixir](http://elixir-lang.org/) library provides the means to define, simulate, and serialize Artificial-Neural-Networks (ANNs), as well as the means to develop them through use of the Neuro-Evolution of Augmenting Toplogies algorithm ([NEAT](http://nn.cs.utexas.edu/downloads/papers/stanley.ec02.pdf)), back-propogation, or gradient approximation.
NEAT, unlike back-propogation, develops both topology and neural weights. It trains using a fitness function instead of just training data. The gradient approximation algorithm is like back-propogation, in that it uses gradient optimization, but instead of calculating the exact gradient using the training data, it approximates the gradient using a training function.
Training functions instead of training data allow for more flexibility.
## Installation
### Add as a dependency
Add `{:neat_ex, "~> 1.2.1"}` to your list of deps in your mix file, then run `mix deps.get`.
### Or clone a copy
To clone and install, do:
git clone https://gitlab.com/onnoowl/Neat-Ex.git
cd Neat-Ex
mix deps.get
## Documentation
For details, the latest documentation can be found at http://hexdocs.pm/neat_ex/index.html. For example usage, see the example below.
## News
### New in Version 1.2.1
* IDs are now generated using a hash (SipHash). This is vastly more memory efficient, as IDs will only ever by 64 bits. Collisions should be unlikely, and the system is incredibly resistant to collisions if it does happen.
### New in Version 1.2.0
* Updated to Elixir 1.4
* Corrected algorithm to randomly re-assign species representative each iteration
* IDs are generated without cantor's pairing function, using simple tuples instead. This is a little more memory efficient
### New in Version 1.1.0
This library is expanding to feature more neural training algorithms.
* Updated to Elixir 1.2 and shifted from Dicts and Sets to Maps and MapSets
* Added the [`Backprop`](http://hexdocs.pm/neat_ex/Backprop.html) module for back-propogation
* Added the [`GradAprox`](http://hexdocs.pm/neat_ex/GradAprox.html) module for gradient approximation and optimization of generic parameters
* Added the [`GradAprox.NeuralTrainer`](http://hexdocs.pm/neat_ex/GradAprox.NeuralTrainer.html) module for gradient approximation and optimization of neural networks
#### Backprop vs GradAprox.NeuralTrainer
For training with a dataset, using the Backprop module is preferable. If the problem only allows for a fitness/error function, then GradAprox.NeuralTrainer should be used. This module approximates gradients instead of precisely calculating them by modifying weights slightly and than re-evaluating the fitness function.
See each module's documentation for more details and example usage.
### (Potential) Upcoming Features
* Newton's Method for gradient optimization
* Back-propogation through time (BPTT) and automated neural network unfolding
## Neat Example Usage
Here's a simple example that shows how to setup an evolution that evolves neural networks to act like binary XORs, where -1s are like 0s (and 1s are still 1s). The expected behavior is listed in `dataset`, and neural networks are assigned a fitness based on how close to the expected behavior they come. After 50 or so generations, or 10 seconds of computation, the networks exhibit the expected behavior.
```elixir
#################
# Training data #
#################
dataset = [{{-1, -1}, -1}, {{1, -1}, 1}, {{-1, 1}, 1}, {{1, 1}, -1}] #{{in1, in2} output} -> the expected behavior
####################
# Fitness function #
####################
fitness = fn ann ->
sim = Ann.Simulation.new(ann)
error = Enum.reduce dataset, 0, fn {{in1, in2}, out}, error ->
#We'll use 1 and 2 as input neurons, and we'll use 3 as a bias (it will always be given a value of 1.0)
inputs = %{1 => in1, 2 => in2, 3 => 1.0}
#Then we'll evaluate a simulation with these given inputs
evaled_sim = Ann.Simulation.eval(sim, inputs)
#Then we'll get the output of the 4th neuron, which is our output
result = Map.fetch!(evaled_sim.data, 4)
#Then we'll add the distance between the result and the expected output to the accumulated error
error + abs(result - out)
end
#We're supposed to return fitness (where greater values are better) instead of error (where greater values are worse).
#The maximum our error can be is 8, so we return (8 - error)^2 as our fitness.
:math.pow(8 - error, 2)
#The range of output for all neurons is -1 to positive 1. This means the furthest away the output
#can ever be from the correct answer is 2. Since our dataset is of size 4, this means the maximum
#error is 4*2 = 8
#Doing 8 - error gives us a fitness value instead of an error value, because higher values are better.
#Finally, we square the result, which is good practice.
end
######################
# Training the model #
######################
#To specify the inputs and outputs, we make a seed_ann. This will be how all the ANNs will start.
#Make a new network with inputs [1, 2, 3], and outputs [4], and use Ann.connectAll to connect
#all of the inputs to the outputs for us. This way it will start with some topology.
seed_ann = Ann.new([1, 2, 3], [4]) |> Ann.connectAll
#Make a new neat struct with this seed_ann and our fitness function
neat = Neat.new_single_fitness(seed_ann, fitness)
#Then evolve it until it reaches fitness level 63 (this fitness's function's max fitness is 64).
{ann, fitness} = Neat.evolveUntil(neat, 63).best
IO.puts Ann.json(ann) #display a json representation of the ANN.
###################
# Using the model #
###################
#We can then try out the produced ANN ourselves by making a simulation
simulation = ann
|> Ann.Simulation.new
|> Ann.Simulation.eval(%{1 => 1.0, 2 => 1.0, 3 => 1.0})
IO.inspect simulation.data[4] #in our example, the output is at neuron #4
```
### XOR
mix xor.single
This command runs the sample xor code, evolving a neural network to act as an XOR logic gate. The resulting network can be viewed visually by running the command `./render xor`, and then by opening `xor.png`. Rendering depends on GraphViz, and having the command `dot` in your path.
### FishSim
mix fishsim [display_every] [minutes_to_run]
This evolves neural networks to act like fish, and to run away from a shark. Fitness is based on how long fish can survive the shark. It will display ascii art demonstrating the simulation, where the @ sign is the shark, and the digits represent the fish, and the concentration at that specific location (higher numbers show a higher relative concentration of fish).
The evolution will only print out every `display_every` generations (default 1, meaning every generation). Setting it to 5, for example, will evolve for 5 generations between each display (which is far faster).
The evolution lasts `minutes_to_run` minutes (default is 60).
mix fishsim [display_every] [minutes_to_run] [file_to_record_to]
By including a file name, the simulation will record visualization data to the file rather than displaying ascii art. `display_every` becomes handy for limiting the size of the visualization file. To view the recording after it's made, use Jonathan's project found [here](https://gitlab.com/Zanthos/FishSimVisualAid), and pass the file as the first argument.
When the process finishes, you can view the best fish using `./render bestFish`, and then by opening `bestFish.png`
## Testing (for contributors)
mix test
