Updated samples and their documentation.

Author: CodeReclaimers

examples/README.md

@@ -6,6 +6,8 @@ directly related to the NEAT library usage.
 
 ## The examples ##
 
+* `xor` A "hello world" sample showing basic usage.
+
 * `circuits` Uses an external circuit simulator (PySpice) to create electronic circuits that reproduce an arbitrary function of the input voltage.
 
 * `memory-fixed` Reproduce a fixed-length sequence of binary inputs.    

examples/circuits/README.md

@@ -0,0 +1,8 @@
+## Circuit example ##
+
+The scripts in this directory show how to evolve a network that describes an electronic 
+ circuit that reproduces an arbitrary function of the input voltage.
+
+Note that there is a significant amount of duplication between these scripts, and this is intentional.  The goal is to 
+make it easier to see what the example is doing, without making the user dig through a bunch of code that is not 
+directly related to the NEAT library usage.

examples/single-pole-balancing/README.md

@@ -0,0 +1,27 @@
+## Single-pole balancing examples ##
+
+The scripts in this directory show how to evolve a network that balances a pole on top of a movable cart.  The network
+inputs are the cart position, pole angle, and the derivatives of cart position and pole angle.  The network output is 
+used to apply a constant-magnitude force to the cart in either the left or right direction.
+
+Note that there is a significant amount of duplication between these scripts, and this is intentional.  The goal is to 
+make it easier to see what the example is doing, without making the user dig through a bunch of code that is not 
+directly related to the NEAT library usage.
+
+## Running the examples ##
+
+* Run `evolve-feedforward.py`.  When it completes, it will have created the following output:
+    - `avg_fitness.svg` Plot of mean/max fitness vs. generation.
+    - `speciation.svg` Speciation plot vs. generation.
+    - `winner-feedforward` A pickled version of the most fit genome.
+    - `winner-feedforward.gv` Graphviz layout of the full winning network.
+    - `winner-feedforward.gv.svg` Rendered image of the full winning network.
+    - `winner-feedforward-enabled.gv` Graphviz layout of the winning network, with disabled connections removed.
+    - `winner-feedforward-enabled.gv.svg` Rendered image of the winning network, with disabled connections removed.
+    - `winner-feedforward-enabled-pruned.gv` Graphviz layout of the winning network, with disabled and non-functional connections removed.
+    - `winner-feedforward-enabled-pruned.gv.svg` Rendered image of the winning network, with disabled and non-functional connections removed.
+    
+* Run `feedforward-test.py`.  It will load the most fit genome from `winner-feedforward` and run it in a new simulation to test its
+performance.  It will also run a second simulation, and produce a movie `feedforward-movie.mp4` showing the behavior.  (See a sample
+movie [here](http://gfycat.com/CavernousCheeryIbadanmalimbe).)
+

examples/single-pole-balancing/cart_pole.py

@@ -0,0 +1,104 @@
+'''
+General settings and implementation of the single-pole cart system dynamics.
+'''
+
+from math import cos, pi, sin
+import random
+
+
+class CartPole(object):
+    gravity = 9.8  # acceleration due to gravity, positive is downward, m/sec^2
+    mcart = 1.0  # cart mass in kg
+    mpole = 0.1  # pole mass in kg
+    lpole = 0.5  # half the pole length in meters
+    time_step = 0.01  # time step in seconds
+
+    def __init__(self, x=None, theta=None, dx=None, dtheta=None,
+                 position_limit=2.4, angle_limit_radians=45 * pi / 180):
+        self.position_limit = position_limit
+        self.angle_limit_radians = angle_limit_radians
+
+        if x is None:
+            x = random.uniform(-0.5 * self.position_limit, 0.5 * self.position_limit)
+
+        if theta is None:
+            theta = random.uniform(-0.5 * self.angle_limit_radians, 0.5 * self.angle_limit_radians)
+
+        if dx is None:
+            dx = random.uniform(-1.0, 1.0)
+
+        if dtheta is None:
+            dtheta = random.uniform(-1.0, 1.0)
+
+        self.t = 0.0
+        self.x = x
+        self.theta = theta
+
+        self.dx = dx
+        self.dtheta = dtheta
+
+        self.xacc = 0.0
+        self.tacc = 0.0
+
+    def step(self, force):
+        '''
+        Update the system state using leapfrog integration.
+            x_{i+1} = x_i + v_i * dt + 0.5 * a_i * dt^2
+            v_{i+1} = v_i + 0.5 * (a_i + a_{i+1}) * dt
+        '''
+        # Locals for readability.
+        g = self.gravity
+        mp = self.mpole
+        mc = self.mcart
+        mt = mp + mc
+        L = self.lpole
+        dt = self.time_step
+
+        # Remember acceleration from previous step.
+        tacc0 = self.tacc
+        xacc0 = self.xacc
+
+        # Update position/angle.
+        self.x += dt * self.dx + 0.5 * xacc0 * dt ** 2
+        self.theta += dt * self.dtheta + 0.5 * tacc0 * dt ** 2
+
+        # Compute new accelerations as given in "Correct equations for the dynamics of the cart-pole system"
+        # by Razvan V. Florian.
+        st = sin(self.theta)
+        ct = cos(self.theta)
+        tacc1 = (g * st + ct * (-force - mp * L * self.dtheta ** 2 * st) / mt) / (L * (4.0 / 3 - mp * ct ** 2 / mt))
+        xacc1 = (force + mp * L * (self.dtheta ** 2 * st - tacc1 * ct)) / mt
+
+        # Update velocities.
+        self.dx += 0.5 * (xacc0 + xacc1) * dt
+        self.dtheta += 0.5 * (tacc0 + tacc1) * dt
+
+        # Remember current acceleration for next step.
+        self.tacc = tacc1
+        self.xacc = xacc1
+        self.t += dt
+
+    def get_scaled_state(self):
+        '''Get full state, scaled into (approximately) [0, 1].'''
+        return [0.5 * (self.x + self.position_limit) / self.position_limit,
+                (self.dx + 0.75) / 1.5,
+                0.5 * (self.theta + self.angle_limit_radians) / self.angle_limit_radians,
+                (self.dtheta + 1.0) / 2.0]
+
+
+def continuous_actuator_force(action):
+    return -10.0 + 2.0 * action[0]
+
+
+def noisy_continuous_actuator_force(action):
+    a = action[0] + random.gauss(0, 0.2)
+    return 10.0 if a > 0.5 else -10.0
+
+
+def discrete_actuator_force(action):
+    return 10.0 if action[0] > 0.5 else -10.0
+
+
+def noisy_discrete_actuator_force(action):
+    a = action[0] + random.gauss(0, 0.2)
+    return 10.0 if a > 0.5 else -10.0

examples/single-pole-balancing/clean.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+rm *.svg *.gv *.mp4 winner-feedforward

examples/single-pole-balancing/config-feedforward

@@ -0,0 +1,61 @@
+# NEAT configuration for the bit-sequence memory experiment.
+
+# The `NEAT` section specifies parameters particular to the NEAT algorithm
+# or the experiment itself.  This is the only required section.
+[NEAT]
+pop_size              = 250
+max_fitness_threshold = 60000
+reset_on_extinction   = 0
+
+[DefaultGenome]
+num_inputs              = 4
+num_hidden              = 1
+num_outputs             = 1
+initial_connection      = partial 0.5
+feed_forward            = 0
+compatibility_threshold = 3.0
+compatibility_disjoint_coefficient    = 1.0
+compatibility_weight_coefficient      = 0.6
+conn_add_prob           = 0.2
+conn_delete_prob        = 0.2
+node_add_prob           = 0.2
+node_delete_prob        = 0.2
+activation_default      = sigmoid
+activation_options      = sigmoid
+activation_mutate_rate  = 0.0
+aggregation_default     = sum
+aggregation_options     = sum
+aggregation_mutate_rate = 0.0
+bias_init_mean          = 0.0
+bias_init_stdev         = 1.0
+bias_replace_rate       = 0.1
+bias_mutate_rate        = 0.7
+bias_mutate_power       = 0.5
+bias_max_value          = 30.0
+bias_min_value          = -30.0
+response_init_mean      = 1.0
+response_init_stdev     = 0.0
+response_replace_rate   = 0.0
+response_mutate_rate    = 0.0
+response_mutate_power   = 0.0
+response_max_value      = 30.0
+response_min_value      = -30.0
+
+weight_max_value        = 30
+weight_min_value        = -30
+weight_init_mean        = 0.0
+weight_init_stdev       = 1.0
+weight_mutate_rate      = 0.8
+weight_replace_rate     = 0.1
+weight_mutate_power     = 0.5
+enabled_default         = True
+enabled_mutate_rate     = 0.01
+
+[DefaultStagnation]
+species_fitness_func = max
+max_stagnation  = 20
+
+[DefaultReproduction]
+elitism            = 2
+survival_threshold = 0.2
+

examples/single-pole-balancing/evolve-feedforward.py

@@ -0,0 +1,81 @@
+"""
+Single-pole balancing experiment using a feed-forward neural network.
+"""
+
+from __future__ import print_function
+
+import os
+import pickle
+
+import cart_pole
+
+import neat
+import visualize
+
+runs_per_net = 5
+num_steps = 60000 # equivalent to 1 minute of simulation time
+
+
+# Use the NN network phenotype and the discrete actuator force function.
+def eval_genomes(genomes, config):
+    for genome_id, genome in genomes:
+        net = neat.nn.FeedForwardNetwork.create(genome, config)
+
+        fitnesses = []
+
+        for runs in range(runs_per_net):
+            sim = cart_pole.CartPole()
+
+            # Run the given simulation for up to num_steps time steps.
+            fitness = 0.0
+            for s in range(num_steps):
+                inputs = sim.get_scaled_state()
+                action = net.activate(inputs)
+
+                # Apply action to the simulated cart-pole
+                force = cart_pole.discrete_actuator_force(action)
+                sim.step(force)
+
+                # Stop if the network fails to keep the cart within the position or angle limits.
+                # The per-run fitness is the number of time steps the network can balance the pole
+                # without exceeding these limits.
+                if abs(sim.x) >= sim.position_limit or abs(sim.theta) >= sim.angle_limit_radians:
+                    break
+
+                fitness += 1.0
+
+            fitnesses.append(fitness)
+
+        # The genome's fitness is its worst performance across all runs.
+        genome.fitness = min(fitnesses)
+
+
+# Load the config file, which is assumed to live in
+# the same directory as this script.
+local_dir = os.path.dirname(__file__)
+config_path = os.path.join(local_dir, 'config-feedforward')
+config = neat.Config(neat.DefaultGenome, neat.DefaultReproduction, neat.DefaultStagnation, config_path)
+
+pop = neat.Population(config)
+stats = neat.StatisticsReporter()
+pop.add_reporter(stats)
+pop.add_reporter(neat.StdOutReporter())
+winner = pop.run(eval_genomes, 2000)
+
+# Save the winner.
+with open('winner-feedforward', 'wb') as f:
+    pickle.dump(winner, f)
+
+print(winner)
+
+visualize.plot_stats(stats, ylog=True, view=True)
+visualize.plot_species(stats, view=True)
+
+node_names = {-1: 'x', -2: 'dx', -3: 'theta', -4: 'dtheta', 0: 'control'}
+visualize.draw_net(config, winner, True, node_names=node_names)
+
+visualize.draw_net(config, winner, view=True, node_names=node_names, filename="winner-feedforward.gv")
+visualize.draw_net(config, winner, view=True, node_names=node_names, filename="winner-feedforward-enabled.gv", show_disabled=False)
+visualize.draw_net(config, winner, view=True, node_names=node_names, filename="winner-feedforward-enabled-pruned.gv", show_disabled=False, prune_unused=True)
+
+

examples/single-pole-balancing/fitness.py

@@ -0,0 +1,17 @@
+from cart_pole import CartPole, run_simulation
+
+runs_per_net = 5
+
+
+def evaluate_population(genomes, create_func, force_func):
+    for g in genomes:
+        net = create_func(g)
+
+        fitness = 0
+
+        for runs in range(runs_per_net):
+            sim = CartPole()
+            fitness += run_simulation(sim, net, force_func)
+
+        # The genome's fitness is its average performance across all runs.
+        g.fitness = fitness / float(runs_per_net)

examples/single-pole-balancing/movie.py

@@ -0,0 +1,36 @@
+import gizeh as gz
+import moviepy.editor as mpy
+from cart_pole import CartPole
+
+
+def make_movie(net, force_function, duration_seconds, output_filename):
+    w, h = 300, 100
+    scale = 300 / 6
+
+    cart = gz.rectangle(scale * 0.5, scale * 0.25, xy=(150, 80), stroke_width=1, fill=(0, 1, 0))
+    pole = gz.rectangle(scale * 0.1, scale * 1.0, xy=(150, 55), stroke_width=1, fill=(1, 1, 0))
+
+    sim = CartPole()
+
+    def make_frame(t):
+        inputs = sim.get_scaled_state()
+        action = net.activate(inputs)
+        sim.step(force_function(action))
+
+        surface = gz.Surface(w, h, bg_color=(1, 1, 1))
+
+        # Convert position to display units
+        visX = scale * sim.x
+
+        # Draw cart.
+        group = gz.Group((cart,)).translate((visX, 0))
+        group.draw(surface)
+
+        # Draw pole.
+        group = gz.Group((pole,)).translate((visX, 0)).rotate(sim.theta, center=(150 + visX, 80))
+        group.draw(surface)
+
+        return surface.get_npimage()
+
+    clip = mpy.VideoClip(make_frame, duration=duration_seconds)
+    clip.write_videofile(output_filename, codec="mpeg4", fps=50)