chemparseplot.plot.disconnectivity

Approximate disconnectivity graphs from minima databases.

The classic disconnectivity graph needs transition states; a hopping campaign records only quenched minima. These helpers draw the superbasin merge tree of a descriptor-space k-nearest-neighbour graph instead: at each energy level the minima below it split into connected components, and components merge as the level rises. That approximation is a rendering of the database made for reading the figure; it should never feed a reported statistic.

Basins can be lumped for display by spectral clustering on the same graph. Everything is iterative: with a thousand minima the merge chains grow deeper than any recursion limit.

Added in version 1.10.0.

Module Contents

Classes

Node	A merge-tree node; leaves carry their minimum’s index.

Functions

dedup	Merge near-identical minima, keeping the lowest-energy representative.
knn_graph	Symmetric k-nearest-neighbour adjacency in descriptor space.
bridge_components	Weakly connect graph components through their closest point pairs.
spectral_basins	Display-only basin assignment by spectral clustering on the graph.
merge_tree	Superbasin merge tree over an energy-threshold sweep.
iter_nodes	Post-order traversal without recursion.
layout	Leaf x positions in tree order, children sorted deepest-first.
paint	Colour each subtree by the spectral basin of its deepest minimum.
draw	Vertical stems to the merge level, horizontal bars at merges.
plot_disconnectivity	Full pipeline: dedup, graph, merge tree, spectral paint, draw.

Data

BASIN_PALETTE

API

chemparseplot.plot.disconnectivity.BASIN_PALETTE

None

chemparseplot.plot.disconnectivity.dedup(matrix, energies, tol)

Merge near-identical minima, keeping the lowest-energy representative.

Returns the kept row indices, lowest energy first.

Added in version 1.10.0.

chemparseplot.plot.disconnectivity.knn_graph(matrix, k=6)

Symmetric k-nearest-neighbour adjacency in descriptor space.

Added in version 1.10.0.

chemparseplot.plot.disconnectivity.bridge_components(adjacency, matrix, weight=0.1)

Weakly connect graph components through their closest point pairs.

Spectral clustering assumes a connected graph; a k-NN graph over a minima database often fragments. One weak edge per component pair (closest points in descriptor space) restores the geometry without drowning the strong intra-basin structure.

Added in version 1.10.0.

chemparseplot.plot.disconnectivity.spectral_basins(adjacency, n_basins, rng, matrix=None)

Display-only basin assignment by spectral clustering on the graph.

With matrix given, disconnected components are weakly bridged through their closest descriptor pairs first.

Added in version 1.10.0.

class chemparseplot.plot.disconnectivity.Node(level, children=None, leaf=None)

A merge-tree node; leaves carry their minimum’s index.

Added in version 1.10.0.

Initialization

__slots__

(‘argmin’, ‘children’, ‘emin’, ‘leaf’, ‘level’, ‘x’)

chemparseplot.plot.disconnectivity.merge_tree(adjacency, energies, levels)

Superbasin merge tree over an energy-threshold sweep.

Added in version 1.10.0.

chemparseplot.plot.disconnectivity.iter_nodes(root)

Post-order traversal without recursion.

Added in version 1.10.0.

chemparseplot.plot.disconnectivity.layout(root)

Leaf x positions in tree order, children sorted deepest-first.

Added in version 1.10.0.

chemparseplot.plot.disconnectivity.paint(root, assign, palette=None)

Colour each subtree by the spectral basin of its deepest minimum.

Added in version 1.10.0.

chemparseplot.plot.disconnectivity.draw(ax, root, colors, lw=1.1)

Vertical stems to the merge level, horizontal bars at merges.

Added in version 1.10.0.

chemparseplot.plot.disconnectivity.plot_disconnectivity(ax, matrix, energies, *, dedup_tol=0.15, knn=6, n_levels=48, n_basins=5, rng=None)

Full pipeline: dedup, graph, merge tree, spectral paint, draw.

Returns (kept_indices, root) so callers can label leaves.

Added in version 1.10.0.