Update README.md

README.md

@@ -6,6 +6,7 @@ tags:
   - adaptive
   - research
   - nested-lora
+  - synaptic-plasticity
   - rank-adaptation
 library_name: transformers
 datasets:
@@ -15,52 +16,46 @@ pipeline_tag: text-classification
 
 # Unified-LoRA
 
-**Adaptive rank controller for LoRA fine-tuning via nested orbital slicing.**
+**LoRA fine-tuning with synaptic plasticity: a neurobiologically-inspired controller that switches between qualitatively different operational modes based on training stress.**
 
-⚠️ **This is NOT a pretrained model.** Unified-LoRA is a training method/controller for LoRA.
+⚠️ **This is NOT a pretrained model.** Unified-LoRA is a training method/controller.
 
 👉 **Code**: [github.com/Sva76/Unified-LoRa](https://github.com/Sva76/Unified-LoRa)
 👉 **Demo**: [unified_lora_demo.ipynb](https://github.com/Sva76/Unified-LoRa/blob/main/notebooks/unified_lora_demo.ipynb)
 
 ## What It Does
 
-Instead of fixing `rank=8` and hoping it works, Unified-LoRA allocates a single LoRA matrix pair at max rank and controls active capacity via **matrix slicing** (r4 ⊂ r8 ⊂ r16). An OrbitalController monitors gradient stress per layer and promotes/demotes rank using adaptive thresholds (μ ± kσ).
+A composite synaptic stress signal **φ(t) = f(Convergence, Entropy, Stress)** drives a 3-state FSM:
 
-**Key properties:**
-- Zero cold-start on rank transitions (lower ranks are subsets of higher ranks)
-- Per-layer independence (each adapter finds its own optimal rank)
-- ~100 lines of code, no SVD, negligible overhead
+| Mode | φ range | Rank | Behavior |
+|------|---------|------|----------|
+| SINGLE | φ < 0.3 | r=4 | Efficient cruise |
+| MULTI | 0.3 ≤ φ < 0.7 | r=8 | Active learning |
+| MIRROR | φ ≥ 0.7 | r=16 | Max capacity + weight snapshot for rollback |
 
-## Results
+Rank transitions use **nested matrix slicing** (r4 ⊂ r8 ⊂ r16) — zero cold-start, zero re-allocation.
+
+Mirror mode saves a weight snapshot on entry. On exit, if weights drifted <5% (transient noise), the snapshot is restored. If drift was significant (real signal), the new weights are kept.
 
-**GLUE (DistilBERT, 67M):** Comparable or better on 3/4 tasks with 33–56% rank reduction.
+## Results
 
-| Task | Baseline (r=16) | Adaptive | Rank Reduction |
-|------|-----------------|----------|----------------|
-| MRPC | 0.882 F1        | **0.886**| 42%            |
-| CoLA | 0.488 MCC       | **0.491**| 56%            |
-| RTE  | 0.556 Acc       | **0.592**| 33%            |
+**GLUE (DistilBERT):** 3/4 tasks equal or better with 33–56% rank reduction.
 
-**Noise resilience (validated use case):** +31 F1 points at 50% label noise, 9× lower variance vs fixed rank. No benefit on clean data. Pattern confirmed at 67M, 1.1B, and 3B scales.
+**Noise resilience:** +31 F1 at 50% label noise, 9× lower variance. No benefit on clean data. Confirmed at 67M–3B.
 
-**NestedLoRA stress tests:** Performance parity with baseline, ~15% rank saving, zero cold-start degradation.
+**Stress-recovery cycle (Tinker/Llama-3.2-1B):** φ returns to pre-shock baseline (0.33 → 0.83 → 0.33), demonstrating fully reversible stress handling.
 
 ## Quick Start
 
 ```python
 from controller import setup_unified_lora
 
-adapters, ctrl = setup_unified_lora(
-    model,
-    target_modules=["q_proj", "v_proj"],
-    max_rank=16,
-    rank_levels=[4, 8, 16],
-)
+adapters, ctrl = setup_unified_lora(model, target_modules=["q_proj", "v_proj"])
 
 for batch in dataloader:
     loss = model(**batch).loss
     loss.backward()
-    ctrl.step()
+    ctrl.step(loss=loss.item())  # φ(t) needs the loss for convergence signal
     optimizer.step()
     optimizer.zero_grad()
 ```
@@ -70,7 +65,7 @@ for batch in dataloader:
 ```bibtex
 @software{unified_lora_2025,
   author = {Simona Vargiu},
-  title = {Unified-LoRA: Adaptive Rank Controller via Nested Orbital Slicing},
+  title = {Unified-LoRA: Synaptic Plasticity Controller for Adaptive LoRA Fine-Tuning},
   year = {2025},
   url = {https://github.com/Sva76/Unified-LoRa}
 }