Module summaries

activations

Has the built-in activation functions, code for using them, and code for adding new user-defined ones.

exception activations.InvalidActivationFunction(TypeError)[source]

Exception called if an activation function being added is invalid according to the validate_activation function.

Changed in version 0.91-github: Base of exception changed to more-precise TypeError.

activations.validate_activation(function)[source]

Checks to make sure its parameter is a function that takes a single argument.

Parameters:function (object) – Object to be checked.
Raises:InvalidActivationFunction – If the object does not pass the tests.
class activations.ActivationFunctionSet[source]

Contains the list of current valid activation functions, including methods for adding and getting them.

add(name, function)[source]

After validating the function (via validate_activation), adds it to the available activation functions under the given name. Used by DefaultGenomeConfig.add_activation.

Parameters:
get(name)[source]

Returns the named function, or raises an exception if it is not a known activation function.

Parameters:name (str) – The name of the function.
Raises:InvalidActivationFunction – If the function is not known.
is_valid(name)[source]

Checks whether the named function is a known activation function.

Parameters:name (str) – The name of the function.
Returns:Whether or not the function is known.
Return type:bool

Note

TODO: Suggested simplification for the below: Make __config_items__ a dict of lists, with name -> [value_type, default] - no default if the last is None. This would also allow moving get_config_params into the BaseAttribute class, although config_item_names may require some modifications. (A default capability will be needed for future expansions of the attributes, such as different types of initializations, and for enabling better handling of the current activation/aggregation function defaults.)

The above is mostly/entirely done in the config_work branch.

attributes

Deals with attributes used by genes.

Inheritance diagram of attributes
class attributes.BaseAttribute(name)[source]

Superclass for the type-specialized attribute subclasses, used by genes (such as via the genes.BaseGene implementation). Calls config_item_names to set up a listing of the names of configuration items using setattr.

config_item_names()[source]

Formats a list of configuration item names by combining the attribute’s name with the attribute class’ list of __config_items__.

Returns:A list of configuration item names.
Return type:list(str)
class attributes.FloatAttribute(BaseAttribute)[source]

Class for numeric attributes such as the response of a node; includes code for configuration, creation, and mutation.

get_config_params()[source]

Uses config_item_names to get its list of configuration item names, then gets a float-type config.ConfigParameter instance for each and returns it.

Returns:A list of ConfigParameter instances.
Return type:list(object)
clamp(value, config)[source]

Gets the minimum and maximum values desired from config, then ensures that the value is between them.

Parameters:
  • value (float) – The value to be clamped.
  • config (object) – The configuration object from which the minimum and maximum desired values are to be retrieved.
Returns:

The value, if it is within the desired range, or the appropriate end of the range, if it is not.

Return type:

float

init_value(config)[source]

Initializes the attribute’s value, (currently always) using a gaussian distribution with the configured mean and standard deviation followed by clamp to keep the result within the desired range.

Parameters:config (object) – The configuration object from which the mean and standard deviation values are to be retrieved.
Returns:The new value.
Return type:float
mutate_value(value, config)[source]

May replace (as if reinitializing, using init_value), mutate (using a 0-mean gaussian distribution with a configured standard deviation from mutate_power), or leave alone the input value, depending on the configuration settings (of replace_rate and mutate_rate). TODO: Note that the replace_rate is likely to be lower, so should be checked second. (Done in the config_work branch.)

Parameters:
  • value (float) – The current value of the attribute.
  • config (object) – The configuration object from which the parameters are to be extracted.
Returns:

Either the original value, if unchanged, or the new value.

Return type:

float

class attributes.BoolAttribute(BaseAttribute)[source]

Class for boolean attributes such as whether a connection is enabled or not; includes code for configuration, creation, and mutation.

get_config_params()[source]

Uses config_item_names to get its list of configuration item names, then gets a bool-type or float-type config.ConfigParameter instance for each and returns it.

Returns:A list of ConfigParameter instances.
Return type:list(object)
init_value(config)[source]

Initializes the attribute’s value, either using a configured default or (if the default is None) with a 50/50 chance of True or False.

Parameters:config (object) – The configuration object from which the default parameter is to be retrieved.
Returns:The new value.
Return type:bool
mutate_value(value, config)[source]

With a frequency determined by the mutate_rate (which is more precisely a replace_rate) configuration parameter, replaces the value with a 50/50 chance of True or False; note that this has a 50% chance of leaving the value unchanged. TODO: Have different chances possible of mutation in each direction. Also, do not check vs random if the mutate_rate is 0 (done in the config_work branch).

Parameters:
  • value (bool) – The current value of the attribute.
  • config (object) – The configuration object from which the mutate_rate parameter is to be extracted.
Returns:

Either the original value, if unchanged, or the new value.

Return type:

bool

class attributes.StringAttribute(BaseAttribute)[source]

Class for string attributes such as the aggregation function of a node, which are selected from a list of options; includes code for configuration, creation, and mutation.

get_config_params()[source]

Uses config_item_names to get its list of configuration item names, then gets a str-type, list-type or float-type config.ConfigParameter instance for each and returns it.

Returns:A list of ConfigParameter instances.
Return type:list(object)
init_value(config)[source]

Initializes the attribute’s value, either using a configured default or (if the default is either None or random) with a randomly-chosen member of the options (each having an equal chance). Note: It is possible for the default value, if specifically configured, to not be one of the options.

Parameters:config (object) – The configuration object from which the default and, if necessary, options parameters are to be retrieved.
Returns:The new value.
Return type:str
mutate_value(value, config)[source]

With a frequency determined by the mutate_rate (which is more precisely a replace_rate) configuration parameter, replaces the value with an one of the options, with each having an equal chance; note that this can be the same value as before. (It is possible to crudely alter the chances of what is chosen by listing a given option more than once, although this is inefficient given the use of the random.choice function.) TODO: Do not check vs random if the mutate_rate is 0 (done in the config_work branch). (Longer-term, add configurable probabilities of which option is used; eventually, as with the improved version of RBF-NEAT, separate genes for the likelihoods of each (but always doing some change, to prevent overly-conservative evolution due to its inherent short-sightedness), allowing the genomes to control the distribution of options, will be desirable.)

checkpoint

Uses pickle to save and restore populations (and other aspects of the simulation state).

class checkpoint.Checkpointer(generation_interval=100, time_interval_seconds=300)[source]

A reporter class that performs checkpointing, saving and restoring the simulation state (including population, randomization, and other aspects). It saves the current state every generation_interval generations or time_interval_seconds seconds, whichever happens first. Subclasses reporting.BaseReporter. (The potential save point is at the end of a generation.)

Parameters:
  • generation_interval (int or None) – If not None, maximum number of generations between checkpoints.
  • time_interval_seconds (float or None) – If not None, maximum number of seconds between checkpoints.
static save_checkpoint(config, population, species, generation)[source]

Saves the current simulation (including randomization) state to neat-checkpoint-generation, with generation being the generation number.

static restore_checkpoint(filename)[source]

Resumes the simulation from a previous saved point. Loads the specified file, sets the randomization state, and returns a population.Population object set up with the rest of the previous state.

Parameters:filename (str) – The file to be restored from.
Returns:Object that can be used with Population.run to restart the simulation.
Return type:Population object.

config

Does general configuration parsing; used by other classes for their configuration.

class config.ConfigParameter(name, value_type)[source]

Does initial handling of a particular configuration parameter.

Parameters:
  • name (str) – The name of the configuration parameter.
  • value_type (str) – The type that the configuration parameter should be; must be one of str, int, bool, float, or list.
__repr__()[source]

Returns a representation of the class suitable for use in code for initialization.

Returns:Representation as for repr.
Return type:str
parse(section, config_parser)[source]

Uses the supplied configuration parser (either from the configparser.ConfigParser class, or - for 2.7 - the ConfigParser.SafeConfigParser class) to gather the configuration parameter from the appropriate configuration file section. Parsing varies depending on the type.

Parameters:
  • section (str) – The section name, taken from the __name__ attribute of the class to be configured (or NEAT for those parameters).
  • config_parser (object) – The configuration parser to be used.
Returns:

The configuration parameter value, in stringified form unless a list.

Return type:

str or list

interpret(config_dict)[source]

Takes a dictionary of configuration parameters, as output by the configuration parser called in parse(), and interprets them into the proper type, with some error-checking.

Parameters:config_dict (dict) – Configuration parameters as output by the configuration parser.
Returns:The configuration parameter value
Return type:str or int or bool or float or list
format(value)[source]

Depending on the type of configuration parameter, returns either a space-separated list version, for list parameters, or the stringified version (using str), of value.

Parameters:value (str or int or bool or float or list) – Configuration parameter value to be formatted.
config.write_pretty_params(f, config, params)[source]

Prints configuration parameters, with justification based on the longest configuration parameter name.

Parameters:
  • f (file) – File object to be written to.
  • config (object) – Configuration object from which parameter values are to be fetched (using getattr).
  • params (list) – List of ConfigParameter instances giving the names of interest and the types of parameters.
class config.Config(genome_type, reproduction_type, species_set_type, stagnation_type, filename)[source]

A simple container for user-configurable parameters of NEAT. The four parameters ending in _type may be the built-in ones or user-provided objects, which must make available the methods parse_config and write_config, plus others depending on which object it is. (For more information on the objects, see below and Customizing Behavior.) Config itself takes care of the NEAT parameters. For a description of the configuration file, see Configuration file description.

Parameters:
Raises:

AssertionError – If any of the objects lack a parse_config method.

save(filename)[source]

Opens the specified file for writing (not appending) and outputs a configuration file from the current configuration. Uses write_pretty_params() for the NEAT parameters and the appropriate class write_config methods for the other sections.

Parameters:filename (str) – The configuration file to be written.

ctrnn

class ctrnn.CTRNNNodeEval(time_constant, activation, aggregation, bias, response, links)[source]

Sets up the basic Continuous-time recurrent neural network implementation (continuous-time recurrent neural network) nodes.

Parameters:
class ctrnn.CTRNN(inputs, outputs, node_evals)[source]

Sets up the Continuous-time recurrent neural network implementation network itself.

reset()[source]

Resets the time and all node activations to 0 (necessary due to otherwise retaining state via recurrent connections).

advance(inputs, advance_time, time_step=None)[source]

Advance the simulation by the given amount of time, assuming that inputs are constant at the given values during the simulated time.

Parameters:
  • inputs (list) – The values for the input nodes.
  • advance_time (float) – How much time to advance the network before returning the resulting outputs.
  • time_step (float) – How much time per step to advance the network; the default of None will currently result in an error, but it is planned to determine it automatically.
Returns:

The values for the output nodes.

Return type:

list

Raises:

NotImplementedError – If a time_step is not given.

static create(genome, config, time_constant)[source]

Receives a genome and returns its phenotype (a CTRNN with CTRNNNodeEval nodes).

Parameters:

genes

Inheritance diagram of genes, iznn
class genes.BaseGene(key)[source]

Handles functions shared by multiple types of genes (both node and connection), including crossover and calling mutation methods.

Parameters:key (int) – The gene identifier. Note: For connection genes, determining whether they are homologous (for genomic distance and crossover determination) uses the identifiers of the connected nodes, not the connection gene’s identifier.
__str__()[source]

Converts gene attributes into a printable format.

Returns:Stringified gene instance.
Return type:str
__lt__(other)[source]

Allows sorting genes by keys.

Parameters:other (object) – The other BaseGene object.
Returns:Whether the calling instance’s key is less than that of the other instance.
Return type:bool
classmethod parse_config(config, param_dict)[source]

Placeholder; parameters are entirely in gene attributes.

classmethod get_config_params()[source]

Fetches configuration parameters from each gene class’ __gene_attributes__ list (using FloatAttribute.get_config_params, BoolAttribute.get_config_params, or StringAttribute.get_config_params as appropriate for each listed attribute). Used by genome.DefaultGenomeConfig to include gene parameters in its configuration parameters.

Returns:List of configuration parameters (as config.ConfigParameter instances) for the gene attributes.
Return type:list(object)
init_attributes(config)[source]

Initializes its gene attributes using the supplied configuration object and FloatAttribute.init_value, BoolAttribute.init_value, or StringAttribute.init_value as appropriate.

Parameters:config (object) – Configuration object to be used by the appropriate attributes class.
mutate(config)[source]

Mutates (possibly) its gene attributes using the supplied configuration object and FloatAttribute.init_value, BoolAttribute.init_value, or StringAttribute.init_value as appropriate.

Parameters:config (object) – Configuration object to be used by the appropriate attributes class.
copy()[source]

Makes a copy of itself, including its subclass, key, and all gene attributes.

Returns:A copied gene
Return type:object
crossover(gene2)[source]

Creates a new gene via crossover - randomly inheriting attributes from its parents. The two genes must be homologous, having the same key/id.

Parameters:gene2 (object) – The other gene.
Returns:A new gene, with the same key/id, with other attributes being copied randomly (50/50 chance) from each parent gene.
Return type:object
class genes.DefaultNodeGene(BaseGene)[source]

Groups attributes specific to node genes - such as bias - and calculates genetic distances between two homologous (not disjoint or excess) node genes.

distance(other, config)[source]

Determines the degree of differences between node genes using their 4 attributes; the final result is multiplied by the configured compatibility_weight_coefficient.

Parameters:
  • other (object) – The other DefaultNodeGene.
  • config (object) – The genome configuration object.
Returns:

The contribution of this pair to the genomic distance between the source genomes.

Return type:

float

class genes.DefaultConnectionGene(BaseGene)[source]

Groups attributes specific to connection genes - such as weight - and calculates genetic distances between two homologous (not disjoint or excess) connection genes.

distance(other, config)[source]

Determines the degree of differences between connection genes using their 2 attributes; the final result is multiplied by the configured compatibility_weight_coefficient.

Parameters:
  • other (object) – The other DefaultConnectionGene.
  • config (object) – The genome configuration object.
Returns:

The contribution of this pair to the genomic distance between the source genomes.

Return type:

float

genome

Inheritance diagram of genome, iznn
genome.product(x)[source]

Used to implement a product (\(prod x\)) aggregation function.

Parameters:x (list(float)) – The inputs to be multiplied together.
class genome.DefaultGenomeConfig(params)[source]

Does the configuration for the DefaultGenome class. Has the dictionary aggregation_function_defs, which defines the available aggregation functions, and the list allowed_connectivity, which defines the available values for initial_connection. Includes parameters taken from the configured gene classes, such as genes.DefaultNodeGene, genes.DefaultConnectionGene, or iznn.IZNodeGene.

Parameters:params (dict) – Parameters from configuration file and DefaultGenome initialization (by parse_config).
add_activation(name, func)[source]

Adds a new activation function, as described in Customizing Behavior. Uses ActivationFunctionSet.add.

Parameters:
save(f)[source]

Saves the initial_connection configuration and uses config.write_pretty_params() to write out the other parameters.

Parameters:f (file) – The file object to be written to.
get_new_node_key(node_dict)[source]

Finds the next unused node key.

Parameters:node_dict (dict) – A dictionary of node keys vs nodes
Returns:A currently-unused node key.
Return type:int

Changed in version 0.91-github: Moved from DefaultGenome so no longer only single-genome-instance unique.

class genome.DefaultGenome(key)[source]

A genome for generalized neural networks. For class requirements, see Genome Interface. Terminology: pin - Point at which the network is conceptually connected to the external world; pins are either input or output. node - Analog of a physical neuron. connection - Connection between a pin/node output and a node’s input, or between a node’s output and a pin/node input. key - Identifier for an object, unique within the set of similar objects. Design assumptions and conventions. 1. Each output pin is connected only to the output of its own unique neuron by an implicit connection with weight one. This connection is permanently enabled. 2. The output pin’s key is always the same as the key for its associated neuron. 3. Output neurons can be modified but not deleted. 4. The input values are applied to the input pins unmodified.

Parameters:key (int) – Identifier for this individual/genome.
classmethod parse_config(param_dict)[source]

Required interface method. Provides default node and connection gene specifications (from genes) and uses DefaultGenomeConfig to do the rest of the configuration.

Parameters:param_dict (dict) – Dictionary of parameters from configuration file.
Returns:Configuration object; considered opaque by rest of code, so type may vary by implementation (here, a DefaultGenomeConfig instance).
Return type:object
classmethod write_config(f, config)[source]

Required interface method. Saves configuration using DefaultGenomeConfig.save().

Parameters:
configure_new(config)[source]

Required interface method. Configures a new genome (itself) based on the given configuration object, including genes for connectivity (based on initial_connection) and starting nodes (as defined by num_hidden, num_inputs, and num_outputs in the configuration file.

Parameters:config (object) – Genome configuration object.
configure_crossover(genome1, genome2, config)[source]

Required interface method. Configures a new genome (itself) by crossover from two parent genomes. disjoint or excess genes are inherited from the fitter of the two parents, while homologous genes use the gene class’ crossover function (e.g., genes.BaseGene.crossover()).

Parameters:
  • genome1 (object) – The first parent genome.
  • genome2 (object) – The second parent genome.
  • config (object) – Genome configuration object.
mutate(config)[source]

Required interface method. Mutates this genome. What mutations take place are determined by configuration file settings, such as node_add_prob and node_delete_prob for the likelihood of adding or removing a node and conn_add_prob and conn_delete_prob for the likelihood of adding or removing a connection. (Currently, more than one of these can happen with a call to mutate; a TODO is to add a configuration item to choose whether or not multiple mutations can happen simultaneously.) Non-structural mutations (to gene attributes) are performed by calling the appropriate mutate method(s) for connection and node genes (generally genes.BaseGene.mutate()).

Parameters:config (object) – Genome configuration object.
mutate_add_node(config)[source]

Takes a randomly-selected existing connection, turns its enabled attribute to False, and makes two new (enabled) connections with a new node between them, which join the now-disabled connection’s nodes. The connection weights are chosen so as to potentially have roughly the same behavior as the original connection, although this will depend on the activation function, bias, and response multiplier of the new node. TODO: Particularly if the configuration is changed to only allow one structural mutation, then if there are no connections, call mutate_add_connection() instead of returning.

Parameters:config (object) – Genome configuration object.
add_connection(config, input_key, output_key, weight, enabled)[source]

Adds a specified new connection; its key is the tuple of (input_key, output_key). TODO: Add validation of this connection addition.

Parameters:
  • config (object) – Genome configuration object
  • input_key (int) – Key of the input node.
  • output_key (int) – Key of the output node.
  • weight (float) – The weight the new connection should have.
  • enabled (bool) – The enabled attribute the new connection should have.
mutate_add_connection(config)[source]

Attempts to add a randomly-selected new connection, with some filtering: 1. input nodes cannot be at the output end. 2. Existing connections cannot be duplicated. TODO: If a selected existing connection is not enabled, have some configurable chance that it will become enabled. 3. Two output nodes cannot be connected together. 4. If feed_forward is set to True in the configuration file, connections cannot create cycles.

Parameters:config (object) – Genome configuration object

Changed in version 0.91-github: Output nodes not allowed to be connected together.

mutate_delete_node(config)[source]

Deletes a randomly-chosen (non-output/input) node along with its connections.

Parameters:config (object) – Genome configuration object
mutate_delete_connection()[source]

Deletes a randomly-chosen connection. TODO: If the connection is enabled, have an option to - possibly with a weight-dependent chance - turn its enabled attribute to False instead.

distance(other, config)[source]

Required interface method. Returns the genomic distance between this genome and the other. This distance value is used to compute genome compatibility for speciation. Uses (by default) the genes.DefaultNodeGene.distance() and genes.DefaultConnectionGene.distance() methods for homologous pairs, and the configured compatibility_disjoint_coefficient for disjoint/excess genes. (Note that this is one of the most time-consuming portions of the library; optimization - such as using cython - may be needed if using an unusually fast fitness function and/or an unusually large population.)

Parameters:
  • other (object) – The other DefaultGenome instance (genome) to be compared to.
  • config (object) – The genome configuration object.
Returns:

The genomic distance.

Return type:

float

size()[source]

Required interface method. Returns genome complexity, taken to be (number of nodes, number of enabled connections); currently only used for reporters - some retrieve this information for the highest-fitness genome at the end of each generation.

__str__()[source]

Gives a listing of the genome’s nodes and connections.

Returns:Node and connection information.
Return type:str
static create_node(config, node_id)[source]

Creates a new node with the specified id (including for its gene), using the specified configuration object to retrieve the proper node gene type and how to initialize its attributes.

Parameters:
  • config (object) – The genome configuration object.
  • node_id (int) – The key for the new node.
Returns:

The new node object.

Return type:

object

static create_connection(config, input_id, output_id)[source]

Creates a new connection with the specified id pair as its key (including for its gene, as a tuple), using the specified configuration object to retrieve the proper connection gene type and how to initialize its attributes.

Parameters:
  • config (object) – The genome configuration object.
  • input_id (int) – The input end’s key.
  • output_id (int) – The output end’s key.
Returns:

The new connection object.

Return type:

object

connect_fs_neat_nohidden(config)[source]

Connect one randomly-chosen input to all output nodes (FS-NEAT without connections to hidden nodes, if any). Previously called connect_fs_neat. Implements the fs_neat_nohidden setting for initial_connection.

Parameters:config (object) – The genome configuration object.
connect_fs_neat_hidden(config)[source]

Connect one randomly-chosen input to all hidden nodes and output nodes (FS-NEAT with connections to hidden nodes, if any). Implements the fs_neat_hidden setting for initial_connection.

Parameters:config (object) – The genome configuration object.
compute_full_connections(config, direct)[source]

Compute connections for a fully-connected feed-forward genome–each input connected to all hidden nodes (and output nodes if direct is set or there are no hidden nodes), each hidden node connected to all output nodes. (Recurrent genomes will also include node self-connections.)

Parameters:
  • config (object) – The genome configuration object.
  • direct (bool) – Whether or not, if there are hidden nodes, to include links directly from input to output.
Returns:

The list of connections, as (input key, output key) tuples

Return type:

list(tuple(int,int))

Changed in version 0.91-github: “Direct” added to help with documentation vs program conflict; connect_fs_neat, connect_full, connect_partial split up.

connect_full_nodirect(config)[source]

Create a fully-connected genome (except no direct input to output connections unless there are no hidden nodes).

Parameters:config (object) – The genome configuration object.
connect_full_direct(config)[source]

Create a fully-connected genome, including direct input-output connections.

Parameters:config (object) – The genome configuration object.
connect_partial_nodirect(config)[source]

Create a partially-connected genome, with (unless there are no hidden nodes) no direct input-output connections.

Parameters:config (object) – The genome configuration object.
connect_partial_direct(config)[source]

Create a partially-connected genome, possibly including direct input-output connections.

Parameters:config (object) – The genome configuration object.

graphs

Directed graph algorithm implementations.

graphs.creates_cycle(connections, test)[source]

Returns true if the addition of the test connection would create a cycle, assuming that no cycle already exists in the graph represented by connections. Used to avoid recurrent networks when a purely feed-forward network is desired (e.g., as determined by the feed_forward setting in the configuration file.

Parameters:
  • connections (list(tuple(int, int))) – The current network, as a list of (input, output) connection identifiers.
  • test (tuple(int, int)) – Possible connection to be checked for causing a cycle.
Returns:

True if a cycle would be created; false if not.

Return type:

bool

graphs.required_for_output(inputs, outputs, connections)[source]

Collect the nodes whose state is required to compute the final network output(s).

Parameters:
  • inputs (list(int)) – the input node identifiers; it is assumed that the input identifier set and the node identifier set are disjoint.
  • outputs (list(int)) – the output node identifiers; by convention, the output node ids are always the same as the output index.
  • connections (list(tuple(int, int))) – list of (input, output) connections in the network; should only include enabled ones.
Returns:

A list of layers, with each layer consisting of a set of node identifiers.

Return type:

list(set(int))

graphs.feed_forward_layers(inputs, outputs, connections)[source]

Collect the layers whose members can be evaluated in parallel in a feed-forward network.

Parameters:
Returns:

A list of layers, with each layer consisting of a set of identifiers; only includes nodes returned by required_for_output.

Return type:

list(set(int))

indexer

Helps with creating new identifiers/keys.

class indexer.Indexer(first)[source]

Initializes an Indexer instance with the internal ID counter set to first. This class functions to help with creating new (unique) identifiers/keys.

Parameters:first (int) – The initial identifier (key) to be used.
get_next(result=None)[source]

If result is not None, then we return it unmodified. Otherwise, we return the next ID and increment our internal counter.

Parameters:result (int or None) – Returned unmodified unless None.
Returns:Identifier/key to use.
Return type:int

iznn

This module implements a spiking neural network. Neurons are based on the model described by:

Izhikevich, E. M.
Simple Model of Spiking Neurons
IEEE TRANSACTIONS ON NEURAL NETWORKS, VOL. 14, NO. 6, NOVEMBER 2003

See http://www.izhikevich.org/publications/spikes.pdf.

Inheritance diagram of iznn
class iznn.IZNodeGene(BaseGene)[source]

Contains attributes for the iznn node genes and determines genomic distances.

class iznn.IZGenome(DefaultGenome)[source]

Contains the parse_config class method for iznn genome configuration.

class iznn.IZNeuron(bias, a, b, c, d, inputs)[source]

Sets up and simulates the iznn nodes (neurons).

Parameters:
  • bias (float) – The bias of the neuron.
  • a (float) – The time scale of the recovery variable.
  • b (float) – The sensitivity of the recovery variable.
  • c (float) – The after-spike reset value of the membrane potential.
  • d (float) – The after-spike reset of the recovery variable.
  • inputs (list(tuple(int, float))) – A list of (input key, weight) pairs for incoming connections.
advance(dt_msec)[source]

Advances simulation time for the neuron by the given time step in milliseconds. TODO: Currently has some numerical stability problems.

Parameters:dt_msec (float) – Time step in milliseconds.
reset()[source]

Resets all state variables.

class iznn.IZNN(neurons, inputs, outputs)[source]

Sets up the network itself and simulates it using the connections and neurons.

Parameters:
set_inputs(inputs)[source]

Assigns input voltages.

Parameters:inputs (list(float)) – The input voltages for the input nodes.
reset()[source]

Resets all neurons to their default state.

get_time_step_msec()[source]

Returns a suggested time step; currently hardwired to 0.05. TODO: Investigate this (particularly effects on numerical stability issues).

Returns:Suggested time step in milliseconds.
Return type:float
advance(dt_msec)[source]

Advances simulation time for all neurons in the network by the input number of milliseconds.

Parameters:dt_msec (float) – How many milliseconds to advance the network.
Returns:The values for the output nodes.
Return type:list(float)
static create(genome, config)[source]

Receives a genome and returns its phenotype (a neural network).

Parameters:
  • genome (object) – An IZGenome instance.
  • config (object) – Configuration object.
Returns:

An IZNN instance.

Return type:

object

math_util

Contains some mathematical/statistical functions not found in the Python2 standard library, plus a mechanism for looking up some commonly used functions (such as for the species_fitness_func) by name.

math_util.stat_functions

Lookup table for commonly used {value} -> value functions; includes max, min, mean, and median. The species_fitness_func (used for stagnation.DefaultStagnation) is required to be one of these.

math_util.mean(values)[source]

Returns the arithmetic mean.

math_util.median(values)[source]

Returns the median. (Note: For even numbers of values, does not take the mean between the two middle values.)

math_util.variance(values)[source]

Returns the (population) variance.

math_util.stdev(values)[source]

Returns the (population) standard deviation. Note spelling.

math_util.softmax(values)[source]

Compute the softmax (a differentiable/smooth approximization of the maximum function) of the given value set. The softmax is defined as follows: \(\begin{equation}v_i = \exp(v_i) / s \text{, where } s = \sum(\exp(v_0), \exp(v_1), \dotsc)\end{equation}\).

nn.feed_forward

class nn.feed_forward.FeedForwardNetwork(inputs, outputs, node_evals)[source]

A straightforward (no pun intended) feed-forward neural network NEAT implementation.

Parameters:
  • inputs (list(int)) – The input keys (IDs).
  • outputs (list(int)) – The output keys.
  • node_evals (list(list(object))) – A list of node descriptions, with each node represented by a list.
activate(inputs)[source]

Feeds the inputs into the network and returns the resulting outputs.

Parameters:inputs (list) – The values for the input nodes.
Returns:The values for the output nodes.
Return type:list
static create(genome, config)[source]

Receives a genome and returns its phenotype (a FeedForwardNetwork).

nn.recurrent

class nn.recurrent.RecurrentNetwork(inputs, outputs, node_evals)[source]

A recurrent (but otherwise straightforward) neural network NEAT implementation.

Parameters:
  • inputs (list(int)) – The input keys (IDs).
  • outputs (list(int)) – The output keys.
  • node_evals (list(list(object))) – A list of node descriptions, with each node represented by a list.
reset()[source]

Resets all node activations to 0 (necessary due to otherwise retaining state via recurrent connections).

activate(inputs)[source]

Feeds the inputs into the network and returns the resulting outputs.

Parameters:inputs (list) – The values for the input nodes.
Returns:The values for the output nodes.
Return type:list
static create(genome, config)[source]

Receives a genome and returns its phenotype (a RecurrentNetwork).

parallel

Runs evaluation functions in parallel subprocesses in order to evaluate multiple genomes at once.

class parallel.ParallelEvaluator(num_workers, eval_function, timeout=None)[source]

Runs evaluation functions in parallel subprocesses in order to evaluate multiple genomes at once.

Parameters:
  • num_workers (int) – How many workers to have in the Pool.
  • eval_function (function) – The eval_function should take one argument - a tuple of (genome object, config object) - and return a single float (the genome’s fitness) Note that this is not the same as how a fitness function is called by Population.run.
  • timeout (int or None) – How long (in seconds) each subprocess will be given before an exception is raised (unlimited if None).
__del__()[source]

Takes care of removing the subprocesses.

evaluate(genomes, config)[source]

Distributes the evaluation jobs among the subprocesses, then assigns each fitness back to the appropriate genome.

Parameters:

population

Implements the core evolution algorithm.

exception population.CompleteExtinctionException[source]

Raised on complete extinction (all species removed due to stagnation) unless reset_on_extinction is set.

class population.Population(config, initial_state=None)[source]

This class implements the core evolution algorithm: 1. Evaluate fitness of all genomes. 2. Check to see if the termination criterion is satisfied; exit if it is. 3. Generate the next generation from the current population. 4. Partition the new generation into species based on genetic similarity. 5. Go to 1.

Parameters:
run(fitness_function, n=None)[source]

Runs NEAT’s genetic algorithm for at most n generations. If n is None, run until solution is found or extinction occurs.

The user-provided fitness_function must take only two arguments: 1. The population as a list of (genome id, genome) tuples. 2. The current configuration object.

The return value of the fitness function is ignored, but it must assign a Python float to the fitness member of each genome.

The fitness function is free to maintain external state, perform evaluations in parallel, etc.

It is assumed that the fitness function does not modify the list of genomes, the genomes themselves (apart from updating the fitness member), or the configuration object.

Parameters:
  • fitness_function (object) – The fitness function to use, with arguments specified above.
  • n (int or None) – The maximum number of generations to run (unlimited if None).
Returns:

The best genome seen.

Return type:

object

reporting

Inheritance diagram of reporting, checkpoint, statistics
class reporting.ReporterSet[source]

Keeps track of the set of reporters and gives methods to dispatch them at appropriate points.

add(reporter)[source]

Adds a reporter to those to be called via ReporterSet methods.

Parameters:reporter (object) – A reporter instance.
remove(reporter)[source]

Removes a reporter from those to be called via ReporterSet methods.

Parameters:reporter (object) – A reporter instance.
start_generation(gen)[source]

Calls start_generation on each reporter in the set.

Parameters:gen (int) – The generation number.
end_generation(config, population, species)[source]

Calls end_generation on each reporter in the set.

Parameters:
post_evaluate(config, population, species)[source]

Calls post_evaluate on each reporter in the set.

Parameters:
post_reproduction(config, population, species)[source]

Not currently called. Would call post_reproduction on each reporter in the set.

complete_extinction()[source]

Calls complete_extinction on each reporter in the set.

found_solution(config, generation, best)[source]

Calls found_solution on each reporter in the set.

Parameters:
  • config (object) – Config configuration object.
  • generation (int) – Generation number.
  • best (object) – The currently highest-fitness genome. (Ties are resolved pseudorandomly by dictionary ordering.)
species_stagnant(sid, species)[source]

Calls species_stagnant on each reporter in the set.

Parameters:
info(msg)[source]

Calls info on each reporter in the set.

Parameters:msg (str) – Message to be handled.
class reporting.BaseReporter[source]

Abstract class defining the reporter interface expected by ReporterSet. Inheriting from it will provide a set of dummy methods to be overridden as desired, as follows:

start_generation(generation)[source]

Called via ReporterSet (by population.Population.run()) at the start of each generation, prior to the invocation of the fitness function.

Parameters:generation (int) – The generation number.
end_generation(config, population, species)[source]

Called via ReporterSet (by population.Population.run()) at the end of each generation, after reproduction and speciation.

Parameters:
post_evaluate(config, population, species, best_genome)[source]

Called via ReporterSet (by population.Population.run()) after the fitness function is finished.

Parameters:
post_reproduction(config, population, species)[source]

Not currently called (indirectly or directly), including by either population.Population.run() or reproduction.DefaultReproduction. Note: New members of the population likely will not have a set species.

complete_extinction()[source]

Called via ReporterSet (by population.Population.run()) if complete extinction (due to stagnation) occurs, prior to (depending on the reset_on_extinction configuration setting) a new population being created or a population.CompleteExtinctionException being raised.

found_solution(config, generation, best)[source]

Called via ReporterSet (by population.Population.run()) prior to exiting if the configured fitness threshold is met. (Note: Not called upon reaching the generation maximum - set when calling population.Population.run() - and exiting for this reason.)

Parameters:
  • config (object) – Config configuration object.
  • generation (int) – Generation number.
  • best (object) – The currently highest-fitness genome. (Ties are resolved pseudorandomly by dictionary ordering.)
species_stagnant(sid, species)[source]

Called via ReporterSet (by reproduction.DefaultReproduction.reproduce()) for each species considered stagnant by the stagnation class (such as stagnation.DefaultStagnation).

Parameters:
info(msg)[source]

Miscellaneous informational messages, from multiple parts of the library, called via ReporterSet.

Parameters:msg (str) – Message to be handled.
class reporting.StdOutReporter(show_species_detail)[source]

Uses print to output information about the run; an example reporter class.

Parameters:show_species_detail (bool) – Whether or not to show additional details about each species in the population.

reproduction

class reproduction.DefaultReproduction(config, reporters, stagnation)[source]

Handles creation of genomes, either from scratch or by sexual or asexual reproduction from parents. Implements the default NEAT-python reproduction scheme: explicit fitness sharing with fixed-time species stagnation. For class requirements, see Reproduction Interface.

Parameters:
  • config (dict) – Configuration object, in this implementation a dictionary.
  • reporters (object) – A ReporterSet object.
  • stagnation (object) – A DefaultStagnation object - the current code partially depends on internals of this class (a TODO is noted to correct this).
classmethod parse_config(param_dict)[source]

Required interface method. Provides defaults for elitism, survival_threshold, and min_species_size parameters and updates them from the configuration file. TODO: Use a separate configuration class, for consistency with other types (done in the config_work branch).

Parameters:param_dict (dict) – Dictionary of parameters from configuration file.
Returns:Configuration object; considered opaque by rest of code, so current type returned is not required for interface.
Return type:dict
classmethod write_config(f, param_dict)[source]

Required interface method. Saves elitism and survival_threshold (but not min_species_size) parameters to new config file. (Inconsistency re min_species_size fixed in the config_work branch.)

Parameters:
  • f (file) – File object to write to.
  • param_dict (dict) – Dictionary of current parameters in this implementation; more generally, reproduction config object.
create_new(genome_type, genome_config, num_genomes)[source]

Required interface method. Creates num_genomes new genomes of the given type using the given configuration. Also initializes ancestry information (as an empty tuple).

Parameters:
  • genome_type (class) – Genome class (such as DefaultGenome or iznn.IZGenome) of which to create instances.
  • genome_config (object) – Opaque genome configuration object.
  • num_genomes (int) – How many new genomes to create.
Returns:

A dictionary (with the unique genome identifier as the key) of the genomes created.

Return type:

dict(int, object)

static compute_spawn(adjusted_fitness, previous_sizes, pop_size, min_species_size)[source]

Apportions desired number of members per species according to fitness (adjusted by reproduce() to a 0-1 scale) from out of the desired population size.

Parameters:
  • adjusted_fitness (list(float)) – Mean fitness for species members, adjusted to 0-1 scale (see below).
  • previous_sizes (list(int)) – Number of members of species in population prior to reproduction.
  • pop_size (int) – Desired population size, as input to reproduce().
  • min_species_size (int) – Minimum number of members per species; can result in population size being above pop_size.
reproduce(config, species, pop_size, generation)[source]

Required interface method. Creates the population to be used in the next generation from the given configuration instance, SpeciesSet instance, desired size of the population, and current generation number. This method is called after all genomes have been evaluated and their fitness member assigned. This method should use the stagnation instance given to the initializer to remove species deemed to have stagnated. Note: Determines relative fitnesses by transforming into (ideally) a 0-1 scale; however, if the top and bottom fitnesses are not at least 1 apart, the range may be less than 0-1, as a check against dividing by a too-small number. TODO: Make minimum difference configurable (defaulting to 1 to preserve compatibility).

Parameters:
  • config (object) – A Config instance.
  • species (object) – A DefaultSpeciesSet instance. As well as depending on some of the DefaultStagnation internals, this method also depends on some of those of the DefaultSpeciesSet and its referenced species objects.
  • pop_size (int) – Population size desired, such as set in the configuration file.
  • generation (int) – Generation count.
Returns:

New population, as a dict of unique genome ID/key vs genome.

Return type:

dict(int, object)

six_util

This Python 2/3 portability code was copied from the six module to avoid adding it as a dependency.

six_util.iterkeys(d, **kw)[source]

This function returns an iterator over the keys of dict d.

Parameters:
  • d (dict) – Dictionary to iterate over
  • kw – The function of this parameter is unclear.
six_util.iteritems(d, **kw)[source]

This function returns an iterator over the (key, value) pairs of dict d.

Parameters:
  • d (dict) – Dictionary to iterate over
  • kw – The function of this parameter is unclear.
six_util.itervalues(d, **kw)[source]

This function returns an iterator over the values of dict d.

Parameters:
  • d (dict) – Dictionary to iterate over
  • kw – The function of this parameter is unclear.

species

Divides the population into species based on genomic distances.

class species.Species(key, generation)[source]

Represents a species and contains data about it such as members, fitness, and time stagnating. Note: stagnation.DefaultStagnation manipulates many of these.

Parameters:
update(representative, members)[source]

Required interface method. Updates a species instance with the current members and most-representative member (from which genomic distances are measured).

Parameters:
  • representative (object) – A genome instance.
  • members – A dictionary of genome id vs genome instance.
get_fitnesses()[source]

Required interface method (used by stagnation.DefaultStagnation, for instance). Retrieves the fitnesses of each member genome.

Returns:List of fitnesses of member genomes.
Return type:list(float)
class species.GenomeDistanceCache(config)[source]

Caches (indexing by genome key/id) genomic distance information to avoid repeated lookups. (The distance function is among the most time-consuming parts of the library, although many fitness functions are likely to far outweigh this for moderate-size populations.)

Parameters:config (object) – A genome configuration object; later used by the genome distance function.
__call__(genome0, genome1)[source]

GenomeDistanceCache is called as a method with a pair of genomes to retrieve the distance.

Parameters:
  • genome0 (object) – The first genome object.
  • genome1 (object) – The second genome object.
Returns:

The genomic distance.

Return type:

float

class species.DefaultSpeciesSet(config, reporters)[source]

Encapsulates the default speciation scheme by configuring it and performing the speciation function (placing genomes into species by genetic similarity). reproduction.DefaultReproduction currently depends on this having a species attribute consisting of a dictionary of species keys to species.

Parameters:
classmethod parse_config(param_dict)[source]

Required interface method. Currently, the only configuration parameter is the compatibility_threshold. TODO: Use a separate configuration class, for consistency with other types (done in the config_work branch).

Parameters:param_dict (dict(str, str)) – Dictionary of parameters from configuration file.
Returns:Configuration object; considered opaque by rest of code, so current type returned is not required for interface.
Return type:dict
classmethod write_config(f, param_dict)[source]

Required interface method. Writes parameter(s) to new config file.

Parameters:
  • f (file) – File object to write to.
  • param_dict (dict) – Dictionary of current parameters in this implementation; more generally, stagnation config object.
speciate(config, population, generation)[source]

Required interface method. Place genomes into species by genetic similarity (genomic distance). (The current code has a docstring stating that there may be a problem if all old species representatives are not dropped for each generation; it is not clear how this is consistent with the code in reproduction.DefaultReproduction.reproduce(), such as for elitism.)

Parameters:
get_species_id(individual_id)[source]

Required interface method (used by reporting.StdOutReporter). Retrieves species id/key for a given genome id/key.

Parameters:individual_id (int) – Genome id/key.
Returns:Species id/key.
Return type:int
get_species(individual_id)[source]

Retrieves species object for a given genome id/key. May become a required interface method, and useful for some fitness functions already.

Parameters:individual_id (int) – Genome id/key.
Returns:Species containing the genome corresponding to the id/key.
Return type:object

Note

TODO: Currently, depending on the settings for species_fitness_func and fitness_criterion, it is possible for a species with members above the fitness_threshold level of fitness to be considered “stagnant” (including, most problematically, because they are at the limit of fitness improvement).

stagnation

class stagnation.DefaultStagnation(config, reporters)[source]

Keeps track of whether species are making progress and helps remove ones that, for a configurable number of generations, are not.

Parameters:
  • config (object) – Configuration object; in this implementation, a dictionary, but should be treated as opaque outside this class.
  • reporters (object) – A ReporterSet instance with reporters that may need activating; not currently used.
classmethod parse_config(param_dict)[source]

Required interface method. Provides defaults for species_fitness_func, max_stagnation, and species_elitism parameters and updates them from the configuration file. TODO: Use a separate configuration class, for consistency with other types (done in the config_work branch).

Parameters:param_dict (dict(str, str)) – Dictionary of parameters from configuration file.
Returns:Configuration object; considered opaque by rest of code, so current type returned is not required for interface.
Return type:dict
classmethod write_config(f, param_dict)[source]

Required interface method. Saves parameters to new config file. TODO: Has a default of 15 for species_elitism, but will be overridden by the default of 0 in parse_config (fixed in the config_work branch).

Parameters:
  • f (file) – File object to write to.
  • param_dict (dict) – Dictionary of current parameters in this implementation; more generally, stagnation config object.
update(species_set, generation)[source]

Required interface method. Updates species fitness history information, checking for ones that have not improved in max_stagnation generations, and - unless it would result in the number of species dropping below the configured species_elitism if they were removed, in which case the highest-fitness species are spared - returns a list with stagnant species marked for removal. TODO: Currently interacts directly with the internals of the species.Species object. Also, currently both checks for num_non_stagnant to stop marking stagnant and does not allow the top species_elitism species to be marked stagnant. While the latter could admittedly help with the problem mentioned above, the ordering of species fitness is using the fitness gotten from the species_fitness_func (and thus may miss high-fitness members of overall low-fitness species, depending on the function in use).

Parameters:
Returns:

A list of tuples of (species id/key, Species object, is_stagnant).

Return type:

list(tuple(int, object, bool))

Changed in version 0.91-github: Species sorted to avoid marking best-performing as stagnant even with species_elitism.

statistics

Note

There are two design decisions to be aware of: * The most-fit genomes are based on the highest-fitness member of each generation; other genomes are not saved by this module (if they were, it would far worsen existing potential memory problems - see below), and it is assumed that fitnesses (as given by the fitness function) are not relative to others in the generation (also assumed by the use of the fitness threshold as a signal for exiting). Code violating this assumption (e.g., with competitive coevolution) will need to use different statistical gathering methods. * Generally reports or records a per-generation list of values; the numeric position in the list may not correspond to the generation number if there has been a restart, such as via the checkpoint module. There is also a TODO item: Currently keeps accumulating information in memory, which may be a problem in long runs.

class statistics.StatisticsReporter(BaseReporter)[source]

Gathers (via the reporting interface) and provides (to callers and/or to a file) the most-fit genomes and information on genome and species fitness and species sizes.

post_evaluate(config, population, species, best_genome)[source]

Called as part of the reporting.BaseReporter interface after the evaluation at the start of each generation; see BaseReporter.post_evaluate. Information gathered includes a copy of the best genome in each generation and the fitnesses of each member of each species.

get_fitness_stat(f)[source]

Calls the given function on the genome fitness data from each recorded generation and returns the resulting list.

Parameters:f (function) – A function that takes a list of scores and returns a summary statistic (or, by returning a list or tuple, multiple statistics) such as mean or stdev.
Returns:A list of the results from function f for each generation.
Return type:list
get_fitness_mean()[source]

Gets the per-generation average fitness. A wrapper for get_fitness_stat() with the function being mean.

Returns:List of mean genome fitnesses for each generation.
Return type:list(float)
get_fitness_stdev()[source]

Gets the per-generation standard deviation of the fitness. A wrapper for get_fitness_stat() with the function being stdev.

Returns:List of standard deviations of genome fitnesses for each generation.
Return type:list(float)
best_unique_genomes(n)[source]

Returns the n most-fit genomes, with no duplication (from the most-fit genome passing unaltered to the next generation), sorted in decreasing fitness order.

Parameters:n (int) – Number of most-fit genomes to return.
Returns:List of n most-fit genomes (as genome objects).
Return type:list(object)
best_genomes(n)[source]

Returns the n most-fit genomes, possibly with duplicates, sorted in decreasing fitness order.

Parameters:n (int) – Number of most-fit genomes to return.
Returns:List of n most-fit genomes (as genome objects).
Return type:list(object)
best_genome()[source]

Returns the most-fit genome ever seen. A wrapper around best_genomes().

Returns:The most-fit genome.
Return type:object
get_species_sizes()[source]

Returns a by-generation list of lists of species sizes. Note that some values may be 0, if a species has either not yet been seen or has been removed due to stagnation; species without generational overlap may be more similar in genomic distance than the configured compatibility_threshold would otherwise allow.

Returns:List of lists of species sizes, ordered by species id/key.
Return type:list(list(int))
get_species_fitness(null_value='')[source]

Returns a by-generation list of lists of species fitnesses; the fitness of a species is determined by the mean fitness of the genomes in the species, as with the reproduction distribution by reproduction.DefaultReproduction. The null_value parameter is used for species not present in a particular generation (see above).

Parameters:null_value (str) – What to put in the list if the species is not present in a particular generation.
Returns:List of lists of species fitnesses, ordered by species id/key.
Return type:list(list(float or str))
save_genome_fitness(delimiter=' ', filename='fitness_history.csv', with_cross_validation=False)[source]

Saves the population’s best and mean fitness (using the csv package). At some point in the future, cross-validation fitness may be usable (via, for instance, the fitness function using alternative test situations/opponents and recording this in a cross_fitness attribute; this can be used for, e.g., preventing overfitting); currently, with_cross_validation should always be left at its False default.

Parameters:
  • delimiter (str) – Delimiter between columns in the file; note that the default is not ‘,’ as may be otherwise implied by the csv file extension (which refers to the package used).
  • filename (str) – The filename to open (for writing, not appending) and write to.
  • with_cross_validation (bool) – For future use; currently, leave at its False default.
save_species_count(delimiter=' ', filename='speciation.csv')[source]

Logs speciation throughout evolution, by tracking the number of genomes in each species. Uses get_species_sizes(); see that method for more information.

Parameters:
  • delimiter (str) – Delimiter between columns in the file; note that the default is not ‘,’ as may be otherwise implied by the csv file extension (which refers to the csv package used).
  • filename (str) – The filename to open (for writing, not appending) and write to.
save_species_fitness(delimiter=' ', null_value='NA', filename='species_fitness.csv')[source]

Logs species’ mean fitness throughout evolution. Uses get_species_fitness(); see that method for more information on, for instance, null_value.

Parameters:
  • delimiter (str) – Delimiter between columns in the file; note that the default is not ‘,’ as may be otherwise implied by the csv file extension (which refers to the csv package used).
  • null_value (str) – See get_species_fitness().
  • filename (str) – The filename to open (for writing, not appending) and write to.
save()[source]

A wrapper for save_genome_fitness(), save_species_count(), and save_species_fitness(); uses the default values for all three.

Table of Contents