Module summaries

activations

Has the built-in activation functions, code for using them, and code for adding new user-defined ones. For the built-in activation functions, see Overview of builtin activation functions.

exception activations.InvalidActivationFunction(Exception)

Exception called if an activation function being added is invalid according to the multiparameter.MultiParameterSet.add_func() method, or if an unknown activation function is requested by name via get.

Deprecated since version 0.92-multiparam_funcs: This is now an alias for multiparameter.BadFunctionError. Use either it, or preferably one of its two subclasses, multiparameter.InvalidFunctionError (for unusable functions; based on TypeError) or multiparameter.UnknownFunctionError (for unknown functions requested by name; based on LookupError).

class activations.ActivationFunctionSet

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

add(name, function)

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

Parameters:

• name (str) – The name by which the function is to be known in the configuration file.
• function (function) – The function to be added.

get(name)

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

Parameters:name (str) – The name of the function. Returns:The function of interest Return type:function Raises:UnknownFunctionError – If the function is not known.

is_valid(name)

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

Changed in version 0.92-multiparam_funcs: Most functionality of ActivationFunctionSet moved to multiparameter.

aggregations

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

Note

Non-enabled connections will, by all methods currently included in NEAT-Python, not be included among the numbers input to these functions, even as 0s.

aggregations.product_aggregation(x)

An adaptation of the multiplication function to take an iterable.

Parameters:x (list(float) or tuple(float) or set(float)) – The numbers to be multiplied together; takes any iterable. Returns:\(\prod(x)\) Return type:float

aggregations.sum_aggregation(x)

Probably the most commonly-used aggregation function.

Parameters:x (list(float) or tuple(float) or set(float)) – The numbers to find the sum of; takes any iterable. Returns:\(\sum(x)\) Return type:float

aggregations.max_aggregation(x)

Returns the maximum of the inputs.

Parameters:x (list(float) or tuple(float) or set(float)) – The numbers to find the greatest of; takes any iterable. Returns:\(\max(x)\) Return type:float

aggregations.min_aggregation(x)

Returns the minimum of the inputs.

Parameters:x (list(float) or tuple(float) or set(float)) – The numbers to find the least of; takes any iterable. Returns:\(\min(x)\) Return type:float

aggregations.maxabs_aggregation(x)

Returns the maximum by absolute value, which may be positive or negative. Envisioned as suitable for neural network pooling operations.

Parameters:x (list(float) or tuple(float) or set(float)) – The numbers to find the absolute-value maximum of; takes any iterable. Returns:\(x_i, i = \text{argmax}\lvert\mathbf{x}\rvert\) Return type:float

New in version 0.92.

aggregations.median_aggregation(x)

Returns the median of the inputs.

Parameters:x (list(float) or tuple(float) or set(float)) – The numbers to find the median of; takes any iterable. Returns:The median; if there are an even number of inputs, takes the mean of the middle two. Return type:float

New in version 0.92.

aggregations.mean_aggregation(x)

Returns the arithmetic mean. Potentially maintains a more stable result than sum for changing numbers of enabled connections, which may be good or bad depending on the circumstances; having both available to the algorithm is advised.

Parameters:x (list(float) or tuple(float) or set(float)) – The numbers to find the mean of; takes any iterable. Returns:The arithmetic mean. Return type:float

New in version 0.92.

aggregations.tmean_aggregation(x)

Returns the trimmed mean, with 25% of the values being trimmed off each end.

Parameters:x (list(float) or tuple(float) or set(float)) – The numbers to find the trimmed mean of; takes any iterable. Returns:The trimmed arithmetic mean. Return type:float

New in version 0.92-multiparam_funcs.

aggregations.maxabs_mean_aggregation(x, a)

A multiparameter aggregation function; the weighted mean of the maxabs_aggregation() and mean_aggregation(), with the weighing determined by the evolved a parameter. If a is 1.0, then maxabs is used; if a is 0.0, then mean is used.

Parameters:

• x (list(float) or tuple(float) or set(float)) – The numbers to aggregate; takes any iterable.
• a (float) – Determines the relative weights of maxabs and mean; must be between 0.0 and 1.0, inclusive.

Returns:

The weighted mean of the maxabs and mean aggregation functions.

Return type:

float

Raises:

ValueError – If a is outside of 0.0-1.0.

New in version 0.92-multiparam_funcs.

aggregations.multiparam_tmean_aggregation(x, a)

A multiparameter aggregation function; in this case, the evolved a term is used for the trim parameter of tmean.

Parameters:

• x (list(float) or tuple(float) or set(float)) – The numbers to aggregate; takes any iterable.
• a (float) – Determines the trim parameter used; must be between 0.0 and 0.5, inclusive.

Returns:

The trimmed mean of the data.

Return type:

float

Raises:

ValueError – If a is outside of 0.0-0.5.

New in version 0.92-multiparam_funcs.

aggregations.maxabs_tmean_aggregation(x, a)

A multiparameter aggregation function; if the evolved a term is 0.0 or above, maxabs_mean_aggregation() is called; if a is below 0.0, then multiparam_tmean_aggregation() is called, with a = abs(a/2). Recommended for ``pooling`` use by neural networks.

Parameters:

• x (list(float) or tuple(float) or set(float)) – The numbers to aggregate; takes any iterable.
• a (float) – Determines the balance between maxabs, mean, tmean, and median; must be between -1.0 and 1.0, inclusive.

Returns:

The combination of the inputs according to the a parameter.

Return type:

float

Raises:

ValueError – If a is outside of -1.0-1.0.

New in version 0.92-multiparam_funcs.

aggregations.sum_product_aggregation(x, a)

A multiparameter aggregation function; the evolved a term determines the weights in the weighted mean of the sum_aggregation() and product_aggregation() functions. Recommended as a more flexible replacement for both sum and product.

Parameters:

• x (list(float) or tuple(float) or set(float)) – The numbers to aggregate; takes any iterable.
• a (float) – Determines the balance between sum and product; must be between 0.0 and 1.0, inclusive.

Returns:

The combination of the inputs according to the a parameter.

Return type:

float

Raises:

ValueError – If a is outside of 0.0-1.0.

New in version 0.92-multiparam_funcs.

aggregations.max_median_min_aggregation(x, a)

A multiparameter aggregation function; the evolved a term determines the weights in the weighted mean of the max, median, and min aggregation functions. While meant primarily for CPPNs, could be of use in other circumstances.

Parameters:

• x (list(float) or tuple(float) or set(float)) – The numbers to aggregate; takes any iterable.
• a (float) – Determines the balance between max, median, and min; must be between -1.0 and 1.0, inclusive.

Returns:

The combination of the inputs according to the a parameter.

Return type:

float

Raises:

ValueError – If a is outside of -1.0-1.0.

New in version 0.92-multiparam_funcs.

aggregations.sum_mean_aggregation(x, a)

A multiparameter aggregation function; the evolved a term determines a compromise between the sum and mean aggregation functions. (Intermediate functions are created by dividing by less than the number of inputs (as for mean) but more than 1 (as for sum).)

Parameters:

• x (list(float) or tuple(float) or set(float)) – The numbers to aggregate; takes any iterable.
• a (float) – Determines the balance between sum and arithmetic mean; must be between 0.0 and 1.0, inclusive.

Returns:

The combination of the inputs according to the a parameter.

Return type:

float

Raises:

ValueError – If a is outside of 0.0-1.0.

New in version 0.92-multiparam_funcs.

aggregations.product_mean_aggregation(x, a, use_median)

A multiparameter aggregation function; the evolved a term determines a compromise between the product aggregation function and a geometric mean. Since it is desired to avoid complex numbers resulting from taking the roots of negative numbers, the root is taken of the absolute value of the inputs’ product; the evolved use_median boolean term determines whether the sign of the result is taken from the median of the inputs or the product of the inputs.

Parameters:

• x (list(float) or tuple(float) or set(float)) – The numbers to aggregate; takes any iterable.
• a (float) – Determines the balance between product and geometric mean; must be between 0.0 and 1.0, inclusive.
• use_median (bool) – Whether to use the median (if True) or the product (if False) of the inputs to determine the sign.

Returns:

The combination of the inputs according to the a and use_median parameters.

Return type:

float

Raises:

• ValueError – If a is not in 0.0-1.0.
• TypeError – If use_median is not a boolean.

New in version 0.92-multiparam_funcs.

aggregations.sum_product_mean_aggregation(x, a, b, use_median)

A multiparameter aggregation function; the evolved b term determines the weights of the weighted mean of the sum_mean_aggregation() and product_mean_aggregation() functions, while the other two evolved terms (a and use_median) are inputs to those two aggregation functions (only for product_mean_aggregation for use_median).

Parameters:

• x (list(float) or tuple(float) or set(float)) – The numbers to aggregate; takes any iterable.
• a (float) – Determines the balance between sum and arithmetic mean and/or between product and geometric mean, depending on b; must be between 0.0 and 1.0, inclusive.
• b (float) – Determines the balance between the sum_mean_aggregation and product_mean_aggregation functions.
• use_median (bool) – Input into product_mean_aggregation().

Returns:

The combination of the inputs according to the a, b, and use_median parameters.

Return type:

float

Raises:

• ValueError – If a or b is not in 0.0-1.0.
• TypeError – If use_median is not a boolean.

New in version 0.92-multiparam_funcs.

exception aggregations.InvalidAggregationFunction(Exception)

Exception called if an aggregation function being added is invalid according to the multiparameter.MultiParameterSet.add_func() method, or if an unknown aggregation function is requested by name via get.

New in version 0.92.

Deprecated since version 0.92-multiparam_funcs: This is now an alias for multiparameter.BadFunctionError. Use either it, or preferably one of its two subclasses, multiparameter.InvalidFunctionError (for unusable functions; based on TypeError) or multiparameter.UnknownFunctionError (for unknown functions requested by name; based on LookupError).

class aggregations.AggregationFunctionSet

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

add(name, function)

After validating the function, adds it to the available aggregation functions under the given name. Used by DefaultGenomeConfig.add_aggregation. TODO: Check for whether the function needs reduce, or at least offer a form of this function (or extra argument for it, defaulting to false), and/or its interface in genome, that will appropriately “wrap” the input function.

Parameters:

• name (str) – The name by which the function is to be known in the configuration file.
• function (function) – The function to be added.

New in version 0.92.

get(name)

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

Parameters:name (str) – The name of the function. Returns:The function of interest Return type:function Raises:UnknownFunctionError – If the function is not known.

New in version 0.92.

Changed in version 0.92-multiparam_funcs: Changed from InvalidAggregationFunction to multiparameter.UnknownFunctionError.

__getitem__(index)

Present for compatibility with older programs that expect the aggregation functions to be in a dict. A wrapper for get(index).

Parameters:

index (str) – The name of the function.

Returns:

The function of interest.

Return type:

function

Raises:

• UnknownFunctionError – If the function is not known.
• DeprecationWarning – Always.

Changed in version 0.92: Originally a dictionary in genome.

Deprecated since version 0.92: Use get(index) instead.

is_valid(name)

Checks whether the named function is a known aggregation function.

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

New in version 0.92.

Changed in version 0.92: Moved from genome and expanded to match activations (plus the maxabs, median, and mean functions added).

Changed in version 0.92-multiparam_funcs: Most functionality of AggregationFunctionSet moved to multiparameter.

attributes

Deals with attributes used by genes.

class attributes.BaseAttribute(name, **default_dict)

Superclass for the type-specialized attribute subclasses, used by genes (such as via the genes.BaseGene implementation). Updates _config_items with any defaults supplied, then uses config_item_name to set up a listing of the names of configuration items using setattr.

Parameters:

• name (str) – The name of the attribute, held in the instance’s name attribute.
• default_dict (dict(str, str)) – An optional dictionary of defaults for the configuration items.

Changed in version 0.92: Default_dict capability added.

config_item_name(config_item_base_name)

Formats a configuration item’s name by combining the attribute’s name with the base item name.

Parameters:config_item_base_name (str) – The base name of the configuration item, to be combined with the attribute’s name. Returns:The configuration item’s full name. Return type:str

Changed in version 0.92: Originally (as config_item_names) did not take any input and returned a list based on the _config_items subclass attribute.

get_config_params()

Uses config_item_name for each configuration item to get the name, then gets the appropriate type of config.ConfigParameter instance for each (with any appropriate defaults being set from _config_items, including as modified by BaseAttribute) and returns it.

Returns:A list of ConfigParameter instances. Return type:list(instance)

Changed in version 0.92: Was originally specific for the attribute subclass, since it did not pick up the appropriate type from the _config_items list; default capability also added.

class attributes.FloatAttribute(BaseAttribute)

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

clamp(value, config)

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 (instance) – 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)

Initializes the attribute’s value, using either a gaussian distribution with the configured mean and standard deviation, followed by clamp to keep the result within the desired range, or a uniform distribution, depending on the configuration setting of init_type.

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

Changed in version 0.92: Uniform distribution initialization option added.

mutate_value(value, config)

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).

Parameters:

• value (float) – The current value of the attribute.
• config (instance) – 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)

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

init_value(config)

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

Deprecated since version 0.92: While it is possible to use “None” as an equivalent to “random”, this is too easily confusable with an actual None.

Changed in version 0.92: Ability to use “random” for a 50/50 chance of True or False added.

Parameters:config (instance) – The configuration object from which the default parameter is to be retrieved. Returns:The new value. Return type:bool Raises:RuntimeError – If the default value is not recognized as standing for any of True, False, “random”, or “none”.

mutate_value(value, config)

With a frequency determined by the mutate_rate and rate_to_false_add or rate_to_true_add configuration parameters, replaces the value with a 50/50 chance of True or False; note that this has a 50% chance of leaving the value unchanged.

Parameters:

• value (bool) – The current value of the attribute.
• config (instance) – The configuration object from which the mutate_rate and other parameters are to be extracted.

Returns:

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

Return type:

bool

Changed in version 0.92: Added the rate_to_false_add and rate_to_true_add parameters.

class attributes.StringAttribute(BaseAttribute)

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

init_value(config)

Initializes the attribute’s value, either using a configured default or (if the default is “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.

Deprecated since version 0.92: While it is possible to use “None” as an equivalent to “random”, this is too easily confusable with an actual None.

Parameters:config (instance) – 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)

With a frequency determined by the mutate_rate configuration parameter, replaces the value with 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: Add configurable probabilities of which option is used. Longer-term, 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.

Parameters:

• value (str) – The current value of the attribute.
• config (instance) – The configuration object from which the options and other parameters are to be extracted.

Returns:

The new value.

Return type:

str

class attributes.FuncAttribute(BaseAttribute)

Handle attributes that may be simple strings or may be functions needing multiparameter handling.

New in version 0.92-multiparam_funcs.

init_value(config)

Initializes the attribute’s value, either using a configured default or (if the default is “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.

Deprecated since version 0.92: While it is possible to use “None” as an equivalent to “random”, this is too easily confusable with an actual None.

New in version 0.92-multiparam_funcs.

param config:The configuration object from which the default and, if necessary, options parameters are to be retrieved. type config:instance return:The new value. rtype:str or function raises RuntimeError:  If the default is neither an object with an init_value attribute nor a string.

mutate_value(value, config)

With a frequency determined by the mutate_rate configuration parameter, replaces the value with 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: Add configurable probabilities of which option is used. Longer-term, 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.

Parameters:

• value (str or function) – The current value of the attribute.
• config (instance) – The configuration object from which the options and other parameters are to be extracted.

Returns:

The new value.

Return type:

str or function

Raises:

RuntimeError – If the chosen option is neither an object with a mutate_value attribute nor a string.

New in version 0.92-multiparam_funcs.

Changed in version 0.92: __config_items__ changed to _config_items, since it is not a Python internal variable.

checkpoint

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

Note

The speed of this module can vary widely between python implementations (and perhaps versions).

class checkpoint.Checkpointer(generation_interval=100, time_interval_seconds=300, filename_prefix='neat-checkpoint-')

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.) The start of the filename will be equal to filename_prefix, followed by the generation number. If there is a need to check the last generation for which a checkpoint was saved, such as to determine which file to load, access last_generation_checkpoint; if -1, none have been saved.

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.
• filename_prefix (str) – The prefix for the checkpoint file names.

start_generation(generation)

Saves the current generation number for use by save_checkpoint().

Parameters:generation (int) – Current generation.

end_generation(config, population, species_set)

Checks to see whether save_checkpoint() needs to be called, and if so calls it, then updates the last_generation_checkpoint and the corresponding last_time_checkpoint attributes.

Parameters:

• config (instance) – The config.Config configuration instance to be used.
• population (dict(int, object)) – A population as created by reproduction.DefaultReproduction.create_new() or a compatible implementation.
• species (instance) – A species.DefaultSpeciesSet (or compatible implementation) instance.

save_checkpoint(config, population, species, generation)

Saves the current simulation state (including randomization state) to (if using the default neat-checkpoint- for filename_prefix) neat-checkpoint-generation, with generation being the generation number.

Parameters:

• config (instance) – The config.Config configuration instance to be used.
• population (dict(int, object)) – A population as created by reproduction.DefaultReproduction.create_new() or a compatible implementation.
• species (instance) – A species.DefaultSpeciesSet (or compatible implementation) instance.
• generation (int) – The generation number.

static restore_checkpoint(filename)

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:Population instance that can be used with Population.run to restart the simulation. Return type:instance

config

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

class config.ConfigParameter(name, value_type, default=None)

Does initial handling of a particular configuration parameter.

Parameters:

• name (str) – The name of the configuration parameter.
• value_type – The type that the configuration parameter should be; must be one of str, int, bool, float, or list.
• default (str or None) – If given, the default to use for the configuration parameter.

Changed in version 0.92: Default capability added.

__repr__()

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

Returns:Representation as for repr. Return type:str

parse(section, config_parser)

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 (instance) – The configuration parser to be used.

Returns:

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

Return type:

str or list(str)

interpret(config_dict)

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(str, str)) – Configuration parameters as output by the configuration parser.

Returns:

The configuration parameter value

Return type:

str or int or bool or float or list(str)

Raises:

• RuntimeError – If there is a problem with the configuration parameter.
• DeprecationWarning – If a default is used.

Changed in version 0.92: Default capability added.

format(value)

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. Returns:String version. Return type:str

config.write_pretty_params(f, config, params)

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

Parameters:

• f (file) – File object to be written to.
• config (instance) – Configuration object from which parameter values are to be fetched (using getattr).
• params (list(instance)) – List of ConfigParameter instances giving the names of interest and the types of parameters.

exception config.UnknownConfigItemError(NameError)

Error for unknown configuration option(s) - partially to catch typos. TODO: genome.DefaultGenomeConfig does not currently check for these.

New in version 0.92.

class config.DefaultClassConfig(param_dict, param_list)

Replaces at least some boilerplate configuration code for reproduction, species_set, and stagnation classes.

Parameters:

• param_dict (dict(str, str)) – Dictionary of configuration parameters from config file.
• param_list (list(instance)) – List of ConfigParameter instances; used to know what parameters are of interest to the calling class.

Raises:

UnknownConfigItemError – If a key in param_dict is not among the names in param_list.

classmethod write_config(f, config)

Required method (inherited by calling classes). Uses write_pretty_params() to output parameters of interest to the calling class.

Parameters:

• f (file) – File object to be written to.
• config (instance) – DefaultClassConfig instance.

New in version 0.92.

class config.Config(genome_type, reproduction_type, species_set_type, stagnation_type, filename)

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, which are found as some of its attributes. For a description of the configuration file, see Configuration file description. The __name__ attributes of the _type parameters are used for the titles of the configuration file sections. A Config instance’s genome_config, species_set_config, stagnation_config, and reproduction_config attributes hold the configuration objects for the respective classes.

Parameters:

• genome_type (class) – Specifies the genome class used, such as genome.DefaultGenome or iznn.IZGenome. See Genome Interface for the needed interface.
• reproduction_type (class) – Specifies the reproduction class used, such as reproduction.DefaultReproduction. See Reproduction Interface for the needed interface.
• species_set_type (class) – Specifies the species set class used, such as species.DefaultSpeciesSet.
• stagnation_type (class) – Specifies the stagnation class used, such as stagnation.DefaultStagnation.
• filename (str) –

  Pathname for configuration file to be opened, read, processed by a parser from the configparser.ConfigParser class (or, for 2.7, the ConfigParser.SafeConfigParser class), the NEAT section handled by Config, and then other sections passed to the parse_config methods of the appropriate classes.

Raises:

• AssertionError – If any of the _type classes lack a parse_config method.
• UnknownConfigItemError – If an option in the NEAT section of the configuration file is not recognized.
• DeprecationWarning – If a default is used for one of the NEAT section options.

Changed in version 0.92: Added default capabilities, UnknownConfigItemError, no_fitness_termination.

save(filename)

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. (A comparison of it and the input configuration file can be used to determine any default parameters of interest.)

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

ctrnn

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

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

Parameters:

• time_constant (float) – Controls how fast the node responds; \(\tau_i\) from Continuous-time recurrent neural network implementation.
• activation (function) – Activation function for the node.
• aggregation (function) – Aggregation function for the node.
• bias (float) – Bias for the node.
• response (float) – Response multiplier for the node.
• links (list(tuple(int,float))) – List of other nodes providing input, as tuples of (input key, weight)

class ctrnn.CTRNN(inputs, outputs, node_evals)

Sets up the ctrnn network itself.

reset()

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

set_node_value(node_key, value)

Sets the current node activation for the particular node selected.

Parameters:

• node_key (int) – The key for the node to be altered.
• value (float) – What to set the activation of the node to.

get_max_time_step()

Planned to return the maximum time step that will be stable for the current network; not yet implemented.

Raises:NotImplementedError – Always.

advance(inputs, advance_time, time_step=None)

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(float)) – The values for the input nodes.
• advance_time (float) – How much time to advance the network before returning the resulting outputs.
• time_step (float or None) – 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 using get_max_time_step().

Returns:

The values for the output nodes.

Return type:

list(float)

Raises:

• NotImplementedError – If a time_step is not given.
• RuntimeError – If the number of inputs does not match the number of input nodes

Changed in version 0.92: Exception changed to more-specific RuntimeError.

static create(genome, config, time_constant)

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

Parameters:

• genome (instance) – A genome.DefaultGenome instance.
• config (instance) – A config.Config instance.
• time_constant (float) – Used for the CTRNNNodeEval initializations.

distributed

Distributed evaluation of genomes.

Note

This module is in a beta state, and still unstable even in single-machine testing. Reliability is likely to vary, including depending on the Python version and implementation (e.g., cpython vs pypy) in use and the likelihoods of timeouts (due to machine and/or network slowness). In particular, while the code can try to reconnect between between primary and secondary nodes, as noted in the multiprocessing documentation this may not work due to data loss/corruption. Note also that this module is not responsible for starting the script copies on the different compute nodes, since this is very site/configuration-dependent.

About compute nodes:

The primary compute node (the node which creates and mutates genomes) and the secondary compute nodes (the nodes which evaluate genomes) can execute the same script. The role of a compute node is determined using the mode argument of the DistributedEvaluator. If the mode is MODE_AUTO, the host_is_local() function is used to check if the addr argument points to the localhost. If it does, the compute node starts as a primary node, and otherwise as a secondary node. If mode is MODE_PRIMARY, the compute node always starts as a primary node. If mode is MODE_SECONDARY, the compute node will always start as a secondary node.

There can only be one primary node per NEAT, but any number of secondary nodes. The primary node will not evaluate any genomes, which means you will always need at least two compute nodes (one primary and at least one secondary).

You can run any number of compute nodes on the same physical machine (or VM). However, if a machine has both a primary node and one or more secondary nodes, MODE_AUTO cannot be used for those secondary nodes - MODE_SECONDARY will need to be specified.

Usage:

1. Import modules and define the evaluation logic (the eval_genome function). (After this, check for if __name__ == '__main__', and put the rest of the code inside the body of the statement, or in subroutines called from it.)
2. Load config and create a population - here, the variable p.
3. If required, create and add reporters.
4. Create a DistributedEvaluator(addr_of_primary_node, b'some_password', eval_function, mode=MODE_AUTO) - here, the variable de.
5. Call de.start(exit_on_stop=True). The start() call will block on the secondary nodes and call sys.exit(0) when the NEAT evolution finishes. This means that the following code will only be executed on the primary node.
6. Start the evaluation using p.run(de.evaluate, number_of_generations).
7. Stop the secondary nodes using de.stop().
8. You are done. You may want to save the winning genome(s) or show some statistics.

See examples/xor/evolve-feedforward-distributed.py for a complete example.

Note

The below contains some (but not complete) information about private functions, classes, and similar (starting with _); this documentation is meant to help with maintaining and improving the code, not for enabling external use, and the interface may change rapidly with no warning.

distributed.MODE_AUTO

distributed.MODE_PRIMARY

distributed.MODE_SECONDARY

Values - which should be treated as constants - that are used for the mode argument of DistributedEvaluator. If MODE_AUTO, _determine_mode() uses host_is_local() and the specified addr of the primary node to decide the mode; the other two specify it.

distributed._EXCEPTION_TYPE_OK

distributed._EXCEPTION_TYPE_UNCERTAIN

distributed._EXCEPTION_TYPE_BAD

Values - which should be treated as constants - that are returned by the _check_exception() function. The first is for a queue being empty and similar reasons to try again. The second indicates likely disconnection, but should try to reconnect. The third includes all other cases, and is responded to in the calling code by either immediately raising the exception again, or returning and exiting with a non-zero exit (status) value.

exception distributed.ModeError(RuntimeError)

An exception raised when a mode-specific method is being called without being in the mode - either a primary-specific method called by a secondary node or a secondary-specific method called by a primary node.

distributed.host_is_local(hostname, port=22)

Returns True if the hostname points to the localhost (including shares addresses), otherwise False.

Parameters:

• hostname (str) – The hostname to be checked; will be put through socket.getfqdn.
• port (int) – The optional port for socket functions requiring one. Defaults to 22, the ssh port.

Returns:

Whether the hostname appears to be equivalent to that of the localhost.

Return type:

bool

distributed._determine_mode(addr, mode)

Returns the mode that should be used. If mode is MODE_AUTO, this is determined by checking (via host_is_local()) if addr points to the localhost; if it does, it returns MODE_PRIMARY, else it returns MODE_SECONDARY. If mode is either MODE_PRIMARY or MODE_SECONDARY, it returns the mode argument. Otherwise, a ValueError is raised.

Parameters:

• addr (tuple(str, int) or bytes) – Either a tuple of (hostname, port) pointing to the machine that has the primary node, or the hostname (as bytes if on 3.X).
• mode (int) – Specifies the mode to run in - must be one of MODE_AUTO, MODE_PRIMARY, or MODE_SECONDARY.

Raises:

ValueError – If the mode is not one of the above.

distributed.chunked(data, chunksize)

Splits up data and returns it as a list of chunks containing at most chunksize elements of data.

Parameters:

• data (list(object) or tuple(object) or set(object)) – The data to split up; takes any iterable.
• chunksize (int) – The maximum number of elements per chunk.

Returns:

A list of chunks containing (as a list) at most chunksize elements of data.

Return type:

list(list(object))

Raises:

ValueError – If chunksize is not 1+ or is not an integer

distributed._check_exception(e)

Evaluates whether an exception should be treated as simply a reason to retry the operation, as indicating a need to reconnect, or as some worse type of error. TODO: Currently, due to problems with the variety of exceptions emitted by the multiprocessing module - particularly due to different versions of Python - attempts in most (but not all) cases to evaluate the exception via repr, looking for keywords, which is uncertain at best. The multiprocessing module in particular has a large number of The assert statement checks, frequently without user messages. Two pull requests have been submitted to correct this for the most problematic portions of the module, in at least the latest (developmental) version of Python (“nightly”), of which one has been accepted thus far; the other is awaiting review.

Parameters:e (instance) – The exception to be evaluated. Returns:One of _EXCEPTION_TYPE_OK, _EXCEPTION_TYPE_UNCERTAIN, or _EXCEPTION_TYPE_BAD. Return type:int

class distributed._ExtendedManager(addr, authkey, mode, start=False)

Manages the multiprocessing.managers.SyncManager instance.

Parameters:

• addr (tuple(str, int)) – Should be a tuple of (hostname, port) pointing to the machine running the DistributedEvaluator in primary mode. If mode is MODE_AUTO, the mode is determined by checking whether the hostname points to this host or not (via _determine_mode() and host_is_local()).
• authkey (bytes) – The password used to restrict access to the manager. All DistributedEvaluators need to use the same authkey. Note that this needs to be a bytes object for Python 3.X, and should be in 2.7 for compatibility (identical in 2.7 to a str object). For more information, see under DistributedEvaluator.
• mode (int) – Specifies the mode to run in - must be one of MODE_AUTO, MODE_PRIMARY, or MODE_SECONDARY. Processed by _determine_mode().
• start (bool) – Whether to call the start() method after initialization.

__reduce__()

Used by pickle to serialize instances of this class.

Returns:Information about the class instance, usable to call __init__() for the class again; a tuple of (class name, tuple(addr, authkey, mode, whether_started)). Return type:tuple(str, tuple(tuple(str, int), bytes, int, bool))

start()

Starts (if in MODE_PRIMARY) or connects to (if in MODE_SECONDARY) the manager.

stop()

Stops the manager; if in MODE_PRIMARY, uses shutdown.

get_inqueue()

Returns the inqueue.

Returns:The incoming queue. Return type:instance Raises:RuntimeError – If the manager has not been started.

get_outqueue()

Returns the outqueue.

Returns:The outgoing queue. Return type:instance Raises:RuntimeError – If the manager has not been started.

get_namespace()

Returns the manager’s namespace instance.

Returns:The namespace. Return type:instance Raises:RuntimeError – If the manager has not been started.

class distributed.DistributedEvaluator(addr, authkey, eval_function, secondary_chunksize=1, num_workers=None, worker_timeout=60, mode=MODE_AUTO)

An evaluator working across multiple machines (compute nodes).

Warning

See Authentication Keys for more on the authkey parameter, used to restrict access to the manager.

Parameters:

• addr (tuple(str, int)) – Should be a tuple of (hostname, port) pointing to the machine running the DistributedEvaluator in primary mode. If mode is MODE_AUTO, the mode is determined by checking whether the hostname points to this host or not (via host_is_local()).
• authkey (bytes) – The password used to restrict access to the manager. All DistributedEvaluators need to use the same authkey. Note that this needs to be a bytes object for Python 3.X, and should be in 2.7 for compatibility (identical in 2.7 to a str object).
• eval_function (function) – The eval_function should take two arguments - a genome object and a 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, nor by ParallelEvaluator (although it is more similar to the latter).
• secondary_chunksize (int) – The number of genomes that will be sent to a secondary node at any one time.
• num_workers (int or None) – The number of worker processes per secondary node, used for evaluating genomes. If None, will use multiprocessing.cpu_count() to determine the number of processes (see further below regarding this default). If 1 (for a secondary node), including if there is no usable result from multiprocessing.cpu_count(), then the process creating the DistributedEvaluator instance will also do the evaluations.
• worker_timeout (float or None) – specifies the timeout (in seconds) for a secondary node getting the results from a worker subprocess; if None, there is no timeout.
• mode (int) – Specifies the mode to run in - must be one of MODE_AUTO (the default), MODE_PRIMARY, or MODE_SECONDARY.

Raises:

ValueError – If the mode is not one of the above.

Note

Whether the default for num_workers is appropriate can vary depending on the evaluation function (e.g., whether cpu-bound, memory-bound, i/o-bound…), python implementation, and other factors; if unsure and maximal per-machine performance is critical, experimentation will be required.

is_primary()

Returns True if the caller is the primary node; otherwise False.

Returns:True if primary, False if secondary Return type:bool

is_master()

A backward-compatibility wrapper for is_primary().

Returns:True if primary, False if secondary Return type:bool Raises:DeprecationWarning – Always.

Deprecated since version 0.92.

start(exit_on_stop=True, secondary_wait=0, reconnect=False)

If the DistributedEvaluator is in primary mode, starts the manager process and returns. If the DistributedEvaluator is in secondary mode, it connects to the manager and waits for tasks.

Parameters:

• exit_on_stop (bool) – If a secondary node, whether to exit if (unless reconnect is True) the connection is lost, the primary calls for a shutdown (via stop()), or - even if reconnect is True - the primary calls for a forced shutdown (via calling stop() with force_secondary_shutdown set to True).
• secondary_wait (float) – Specifies the time (in seconds) to sleep before actually starting, if a secondary node.
• reconnect (bool) – If a secondary node, whether it should try to reconnect if the connection is lost.

Raises:

• RuntimeError – If already started.
• ValueError – If the mode is invalid.

stop(wait=1, shutdown=True, force_secondary_shutdown=False)

Stops all secondaries.

Parameters:

• wait (float) – Time (in seconds) to wait after telling the secondaries to stop.
• shutdown (bool) – Whether to shutdown the multiprocessing.managers.SyncManager also (after the wait, if any).
• force_secondary_shutdown (bool) – Causes secondaries to shutdown even if started with reconnect true.

Raises:

• ModeError – If not the primary node (not in MODE_PRIMARY).
• RuntimeError – If not yet started.

evaluate(genomes, config)

Evaluates the genomes. Distributes the genomes to the secondary nodes, then gathers the fitnesses from the secondary nodes and assigns them to the genomes. Must not be called by secondary nodes. TODO: Improved handling of errors from broken connections with the secondary nodes may be needed.

Parameters:

• genomes (dict(int, instance)) – Dictionary of (genome_id, genome)
• config (instance) – Configuration object.

Raises:

ModeError – If not the primary node (not in MODE_PRIMARY).

New in version 0.92.

genes

Handles node and connection genes.

class genes.BaseGene(key)

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

Parameters:key (int or tuple(int, int)) – The gene identifier. Note: For connection genes, determining whether they are homologous (for genomic distance and crossover determination) uses the (ordered) identifiers of the connected nodes.

__str__()

Converts gene attributes into a printable format.

Returns:Stringified gene instance. Return type:str

__lt__(other)

Allows sorting genes by keys.

Parameters:other (instance) – The other BaseGene instance. Returns:Whether the calling instance’s key is less than that of the other instance. Return type:bool

classmethod parse_config(config, param_dict)

Placeholder; parameters are entirely in gene attributes.

classmethod get_config_params()

Fetches configuration parameters from each gene class’ _gene_attributes list (using BaseAttribute.get_config_params). 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(instance) Raises:DeprecationWarning – If the gene class uses __gene_attributes__ instead of _gene_attributes

init_attributes(config)

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

Parameters:config (instance) – Configuration object to be used by the appropriate attributes class.

mutate(config)

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 (instance) – Configuration object to be used by the appropriate attributes class.

copy()

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

Returns:A copied gene Return type:instance

crossover(gene2)

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 (instance) – 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:instance

class genes.DefaultNodeGene(BaseGene)

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)

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 (instance) – The other DefaultNodeGene.
• config (instance) – 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)

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)

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 (instance) – The other DefaultConnectionGene.
• config (instance) – The genome configuration object.

Returns:

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

Return type:

float

Changed in version 0.92: __gene_attributes__ changed to _gene_attributes, since it is not a Python internal variable. Updates also made due to addition of default capabilities to attributes.

genome

Handles genomes (individuals in the population).

class genome.DefaultGenomeConfig(params)

Does the configuration for the DefaultGenome class. Has 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. The activations.ActivationFunctionSet instance is available via its activation_defs attribute, and the aggregations.AggregationFunctionSet instance is available via its aggregation_defs - or, for compatibility, aggregation_function_defs - attributes. TODO: Check for unused configuration parameters from the config file.

Parameters:params (dict(str, str)) – Parameters from configuration file and DefaultGenome initialization (by parse_config). Raises:RuntimeError – If initial_connection or structural_mutation_surer is invalid.

Changed in version 0.92: Aggregation functions moved to aggregations; additional configuration parameters added.

add_activation(name, func)

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

Parameters:

• name (str) – The name by which the function is to be known in the configuration file.
• func (function) – A function that meets the requirements of multiparameter.MultiParameterSet.add_func().

add_aggregation(name, func)

Adds a new aggregation function. Uses AggregationFunctionSet.add.

Parameters:

• name (str) – The name by which the function is to be known in the configuration file.
• func (function) – A function meeting the requirements of multiparameter.MultiParameterSet.add_func().

New in version 0.92.

save(f)

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. Raises:RuntimeError – If the value for a partial-connectivity configuration is not in [0.0,1.0].

get_new_node_key(node_dict)

Finds the next unused node key. TODO: Explore using the same node key if a particular connection is replaced in more than one genome in the same generation (use a reporting.BaseReporter.end_generation() method to wipe a dictionary of connection tuples versus node keys). One could even extend this beyond one generation, with the removal of the old keys from further use triggered by one of the existing nodes with that key acquiring a new connection. Question: If two nodes are otherwise very different (perhaps as measured by genetic distance, treating them as homologous for purposes of the check), should they still have the same key, even if they replaced the same connection?

Parameters:node_dict (dict(int, instance)) – A dictionary of node keys vs nodes Returns:A currently-unused node key. Return type:int Raises:AssertionError – If a newly-created id is already in the node_dict.

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

get_compatibility_info()

A method to retrieve the current compatibility_disjoint_coefficient and compatibility_weight_coefficient settings. More information may be added.

Returns:A dictionary of, currently, disjoint_coefficient vs the compatibility_disjoint_coefficient and weight_coefficient vs the compatibility_weight_coefficient Return type:dict(str, float)

check_structural_mutation_surer()

Checks vs structural_mutation_surer and, if necessary, single_structural_mutation to decide if changes from the former should happen.

Returns:If should have a structural mutation under a wider set of circumstances. Return type:bool

New in version 0.92.

class genome.DefaultGenome(key)

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)

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(str, str)) – 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:instance

classmethod write_config(f, config)

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

Parameters:

• f (file) – File object to write to.
• config (instance) – Configuration object (here, a DefaultGenomeConfig instance).

configure_new(config)

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 (instance) – Genome configuration object.

configure_crossover(genome1, genome2, config)

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 (instance) – The first parent genome.
• genome2 (instance) – The second parent genome.
• config (instance) – Genome configuration object; currently ignored.

mutate(config)

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. Checks single_structural_mutation for whether more than one structural mutation should be permitted per call. 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 (instance) – Genome configuration object.

Changed in version 0.92: single_structural_mutation config parameter added.

mutate_add_node(config)

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. If there are no connections available, may call mutate_add_connection() instead, depending on the result from check_structural_mutation_surer. TODO: Perhaps exactly how the new connection weights are set up should be configurable, such as each being copysign(old_weight)*sqrt(abs(old_weight))?

Parameters:config (instance) – Genome configuration object.

Changed in version 0.92: Potential addition of connection instead added.

add_connection(config, input_key, output_key, weight, enabled)

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

Parameters:

• config (instance) – Genome configuration object.
• input_key (int) – Key of the connection’s input-side node.
• output_key (int) – Key of the connection’s output-side node.
• weight (float) – The weight the new connection should have.
• enabled (bool) – The enabled attribute the new connection should have.

mutate_add_connection(config)

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. (If an existing connection is selected, it may be enabled depending on the result from check_structural_mutation_surer.) 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 (instance) – Genome configuration object

Changed in version 0.92: Output nodes not allowed to be connected together. Possibility of enabling existing connection added.

mutate_delete_node(config)

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

Parameters:config (instance) – Genome configuration object

mutate_delete_connection()

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)

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. The latter is due to, if the fitness function does not involve interactions between genomes, that there will be only pop_size invocations of the fitness function, but pop_size squared invocations of the distance function. TODO: Enable cython to work better with this function, while retaining compatibility with cpython, pypy, etc.)

Parameters:

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

Returns:

The genomic distance.

Return type:

float

size()

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.

Returns:Genome complexity Return type:tuple(int, int)

__str__()

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

Returns:Node and connection information. Return type:str

static create_node(config, node_id)

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 (instance) – The genome configuration object.
• node_id (int) – The key for the new node.

Returns:

The new node instance.

Return type:

instance

static create_connection(config, input_id, output_id)

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 (instance) – The genome configuration object.
• input_id (int) – The input end node’s key.
• output_id (int) – The output end node’s key.

Returns:

The new connection instance.

Return type:

instance

connect_fs_neat_nohidden(config)

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 (instance) – The genome configuration object.

Changed in version 0.92: Connect_fs_neat, connect_full, connect_partial split up - documentation vs program conflict.

connect_fs_neat_hidden(config)

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 (instance) – The genome configuration object.

Changed in version 0.92: Connect_fs_neat, connect_full, connect_partial split up - documentation vs program conflict.

compute_full_connections(config, direct)

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 (instance) – 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.92: “Direct” added to help with documentation vs program conflict for initial_connection of full or partial.

connect_full_nodirect(config)

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

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

Changed in version 0.92: Connect_fs_neat, connect_full, connect_partial split up - documentation vs program conflict.

connect_full_direct(config)

Create a fully-connected genome, including direct input-output connections even if there are hidden nodes.

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

Changed in version 0.92: Connect_fs_neat, connect_full, connect_partial split up - documentation vs program conflict.

connect_partial_nodirect(config)

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

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

Changed in version 0.92: Connect_fs_neat, connect_full, connect_partial split up - documentation vs program conflict.

connect_partial_direct(config)

Create a partially-connected genome, possibly including direct input-output connections even if there are hidden nodes.

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

Changed in version 0.92: Connect_fs_neat, connect_full, connect_partial split up - documentation vs program conflict.

graphs

Directed graph algorithm implementations.

graphs.creates_cycle(connections, test)

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)

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 set of node identifiers.

Return type:

set(int)

graphs.feed_forward_layers(inputs, outputs, connections)

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

Parameters:

• inputs (list(int)) – the network input node identifiers.
• outputs (list(int)) – the output node identifiers.
• 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 identifiers; only includes nodes returned by required_for_output.

Return type:

list(set(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.

iznn.REGULAR_SPIKING_PARAMS

iznn.INTRINSICALLY_BURSTING_PARAMS

iznn.CHATTERING_PARAMS

iznn.FAST_SPIKING_PARAMS

iznn.THALAMO_CORTICAL_PARAMS

iznn.RESONATOR_PARAMS

iznn.LOW_THRESHOLD_SPIKING_PARAMS

Parameter sets (for a, b, c, and d, described below) producing known types of spiking behaviors.

class iznn.IZNodeGene(BaseGene)

Contains attributes for the iznn node genes and determines genomic distances. TODO: Genomic distance currently does not take into account the node’s bias.

distance(other, config)

Determines the genomic distance between this node gene and the other node gene.

Parameters:

• other (instance) – The other IZNodeGene instance.
• config (instance) – Configuration object, in this case a genome.DefaultGenomeConfig instance.

class iznn.IZGenome(DefaultGenome)

Sets up the genome to use IZNodeGene instances for node genes, and genes.DefaultConnectionGene instances for connection genes.

classmethod parse_config(param_dict)

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

Parameters:param_dict (dict(str, str)) – 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:instance

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

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.

Raises:

RuntimeError – If the number of inputs does not match the number of input nodes.

advance(dt_msec)

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()

Resets all state variables.

class iznn.IZNN(neurons, inputs, outputs)

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

Parameters:

• neurons (list(instance)) – The IZNeuron instances needed.
• inputs (list(int)) – The input node keys.
• outputs (list(int)) – The output node keys.

set_inputs(inputs)

Assigns input voltages.

Parameters:inputs (list(float)) – The input voltages for the input nodes.

reset()

Resets all neurons to their default state.

get_time_step_msec()

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)

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)

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

Parameters:

• genome (instance) – An IZGenome instance.
• config (instance) – Configuration object, in this implementation a config.Config instance.

Returns:

An IZNN instance.

Return type:

instance

Changed in version 0.92: __gene_attributes__ changed to _gene_attributes, since it is not a Python internal variable.

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.NORM_EPSILON

This is a system-dependent constant (the 4th root of the `sys.float_info.epsilon` system constant) used as a minimum value for precision (note that many machine

learning techniques can work well with half-precision floating-point numbers).

math_util.mean(values)

Returns the arithmetic mean.

Parameters:values (list(float) or set(float) or tuple(float)) – Numbers to take the mean of. Returns:The arithmetic mean. Return type:float

math_util.median(values)

Returns the median for odd numbers of values; returns the higher of the middle two values for even numbers of values.

Parameters:values (list(float) or set(float) or tuple(float)) – Numbers to take the median of. Returns:The median. Return type:float

math_util.median2(values)

Returns the median for odd numbers of values; returns the mean of the middle two values for even numbers of values.

Parameters:values (list(float) or set(float) or tuple(float)) – Numbers to take the median of. Returns:The median. Return type:float

New in version 0.92.

math_util.tmean(values, trim=0.25)

Returns the trimmed mean of the input values, with the fraction trimmed from each end being the second argument; requires 0.0 <= trim <= 0.5. If trim is over 0.25, returns the weighted mean of tmean(values, 0.25) and median2(values).

Parameters:

• values (list(float) or set(float) or tuple(float)) – Numbers to take the trimmed mean of.
• trim (float) – Fraction to trim from each end, if <= 0.25 (must have 0.0 <= trim <= 0.5)

Returns:

The trimmed mean.

Return type:

float

Raises:

ValueError – If trim is outside of the range 0.0-0.5, inclusive.

math_util.variance(values)

Returns the (population) variance.

Parameters:values (list(float) or set(float) or tuple(float)) – Numbers to get the variance of. Returns:The variance. Return type:float

math_util.stdev(values)

Returns the (population) standard deviation. Note spelling.

Parameters:values (list(float) or set(float) or tuple(float)) – Numbers to get the standard deviation of. Returns:The standard deviation. Return type:float

math_util.softmax(values)

Compute the softmax (a differentiable/smooth approximation of the maximum function, scaled from 0-1) of the given value set. (See the Wikipedia entry for more on softmax. Envisioned as useful for postprocessing of network output.)

Parameters:values (list(float) or set(float) or tuple(float)) – Numbers to get the softmax of. Returns:\(\begin{equation}v_i = \exp(v_i) / s \text{, where } s = \sum(\exp(v_0), \exp(v_1), \dotsc)\end{equation}\) Return type:list(float)

Changed in version 0.92: Previously not functional on Python 3.X due to changes to map.

math_util.stat_functions

Lookup table for commonly used {value} -> value functions, namely max, min, mean, median, median2, and tmean. The species_fitness_func (used for stagnation.DefaultStagnation) is required to be one of these, as is the fitness_criterion used for determining termination based on fitness (if no_fitness_termination is not set).

Changed in version 0.92: median2 added.

Changed in version 0.92-multiparam_funcs: tmean added.

multiparameter

The basis for multiparameter activation and aggregation functions.

class multiparameter.EvolvedMultiParameterFunction(name, multi_param_func)

Holds, initializes, and mutates the evolved parameters for one instance of a multiparameter function.

Parameters:

• name (str) – The name of the function.
• multi_param_func (instance) – The MultiParameterFunction instance for the multiparameter function.

class multiparameter.MultiParameterFunction(name, which_type, user_func, evolved_param_names, **evolved_param_dicts)

Holds and initializes configuration information for one multiparameter function.

Parameters:

• name (str) – The name of the function.
• which_type (str) – The type of function (currently, either activation or aggregation).
• user_func (function) – The multiparameter function.
• evolved_param_names (list(str)) – A list of the evolved variable names.
• evolved_param_dicts (dict) – The dictionaries with configuration information for each of the evolved variables.

exception multiparameter.BadFunctionError(Exception)

Base exception class for errors related to unusable or unknown activation/aggregation functions.

exception multiparameter.InvalidFunctionError(TypeError, BadFunctionError)

Exception raised if an object to be added as a function is not usable - for instance, if it is not a function (or lambda) or does not take any parameters.

exception multiparameter.UnknownFunctionError(LookupError, BadFunctionError)

Exception raised if an unknown function is requested by name, such as via activations.ActivationFunctionSet.get(), aggregations.AggregationFunctionSet.get(), or multiparameter.MultiParameterSet.get_MPF().

class multiparameter.MultiParameterSet(*which_types)

Holds the set of (potentially multiparameter) functions and contains methods for dealing with them.

Parameters:which_types (str) – What types of functions to hold; initialized by genome.DefaultGenomeConfig to [‘activation’, ‘aggregation’]. Determines the valid types for which_type parameters in the class methods.

get_MPF(name, which_type)

Fetches the named MultiParameterFunction instance.

Parameters:

• name (str) – The name of the function.
• which_type (str) – The type of function (currently, either activation or aggregation).

Returns:

The named MultiParameterFunction instance.

Return type:

instance

Raises:

UnknownFunctionError – If the function is unknown.

add_func(name, user_func, which_type, **kwargs)

Adds a new activation/aggregation function, potentially multiparameter. A multiparameter function must have entries in kwargs for each of its parameter variables to be evolved. Requirements for the function include the following: 1. Most obviously, must be a function (including lambda). 2. Functions (such as built-in functions) without a __code__ attribute cannot be multiparameter functions without a wrapper function (which will have the appropriate __code__ attribute); this attribute is used to determine the arguments for the function. 3. Any function arguments except the first one must be evolved variables with corresponding entries in kwargs. 4. Multiparameter function names cannot have parentheses, since parenthesized terms are used in constructing a particular function instance.

Parameters:

• name (str) – The name of the function.
• user_func (function) – The function to be added.
• which_type (str) – The type of function (currently, either activation or aggregation).
• kwargs (dict(str, dict(str,object))) – The configuration information for the function’s evolved variables.

Raises:

InvalidFunctionError – If the function does not meet the requirements specified above.

nn

Handles standard neural networks, either feed-forward or recurrent.

nn.create(genome, config)

Returns either a RecurrentNetwork or a FeedForwardNetwork for this genome, based on the genome’s maybe_recurrent attribute (a conservative estimate).

Parameters:

• genome (instance) – Genome to return phenotype for.
• config (instance) – Configuration object.

Returns:

A nn.feed_forward.FeedForwardNetwork or nn.recurrent.RecurrentNetwork instance.

Return type:

instance

nn.feed_forward

class nn.feed_forward.FeedForwardNetwork(inputs, outputs, node_evals)

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)

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

Parameters:inputs (list(float)) – The values for the input nodes. Returns:The values for the output nodes. Return type:list(float) Raises:RuntimeError – If the number of inputs is not the same as the number of input nodes.

reset()

Dummy method to match interface reset method for nn.recurrent.RecurrentNetwork.

static create(genome, config)

Receives a genome and returns its phenotype.

Parameters:

• genome (instance) – Genome to return phenotype for.
• config (instance) – Configuration object.

Returns:

A FeedForwardNetwork instance.

Return type:

instance

nn.recurrent

class nn.recurrent.RecurrentNetwork(inputs, outputs, node_evals)

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()

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

activate(inputs)

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

Parameters:inputs (list(float)) – The values for the input nodes. Returns:The values for the output nodes. Return type:list(float) Raises:RuntimeError – If the number of inputs is not the same as the number of input nodes.

static create(genome, config)

Receives a genome and returns its phenotype.

Parameters:

• genome (instance) – Genome to return phenotype for.
• config (instance) – Configuration object.

Returns:

A RecurrentNetwork instance.

Return type:

instance

parallel

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

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

Runs evaluation functions in parallel subprocesses in order to evaluate multiple genomes at once. The analogous threaded is probably preferable for python implementations without a GIL (Global Interpreter Lock); note that neat-python is not currently tested vs any such implementations.

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, nor by ThreadedEvaluator (although it is more similar to the latter).
• timeout (int or None) – How long (in seconds) each subprocess will be given before an exception is raised (unlimited if None).

__del__()

Takes care of removing the subprocesses.

evaluate(genomes, config)

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

Parameters:

• genomes (list(tuple(int, instance))) – A list of tuples of genome_id (not used), genome.
• config (instance) – A config.Config instance.

population

Implements the core evolution algorithm.

exception population.CompleteExtinctionException

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

class population.Population(config, initial_state=None)

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:

• config (instance) – The Config configuration object.
• initial_state (None or tuple(instance, instance, int)) – If supplied (such as by a method of the Checkpointer class), a tuple of (Population, Species, generation number)

Raises:

RuntimeError – If the fitness_criterion function is invalid.

add_reporter(reporter)

Adds a reporter to those that will be notified at appropriate points. Uses ReporterSet.add().

Parameters:reporter (instance) – A reporter callable via a reporting.ReporterSet instance.

remove_reporter(reporter)

Removes a reporter from those that will be notified at appropriate points. Uses ReporterSet.remove().

Parameters:reporter (instance) – A reporter callable via a reporting.ReporterSet instance.

run(fitness_function, n=None)

Runs NEAT’s genetic algorithm for at most n generations. If n is None, run until a solution is found or total 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 (function) – 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:

instance

Raises:

• RuntimeError – If None for n but no_fitness_termination is True.
• CompleteExtinctionException – If all species go extinct due to stagnation but reset_on_extinction is False.

Changed in version 0.92: no_fitness_termination capability added.

reporting

Makes possible reporter classes, which are triggered on particular events and may provide information to the user, may do something else such as checkpointing, or may do both.

class reporting.ReporterSet

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

add(reporter)

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

Parameters:reporter (instance) – A reporter instance.

remove(reporter)

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

Parameters:reporter (instance) – A reporter instance.

start_generation(gen)

Calls start_generation on each reporter in the set.

Parameters:gen (int) – The generation number.

end_generation(config, population, species)

Calls end_generation on each reporter in the set.

Parameters:

• config (instance) – Config configuration instance.
• population (dict(int, instance)) – Current population, as a dict of unique genome ID/key vs genome.
• species (instance) – Current species set object, such as a DefaultSpeciesSet instance.

post_evaluate(config, population, species)

Calls post_evaluate on each reporter in the set.

Parameters:

• config (instance) – Config configuration instance.
• population (dict(int, instance)) – Current population, as a dict of unique genome ID/key vs genome.
• species (instance) – Current species set object, such as a DefaultSpeciesSet instance.
• best_genome (instance) – The currently highest-fitness genome. (Ties are resolved pseudorandomly, by dictionary ordering.)

post_reproduction(config, population, species)

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

complete_extinction()

Calls complete_extinction on each reporter in the set.

found_solution(config, generation, best)

Calls found_solution on each reporter in the set.

Parameters:

• config (instance) – Config configuration instance.
• generation (int) – Generation number.
• best (instance) – The currently highest-fitness genome. (Ties are resolved pseudorandomly by dictionary ordering.)

species_stagnant(sid, species)

Calls species_stagnant on each reporter in the set.

Parameters:

• sid (int) – The species id/key.
• species (instance) – The Species instance.

info(msg)

Calls info on each reporter in the set.

Parameters:msg (str) – Message to be handled.

class reporting.BaseReporter

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)

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)

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

Parameters:

• config (instance) – Config configuration instance.
• population (dict(int, instance)) – Current population, as a dict of unique genome ID/key vs genome.
• species (instance) – Current species set object, such as a DefaultSpeciesSet instance.

post_evaluate(config, population, species, best_genome)

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

Parameters:

• config (instance) – Config configuration instance.
• population (dict(int, instance)) – Current population, as a dict of unique genome ID/key vs genome.
• species (instance) – Current species set object, such as a DefaultSpeciesSet instance.
• best_genome (instance) – The currently highest-fitness genome. (Ties are resolved pseudorandomly, by dictionary ordering.)

post_reproduction(config, population, species)

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()

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)

Called via ReporterSet (by population.Population.run()) prior to exiting if the configured fitness threshold is met, unless no_fitness_termination is set; if it is set, then called upon reaching the generation maximum - set when calling population.Population.run() - and exiting for this reason.)

Parameters:

• config (instance) – Config configuration instance.
• generation (int) – Generation number.
• best (instance) – The currently highest-fitness genome. (Ties are resolved pseudorandomly by dictionary ordering.)

Changed in version 0.92: no_fitness_termination capability added.

species_stagnant(sid, species)

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

Parameters:

• sid (int) – The species id/key.
• species (instance) – The Species instance.

info(msg)

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)

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

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

class reproduction.DefaultReproduction(config, reporters, stagnation)

Implements the default NEAT-python reproduction scheme: explicit fitness sharing with fixed-time species stagnation. Inherits from config.DefaultClassConfig the required class method write_config. TODO: Provide some sort of optional cross-species performance criteria, which are then used to control stagnation and possibly the mutation rate configuration. This scheme should be adaptive so that species do not evolve to become “cautious” and only make very slow progress.

Parameters:

• config (instance) – Configuration object, in this implementation a config.DefaultClassConfig instance.
• reporters (instance) – A ReporterSet instance.
• stagnation (instance) – A DefaultStagnation instance - the current code partially depends on internals of this class (a TODO is noted to correct this).

Raises:

ValueError – If min_species_size is below 2 (the minimum needed for crossover), or if fitness_min_divisor is below 0.0.

Changed in version 0.92: Configuration changed to use DefaultClassConfig, instead of a dictionary, and inherit write_config.

Changed in version 0.92-multiparam_funcs: Fitness_min_divisor and min_species_size checks added.

classmethod parse_config(param_dict)

Required interface method. Provides defaults for elitism, survival_threshold, min_species_size, and fitness_min_divisor parameters and updates them from the configuration file, in this implementation using config.DefaultClassConfig.

Parameters:param_dict (dict(str, str)) – Dictionary of parameters from configuration file. Returns:Reproduction configuration object; considered opaque by rest of code, so current type returned is not required for interface. Return type:DefaultClassConfig instance

Changed in version 0.92: Configuration changed to use DefaultClassConfig instead of a dictionary.

Changed in version 0.92-multiparam_funcs: Fitness_min_divisor added.

create_new(genome_type, genome_config, num_genomes)

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 (instance) – 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, instance)

static compute_spawn(adjusted_fitness, previous_sizes, pop_size, min_species_size)

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() and set in the configuration file.
• min_species_size (int) – Minimum number of members per species, set via the min_species_size configuration parameter (or the elitism configuration parameter, if higher); can result in population size being above pop_size.

reproduce(config, species, pop_size, generation)

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. Determines relative fitnesses by transforming into (ideally) a 0-1 scale; however, if the top and bottom fitnesses are not at least some amount apart, the range may be less than 0-1, as a check against dividing by a too-small number. The minimum divisor is determined by the configuration variable fitness_min_divisor.

Parameters:

• config (instance) – A Config instance.
• species (instance) – 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, instance)

Raises:

RuntimeWarning – If, at the first generation (number 0), the pop_size is less than (rounded up) 4/survival_threshold, and thus would not have room for at least two species for which the survival_threshold can be enforced.

Changed in version 0.92: Previously, the minimum and maximum relative fitnesses were determined (contrary to the comments in the code) including members of species being removed due to stagnation; it is now determined using only the non-stagnant species. The minimum size of species was (and is) the greater of the min_species_size and elitism configuration parameters; previously, this was not taken into account for compute_spawn(); this made it more likely to have a population size above the configured population size.

Changed in version 0.92-multiparam_funcs: Fitness_min_divisor configuration variable introduced; warning for too-low population size introduced.

six_util

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

Todo

Better documentation for the kw parameter in the below. Internally, these are using **kw as a parameter for keys/items/values/iterkeys/iteritems/itervalues! Is this in case someone puts in a set of key/value pairs instead of a dictionary? The six documentation just states that this parameter is “passed to the underlying method”, which is not helpful.

six_util.iterkeys(d, **kw)

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)

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)

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)

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

Parameters:

• key (int) – Identifier/key
• generation (int) – Initial generation of appearance

update(representative, members)

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

Parameters:

• representative (instance) – A genome instance.
• members (dict(int, instance)) – A dictionary of genome id vs genome instance.

get_fitnesses()

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)

Caches (indexing by genome key/id) genomic distance information to avoid repeated lookups. (The distance function, memoized by this class, 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 (instance) – A genome configuration instance; later used by the genome distance function.

__call__(genome0, genome1)

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

Parameters:

• genome0 (instance) – The first genome instance.
• genome1 (instance) – The second genome instance.

Returns:

The genomic distance.

Return type:

float

class species.DefaultSpeciesSet(config, reporters)

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. Inherits from config.DefaultClassConfig the required class method write_config.

Parameters:

• config (instance) – A configuration object, in this implementation a config.Config instance.
• reporters (instance) – A ReporterSet instance giving reporters to be notified about genomic distance statistics.

Changed in version 0.92: Configuration changed to use DefaultClassConfig, instead of a dictionary, and inherit write_config.

classmethod parse_config(param_dict)

Required interface method. Currently, the only configuration parameter is the compatibility_threshold; this method provides a default for it and updates it from the configuration file, in this implementation using config.DefaultClassConfig.

Parameters:param_dict (dict(str, str)) – Dictionary of parameters from configuration file. Returns:SpeciesSet configuration object; considered opaque by rest of code, so current type returned is not required for interface. Return type:DefaultClassConfig instance

Changed in version 0.92: Configuration changed to use DefaultClassConfig instead of a dictionary.

speciate(config, population, generation)

Required interface method. Place genomes into species by genetic similarity (genomic distance). TODO: 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. TODO: Check if sorting the unspeciated genomes by fitness will improve speciation (by making the highest-fitness member of a species its representative).

Parameters:

• config (instance) – Config instance.
• population (dict(int, instance)) – Population as per the output of DefaultReproduction.reproduce.
• generation (int) – Current generation number.

get_species_id(individual_id)

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)

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:instance

stagnation

Keeps track of whether species are making progress and helps remove ones that are not.

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).

class stagnation.DefaultStagnation(config, reporters)

Keeps track of whether species are making progress and helps remove ones that, for a configurable number of generations, are not. Inherits from config.DefaultClassConfig the required class method write_config.

Parameters:

• config (instance) – Configuration object; in this implementation, a config.DefaultClassConfig instance, but should be treated as opaque outside this class.
• reporters (instance) – A ReporterSet instance with reporters that may need activating; not currently used.

Changed in version 0.92: Configuration changed to use DefaultClassConfig, instead of a dictionary, and inherit write_config.

classmethod parse_config(param_dict)

Required interface method. Provides defaults for species_fitness_func, max_stagnation, and species_elitism parameters and updates them from the configuration file, in this implementation using config.DefaultClassConfig.

Parameters:param_dict (dict(str, str)) – Dictionary of parameters from configuration file. Returns:Stagnation configuration object; considered opaque by rest of code, so current type returned is not required for interface. Return type:DefaultClassConfig instance

Changed in version 0.92: Configuration changed to use DefaultClassConfig instead of a dictionary.

update(species_set, generation)

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:

• species_set (instance) – A species.DefaultSpeciesSet or compatible object.
• generation (int) – The current generation.

Returns:

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

Return type:

list(tuple(int, instance, bool))

Changed in version 0.92: Species sorted (by the species fitness according to the species_fitness_func) 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)

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)

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)

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()

Gets the per-generation mean 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_tmean(trim=0.25)

Gets the per-generation trimmed mean fitness. A wrapper for get_fitness_stat() with the function being tmean. Not currently used internally.

New in version 0.92-multiparam_funcs.

Parameters:trim (float) – Trim proportion (from each end) and/or determinant of weighting with median2; see tmean for more information. Returns:List of trimmed mean genome fitnesses for each generation. Return type:list(pytypes:float)

get_fitness_median()

Gets the per-generation median fitness. A wrapper for get_fitness_stat() with the function being median2. Not currently used internally.

New in version 0.92.

Returns:List of median genome fitnesses for each generation. Return type:list(pytypes:float)

get_fitness_stdev()

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)

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 instances). Return type:list(instance)

best_genomes(n)

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 instances). Return type:list(instance)

best_genome()

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

Returns:The most-fit genome. Return type:instance

get_species_sizes()

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='')

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)

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')

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')

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()

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

threaded

Runs evaluation functions in parallel threads (using the python library module threading) in order to evaluate multiple genomes at once. Probably preferable to parallel for python implementations without a GIL (Global Interpreter Lock); note, however, that neat-python is not currently tested on any such implementation.

class threaded.ThreadedEvaluator(num_workers, eval_function)

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

Parameters:

• num_workers (int) – How many worker threads to use.
• eval_function (function) – The eval_function should take two arguments - a genome object and a 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, nor by ParallelEvaluator (although it is more similar to the latter).

__del__()

Attempts to take care of removing each worker thread, but deliberately calling self.stop() in the threads may be needed. TODO: Avoid reference cycles to ensure this method is called. (Perhaps use weakref, depending on what the cycles are? Note that weakref is not compatible with saving via pickle, so all of them will need to be removed prior to any save.)

start()

Starts the worker threads, if in the primary thread.

stop()

Stops the worker threads and waits for them to finish.

_worker():

The worker function.

evaluate(genomes, config)

Starts the worker threads if need be, queues the evaluation jobs for the worker threads, then assigns each fitness back to the appropriate genome.

Parameters:

• genomes (list(tuple(int, instance))) – A list of tuples of genome_id, genome instances.
• config (instance) – A config.Config instance.

New in version 0.92.

Table of Contents