README
¶
evo
evo is neuroevolution framework based upon Dr. Kenneth Stanley's NEAT and subsequent extensions. Built from the ground up from the research papers and online articles, this implementation strives to be performant and extensible. See the wiki for more details.
NOTE: This is the second incarnation of EVO. Having survived the growing pains of the original, I decided to update the library based on my experience and continued reading. The prior version is archived under the archive-20180109 branch.
Installing
To start using EVO, install Go and run go get:
$ go get github.com/klokare/evo/...
Mercurial requirement
The library relies on packages from gonum which have their own dependencies. Some of those, like gopdf, require the use of Mercurial for the above go get command to work. If you see the following error, install Mercurial and then reissue the go get command.
$ go get github.com/klokare/evo/...
go: missing Mercurial command. See https://golang.org/s/gogetcmd
...
For further information on using, see the examples and peruse the wiki.
Version history and upcoming releases
| Version | Description |
|---|---|
| 0.1 | core library and tests (completed) |
| 0.2 | default configurer (completed) |
| 0.3 | default network and translator (completed) |
| 0.4 | NEAT-equivalent package and XOR experiment (completed) |
| 0.5 | |
| 0.6 | HyperNEAT package and boxes experiment (completed) |
| 0.7 | configurer rewrite, removal of functional options |
| 0.8 | ES-HyperNEAT package and mazes experiment |
| 0.9 | novelty package and updated mazes experiment |
| 0.10 | real-time package |
| 1.0 | production-ready release |
Documentation
¶
Index ¶
- Variables
- func GroupBySpecies(genomes []Genome) [][]Genome
- func SetSeed(seed int64)
- func SortBy(genomes []Genome, comparisons ...Comparison)
- type Activation
- type Callback
- type Comparison
- type Conn
- type Crosser
- type Evaluator
- type Event
- type Experiment
- type Genome
- type Matrix
- type Mutator
- type Mutators
- type Network
- type Neuron
- type Node
- type Phenome
- type Population
- type Populator
- type Position
- type Random
- type Result
- type Searcher
- type Seeder
- type Selector
- type Speciator
- type Species
- type Subscription
- type SubscriptionProvider
- type Substrate
- type Transcriber
- type Translator
Constants ¶
This section is empty.
Variables ¶
var ( ErrMissingNetworkFromTranslator = errors.New("successful translation did not return a network") ErrNoSeedGenomes = errors.New("seeder produced no genomes") )
Known errors
var Activations = map[string]Activation{ "direct": Direct, "sigmoid": Sigmoid, "steepened-sigmoid": SteepenedSigmoid, "tanh": Tanh, "inverse-abs": InverseAbs, "sin": Sin, "gauss": Gauss, "relu": ReLU, }
Activations provides map of activation functions by name
var ( Comparisons = map[string]Comparison{ "fitness": ByFitness, "age": ByAge, "solved": BySolved, "novelty": ByNovelty, "complexity": ByComplexity, "species": BySpecies, } )
Compares provides map of compare functions by name
Functions ¶
func GroupBySpecies ¶
GroupBySpecies returns the genoems orgainised by their species. These are copies and do not point back to the original slice. TODO: is there a more efficient way to build this than going through a map?
func SetSeed ¶
func SetSeed(seed int64)
SetSeed reinitialises the internal random number generator's seed value. This function is not safe for concurrent calls and really only should be used to control seed values for debugging.
func SortBy ¶
func SortBy(genomes []Genome, comparisons ...Comparison)
SortBy orders the genome by the comparison functions.
Types ¶
type Activation ¶
type Activation byte
Activation is the type of activation function to use with the neuron
const ( Direct Activation = iota + 1 Sigmoid SteepenedSigmoid Tanh InverseAbs // Also known as soft sign Sin Gauss ReLU )
Known list of activation types
func (Activation) Activate ¶
func (a Activation) Activate(x float64) float64
Activate the neuron using the appropriate transformation function.
func (Activation) String ¶
func (a Activation) String() string
type Callback ¶
type Callback func(pop Population) error
Callback functions are called when the event to which they are subscribed occurs. The final flag is true when the experiment is solved or on its final iteration
func WithIterations ¶
WithIterations creates a cancelable context and return the cancel function and a callback which must be subscribed in the experiment. The context will be cancelled when the number of iteations has been reached
func WithSolution ¶
WithSolution creates a cancelable context and return the cancel function and a callback which must be subscribed in the experiment. The context will be cancelled when a solution has been found.
type Comparison ¶
type Comparison byte
Comparison two genomes for relative order
const ( ByFitness Comparison = iota + 1 ByNovelty ByComplexity ByAge BySolved BySpecies )
Known comparison types
func (Comparison) Compare ¶
func (c Comparison) Compare(a, b Genome) int8
Compare two genomes using the appropriate method
func (Comparison) String ¶
func (c Comparison) String() string
type Conn ¶
type Conn struct {
Source, Target Position // The positions of the source and target nodes
Weight float64 // The connection weight
Enabled bool // True if this connection should be used to create a synapse
Locked bool // Locked connections cannot be removed or split
}
A Conn describes a synapse (a connection between neurons) in the network
type Crosser ¶
Crosser creates a new child from the parents through crossover (or cloning if there is only one parent). The crosser is not responsible for mutation or for assigning the genome an ID or to a species.
type Evaluator ¶
Evaluator utilises the network provided and returns its fitness (or error) as a result
type Experiment ¶
type Experiment interface {
Crosser
Mutator
Populator
Searcher
Selector
Speciator
Transcriber
Translator
}
An Experiment comprises the helpers necessary for creating, evaluating, and advancing a population in the search of a solution (or simply a better solver) of a particular problem.
type Genome ¶
type Genome struct {
ID int64 // The genome's unique identifier
Species int // The ID of the species
Age int // Number of generations genome has been alive
Fitness float64 // The genome's latest fitness score
Novelty float64 // The genome's latest novelty score, if any
Solved bool // True if the genome produced a solution in the last evaluation
Traits []float64 // Additional information, encoded as floats, that will be passed to the evaluation function
Encoded Substrate // The encoded neural network layout
Decoded Substrate // The decoded neural network layout
}
A Genome is the encoded neural network and its last result when applied in evaluation. For performance reasons, helpers should keep the nodes (by ID) and conns (by source and then target IDs) sorted though this is not required.
func (Genome) Complexity ¶
Complexity returns the number of nodes and connections in the genome
type Matrix ¶
type Matrix interface {
// Dims returns the dimensions of a Matrix.
Dims() (r, c int)
// At returns the value of a matrix element at row i, column j.
// It will panic if i or j are out of bounds for the matrix.
At(i, j int) float64
}
Matrix descibes data organised as a matrix. It mimics a subset of the signature of [gonum's mat.Matrix](https://godoc.org/gonum.org/v1/gonum/mat) which allows directly passing matrices from that package as inputs as well as any other type that implements it, such as [sparse](https://godoc.org/github.com/james-bowman/sparse). Network implementations, however, may expect a specific type and throw an error if they cannot convert to the desired type.
type Mutators ¶
type Mutators []Mutator
Mutators collection which acts as a single mutator. Component mutators will be called in order until the complexity of the genome changes.
type Node ¶
type Node struct {
Position // The location of the node on the substrate
Neuron // Then neuron type
Activation // The activation type
Bias float64 // Bias value for the neuron
Locked bool // Locked nodes cannot be removed
}
A Node describes a neuron in the network
type Phenome ¶
type Phenome struct {
ID int64 // The unique identifier of the genome
Traits []float64 // Any additional information, specific to this genome, to be passed to the evaluation function. This is optional.
Network // The neural network made from the genome's encoding
}
A Phenome is the instatiated genome to be sent to the evaluator
type Population ¶
type Population struct {
Generation int // The population's generation number
Genomes []Genome // The population's collection of genomes. The ordering of these is not guranateed.
}
A Population is the collection of genomes and species for a given generation.
func Run ¶
func Run(ctx context.Context, exp Experiment, eval Evaluator) (pop Population, err error)
Run the experiment in the given context with the evalutor. The context will decide when the experiment ends. See IterationContext and TimoutContext functions. An error is returned if any of the composite helpers' methods return an error.
type Populator ¶
type Populator interface {
Populate() (Population, error)
}
Populator provides a popluation from which the experiment will begin
type Position ¶
Position of a node on the substrate
func Midpoint ¶
Midpoint returns the midpoint (between to positions) or centre (between three or more positions). This function is necessary because of how Go treats floating point [constants](https://www.ardanlabs.com/blog/2014/04/introduction-to-numeric-constants-in-go.html) and how that can lead to [differeing values](https://github.com/golang/go/issues/23876) for similar calculations.
type Random ¶
Random provides the necessary functions used by this package without restricting use to the standard library's Rand
type Result ¶
type Result struct {
ID int64 // The unique ID of the genome from which the phenome was made
Solved bool // True if the network provided a winning solution
Fitness float64 // A positive value indicating the fitness of this network after evaluation
Novelty float64 // An optional value indicating the novelty of this network's decisions during evaluation
Behavior interface{} // An optional slice describing the novelty of the network's decisions
}
Result describes the outcome of running the evaluation. ID and fitness are required properties. If an error occurs in the evaluation, this should be returned with the result.
type Selector ¶
type Selector interface {
Select(Population) (continuing []Genome, parents [][]Genome, err error)
}
Selector examines a population returns the current genomes who will continue and those that will become parents
type Speciator ¶
type Speciator interface {
Speciate(*Population) error
}
Speciator assigns the population's genomes to a species, creating and destroying species as necessary.
type Species ¶
type Species struct {
ID int64 // The species's unique identifer
Decay float64 // The current decay amount applied to the species when calculating offspring or checking for stagnation
Champion int64 // ID of best genome, according to experiment's Comparer, within the species
Example Genome // The genome against whom other genomes are compared to see if they belong to this species
}
A Species represents the current state of a group of like genomes
type Subscription ¶
Subscription pairs a listener with its event
type SubscriptionProvider ¶
type SubscriptionProvider interface {
Subscriptions() []Subscription
}
SubscriptionProvider informs the caller of waiting subscriptions
type Substrate ¶
A Substrate lays out a neural network on a multidimensional s
func (Substrate) Complexity ¶
Complexity returns the sum of the sizes of the substrate's nodes and connections
type Transcriber ¶
Transcriber creates the decoded substrate from the encoded one.
type Translator ¶
Translator creates a new network from defintions contained in the nodes and connections
Source Files
Directories