Connectivity Analyzer Analysis

Atomic connectivity and bond-event analysis utilities.

This module provides tools for extracting, aggregating, and analyzing atomic connectivities derived from ReaxFF fort.7 data.

Connectivities describe the bonding network between atoms in each frame, including bond partners and bond orders. The utilities here convert raw fort.7 connectivity columns into tidy edge lists, adjacency tables, time-series bond traces, and discrete bond formation/breakage events.

Typical use cases include:

• building bond (edge) lists with bond orders for chemical analysis
• aggregating connectivity statistics across frames
• tracking bond-order time series for specific atom pairs
• detecting bond formation and breakage events with noise suppression
• visual debugging of bond-event detection parameters

bond_events(handler, frames=None, iterations=None, *, src=None, dst=None, threshold=0.35, hysteresis=0.05, smooth='ma', window=7, ema_alpha=None, min_run=3, xaxis='iter', undirected=True)

Detect bond formation and breakage events from bond-order time series.

Events are identified using optional smoothing, Schmitt-trigger hysteresis, and flicker suppression to avoid noise-induced toggling.

Works on

Fort7Handler — fort.7

Parameters:

Name	Type	Description	Default
handler	Fort7Handler	Parsed fort.7 handler.	required
src	int	Restrict analysis to a specific atom pair.	None
dst	int	Restrict analysis to a specific atom pair.	None
threshold	float	Bond-order threshold for bonded state.	0.35
hysteresis	float	Hysteresis half-width around the threshold.	0.05
smooth	('ma', 'ema')	Smoothing method applied before event detection.	"ma"
window	int	Smoothing window size.	7
min_run	int	Minimum run length to suppress flicker.	3
xaxis	('iter', 'frame')	X-axis used in the output.	"iter"
undirected	bool	Treat bonds as undirected.	True

Returns:

Type	Description
DataFrame	Event table with columns: src, dst, event, frame_idx, iter, x_axis, bo_at_event.

Examples:

>>> ev = bond_events(f7, src=1, dst=2)

bond_timeseries(handler, frames=None, iterations=None, undirected=True, bo_threshold=0.0, as_wide=False)

Track bond-order time series for all bonds across selected frames.

Missing bonds in a frame are filled with bond order zero.

Works on

Fort7Handler — fort.7

Parameters:

Name	Type	Description	Default
handler	Fort7Handler	Parsed fort.7 handler.	required
frames	Indexish	Frame indices or iteration numbers to include.	None
iterations	Indexish	Frame indices or iteration numbers to include.	None
undirected	bool	Treat bonds as undirected.	True
bo_threshold	float	Values below this threshold are set to zero.	0.0
as_wide	bool	If True, return a wide matrix (frames × bonds).	False

Returns:

Type	Description
DataFrame	Bond-order time series in tidy (long) or wide format.

Examples:

>>> ts = bond_timeseries(f7, bo_threshold=0.1)

connection_list(handler, frames=None, iterations=None, min_bo=0.0, undirected=True, aggregate='max', include_self=False)

Build a tidy bond (edge) list with bond orders as weights.

Works on

Fort7Handler — fort.7

Parameters:

Name	Type	Description	Default
handler	Fort7Handler	Parsed fort.7 handler.	required
frames	Indexish	Frame indices or iteration numbers to include.	None
iterations	Indexish	Frame indices or iteration numbers to include.	None
min_bo	float	Minimum bond order to keep.	0.0
undirected	bool	If True, treat bonds as undirected and merge A–B / B–A duplicates.	True
aggregate	('max', 'mean')	Aggregation rule for bond order when merging duplicates.	"max"
include_self	bool	If True, keep self-edges (usually False).	False

Returns:

Type	Description
DataFrame	Tidy edge list with columns: frame_idx, iter, src, dst, bo, j.

Examples:

>>> edges = connection_list(f7, frames=[0, 1], min_bo=0.3)

connection_stats_over_frames(handler, frames=None, iterations=None, min_bo=0.0, undirected=True, how='mean')

Aggregate bond statistics across selected frames.

Works on

Fort7Handler — fort.7

Parameters:

Name	Type	Description	Default
handler	Fort7Handler	Parsed fort.7 handler.	required
frames	Indexish	Frame indices or iteration numbers to include.	None
iterations	Indexish	Frame indices or iteration numbers to include.	None
min_bo	float	Minimum bond order to consider.	0.0
undirected	bool	Treat bonds as undirected.	True
how	('mean', 'max', 'count')	Aggregation rule across frames.	"mean"

Returns:

Type	Description
DataFrame	Table with columns src, dst, value representing the aggregated bond metric.

Examples:

>>> stats = connection_stats_over_frames(f7, how="count")

connection_table(handler, frame, min_bo=0.0, undirected=True, fill_value=0.0)

Build a dense adjacency (connectivity) table for a single frame.

Works on

Fort7Handler — fort.7

Parameters:

Name	Type	Description	Default
handler	Fort7Handler	Parsed fort.7 handler.	required
frame	int	Frame index to extract.	required
min_bo	float	Minimum bond order to include.	0.0
undirected	bool	Treat bonds as undirected.	True
fill_value	float	Value used for absent bonds.	0.0

Returns:

Type	Description
DataFrame	Adjacency-like table with index=source atom and columns=destination atom, values equal to bond order.

Examples:

>>> tbl = connection_table(f7, frame=0, min_bo=0.2)

debug_bond_trace_overlay(handler, src, dst, *, smooth='ema', window=8, hysteresis=0.05, threshold=0.1, min_run=0, xaxis='iter', save=None)

Plot a diagnostic overlay for a single bond-order time series.

The plot shows raw and smoothed bond order, hysteresis bands, and detected formation/breakage events. This is intended for tuning event-detection parameters.

Works on

Fort7Handler — fort.7

Parameters:

Name	Type	Description	Default
handler	Fort7Handler	Parsed fort.7 handler.	required
src	int	Atom indices defining the bond.	required
dst	int	Atom indices defining the bond.	required
smooth	str	Smoothing method and window size.	'ema'
window	str	Smoothing method and window size.	'ema'
hysteresis	float	Event-detection parameters.	0.05
threshold	float	Event-detection parameters.	0.05
save	str	File path to save the plot. If None, the plot is shown interactively.	None

Returns:

Type	Description
None

Examples:

>>> debug_bond_trace_overlay(f7, 1, 2, threshold=0.2)