Module rough_path 

Rough-path signatures for sequential trace feature extraction.

Rough-path signatures are universal noncommutative features extracted from sequential data (frame time series, event streams, syscall traces). They capture the “shape” of a path regardless of parameterization, making them ideal for anomaly detection and workload characterization.

Mathematical Model

Given a d-dimensional path X: [0,T] → ℝ^d, the signature is the collection of iterated integrals:

S(X)^{i₁,...,iₖ} = ∫₀<t₁<...<tₖ<T dX^{i₁}_{t₁} ⊗ ... ⊗ dX^{iₖ}_{tₖ}

The truncated signature at depth N keeps only terms with k ≤ N. For practical use, depth 3-4 captures sufficient structure.

Discretization

For discrete time series X = (x₀, x₁, …, x_n), the increments are Δx_i = x_{i+1} - x_i, and the iterated integrals become iterated sums:

S^{i}     = Σ Δx^i_k                      (depth 1)
S^{i,j}   = Σ_{k<l} Δx^i_k · Δx^j_l      (depth 2)
S^{i,j,m} = Σ_{k<l<r} Δx^i_k · Δx^j_l · Δx^m_r  (depth 3)

Efficient Computation (Chen’s Identity)

Rather than brute-force triple loops, we use Chen’s identity for incremental computation:

S(X_{[0,t+1]}) = S(X_{[0,t]}) ⊗ S(Δx_{t})

where ⊗ is the tensor (shuffle) product. This gives O(n · d^N) instead of O(n^N · d^N).

Usage

use ftui_runtime::rough_path::SignatureExtractor;

// 2D path: (frame_time_ms, alloc_count)
let mut ext = SignatureExtractor::new(2, 3); // dim=2, depth=3

ext.observe(&[16.0, 1200.0]);
ext.observe(&[17.0, 1250.0]);
ext.observe(&[15.0, 1180.0]);
ext.observe(&[32.0, 1500.0]); // spike!

let sig = ext.signature();
// sig contains depth-1, depth-2, and depth-3 terms
// Use for anomaly detection, distance computation, etc.

Applications

Use case	Dimensions	What it detects
Frame timing	1D (ms)	Stutter patterns, periodicity
Render+alloc	2D (ms, bytes)	Correlated regressions
Event stream	3D (dt, type, payload)	Workload fingerprints

Fallback

When signatures are too expensive (very high-dimensional data), use standard statistical features (mean, variance, skew, autocorrelation).

Structs

SignatureConfig

Configuration for signature extraction.

SignatureExtractor

Incremental truncated signature extractor.

Functions

signature_distance

Compute the L2 distance between two signature vectors.

signature_size

Computes the number of signature components for given dim and depth.