Revise experimental results for Unified-LoRA

Updated the experimental results section to improve clarity and structure, including new quantitative and qualitative analyses of Unified-LoRA's performance under various conditions.

docs/experimental_results.md

@@ -1,144 +1,182 @@
-## 📊 Experimental Evidence — Rank Dynamics under Disturbance
+# Experimental Results
 
-This section summarizes the **qualitative experimental evidence** supporting the design of **Unified-LoRA**, focusing on *rank dynamics* rather than downstream accuracy.
+## 1. Stress Test — Task Switch (Quantitative)
+
+### Setup
 
-The goal is **not** to compete on SOTA benchmarks, but to demonstrate a **structural difference** in how model capacity is controlled during fine-tuning.
+- **Model**: DistilBERT-base-uncased + NestedLoRALinear (max_rank=16)
+- **Protocol**: MRPC × 60 steps → SST-2 × 60 steps (shock at step 60)
+- **Seeds**: 0, 1, 2 (same seed = same batch order for baseline and unified)
+- **Baseline**: Same architecture, rank=16 fixed, no controller
+- **Hardware**: Google Colab, T4 GPU
 
----
+### Results
 
-## Experimental Setting
+|                        | Baseline (r=16 fixed) | Unified (orbital) | Delta    |
+|------------------------|-----------------------|-------------------|----------|
+| SST-2 Acc (new task)   | 0.736                 | 0.740             | +0.004   |
+| MRPC F1 (retention)    | 0.526                 | 0.515             | -0.011   |
+| Effective rank         | 16.0                  | 13.6              |          |
+| Rank saving            | 0%                    | 15%               |          |
 
-All methods were evaluated under **identical conditions**:
+### Per-seed detail
 
-- **Model:** `Qwen/Qwen3-4B-Instruct-2507`
-- **Task:** GLUE CoLA (classification, autoregressive formulation)
-- **Environment:** Tinker (black-box setting — loss not directly observable)
-- **Hardware:** Standard cloud GPU (T4-class)
-- **Training length:** ~60 steps per method
+| Seed | Baseline SST-2 | Unified SST-2 | Baseline MRPC | Unified MRPC | Eff rank | Transitions |
+|------|----------------|---------------|---------------|--------------|----------|-------------|
+| 0    | 0.759          | 0.760         | 0.588         | 0.595        | 13.7     | 6           |
+| 1    | 0.649          | 0.664         | 0.783         | 0.781        | 13.2     | 6           |
+| 2    | 0.799          | 0.795         | 0.207         | 0.169        | 13.8     | 8           |
 
-This setup reflects realistic **API-based / enterprise fine-tuning**, where internal loss signals are not exposed.
+### Rank traces
 
----
+**Seed 0:**
+```
+[  0] r4  r4  r4  r4  r8  r8  r16 r16 r16 r16
+[ 10] r16 r16 r16 r16 r16 r16 r16 r16 r16 r16
+...
+[ 60] <<<SHOCK r16 r16 r16 r16 r16 r16 r16 r16 r16 r16
+[ 70] r16 r8  r8  r8  r8  r8  r8  r8  r8  r8
+[ 80] r4  r4  r4  r4  r4  r4  r4  r4  r4  r8
+[ 90] r8  r8  r8  r16 r16 r16 r16 r16 r16 r16
+```
 
-## Methods Compared
+**Seed 1 (cleanest trajectory):**
+```
+[  0] r4  r4  r4  r8  r8  r8  r8  r16 r16 r16
+[ 10] r16 r16 r16 r16 r16 r16 r16 r16 r16 r16
+...
+[ 60] <<<SHOCK r16 r16 r16 r16 r16 r16 r16 r16 r8  r8
+[ 70] r8  r8  r8  r8  r4  r4  r4  r4  r4  r4
+[ 80] r4  r4  r4  r4  r4  r4  r4  r4  r4  r4
+[ 90] r4  r4  r8  r16 r16 r16 r16 r16 r16 r16
+```
 
-| Method | Category | Control Logic |
-|------|---------|---------------|
-| Standard LoRA | Baseline | Fixed rank |
-| Schedule-free / Fixed Rank | Baseline+ | Fixed rank, optimized LR |
-| AdaLoRA-like | Open-loop adaptive | Rank = function of time |
-| **Unified-LoRA (proposed)** | **Closed-loop continuous** | **Rank = function of stress** |
+**Seed 2:**
+```
+[  0] r4  r8  r8  r8  r8  r8  r16 r16 r16 r16
+[ 10] r16 r16 r16 r16 r16 r16 r16 r16 r16 r16
+...
+[ 60] <<<SHOCK r8  r8  r16 r16 r16 r16 r16 r16 r16 r16
+[ 70] r16 r16 r16 r16 r8  r8  r8  r8  r8  r8
+[ 80] r8  r8  r8  r4  r4  r4  r4  r4  r4  r4
+[ 90] r8  r8  r8  r8  r8  r16 r16 r16 r16 r16
+```
 
----
+### Interpretation
 
-## Rank Dynamics — Comparative Analysis
+All three seeds show the same pattern post-shock:
+1. Controller detects the distribution shift (loss spike after task switch)
+2. Descends through orbitals: r16 → r8 → r4
+3. Stabilizes at ground state for 10-18 steps
+4. Re-ascends when new task complexity demands capacity: r4 → r8 → r16
 
-### Axes
-- **X-axis:** training step (0 → ~60)
-- **Y-axis:** effective LoRA rank
+The baseline stays at r=16 for all 120 steps regardless of the shock. It has no mechanism to detect or respond to the distribution shift.
 
-### 1️⃣ AdaLoRA-like (budget-based)
 
-- Stepwise, monotonic decreasing trajectory  
-- Starts at **rank = 32**
-- Slowly decays according to a predefined schedule
-- At step ~60 remains around **rank ≈ 23–24**
-- **No reaction** to shocks or dynamic changes
+## 2. Stable Task — Single Task Parity (Quantitative)
 
-**Interpretation:**  
-Adaptive *offline*, but **blind to the real training state**. Rank allocation follows a schedule, not feedback.
+### Setup
 
----
+- **Model**: DistilBERT-base-uncased + NestedLoRALinear (max_rank=16)
+- **Task**: MRPC only, 120 steps
+- **Seeds**: 0, 1, 2
+- **Baseline**: Same architecture, rank=16 fixed
 
-### 2️⃣ Schedule-free / Standard LoRA
+### Results
 
-- Flat trajectory
-- **Fixed rank = 16**
-- No dynamics, no feedback, no adaptation
+| Seed | Baseline F1 | Unified F1 | Delta  |
+|------|-------------|------------|--------|
+| 0    | 0.806       | 0.808      | +0.002 |
+| 1    | 0.822       | 0.826      | +0.004 |
+| 2    | 0.824       | 0.824      | +0.000 |
+| **Mean** | **0.818 ± 0.008** | **0.820 ± 0.008** | **+0.002** |
 
-**Interpretation:**  
-A stable but **capacity-blind baseline**. Learning rate optimization cannot compensate for lack of structural flexibility.
+The controller correctly identifies that no intervention is needed on a stable task and remains at r=16 for nearly all steps. Parity confirmed — the controller never hurts.
 
----
 
-### 3️⃣ Unified-LoRA (loss-proxy + injected shocks)
+## 3. Rank Dynamics under Disturbance (Qualitative — Tinker)
 
-- Continuous, **non-monotonic** trajectory
-- Starts from **rank = 6** (minimum capacity)
-- Progressively grows up to **rank ≈ 31**
-- **Immediate reaction** to injected disturbances (e.g. steps ~20, ~30, ~45)
-- No unstable oscillations observed
+### Setup
 
-**Interpretation:**  
-True **closed-loop control** over model capacity. Rank adapts to *observed stress*, not to a predefined schedule.
+- **Model**: Qwen/Qwen3-4B-Instruct-2507
+- **Task**: GLUE CoLA (classification, autoregressive formulation)
+- **Environment**: Tinker (black-box — loss not directly observable)
+- **Hardware**: Cloud GPU (T4-class)
+- **Training length**: ~60 steps per method
 
----
+This setup reflects API-based / enterprise fine-tuning, where internal loss signals are not exposed.
 
-## 📌 Key Observation — Disturbance Rejection
+### Methods compared
 
-| Method | Shock Reaction | Stability | Recovery |
-|------|----------------|----------|----------|
-| Standard / Schedule-free | ❌ None | Passive | — |
-| AdaLoRA-like | ⚠️ Indirect, delayed | Partial | Limited |
-| **Unified-LoRA** | ✅ Immediate | Stable | Immediate |
+| Method               | Category              | Control logic           |
+|----------------------|-----------------------|-------------------------|
+| Standard LoRA        | Baseline              | Fixed rank              |
+| Schedule-free        | Baseline+             | Fixed rank, optimized LR|
+| AdaLoRA-like         | Open-loop adaptive    | Rank = f(step)          |
+| Unified-LoRA         | Closed-loop continuous| Rank = f(stress)        |
 
-👉 **Only Unified-LoRA exhibits disturbance rejection**, a property expected from closed-loop control systems and absent in open-loop approaches.
+### Observations
 
----
+**AdaLoRA-like**: monotonic decreasing trajectory from rank=32 to ~24. No reaction to shocks. Adaptive offline, but blind to real training state.
 
-## Control-Theoretic Interpretation
+**Standard / Schedule-free LoRA**: flat trajectory at fixed rank. No dynamics, no adaptation.
 
-- **Standard / Schedule-free / AdaLoRA:** open-loop control  
-- **Unified-LoRA:** closed-loop continuous control
+**Unified-LoRA**: non-monotonic trajectory. Starts from rank=6, grows to ~31, immediate reaction to injected disturbances at steps ~20, ~30, ~45. No unstable oscillations.
 
-Formally:
+### Disturbance rejection
 
-Standard / AdaLoRA: rank = f(step)
-Unified-LoRA: rank = f(stress(step, history))
+| Method                  | Shock reaction | Stability | Recovery  |
+|-------------------------|----------------|-----------|-----------|
+| Standard / Schedule-free| None           | Passive   | —         |
+| AdaLoRA-like            | Indirect       | Partial   | Limited   |
+| Unified-LoRA            | Immediate      | Stable    | Immediate |
 
+Only Unified-LoRA exhibits disturbance rejection — a property of closed-loop control systems, absent in open-loop approaches.
 
-Where **stress** is a continuous, smoothed, normalized signal derived from observable training dynamics.
 
----
+## 4. Architecture Evolution — What Didn't Work
 
-## Why Black-Box Matters
+### Separate adapters (V1-V4)
 
-Unified-LoRA operates **without direct access to the loss**.
+Four versions of the controller were tested with independent adapter matrices per rank (r=4, r=8, r=16 as separate nn.Linear pairs):
 
-In Tinker-like environments, the system observes *trajectory-level signals*, not internal optimization variables.
+| Version        | Mean F1 | Δ vs baseline | Saving | Problem                              |
+|----------------|---------|---------------|--------|--------------------------------------|
+| V1 Homeostatic | 0.850   | +0.002*       | 62%    | No baseline in same run              |
+| V2 State-Aware | 0.812   | -0.036        | 46%    | Cold start on transitions            |
+| V3 State Ctrl  | 0.817   | -0.031        | 47%    | Stuck at r=8 on 2/3 seeds           |
+| V4 Trend-Aware | 0.821   | -0.027        | 14%    | Never activated on 2/3 seeds         |
 
-> “I observe the missile trajectory, not the engine — yet I can still control it.”
+*V1 baseline was from a different run, not directly comparable.
 
-This capability is critical for:
-- API-based fine-tuning
-- enterprise training pipelines
-- safety- or cost-constrained environments
+**Root cause**: switching between separate adapters means the new adapter has independent weights that never benefited from training at the previous rank. Every transition is a partial cold start.
 
----
+**Solution**: nested orbital architecture (single A/B pair, rank via slicing). This eliminated the cold start entirely and achieved parity with baseline.
 
-## Computational Overhead
+### Other approaches that didn't help on clean data
 
-Unified-LoRA introduces:
+- Adaptive rank per-layer (gradient EMA): no performance benefit
+- Fluid dynamics metrics (shock, vorticity, swirl): too conservative
+- Budget redistribution across layers: winner-takes-all problem
+- Fixed-threshold hysteresis: controller either never activated or got stuck
+- Vincolo StabilityController integration: zero shock events on stable training
 
-- **O(1)** computation per step
-- No SVD
-- No matrix decomposition
-- Negligible overhead relative to the training step
 
----
+## 5. Black-Box Compatibility
 
-## Takeaway
+The controller operates without access to:
+- Gradients
+- Internal activations
+- Optimizer state
+- Per-layer information
 
-Unified-LoRA is:
-- **not** a scheduler
-- **not** a rank budget
-- **not** a learning-rate trick
+It observes only the loss trajectory. This makes it compatible with API-based fine-tuning platforms (Azure OpenAI, Tinker) where the training loop is exposed but model internals are not.
 
-It implements a **dynamic controller over model capacity**.
+Computational overhead: O(1) per step. No SVD, no matrix decomposition.
 
-At equal training conditions:
-- higher stability
-- better resource utilization
 
-Under disturbances:
-- **it is the only method that reacts correctly**
+## Open Questions
+
+- Scale validation on 7B+ models (Tinker experiments in progress)
+- Minimum shock magnitude required for measurable controller benefit
+- Adaptive LR modulation as black-box analog of rank control (for platforms where rank is fixed at creation)