Electrostatics Analyzer Analysis

Electrostatics analysis utilities (dipole and polarization).

This module provides fast, vectorized electrostatics calculations for ReaxFF simulations, including total and local dipoles, polarization, and polarization–electric-field hysteresis analysis.

Design notes

• Heavy computations are vectorized with NumPy for performance.
• Coordinates, charges, and connectivity are preloaded once per frame batch.
• Local electrostatics operate on atom-centered clusters using connectivity.
• Polarization volumes can be estimated via convex hull or bounding box.

Typical use cases include:

• computing total dipole or polarization vs time/frame
• computing local dipoles around selected core atom types
• generating polarization–field hysteresis loops

dipoles_polarizations_over_multiple_frames(xh, f7, *, scope='total', core_types=None, mode='dipole', volume_method=None, frames=None, every=1)

Compute dipoles or polarization over multiple frames (fast path).

Works on

XmoloutHandler + Fort7Handler — xmolout + fort.7

Parameters:

Name	Type	Description	Default
scope	('total', 'local')	Whether to compute total system electrostatics or local clusters.	"total"
core_types	sequence of str	Required when scope="local".	None
mode	('dipole', 'polarization')	Quantity to compute.	"dipole"
frames	sequence of int	Frame indices to include.	None
every	int	Subsampling stride.	1

Returns:

Type	Description
DataFrame	Electrostatics results with frame and iteration metadata.

Examples:

>>> df = dipoles_polarizations_over_multiple_frames(xh, f7, mode="dipole")

polarization_field_analysis(xh, f7, f78, ctrl, *, field_var='field_z', aggregate=None, x_variable='field_z', y_variable='P_z (uC/cm^2)')

Perform polarization–electric-field hysteresis analysis.

Works on

XmoloutHandler + Fort7Handler + Fort78Handler + ControlHandler

Parameters:

Name	Type	Description	Default
field_var	str	Electric-field component to use.	"field_z"
aggregate	('mean', 'max', 'min', 'last')	Aggregation mode over identical field values.	"mean","max","min","last"
x_variable	str	Columns used for zero-crossing detection.	'field_z'
y_variable	str	Columns used for zero-crossing detection.	'field_z'

Returns:

Name	Type	Description
joint_df	DataFrame	Polarization and electric field per frame.
aggregated_df	DataFrame	Aggregated hysteresis curve.
y_zeros	list[float]	Zero crossings of polarization.
x_zeros	list[float]	Zero crossings of electric field.

Examples:

>>> joint, agg, p0, e0 = polarization_field_analysis(xh, f7, f78, ctrl)