Module src.utils.key_estimation
Key Estimation Module for Umbilic-Surface Harmony.
Detects the Diatonic Key based on the geometric activation of Dominant and Subdominant surfaces. Uses src.materials as the single source of truth for surface activation physics.
[[ GEOMETRIC LOGIC ]] 1. TOPOLOGICAL AXIS: A Key is a container defined by the activation of its Dominant (t-1)
and Torque/Supertonic (t+2) surfaces.2. GEOMETRIC ID: To claim a Key, a set of notes must provide either:
– STABILITY: The Edge (Major 3rd, t+8). Anchors the Tonic. – TENSION: The Vector (Leading Tone, t+7). Points to the Tonic.3. HARMONIC RESOLUTION (EXPERIMENTAL: SUBTRACTION LOGIC):
– The “Minor” label is forced only if the Harmonic Dominant (t+8) was present in History but is NOT present in the Current frame (Resolution of Tension).
Functions
| KeyEstimation.reset () | Resets the internal state of the estimator. |
| KeyEstimation.estimate (notes, dt, speed_factor) | Estimates the Key based on active notes and surface topology. |