Plotter Utility
Plotting utilities for ReaxKit.
This module provides a collection of lightweight, reusable plotting helpers built on Matplotlib for visualizing ReaxFF simulation data. The functions support common use cases such as time-series plots, multi-axis comparisons, stacked subplots, 3D atom visualizations, sensitivity (tornado) plots, and 2D projections of 3D data.
All helpers share a consistent save/show behavior and are designed to be used directly by analyzers and workflows.
directed_plot(x, y, *, figsize=(10, 6), title='', xlabel='', ylabel='', color='blue', linestyle='-', arrow_color='red', arrow_width=0.003, grid=False, xlim=None, ylim=None, hline=None, hline_kwargs=None, legend=False, save=None)
Plot a 2D path with directional arrows.
This helper visualizes progression along a trajectory by drawing a
continuous line through (x, y) points and overlaying arrows that
indicate direction. It is useful for trajectories, energy paths, or
ordered parameter sweeps.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
x
|
sequence of float
|
Path coordinates. |
required |
y
|
sequence of float
|
Path coordinates. |
required |
title
|
str
|
Plot title and axis labels. |
''
|
xlabel
|
str
|
Plot title and axis labels. |
''
|
ylabel
|
str
|
Plot title and axis labels. |
''
|
save
|
str or Path
|
Output directory or file path. |
None
|
Returns:
| Type | Description |
|---|---|
None
|
|
dual_yaxis_plot(x, y1, y2, *, figsize=(10, 6), title='', xlabel='', ylabel1='', ylabel2='', color1='blue', linestyle1='-', marker1='', color2='green', linestyle2='--', marker2='', xlim=None, ylim1=None, ylim2=None, grid=False, hline1=None, hline1_kwargs=None, hline2=None, hline2_kwargs=None, vline=None, vline_kwargs=None, save=None)
Plot two datasets against a shared x-axis with separate y-axes.
This function is intended for comparing quantities with different units or magnitudes on the same plot (e.g., energy vs temperature).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
x
|
sequence of float
|
Shared x-axis values. |
required |
y1
|
sequence of float
|
Data for the left and right y-axes. |
required |
y2
|
sequence of float
|
Data for the left and right y-axes. |
required |
title
|
str
|
Labels and title. |
''
|
xlabel
|
str
|
Labels and title. |
''
|
ylabel1
|
str
|
Labels and title. |
''
|
ylabel2
|
str
|
Labels and title. |
''
|
save
|
str or Path
|
Output directory or file path. |
None
|
Returns:
| Type | Description |
|---|---|
None
|
|
heatmap2d_from_3d(coords, values, *, plane='xy', bins=50, xlim=None, ylim=None, agg='mean', vmin=None, vmax=None, cmap='viridis', title='2D aggregated heatmap', figsize=(6.5, 5.5), save=None, show_colorbar=True, show_message=True)
Project 3D point data onto a 2D plane and aggregate values on a grid.
This function bins projected coordinates onto a regular grid and aggregates per-point values using a specified operation, producing a 2D heatmap suitable for planar analysis.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
coords
|
(array - like, shape(N, 3))
|
3D coordinates. |
required |
values
|
(array - like, shape(N))
|
Values to aggregate. |
required |
plane
|
('xy', 'xz', 'yz')
|
Projection plane. |
'xy'
|
agg
|
('mean', 'max', 'min', 'sum', 'count')
|
Aggregation method. |
'mean'
|
save
|
str or Path
|
Output directory or file path. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
Figure
|
|
grid |
ndarray
|
Aggregated 2D grid. |
xedges, yedges : numpy.ndarray
|
Bin edges along each axis. |
multi_subplots(subplots, *, title=None, xlabel=None, ylabel=None, sharex=False, sharey=False, legend=True, grid=False, figsize=(8.0, 6.0), save=None)
Create multiple vertically stacked subplots.
Each subplot accepts the same series specification used by
single_plot, allowing consistent plotting across panels.
Titles and axis labels may be shared or specified per subplot.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
subplots
|
sequence of sequence of dict
|
Series definitions for each subplot. |
required |
title
|
str or sequence of str
|
Global or per-subplot titles and labels. |
None
|
xlabel
|
str or sequence of str
|
Global or per-subplot titles and labels. |
None
|
ylabel
|
str or sequence of str
|
Global or per-subplot titles and labels. |
None
|
save
|
str or Path
|
Output directory or file path. |
None
|
Returns:
| Type | Description |
|---|---|
Figure
|
The created figure. |
scatter3d_points(coords, values, *, title='atoms (3D)', s=8.0, alpha=0.9, vmin=None, vmax=None, cmap='coolwarm', figsize=(7.5, 6.0), elev=22.0, azim=38.0, save=None, show_colorbar=True, show_message=True)
Render a 3D scatter plot of atomic coordinates.
Points are colored by a scalar per-atom property such as partial charge or bond-order sum, enabling spatial visualization of atom-resolved quantities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
coords
|
(array - like, shape(N, 3))
|
Atomic coordinates. |
required |
values
|
(array - like, shape(N))
|
Scalar values mapped to colors. |
required |
save
|
str or Path
|
Output directory or file path. |
None
|
Returns:
| Type | Description |
|---|---|
Figure
|
The created figure. |
single_plot(x=None, y=None, *, series=None, hlines=None, title=None, xlabel=None, ylabel=None, save=None, legend=False, figsize=(8.0, 3.2), plot_type='line')
Create a single plot for one or multiple data series.
This function supports both simple (x, y) inputs and flexible
multi-series plotting using a list of dictionaries. It can render
line or scatter plots, add horizontal reference lines, and
automatically save or display the figure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
x
|
sequence of float
|
Data to plot when using the simple API. |
None
|
y
|
sequence of float
|
Data to plot when using the simple API. |
None
|
series
|
sequence of mapping
|
Multi-series specification with keys such as |
None
|
hlines
|
sequence
|
Horizontal reference lines specified as floats, tuples, or dicts. |
None
|
title
|
str
|
Plot title and axis labels. |
None
|
xlabel
|
str
|
Plot title and axis labels. |
None
|
ylabel
|
str
|
Plot title and axis labels. |
None
|
save
|
str or Path
|
Output directory or file path. If not provided, the plot is shown. |
None
|
legend
|
bool
|
Whether to display a legend. |
False
|
figsize
|
tuple of float
|
Figure size. |
(8.0, 3.2)
|
plot_type
|
('line', 'scatter')
|
Type of plot to generate. |
'line'
|
Returns:
| Type | Description |
|---|---|
Figure
|
The created figure. |
tornado_plot(labels, min_vals, max_vals, *, median_vals=None, title='Tornado Plot', xlabel='Value', ylabel='Value', save=None, top=0, vline=None, left_color='#1F77B4', right_color=(225 / 255, 113 / 255, 29 / 255))
Create a tornado plot to visualize sensitivity or uncertainty ranges.
Each label is represented by a horizontal bar spanning from a minimum to a maximum value. Bars are ordered by total span, highlighting the most influential parameters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
labels
|
sequence of str
|
Parameter or variable names. |
required |
min_vals
|
sequence of float
|
Lower and upper bounds for each parameter. |
required |
max_vals
|
sequence of float
|
Lower and upper bounds for each parameter. |
required |
median_vals
|
sequence of float
|
Optional central estimates to mark on each bar. |
None
|
save
|
str or Path
|
Output directory or file path. |
None
|
Returns:
| Type | Description |
|---|---|
None
|
|