tud_lbm.io.analysis.accelerations.acceleration_analysis
=======================================================

.. py:module:: tud_lbm.io.analysis.accelerations.acceleration_analysis

.. autoapi-nested-parse::

   Acceleration-peak analysis of the Ca(t) curve for regime classification.

   Computes the raw second backward difference of capillary number ``Ca`` over
   normalised iteration, locates the peak-acceleration / peak-deceleration pair,
   and derives the slope window used by regime classification (see
   :mod:`tud_lbm.io.analysis.accelerations.regime_classification`).



Attributes
----------

.. autoapisummary::

   tud_lbm.io.analysis.accelerations.acceleration_analysis.Smoothing


Classes
-------

.. autoapisummary::

   tud_lbm.io.analysis.accelerations.acceleration_analysis.AccelerationResult


Functions
---------

.. autoapisummary::

   tud_lbm.io.analysis.accelerations.acceleration_analysis.compute_acceleration
   tud_lbm.io.analysis.accelerations.acceleration_analysis.find_slope_window
   tud_lbm.io.analysis.accelerations.acceleration_analysis.save_diagnostic_plot


Module Contents
---------------

.. py:data:: Smoothing

.. py:class:: AccelerationResult

   Ca(t), its raw second difference, and the located peak pair.


   .. py:attribute:: iteration
      :type:  numpy.ndarray


   .. py:attribute:: ca
      :type:  numpy.ndarray


   .. py:attribute:: accel
      :type:  numpy.ndarray


   .. py:attribute:: peak_accel_idx
      :type:  int | None


   .. py:attribute:: peak_decel_idx
      :type:  int | None


   .. py:attribute:: has_peak_pair
      :type:  bool


.. py:function:: compute_acceleration(df: pandas.DataFrame, *, x_col: str = 'normalised_iteration', smoothing: Smoothing = 'raw', savgol_window: int = _DEFAULT_SAVGOL_WINDOW, savgol_polyorder: int = _DEFAULT_SAVGOL_POLYORDER) -> AccelerationResult

   Locate the peak-acceleration / peak-deceleration pair in ``df["Ca"]``.

   ``accel`` is the second backward difference of ``Ca``, NaN-padded at
   indices 0 and 1 so it aligns with ``iteration``/``ca``. By default
   (``smoothing="raw"``) it is unsmoothed. With ``smoothing="savgol"``, a
   Savitzky-Golay filter (``savgol_window``, ``savgol_polyorder``) is applied
   to the raw second difference to remove spurious spikes before peak
   detection; this falls back to the raw curve when there are fewer points
   than ``savgol_window``. Peak acceleration is ``argmax(accel)``; peak
   deceleration is ``argmin(accel)`` searched strictly after the
   peak-acceleration index.


.. py:function:: find_slope_window(result: AccelerationResult, *, margin: int = _SLOPE_WINDOW_MARGIN) -> tuple[int, int] | None

   Return ``[peak_accel_idx+margin, peak_decel_idx-margin]``, or ``None``.

   ``None`` when no peak pair was found, or fewer than two indices remain in
   the window.


.. py:function:: save_diagnostic_plot(result: AccelerationResult, window: tuple[int, int] | None, out_path: str | pathlib.Path) -> pathlib.Path

   Save Ca(t) + twin-axis accel(t) with peak markers and the slope window.