fragile.callbacks.tree#

Data structure to keep track of the graph that stores all the states visited by a Swarm.

Module Contents#

Classes#

BaseTree

Data structure in charge of storing the history of visited states of an algorithm run.

NetworkxTree

It is a tree data structure that stores the paths followed by the walkers using a networkx DiGraph to keep track of the states relationships.

DataTree

Tree data structure that keeps track of the visited states.

HistoryTree

Tree data structure that keeps track of the visited states.

Functions#

to_node_id(x)

Attributes#

DEFAULT_ROOT_ID

fragile.callbacks.tree.DEFAULT_ROOT_ID =#
fragile.callbacks.tree.to_node_id(x)[source]#
class fragile.callbacks.tree.BaseTree(root_id=DEFAULT_ROOT_ID)[source]#

Data structure in charge of storing the history of visited states of an algorithm run.

__call__(*args, **kwargs)[source]#

Return the current instance of BaseTree.

This is used to avoid defining a tree_callable `` as         ``lambda: tree_instance when initializing a Swarm. If the BaseTree needs is passed to a remote process, you may need to write custom serialization for it, or resort to creating an appropriate tree_callable.

Return type

BaseTree

update(node_ids, parent_ids, n_iter=None, **kwargs)[source]#

Update the history of the tree adding the necessary data to recreate a the trajectories sampled by the Swarm.

Parameters

  • node_ids (List[fragile.core.typing.NodeId]) – List of states hashes representing the node_ids of the current states.

  • parent_ids (List[fragile.core.typing.NodeId]) – List of states hashes representing the parent nodes of the current states.

  • n_iter (int) – Number of iteration of the algorithm when the data was sampled.

  • kwargs – Keyword arguments representing different States instances.

Returns

None

Return type

None

reset(*args, **kwargs)[source]#

Delete all the data currently stored and reset the internal state of the tree.

Return type

None

prune_tree(*args, **kwargs)[source]#

Remove branches of the tree.

Return type

None

class fragile.callbacks.tree.NetworkxTree(names=None, prune=False, root_id=DEFAULT_ROOT_ID, node_names=DEFAULT_NODE_DATA, edge_names=DEFAULT_EDGE_DATA, next_prefix=DEFAULT_NEXT_PREFIX)[source]#

Bases: BaseTree

It is a tree data structure that stores the paths followed by the walkers using a networkx DiGraph to keep track of the states relationships.

Parameters

  • names (fragile.core.typing.NamesData) –

  • prune (bool) –

  • root_id (fragile.core.typing.NodeId) –

  • node_names (fragile.core.typing.NamesData) –

  • edge_names (fragile.core.typing.NamesData) –

  • next_prefix (str) –

DEFAULT_ROOT_ID#
DEFAULT_NEXT_PREFIX = next_#
DEFAULT_NODE_DATA = ['observs', 'rewards', 'oobs', 'scores']#
DEFAULT_EDGE_DATA = ['actions']#
__len__()[source]#
Return type

int

__repr__()[source]#

Return repr(self).

Return type

str

reset(root_id=None, state=None)[source]#

Delete all the data currently stored and reset the internal state of the tree and reset the root node with the provided data.

Parameters
Return type

None

update(node_ids, parent_ids, freeze_ids, freeze_parents, n_iter=None, **kwargs)[source]#

Update the history of the tree adding the necessary data to recreate a the trajectories sampled by the Swarm.

Parameters

  • node_ids (List[fragile.core.typing.NodeId]) – List of states hashes representing the node_ids of the current states.

  • parent_ids (List[fragile.core.typing.NodeId]) – List of states hashes representing the parent nodes of the current states.

  • freeze_ids (List[fragile.core.typing.NodeId]) – List of the ids of walkers that are marked as inactive.

  • freeze_parents (List[fragile.core.typing.NodeId]) – List of the parent ids of walkers that are marked as inactive.

  • n_iter (int) – Number of iteration of the algorithm when the data was sampled.

  • kwargs – Keyword arguments representing different States instances.

Returns

None

prune_tree(alive_leafs)[source]#

Remove the branches that do not have a walker in their leaves.

Parameters

alive_leafs (Set[fragile.core.typing.NodeId]) – Contains the ids of the leaf nodes that are being expanded by the walkers.

Returns

None.

reset_graph(node_data, root_id=None, epoch=- 1)[source]#

Delete all the data currently stored and reset the internal state of the instance.

Parameters

  • root_id (fragile.core.typing.NodeId) – The node id of the root node.

  • node_data (Dict[str, Any]) – Dictionary containing the data that will be added to the new node created. The keys of the dictionary contain the names of the attributes and its values the corresponding value added to the node.

  • epoch (int) – Epoch of the Swarm run when the current node was generated. Defaults to -1.

Returns

None.

Return type

None

append_leaf(leaf_id, parent_id, node_data, edge_data, epoch=- 1)[source]#

Add a new state as a leaf node of the tree to keep track of the trajectories of the swarm.

Parameters

  • leaf_id (fragile.core.typing.NodeId) – Node id that identifies the new node that will be added to the tree.

  • parent_id (fragile.core.typing.NodeId) – Node id that identifies the parent of the node that will be added to the tree.

  • node_data (Dict[str, Any]) – Dictionary containing the data that will be added to the new node created. The keys of the dictionary contain the names of the attributes and its values the corresponding value added to the node.

  • edge_data (Dict[str, Any]) – Dictionary containing the data that will be added to the new edge created from parent_id to leaf_id. The keys of the dictionary contain the names of the attributes and its values the corresponding value added to the edge.

  • epoch (int) – Epoch of the Swarm run when the current node was generated. Defaults to -1.

Returns

None.

Return type

None

prune_dead_branches(dead_leafs, alive_leafs)[source]#

Prune the orphan leaves that will no longer be used in order to save memory.

Parameters

  • dead_leafs (Set[fragile.core.typing.NodeId]) – Leaves of the branches that will be removed.

  • alive_leafs (Set[fragile.core.typing.NodeId]) – Leaves of the branches that will kept being expanded.

Returns

None

Return type

None

prune_branch(leaf_id, alive_nodes)[source]#

Recursively prunes a branch that ends in an orphan leaf.

Parameters

  • leaf_id (fragile.core.typing.NodeId) – Value that identifies the leaf of the tree. If leaf_id is the hash of a walker state from_hash needs to be True. Otherwise it refers to a node id of the leaf node.

  • alive_nodes (Set[fragile.core.typing.NodeId]) – Nodes of the branches that can be still expanded.

Returns

None

Return type

None

get_parent(node_id)[source]#

Get the node id of the parent of the target node.

Parameters

node_id (fragile.core.typing.NodeId) –

Return type

fragile.core.typing.NodeId

get_branch(leaf_id)[source]#

Return a list of the node ids of the path between root_node and leaf_id.

Parameters

leaf_id (fragile.core.typing.NodeId) – Node id of the end of the path that will be returned.

Returns

List containing the nodes found between the root node and leaf_id. It starts with self.root_id and ends with leaf_id.

Return type

List[fragile.core.typing.NodeId]

get_path_node_ids(leaf_id, root_id=None)[source]#

Get the data of the path between leaf_id and root_id.

Parameters

  • leaf_id (fragile.core.typing.NodeId) – Id that identifies the leaf of the tree. If leaf_id is the hash of a walker state from_hash needs to be True. Otherwise it refers to a node id of the leaf node.

  • root_id (fragile.core.typing.NodeId) – Node id of the root node of the tree.

Returns

List of the node ids between root and leaf_id.

Return type

numpy.ndarray

get_leaf_nodes()[source]#

Return a list containing all the node ids of the leaves of the tree.

Return type

Tuple[fragile.core.typing.NodeId]

compose(other)[source]#

Compose the graph of another BaseNetworkxTree with the graph of the current instance.

Composition is the simple union of the node sets and edge sets. The node sets of self.data and other.data do not need to be disjoint.

The data in other takes precedence over the data in the current instance.

Parameters

other (Union[NetworkxTree, networkx.Graph]) – Instance of BaseNetworkxTree that will be composed with the current instance.

Returns

None

Return type

None

_update_prune_sentinel()[source]#
_extract_data_from_states(index, state, only_node_data=False)[source]#
Parameters
class fragile.callbacks.tree.DataTree(names=None, prune=False, root_id=DEFAULT_ROOT_ID, node_names=NetworkxTree.DEFAULT_NODE_DATA, edge_names=NetworkxTree.DEFAULT_EDGE_DATA, next_prefix=NetworkxTree.DEFAULT_NEXT_PREFIX)[source]#

Bases: NetworkxTree

Tree data structure that keeps track of the visited states.

It allows to save the Swarm data after every iteration and methods to recover the sampled data after the algorithm run.

The data that will be stored in the graph it’s defined in the names parameter. For example:

  • If names is ["observs", "actions"], the observations of every visited state will be stored as node attributes, and actions will be stored as edge attributes.

  • If names if ["observs", "actions", "next_observs"] the same data will be stored, but when the data generator methods are called the observation corresponding to the next state will also be returned.

The attribute names also defines the order of the data returned by the generator.

As long as the data is stored in the graph (passing a valid names list at initialization, the order of the data can be redefined passing the names parameter to the generator method.

For example, if the names passed at initialization is ["states", "rewards"], you can call the generator methods with names=["rewards", "states", "next_states"] and the returned data will be a tuple containing (rewards, states, next_states).

Parameters

  • names (fragile.core.typing.NamesData) –

  • prune (bool) –

  • root_id (fragile.core.typing.NodeId) –

  • node_names (fragile.core.typing.NamesData) –

  • edge_names (fragile.core.typing.NamesData) –

  • next_prefix (str) –

_one_node_tuples(node, next_node, return_children)[source]#
Return type

fragile.core.typing.NodeData

_extract_one_node_data(data, names)[source]#

Transform the one tuple of dictionaries returned by the data generators into a tuple of data values where each value corresponds to a name in names.

Parameters

  • data (fragile.core.typing.NodeData) –

  • names (fragile.core.typing.NamesData) –

Return type

Tuple

_process_batch(batch_data)[source]#

Preprocess the list of tuples representing a batched group of elements and return a tuple of arrays representing the batched values for every data attribute.

Parameters

batch_data (List[tuple]) –

Return type

Tuple[fragile.core.typing.Tensor, Ellipsis]

_generate_batches(generator, names, batch_size=None)[source]#

Return batches of processed data represented as tuples of arrays.

Parameters

  • generator (fragile.core.typing.NodeDataGenerator) –

  • names (fragile.core.typing.NamesData) –

  • batch_size (int) –

Return type

Generator[Tuple, None, None]

_validate_names(names)[source]#
path_data_generator(node_ids, return_children=False)[source]#

Return a generator that returns the data corresponding to a path.

Each value yielded corresponds to one element of the path. The edge data will be assigned to the parent node of the edge. This means the edge data contains the data associated with the transition to a child.

The data corresponding to the last node of the path will not be returned.

Parameters

  • node_ids (Union[Tuple[fragile.core.typing.NodeId], Set[fragile.core.typing.NodeId], List[fragile.core.typing.NodeId]]) – Node ids of a path ordered. The first node of the path corresponds to the first element of node_ids.

  • return_children (bool) – If True the data corresponding to the child of each node in the path will also be returned.

Yields

tuple of dictionaries containing the data of each node and edge of the path, following the order of node_ids.

If return_children is False it will yield (node_data, edge_data). If return_children is True it will yield (node_data, edge_data, next_node_data).

Return type

fragile.core.typing.NodeDataGenerator

random_nodes_generator(return_children=False)[source]#

Return a generator that yields the data of all the nodes sampling them at random.

Each value yielded corresponds to the data associated with one node and the edge connecting to one of its children. The edge data will be assigned to the parent node of the edge. This means the edge data of each node contains the data associated with the transition to a child.

Parameters

return_children (bool) – If True the data corresponding to the child of each node in the path will also be returned.

Yields

tuple of dictionaries containing the data for each node and edge sampled at random.

If return_children is False it will yield (node_data, edge_data). If return_children is True it will yield (node_data, edge_data, next_node_data).

Return type

fragile.core.typing.NodeDataGenerator

iterate_path_data(node_ids, batch_size=None, names=None)[source]#

Return a generator that yields the data of the nodes contained in the provided path.

Parameters

  • node_ids (Union[Tuple[fragile.core.typing.NodeId], List[fragile.core.typing.NodeId]]) – Ids of the nodes of the path that will be sampled. The nodes must be provided in order, starting with the first node of the path.

  • batch_size (int) – If it is not None, the generator will return batches of data with the target batch size. If Batch size is less than 1 it will return a single batch containing all the data.

  • names (fragile.core.typing.NamesData) – Names of the data attributes that will be yielded by the generator.

Returns

Generator providing the data corresponding to a path in the internal tree.

Return type

fragile.core.typing.NodeDataGenerator

iterate_nodes_at_random(batch_size=None, names=None)[source]#

Return a generator that yields the data of the nodes contained in the provided path.

Parameters

  • batch_size (int) – If it is not None, the generator will return batches of data with the target batch size. If Batch size is less than 1 it will return a single batch containing all the data.

  • names (fragile.core.typing.NamesData) – Names of the data attributes that will be yielded by the generator.

Returns

Generator providing the data corresponding to all the nodes of the tree sampled at random.

Return type

fragile.core.typing.NodeDataGenerator

iterate_branch(node_id, batch_size=None, names=None)[source]#

Return a generator that yields the data of the nodes contained in the provided path.

Parameters

  • node_id (fragile.core.typing.NodeId) – Ids of the last node of the branch that will be sampled. The first node will be the root node of the tree, and the last one will be the one with the provided node_id.

  • batch_size (int) – If it is not None, the generator will return batches of data with the target batch size. If Batch size is less than 1 it will return a single batch containing all the data.

  • names (fragile.core.typing.NamesData) – Names of the data attributes that will be yielded by the generator.

Returns

Generator providing the data corresponding to a branch of the internal tree.

Return type

fragile.core.typing.NodeDataGenerator

class fragile.callbacks.tree.HistoryTree(names=None, prune=False, root_id=DEFAULT_ROOT_ID, node_names=None, edge_names=('actions', 'dt'), next_prefix=NetworkxTree.DEFAULT_NEXT_PREFIX, **kwargs)[source]#

Bases: fragile.callbacks.data_tracking.TrackWalkersId

Tree data structure that keeps track of the visited states.

It allows to save the Swarm data after every iteration and methods to recover the sampled data after the algorithm run.

The data that will be stored in the graph it’s defined in the names parameter. For example:

  • If names is ["observs", "actions"], the observations of every visited state will be stored as node attributes, and actions will be stored as edge attributes.

  • If names if ["observs", "actions", "next_observs"] the same data will be stored, but when the data generator methods are called the observation corresponding to the next state will also be returned.

The attribute names also defines the order of the data returned by the generator.

As long as the data is stored in the graph (passing a valid names list at initialization, the order of the data can be redefined passing the names parameter to the generator method.

For example, if the names passed at initialization is ["states", "rewards"], you can call the generator methods with names=["rewards", "states", "next_states"] and the returned data will be a tuple containing (rewards, states, next_states).

Parameters

  • names (fragile.core.typing.NamesData) –

  • prune (bool) –

  • root_id (fragile.core.typing.NodeId) –

  • node_names (fragile.core.typing.NamesData) –

  • edge_names (fragile.core.typing.NamesData) –

  • next_prefix (str) –

name = tree#
property graph#
Return type

networkx.Graph

property data_tree#
property inputs#

Return a dictionary containing the data that this component needs to function.

Return type

fragile.core.typing.InputDict

__getattr__(item)[source]#
__repr__()[source]#

Return repr(self).

to_html()[source]#
setup(swarm)[source]#

Prepare the component during the setup phase of the Swarm.

reset(root_id=None, state=None, **kwargs)[source]#

Reset the internal state of the SwarmComponent.

Parameters

  • inplace (bool, optional) – Unused. Defaults to True.

  • root_walker (Optional[StateData], optional) – Set the internal state of the SwarmComponent to this value. Defaults to None.

  • states (Optional[StateData], optional) – Set the internal state of the SwarmComponent to this value. Defaults to None.

  • kwargs – Other parameters required to reset the component.

update_tree()[source]#
before_walkers()[source]#
after_evolve()[source]#
after_reset()[source]#
iterate_root_path(batch_size=None, names=None)[source]#

Return a generator that yields the data of the nodes contained in the provided path.

Parameters

  • batch_size (int) – If it is not None, the generator will return batches of data with the target batch size. If Batch size is less than 1 it will return a single batch containing all the data.

  • names (fragile.core.typing.NamesData) – Names of the data attributes that will be yielded by the generator.

Returns

Generator providing the data corresponding to a branch of the internal tree.

Return type

fragile.core.typing.NodeDataGenerator

get_root_graph()[source]#