aizynthfinder.search.mcts package

Submodules

aizynthfinder.search.mcts.node module

Module containing a class that represents a node in the search tree.

class aizynthfinder.search.mcts.node.MctsNode(state, owner, config, parent=None)

Bases: object

A node in the search tree.

The children are instantiated lazily for efficiency: only when a child is selected the reaction to create that child is applied.

Properties of an instantiated children to a node can be access with:

children_attr = node[child]

the return value is a dictionary with keys “action”, “value”, “prior” and “visitations”.

Variables:

  • is_expanded – if the node has had children added to it

  • is_expandable – if the node is expandable

  • tree – the tree owning this node

Parameters:

  • state (MctsState) – the state of the node

  • owner (MctsSearchTree) – the tree that owns this node

  • config (Configuration) – settings of the tree search algorithm

  • parent (Optional[MctsNode]) – the parent node, defaults to None

classmethod create_root(smiles, tree, config)

Create a root node for a tree using a SMILES.

Parameters:

  • smiles (str) – the SMILES representation of the root state

  • tree (MctsSearchTree) – the search tree

  • config (Configuration) – settings of the tree search algorithm

Returns:

the created node

Return type:

MctsNode

classmethod from_dict(dict_, tree, config, molecules, parent=None)

Create a new node from a dictionary, i.e. deserialization.

Parameters:

  • dict – the serialized node

  • tree (MctsSearchTree) – the search tree

  • config (Configuration) – settings of the tree search algorithm

  • molecules (MoleculeDeserializer) – the deserialized molecules

  • parent (Optional['MctsNode']) – the parent node

  • dict_ (StrDict)

Returns:

a deserialized node

Return type:

MctsNode

property children: List['MctsNode']

Returns all of the instantiated children.

Returns:

the children

property is_solved: bool

Return if the state is solved.

property parent: 'MctsNode' | None

Return the parent of the node.

property state: MctsState

Return the underlying state of the node.

actions_to()

Returns the actions leading to this node

Returns:

the list of actions

Return type:

List[RetroReaction]

backpropagate(child, value_estimate)

Update the number of visitations of a particular child and its value.

Parameters:

  • child (MctsNode) – the child node

  • value_estimate (float) – the value to add to the child value

Return type:

None

children_view()

Creates a view of the children attributes. Each of the list returned is a new list, although the actual children are not copied.

The return dictionary will have keys “actions”, “values”, “priors”, “visitations” and “objects”.

Returns:

the view

Return type:

StrDict

expand()

Expand the node.

Expansion is the process of creating the children of the node, without instantiating a child object. The actions and priors are taken from the policy network.

If immediate instantiation is marked for some policies, however, the children nodes will be instantiated.

Return type:

None

is_terminal()

Node is terminal if its unexpandable, or the internal state is terminal (solved).

Returns:

the terminal attribute of the node

Return type:

bool

path_to()

Return the path to this node, which is a list of actions and a list of node.

Returns:

the actions and nodes

Return type:

Tuple[List[RetroReaction], List[MctsNode]]

promising_child()

Return the child with the currently highest Q+U.

The selected child will be instantiated if it has not been already.

If no actions could be found that were applicable, the method will return None.

Returns:

the child

Return type:

Optional[‘MctsNode’]

serialize(molecule_store)

Serialize the node object to a dictionary.

Parameters:

molecule_store (MoleculeSerializer) – the serialized molecules

Returns:

the serialized node

Return type:

StrDict

to_reaction_tree()

Return reaction tree from the path of actions and nodes leading to this node.

Returns:

the constructed tree

Return type:

ReactionTree

class aizynthfinder.search.mcts.node.ParetoMctsNode(state, owner, config, parent=None)

Bases: MctsNode

A node in a multi-objective tree search.

This implements the algorithm from:

Chen W., Liu L. Pareto Monte Carlo Tree Search for Multi-Objective Informative Planning Robotics: Science and Systems 2019, 2012 arXiv:2111.01825

The main difference compared to the standard MCTS algorithm is:
  • Children stats: the values, cumulative reward and priors are nested

    list, with one value per objective

  • Selection: children on Pareto front are computed, and

    a child from this set is taken randomly

This implementation disregards the prior of the children when it has been visited once.

It is assumed that all objectives are to be maximised.

Parameters:
backpropagate(child, value_estimate)

Update the number of visitations of a particular child and its value.

Parameters:

  • child (MctsNode) – the child node

  • value_estimate (List[float]) – the value to add to the child value

Return type:

None

children_view()

Creates a view of the children attributes. Each of the list returned is a new list, although the actual children are not copied.

The return dictionary will have keys “actions”, “values”, “priors”, “visitations”, “rewards_cum”, and “objects”.

Returns:

the view

Return type:

StrDict

serialize(molecule_store)

Serialize the node object to a dictionary.

Parameters:

molecule_store (MoleculeSerializer) – the serialized molecules

Returns:

the serialized node

Return type:

StrDict

aizynthfinder.search.mcts.search module

Module containing a class that holds the tree search

class aizynthfinder.search.mcts.search.MctsSearchTree(config, root_smiles=None)

Bases: object

Encapsulation of the search tree.

Variables:

  • root – the root node

  • config – the configuration of the search tree

Parameters:

  • config (Configuration) – settings of the tree search algorithm

  • root_smiles (Optional[str]) – the root will be set to a node representing this molecule, defaults to None

classmethod from_json(filename, config)

Create a new search tree by deserialization from a JSON file

Parameters:

  • filename (str) – the path to the JSON node

  • config (Configuration) – the configuration of the search

Returns:

a deserialized tree

Return type:

MctsSearchTree

backpropagate(from_node)

Backpropagate the value estimate and update all nodes from a given node all the way to the root.

Parameters:

from_node (MctsNode) – the end node of the route to update

Return type:

None

compute_reward(node)

Compute the reward of a node in the search tree, using one of

  1. Single-objective

  2. Multi-objective

  3. Weighted-sum of multiple specified rewards

Parameters:

node (MctsNode) – the node to compute the reward for

Returns:

the value from the scorer(s)

Return type:

Union[float, Sequence[float]]

graph(recreate=False)

Construct a directed graph object with the nodes as vertices and the actions as edges attribute “action”.

Parameters:

recreate (bool) – if True will construct the graph even though it is cached, defaults to False

Returns:

the graph object

Raises:

ValueError – if the tree is not defined

Return type:

DiGraph

nodes()

Return all the nodes in the search tree

Return type:

List[MctsNode]

one_iteration()
Perform one iteration of

  1. Selection

  2. Expansion

  3. Rollout

  4. Backpropagation

Returns:

if a solution was found

Return type:

bool

select_leaf()

Traverse the tree selecting the most promising child at each step until leaf node returned.

Returns:

the leaf node

Raises:

ValueError – if the tree is not defined

Return type:

MctsNode

serialize(filename)

Serialize the search tree to a JSON file

Parameters:

filename (str) – the path to the JSON file

Raises:

ValueError – if the tree is not defined

Return type:

None

aizynthfinder.search.mcts.state module

Module contain a class that encapsulate the state of search tree node.

class aizynthfinder.search.mcts.state.MctsState(mols, config)

Bases: object

Encapsulation of the molecular state of a node.

A state consists of an immutable list of molecules that are either solved (can be found in stock) or that potentially can be expanded to new molecules by applying a reaction on them.

The class is hashable and comparable by the inchi keys of all the molecules.

Variables:

  • mols – the list of molecules

  • expandable_mols – the list of molecules not in stock

  • stock – the configured stock

  • in_stock_list – for each molecule if they are in stock

  • is_solved – is true if all molecules are in stock:

  • max_transforms – the maximum of the transforms of the molecule

  • is_terminal – is true if the all molecules are in stock or if the maximum transforms has been reached

  • expandables_hash – an hash string computed on the expandable molecules

Parameters:

  • mols (Sequence[TreeMolecule]) – the molecules of the state

  • config (Configuration) – settings of the tree search algorithm

classmethod from_dict(dict_, config, molecules)

Create a new state from a dictionary, i.e. deserialization

Parameters:

  • dict (dict) – the serialized state

  • config (Configuration) – settings of the tree search algorithm

  • molecules (MoleculeDeserializer) – the deserialized molecules

  • dict_ (StrDict)

Returns:

a deserialized state

Return type:

State

property stock_availability: List[str]

Returns a list of availabilities for all molecules

Returns:

the list

Return type:

list of str

serialize(molecule_store)

Serialize the state object to a dictionary

Parameters:

molecule_store (MolecularSerializer) – the serialized molecules

Returns:

the serialized state

Return type:

dict

to_image(ncolumns=6)

Constructs an image representation of the state

Parameters:

ncolumns (int, optional) – number of molecules per row, defaults to 6

Returns:

the image representation

Return type:

a PIL image

aizynthfinder.search.mcts.utils module

Module containing utility routines for MCTS. This is not part of public interface

class aizynthfinder.search.mcts.utils.ReactionTreeFromSuperNode(*args, **kwargs)

Bases: ReactionTreeLoader

Creates a reaction tree object from MCTS-like nodes and reaction objects

Parameters:

  • args (Any)

  • kwargs (Any)

aizynthfinder.search.mcts.utils.route_to_node(from_node)

Return the route to a give node to the root.

Will return both the actions taken to go between the nodes, and the nodes in the route themselves.

Parameters:

from_node (MctsNode) – the end of the route

Returns:

the route

Return type:

Tuple[List[RetroReaction], List[MctsNode]]

Module contents

Sub-package containing MCTS routines