Signal Ops Utility

Detect and clean binary states from continuous numerical signals.

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.

Usage context

State extraction: Detect ON/OFF states from analog response signals.
Hysteresis control: Apply Schmitt-trigger logic to reduce noise switching.
Post-processing: Remove short-lived flicker in binary trajectories.

Function: `schmitt_hysteresis`

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.

Notes

An example can be found at: https://www.geeksforgeeks.org/electronics-engineering/schmitt-trigger/

Examples:

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

Function: `clean_flicker`

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.