rubyneat 0.4.0.alpha.4 → 0.4.0.alpha.5

data/_site/index.md

@@ -0,0 +1,444 @@
+<div id="table-of-contents">
+<h2>Table of Contents</h2>
+<div id="text-table-of-contents">
+<ul>
+<li><a href="#orgheadline42">1. RubyNEAT &#x2013; Ruby implementation of Neural Evolution of Augmenting Topologies (NEAT)</a>
+<ul>
+<li><a href="#orgheadline1">1.1. What is NEAT?</a></li>
+<li><a href="#orgheadline2">1.2. What is RubyNEAT?</a></li>
+<li><a href="#orgheadline9">1.3. Architecture</a>
+<ul>
+<li><a href="#orgheadline3">1.3.1. Controller</a></li>
+<li><a href="#orgheadline4">1.3.2. Evolver</a></li>
+<li><a href="#orgheadline5">1.3.3. Expressor</a></li>
+<li><a href="#orgheadline6">1.3.4. Evaluator</a></li>
+<li><a href="#orgheadline7">1.3.5. Population</a></li>
+<li><a href="#orgheadline8">1.3.6. Critter</a></li>
+</ul>
+</li>
+<li><a href="#orgheadline11">1.4. Installation</a>
+<ul>
+<li><a href="#orgheadline10">1.4.1. Requirements</a></li>
+</ul>
+</li>
+<li><a href="#orgheadline15">1.5. Examples</a>
+<ul>
+<li><a href="#orgheadline14">1.5.1. Note Well</a></li>
+</ul>
+</li>
+<li><a href="#orgheadline41">1.6. RubyNEAT DSL</a>
+<ul>
+<li><a href="#orgheadline34">1.6.1. The XOR Neater Example</a></li>
+<li><a href="#orgheadline40">1.6.2. Releases</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+
+&#x2014;
+layout: default
+title: RubyNEAT
+&#x2014;
+
+# RubyNEAT &#x2013; Ruby implementation of Neural Evolution of Augmenting Topologies (NEAT)<a id="orgheadline42"></a>
+
+## What is NEAT?<a id="orgheadline1"></a>
+
+NEAT is an acronym for Neural Evolution of Augmenting Topologies.
+In short, neural nets that are evolved from a minimal topology,
+allowing selection to decide on what topologies are most adequate
+for resolving the problem at hand.
+
+## What is RubyNEAT?<a id="orgheadline2"></a>
+
+RubyNEAT is the world's first (and currently only) implementation
+of the NEAT algorithm in the Ruby programming language. RubyNEAT
+leverages some of the benefits of Ruby, such as metaprogramming,
+to implement activation of the Neural Net.
+
+Basically, the Neural Nets in RubyNEAT manifests themselves in the
+Phenotypes as functional programs &#x2013; of a sort. You may think of it
+as an application of Genetic Programming techniques to resolving the
+NEAT algorithm. As such, once fit Critters (neural nets) are found,
+they may be extracted as pure Ruby code, not needing the
+RubyNEAT engine for activation.
+
+## Architecture<a id="orgheadline9"></a>
+
+RubyNEAT comprises many interacting modules. While it is
+not strictly necessary to understand RubyNEAT at this level
+of detail, it would be beneficial for a number of reasons,
+especially in understanding how to tweak the parameters
+to improve performance for your application. 
+
+RubyNEAT comprises the following modules: 
+Controller, Expressor, Evaluator, Evolver, Population, and Critter.
+
+### Controller<a id="orgheadline3"></a>
+
+The Controller mediates all aspects of RubyNEAT
+evolution, the various modules involved and their
+interactions, and also holds the settings the other
+modules will refer to. 
+
+The Controller is singular. There can only be one
+Controller in the RubyNEAT system. All other objects
+associated with the Controller shall have embedded
+in them a reference to their controller.
+
+### Evolver<a id="orgheadline4"></a>
+
+The Evolver module houses the evolving algorithms
+for RubyNEAT. It evolves the entire Population of Critters.
+
+### Expressor<a id="orgheadline5"></a>
+
+The Expressor module is responsible for interpreting
+the Genotype of the Critters and creating their
+Phenotypes. The default Expressor generates Ruby code
+and attaches that code to the Phenotype instances of the Critter. 
+
+It is entirely possible to swap in a different Expressor and
+generate code for a different target language, or create some 
+other construct. There is no limit to what you could
+have an Expressor do.
+
+### Evaluator<a id="orgheadline6"></a>
+
+The Evaluator is a kind of bridge between the inner "biology" of the RubyNEAT "ecosystem" and the outside world. It has ties to the RubyNEAT DSL where you encode your own fitness functions and data links to some external problem space. It is, in a sense, the "gateway".
+
+### Population<a id="orgheadline7"></a>
+
+The Population is what your intuition tells you. It is a environment that houses a collection of Critters. 
+
+### Critter<a id="orgheadline8"></a>
+
+The Critter is the embodiment of both the genetics for the neural net and also the expression of the same. It contains, in other words, the Genotype and the Phenotype.
+
+Critters are mated through the Evolver, and have their genes expressed through the Expressor. 
+
+## Installation<a id="orgheadline11"></a>
+
+You may install RubyNEAT by cloning the repo at GitHub:
+[RubyNEAT Github](https://github.com/flajann2/rubyneat)
+
+Or you may get it via a gem
+
+    gem install rubyneat --pre
+
+### Requirements<a id="orgheadline10"></a>
+
+You will need at least Ruby 2.0.0, though we strongly recommend 2.1.1
+or better. We will NOT be supporting 1.9.x,
+as that is being phased out anyway.
+
+## Examples<a id="orgheadline15"></a>
+
+Clone:
+
+    git clone git@github.com:flajann2/rubyneat_examples.git
+
+and cd into the '''rubyneat<sub>examples</sub>''' directory. 
+
+Type: 
+
+    neat list neaters
+
+to get a list of neaters. To run one like, say, the XOR test:
+
+    neat run xor
+
+### Note Well<a id="orgheadline14"></a>
+
+The pole-balancing invpend neater is still under
+development. It will display a window with the cart and pole,
+but will not balance yet. Just a matter of me 
+finishing up that code. All the others work.
+
+1.  RubyNEAT
+
+    -   GitHUB
+        [RubyNEAT GitHub](https://github.com/flajann2/rubyneat)
+    
+    -   Ruby GEM
+        
+            gem install rubyneat --pre
+
+2.  RubyNEAT Examples
+
+    -   Github
+        [Example Neaters on GitHub](https://github.com/flajann2/rubyneat_examples)
+
+## RubyNEAT DSL<a id="orgheadline41"></a>
+
+I will take the '''XOR''' neater and document it.
+This is not the perfect way to go,
+but I will get more extensive later.
+
+### The XOR Neater Example<a id="orgheadline34"></a>
+
+    require 'xor'
+    include NEAT::DSL
+
+-   The first lines here includes the special XOR library, which is basically:
+
+    def xor(*inp)
+      inp.map{|n| (n > 0) ? 1 : 0}.reduce {|p, i| p + ((i > 0) ? 1 : 0) } == 1
+    end
+
+-Basic settings for the '''XOR''', which can handle more than 2 inputs.
+
+    XOR_INPUTS = 2
+    XOR_STATES = 2 ** XOR_INPUTS
+    MAX_FIT    = XOR_STATES
+    ALMOST_FIT = XOR_STATES - 0.5
+
+-   The actual definition of the Neater. Here you specify the parameters RubyNEAT
+    will use to run the evolution, as well as the CPPN neuron types, the fitness function,
+    etc.
+
+    define "XOR System" do
+
+-   Inputs defined as name: Neuron, name: Neuron &#x2026; hash. In this segment, we
+    create a block to generate the hash since we can have a variable number of
+    inputs to the XOR. The input names must be unique. Note that a bias neuron
+    is also supplied, and it is always called :bias.
+
+    inputs {
+      cinv = Hash[(1..XOR_INPUTS).map{|i| [("i%s" % i).to_sym, InputNeuron]}]
+      cinv[:bias] = BiasNeuron
+      cinv
+    }
+
+-   Outputs are defined in a similar fashion to the inputs. The names of all the 
+    output neurons must be unique. Here in this example we only have one output, and
+    we use the hyperbolic tan Neuron as the output. There is also a sigmoid Neuron
+    that could be used as well, but the input levels would have to be conditioned
+    to vary from 0 to 1 instead of from -1 to one.
+
+    outputs out: TanhNeuron
+
+-   Hidden neuron specification is optional. 
+    The names given here are largely meaningless, but but follow the same rules
+    for uniqueness. The neurons specified will be selected randomly as the topologies
+    are augmented.
+
+    hidden tan: TanhNeuron
+
+1.  Settings
+
+    For RubyNEAT. Extensive documentation will be provided on a later date
+    as to the meanings, which closely follow the parameters for Ken Stanley's NEAT
+    implementation.
+    
+    1.  General
+    
+            hash_on_fitness false
+            start_population_size 30
+            population_size 30
+            max_generations 10000
+            max_population_history 10
+    
+    2.  Evolver probabilities and SDs
+    
+        Perturbations
+        
+            mutate_perturb_gene_weights_prob 0.10
+            mutate_perturb_gene_weights_sd 0.25
+    
+    3.  Complete Change of weight
+    
+            mutate_change_gene_weights_prob 0.10
+            mutate_change_gene_weights_sd 1.00
+    
+    4.  Adding new neurons and genes
+    
+            mutate_add_neuron_prob 0.05
+            mutate_add_gene_prob 0.20
+    
+    5.  Switching genes on and off
+    
+            mutate_gene_disable_prob 0.01
+            mutate_gene_reenable_prob 0.01
+            
+            interspecies_mate_rate 0.03
+            mate_only_prob 0.10 *0.7
+    
+    6.  Mating
+    
+            survival_threshold 0.20 # top % allowed to mate in a species.
+            survival_mininum_per_species  4 # for small populations, we need SOMETHING to go on.
+    
+    7.  Fitness costs
+    
+            fitness_cost_per_neuron 0.00001
+            fitness_cost_per_gene   0.00001
+    
+    8.  Speciation
+    
+            compatibility_threshold 2.5
+            disjoint_coefficient 0.6
+            excess_coefficient 0.6
+            weight_coefficient 0.2
+            max_species 20
+            dropoff_age 15
+            smallest_species 5
+    
+    9.  Sequencing
+    
+        The evaluation function is called repeatedly, and each iteration is given a
+        monotonically increasing integer which represents the sequence number. The results
+        of each run is returned, and those results are evaluated elsewhere in the Neater.
+        
+            start_sequence_at 0
+            end_sequence_at 2 ** XOR_INPUTS - 1
+
+2.  The Evolution Block
+
+        evolve do
+    
+    1.  The Query Block
+    
+        This query shall return a vector result that will serve
+        as the inputs to the critter. 
+        
+            query { |seq|
+              * We'll use the seq to create the xor sequences via
+              * the least signficant bits.
+              condition_boolean_vector (0 ... XOR_INPUTS).map{|i| (seq & (1 << i)) != 0}
+            }
+    
+    2.  The Compare Block
+    
+        Compare the fitness of two critters. We may choose a different ordering here.
+        
+            compare {|f1, f2| f2 <=> f1 }
+    
+    3.  The Cost of Fitness Block
+    
+        Here we integrate the cost with the fitness.
+        
+            cost { |fitvec, cost|
+              fit = XOR_STATES - fitvec.reduce {|a,r| a+r} - cost
+              $log.debug ">>>>>>> fitvec *{fitvec} => *{fit}, cost *{cost}"
+              fit
+            }
+    
+    4.  The Fitness Block
+    
+        The fitness block is called for each activation and is given the input vector,
+        the output vector, and the sequence number given to the query. The results are
+        evaluated and a fitness scalar is returned.
+        
+        \#+BEGIN<sub>SRC</sub> ruby
+          fitness { |vin, vout, seq|
+            unless vout **\*** :error
+              bin = uncondition<sub>boolean</sub><sub>vector</sub> vin
+              bout = uncondition<sub>boolean</sub><sub>vector</sub> vout
+              bactual = [xor(\*vin)]
+              vactual = condition<sub>boolean</sub><sub>vector</sub> bactual
+              fit = (bout **\*** bactual) ? 0.00 : 1.00
+              **simple<sub>fitness</sub><sub>error</sub>(vout, vactual.map{|f| f \* 0.50 })
+              bfit = (bout \*\*** bactual) ? 'T' : 'F'
+              fit
+            else
+              $log.debug "Error on \*{vin} [\*{seq}]"
+              1.0
+            end
+          }
+        \\#+ END<sub>SRC</sub>
+    
+    5.  The Termination Condition
+    
+        When the desired fitness level is reached, you may want to end the
+        Neater run. If so, provide a block to do just that.
+        
+              stop_on_fitness { |fitness, c|
+                puts "*** Generation Run *{c.generation_num}, best is *{fitness[:best]} ***\n\n"
+                fitness[:best] >= ALMOST_FIT
+              }
+            end
+
+3.  Report Generating Block
+
+    This particular report block just adds something to the log. You could easily
+    replace that with a visual update if you like, etc.
+    
+        report do |rept|
+          $log.info "REPORT *{rept.to_yaml}"
+        end
+
+4.  Engine Run Block
+
+    The block here is called upon the completion of each generation. The
+    'c' parameter is the RubyNEAT Controller, the same as given to the stop<sub>on</sub><sub>fitness</sub>
+    block.
+    
+        run_engine do |c|
+          $log.info "******** Run of generation %s completed, history count %d ********" %
+                [c.generation_num, c.population_history.size]
+        end
+
+### Releases<a id="orgheadline40"></a>
+
+1.  v0.4.0.alpha.4
+
+    -   First crude cut of a dashboard rubyneat<sub>dashboard</sub>
+
+2.  0.3.5.alpha.6
+
+    -   Command line workflow is a bit cleaner
+    -   Removed neater examples completely and place them in   
+        <https://github.com/flajann2/rubyneat_examples>
+    -   Cleaned up the internal docs a bit
+    -   Uniquely Generated Named Objects (UGNOs) cleaned up to be respectable
+
+3.  2015-06-08
+
+    -   Working on the Iterated ES HyperNEAT still,
+        after being side-tracked by having to make a living.
+        Also creating a maze environment for the critters to
+        operate as bots in order to test the new ES HyperNEAT extension.
+    -   rnDSL, as a result of TWEANN Compositions, is undergoing
+        radical changes. All example Neaters will be 
+        eventually update to reflect the new syntax.
+
+4.  2014-09-25
+
+    Hot on the efforts on adding two major features to RubyNEAT:
+    
+    -   TWEANN Compositions &#x2013; you will be able to define composites of TWEANNs on
+        a per critter basis. This should mirror how, say, biological brains composite
+        themselves into regions of speciality. You may specify different selections
+        of neurons for each TWEANN. This is totally experiential, so we'll
+        see if this results in better convergence for some problems.
+    
+    -   iterated ES HyperNEAT &#x2013; one of the compsitions
+        above can be specified as a Hyper TWEANN, and just
+        represent one of the many compositions you may have.
+    
+    -   The syntax of the Neater DSL will change quite a bit to
+        reflect the new features, and all of the examples will
+        be rewritten to show this.
+    
+    Do not confuse the ANN compositions here with CPPNs,
+    which are completely different. By default, all TWEANNs 
+    in HyperNEAT are potential CPPNs anyway, as
+    you can specify more than one neuron type.
+
+5.  2014-08-03
+
+    Just released a very crude alpha cut of a 
+    dashboard for RubyNEAT. You will have to
+    install it manually, along with rubyneat.
+    The gem is rubyneat<sub>dashboard</sub>.
+    
+    -   I am currently working on a Dashboard for RubyNEAT.
+        It will be a gemmable plugin that will allow you to
+        use the browser as the dashboard. It will have realtime
+        updates and the like, allowing you to monitor the progress 
+        of your Neaters, and to view and possibly set parameters,
+        and to see what your Critters look like.

data/_site/index.org

@@ -0,0 +1,525 @@
+<!DOCTYPE html>
+<html>
+
+  <head>
+  <meta charset="utf-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+
+  <title>RubyNEAT</title>
+  <meta name="description" content="Write an awesome description for your new site here. You can edit this line in _config.yml. It will appear in your document head meta (for Google search results) and in your feed.xml site description.
+">
+
+  <link rel="stylesheet" href="/css/main.css">
+  <link rel="canonical" href="http://rubyneat.de/index.org">
+  <link rel="alternate" type="application/rss+xml" title="RubyNEAT" href="http://rubyneat.de/feed.xml">
+</head>
+
+
+  <body>
+
+    <header class="site-header">
+
+  <div class="wrapper">
+
+    <a class="site-title" href="/">RubyNEAT</a>
+
+    <nav class="site-nav">
+      <a href="#" class="menu-icon">
+        <svg viewBox="0 0 18 15">
+          <path fill="#424242" d="M18,1.484c0,0.82-0.665,1.484-1.484,1.484H1.484C0.665,2.969,0,2.304,0,1.484l0,0C0,0.665,0.665,0,1.484,0 h15.031C17.335,0,18,0.665,18,1.484L18,1.484z"/>
+          <path fill="#424242" d="M18,7.516C18,8.335,17.335,9,16.516,9H1.484C0.665,9,0,8.335,0,7.516l0,0c0-0.82,0.665-1.484,1.484-1.484 h15.031C17.335,6.031,18,6.696,18,7.516L18,7.516z"/>
+          <path fill="#424242" d="M18,13.516C18,14.335,17.335,15,16.516,15H1.484C0.665,15,0,14.335,0,13.516l0,0 c0-0.82,0.665-1.484,1.484-1.484h15.031C17.335,12.031,18,12.696,18,13.516L18,13.516z"/>
+        </svg>
+      </a>
+
+      <div class="trigger">
+        
+          
+          <a class="page-link" href="/about/">About</a>
+          
+        
+          
+        
+          
+          <a class="page-link" href="/index.org">RubyNEAT</a>
+          
+        
+          
+        
+      </div>
+    </nav>
+
+  </div>
+
+</header>
+
+
+    <div class="page-content">
+      <div class="wrapper">
+        * RubyNEAT -- Ruby implementation of Neural Evolution of Augmenting Topologies (NEAT)
+** What is NEAT?
+   NEAT is an acronym for Neural Evolution of Augmenting Topologies.
+   In short, neural nets that are evolved from a minimal topology,
+   allowing selection to decide on what topologies are most adequate
+   for resolving the problem at hand.
+
+** What is RubyNEAT?
+   RubyNEAT is the world's first (and currently only) implementation
+   of the NEAT algorithm in the Ruby programming language. RubyNEAT
+   leverages some of the benefits of Ruby, such as metaprogramming,
+   to implement activation of the Neural Net.
+
+   Basically, the Neural Nets in RubyNEAT manifests themselves in the
+   Phenotypes as functional programs -- of a sort. You may think of it
+   as an application of Genetic Programming techniques to resolving the
+   NEAT algorithm. As such, once fit Critters (neural nets) are found,
+   they may be extracted as pure Ruby code, not needing the
+   RubyNEAT engine for activation.
+
+** Architecture
+   RubyNEAT comprises many interacting modules. While it is
+   not strictly necessary to understand RubyNEAT at this level
+   of detail, it would be beneficial for a number of reasons,
+   especially in understanding how to tweak the parameters
+   to improve performance for your application. 
+
+   RubyNEAT comprises the following modules: 
+   Controller, Expressor, Evaluator, Evolver, Population, and Critter.
+
+*** Controller
+    The Controller mediates all aspects of RubyNEAT
+    evolution, the various modules involved and their
+    interactions, and also holds the settings the other
+    modules will refer to. 
+
+    The Controller is singular. There can only be one
+    Controller in the RubyNEAT system. All other objects
+    associated with the Controller shall have embedded
+    in them a reference to their controller.
+
+*** Evolver
+    The Evolver module houses the evolving algorithms
+    for RubyNEAT. It evolves the entire Population of Critters.
+
+*** Expressor
+    The Expressor module is responsible for interpreting
+    the Genotype of the Critters and creating their
+    Phenotypes. The default Expressor generates Ruby code
+    and attaches that code to the Phenotype instances of the Critter. 
+
+    It is entirely possible to swap in a different Expressor and
+    generate code for a different target language, or create some 
+    other construct. There is no limit to what you could
+    have an Expressor do.
+
+*** Evaluator
+The Evaluator is a kind of bridge between the inner "biology" of the RubyNEAT "ecosystem" and the outside world. It has ties to the RubyNEAT DSL where you encode your own fitness functions and data links to some external problem space. It is, in a sense, the "gateway".
+
+*** Population
+The Population is what your intuition tells you. It is a environment that houses a collection of Critters. 
+
+*** Critter
+The Critter is the embodiment of both the genetics for the neural net and also the expression of the same. It contains, in other words, the Genotype and the Phenotype.
+
+Critters are mated through the Evolver, and have their genes expressed through the Expressor. 
+
+** Installation
+   You may install RubyNEAT by cloning the repo at GitHub:
+   [[https://github.com/flajann2/rubyneat][RubyNEAT Github]]
+
+   Or you may get it via a gem
+   #+BEGIN_SRC bash
+   gem install rubyneat --pre 
+   #+END_SRC
+
+*** Requirements
+     You will need at least Ruby 2.0.0, though we strongly recommend 2.1.1
+     or better. We will NOT be supporting 1.9.x,
+     as that is being phased out anyway.
+
+** Examples
+    Clone:
+
+    #+BEGIN_SRC bash
+      git clone git@github.com:flajann2/rubyneat_examples.git
+    #+END_SRC
+
+    and cd into the '''rubyneat_examples''' directory. 
+
+    Type: 
+
+    #+BEGIN_SRC bash
+      neat list neaters
+    #+END_SRC
+
+    to get a list of neaters. To run one like, say, the XOR test:
+
+    #+BEGIN_SRC bash
+      neat run xor
+    #+END_SRC
+
+*** Note Well
+    The pole-balancing invpend neater is still under
+    development. It will display a window with the cart and pole,
+    but will not balance yet. Just a matter of me 
+    finishing up that code. All the others work.
+
+**** RubyNEAT
+- GitHUB
+  [[https://github.com/flajann2/rubyneat][RubyNEAT GitHub]]
+
+- Ruby GEM
+  #+BEGIN_SRC bash
+  gem install rubyneat --pre
+  #+END_SRC
+
+**** RubyNEAT Examples
+- Github
+  [[https://github.com/flajann2/rubyneat_examples][Example Neaters on GitHub]]
+
+** RubyNEAT DSL
+    I will take the '''XOR''' neater and document it.
+    This is not the perfect way to go,
+    but I will get more extensive later.
+
+*** The XOR Neater Example
+#+BEGIN_SRC ruby
+ require 'xor'
+ include NEAT::DSL
+#+END_SRC
+
+- The first lines here includes the special XOR library, which is basically:
+
+#+BEGIN_SRC ruby
+ def xor(*inp)
+   inp.map{|n| (n > 0) ? 1 : 0}.reduce {|p, i| p + ((i > 0) ? 1 : 0) } == 1
+ end
+#+END_SRC
+
+
+-Basic settings for the '''XOR''', which can handle more than 2 inputs.
+
+#+BEGIN_SRC ruby
+ XOR_INPUTS = 2
+ XOR_STATES = 2 ** XOR_INPUTS
+ MAX_FIT    = XOR_STATES
+ ALMOST_FIT = XOR_STATES - 0.5
+#+END_SRC
+
+- The actual definition of the Neater. Here you specify the parameters RubyNEAT
+  will use to run the evolution, as well as the CPPN neuron types, the fitness function,
+  etc.
+
+#+BEGIN_SRC ruby
+ define "XOR System" do
+#+END_SRC
+
+- Inputs defined as name: Neuron, name: Neuron ... hash. In this segment, we
+  create a block to generate the hash since we can have a variable number of
+  inputs to the XOR. The input names must be unique. Note that a bias neuron
+  is also supplied, and it is always called :bias.
+
+#+BEGIN_SRC ruby
+   inputs {
+     cinv = Hash[(1..XOR_INPUTS).map{|i| [("i%s" % i).to_sym, InputNeuron]}]
+     cinv[:bias] = BiasNeuron
+     cinv
+   }
+#+END_SRC
+
+- Outputs are defined in a similar fashion to the inputs. The names of all the 
+  output neurons must be unique. Here in this example we only have one output, and
+  we use the hyperbolic tan Neuron as the output. There is also a sigmoid Neuron
+  that could be used as well, but the input levels would have to be conditioned
+  to vary from 0 to 1 instead of from -1 to one.
+
+#+BEGIN_SRC ruby
+   outputs out: TanhNeuron
+#+END_SRC
+
+- Hidden neuron specification is optional. 
+  The names given here are largely meaningless, but but follow the same rules
+  for uniqueness. The neurons specified will be selected randomly as the topologies
+  are augmented.
+
+#+BEGIN_SRC ruby
+  hidden tan: TanhNeuron
+#+END_SRC
+
+**** Settings
+     For RubyNEAT. Extensive documentation will be provided on a later date
+     as to the meanings, which closely follow the parameters for Ken Stanley's NEAT
+     implementation.
+
+****** General
+#+BEGIN_SRC ruby
+  hash_on_fitness false
+  start_population_size 30
+  population_size 30
+  max_generations 10000
+  max_population_history 10
+#+END_SRC
+
+****** Evolver probabilities and SDs
+        Perturbations
+#+BEGIN_SRC ruby
+  mutate_perturb_gene_weights_prob 0.10
+  mutate_perturb_gene_weights_sd 0.25
+#+END_SRC
+
+****** Complete Change of weight
+#+BEGIN_SRC ruby
+  mutate_change_gene_weights_prob 0.10
+  mutate_change_gene_weights_sd 1.00
+#+END_SRC
+
+****** Adding new neurons and genes
+#+BEGIN_SRC ruby
+  mutate_add_neuron_prob 0.05
+  mutate_add_gene_prob 0.20
+#+END_SRC
+
+****** Switching genes on and off
+#+BEGIN_SRC ruby
+  mutate_gene_disable_prob 0.01
+  mutate_gene_reenable_prob 0.01
+
+  interspecies_mate_rate 0.03
+  mate_only_prob 0.10 *0.7
+#+END_SRC
+
+****** Mating
+#+BEGIN_SRC ruby
+  survival_threshold 0.20 # top % allowed to mate in a species.
+  survival_mininum_per_species  4 # for small populations, we need SOMETHING to go on.
+#+END_SRC
+
+****** Fitness costs
+#+BEGIN_SRC ruby
+  fitness_cost_per_neuron 0.00001
+  fitness_cost_per_gene   0.00001
+#+END_SRC
+
+****** Speciation
+
+#+BEGIN_SRC ruby
+  compatibility_threshold 2.5
+  disjoint_coefficient 0.6
+  excess_coefficient 0.6
+  weight_coefficient 0.2
+  max_species 20
+  dropoff_age 15
+  smallest_species 5
+#+END_SRC
+
+****** Sequencing
+        The evaluation function is called repeatedly, and each iteration is given a
+        monotonically increasing integer which represents the sequence number. The results
+        of each run is returned, and those results are evaluated elsewhere in the Neater.
+
+#+BEGIN_SRC ruby
+  start_sequence_at 0
+  end_sequence_at 2 ** XOR_INPUTS - 1
+#+END_SRC
+
+**** The Evolution Block
+
+#+BEGIN_SRC ruby
+ evolve do
+#+END_SRC
+
+****** The Query Block
+        This query shall return a vector result that will serve
+        as the inputs to the critter. 
+
+#+BEGIN_SRC ruby
+   query { |seq|
+     * We'll use the seq to create the xor sequences via
+     * the least signficant bits.
+     condition_boolean_vector (0 ... XOR_INPUTS).map{|i| (seq & (1 << i)) != 0}
+   }
+#+END_SRC
+
+****** The Compare Block
+Compare the fitness of two critters. We may choose a different ordering here.
+
+#+BEGIN_SRC ruby
+  compare {|f1, f2| f2 <=> f1 }
+#+END_SRC
+
+****** The Cost of Fitness Block
+        Here we integrate the cost with the fitness.
+
+#+BEGIN_SRC ruby
+  cost { |fitvec, cost|
+    fit = XOR_STATES - fitvec.reduce {|a,r| a+r} - cost
+    $log.debug ">>>>>>> fitvec *{fitvec} => *{fit}, cost *{cost}"
+    fit
+  }
+#+END_SRC
+
+****** The Fitness Block
+        The fitness block is called for each activation and is given the input vector,
+        the output vector, and the sequence number given to the query. The results are
+        evaluated and a fitness scalar is returned.
+
+#+BEGIN_SRC ruby
+  fitness { |vin, vout, seq|
+    unless vout *** :error
+      bin = uncondition_boolean_vector vin
+      bout = uncondition_boolean_vector vout
+      bactual = [xor(*vin)]
+      vactual = condition_boolean_vector bactual
+      fit = (bout *** bactual) ? 0.00 : 1.00
+      *simple_fitness_error(vout, vactual.map{|f| f * 0.50 })
+      bfit = (bout *** bactual) ? 'T' : 'F'
+      fit
+    else
+      $log.debug "Error on *{vin} [*{seq}]"
+      1.0
+    end
+  }
+#+ END_SRC
+
+****** The Termination Condition
+        When the desired fitness level is reached, you may want to end the
+        Neater run. If so, provide a block to do just that.
+
+#+BEGIN_SRC ruby
+   stop_on_fitness { |fitness, c|
+     puts "*** Generation Run *{c.generation_num}, best is *{fitness[:best]} ***\n\n"
+     fitness[:best] >= ALMOST_FIT
+   }
+ end
+#+END_SRC
+
+**** Report Generating Block
+      This particular report block just adds something to the log. You could easily
+      replace that with a visual update if you like, etc.
+
+#+BEGIN_SRC ruby
+ report do |rept|
+   $log.info "REPORT *{rept.to_yaml}"
+ end
+#+END_SRC
+
+**** Engine Run Block
+      The block here is called upon the completion of each generation. The
+      'c' parameter is the RubyNEAT Controller, the same as given to the stop_on_fitness
+      block.
+
+#+BEGIN_SRC ruby
+ run_engine do |c|
+   $log.info "******** Run of generation %s completed, history count %d ********" %
+         [c.generation_num, c.population_history.size]
+ end
+#+END_SRC
+
+*** Releases
+**** v0.4.0.alpha.4
+ + First crude cut of a dashboard rubyneat_dashboard
+
+**** 0.3.5.alpha.6
+ + Command line workflow is a bit cleaner
+ + Removed neater examples completely and place them in   
+   https://github.com/flajann2/rubyneat_examples
+ + Cleaned up the internal docs a bit
+ + Uniquely Generated Named Objects (UGNOs) cleaned up to be respectable
+
+**** 2015-06-08
+ + Working on the Iterated ES HyperNEAT still,
+   after being side-tracked by having to make a living.
+   Also creating a maze environment for the critters to
+   operate as bots in order to test the new ES HyperNEAT extension.
+ + rnDSL, as a result of TWEANN Compositions, is undergoing
+   radical changes. All example Neaters will be 
+   eventually update to reflect the new syntax.
+
+**** 2014-09-25
+     Hot on the efforts on adding two major features to RubyNEAT:
+
+ + TWEANN Compositions -- you will be able to define composites of TWEANNs on
+   a per critter basis. This should mirror how, say, biological brains composite
+   themselves into regions of speciality. You may specify different selections
+   of neurons for each TWEANN. This is totally experiential, so we'll
+   see if this results in better convergence for some problems.
+
+ + iterated ES HyperNEAT -- one of the compsitions
+   above can be specified as a Hyper TWEANN, and just
+   represent one of the many compositions you may have.
+
+ + The syntax of the Neater DSL will change quite a bit to
+   reflect the new features, and all of the examples will
+   be rewritten to show this.
+
+ Do not confuse the ANN compositions here with CPPNs,
+ which are completely different. By default, all TWEANNs 
+ in HyperNEAT are potential CPPNs anyway, as
+ you can specify more than one neuron type.
+
+**** 2014-08-03
+    Just released a very crude alpha cut of a 
+    dashboard for RubyNEAT. You will have to
+    install it manually, along with rubyneat.
+    The gem is rubyneat_dashboard.
+
++ I am currently working on a Dashboard for RubyNEAT.
+  It will be a gemmable plugin that will allow you to
+  use the browser as the dashboard. It will have realtime
+  updates and the like, allowing you to monitor the progress 
+  of your Neaters, and to view and possibly set parameters,
+  and to see what your Critters look like.
+
+
+      </div>
+    </div>
+
+    <footer class="site-footer">
+
+  <div class="wrapper">
+
+    <h2 class="footer-heading">RubyNEAT</h2>
+
+    <div class="footer-col-wrapper">
+      <div class="footer-col footer-col-1">
+        <ul class="contact-list">
+          <li>RubyNEAT</li>
+          <li><a href="mailto:fred.mitchell@gmx.de">fred.mitchell@gmx.de</a></li>
+        </ul>
+      </div>
+
+      <div class="footer-col footer-col-2">
+        <ul class="social-media-list">
+          
+          <li>
+            <a href="https://github.com/flajann2"><span class="icon icon--github"><svg viewBox="0 0 16 16"><path fill="#828282" d="M7.999,0.431c-4.285,0-7.76,3.474-7.76,7.761 c0,3.428,2.223,6.337,5.307,7.363c0.388,0.071,0.53-0.168,0.53-0.374c0-0.184-0.007-0.672-0.01-1.32 c-2.159,0.469-2.614-1.04-2.614-1.04c-0.353-0.896-0.862-1.135-0.862-1.135c-0.705-0.481,0.053-0.472,0.053-0.472 c0.779,0.055,1.189,0.8,1.189,0.8c0.692,1.186,1.816,0.843,2.258,0.645c0.071-0.502,0.271-0.843,0.493-1.037 C4.86,11.425,3.049,10.76,3.049,7.786c0-0.847,0.302-1.54,0.799-2.082C3.768,5.507,3.501,4.718,3.924,3.65 c0,0,0.652-0.209,2.134,0.796C6.677,4.273,7.34,4.187,8,4.184c0.659,0.003,1.323,0.089,1.943,0.261 c1.482-1.004,2.132-0.796,2.132-0.796c0.423,1.068,0.157,1.857,0.077,2.054c0.497,0.542,0.798,1.235,0.798,2.082 c0,2.981-1.814,3.637-3.543,3.829c0.279,0.24,0.527,0.713,0.527,1.437c0,1.037-0.01,1.874-0.01,2.129 c0,0.208,0.14,0.449,0.534,0.373c3.081-1.028,5.302-3.935,5.302-7.362C15.76,3.906,12.285,0.431,7.999,0.431z"/></svg>
+</span><span class="username">flajann2</span></a>
+
+          </li>
+          
+
+          
+          <li>
+            <a href="https://twitter.com/flajann"><span class="icon icon--twitter"><svg viewBox="0 0 16 16"><path fill="#828282" d="M15.969,3.058c-0.586,0.26-1.217,0.436-1.878,0.515c0.675-0.405,1.194-1.045,1.438-1.809c-0.632,0.375-1.332,0.647-2.076,0.793c-0.596-0.636-1.446-1.033-2.387-1.033c-1.806,0-3.27,1.464-3.27,3.27 c0,0.256,0.029,0.506,0.085,0.745C5.163,5.404,2.753,4.102,1.14,2.124C0.859,2.607,0.698,3.168,0.698,3.767 c0,1.134,0.577,2.135,1.455,2.722C1.616,6.472,1.112,6.325,0.671,6.08c0,0.014,0,0.027,0,0.041c0,1.584,1.127,2.906,2.623,3.206 C3.02,9.402,2.731,9.442,2.433,9.442c-0.211,0-0.416-0.021-0.615-0.059c0.416,1.299,1.624,2.245,3.055,2.271 c-1.119,0.877-2.529,1.4-4.061,1.4c-0.264,0-0.524-0.015-0.78-0.046c1.447,0.928,3.166,1.469,5.013,1.469 c6.015,0,9.304-4.983,9.304-9.304c0-0.142-0.003-0.283-0.009-0.423C14.976,4.29,15.531,3.714,15.969,3.058z"/></svg>
+</span><span class="username">flajann</span></a>
+
+          </li>
+          
+        </ul>
+      </div>
+
+      <div class="footer-col footer-col-3">
+        <p>Write an awesome description for your new site here. You can edit this line in _config.yml. It will appear in your document head meta (for Google search results) and in your feed.xml site description.
+</p>
+      </div>
+    </div>
+
+  </div>
+
+</footer>
+
+
+  </body>
+
+</html>