Zoonomia API docs

zoonomia.operations

zoonomia.operations.build_types_possibility_table(basis_set, terminal_set, max_depth, grow_=False)[source]

This function returns a “types possibility table” which, for each depth \(d_{i} \in [1, ..., d_{max}]\) gives the possible return types for a tree of maximum depth \(i\). See Montana1995.

Parameters:
  • basis_set (zoonomia.solution.OperatorSet[BasisOperator]) – The OperatorSet of basis operators which, together with terminal_set, satisfy the closure property.
  • terminal_set (zoonomia.solution.OperatorSet[TerminalOperator]) – The OperatorSet of terminal operators which, together with terminal_set, satisfy the closure property.
  • max_depth (int) – The maximum tree depth from root to leaf.
  • grow (bool) – Whether to generate a table for the grow method. Default is to generate a table for the full method.
Returns:

A lookup table which for index \(i\) provides a list of all the possible return types for a tree of maximum depth \(i\).

Return type:

tuple[tuple[type]]

zoonomia.operations.crossover_subtree(solution_1, solution_2)[source]

Perform subtree crossover between two solutions.

Parameters:
Returns:

Two mutant solution offspring.

Return type:

tuple[zoonomia.solution.Solution]

zoonomia.operations.full(max_depth, basis_set, terminal_set, dtype, objectives, rng)[source]

An implementation of Koza’s full tree generation strategy augmented to take type information into account. Returns a candidate solution satisfying the property that all branches of the solution’s tree representation have path length from root to leaf equal to \(d_{max}\). See Koza1992 and Montana1995.

Parameters:
  • max_depth (int) – The maximum tree depth from root to leaf.
  • basis_set (zoonomia.solution.BasisSet[zoonomia.solution.BasisOperator]) – The OperatorSet of basis operators which, together with terminal_set, satisfy the closure property.
  • terminal_set (zoonomia.solution.TerminalSet[zoonomia.solution.TerminalOperator]) – The OperatorSet of terminal operators which, together with terminal_set, satisfy the closure property.
  • dtype (type) – The return type of the resulting solution’s functional representation.
  • objectives (tuple[zoonomia.solution.Objective]) – The objectives that the resulting solution will be constructed with.
  • rng (random.Random) – A random number generator instance.
Returns:

A candidate solution.

Return type:

zoonomia.solution.Solution

zoonomia.operations.grow(max_depth, basis_set, terminal_set, dtype, objectives, rng)[source]

An implementation of Koza’s grow tree generation strategy augmented to take type information into account. Returns a candidate solution whose graph representation has maximum path length from root to leaf constrained to the interval \([1, d_{max}]\). See Koza1992 and Montana1995.

Parameters:
  • max_depth (int) – The maximum tree depth from root to leaf.
  • basis_set (zoonomia.solution.BasisSet[zoonomia.solution.BasisOperator]) – The OperatorSet of basis operators which, together with terminal_set, satisfy the closure property.
  • terminal_set (zoonomia.solution.TerminalSet[zoonomia.solution.TerminalOperator]) – The OperatorSet of terminal operators which, together with basis_set, satisfy the closure property.
  • dtype (type) – The return type of the resulting solution’s functional representation.
  • objectives (tuple[zoonomia.solution.Objective]) – The objectives that the resulting solution will be constructed with.
  • rng (random.Random) – A random number generator instance.
Returns:

A candidate solution.

Return type:

zoonomia.solution.Solution

zoonomia.operations.mutate_node(solution)[source]

Perform a point mutation on a solution, returning a new mutant solution.

Parameters:solution (zoonomia.solution.Solution) – A solution.
Returns:A mutant solution.
Return type:zoonomia.solution.Solution
zoonomia.operations.mutate_subtree(solution)[source]

Perform subtree mutation on a solution, returning a new mutant solution.

Parameters:solution (zoonomia.solution.Solution) – A solution.
Returns:A mutant solution.
Return type:zoonomia.solution.Solution
zoonomia.operations.ramped_half_and_half(max_depth, population_size, basis_set, terminal_set, dtype, objectives, rng)[source]

An implementation of something like Koza’s ramped half-and-half population initialization procedure. See Koza1992.

Parameters:
  • max_depth (int) – the max tree depth per individual.
  • population_size (int) – number of individuals in the population.
  • basis_set (zoonomia.solution.BasisSet[zoonomia.solution.BasisOperator]) – The OperatorSet of basis operators which, together with terminal_set, satisfy the closure property.
  • terminal_set (zoonomia.solution.TerminalSet[zoonomia.solution.TerminalOperator]) – The OperatorSet of terminal operators which, together with basis_set, satisfy the closure property.
  • dtype (type) – The return type of the resulting solutions’ functional representations.
  • objectives (tuple[zoonomia.solution.Objective]) – The objectives that the resulting solution will be constructed with.
  • rng (random.Random) – A random number generator instance.
Returns:

Return type:

frozenset

zoonomia.operations.tournament_select(solution_1, solution_2, rng)[source]

Perform multi-objective tournament selection between two candidate solutions.

Parameters:
Returns:

The solution which wins the tournament.

Return type:

zoonomia.solution.Solution

zoonomia.solution

class zoonomia.solution.BasisOperator(func, signature, dtype)[source]

Bases: object

__call__(*args, **kwargs)[source]
__init__(func, signature, dtype)[source]

A BasisOperator represents a member of the basis set. A BasisOperator contains a reference to a function, a tuple type signature corresponding to that function, and a reference dtype to that function’s return type.

Parameters:
  • func – A function of arity \(N+1\) which takes \(N+1\) arguments having type signature \((T0, ..., TN)\) to a result of type \(U\).
  • signature (tuple[type]) – Type signature for func. You should make sure this matches the actual types that the function expects.
  • dtype (U) – Output type for func. You should make sure this matches the actual type returned by the function.
__repr__()[source]
__slots__ = ('func', 'signature', 'dtype')
dtype
func
signature
class zoonomia.solution.Fitness(score, objective)[source]

Bases: object

__eq__(other)[source]
__ge__(other)[source]
__gt__(other)[source]
__hash__()[source]
__init__(score, objective)[source]

A Fitness maps a fitness measurement to an Objective.

Parameters:
__le__(other)[source]
__lt__(other)[source]
__repr__()[source]
__slots__ = ('score', '_objective', '_hash')
score
class zoonomia.solution.Objective(eval_func, weight)[source]

Bases: object

__eq__(other)[source]
__hash__()[source]
__init__(eval_func, weight)[source]

An Objective contains a reference to a function for evaluating a Solution, and a weight by which the resulting fitness score will be multiplied.

Parameters:
  • eval_func ((zoonomia.solution.Solution) -> float) – A function which computes a fitness score for a Solution.
  • weight (float) – The weight to give this objective.
__repr__()[source]
__slots__ = ('_eval_func', '_weight', '_hash')
evaluate(solution)[source]

Compute the fitness measurement of a solution with respect to this objective.

Parameters:solution (zoonomia.solution.Solution) – A candidate solution.
Returns:A fitness measurement of the solution with respect to this objective.
Rtype zoonomia.solution.Fitness:
 
class zoonomia.solution.OperatorSet(operators)[source]

Bases: object

__getitem__(item)[source]

If item is a tuple, select those BasisOperators belonging to this OperatorSet which have signatures equal to item. If item is a type, select those BasisOperators and TerminalOperators which have dtype equal to item.

Parameters:item (tuple[type] or type) – A signature or dtype.
Raises:KeyError – If the given item has no associated operators in this OperatorSet.
Returns:The operators belonging to this OperatorSet which match the signature or dtype item.
Return type:tuple[BasisOperator] or tuple[TerminalOperator|BasisOperator]
__init__(operators)[source]

An OperatorSet contains BasisOperators and TerminalOperators and also provides a convenient mapping which allows a user to select either the subset of operators having output type dtype or the subset of basis operators having a particular type signature.

Parameters:operators (collections.Iterable[BasisOperator|TerminalOperator]) –
__iter__()[source]

Returns an iterator over this instance’s operators.

Returns:An iterator of operators.
Return type:collections.Iterator[BasisOperator|TerminalOperator]
__repr__()[source]
__slots__ = ('operators', '_dtype_to_operators', '_signature_to_operators')
operators
union(other)[source]

Returns an OperatorSet containing those elements which are in the union of both this OperatorSet and the other OperatorSet.

Parameters:other (OperatorSet) –
Return union:
Return type:OperatorSet
class zoonomia.solution.Solution(tree, objectives, map_=<built-in function map>)[source]

Bases: object

__eq__(other)[source]
__ge__(other)[source]
__gt__(other)[source]
__hash__()[source]
__init__(tree, objectives, map_=<built-in function map>)[source]

A Solution unites a tree representation with a collection of Objectives.

Parameters:
  • tree (zoonomia.tree.Tree) –
  • objectives (tuple[zoonomia.solution.Objective]) –
  • map (((T) -> U, collections.Iterable[T]) -> collectons.Iterable[U]) – The map implementation to use in computing things (such as Fitness values) associated with this solution.
__le__(other)[source]
__lt__(other)[source]
__repr__()[source]
__slots__ = ('tree', 'objectives', 'map', '_hash', '_lock', '_fitnesses')
dominates(other)[source]

Predicate function to determine whether this solution dominates another solution in the Pareto sense. That is, we say that this solution dominates another solution if for all Objectives associated with both solutions the corresponding Fitness measurements for this solution are all greater than or equal to–and at least one Fitness measurement is strictly greater than–the corresponding Fitness measurements for the other solution.

Parameters:other (zoonomia.solution.Solution) – Another candidate solution.
Returns:Whether this solution dominates other.
Return type:bool
evaluate()[source]

Compute the weighted fitness score of a solution with respect to each objective. Results are computed and cached in a thread-safe manner, so repeated calls to this method from multiple threads should result in only one (potentially expensive) call to each associated Objective’s evaluate method.

Returns:A tuple of Fitness measurements.
Return type:tuple[zoonomia.solution.Fitness]
map
objectives
tree
class zoonomia.solution.TerminalOperator(source, dtype)[source]

Bases: object

__init__(source, dtype)[source]

A TerminalOperator represents a member of the terminal set. A TerminalOperator acts as a source which emits data of type dtype.

Parameters:
  • source (collections.Iterable[T]) – An iterable which yields data of type T.
  • dtype (T) – The output type for source. You should make sure this matches the actual type yielded by source.
__iter__()[source]
__repr__()[source]
__slots__ = ('source', 'dtype')
dtype
source
zoonomia.solution.verify_closure_property(basis_set, terminal_set)[source]

Verify that the OperatorSets basis_set and terminal_set together satisfy a strongly-typed version of the closure property. You can use this function to unit-test your OperatorSets. See Koza1992 for more about the closure property.

Warning

This function can only check that the combined basis_set and terminal_set is closed with respect to types. You must ensure that the functions you provide are well-behaved (in the closure sense) given any values they might encounter.

Parameters:
  • basis_set (zoonomia.solution.OperatorSet[BasisOperator]) – The candidate basis set to test for closure.
  • terminal_set (zoonomia.solution.OperatorSet[TerminalOperator]) – The candidate terminal set to test for closure.
Returns:

True if the closure property is satisfied, False otherwise.

Return type:

bool

zoonomia.tree

class zoonomia.tree.Node(operator)[source]

Bases: object

Nodes are the fundamental elements of the trees used to represent candidate solutions in Zoonomia. A tree is composed by linking nodes together using the add_child method.

Warning

Nodes are not intended to be thread safe. You should construct tree structures from a single thread and only when you are done mutating the structure should the root node be passed into the constructor of zoonomia.tree.Tree.

__init__(operator)[source]

A node has a unique identity and holds a reference to an operator. Optionally, a node can hold references to child nodes provided that those child nodes’ operators’ dtypes match this node’s operator’s signature.

Parameters:operator (zoonomia.solution.BasisOperator or zoonomia.solution.TerminalOperator) – A reference to the operator to associate with this node.
__repr__()[source]
__slots__ = ('operator', 'dtype', 'left', '_right', 'right')
add_child(child, position)[source]

Add a child to this node corresponding to a position in the operator’s signature. The child node’s dtype must match the operator’s signature at the given position.

Parameters:
  • child (zoonomia.tree.Node) – A reference to another Node instance.
  • position (int) – The position, corresponding to an element of the operator’s signature, to “wire up” the child node’s operator’s output.
Raises:
  • TypeError – If child’s dtype doesn’t match the operator’s signature at the given position.
  • IndexError – If child’s signature does not contain an index corresponding to the given position.
dtype
left
operator
right
class zoonomia.tree.Tree(root)[source]

Bases: object

Whereas a tree data structure is composed of zoonomia.tree.Node objects which refer to each other in a potentially complicated manner, a Tree instance is a “handle” which we can use to abstract away that complexity and actually use the tree to do work.

Note

While the Nodes which are used to construct a tree data structure are not thread-safe, if you make sure that once a Tree is constructed nothing will change its nodes you can be sure that the tree is “effectively immutable” and therefore “safe”.

__init__(root)[source]

A Tree instance is a thin wrapper around a tree data structure composed of Nodes that supports post-order depth-first iteration over all the nodes. You should ensure that the tree data structure is fully-populated before you attempt iteration.

Parameters:root (zoonomia.tree.Node) – The root node of the tree data structure which this instance will “wrap”.
__iter__()[source]

Returns a post-order depth-first iterator over all nodes in this tree.

Returns:An iterator over all the nodes in this tree.
Return type:collections.Iterator[zoonomia.tree.Node]
__slots__ = ('root', 'dtype')
dtype
root