monitor_embedding.md

Delay Embedding — Phase-Space Reconstruction

Why this module is exposed

Delay embedding is how SPO can recover state-space structure when only scalar observations are available. It lets monitoring and anomaly workflows operate from raw traces without requiring a separate external embedding stack.

The module is intentionally strict at boundaries so a downstream controller uses phase-space features with deterministic semantics.

The monitor.embedding module reconstructs phase-space trajectories from scalar oscillator traces. It provides delay-coordinate embedding, Fraser-Swinney average mutual information, nearest-neighbor distances, and Python-side wrappers for optimal delay and embedding dimension.

Operational use

Use this module when a monitor needs geometry and short-term predictability from non-vector observations (for example, single-channel physiology traces mapped into state-space structure).

A practical sequence is:

1. Build a validated embedded matrix (delay_embed or auto_embed);
2. Select delay/dimension from information-theoretic and neighborhood diagnostics;
3. Feed the reconstructed state to downstream monitor logic;
4. Validate resulting geometrical signals against replay baselines before using them in policy experiments.

Keep this boundary explicit: embedding is a feature-construction layer, not a replacement for raw trace quality checks.

API

from scpn_phase_orchestrator.monitor.embedding import (
    delay_embed,
    mutual_information,
    nearest_neighbor_distances,
    optimal_delay,
    optimal_dimension,
    auto_embed,
)

delay_embed(signal, delay, dimension) returns the standard delay-coordinate matrix:

v(t) = [x(t), x(t + tau), x(t + 2 tau), ...]

mutual_information(signal, lag, n_bins) estimates average mutual information for delay selection. nearest_neighbor_distances(embedded) supports false-nearest-neighbor dimension selection.

Direct backend boundary

Go, Julia, and Mojo direct bridge calls share the same typed pre-dispatch contract before optional runtime loading. Signal payloads must be finite real one-dimensional samples. Real numeric object arrays are supported; Boolean, text, complex and temporal aliases, including object-stored durations, are rejected before float conversion. Delay, dimension, lag, bin-count, row-count, and embedding-dimension controls must be integer values in the public API domain. Embedded nearest-neighbor payloads must be finite real flat float64 arrays whose length matches T*m, with numeric-string aliases rejected at the same pre-dispatch boundary.

Boolean aliases, object-dtype complex aliases, complex samples, non-finite samples, numeric-string aliases, non-vector signal payloads, malformed flattened embedding lengths, invalid delay/dimension requests, invalid lags, and invalid bin counts are rejected before shared-library, Julia, or subprocess execution.

Direct backend return payloads are validated before they are handed back to the public monitor boundary. The public dispatcher repeats the same physics-facing checks after backend fallback resolution so a shape-correct optional backend cannot silently return the wrong phase-space reconstruction. Delay-embedding outputs must have the exact (T_effective, dimension) shape and match the mathematical indexing x[t + k*tau]; numeric-string aliases and object-dtype complex aliases are rejected before float coercion; mutual-information outputs must be finite non-negative real scalars; nearest-neighbor outputs must contain finite non-negative distances and integral in-range neighbor indices, with self-neighbors rejected for non-trivial embeddings. Malformed Mojo text output is normalised to deterministic ValueError failures rather than leaking parser exceptions.

The installed Rust entry points retain their contiguous one-dimensional float64 array ABI. They check original non-Boolean integer metadata, finite samples and finite nonnegative FNN tolerances. Embedding-window, output-size and histogram-size products are checked before allocation. A valid delay exceeding the series length returns dimension 1 from the native FNN selector without signed truncation.

The source-type benchmark records the canonical parity gate on actual Python, Rust, Go, Julia and Mojo backends at 64 and 160 samples, with source and extension hashes. Rust has no standalone mutual-information or nearest-neighbor FFI; its supported contracts are recorded separately. Three calls per backend on a shared host are local regression evidence, not a controlled speedup comparison.

Invariants

delay_embed is exact indexing and should match across backends without tolerance. Mutual information is non-negative. Nearest-neighbor distances are finite non-negative values with integer neighbor indices in range and no self-neighbor for non-trivial inputs. Optional backend outputs that violate those invariants are rejected and the dispatcher falls back to the next available backend rather than returning a corrupted embedding or a truncated neighbor index.

Practical usage profile

Teams typically use this module during inspection and replay pipelines:

• validate embedding settings with optimal_delay/optimal_dimension,
• extract trajectory geometry with delay coordinates,
• use downstream monitors on the reconstructed state space instead of direct raw samples.

That pattern keeps signal reconstruction and control logic in one audited path.

::: scpn_phase_orchestrator.monitor.embedding