pele.utils.disconnectivity_graph

class pele.utils.disconnectivity_graph.TreeLeastCommonAncestor

Source

class TreeLeastCommonAncestor:

Find the least common ancestor to a set of trees

TreeLeastCommonAncestor.get_all_paths_to_common_ancestor()

Source

def get_all_paths_to_common_ancestor(self):

return all the ancestors of all the input trees up to the least common ancestor

class pele.utils.disconnectivity_graph.Tree

Source

class Tree:

a Tree graph

Each member of this class is a node in a Tree. The node can have many children, but only one parent. If the node has no parents then it is the root node. If the node has no children then it is a leaf.

Tree.add_branch()

Source

def add_branch(self, branch):

make branch a child of this tree

Tree.make_branch()

Source

def make_branch(self):

return a new Tree which is a child of this Tree

Tree.get_branches()

Source

def get_branches(self):

return the list of branches of this tree

Tree.number_of_branches()

Source

def number_of_branches(self):

return the number of branches of this tree

Tree.is_leaf()

Source

def is_leaf(self):

return true if this tree has no descendants

Tree.number_of_leaves()

Source

def number_of_leaves(self):

return the number of leaves that are descendants of this Tree

Tree.get_leaves()

Source

def get_leaves(self):

return a list of the leaves that are descendants of this Tree

Tree.leaf_iterator()

Source

def leaf_iterator(self):

iterate through the leaves that are descendants of this Tree

Tree.get_all_trees()

Source

def get_all_trees(self):

iterator over all subtrees, including self

Tree.number_of_subtrees()

Source

def number_of_subtrees(self):

return the number total number of subtrees, including this one

Tree.get_ancestors()

Source

def get_ancestors(self):

iterate over ancestors excluding self

class pele.utils.disconnectivity_graph.DGTree

Source

class DGTree(Tree):

add a few functions to Tree to make it specific to disconnectivity graph

DGTree.get_one_minimum()

Source

def get_one_minimum(self):

return a single minimum that is in this tree

class pele.utils.disconnectivity_graph.ColorDGraphByGroups

Source

class ColorDGraphByGroups:

color the graph based on specified grouping of minima

Parameters:

tree_graph: a DGTree object

usually accessed by dgraph.tree_graph if dgraph is a DisconnectivityGraph object.

groupslist

list of groups of minima that should have the same color

Notes

For each node, check all minima for which the node is a parent. If all minima are contained on one of the groups, the node will be coloured to represent that group. If any minimum is not contained on one of the groups, the node is not coloured. If all minima are contained in groups but more than one group is represented, the node will be the colour of the last group listed

ColorDGraphByGroups.get_list_of_colors_mpl()

Source

def get_list_of_colors_mpl(self, number):

return a list of colors for the groups. Use matplotlib colormap

ColorDGraphByGroups.get_list_of_colors()

Source

def get_list_of_colors(self, number, colors=None):

return a list of colors for the groups

ColorDGraphByGroups.minimum_to_color()

Source

def minimum_to_color(self, minimum):

return the color of the minimum, or None if not colored

ColorDGraphByGroups.tree_get_colors()

Source

def tree_get_colors(self, tree):

return the color that this tree should be colored by

ColorDGraphByGroups.colors_to_color()

Source

def colors_to_color(self, colors):

if there are multiple colors for this tree, select which one to use

select the color which is listed last in self.color_list

ColorDGraphByGroups.run()

Source

def run(self):

main loop for the algorithm

class pele.utils.disconnectivity_graph.ColorDGraphByValue

Source

class ColorDGraphByValue:

color a disconnectivity graph by values associated with minima (e.g. order parameter)

Parameters:

tree_graph: a DGTree object

usually accessed by dgraph.tree_graph if dgraph is a DisconnectivityGraph object.

minimum_to_value: callable

A function that accepts a minimum and returns a float value. return None to indicate no color for this minimum

colormap: callable, optional

function which converts a float in (0,1) to a matplotlib color (RGB)

normalize_values: bool

if True the values will be normalized to fall between 0 and 1

Notes

Each node in the graph will be colored according to the value of the child minimum with the largest value. If any child minimum has value None then the node will not be colored

ColorDGraphByValue.tree_get_value()

Source

def tree_get_value(self, tree):

return the color that this tree should be colored by

ColorDGraphByValue.run()

Source

def run(self):

main loop for the algorithm

class pele.utils.disconnectivity_graph.DisconnectivityGraph

Source

class DisconnectivityGraph:

make a disconnectivity graph

Parameters:

grapha networkx graph

a graph with Minimum objects as nodes and transition states defining the edges. You can use the function database2graph() defined in this module to create this from a database.

>>> from pele.utils.disconnectivity_graph import database2graph
>>> graph = database2graph(database)
>>> dg = DisconnectivityGraph(graph)

nlevelsint

how many levels at which to bin the transition states

Emaxfloat

maximum energy for transition state cutoff. Default is the maximum energy of all transition states.

minimalist of Minima

a list of minima to ensure are displayed in the graph. e.g. they will be displayed even if they’re in a connected cluster smaller than smaller than subgraph_size

subgraph_sizeint

if subgraph_size is not None then all disconnected graphs of size greater than subraph_size will be included.

order_by_energybool

order the subtrees by placing ones with lower energy closer to the center

order_by_basin_sizebool

order the subtrees by placing larger basins closer to the center

center_gminbool

when a node splits into its daughter nodes, the one containing the global minimum is always placed centrally (even if other nodes carry more minima). This does not guarantee that the global minimum is central in the overall diagram because other nodes may push the one containing the global minimum over to one side

include_gminbool

make sure to include the global minimum, even if it is not part of the main connected region

node_offsetfloat

offset between 0 and 1 for how to draw the angled lines. 0 for no angle, draw horizontally out then vertically down. 1 for angled lines all the way to the next energy level

energy_attributestring, optional

attribute which contains energy. default is energy. This attribute can be used to generate free energy disconnectivity graphs

order_by_valuecallable, optional, v = order_by_value(m)

If this function is passed the minima at each level will be sorted by this value with small values to the left. A group of minima will be sorted according to the smallest value in the group.

See also

pele.storage.Database

The database format in which minima and transition states are stored in pele

Examples

The scripts/make_disconnectivity_graph.py script makes a disconnectivity graph from the command line.

These examples assume a Database with minima already exists

>>> import matplotlib.pyplot as plt
>>> graph = database2graph(database)
>>> dg = DisconnectivityGraph(graph)
>>> dg.calculate()
>>> dg.plot()
>>> plt.show()

DisconnectivityGraph.set_energy_levels()

Source

def set_energy_levels(self, elevels):

manually set the energy levels

DisconnectivityGraph.get_minima_layout()

Source

def get_minima_layout(self):

return the x position of the minima

DisconnectivityGraph.get_tree_layout()

Source

def get_tree_layout(self):

Returns the x position of the trees

DisconnectivityGraph.calculate()

Source

def calculate(self):

do the calculations necessary to draw the diconnectivity graph

DisconnectivityGraph.color_by_group()

Source

def color_by_group(self, groups, colors=None):

color the graph based on specified grouping of minima

Parameters:

groupslist

list of groups of minima that should have the same color

Notes

For each node, check all minima for which the node is a parent. If all minima are contained on one of the groups, the node will be coloured to represent that group. If any minimum is not contained on one of the groups, the node is not coloured. If all minima are contained in groups but more than one group is represented, the node will be the colour of the last group listed

DisconnectivityGraph.color_by_value()

Source

def color_by_value(
    self, minimum_to_value, colormap=None, normalize_values=True
):

color the graph by values associated with minima (e.g. order parameter)

Parameters:

minimum_to_value: callable

A function that accepts a minimum and returns a float value. return None to indicate no color for this minimum

colormap: callable, optional

function which converts a float in (0,1) to a matplotlib color (RGB)

normalize_values: bool

if True the values will be normalized to fall between 0 and 1

Notes

Each node in the graph will be colored according to the value of the child minimum with the largest value. If any child minimum has value None then the node will not be colored

DisconnectivityGraph.draw_minima()

Source

def draw_minima(self, minima, axes=None, **kwargs):

draw a specified list of minima as points

Parameters:

minimalist of minima

axesmatlplotlib axes

Draw them on these axes. If None, use self.axes.

kwargskwargs

additional keyword arguments will be passed to matplolib.Axes.scatter(). Use this to specify how to draw the points.

DisconnectivityGraph.plot()

Source

def plot(
    self,
    show_minima=False,
    show_trees=False,
    linewidth=0.5,
    axes=None,
    title=None,
):

draw the disconnectivity graph using matplotlib

don’t forget to call calculate() first

also, you must call pyplot.show() to actually see the plot

DisconnectivityGraph.label_minima()

Source

def label_minima(self, minima_labels, axes=None, rotation=60.0, **kwargs):

label the specified minima

Parameters:

minima_labels: dict

dictionary with minima as keys and labels as values. i.e. label = minima_labels[minimum]

axes: matplotlib axis object, optional

The axes we are working on

rotation: float

angle (in degrees) of how much to rotate the text

kwargs: kwargs

additional keyword arguments are passed on to matplotlib ax.set_xticklabels()

Notes

if the labels are outside of the figure bounding box you can fix it with plt.tight_layout() or fig.tight_layout()

DisconnectivityGraph.show()

Source

def show(self):

simple wrapper for matplotlib.pyplot.show()

DisconnectivityGraph.savefig()

Source

def savefig(self, *args, **kwargs):

simple wrapper for matplotlib.pyplot.savefig()