circuitree.grammar.CircuitGrammar

class circuitree.grammar.CircuitGrammar(*args, **kwargs)

Abstract class for Grammars. Used to define custom rules for the circuit assembly “game”.

Each stage of circuit topology assembly is represented by a state, which is a hashable ID (typically a string) for the current state. The state can be modified by applying an action, and the game ends when a terminal state is reached.

To search a particular space of circuits, you must use or create a subclass of this class that defines the rules of that particular assembly game - which actions can be taken from a given state, and how to apply them. Specifically, the following methods must be implemented:

  • get_actions

  • do_action

  • is_terminal

  • get_unique_state

See the documentation for each of these methods for more details.

__init__(*args, **kwargs)

Methods

__init__(*args, **kwargs)

do_action(state, action)

Given a state and an action, return the new state that results.

get_actions(state)

Get the possible actions that can be taken from the current state.

get_undo_actions(state)

(Experimental) Get all actions that can be undone from the given state.

get_unique_state(state)

Given a state, return a unique representation of that state.

has_pattern(state, pattern)

Optional method to check if a given state contains a particular sub-pattern.

is_terminal(state)

Given a state, return whether it is a terminal state.

to_dict()

Convert the grammar to a dictionary that can be serialized to JSON.

undo_action(state, action)

(Experimental) Undo one action from the given state.
abstract do_action(state: Hashable, action: Any) → Hashable

Given a state and an action, return the new state that results. Should be deterministic. The resulting state ID does not need to be unique (for example, it may not take symmetries into account).

Parameters:

  • state (Hashable) – The current state of the game.

  • action (Any) – The action to take.

Returns:

The new state.

Return type:

Hashable

abstract get_actions(state: Hashable) → Iterable[Any]

Get the possible actions that can be taken from the current state. A terminal state should return an empty list. List entries should be unique.

Warning: Actions should never form a cycle. That is, an action should always result in a new state, and multiple actions should never lead back to the same state. Many of the features of the package, including MCTS, assume that no loops are present.

Parameters:

state (Hashable) – The current state of the game.

Returns:

A list of actions.

Return type:

Iterable[Any]

get_undo_actions(state: Hashable) → Iterable[Any]

(Experimental) Get all actions that can be undone from the given state.

abstract get_unique_state(state: Hashable) → Hashable

Given a state, return a unique representation of that state.

This is used to determine whether two state IDs represent the same topology. For example, two assembly paths may lead to state IDs that are isomorphic “mirror images” of each other. In this case, get_unique_state should return the same ID for both.

Parameters:

state (Hashable) – The current state.

Returns:

A unique representation of the state.

Return type:

Hashable

has_pattern(state: Hashable, pattern: Hashable) → bool

Optional method to check if a given state contains a particular sub-pattern. This is useful for finding specific beneficial patterns, or motifs.

Parameters:

  • state (Hashable) – The current state.

  • pattern (Hashable) – The pattern to search for.

Raises:

NotImplementedError – If the method is not implemented.

Returns:

Whether the pattern is present.

Return type:

bool

abstract is_terminal(state: Hashable) → bool

Given a state, return whether it is a terminal state. A terminal state is one where no further actions can be taken.

Parameters:

state (Hashable) – The current state.

Returns:

Whether the state is terminal.

Return type:

bool

to_dict() → dict

Convert the grammar to a dictionary that can be serialized to JSON. Useful for saving the grammar to a file or for transferring it over a network.

The __grammar_cls__ key is added to the dictionary to indicate the name of the class that should be used to re-instantiate the grammar.

Returns:

A dictionary representation of the grammar.

Return type:

dict

undo_action(state: Hashable, action: Any) → Hashable

(Experimental) Undo one action from the given state.