Skip to content

Commit 46228eb

Browse files
author
Brian H
committed
maze experiment and novelty search
redesign to centralize access to helpers (Context) and make configuration simpler via interfaces. improved the trials output. added the maze experiment and novelty search.
1 parent a17441b commit 46228eb

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+2856
-2633
lines changed

‎README.md

+54-39
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,72 @@
1-
NEAT for Go
2-
###########
3-
1+
RedQ.NEAT
2+
==========
43
This a Go implementation of NeuralEvolution of Augmenting Topologies (NEAT). From the [NEAT F.A.Q](http://www.cs.ucf.edu/~kstanley/neat.html#FAQ1).
54

65
*NEAT stands for NeuroEvolution of Augmenting Topologies. It is a method for evolving artificial neural networks with a genetic algorithm. NEAT implements the idea that it is most effective to start evolution with small, simple networks and allow them to become increasingly complex over generations. That way, just as organisms in nature increased in complexity since the first cell, so do neural networks in NEAT. This process of continual elaboration allows finding highly sophisticated and complex neural networks.*
76

8-
The core of this library, often called Classic in the code, was written from the ground up using Dr. Kenneth Stanley's [PhD dissertation](http://nn.cs.utexas.edu/keyword?stanley:phd04) as a guide. NEAT has changed a bit since that paper and I have made some adjustments based on the F.A.Q. I have also add some flexibility in the design to allow for growing the library via helpers which will provide for adding HyperNEAT, Novelty Search, etc. to the library without changing the core API.
9-
10-
The library and proof-of-concept experiments utilize SVG to visualize the network of the best genome as well as the experiment's history. This visualization is based on the [NeuroEvolution Visualization Toolkit (NEVT)](http://nevt.sourceforge.net). Each image is output into an .html file for viewing from your desktop or presented through a web server.
11-
12-
# How to use
13-
14-
## Installation
7+
More information will be provided on the blog [redq.me](http://www.redq.me).
158

9+
# Installation
1610
```sh
1711
go get github.com/rqme/neat
1812
```
1913

20-
## Proof-of-concept experiments
14+
# Usage
15+
The API documentation can be found at [GoDoc](http://godoc.org/github.com/rqme/neat).
2116

22-
Inside the github.com/rqme/neat/x/proofs direcory are a series of experiments. I have tried to include at least one for each new feature of the library, usually from (or based on) the one the feature's creator used. Each experiment is set up to run as a series of indpendent trials with the results displayed in the console.
17+
The Context and Experiment are the central components of the library. The latter encapsulates everything needed for execution and the former provides access to all the necessary helpers. There are several convenience functions in the starter package.
2318

24-
Feature | Experiment | Use check-stop flag (see below)
25-
----------------|-------------|--------------------------------
26-
NEAT | XOR | yes
27-
NEAT | Double Pole | yes
28-
Phased Mutation | OCR | no
19+
RedQ.NEAT includes several demonstration experiments, each built at the onset of adding a new feature (like [phased mutation](http://sharpneat.sourceforge.net/phasedsearch.html)) or concept (like [Novelty Search](http://eplex.cs.ucf.edu/noveltysearch/userspage/)). These proof-of-concepts are intended to valid this library with the idea being tested as well as compare different helpers (such as HyperNEAT vs regular NEAT). The experiments are each in their own package in the x/experiments directory.
2920

30-
### To build
21+
## Running experiments
22+
Each experiment builds off the trials package which provides a way to compare multiple runs of an experiment against each other. This package provides several command line arguments that are common to all experiments and displays its output in the console window. For example, here is the output of the XOR experiment:
3123

3224
```sh
33-
go build github.com/rqme/neat/x/proof/xor
25+
$ xor --check-stop --trials 40
26+
Run Iters. Seconds Nodes Conns Fitness Fail Comment
27+
--- --------- --------- --------- --------- --------- ------ ---------
28+
0 28 1.339 9 16 16.000
29+
1 26 1.192 8 14 15.443
30+
2 59 3.384 7 17 16.000
31+
3 59 3.609 14 28 16.000
32+
...
33+
36 45 2.513 11 20 16.000
34+
37 30 1.265 7 12 12.250
35+
38 28 1.246 9 17 16.000
36+
39 19 0.822 6 12 13.930
37+
38+
Summary for trials excluding failures (and time for skipped)
39+
Iters. Seconds Nodes Conns Fitness
40+
--- --------- --------- --------- --------- ---------
41+
AVG 34 1.769 9 17 14.894
42+
MED 32 1.625 9 16 15.996
43+
SDV 13 0.905 2 5 1.637
44+
MIN 9 0.303 5 7 10.782
45+
MAX 66 4.503 15 33 16.000
3446
```
3547

36-
###To run
48+
### Common command-line arguments
49+
flag | description | default
50+
-----|-------------|------------
51+
config-name | Common name used as a prefix to archive files | defaults to the name of the executable
52+
config-path | Directory containing the initial configuration file and, if available, state files | Current directory
53+
trials | The number of trial runs to perform | 10
54+
check-stop | Experiments which do not end with an explicit stop are considered to have failed. | false
55+
show-work | Informs the Evaluator (if it implements Demonstrable) to show its work during evaluation. This is used only for the best genome. | false
56+
skip-evolve | Skips evolution and only performs summary of archived runs. Best used with --show-work and setting the config-path to the ArchivePath used in the settings file. | false
57+
58+
## Experiments
59+
### XOR
60+
[Exclusive OR](https://en.wikipedia.org/wiki/Exclusive_or), or XOR for short, is the starter experiment to verify the NEAT (called Classic in RedQ.NEAT) functionality. Located in the x/examples/xor directory, the package produces a standalone executable file. A configuration file, xor-config.json, is provided.
61+
62+
The experiment provides no new command-line arguments but it is recommended to use --check-stop when running to catch trials that do not produce a solution.
63+
64+
RedQ.NEAT was able to find a solution in 40 out of 40 trials. The median number of nodes and connections were 9 and 16 respectively. The results of this experiment are detailed in the [wiki](https://github.com/rqme/neat/wiki/XOR-experiment-results).
65+
66+
# Background
67+
The core of this library, often called Classic in the code, was written from the ground up using Dr. Kenneth Stanley's [PhD dissertation](http://nn.cs.utexas.edu/keyword?stanley:phd04) as a guide. NEAT has changed a bit since that paper and I have made some adjustments based on the F.A.Q. I have also add some flexibility in the design to allow for growing the library via helpers which will provide for adding HyperNEAT, Novelty Search, etc. to the library without changing the core API.
68+
69+
The library and proof-of-concept experiments utilize SVG to visualize the network of the best genome as well as the experiment's history. This visualization is based on the [NeuroEvolution Visualization Toolkit (NEVT)](http://nevt.sourceforge.net). Each image is output into an .html file for viewing from your desktop or presented through a web server.
70+
3771

38-
```sh
39-
xor --config-path "." --archive-path "/tmp" --archive-name "xor" --web-path "/tmp" --check-stop
40-
```
41-
There is a configuration file in each. Place this in the archive-path or, preferrably, config-path directory.
42-
43-
#### Command-line flags
44-
45-
Flag | Default | Description
46-
-------------|---------|------------------------------------------------------------------------------------------
47-
archive-path | "" | the directory to which generational settings and state will be written
48-
archive-name | "" | prefix for the archive files
49-
config-path | "" | overrides the archive-path. used to restore settings and state from a different location
50-
web-path | "" | the directory where html files from the web visualizer will be written
51-
trials | 10 | the number of trials to run
52-
check-stop | false | consider not meeting the stop condition a failure.
53-
duration | 90 | maximum number of minutes to run a trial. used by OCR only
54-
velocity | false | include velocity (Markov) in inputs. used by double pole only
55-
56-
Note: as the archiving process writes out all settings, including zero files, it is advisable to use a config-path to store an initial settings file to ensure it is not overwritten. This is especially important if setting traits are used as original settings will be overwritten during evolution.
5772

‎archiver/file.go

+72-90
Original file line numberDiff line numberDiff line change
@@ -27,122 +27,104 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
2727
package archiver
2828

2929
import (
30-
. "github.com/rqme/errors"
31-
"github.com/rqme/neat"
32-
33-
"bufio"
34-
"bytes"
30+
"encoding/json"
3531
"fmt"
36-
"io"
3732
"os"
3833
"path"
34+
"strconv"
35+
36+
"github.com/rqme/neat"
3937
)
4038

41-
type File struct {
42-
ArchivePath string
43-
ArchiveName string
39+
type FileSettings interface {
40+
ArchiveName() string
41+
ArchivePath() string
4442
}
4543

46-
// Archives the configuration extracted from an item to a file
47-
func (a File) Archive(item neat.Configurable) error {
44+
type File struct {
45+
FileSettings
46+
useTrials bool
47+
trialNum int
48+
}
4849

49-
errs := new(Errors)
50-
for _, suffix := range []string{"config", "state"} {
50+
func (a *File) SetTrial(t int) error {
51+
a.useTrials = true
52+
a.trialNum = t
53+
return nil
54+
}
5155

52-
// Extract the configuration for this tag
53-
c, err := neat.Extract(item, fmt.Sprintf("neat.%s", suffix))
54-
if err != nil {
55-
errs.Add(fmt.Errorf("archiver.File.Archive - Error extracting for %s : %v", suffix, err))
56-
continue
57-
}
56+
func (a *File) makePath(s string) string {
57+
p := a.ArchivePath()
58+
if a.useTrials {
59+
p = path.Join(p, strconv.Itoa(a.trialNum))
60+
}
61+
return path.Join(p, fmt.Sprintf("%s-%s.json", a.ArchiveName(), s))
62+
}
5863

59-
// Ensure the directory
60-
if _, err := os.Stat(a.ArchivePath); os.IsNotExist(err) {
61-
if err = os.Mkdir(a.ArchivePath, os.ModePerm); err != nil {
62-
errs.Add(fmt.Errorf("Could not create archive path %s: %v", a.ArchivePath, err))
63-
}
64-
}
64+
func (a *File) Archive(ctx neat.Context) error {
6565

66-
// Identify the path
67-
var p string
68-
if a.ArchiveName == "" {
69-
p = path.Join(a.ArchivePath, fmt.Sprintf("%s.json", suffix))
70-
} else {
71-
p = path.Join(a.ArchivePath, fmt.Sprintf("%s-%s.json", a.ArchiveName, suffix))
72-
}
66+
// Save the settings
67+
name := a.makePath("config")
68+
f, err := os.Create(name)
69+
if err != nil {
70+
return err
71+
}
72+
e := json.NewEncoder(f)
73+
if err = e.Encode(ctx); err != nil {
74+
f.Close()
75+
return err
76+
}
77+
f.Close()
7378

74-
// Create the file
75-
f, err := os.Create(p)
79+
// Save the state values
80+
for k, v := range ctx.State() {
81+
name := a.makePath(k)
82+
f, err = os.Create(name)
7683
if err != nil {
77-
errs.Add(fmt.Errorf("archiver.File.Archive - Error creating file for %s : %v", suffix, err))
78-
continue
84+
return err
7985
}
80-
81-
// Write the config to the file
82-
_, err = f.WriteString(c)
83-
if err != nil {
84-
errs.Add(fmt.Errorf("archiver.File.Archive - Error writing to file for %s : %v", suffix, err))
85-
continue
86+
e = json.NewEncoder(f)
87+
if err = e.Encode(v); err != nil {
88+
f.Close()
89+
return err
8690
}
8791
f.Close()
88-
8992
}
90-
91-
return errs.Err()
93+
return nil
9294
}
9395

94-
// Restores an item from the configuration stored in a file
95-
func (a File) Restore(item neat.Configurable) error {
96+
func (a *File) Restore(ctx neat.Context) error {
9697

97-
errs := new(Errors)
98-
for _, suffix := range []string{"config", "state"} {
99-
100-
// Identify the path
101-
var p string
102-
if a.ArchiveName == "" {
103-
p = path.Join(a.ArchivePath, fmt.Sprintf("%s.json", suffix))
104-
} else {
105-
p = path.Join(a.ArchivePath, fmt.Sprintf("%s-%s.json", a.ArchiveName, suffix))
106-
}
98+
// Restore the settings
99+
name := a.makePath("config")
100+
f, err := os.Open(name)
101+
if err != nil {
102+
return err
103+
}
104+
d := json.NewDecoder(f)
105+
if err = d.Decode(&ctx); err != nil {
106+
f.Close()
107+
return err
108+
}
109+
f.Close()
107110

108-
// Open the file
109-
f, err := os.Open(p)
110-
if err != nil {
111-
if os.IsNotExist(err) {
112-
continue // Nothing to restore
113-
}
114-
errs.Add(fmt.Errorf("archiver.File.Restore - Error opening file for %s : %v", suffix, err))
111+
// Restore the state values
112+
for k, v := range ctx.State() {
113+
name := a.makePath(k)
114+
if _, err := os.Stat(name); os.IsNotExist(err) {
115115
continue
116116
}
117117

118-
// Read the config to the file
119-
b := bytes.NewBufferString("")
120-
r := bufio.NewReader(f)
121-
for {
122-
s, err := r.ReadBytes('\n')
123-
if err != nil && err != io.EOF {
124-
break
125-
} else {
126-
b.Write(s)
127-
b.WriteString("\n")
128-
if err != nil && err == io.EOF {
129-
break
130-
}
131-
}
118+
f, err = os.Open(name)
119+
if err != nil {
120+
return err
132121
}
133-
if err != nil && err != io.EOF {
134-
errs.Add(fmt.Errorf("archiver.File.Restore - Error reading from file for %s : %v", suffix, err))
135-
continue
122+
d = json.NewDecoder(f)
123+
if err = d.Decode(&v); err != nil {
124+
f.Close()
125+
return err
136126
}
137127
f.Close()
138-
139-
// Configure the item
140-
err = item.Configure(b.String())
141-
if err != nil {
142-
errs.Add(fmt.Errorf("archiver.File.Restore - Error Configuring for %s : %v", suffix, err))
143-
continue
144-
}
145-
146128
}
147-
return errs.Err()
129+
return nil
148130
}

‎archiver/null.go

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
/*
2+
Copyright (c) 2015, Brian Hummer ([email protected])
3+
All rights reserved.
4+
5+
Redistribution and use in source and binary forms, with or without
6+
modification, are permitted provided that the following conditions are met:
7+
8+
* Redistributions of source code must retain the above copyright notice, this
9+
list of conditions and the following disclaimer.
10+
11+
* Redistributions in binary form must reproduce the above copyright notice,
12+
this list of conditions and the following disclaimer in the documentation
13+
and/or other materials provided with the distribution.
14+
15+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
19+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
23+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
24+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25+
*/
26+
27+
package archiver
28+
29+
import "github.com/rqme/neat"
30+
31+
type Null struct{}
32+
33+
func (a Null) Archive(ctx neat.Context) error {
34+
return nil
35+
}
36+
37+
func (a Null) Restore(ctx neat.Context) error {
38+
return nil
39+
}

0 commit comments

Comments
 (0)