.. _spp_analysis:

====================================
Sequence of Physical Processes (SPP)
====================================

**Time-Domain LAOS Analysis Without Fourier Transform Limitations**

Overview
========

The **Sequence of Physical Processes (SPP)** framework, introduced by Rogers et al. (2011),
provides a fundamentally different approach to Large Amplitude Oscillatory Shear (LAOS) analysis.
Unlike Fourier/Chebyshev decomposition methods, SPP operates entirely in the time domain,
directly extracting transient elastic modulus and dynamic viscosity without the need for
harmonic decomposition.

.. admonition:: Key Insight
   :class: tip

   SPP reveals the **instantaneous material physics** at each point in the oscillatory cycle,
   making it particularly powerful for understanding yield-stress behavior, thixotropy, and
   other transient nonlinear phenomena. The approach views stress waveforms as representing
   a *sequence of physical processes* rather than a superposition of harmonics.

The foundational principle of SPP is that soft materials under LAOS undergo discrete physical
processes in sequence: (i) elastic extension, (ii) yielding, (iii) flow, and (iv) reformation.
This provides an intuitively simpler interpretation while removing the problem of infinite
series encountered in Fourier transformation.

.. tip:: Rogers-parity defaults (RheoJAX)

   Unless otherwise specified, RheoJAX SPP components use MATLAB/Rogers-aligned defaults:
   ``n_harmonics=39`` (odd), ``step_size=8``, ``num_mode=2`` (periodic/looped), and wrapped
   strain-rate inference when rate is absent.

Current Defaults
================

.. list-table:: Rogers-parity defaults (RheoJAX)
   :widths: 25 15 60
   :header-rows: 1

   * - Parameter
     - Default
     - Notes
   * - ``n_harmonics``
     - 39 (odd)
     - Matches SPPplus v2.1 parity
   * - ``step_size``
     - 8
     - 8-point 4th-order stencil
   * - ``num_mode``
     - 2
     - Periodic/looped differentiation
   * - ``wrap_strain_rate``
     - True
     - Infers |gamma_dot| with periodic wrap when rate missing
   * - ``yield_tolerance``
     - 0.02
     - Static/dynamic yield detection tolerance

When to Use SPP
---------------

**SPP is ideal for:**

- **Yield-stress LAOS**: Directly identifies yielding transitions within each cycle
- **Weak thixotropy**: Tracks structural evolution without assuming steady-state
- **Phase transitions**: Detects solid-liquid transitions during oscillation
- **Physical interpretation**: Maps response to physical processes (cage modulus, flow)
- **Single-amplitude experiments**: Extract static/dynamic yield stresses, cage modulus, and flow behavior

**SPP complements (rather than replaces) Fourier methods for:**

- Broadband frequency characterization
- Standard nonlinear parameters (e\ :sub:`3`/e\ :sub:`1`, v\ :sub:`3`/v\ :sub:`1`)
- Comparison with literature using harmonic ratios

Theoretical Foundations
=======================

The SPP Framework
-----------------

Traditional LAOS analysis decomposes stress into Fourier harmonics:

.. math::

   \sigma(t) = \sum_{n=\text{odd}} \left[ G'_n \sin(n\omega t) + G''_n \cos(n\omega t) \right]

This whole-waveform approach creates a potentially infinite number of hard-to-interpret
harmonics, often generated by combinations of many distinct physical processes. The dynamic
moduli :math:`G'` and :math:`G''` are not uniquely defined when the strain amplitude is sufficiently large
to cause a nonlinear, non-sinusoidal stress response.

SPP instead views the stress response as representing a **sequence of physical processes**,
with each process having distinct characteristics that can be independently analyzed:

1. **Elastic extension** of microstructural cages
2. **Static yielding** when cages break
3. **Viscous flow** following the flow curve
4. **Cage reformation** when instantaneous shear rate approaches zero

This approach provides clear quantifiable results while simultaneously removing the problem
of attempting to understand a potential infinity of experimental values.

The Four-Step Yielding Sequence
-------------------------------

For yield-stress materials (colloidal glasses, gels, pastes), SPP reveals a characteristic
four-step sequence within each oscillatory cycle:

.. admonition:: Four-Step Yielding Sequence
   :class: note

   The four-step yielding sequence within each LAOS cycle:

   1. **Elastic extension** (1→2): Stress increases linearly with strain
   2. **Static yield** (point 2): Maximum stress before cage rupture
   3. **Viscous flow** (2→3→4): Power-law flow following the steady-state flow curve
   4. **Cage reformation** (point 4): Stress at zero rate when cages reform

   *Adapted from Rogers et al. (2011).*

**Step 1: Elastic Extension (1→2)**

Beginning at zero stress, an increase in strain causes the microstructural cage to extend
in a linear elastic fashion. The cage represents the effective constraint formed by nearest
neighbors (colloidal particles, polymer entanglements, etc.). During this phase:

- Stress increases linearly with strain
- The slope represents the **apparent cage modulus** G\ :sub:`cage`
- Material behaves as an elastic solid

**Step 2: Static Yielding (Point 2)**

This proceeds until the cages are strained beyond their yield strains, whereupon the
system begins to flow. Static yielding is associated with:

- The "bump" or overshoot immediately following the linear stress buildup
- The **static yield stress** |sigma_sy|: maximum stress before cage rupture
- The **static yield strain** |gamma_y|: strain at which cages break

**Step 3: Viscous Flow (2→3→4)**

After yielding, the material follows the steady-state flow curve according to the
instantaneous shear rate. The stress response:

- Exhibits power-law behavior: |sigma| = K |gamma_dot|\ :sup:`n`
- Follows the same flow curve as steady-shear experiments
- Continues until the instantaneous shear rate approaches zero

**Step 4: Cage Reformation (Point 4)**

When the instantaneous shear rate momentarily becomes zero at the strain extrema:

- Cages instantaneously reform
- The **dynamic yield stress** |sigma_dy|: stress at zero rate (cage reformation point)
- The straining-yielding-flowing-reformation process begins again in the opposite direction

Key Physical Parameters
-----------------------

Cage Modulus (G\ :sub:`cage`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The **cage modulus** represents the instantaneous elastic stiffness when strain rate is
zero (maximum strain). It is defined as:

.. math::

   G_{\text{cage}} \equiv \left. \frac{d\sigma}{d\gamma} \right|_{\sigma=0}

This captures the elastic "cage" formed by microstructure at maximum deformation:

- **Constant across amplitudes**: Unlike :math:`G'`, G\ :sub:`cage` remains constant even at large
  amplitudes where :math:`G'` decreases by more than a decade
- **State-dependent**: Solid-state cages are stronger than soft-state cages
- **Recovers after breaking**: Once broken, cages reform with the soft-state modulus

In the small phase angle, small-amplitude limit, the cage modulus reduces to the storage modulus:

.. math::

   \lim_{\delta, \gamma_0 \to 0} G_{\text{cage}} = \lim_{\delta, \gamma_0 \to 0} G'

Static Yield Stress (|sigma_sy|)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The **static yield stress** is the stress that must be overcome to make a material flow.
It is extracted at the strain reversal point (|gamma| = |gamma_0|, |gamma_dot| = 0):

.. math::

   \sigma_{y,\text{static}} = \sigma(t)\big|_{\gamma=\pm\gamma_0}

This represents the maximum stress the material sustains before yielding and is directly
comparable to yield stress from steady shear or stress growth tests.

Dynamic Yield Stress (|sigma_dy|)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The **dynamic yield stress** is the stress below which the material ceases flowing.
It is obtained at maximum strain rate (|gamma| = 0, |gamma_dot| = |gamma_dot_0|):

.. math::

   \sigma_{y,\text{dynamic}} = \sigma(t)\big|_{\dot{\gamma}=\pm\dot{\gamma}_0}

Key relationships between yield stresses:

- Static and dynamic yield stresses have the **same rate-dependence** (power-law with
  identical index ~0.2 for typical soft glassy materials)
- In the large-amplitude limit: |sigma_sy| |approx| 2.75 |times| |sigma_dy|
- Both depend on the strain-rate amplitude: |sigma_y| |propto| |gamma_0|\ :sup:`0.2`

Phase Without Fourier
~~~~~~~~~~~~~~~~~~~~~

SPP defines a **time-domain phase** |delta_t| without Fourier decomposition:

.. math::

   \delta_t(t) = \arctan\left( \frac{G''_t(t)}{G'_t(t)} \right)

This phase angle evolves continuously through the cycle:

- |delta_t| |rarr| 0|deg|: Purely elastic response (solid-like)
- |delta_t| |rarr| 90|deg|: Purely viscous response (liquid-like)
- Transition regions reveal yielding and recovery

Power-Law Flow Analysis
~~~~~~~~~~~~~~~~~~~~~~~

For yielded materials exhibiting power-law flow, SPP extracts:

.. math::

   \sigma = K |\dot{\gamma}|^n \text{sign}(\dot{\gamma})

where K is the consistency and n is the flow index. This is evaluated in the flowing
portions of each cycle where |gamma| |approx| 0 (maximum strain rate).

**Critical insight**: The post-yielding oscillatory stress response follows the **same flow
curve** as steady-shear experiments, providing a direct link between LAOS and steady-state
rheology.

Mathematical Formulation
========================

Frenet-Serret Frame Approach
----------------------------

The later SPP formulation (Rogers 2012) uses differential geometry on the 3D response
trajectory |vec_r| = [|gamma|, |gamma_dot|/|omega|, |sigma|] to extract instantaneous moduli:

.. math::

   G'_t = -\frac{(\vec{r}' \times \vec{r}'')_\gamma}{(\vec{r}' \times \vec{r}'')_\sigma}, \qquad
   G''_t = -\frac{(\vec{r}' \times \vec{r}'')_{\dot{\gamma}/\omega}}{(\vec{r}' \times \vec{r}'')_\sigma}

where |vec_r|' and |vec_r|'' are the first and second derivatives of the trajectory with respect
to the arc-length parameter.

The stress decomposition becomes:

.. math::

   \sigma(t) = G'_t(t) \gamma(t) + \frac{G''_t(t)}{\omega} \dot{\gamma}(t) + G^d_t(t)

where G\ :sup:`d`\ :sub:`t` is the **dissipative modulus** representing irreversible energy loss.

Binormal Vector Decomposition
-----------------------------

The instantaneous moduli are extracted from the binormal vector components of the
Frenet-Serret frame:

.. math::

   \vec{B} = \vec{T} \times \vec{N}

where |vec_T| is the unit tangent and |vec_N| is the principal normal. The moduli are:

.. math::

   G'_t = -\frac{B_\gamma}{B_\sigma}, \qquad G''_t = -\frac{B_{\dot{\gamma}/\omega}}{B_\sigma}

This formulation provides a robust numerical method for extracting instantaneous moduli
from experimental LAOS data.

Complete Stress Reconstruction (Rogers 2017)
--------------------------------------------

Rogers (2017) established that **three**, not two, time-dependent nonlinear viscoelastic
functions are required to fully describe any LAOS response:

.. math::

   \sigma(t) = G'_t(t)[\gamma(t) - \gamma_{eq}(t)] + \frac{G''_t(t)}{\omega}\dot{\gamma}(t) + \sigma_y(t)

where:

- :math:`G'_t(t)` — instantaneous storage modulus
- :math:`G''_t(t)` — instantaneous loss modulus
- :math:`\gamma_{eq}(t)` — equilibrium strain position (can shift during deformation)
- :math:`\sigma_y(t)` — yield stress term (zero-rate stress intercept)

The third term, :math:`\sigma_y(t) - G'_t(t)\gamma_{eq}(t)`, represents the **displacement**
of the osculating plane and accounts for:

- **Yield stresses**: Stress offsets not captured by moduli alone
- **Shifting equilibria**: The zero-elastic-extension point can move during deformation
- **Non-Newtonian flow**: Deviation from simple viscoelastic behavior

Lab Frame vs. Material Frame
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A key insight from Rogers (2017) is distinguishing between:

- **Lab frame strain**: :math:`\gamma(t)` — measured from the rheometer
- **Material frame strain**: :math:`\gamma_{mat}(t) = \gamma(t) - \gamma_{eq}(t)` — felt by the material

For **linear viscoelastic materials**, :math:`\gamma_{eq} = 0` everywhere.

For **generalized Newtonian fluids**, :math:`\gamma_{eq}(t) = \gamma(t)`, ensuring zero
elastic stress at all times (purely viscous).

For **yield-stress materials**, :math:`\gamma_{eq}` shifts during yielding:

- Before yield: :math:`\gamma_{eq} = 0`
- After yield: :math:`\gamma_{eq} \to \pm(\gamma_0 - \gamma_y)`
- The material experiences plastic deformation in its own reference frame

Rates of Change (Stiffening/Softening)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Rogers (2017) provides explicit equations for the rates at which moduli change:

.. math::

   \dot{G}'_t = \tau ||\dot{\mathbf{A}}|| \left( \frac{N_\gamma}{B_\sigma} - \frac{B_\gamma N_\sigma}{B_\sigma^2} \right)

.. math::

   \dot{G}''_t = \tau ||\dot{\mathbf{A}}|| \left( \frac{N_{\dot{\gamma}/\omega}}{B_\sigma} - \frac{B_{\dot{\gamma}/\omega} N_\sigma}{B_\sigma^2} \right)

where :math:`\tau` is the **torsion** of the response trajectory and :math:`N_\gamma`,
:math:`N_{\dot{\gamma}/\omega}`, :math:`N_\sigma` are components of the principal normal.

**Physical interpretation**:

- :math:`\dot{G}'_t > 0`: **Stiffening** (increasing elasticity)
- :math:`\dot{G}'_t < 0`: **Softening** (decreasing elasticity)
- :math:`\dot{G}''_t > 0`: **Thickening** (increasing viscosity)
- :math:`\dot{G}''_t < 0`: **Thinning** (decreasing viscosity)

**Critical insight**: In the linear regime where trajectories are planar, torsion
:math:`\tau = 0` everywhere, making both rate derivatives zero. Nonzero torsion indicates
nonlinear behavior.

Time-Domain Cole-Cole Plots
~~~~~~~~~~~~~~~~~~~~~~~~~~~

SPP enables dynamic Cole-Cole analysis by plotting :math:`G''_t(t)` vs :math:`G'_t(t)`
parametrically through the oscillation cycle:

- **Linear regime**: Collapses to a single point :math:`(G', G'')`
- **Nonlinear regime**: Traces a trajectory showing material evolution

**Trajectory interpretation** (from Rogers 2017):

+----------------------------------+----------------------------+
| Position/Motion                  | Interpretation             |
+==================================+============================+
| :math:`G''_t = 0`                | Purely elastic             |
+----------------------------------+----------------------------+
| :math:`G'_t = 0`                 | Purely viscous             |
+----------------------------------+----------------------------+
| :math:`G''_t > G'_t`             | Predominantly viscous      |
+----------------------------------+----------------------------+
| :math:`G'_t > G''_t`             | Predominantly elastic      |
+----------------------------------+----------------------------+
| Crossing :math:`G'_t = G''_t`    | Fluidization or            |
| line                             | reformation transition     |
+----------------------------------+----------------------------+

Application Scope
=================

Yield-Stress LAOS
-----------------

SPP excels at characterizing yield-stress materials under LAOS:

1. **Pre-yield**: High G\ :sub:`cage`, low |delta_t| (elastic solid)
2. **Yielding**: Rapid drop in G\ :sub:`cage`, increasing |delta_t|
3. **Post-yield**: Power-law flow, |delta_t| |rarr| 90|deg|
4. **Recovery**: G\ :sub:`cage` rebuilds during strain reversal

This provides direct insight into yielding dynamics inaccessible to Fourier methods.

Soft Glassy Materials
---------------------

SPP is particularly well-suited for soft glassy materials where the cage model applies:

- **Colloidal glasses**: Star polymers, hard/soft spheres
- **Microgel pastes**: Concentrated suspensions above jamming
- **Emulsions and foams**: Droplet/bubble cages
- **Polymer gels**: Entanglement networks

For these systems, the cage modulus directly measures the strength of microstructural
caging, and the yield stresses quantify the breaking and reformation of cages.

Weak Thixotropy
---------------

For weakly thixotropic materials (structure recovers partially between cycles):

- G\ :sub:`cage` shows cycle-to-cycle evolution
- Static yield stress may drift over many cycles
- SPP tracks this evolution without assuming steady-state

.. note::

   **Scope limitation**: SPP is best for *weak* thixotropy where structure partially
   equilibrates within each cycle. For *strong* thixotropy (structure changes dramatically
   over cycles), time-resolved rheology or stepped protocols may be more appropriate.

**Rule of thumb**: SPP works well when the structural relaxation time |tau_s| is longer
than the oscillation period (|tau_s| > 2|pi|/|omega|).

Phase Transitions
-----------------

SPP can detect phase transitions within the oscillatory cycle:

- **Solid |rarr| Liquid**: |delta_t| increases sharply at yield
- **Liquid |rarr| Solid**: |delta_t| decreases during recovery/gelation
- **Multiple transitions**: Complex materials may show re-entrant behavior

Practical Implementation
========================

Basic SPP Analysis
------------------

.. code-block:: python

   from rheojax.transforms import SPPDecomposer
   from rheojax.io.readers import auto_read

   # Load LAOS data
   data = auto_read("laos_data.csv")

   # Apply SPP decomposition
   decomposer = SPPDecomposer(
       omega=1.0,              # Angular frequency (rad/s)
       gamma_0=1.0,            # Strain amplitude
       n_harmonics=39,         # Number of harmonics (Rogers default)
       use_numerical_method=False,
       step_size=8,            # Finite-difference step
   )

   result = decomposer.transform(data)
   spp_results = decomposer.get_results()

   # Access key SPP quantities
   print(f"Cage modulus: {spp_results['G_cage']:.1f} Pa")
   print(f"Static yield stress: {spp_results['sigma_sy']:.1f} Pa")
   print(f"Dynamic yield stress: {spp_results['sigma_dy']:.1f} Pa")
   print(f"I3/I1 ratio: {spp_results['I3_I1_ratio']:.4f}")

Cycle Selection
---------------

SPP analysis requires selecting appropriate cycles from the LAOS waveform:

.. code-block:: python

   # Skip first 2 cycles (startup transients), analyze cycles 2-5
   spp = SPPDecomposer(
       omega=1.0,
       gamma_0=1.0,
       start_cycle=2,      # Skip cycles 0, 1 (0-indexed)
       end_cycle=5,        # Analyze up to cycle 5 (exclusive)
   )

   result = spp.transform(rheo_data)

   # Check which cycles were actually analyzed
   print(spp.results_['cycles_analyzed'])  # (2, 5)

.. warning::

   **Cycle selection matters!** Early cycles may contain startup transients, while late
   cycles may show fatigue or structural breakdown. Always visualize multiple cycles
   before selecting the analysis window.

Numerical Differentiation Method
--------------------------------

For raw experimental data compatibility (matching MATLAB SPPplus workflows), use the
numerical differentiation method:

.. code-block:: python

   # MATLAB-compatible numerical SPP analysis
   spp = SPPDecomposer(
       omega=1.0,
       gamma_0=1.0,
       use_numerical_method=True,  # Enable numerical derivatives
       step_size=8,                # 8-point finite-difference stencil
   )

   result = spp.transform(rheo_data)

   # Access instantaneous moduli from numerical method
   numerical = spp.results_['numerical']
   Gp_t = numerical['Gp_t']       # G'(t) - instantaneous storage modulus
   Gpp_t = numerical['Gpp_t']     # G''(t) - instantaneous loss modulus
   delta_t = numerical['delta_t'] # delta(t) - instantaneous phase angle

   # Mean values for comparison with linear measurements
   print(f"Mean G'(t) = {spp.results_['Gp_t_mean']:.1f} Pa")
   print(f"Mean G''(t) = {spp.results_['Gpp_t_mean']:.1f} Pa")

The numerical method implements the cross-product formula from Rogers (2012):

.. math::

   G'_t = -\frac{(\vec{r}' \times \vec{r}'')_0}{(\vec{r}' \times \vec{r}'')_2}, \qquad
   G''_t = -\frac{(\vec{r}' \times \vec{r}'')_1}{(\vec{r}' \times \vec{r}'')_2}

where :math:`\vec{r} = [\gamma, \dot{\gamma}/\omega, \sigma]` is the response trajectory.

Amplitude Sweep Analysis
------------------------

For comprehensive material characterization across strain amplitudes:

.. code-block:: python

   from rheojax.pipeline.spp import SPPAmplitudeSweepPipeline
   import numpy as np

   # Define amplitude sweep
   gamma_0_values = np.logspace(-2, 1, 20)  # 0.01 to 10 strain

   # Run amplitude sweep with SPP analysis
   pipeline = SPPAmplitudeSweepPipeline(omega=1.0)
   results = pipeline.run_sweep(
       data_files=amplitude_sweep_files,
       gamma_0_values=gamma_0_values,
   )

   # Extract amplitude-dependent quantities
   G_cage_vs_gamma = results['G_cage']
   sigma_sy_vs_gamma = results['sigma_sy']
   sigma_dy_vs_gamma = results['sigma_dy']

Bayesian SPP Analysis
---------------------

For uncertainty quantification on SPP-extracted yield stresses:

.. code-block:: python

   from rheojax.models import SPPYieldStress
   from rheojax.core import RheoData

   # Prepare SPP results for Bayesian fitting
   rheo_data = RheoData(
       x=gamma_0_values,
       y=sigma_sy_values,
       test_mode='spp_yield',
   )

   # Fit SPP yield stress model with Bayesian inference
   model = SPPYieldStress()
   model.fit(rheo_data)  # NLSQ point estimate

   # Bayesian inference with uncertainty
   result = model.fit_bayesian(rheo_data, num_warmup=1000, num_samples=2000)

   # Get credible intervals
   intervals = model.get_credible_intervals(
       result.posterior_samples,
       credibility=0.95
   )
   print(f"K = {intervals['K']['mean']:.2f} [{intervals['K']['lower']:.2f}, {intervals['K']['upper']:.2f}]")
   print(f"n = {intervals['n']['mean']:.3f} [{intervals['n']['lower']:.3f}, {intervals['n']['upper']:.3f}]")

Visualizing SPP Results
-----------------------

.. code-block:: python

   import matplotlib.pyplot as plt
   import numpy as np

   fig, axes = plt.subplots(2, 2, figsize=(12, 10))

   # 1. Lissajous curve with SPP annotations
   ax = axes[0, 0]
   ax.plot(strain, stress, 'b-', linewidth=1.5)
   ax.axhline(sigma_sy, color='r', linestyle='--', label=r'$\sigma_{y,static}$')
   ax.axhline(sigma_dy, color='g', linestyle=':', label=r'$\sigma_{y,dynamic}$')
   ax.axvline(gamma_y, color='orange', linestyle='-.', alpha=0.5, label=r'$\gamma_y$')
   ax.set_xlabel(r'Strain $\gamma$')
   ax.set_ylabel(r'Stress $\sigma$ (Pa)')
   ax.legend()
   ax.set_title('Lissajous Curve with Yield Points')

   # 2. Instantaneous moduli through cycle
   ax = axes[0, 1]
   ax.plot(phase_in_cycle, Gp_t, 'b-', label=r"$G'_t$")
   ax.plot(phase_in_cycle, Gpp_t, 'r--', label=r"$G''_t$")
   ax.set_xlabel('Phase in Cycle (degrees)')
   ax.set_ylabel('Instantaneous Modulus (Pa)')
   ax.legend()
   ax.set_title('Time-Resolved Moduli')

   # 3. Cole-Cole plot (transient moduli)
   ax = axes[1, 0]
   ax.plot(Gp_t, Gpp_t, 'b-', linewidth=1)
   ax.plot(Gp_t[0], Gpp_t[0], 'go', markersize=10, label='Start')
   ax.set_xlabel(r"$G'_t$ (Pa)")
   ax.set_ylabel(r"$G''_t$ (Pa)")
   ax.set_aspect('equal')
   ax.set_title('Cole-Cole Spiral')
   ax.legend()

   # 4. Amplitude dependence of yield stresses
   ax = axes[1, 1]
   ax.loglog(gamma_0_values, sigma_sy_values, 'ro-', label='Static yield')
   ax.loglog(gamma_0_values, sigma_dy_values, 'bs-', label='Dynamic yield')
   ax.set_xlabel(r'Strain amplitude $\gamma_0$')
   ax.set_ylabel(r'Yield stress (Pa)')
   ax.legend()
   ax.set_title('Yield Stress vs Amplitude')

   plt.tight_layout()
   plt.savefig('spp_analysis.png', dpi=150)

SPP vs Fourier/Chebyshev Comparison
===================================

Understanding when to use SPP versus traditional Fourier-based methods is crucial for
effective LAOS analysis.

.. list-table:: SPP vs Fourier/Chebyshev Comparison
   :header-rows: 1
   :widths: 25 37 38

   * - Aspect
     - SPP (Time-Domain)
     - Fourier/Chebyshev (Frequency-Domain)
   * - **Domain**
     - Time (instantaneous properties)
     - Frequency (harmonic coefficients)
   * - **Basis functions**
     - Physical processes (discrete)
     - Orthonormal harmonics (infinite series)
   * - **Yield stress**
     - Direct extraction (|sigma_sy|, |sigma_dy|)
     - Indirect (from G\ :sub:`M`, G\ :sub:`L` at large strain)
   * - **Physical interpretation**
     - Intuitive (cage, flow, yielding)
     - Mathematical (harmonic ratios)
   * - **Transient phenomena**
     - Captures within-cycle evolution
     - Averages over cycle
   * - **Higher harmonics**
     - Explained by power-law flow
     - Individual harmonics assigned physical meaning
   * - **Noise sensitivity**
     - Higher near zero stress
     - Lower (averaging effect)
   * - **Standard metrics**
     - G\ :sub:`cage`, |sigma_sy|, |sigma_dy|, S/T factors
     - e\ :sub:`3`/e\ :sub:`1`, v\ :sub:`3`/v\ :sub:`1`, I\ :sub:`3`/I\ :sub:`1`
   * - **Truncation artifacts**
     - None (raw data)
     - Possible (finite harmonics)
   * - **Best for**
     - Yield-stress fluids, physical mechanisms
     - Material fingerprinting, literature comparison
   * - **Computational cost**
     - O(N) per cycle
     - O(N log N) via FFT

Qualitative Consistency
-----------------------

SPP is **qualitatively consistent** with Fourier-Chebyshev analysis. The higher harmonics
observed in Fourier spectra can be explained by the power-law flow response:

- A power-law index of unity produces a simple sine wave (single harmonic)
- A power-law index of zero produces a square wave (infinitely many harmonics with magnitudes 1/n)
- Intermediate indices produce spectra with harmonics decreasing faster than 1/n

The relative magnitude of higher harmonics increases with strain amplitude because a larger
proportion of the waveform comes from the power-law fluid response.

Recommended Workflow
--------------------

For comprehensive LAOS characterization:

1. **Start with Fourier/Chebyshev**: Get standard nonlinear parameters (I\ :sub:`3/1`,
   e\ :sub:`3`/e\ :sub:`1`, v\ :sub:`3`/v\ :sub:`1`) for literature comparison

2. **Apply SPP for physical insight**: Extract yield stresses, cage modulus, and
   phase evolution

3. **Cross-validate**: Ensure both methods tell a consistent physical story

.. code-block:: python

   from rheojax.transforms import OWChirp, SPPDecomposer

   # Fourier-based analysis
   owchirp = OWChirp(extract_harmonics=True)
   harmonics = owchirp.get_harmonics(laos_data)
   I31 = harmonics['third'][1] / harmonics['fundamental'][1]

   # SPP analysis
   spp = SPPDecomposer(omega=1.0, gamma_0=1.0, n_harmonics=39)
   result = spp.transform(rheo_data)
   spp_metrics = spp.get_results()

   # Compare interpretations
   print(f"Fourier I_3/1 = {I31:.3f}")
   print(f"SPP I3/I1 ratio = {spp_metrics['I3_I1_ratio']:.3f}")
   print(f"SPP static yield = {spp_metrics['sigma_sy']:.0f} Pa")
   print(f"SPP cage modulus = {spp_metrics['G_cage']:.0f} Pa")

Limitations and Caveats
=======================

Noise Sensitivity Near Zero Stress
----------------------------------

SPP quantities involve ratios that become sensitive near zero stress:

.. math::

   G'_t = \frac{\sigma}{\gamma} \quad \text{(problematic when } \sigma \approx 0\text{)}

.. warning::

   **Near-zero stress**: When stress approaches zero (during flow reversal in some
   materials), SPP ratios can become noisy or undefined. Apply smoothing or exclude
   these regions from analysis.

**Mitigation strategies:**

.. code-block:: python

   import numpy as np
   from scipy.signal import savgol_filter

   # Option 1: Apply stress threshold (filter data before analysis)
   valid_mask = np.abs(stress) > 1.0  # Pa threshold
   filtered_stress = stress[valid_mask]

   # Option 2: Use higher tolerance for yield point detection
   spp = SPPDecomposer(omega=1.0, gamma_0=1.0, yield_tolerance=0.05)

   # Option 3: Apply smoothing to raw data before SPP
   stress_smooth = savgol_filter(stress, window_length=11, polyorder=3)

Cycle Selection Effects
-----------------------

The choice of which cycles to analyze significantly affects SPP results:

- **Too early**: Transient effects, not representative of steady oscillation
- **Too late**: Fatigue, structural breakdown, edge fracture
- **Single cycle**: May not be representative; average multiple cycles

**Best practice**: Analyze a range of cycles and verify consistency.

Harmonic Truncation Not Applicable
----------------------------------

Unlike Fourier methods, SPP does not truncate harmonics---it uses the raw stress-strain data.
This means:

- **Advantage**: No artifacts from harmonic truncation
- **Caution**: Noise propagates directly into SPP quantities

For noisy data, consider smoothing the raw waveforms before SPP analysis.

Thixotropy Caveats
------------------

SPP assumes that properties can be meaningfully defined at each instant within a cycle.
For strongly thixotropic materials:

- Structure changes faster than the oscillation period
- Instantaneous properties may not be well-defined
- Consider time-resolved or protocol-based methods instead

**Rule of thumb**: SPP works well when the structural relaxation time |tau_s| is longer
than the oscillation period (|tau_s| > 2|pi|/|omega|).

Rate-Dependent Yield Stresses
-----------------------------

The static and dynamic yield stresses measured by SPP are **rate-amplitude dependent**:

.. math::

   \sigma_{y} \propto \gamma_0^{0.2} \propto \dot{\gamma}_0^{0.2}

This is consistent with the cage model where:

- **Dynamic yield**: Finite relaxation time means viscous stress cannot fully relax before
  cage reformation
- **Static yield**: Hopping from potential minima depends on effective shear rate

The rate-dependence of both yield stresses have the same power-law index, suggesting the
finite dissipation time and hopping mechanics are intimately related.

macOS GPU Acceleration
----------------------

.. note::

   **Platform limitation**: GPU acceleration for SPP transforms is currently only supported
   on Linux with CUDA. macOS users will use CPU computation, which remains performant for
   typical LAOS datasets but may be slower for very large datasets.

Tutorial Notebooks
==================

RheoJAX provides comprehensive tutorial notebooks demonstrating SPP analysis workflows:

Basic SPP Tutorial
------------------

**Notebook**: ``examples/advanced/10-spp-laos-tutorial.ipynb``

This tutorial covers:

- Loading and preprocessing LAOS data
- Configuring SPPDecomposer with Rogers-parity defaults
- Extracting instantaneous moduli :math:`G'(t)`, :math:`G''(t)`
- Visualizing Lissajous curves with yield point annotations
- Amplitude sweep analysis for material classification
- Comparison with Fourier/Chebyshev results

Bayesian SPP Workflow
---------------------

**Notebook**: ``examples/bayesian/08-spp-laos.ipynb``

This tutorial demonstrates:

- SPP analysis with uncertainty quantification
- NLSQ |rarr| NUTS warm-start for yield stress fitting
- Convergence diagnostics (R-hat, ESS)
- Posterior predictive checks
- Model comparison for yield stress models

SPP RheoJAX Workflow
--------------------

**Notebook**: ``examples/bayesian/09-spp-rheojax-workflow.ipynb``

Advanced workflow covering:

- SPPAmplitudeSweepPipeline for batch processing
- Integration with ArviZ diagnostics
- Publication-quality figure generation
- Experimental data analysis with real LAOS measurements

References
==========

**Foundational SPP Papers:**

- Rogers, S. A., Erwin, B. M., Vlassopoulos, D., & Cloitre, M. (2011). "A sequence of
  physical processes determined and quantified in LAOS: Application to a yield stress
  fluid." *J. Rheol.* 55, 435-458. https://doi.org/10.1122/1.3544591

- Rogers, S. A. (2012). "A sequence of physical processes determined and quantified in
  LAOS: An instantaneous local 2D/3D approach." *J. Rheol.* 56, 1129-1151.
  https://doi.org/10.1122/1.4726083

- Rogers, S. A., & Lettinga, M. P. (2012). "A sequence of physical processes determined
  and quantified in large-amplitude oscillatory shear (LAOS): Application to theoretical
  nonlinear models." *J. Rheol.* 56, 1-25. https://doi.org/10.1122/1.3662962

- Rogers, S. A. (2017). "In search of physical meaning: defining transient parameters
  for nonlinear viscoelasticity." *Rheol. Acta* 56, 501-525.
  https://doi.org/10.1007/s00397-017-1008-1

**Applications and Extensions:**

- Lee, C.-W., & Rogers, S. A. (2017). "A sequence of physical processes quantified in LAOS
  by continuous local measures." *Korea-Australia Rheol. J.* 29, 269-279.

- Donley, G. J., et al. (2019). "Time-resolved dynamics of the yielding transition in
  soft materials." *J. Non-Newtonian Fluid Mech.* 264, 117-134.

**Comparison with Fourier Methods:**

- Hyun, K., et al. (2011). "A review of nonlinear oscillatory shear tests: Analysis and
  application of large amplitude oscillatory shear (LAOS)." *Prog. Polym. Sci.* 36,
  1697-1753. https://doi.org/10.1016/j.progpolymsci.2011.02.002

- Ewoldt, R., Hosoi, A., & McKinley, G. (2008). "New measures for characterizing nonlinear
  viscoelasticity in large amplitude oscillatory shear." *J. Rheol.* 52, 1427-1458.

See Also
========

- :doc:`/transforms/owchirp` --- OWChirp for Fourier-based LAOS analysis
- :doc:`/models/flow/herschel_bulkley` --- Yield-stress model for flow curve fitting
- :doc:`/user_guide/03_advanced_topics/bayesian_inference` --- Uncertainty quantification for SPP parameters
- :doc:`/examples/index` --- Tutorial notebooks including SPP Bayesian workflow


.. |gamma| unicode:: U+03B3
.. |gamma_0| replace:: |gamma|\ :sub:`0`
.. |gamma_dot| replace:: |gamma|\ :sup:`.`
.. |gamma_dot_0| replace:: |gamma_dot|\ :sub:`0`
.. |gamma_y| replace:: |gamma|\ :sub:`y`
.. |sigma| unicode:: U+03C3
.. |sigma_sy| replace:: |sigma|\ :sub:`y,static`
.. |sigma_dy| replace:: |sigma|\ :sub:`y,dynamic`
.. |sigma_y| replace:: |sigma|\ :sub:`y`
.. |omega| unicode:: U+03C9
.. |delta| unicode:: U+03B4
.. |delta_t| replace:: |delta|\ :sub:`t`
.. |tau_s| replace:: |tau|\ :sub:`s`
.. |tau| unicode:: U+03C4
.. |pi| unicode:: U+03C0
.. |deg| unicode:: U+00B0
.. |rarr| unicode:: U+2192
.. |approx| unicode:: U+2248
.. |times| unicode:: U+00D7
.. |propto| unicode:: U+221D
.. |vec_r| replace:: **r**
.. |vec_T| replace:: **T**
.. |vec_N| replace:: **N**