From 661496c172a53d09c59951c642f1a468abb7f07e Mon Sep 17 00:00:00 2001
From: YurenHao0426 <Blackhao0426@gmail.com>
Date: Wed, 22 Jul 2026 19:55:05 -0500
Subject: mechanism: separate BCI role from performance velocity

---
 experiments/bci_smoke.py | 50 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

(limited to 'experiments/bci_smoke.py')

diff --git a/experiments/bci_smoke.py b/experiments/bci_smoke.py
index 5cd5b65..4724d26 100644
--- a/experiments/bci_smoke.py
+++ b/experiments/bci_smoke.py
@@ -93,6 +93,55 @@ def check_phase_masks_and_velocity_reset():
     print("BCI online/plasticity phase masks and episode velocity reset: exact")
 
 
+def check_temporal_difference_role_vectorizer():
+    """Role perturbations times performance change give the Harnett sign."""
+    cfg = BCIConfig(
+        days=2, episodes_per_day=4096, steps_per_episode=2,
+        feedback="performance_velocity", vectorizer_eta=0.5)
+    model = BCISDIL(cfg, model_seed=12)
+    generator = torch.Generator().manual_seed(13)
+    soma = 0.2 * torch.randn(
+        cfg.episodes_per_day, cfg.n_neurons, generator=generator)
+    xi = torch.empty_like(soma).bernoulli_(
+        0.5, generator=generator).mul_(2).sub_(1)
+    target = model.causal_role_targets(soma, xi)
+    mean_target = target.mean(0)
+    cosine = torch.nn.functional.cosine_similarity(
+        mean_target, model.role, dim=0).item()
+    assert cosine > 0.99
+
+    active = torch.ones(cfg.episodes_per_day, dtype=torch.bool)
+    model.A.zero_()
+    model.update_vectorizer(
+        torch.ones(cfg.episodes_per_day, 1),
+        torch.zeros(cfg.episodes_per_day, cfg.n_neurons),
+        target, active)
+    learned_cosine = torch.nn.functional.cosine_similarity(
+        model.A[:, 0], model.role, dim=0).item()
+    assert learned_cosine > 0.99
+
+    # With the neutral predictor exact, r_i = role_i * delta_error.  Hence the
+    # P+ minus P- residual is positive in improving epochs and negative in
+    # worsening epochs, independent of instantaneous error magnitude.
+    model.A[:, 0].copy_(model.role)
+    model.P.copy_(model.coupling)
+    model.P_bias.zero_()
+    previous = torch.tensor([0.8, 0.4, 0.9, 0.3])
+    current = torch.tensor([0.6, 0.5, 0.5, 0.6])
+    delta = model.feedback_features(current, previous)
+    _, innovation, _, _ = model.apical_components(soma[:4], delta)
+    difference = (innovation[:, :cfg.n_plus].mean(1)
+                  - innovation[:, cfg.n_plus:cfg.n_plus + cfg.n_minus].mean(1))
+    improving = delta[:, 0] > 0
+    worsening = delta[:, 0] < 0
+    sign_index = 0.5 * (
+        difference[improving].mean() - difference[worsening].mean())
+    assert sign_index > 0
+    print(
+        "BCI temporal-difference role vectorizer: "
+        f"cos={cosine:.6f}, sign_index={sign_index.item():.6f}")
+
+
 def check_grouped_decoders_and_metrics():
     generator = torch.Generator().manual_seed(9)
     groups = torch.arange(200)
@@ -136,5 +185,6 @@ if __name__ == "__main__":
     check_causal_estimator()
     check_predictor_identification()
     check_phase_masks_and_velocity_reset()
+    check_temporal_difference_role_vectorizer()
     check_grouped_decoders_and_metrics()
     print("ALL BCI MECHANICS CHECKS PASSED")
-- 
cgit v1.2.3