PyshGP API

There are two main sub-packages that make up PyshGP’s functionality.

The push package provides a Push interpreter and a Push program abstraction.

• pyshgp.push package
• pyshgp.gp package

Other Modules

There are a handful of modules that are used throughout both the Push sub-package and the genetic programming sub-package.

pyshgp.tap module

The Tap and TapManager abstractions allow for users to inject side effects into PyshGP runs.

These side effects could be print statements for monitoring, writing to log files, or sending messages to external systems when certain events occur. A Tap can inject a side effect before a function call, after a function call, or both. Any function or method defined in PyshGP or your application code can be tapped with the @tap decorator defined in the module.

The taps provided in PyshGP are sufficient for most use cases, but user can define and register their own Tap objects via inheritance and method overrides.

class pyshgp.tap.CsvTap(root: str, column_names: Sequence[str])

Bases: pyshgp.tap.LogFileTap

A Tap for writing CSV files.

Parameters

• root (str) – The root directory for putting log files (and directories).

• column_names (Sequence[str]) – The column names to put in the header of the CSV file.

log(id: str, filename: str, row: Dict)

Write a to a CSV file.

Parameters

• id (str) – The ID of the function being tapped. This is used to generate a directory for the log file.

• filename (str) – The name of the CSV file.

• row (dict) – A dictionary that will be written as a row in the CSV. The keys should be in the CsvTap’s list of column_names.

class pyshgp.tap.JsonLinesTap(root: str)

Bases: pyshgp.tap.LogFileTap

A Tap for writing JSON lines files.

Parameters

root (str) – The root directory for putting log files (and directories).

log(id: str, filename: str, row: Dict)

Write a JSON object to a line of a JSON lines file.

Parameters

• id (str) – The ID of the function being tapped. This is used to generate a directory for the log file.

• filename (str) – The name of the JSON file.

• row (dict) – A dictionary that will be written as a row in the file.

class pyshgp.tap.LogFileTap(root: str)

Bases: pyshgp.tap.Tap

A Tap for writing log files.

Parameters

root (str) – The root directory for putting log files (and directories).

dir(id: str) → str

Generate the directory for log files associated with the given function ID.

log(id: str, filename: str, line: str)

Write a line to a log file. Includes a timestamp for each log entry.

Parameters

• id (str) – The ID of the function being tapped. This is used to generate a directory for the log file.

• filename (str) – The name of the log file.

• line (str) – The line of text to write to the log file.

path(id: str, filename: str) → str

Generate the path for the log files with the given name under the directory for the given function ID.

class pyshgp.tap.StdOutRun(*, pre_print_config: bool = False, pre_print_atoms: bool = False, post_print_best: bool = False)

Bases: pyshgp.tap.Tap

A Tap that prints information from a SearchAlgorithm run to stdout.

Parameters

• pre_print_config (bool, optional) – If True, print the PushConfig before each run. Default False.

• pre_print_atoms (bool, optional) – If True, print all the atoms used to generate programs before each run. Default False.

• post_print_best (bool, optional) – If True, print a summary about the best program found at the end of each run. Default False.

post(id: str, args, kwargs, returned, obj=None)

Print a summary of the run result to stdout.

pre(id: str, args, kwargs, obj=None)

Print run config and/or all atoms to stdout.

class pyshgp.tap.StdOutSearchStepTap(every_n_steps: int)

Bases: pyshgp.tap.Tap

A Tap that prints stats from a step (aka generation) of a SearchAlgorithm run.

pre(id: str, args, kwargs, obj=None)

Print population stats before the next step of the run.

class pyshgp.tap.StdOutSimplification

Bases: pyshgp.tap.Tap

A Tap that prints a summary of Genome simplification.

post(id: str, args, kwargs, returned, obj=None)

Print a summary of the result of genome simplification.

pre(id: str, args, kwargs, obj=None)

Print a notification that genome simplification is starting.

class pyshgp.tap.StdOutSimplificationStep

Bases: pyshgp.tap.Tap

A Tap that prints a notification of a successful Genome simplification step.

post(id: str, args, kwargs, returned, obj=None)

Print a notification of a successful step of Genome simplification.

class pyshgp.tap.Tap

Bases: abc.ABC

A debugging/logging abstraction to a function and collects its arguments and returned.

The methods of a Tap should be side effects. It is not recommended to make state changes from with a Tap if that state will change code behavior.

do(id: str, *args, **kwargs)

Perform a particular side-effect when called.

Parameters

id (str) – The ID of the tap.

post(id: str, args: Tuple, kwargs: Dict, returned)

Perform a particular side-effect directly before the associated function/method is called.

Parameters

• id (str) – The ID of the tap, generated based off of the name qualified name of the function.

• args (Tuple) – The positional of the function call. For methods, args[0] is the class instance.

• kwargs (Dict) – The keyword args of the function call.

• returned (Any) – The returned value of the function call.

pre(id: str, args: Tuple, kwargs: Dict)

Perform a particular side-effect directly before the associated function/method is called.

Parameters

• id (str) – The ID of the tap, generated based off of the name qualified name of the function.

• args (Tuple) – The positional of the function call. For methods, args[0] is the class instance.

• kwargs (Dict) – The keyword args of the function call.

class pyshgp.tap.TapManager

Bases: object

Stores a mapping of function ID to Tap object than can be used to inject side effects around functions.

The TapManger class is treated as a singleton and should not be instanced. Its methods are static and the state they manage is shared between all usages of Taps.

Function IDs are a fully qualified identifier for a function. They are generated as the concatenation of the module name the function is defined in (ie. my_package.my_module) and the qualified name of the function definition (ie. MyClass.my_method). The final function ID would be my_package.my_module.MyClass.my_method.

static do(id: str, *args, **kwargs)

Perform the do method of the tap registered under the given ID.

This can be called from any location.

static get(id: str) → Optional[pyshgp.tap.Tap]

Return the Tap associated with given ID or None if no tap is registered.

static register(id: str, tap: pyshgp.tap.Tap)

Register a Tap to be performed when the function with the associated ID is called.

static unregister(id: str)

Unregister the Tap associated with given ID.

pyshgp.tap.set_verbosity(level: int)

Register some Tap objects in the TapManger that print to stdout during an evolutionary run.

Verbosity level 0 prints nothing to stdout.

Verbosity level 1 prints minimal run configuration as well as population statistics every 5 generations.

Verbosity level 2+ prints full run configuration, population statics every generation, and traces the genome simplification process.

pyshgp.tap.tap(fn)

Decorate a function/method to call any associated taps that have been registered in the TapManager.

Functional behavior is not changed.

pyshgp.utils module

Utility classes and functions used throughout pyshgp.

class pyshgp.utils.Copyable

Bases: object

Allows an object to be copied via a method.

copy(deep: bool = False)

Copy the CodeBlock.

class pyshgp.utils.DiscreteProbDistrib

Bases: object

Discrete Probability Distribution.

add(el, p)

Add an element with a relative probability.

elements

sample()

Return a sample from the distribution.

sample_n(n: int = 1, replace: bool = True)

Return n samples from the distribution.

size()

Return the number of elements in the distribution.

class pyshgp.utils.Saveable

Bases: object

Allows a pickle-able class to be written and loaded from a file.

static load(path: str)

Load a CodeBlock from a binary file..

save(path: str)

Save the CodeBlock to a binary file.

class pyshgp.utils.Token(value)

Bases: enum.Enum

Enum class of all Tokens.

no_stack_item = 1

revert = 2

whole_state = 3

pyshgp.utils.instantiate_using(cls: type, args: dict)

Call the given function using only the relevant kwargs present in the args dict.

pyshgp.utils.list_rindex(lst, el)

Index of the last occurrence of an item in a list. Return None is item not found.

pyshgp.validation module

Module for validating data and raising informative errors.

exception pyshgp.validation.PushError

Bases: Exception

Error raised during Push program execution.

classmethod empty_character()

Raise PushError when Character is made from empty string.

classmethod failed_coerce(thing, push_type)

Raise PushError when something fails to coerce to a PushType.

classmethod long_character()

Raise PushError when Character is made from string length more than 1.

classmethod no_type(thing)

Raise PushError when no PushType can be found for something.

pyshgp.validation.check_1d(seq: MutableSequence) → Sequence

Check given data is one-dimensional. Raise error if can’t be easily transformed.

pyshgp.validation.check_2d(data)

Check given data is two-dimensional. Raise error if can’t be easily transformed.

pyshgp.validation.check_X_y(X, y) → Tuple[Sequence, Sequence, int, Sequence]

Check the given X and y datasets are prepared to be passed to a PushEstimator.

Inspired by the scikit-learn function with the same name. https://scikit-learn.org/stable/modules/generated/sklearn.utils.check_X_y.html#sklearn.utils.check_X_y

pyshgp.validation.check_column_types(seq, certainty_proportion: float = 0.2) → Sequence[type]

Check all elements of each column are of the same type.

pyshgp.validation.check_is_fitted(estimator, attribute)

Check the given estimator has already been fit.

Inspired by the scikit-learn function with the same name. https://scikit-learn.org/stable/modules/generated/sklearn.utils.validation.check_is_fitted.html#sklearn.utils.validation.check_is_fitted

pyshgp.validation.check_num_columns(data: Sequence, certainty_proportion: float = 0.2) → int

Return the number of columns of in the dataset.