Signal Ops Utility

Signal-processing utilities for binary state detection.

This module provides helper functions for applying hysteresis-based state detection and post-processing of boolean time-series data, commonly encountered in ReaxFF simulations and field-driven analyses.

Typical use cases include:

• detecting ON/OFF states in polarization or dipole signals
• applying Schmitt-trigger hysteresis to noisy response curves
• removing spurious state flickering in thresholded time series

clean_flicker(state, min_run)

Remove short-lived state transitions in a boolean sequence.

This function suppresses brief ON or OFF segments shorter than a specified minimum run length, producing a cleaner and more physically meaningful state trajectory.

Parameters:

Name	Type	Description	Default
state	array-like of bool	Boolean state sequence (e.g., output of schmitt_hysteresis).	required
min_run	int	Minimum number of consecutive samples required to retain a state segment.	required

Returns:

Type	Description
ndarray	Cleaned boolean state array with flicker removed.

Examples:

>>> clean_state = clean_flicker(state, min_run=5)

schmitt_hysteresis(y, th, hys, init_on=None)

Apply Schmitt-trigger hysteresis to a 1D signal.

This function converts a continuous signal into a boolean state using separate ON and OFF thresholds to suppress noise-induced state switching.

The switching rules are: - ON when y >= th + hys / 2 - OFF when y <= th - hys / 2

Parameters:

Name	Type	Description	Default
y	array - like	Input signal values (e.g., polarization, dipole moment).	required
th	float	Central threshold value.	required
hys	float	Total hysteresis width.	required
init_on	bool	Initial state at the first sample. If not provided, the initial state is inferred from the first data point.	None

Returns:

Type	Description
ndarray	Boolean array representing the ON/OFF state over the signal.

Examples:

>>> state = schmitt_hysteresis(signal, th=0.0, hys=0.1)