v1.0: demo montada desde el tag v1.0 del repositorio

README.md

@@ -1,13 +1,33 @@
 ---
-title: Gauge Orbit Quantization Demo
-emoji: 👀
+title: Gauge equivalence does not survive quantisation
+emoji: "\U0001FA9E"
 colorFrom: indigo
 colorTo: gray
 sdk: gradio
-sdk_version: 6.28.0
-python_version: '3.13'
+sdk_version: 6.22.0
 app_file: app.py
 pinned: false
+license: apache-2.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Gauge equivalence does not survive quantisation
+
+Interactive companion to the note *Gauge equivalence does not survive
+quantisation: value-output orbit, norm-product bound, and
+consequences for rotational methods*.
+
+Pick a point of the value-output gauge orbit and see what
+quantisation does to the OV circuit. The gauge leaves the circuit
+exactly fixed in real arithmetic; the demo shows the error staying at
+the fp64 floor before quantising and exploding after it.
+
+Nothing is reimplemented here: the app runs the note's own
+`src/gauges.py`, `src/quantizer.py` and `src/metrics.py` on a light
+carrier of the value-output sector. `scripts/paridad_demo.py`
+certifies the demo cell by cell against the published sweeps.
+
+The parity gate is not decoration: it replays the published sweeps'
+own gauges and requires the demo to return the same numbers to
+$3\times10^{-15}$, against a tolerance of $10^{-12}$.
+
+Code and paper: https://github.com/mmunozpl/gauge-orbit-quantization

app.py

@@ -0,0 +1,642 @@
+"""demo interactiva: la órbita de gauge valor-salida bajo cuantización.
+
+tres pestañas. la órbita, donde se elige un punto y se ve qué le hace
+la cuantización al circuito; el interruptor, con la validación
+end-to-end ya medida; y qué se mide, con el método.
+
+toda la aritmética la ejecuta el código del paper ---`src/gauges.py`,
+`src/quantizer.py`, `src/metrics.py`--- sobre el portador ligero de
+`demo/portador.py`. aquí no se reimplementa nada, y por eso
+`scripts/paridad_demo.py` puede certificar la demo celda a celda
+contra los csv publicados.
+"""
+
+import sys
+from pathlib import Path
+
+import gradio as gr
+import matplotlib
+import torch
+
+matplotlib.use("Agg")               # sin servidor gráfico en el Space
+
+from matplotlib.figure import Figure  # noqa: E402
+
+
+def _raiz() -> Path:
+    """la raíz del árbol, igual en el repo que en el Space.
+
+    en el repositorio este fichero vive en `demo/`; en el Space, la
+    app viaja a la raíz para que Gradio la encuentre. se sube hasta
+    dar con el directorio que contiene `src` y `demo`, y así el mismo
+    código sirve en los dos sitios sin condicionales.
+
+    returns:
+        el directorio raíz del árbol.
+    """
+    aqui = Path(__file__).resolve()
+    for cand in (aqui.parent, *aqui.parents):
+        if (cand / "src").is_dir() and (cand / "demo").is_dir():
+            return cand
+    return aqui.parent
+
+
+sys.path.insert(0, str(_raiz()))
+
+from demo.portador import carga, par  # noqa: E402
+from src.gauges import (aplica_gauge, gauge_balanceado,  # noqa: E402
+                        gl_condicionado, gl_general, ortogonal,
+                        producto_normas)
+from src.metrics import circuito, error_relativo  # noqa: E402
+from src.quantizer import rtn_cuantiza_descuantiza  # noqa: E402
+
+DOI = "https://doi.org/10.5281/zenodo.21630534"
+REPO = "https://github.com/mmunozpl/gauge-orbit-quantization"
+# gr.Markdown no compone matemáticas salvo que se le declaren los
+# delimitadores; sin esto la prosa enseña los dólares en crudo.
+LATEX = [{"left": "$$", "right": "$$", "display": True},
+         {"left": "$", "right": "$", "display": False}]
+# exponente publicado del ajuste conjunto sobre las dos familias
+# (artifacts/tables/colapso_producto.csv, variable=producto, bits=4).
+EXPONENTE = 0.9979
+IDIOMAS = {"English": "en", "Español": "es"}
+MODELOS = {"vitb": {"n_capas": 12, "n_cabezas": 12, "dim_cabeza": 64},
+           "pythia": {"n_capas": 24, "n_cabezas": 16, "dim_cabeza": 64}}
+# rejilla de fuerzas que la figura recorre en vivo, por familia
+REJILLA = {"gl_escala": [32.0, 16.0, 8.0, 4.0, 2.0],
+           "gl_kappa": [2.0, 10.0, 50.0, 200.0, 1000.0],
+           "conforme": [0.1, 0.5, 1.0, 5.0, 50.0],
+           "orto": [0.0, 1.0, 2.0, 3.0, 4.0]}
+_CACHE: dict[str, dict] = {}
+
+FAM = {
+    "en": {"identidad": "identity (the trained gauge)",
+           "conforme": "conformal orthogonal c·Q",
+           "orto": "Haar orthogonal",
+           "balanceado": "balanced point (constructed)",
+           "gl_escala": "general GL, by scale",
+           "gl_kappa": "general GL, by condition number κ"},
+    "es": {"identidad": "identidad (el gauge entrenado)",
+           "conforme": "conforme ortogonal c·Q",
+           "orto": "ortogonal de Haar",
+           "balanceado": "punto balanceado (construido)",
+           "gl_escala": "GL general, por escala",
+           "gl_kappa": "GL general, por número de condición κ"},
+}
+PARAM = {
+    "en": {"identidad": "unused", "conforme": "coefficient c",
+           "orto": "unused", "balanceado": "unused",
+           "gl_escala": "scale (low = strong gauge)",
+           "gl_kappa": "target κ"},
+    "es": {"identidad": "sin uso", "conforme": "coeficiente c",
+           "orto": "sin uso", "balanceado": "sin uso",
+           "gl_escala": "escala (baja = gauge fuerte)",
+           "gl_kappa": "κ objetivo"},
+}
+DEFECTO = {"identidad": 1.0, "conforme": 1.0, "orto": 1.0,
+           "balanceado": 1.0, "gl_escala": 8.0, "gl_kappa": 50.0}
+
+
+def portador(modelo: str) -> dict:
+    """carga el portador de un modelo, con caché de proceso.
+
+    args:
+        modelo: 'vitb' o 'pythia'.
+
+    returns:
+        el dict de `demo.portador.carga`.
+    """
+    if modelo not in _CACHE:
+        _CACHE[modelo] = carga(modelo)
+    return _CACHE[modelo]
+
+
+def construye_r(
+    familia: str,
+    parametro: float,
+    dim_cabeza: int,
+    gen: torch.Generator,
+) -> torch.Tensor | None:
+    """el gauge de una familia, en fp64.
+
+    args:
+        familia: clave de `FAM`.
+        parametro: el mando de la familia; sin uso en varias.
+        dim_cabeza: d_h.
+        gen: generador de torch.
+
+    returns:
+        tensor [d_h, d_h] en float64, o None para la identidad.
+
+    raises:
+        ValueError: si la familia no existe.
+    """
+    if familia == "identidad":
+        return None
+    if familia == "conforme":
+        return float(parametro) * ortogonal(dim_cabeza, gen)
+    if familia == "orto":
+        return ortogonal(dim_cabeza, gen)
+    if familia == "gl_escala":
+        return gl_general(dim_cabeza, float(parametro), gen)
+    if familia == "gl_kappa":
+        return gl_condicionado(dim_cabeza, float(parametro), gen)
+    raise ValueError(f"familia desconocida: {familia}")
+
+
+def mide_capa(
+    modelo: str,
+    capa: int,
+    familia: str,
+    parametro: float,
+    semilla: int,
+    bits: int,
+) -> list[dict]:
+    """mide todas las cabezas de una capa bajo un punto de la órbita.
+
+    por cabeza devuelve p, d(R), cond(R), el error del circuito sin
+    cuantizar ---el suelo de fp64, que la invariancia exige--- y el
+    error tras cuantizar, con su cociente contra la identidad.
+
+    args:
+        modelo: 'vitb' o 'pythia'.
+        capa: índice de capa.
+        familia: clave de `FAM`.
+        parametro: el mando de la familia.
+        semilla: semilla del muestreo.
+        bits: 4 u 8.
+
+    returns:
+        lista de dicts, una por cabeza.
+    """
+    info = MODELOS[modelo]
+    port = portador(modelo)
+    gen = torch.Generator().manual_seed(int(semilla))
+    filas = []
+    for h in range(info["n_cabezas"]):
+        w_v, w_o = par(port, capa, h)
+        m_ref = circuito(w_v, w_o)
+        e_ident = error_relativo(rtn_cuantiza_descuantiza(w_v, bits),
+                                 rtn_cuantiza_descuantiza(w_o, bits),
+                                 m_ref)
+        if familia == "balanceado":
+            r, _ = gauge_balanceado(w_v, w_o)
+        else:
+            r = construye_r(familia, parametro, info["dim_cabeza"], gen)
+        if r is None:
+            a, b = w_v, w_o
+        else:
+            a, b = aplica_gauge(w_v, w_o, r)
+        e_exacto = error_relativo(a, b, m_ref)
+        e_quant = error_relativo(rtn_cuantiza_descuantiza(a, bits),
+                                 rtn_cuantiza_descuantiza(b, bits),
+                                 m_ref)
+        if r is None:
+            p, d_r, cond = 1.0, 0.0, 1.0
+        else:
+            p = producto_normas(w_v, w_o, r)
+            s = torch.linalg.svdvals(r)
+            d_r = float((s - s.mean()).norm() / s.norm())
+            cond = float(s[0] / s[-1])
+        filas.append({"cabeza": h, "p": p, "d_r": d_r, "cond": cond,
+                      "e_exacto": e_exacto, "e_quant": e_quant,
+                      "e_ident": e_ident,
+                      "cociente": e_quant / e_ident})
+    return filas
+
+
+def _mediana(filas: list[dict], clave: str) -> float:
+    """mediana de una columna de `mide_capa`."""
+    v = sorted(f[clave] for f in filas)
+    n = len(v)
+    return v[n // 2] if n % 2 else 0.5 * (v[n // 2 - 1] + v[n // 2])
+
+
+def figura(
+    modelo: str,
+    capa: int,
+    familia: str,
+    semilla: int,
+    bits: int,
+    punto: tuple[float, float] | None,
+    idi: str,
+) -> Figure:
+    """la ley del producto recorrida en vivo, con el punto elegido.
+
+    se barre la rejilla de fuerzas de la familia sobre las cabezas de
+    la capa y se dibuja $e/e_0$ contra $p$ en log-log, junto a la recta
+    de exponente uno que el ajuste publicado da sobre 743 424 medidas.
+
+    args:
+        modelo: 'vitb' o 'pythia'.
+        capa: índice de capa.
+        familia: clave de `FAM`.
+        semilla: semilla del muestreo.
+        bits: 4 u 8.
+        punto: (p, cociente) del punto elegido, o None.
+        idi: 'en' o 'es'.
+
+    returns:
+        la figura de matplotlib.
+    """
+    fig = Figure(figsize=(6.4, 4.2))
+    ax = fig.subplots()
+    rejilla = REJILLA.get(familia, [DEFECTO[familia]])
+    xs, ys = [], []
+    for valor in rejilla:
+        for f in mide_capa(modelo, capa, familia, valor, semilla, bits):
+            if f["p"] > 0 and f["cociente"] > 0:
+                xs.append(f["p"])
+                ys.append(f["cociente"])
+    if xs:
+        ax.scatter(xs, ys, s=14, alpha=0.45,
+                   label="barrido en vivo" if idi == "es"
+                   else "live sweep")
+        lo, hi = min(xs + [0.9]), max(xs + [1.1])
+        rec = [lo, hi]
+        ax.plot(rec, [x ** EXPONENTE for x in rec], color="crimson",
+                linewidth=1.4,
+                label=(f"ajuste publicado, exponente {EXPONENTE}"
+                       if idi == "es"
+                       else f"published fit, exponent {EXPONENTE}"))
+    if punto is not None and punto[0] > 0 and punto[1] > 0:
+        ax.scatter([punto[0]], [punto[1]], s=140, marker="*",
+                   color="black", zorder=5,
+                   label="tu punto" if idi == "es" else "your point")
+    ax.set_xscale("log")
+    ax.set_yscale("log")
+    ax.set_xlabel("$p(R)$")
+    ax.set_ylabel("$e/e_0$")
+    ax.set_title("La ley del producto" if idi == "es"
+                 else "The product law")
+    ax.legend(fontsize=8)
+    fig.tight_layout()
+    return fig
+
+
+LEMA = {
+ "en": ("### Same function before quantisation; different error "
+        "after it\n\n"
+        "$p(R)$ tracks the quantisation sensitivity of the "
+        "value-output factorisation."),
+ "es": ("### La misma función antes de cuantizar; distinto error "
+        "después\n\n"
+        "$p(R)$ mide la sensibilidad a la cuantización de la "
+        "factorización valor-salida."),
+}
+# de dónde sale cada número: la demo mezcla medida en vivo sobre una
+# capa con el ajuste publicado sobre el barrido entero, y quien mire
+# tiene derecho a saber cuál es cuál sin abrir el código.
+ALCANCE = {
+ "en": ("**Live**, computed now over the chosen model, layer and "
+        "point: the table above, the per-head table and the scattered "
+        "points below. **Published**, measured offline over the full "
+        "sweep of $743\\,424$ points across two models, two bit "
+        "widths and two gauge families: the red line of exponent "
+        f"{EXPONENTE}. A live sample of one layer is not the "
+        "experiment; it is one slice of it."),
+ "es": ("**En vivo**, calculado ahora sobre el modelo, la capa y el "
+        "punto elegidos: la tabla de arriba, la tabla por cabeza y "
+        "los puntos dispersos de abajo. **Publicado**, medido aparte "
+        "sobre el barrido entero de $743\\,424$ puntos en dos "
+        "modelos, dos anchuras y dos familias de gauge: la recta roja "
+        f"de exponente {EXPONENTE}. Una muestra en vivo de una capa "
+        "no es el experimento, es una rebanada suya."),
+}
+
+T = {
+ "en": {
+  "titulo": (
+    "## Gauge equivalence does not survive quantisation\n\n"
+    "The value-output pair of an attention head is not unique: for "
+    "every invertible $R$, the substitution $W_v\\to R^\\top W_v$, "
+    "$W_O\\to W_O R^{-\\top}$ leaves the OV circuit "
+    "$M=W_O W_v$ **exactly** fixed. Pick a point of that orbit below "
+    "and watch what quantisation does to it.\n\n"
+    f"Paper and code: [repository]({REPO}) · previous work: "
+    f"[{DOI.split('/')[-1]}]({DOI})"),
+  "tab1": "The orbit", "tab2": "The switch", "tab3": "What is measured",
+  "modelo": "Model", "capa": "Layer", "familia": "Gauge family",
+  "param": "Parameter", "sem": "Seed", "bits": "Bit width",
+  "btn": "Measure this point", "fig": "The product law",
+  "alcance": "What is live and what is published",
+  "porcabeza": "Per head", "res": "Result",
+  "cab": ["head", "p(R)", "d(R)", "cond(R)", "e unquantised",
+          f"e quantised", "e / e0"],
+ },
+ "es": {
+  "titulo": (
+    "## La equivalencia de gauge no sobrevive a la cuantización\n\n"
+    "El par valor-salida de una cabeza de atención no es único: para "
+    "toda $R$ invertible, la sustitución $W_v\\to R^\\top W_v$, "
+    "$W_O\\to W_O R^{-\\top}$ deja el circuito OV $M=W_O W_v$ "
+    "**exactamente** fijo. Elige abajo un punto de esa órbita y mira "
+    "qué le hace la cuantización.\n\n"
+    f"Artículo y código: [repositorio]({REPO}) · trabajo previo: "
+    f"[{DOI.split('/')[-1]}]({DOI})"),
+  "tab1": "La órbita", "tab2": "El interruptor", "tab3": "Qué se mide",
+  "modelo": "Modelo", "capa": "Capa", "familia": "Familia de gauge",
+  "param": "Parámetro", "sem": "Semilla", "bits": "Anchura",
+  "btn": "Medir este punto", "fig": "La ley del producto",
+  "alcance": "Qué es en vivo y qué es publicado",
+  "porcabeza": "Por cabeza", "res": "Resultado",
+  "cab": ["cabeza", "p(R)", "d(R)", "cond(R)", "e sin cuantizar",
+          "e cuantizado", "e / e0"],
+ },
+}
+
+QSM = {
+ "en": (
+  "### What is measured\n\n"
+  "**The circuit error.** $e=\\lVert\\hat M-M\\rVert_F/"
+  "\\lVert M\\rVert_F$, with $\\hat M$ recomposed in fp64 from the "
+  "quantised pair. All gauge arithmetic is fp64.\n\n"
+  "**The bound.** With a per-row quantiser bounded by $\\delta$, "
+  "$e(R)\\le(\\delta_v+\\delta_O+\\delta_v\\delta_O)\\,g(R)$, and "
+  "with $g$ the only gauge-dependent factor. Normalising it by its "
+  "value at the identity gives $p=\\lVert W_OR^{-\\top}\\rVert_F"
+  "\\lVert R^{\\top}W_v\\rVert_F/"
+  "(\\lVert W_O\\rVert_F\\lVert W_v\\rVert_F)$. Two bounds do not "
+  "divide: $e/e_0\\simeq p$ holds if the effective quantisation "
+  "factor varies little across gauges. It is the hypothesis, not a "
+  "corollary.\n\n"
+  "**Two analytic ends.** The conformal orthogonal class $\\{cQ\\}$ "
+  "gives $p\\equiv1$ for every $c$ and $Q$, so it is neutral for "
+  "the bound. The "
+  "balanced point minimises $p$ over the whole orbit, and the "
+  "minimisers are that family up to a reciprocal rescaling.\n\n"
+  "**$d(R)$** is the standard deviation of the singular values over "
+  "their norm, the distance to $\\{cQ\\}$. It is exactly zero on the "
+  "neutral class.\n\n"
+  "**Nothing is reimplemented here.** The demo runs `src/gauges.py`, "
+  "`src/quantizer.py` and `src/metrics.py` on a light carrier of the "
+  "value-output sector, and `scripts/paridad_demo.py` certifies it "
+  "cell by cell against the published sweeps.\n\n"
+  "**What this demo does not do.** It does not run forwards. The "
+  "end-to-end numbers in the second tab were measured offline over "
+  "the 5000 images of the clean ImageNet-100 validation split."),
+ "es": (
+  "### Qué se mide\n\n"
+  "**El error del circuito.** $e=\\lVert\\hat M-M\\rVert_F/"
+  "\\lVert M\\rVert_F$, con $\\hat M$ recompuesto en fp64 desde el "
+  "par cuantizado. Toda la aritmética de gauges es fp64.\n\n"
+  "**La cota.** Con un cuantizador por fila acotado por $\\delta$, "
+  "$e(R)\\le(\\delta_v+\\delta_O+\\delta_v\\delta_O)\\,g(R)$, y "
+  "con $g$ el único factor que depende del gauge. Normalizarlo por "
+  "su valor en la identidad da $p=\\lVert W_OR^{-\\top}\\rVert_F"
+  "\\lVert R^{\\top}W_v\\rVert_F/"
+  "(\\lVert W_O\\rVert_F\\lVert W_v\\rVert_F)$. Dos cotas no se "
+  "dividen: $e/e_0\\simeq p$ vale si el factor efectivo de "
+  "cuantización varía poco entre gauges. Es la hipótesis, no un "
+  "corolario.\n\n"
+  "**Dos extremos analíticos.** La clase conforme ortogonal "
+  "$\\{cQ\\}$ da $p\\equiv1$ para toda $c$ y toda $Q$, así que es "
+  "neutra para la cota. El punto balanceado minimiza $p$ sobre la "
+  "órbita entera, "
+  "y los mínimos son esa familia salvo un escalado recíproco.\n\n"
+  "**$d(R)$** es la desviación típica de los valores singulares "
+  "partida por su norma, la distancia a $\\{cQ\\}$. Vale cero "
+  "exactamente sobre la clase neutra.\n\n"
+  "**Aquí no se reimplementa nada.** La demo ejecuta "
+  "`src/gauges.py`, `src/quantizer.py` y `src/metrics.py` sobre un "
+  "portador ligero del sector valor-salida, y "
+  "`scripts/paridad_demo.py` la certifica celda a celda contra los "
+  "barridos publicados.\n\n"
+  "**Qué no hace esta demo.** No corre forwards. Las cifras "
+  "end-to-end de la segunda pestaña se midieron aparte sobre las "
+  "5000 imágenes del val limpio de ImageNet-100."),
+}
+
+
+def tabla_e2e(idi: str) -> str:
+    """la validación end-to-end medida, como markdown.
+
+    args:
+        idi: 'en' o 'es'.
+
+    returns:
+        el bloque de markdown de la pestaña del interruptor.
+    """
+    import csv
+
+    ruta = _raiz() / "artifacts" / "tables" / "validacion_e2e.csv"
+    if not ruta.exists():
+        return "_sin tabla end-to-end_" if idi == "es" else "_no table_"
+    filas = list(csv.DictReader(ruta.open()))
+    nom = {"identidad_fp32": ("Identity, not quantised",
+                              "Identidad, sin cuantizar"),
+           "identidad": ("Identity, int4", "Identidad, int4"),
+           "mejor_orto_muestreado": ("Best sampled orthogonal, int4",
+                                     "Mejor ortogonal muestreado, int4"),
+           "peor_orto_muestreado": ("Worst sampled orthogonal, int4",
+                                    "Peor ortogonal muestreado, int4"),
+           "balanceado": ("Balanced point, int4",
+                          "Punto balanceado, int4"),
+           "gl_escala2_fp32": ("GL scale 2, NOT quantised",
+                               "GL escala 2, SIN cuantizar"),
+           "gl_escala2": ("GL scale 2, int4", "GL escala 2, int4")}
+    cab = ("| Condition | Top-1 |\n|---|---|"
+           if idi == "en" else "| Condición | Top-1 |\n|---|---|")
+    j = 0 if idi == "en" else 1
+    cuerpo = "\n".join(
+        f"| {nom.get(f['condicion'], (f['condicion'],) * 2)[j]} "
+        f"| {float(f['top1']):.4f} |" for f in filas)
+    intro = {
+     "en": ("### The switch\n\nSeven forwards of ViT-B/16 over the "
+            "5000 images of the clean ImageNet-100 validation split. "
+            "The same gauge is measured twice, with and without "
+            "quantisation. That pair of rows is the whole argument: "
+            "the gauge leaves the function alone and quantisation "
+            "destroys it. Unquantised, that gauge predicts the same "
+            "class as the identity on **all 5000 images**, without a "
+            "single discrepancy; quantised, it agrees on 44.\n\n"),
+     "es": ("### El interruptor\n\nSiete forwards de ViT-B/16 sobre "
+            "las 5000 imágenes del val limpio de ImageNet-100. El "
+            "mismo gauge se mide dos veces, con y sin cuantizar. Ese "
+            "par de filas es el argumento entero: el gauge deja la "
+            "función quieta y la cuantización la destruye. Sin "
+            "cuantizar, ese gauge predice la misma clase que la "
+            "identidad en **las 5000 imágenes**, sin una sola "
+            "discrepancia; cuantizado, coincide en 44.\n\n"),
+    }
+    return intro[idi] + cab + "\n" + cuerpo
+
+
+def orbita(
+    idioma: str,
+    modelo: str,
+    capa: int,
+    familia: str,
+    parametro: float,
+    semilla: int,
+    bits: int,
+):
+    """mide el punto elegido y compone resultado, tabla y figura.
+
+    args:
+        idioma: clave de `IDIOMAS`.
+        modelo: 'vitb' o 'pythia'.
+        capa: índice de capa.
+        familia: clave de `FAM`.
+        parametro: el mando de la familia.
+        semilla: semilla del muestreo.
+        bits: 4 u 8.
+
+    returns:
+        (markdown del resultado, filas de la tabla, figura).
+    """
+    idi = IDIOMAS[idioma]
+    filas = mide_capa(modelo, int(capa), familia, parametro,
+                      int(semilla), int(bits))
+    p_med = _mediana(filas, "p")
+    coc = _mediana(filas, "cociente")
+    e_ex = max(f["e_exacto"] for f in filas)
+    e_q = _mediana(filas, "e_quant")
+    d_med = _mediana(filas, "d_r")
+    cond_med = _mediana(filas, "cond")
+    if idi == "es":
+        res = (
+          f"**En vivo** · {FAM['es'][familia]}, capa {int(capa)}, "
+          f"int{int(bits)}. Medianas sobre las {len(filas)} cabezas "
+          f"de esa capa.\n\n"
+          f"| | |\n|---|---|\n"
+          f"| $p(R)$ | {p_med:.4f} |\n"
+          f"| $d(R)$, distancia a la clase neutra | {d_med:.4f} |\n"
+          f"| $\\operatorname{{cond}}(R)$ | {cond_med:.3f} |\n"
+          f"| error del circuito **sin cuantizar** (peor cabeza) "
+          f"| {e_ex:.2e} |\n"
+          f"| error del circuito en int{int(bits)} | {e_q:.4f} |\n"
+          f"| $e/e_0$ medido | {coc:.4f} |\n"
+          f"| $e/e_0$ que la cota predice | {p_med:.4f} |\n\n"
+          f"Sin cuantizar el error se queda en el suelo de fp64: el "
+          f"gauge no toca la función. Cuantizado, el mismo punto "
+          f"multiplica el error por {coc:.2f}.")
+    else:
+        res = (
+          f"**Live** · {FAM['en'][familia]}, layer {int(capa)}, "
+          f"int{int(bits)}. Medians over the {len(filas)} heads of "
+          f"that layer.\n\n"
+          f"| | |\n|---|---|\n"
+          f"| $p(R)$ | {p_med:.4f} |\n"
+          f"| $d(R)$, distance to the neutral class | {d_med:.4f} |\n"
+          f"| $\\operatorname{{cond}}(R)$ | {cond_med:.3f} |\n"
+          f"| circuit error **unquantised** (worst head) "
+          f"| {e_ex:.2e} |\n"
+          f"| circuit error at int{int(bits)} | {e_q:.4f} |\n"
+          f"| $e/e_0$ measured | {coc:.4f} |\n"
+          f"| $e/e_0$ predicted by the bound | {p_med:.4f} |\n\n"
+          f"Unquantised the error stays at the fp64 floor: the gauge "
+          f"does not touch the function. Quantised, the same point "
+          f"multiplies the error by {coc:.2f}.")
+    tabla = [[f["cabeza"], round(f["p"], 4), round(f["d_r"], 4),
+              round(f["cond"], 3), f"{f['e_exacto']:.2e}",
+              round(f["e_quant"], 5), round(f["cociente"], 4)]
+             for f in filas]
+    fig = figura(modelo, int(capa), familia, int(semilla), int(bits),
+                 (p_med, coc), idi)
+    return res, tabla, fig
+
+
+def capas_de(modelo: str):
+    """actualiza el desplegable de capas al cambiar de modelo.
+
+    args:
+        modelo: 'vitb' o 'pythia'.
+
+    returns:
+        la actualización de gradio para el desplegable.
+    """
+    n = MODELOS[modelo]["n_capas"]
+    return gr.update(choices=list(range(n)), value=min(5, n - 1))
+
+
+def cambia_familia(idioma: str, familia: str):
+    """reetiqueta el mando de la familia y le pone su valor por defecto.
+
+    args:
+        idioma: clave de `IDIOMAS`.
+        familia: clave de `FAM`.
+
+    returns:
+        la actualización de gradio para el mando.
+    """
+    idi = IDIOMAS[idioma]
+    return gr.update(label=PARAM[idi][familia], value=DEFECTO[familia])
+
+
+def cambia_idioma(idioma: str, familia: str):
+    """reetiqueta la interfaz entera.
+
+    args:
+        idioma: clave de `IDIOMAS`.
+        familia: clave de `FAM` vigente.
+
+    returns:
+        la tupla de actualizaciones, en el orden del cableado.
+    """
+    idi = IDIOMAS[idioma]
+    d = T[idi]
+    fam_op = [(v, k) for k, v in FAM[idi].items()]
+    return (gr.update(value=d["titulo"]),
+            gr.update(value=LEMA[idi]),
+            gr.update(label=d["modelo"]),
+            gr.update(label=d["capa"]),
+            gr.update(choices=fam_op, label=d["familia"]),
+            gr.update(label=PARAM[idi][familia]),
+            gr.update(label=d["sem"]),
+            gr.update(label=d["bits"]),
+            gr.update(value=d["btn"]),
+            gr.update(label=d["res"]),
+            gr.update(headers=d["cab"], label=d["porcabeza"]),
+            gr.update(label=d["fig"]),
+            gr.update(value=ALCANCE[idi], label=d["alcance"]),
+            gr.update(value=tabla_e2e(idi)),
+            gr.update(value=QSM[idi]),
+            gr.update(label=d["tab1"]),
+            gr.update(label=d["tab2"]),
+            gr.update(label=d["tab3"]))
+
+
+TITULO = ("Gauge equivalence does not survive quantisation - "
+          "La equivalencia de gauge no sobrevive a la cuantización")
+
+with gr.Blocks(title=TITULO) as demo:
+    idi_o = gr.Radio(list(IDIOMAS), value="English",
+                     label="Idioma / Language")
+    cab = gr.Markdown(T["en"]["titulo"], latex_delimiters=LATEX)
+    lema = gr.Markdown(LEMA["en"], latex_delimiters=LATEX)
+    with gr.Tab(T["en"]["tab1"]) as pes1:
+        with gr.Row():
+            mod_o = gr.Dropdown(list(MODELOS), value="vitb",
+                                label=T["en"]["modelo"])
+            capa_o = gr.Dropdown(list(range(12)), value=5,
+                                 label=T["en"]["capa"])
+            fam_o = gr.Dropdown([(v, k) for k, v in FAM["en"].items()],
+                                value="gl_escala",
+                                label=T["en"]["familia"])
+            par_o = gr.Number(value=8.0, label=PARAM["en"]["gl_escala"])
+            sem_o = gr.Number(value=0, precision=0, label=T["en"]["sem"])
+            bit_o = gr.Radio([4, 8], value=4, label=T["en"]["bits"])
+        btn_o = gr.Button(T["en"]["btn"], variant="primary")
+        res_o = gr.Markdown(label=T["en"]["res"], latex_delimiters=LATEX)
+        fig_o = gr.Plot(label=T["en"]["fig"])
+        alc_o = gr.Markdown(ALCANCE["en"], label=T["en"]["alcance"],
+                            latex_delimiters=LATEX)
+        tab_o = gr.Dataframe(headers=T["en"]["cab"],
+                             label=T["en"]["porcabeza"])
+        mod_o.change(capas_de, mod_o, capa_o)
+        fam_o.change(cambia_familia, [idi_o, fam_o], par_o)
+        btn_o.click(orbita,
+                    [idi_o, mod_o, capa_o, fam_o, par_o, sem_o, bit_o],
+                    [res_o, tab_o, fig_o])
+    with gr.Tab(T["en"]["tab2"]) as pes2:
+        e2e_o = gr.Markdown(tabla_e2e("en"), latex_delimiters=LATEX)
+    with gr.Tab(T["en"]["tab3"]) as pes3:
+        qsm_o = gr.Markdown(QSM["en"], latex_delimiters=LATEX)
+    idi_o.change(cambia_idioma, [idi_o, fam_o],
+                 [cab, lema, mod_o, capa_o, fam_o, par_o, sem_o,
+                  bit_o, btn_o, res_o, tab_o, fig_o, alc_o, e2e_o,
+                  qsm_o, pes1, pes2, pes3])
+
+if __name__ == "__main__":
+    demo.launch()

artifacts/demo/sector_vo_pythia.json

@@ -0,0 +1,23 @@
+{
+  "modelo": "pythia",
+  "n_capas": 24,
+  "n_cabezas": 16,
+  "dim_cabeza": 64,
+  "formas": {
+    "w_v": [
+      24,
+      16,
+      64,
+      1024
+    ],
+    "w_o": [
+      24,
+      16,
+      1024,
+      64
+    ]
+  },
+  "dtype": "float32 en disco, float64 al cargar",
+  "sha256": "60d47a1947aa620dbca68fae9d7a832405f4f554d6cd17a5b83705b41061966e",
+  "bytes": 201326760
+}

artifacts/demo/sector_vo_pythia.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:60d47a1947aa620dbca68fae9d7a832405f4f554d6cd17a5b83705b41061966e
+size 201326760

artifacts/demo/sector_vo_vitb.json

@@ -0,0 +1,23 @@
+{
+  "modelo": "vitb",
+  "n_capas": 12,
+  "n_cabezas": 12,
+  "dim_cabeza": 64,
+  "formas": {
+    "w_v": [
+      12,
+      12,
+      64,
+      768
+    ],
+    "w_o": [
+      12,
+      12,
+      768,
+      64
+    ]
+  },
+  "dtype": "float32 en disco, float64 al cargar",
+  "sha256": "10ef9ef42a14cd3e6d3ddcd3ee3bd84a80dd3242ee3a2891766ead931607e4ad",
+  "bytes": 56623272
+}

artifacts/demo/sector_vo_vitb.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:10ef9ef42a14cd3e6d3ddcd3ee3bd84a80dd3242ee3a2891766ead931607e4ad
+size 56623272

artifacts/tables/validacion_e2e.csv

@@ -0,0 +1,8 @@
+condicion,bits,top1,desv_invariancia,post_hoc_declarado
+identidad_fp32,,0.9314,,False
+identidad,4,0.9308,,False
+mejor_orto_muestreado,4,0.9306,3.976204823175067e-07,False
+peor_orto_muestreado,4,0.9298,4.014851526790153e-07,False
+balanceado,4,0.9306,4.2091673435606936e-07,True
+gl_escala2_fp32,,0.9314,1.1825894034700468e-05,True
+gl_escala2,4,0.0082,1.1825894034700468e-05,True

demo/portador.py

@@ -0,0 +1,119 @@
+"""carga del portador del sector valor-salida.
+
+lo construye `scripts/extraer_sector_vo.py`. aquí solo se lee y se
+verifica, porque el Space no lleva los modelos originales.
+
+la regla de esta demo: no se reimplementa nada. el portador devuelve
+los mismos tensores que `src.weights.w_v_w_o_*` entregaba al barrido, y
+sobre ellos corren `src.gauges`, `src.quantizer` y `src.metrics` sin
+un byte cambiado. si la demo y el paper discreparan, el culpable sería
+el portador, y por eso lleva manifiesto con sha256.
+"""
+
+import hashlib
+import json
+from pathlib import Path
+
+from safetensors.torch import load_file
+
+def _raiz() -> Path:
+    """la raíz del árbol, igual en el repo que en el Space.
+
+    returns:
+        el directorio que contiene `src` y `demo`.
+    """
+    aqui = Path(__file__).resolve()
+    for cand in (aqui.parent, *aqui.parents):
+        if (cand / "src").is_dir() and (cand / "demo").is_dir():
+            return cand
+    return aqui.parent
+
+
+RAIZ_DEFECTO = _raiz() / "artifacts" / "demo"
+
+
+def _sha256(ruta: Path) -> str:
+    """digest del fichero del portador.
+
+    args:
+        ruta: fichero a resumir.
+
+    returns:
+        sha256 en hexadecimal.
+    """
+    h = hashlib.sha256()
+    with ruta.open("rb") as fh:
+        for bloque in iter(lambda: fh.read(1 << 20), b""):
+            h.update(bloque)
+    return h.hexdigest()
+
+
+def carga(modelo: str, raiz: Path | None = None) -> dict:
+    """lee el portador de un modelo y lo sube a float64.
+
+    el fichero guarda float32, que es la dtype de origen; subirlo a
+    float64 reproduce bit a bit lo que la extracción del barrido
+    entregaba, y deja la aritmética de gauges en fp64.
+
+    args:
+        modelo: 'vitb' o 'pythia'.
+        raiz: directorio del portador; por defecto artifacts/demo.
+
+    returns:
+        dict con 'w_v' [capas, cabezas, d_h, d], 'w_o' [capas,
+        cabezas, d, d_h] en float64, y el manifiesto bajo 'meta'.
+
+    raises:
+        FileNotFoundError: si falta el portador o su manifiesto.
+    """
+    raiz = Path(raiz) if raiz is not None else RAIZ_DEFECTO
+    fichero = raiz / f"sector_vo_{modelo}.safetensors"
+    manif = raiz / f"sector_vo_{modelo}.json"
+    if not fichero.exists() or not manif.exists():
+        raise FileNotFoundError(
+            f"falta el portador de {modelo} en {raiz}; constrúyelo con "
+            f"scripts/extraer_sector_vo.py --modelo {modelo}")
+    meta = json.loads(manif.read_text())
+    t = load_file(str(fichero))
+    return {"w_v": t["w_v"].double(), "w_o": t["w_o"].double(),
+            "meta": meta}
+
+
+def verifica_manifiesto(modelo: str, raiz: Path | None = None) -> None:
+    """comprueba sha256 y formas contra el manifiesto.
+
+    args:
+        modelo: 'vitb' o 'pythia'.
+        raiz: directorio del portador.
+
+    raises:
+        RuntimeError: si el digest o alguna forma no coinciden.
+    """
+    raiz = Path(raiz) if raiz is not None else RAIZ_DEFECTO
+    fichero = raiz / f"sector_vo_{modelo}.safetensors"
+    meta = json.loads((raiz / f"sector_vo_{modelo}.json").read_text())
+    digest = _sha256(fichero)
+    if digest != meta["sha256"]:
+        raise RuntimeError(
+            f"el portador de {modelo} no es el del manifiesto: "
+            f"{digest[:16]} frente a {meta['sha256'][:16]}")
+    t = load_file(str(fichero))
+    for clave, forma in meta["formas"].items():
+        if list(t[clave].shape) != forma:
+            raise RuntimeError(
+                f"forma inesperada en {clave}: {list(t[clave].shape)} "
+                f"frente a {forma}")
+
+
+def par(portador: dict, capa: int, cabeza: int) -> tuple:
+    """(w_v, w_o) de una cabeza, en float64.
+
+    args:
+        portador: el dict que devuelve `carga`.
+        capa: índice de capa.
+        cabeza: índice de cabeza.
+
+    returns:
+        (w_v [d_h, d], w_o [d, d_h]) en float64.
+    """
+    return portador["w_v"][capa, cabeza], portador["w_o"][capa, cabeza]

requirements.txt

@@ -0,0 +1,8 @@
+# entorno del Space: la demo es álgebra sobre pesos. no necesita
+# transformers, timm ni pandas; torch en su rueda de cpu basta.
+--extra-index-url https://download.pytorch.org/whl/cpu
+gradio==6.22.0
+torch==2.11.0
+safetensors==0.6.2
+numpy
+matplotlib

src/config.py

@@ -0,0 +1,79 @@
+"""cargador único de configuraciones YAML."""
+
+import os
+from pathlib import Path
+
+import yaml
+
+
+class _Config(dict):
+    """configuración que exige valor a las rutas sin declarar."""
+
+    def __getitem__(self, clave: str) -> object:
+        """devuelve el valor de una clave, o explica que falta.
+
+        args:
+            clave: nombre de la entrada de configuración.
+
+        returns:
+            el valor asociado a la clave.
+
+        raises:
+            ValueError: si la clave existe pero está sin declarar.
+        """
+        valor = super().__getitem__(clave)
+        if valor in (None, ""):
+            raise ValueError(
+                f"«{clave}» está sin declarar: es una ruta del árbol "
+                f"propio y no se versiona. Se declara en el fichero "
+                f"«.local.yaml» que acompaña a la configuración, o por "
+                f"variable de entorno. Ver LEEME.md."
+            )
+        return valor
+
+
+def _lee(ruta: Path) -> dict:
+    """lee un yaml y devuelve su contenido, vacío si no trae nada.
+
+    args:
+        ruta: ruta al fichero .yaml.
+
+    returns:
+        diccionario con el contenido del yaml.
+    """
+    with open(ruta, encoding="utf-8") as fh:
+        return yaml.safe_load(fh) or {}
+
+
+def _expande(valor: str | None) -> str | None:
+    """expande variables de entorno en un valor de texto.
+
+    args:
+        valor: entrada de la configuración.
+
+    returns:
+        el valor con las variables de entorno ya sustituidas.
+    """
+    return os.path.expandvars(valor) if isinstance(valor, str) else valor
+
+
+def load_config(path: str) -> dict:
+    """lee un yaml y le superpone su variante local, si existe.
+
+    las rutas que apuntan al árbol propio no se versionan: las aporta
+    el fichero «<nombre>.local.yaml» que acompaña al de la
+    configuración, con prioridad sobre él.
+
+    args:
+        path: ruta al fichero .yaml.
+
+    returns:
+        configuración ya superpuesta y con las variables de entorno
+        expandidas.
+    """
+    base = Path(path)
+    cfg = _lee(base)
+    local = base.with_suffix(".local.yaml")
+    if local.exists():
+        cfg.update(_lee(local))
+    return _Config({k: _expande(v) for k, v in cfg.items()})

src/datos.py

@@ -0,0 +1,148 @@
+"""loader mínimo del val limpio de imagenet-100, solo para la
+validación end-to-end (sec. 2.4 del spec). reimplementación
+autocontenida (val-only) del loader ya usado en el paper 1.
+"""
+
+from pathlib import Path
+
+import torch
+from torch.utils.data import DataLoader, Dataset
+from torchvision import datasets, transforms
+
+_NORM = transforms.Normalize(
+    mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225))
+
+
+class _RemapEtiquetas(Dataset):
+    """envuelve un imagefolder filtrado a los wnids canónicos y
+    remapea las etiquetas al orden de la lista (0..99)."""
+
+    def __init__(self, base: datasets.ImageFolder,
+                indices: list[int], mapa: dict[int, int]) -> None:
+        self.base = base
+        self.indices = indices
+        self.mapa = mapa
+
+    def __len__(self) -> int:
+        return len(self.indices)
+
+    def __getitem__(self, i: int) -> tuple[torch.Tensor, int]:
+        img, lbl = self.base[self.indices[i]]
+        return img, self.mapa[int(lbl)]
+
+
+def val_loader_imagenet100(
+    root: str,
+    wnids_path: str,
+    image_size: int = 224,
+    batch_size: int = 128,
+    num_workers: int = 8,
+) -> DataLoader:
+    """loader del split val de imagenet-100, orden canónico cmc.
+
+    args:
+        root: carpeta con `val/<wnid>/...` (estructura imagefolder).
+        wnids_path: fichero con un synset por línea, orden canónico.
+        image_size: lado del crop final.
+        batch_size: tamaño de lote.
+        num_workers: procesos de carga.
+
+    returns:
+        dataloader sin barajar sobre el val completo.
+    """
+    wnids = [ln.strip() for ln in Path(wnids_path).read_text().splitlines()
+             if ln.strip()]
+    tfm = transforms.Compose([
+        transforms.Resize(int(image_size * 256 / 224)),
+        transforms.CenterCrop(image_size),
+        transforms.ToTensor(),
+        _NORM,
+    ])
+    base = datasets.ImageFolder(Path(root) / "val", transform=tfm)
+    wnid_a_idx = {w: i for i, w in enumerate(wnids)}
+    orig_a_nuevo = {
+        orig: wnid_a_idx[synset]
+        for synset, orig in base.class_to_idx.items()
+        if synset in wnid_a_idx
+    }
+    indices = [i for i, (_, lbl) in enumerate(base.samples)
+              if lbl in orig_a_nuevo]
+    ds = _RemapEtiquetas(base, indices, orig_a_nuevo)
+    return DataLoader(ds, batch_size=batch_size, shuffle=False,
+                      num_workers=num_workers, pin_memory=True)
+
+
+@torch.no_grad()
+def top1(modelo: torch.nn.Module, loader: DataLoader,
+         disp: str = "cuda") -> float:
+    """exactitud top-1 del modelo sobre el loader.
+
+    args:
+        modelo: en eval, sobre `disp`.
+        loader: dataloader de validación.
+        disp: dispositivo.
+
+    returns:
+        fracción de aciertos.
+    """
+    modelo.eval()
+    aciertos, total = 0, 0
+    for imgs, lbls in loader:
+        logits = modelo(imgs.to(disp, non_blocking=True))
+        pred = logits.argmax(dim=1).cpu()
+        aciertos += int((pred == lbls).sum())
+        total += int(lbls.numel())
+    return aciertos / total
+
+
+@torch.no_grad()
+def predicciones_y_aciertos(
+    modelo: torch.nn.Module,
+    loader: DataLoader,
+    disp: str = "cuda",
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """clase predicha y acierto por imagen, en el orden del loader.
+
+    las dos cosas, y no solo el acierto, porque responden a preguntas
+    distintas. el acierto sostiene el contraste pareado de mcnemar:
+    dos condiciones sobre las mismas imágenes se comparan por sus
+    discordantes. la clase predicha sostiene una afirmación más
+    fuerte: cero discordantes de mcnemar dice que ambos modelos
+    aciertan y fallan las mismas imágenes, y deja abierto que fallen
+    prediciendo clases distintas. quien quiera afirmar «predice lo
+    mismo» necesita comparar el argmax.
+
+    args:
+        modelo: en eval, sobre `disp`.
+        loader: dataloader de validación, sin barajar.
+        disp: dispositivo.
+
+    returns:
+        (pred [n] int64 con la clase predicha, ok [n] bool).
+    """
+    modelo.eval()
+    preds, oks = [], []
+    for imgs, lbls in loader:
+        pred = modelo(imgs.to(disp, non_blocking=True)).argmax(dim=1).cpu()
+        preds.append(pred)
+        oks.append(pred == lbls)
+    return torch.cat(preds), torch.cat(oks)
+
+
+@torch.no_grad()
+def aciertos_por_imagen(
+    modelo: torch.nn.Module,
+    loader: DataLoader,
+    disp: str = "cuda",
+) -> torch.Tensor:
+    """solo el vector de aciertos; envoltorio de la función anterior.
+
+    args:
+        modelo: en eval, sobre `disp`.
+        loader: dataloader de validación, sin barajar.
+        disp: dispositivo.
+
+    returns:
+        tensor bool [n], True donde la predicción acierta.
+    """
+    return predicciones_y_aciertos(modelo, loader, disp)[1]

src/gauges.py

@@ -0,0 +1,207 @@
+"""construcción de gauges valor-salida en fp64.
+
+reutiliza la construcción del paper 1 (angular-separation-vit):
+ortogonales vía qr de una gaussiana (haar), gl generales vía
+randn + escala·identidad. toda la aritmética en float64 —la lección
+del r casi-singular del paper 1 es constitutiva aquí, no una nota al
+pie.
+"""
+
+import torch
+
+
+def ortogonal(
+    dim_cabeza: int,
+    generador: torch.Generator,
+) -> torch.Tensor:
+    """muestra una rotación haar-aleatoria en o(dim_cabeza), fp64.
+
+    args:
+        dim_cabeza: d_h, tamaño de la matriz cuadrada.
+        generador: generador de torch para reproducibilidad.
+
+    returns:
+        tensor [d_h, d_h] ortogonal en float64.
+    """
+    a = torch.randn(dim_cabeza, dim_cabeza, generator=generador,
+                    dtype=torch.float64)
+    q, r = torch.linalg.qr(a)
+    # signo de la diagonal de r fija el signo de q (convención qr no
+    # es única si no se corrige); sin esto la distribución no es haar.
+    signos = torch.sign(torch.diagonal(r))
+    signos[signos == 0] = 1.0
+    return q * signos
+
+
+def gl_general(
+    dim_cabeza: int,
+    escala: float,
+    generador: torch.Generator,
+) -> torch.Tensor:
+    """muestra r = randn + escala·i en gl(dim_cabeza), fp64.
+
+    escala alta acerca r a un múltiplo escalar de la identidad (gauge
+    débil, bien condicionado); escala baja lo aleja (gauge fuerte,
+    condición alta, la cola que la nota espera que cuantice mal).
+
+    args:
+        dim_cabeza: d_h.
+        escala: coeficiente de la identidad.
+        generador: generador de torch para reproducibilidad.
+
+    returns:
+        tensor [d_h, d_h] en float64, invertible con probabilidad 1.
+    """
+    ident = torch.eye(dim_cabeza, dtype=torch.float64)
+    ruido = torch.randn(dim_cabeza, dim_cabeza, generator=generador,
+                        dtype=torch.float64)
+    return ruido + escala * ident
+
+
+def aplica_gauge(
+    w_v_h: torch.Tensor,
+    w_o_h: torch.Tensor,
+    r: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """transforma (w_v^(h), w_o^(h)) bajo el gauge r, sin tocar el circuito.
+
+    convención: w_v^(h) es [d_h, d] (filas de valor), w_o^(h) es
+    [d, d_h] (columnas de salida). w_v <- r^t w_v, w_o <- w_o r^-t;
+    el circuito m = w_o w_v es invariante para cualquier r en
+    gl(d_h) (no solo ortogonal): m' = (w_o r^-t)(r^t w_v)
+    = w_o (r^-t r^t) w_v = w_o w_v, ya que r^-t r^t = (r^t)^-1 r^t = i.
+
+    args:
+        w_v_h: tensor [d_h, d] en float64.
+        w_o_h: tensor [d, d_h] en float64.
+        r: gauge [d_h, d_h] en float64, invertible.
+
+    returns:
+        (w_v_h transformado, w_o_h transformado), misma forma.
+    """
+    r_inv_t = torch.linalg.inv(r).transpose(-2, -1)
+    return r.transpose(-2, -1) @ w_v_h, w_o_h @ r_inv_t
+
+
+def gl_condicionado(
+    dim_cabeza: int,
+    kappa: float,
+    generador: torch.Generator,
+) -> torch.Tensor:
+    """muestra r en gl(dim_cabeza) con número de condición kappa exacto.
+
+    se toma una gaussiana, se le extrae la svd y se sustituye su
+    espectro por uno geométrico entre 1 y kappa: las bases quedan
+    haar-aleatorias y el condicionamiento pasa a ser la variable
+    controlada, en vez de una consecuencia de la escala. la
+    alternativa declarada y no elegida es el espectro de un solo
+    outlier (sigma_1 = kappa, resto 1).
+
+    kappa = 1 devuelve una matriz ortogonal, que es el ancla del
+    suelo e_0 del ajuste.
+
+    args:
+        dim_cabeza: d_h.
+        kappa: número de condición objetivo, >= 1.
+        generador: generador de torch para reproducibilidad.
+
+    returns:
+        tensor [d_h, d_h] en float64 con cond(r) = kappa.
+
+    raises:
+        ValueError: si kappa < 1.
+    """
+    if kappa < 1.0:
+        raise ValueError(f"kappa debe ser >= 1: {kappa}")
+    a = torch.randn(dim_cabeza, dim_cabeza, generator=generador,
+                    dtype=torch.float64)
+    u, _, vh = torch.linalg.svd(a)
+    # espectro geométrico descendente de kappa a 1; el cociente entre
+    # el mayor y el menor es kappa por construcción.
+    exponentes = torch.linspace(1.0, 0.0, dim_cabeza, dtype=torch.float64)
+    s = torch.pow(torch.tensor(kappa, dtype=torch.float64), exponentes)
+    return (u * s) @ vh
+
+
+def producto_normas(
+    w_v_h: torch.Tensor,
+    w_o_h: torch.Tensor,
+    r: torch.Tensor | None = None,
+) -> float:
+    """p(r) = ||r^t w_v||_f ||w_o r^-t||_f / (||w_v||_f ||w_o||_f).
+
+    la variable de la ley del producto: el inflado del error de
+    cuantización a primer orden. vale 1 en la identidad y 1 en toda
+    la clase conforme ortogonal {c·q}, porque ||w_v (cq)|| escala por
+    c y ||(cq)^-1 w_o|| por 1/c.
+
+    args:
+        w_v_h: tensor [d_h, d] en float64, sin gauge.
+        w_o_h: tensor [d, d_h] en float64, sin gauge.
+        r: gauge [d_h, d_h]; None denota la identidad (p = 1).
+
+    returns:
+        p(r), escalar float.
+    """
+    base = float(w_v_h.norm() * w_o_h.norm())
+    if r is None:
+        return 1.0
+    w_v_g, w_o_g = aplica_gauge(w_v_h, w_o_h, r)
+    return float(w_v_g.norm() * w_o_g.norm()) / base
+
+
+def gauge_balanceado(
+    w_v_h: torch.Tensor,
+    w_o_h: torch.Tensor,
+    tol_rango: float = 1e-10,
+) -> tuple[torch.Tensor, float]:
+    """el gauge que lleva el par a su factorización balanceada.
+
+    el punto balanceado del paper 1 (lema del punto balanceado)
+    minimiza ||w_v r||_f^2 + ||r^-1 w_o||_f^2 sobre la órbita a
+    circuito fijo, y se construye por svd del circuito: con
+    m = w_o w_v = u s v^t de rango d_h, el par balanceado es
+    a = u s^{1/2} y b = s^{1/2} v^t.
+
+    el enlace con esta nota es exacto: ||a||_f ||b||_f = tr(s) =
+    ||m||_*, que es el mínimo del producto de normas sobre la órbita
+    entera (desigualdad de la norma nuclear, ||m||_* <= ||a||_f
+    ||b||_f para toda factorización m = ab). el punto balanceado es
+    entonces el óptimo que la ley del producto predice, y es un gauge
+    NO ortogonal en general: el contraejemplo medido a «la
+    restricción ortogonal es necesaria».
+
+    convención de este repo: m = w_o w_v, y el gauge actúa como
+    w_v <- r^t w_v, w_o <- w_o r^-t. con s = r^t se pide
+    w_o s^-1 = a y s w_v = b.
+
+    args:
+        w_v_h: tensor [d_h, d] en float64.
+        w_o_h: tensor [d, d_h] en float64.
+        tol_rango: valor singular mínimo relativo para declarar el
+            circuito de rango completo.
+
+    returns:
+        (r [d_h, d_h] en float64, p_balanceado), donde p_balanceado
+        es ||m||_* / (||w_v||_f ||w_o||_f) <= 1, el valor de la ley
+        del producto en ese punto.
+
+    raises:
+        ValueError: si el circuito no tiene rango d_h, donde el punto
+            balanceado no es alcanzable por un gauge de gl(d_h).
+    """
+    d_h = w_v_h.shape[0]
+    m = w_o_h @ w_v_h
+    u, s, vh = torch.linalg.svd(m, full_matrices=False)
+    u, s, vh = u[:, :d_h], s[:d_h], vh[:d_h]
+    if float(s[-1]) <= tol_rango * float(s[0]):
+        raise ValueError(
+            f"circuito de rango deficiente: s_min/s_max = "
+            f"{float(s[-1]) / float(s[0]):.2e} <= {tol_rango:.0e}")
+    raiz = s.sqrt()
+    a_bal = u * raiz            # [d, d_h]
+    # s^-1 = w_o^+ a_bal; r = s^t = (s^-1)^-t
+    s_inv = torch.linalg.pinv(w_o_h) @ a_bal
+    r = torch.linalg.inv(s_inv).transpose(-2, -1)
+    p_bal = float(s.sum()) / float(w_v_h.norm() * w_o_h.norm())
+    return r, p_bal

src/metrics.py

@@ -0,0 +1,42 @@
+"""error relativo del circuito ov, recompuesto siempre en fp64.
+
+el circuito m = w_o^(h) w_v^(h) es la cantidad gauge-invariante (ver
+paper 1, sec:gauge). la nota mide cuánto se aleja la versión
+cuantizada-y-recompuesta de la referencia exacta.
+"""
+
+import torch
+
+
+def circuito(w_v_h: torch.Tensor, w_o_h: torch.Tensor) -> torch.Tensor:
+    """circuito m = w_o^(h) w_v^(h), [d, d].
+
+    args:
+        w_v_h: tensor [d_h, d].
+        w_o_h: tensor [d, d_h].
+
+    returns:
+        tensor [d, d] en la dtype de entrada.
+    """
+    return w_o_h @ w_v_h
+
+
+def error_relativo(
+    w_v_hat: torch.Tensor,
+    w_o_hat: torch.Tensor,
+    m_referencia: torch.Tensor,
+) -> float:
+    """e = ||m_hat - m_referencia||_f / ||m_referencia||_f, en fp64.
+
+    args:
+        w_v_hat: w_v^(h) tras gauge y cuantización, [d_h, d].
+        w_o_hat: w_o^(h) tras gauge y cuantización, [d, d_h].
+        m_referencia: circuito exacto de referencia (sin gauge, sin
+            cuantizar), [d, d], en float64.
+
+    returns:
+        error relativo de frobenius, escalar float.
+    """
+    m_hat = circuito(w_v_hat.double(), w_o_hat.double())
+    return float(
+        (m_hat - m_referencia).norm() / m_referencia.norm())

src/quantizer.py

@@ -0,0 +1,42 @@
+"""cuantizador rtn simétrico por canal, con des-cuantización.
+
+round-to-nearest puro: sin gptq, sin rotaciones aprendidas, sin
+calibración con datos. la simplicidad es deliberada —aísla la
+variable de interés (el gauge), la nota no compite con métodos de
+cuantización, los caracteriza (ver spec, sec. 2.2).
+"""
+
+import torch
+
+_QMAX = {4: 7, 8: 127}  # 2^(bits-1) - 1, rango simétrico con signo
+
+
+def rtn_cuantiza_descuantiza(
+    w: torch.Tensor,
+    bits: int,
+) -> torch.Tensor:
+    """cuantiza y descuantiza w por canal (fila), simétrico, rtn.
+
+    cada fila obtiene su propia escala —el "canal" es la fila, la
+    convención estándar para pesos [salida, entrada]—. la aritmética
+    es en la dtype de entrada (se espera float64, el suelo numérico
+    del resto de la nota); no hay almacenamiento entero real, se
+    simula la rejilla de cuantización.
+
+    args:
+        w: tensor [filas, columnas].
+        bits: 4 u 8.
+
+    returns:
+        tensor de la misma forma y dtype, redondeado a la rejilla de
+        `bits` y devuelto a escala real (des-cuantizado).
+    """
+    if bits not in _QMAX:
+        raise ValueError(f"bits no soportado: {bits}")
+    qmax = _QMAX[bits]
+    escala = w.abs().amax(dim=-1, keepdim=True) / qmax
+    # fila nula: escala 0/0 -> nan; se fija a 1 (la fila cuantizada es
+    # 0 de todas formas, la escala no importa).
+    escala = torch.where(escala > 0, escala, torch.ones_like(escala))
+    q = torch.round(w / escala).clamp(min=-qmax, max=qmax)
+    return q * escala

src/reconstruccion.py

@@ -0,0 +1,136 @@
+"""reconstruye un gauge concreto del barrido, re-jugando la misma
+secuencia de muestreo que ``scripts/sweep.py::barre_capa`` con el
+mismo generador y semilla. necesario para la validación end-to-end
+(sec. 2.4 del spec): identifica el mejor/peor gauge MUESTREADO por el
+barrido y lo reconstruye exactamente, sin persistir cada r en el csv.
+"""
+
+import torch
+
+from src.gauges import gl_general, ortogonal
+
+K_MUESTRAS = 32
+ESCALAS_GL = [2.0, 8.0, 32.0]
+
+
+def reconstruye_r(
+    capa_objetivo: int,
+    cabeza_objetivo: int,
+    regimen_objetivo: str,
+    muestra_objetivo: int,
+    n_cabezas: int,
+    dim_cabeza: int,
+    n_capas_previas_por_capa: dict[int, int] | None = None,
+    semilla: int = 0,
+    escala_objetivo: float | None = None,
+) -> torch.Tensor:
+    """re-juega el muestreo hasta dar con el r exacto pedido.
+
+    reproduce el orden de ``barre_capa``: por capa, primero los k
+    gauges compartidos (orto_comp), luego por cabeza los k orto_ph
+    seguidos de los k·3 gl_e (por escala). se recorre capa a capa
+    desde 0 hasta la objetivo, consumiendo el generador exactamente
+    como el barrido original, y se descartan los r que no hacen falta.
+
+    args:
+        capa_objetivo: capa del gauge buscado.
+        cabeza_objetivo: cabeza del gauge buscado (ignorada si
+            regimen_objetivo es 'orto_comp', que es por-capa).
+        regimen_objetivo: 'orto_ph', 'orto_comp' o 'gl_e'.
+        muestra_objetivo: índice de muestra (0..31).
+        n_cabezas: cabezas por capa del modelo (constante).
+        dim_cabeza: d_h.
+        n_capas_previas_por_capa: sin uso (todas las capas del modelo
+            tienen el mismo n_cabezas); se mantiene por si algún
+            modelo futuro varía cabezas por capa.
+        semilla: semilla global del barrido (por defecto la del
+            barrido real, ver scripts/sweep.py --semilla).
+        escala_objetivo: escala de gl_e buscada (solo si
+            regimen_objetivo == 'gl_e').
+
+    returns:
+        tensor [d_h, d_h] en float64, idéntico al usado en el barrido.
+    """
+    gen = torch.Generator().manual_seed(semilla)
+    for capa in range(capa_objetivo + 1):
+        compartidos = [ortogonal(dim_cabeza, gen)
+                      for _ in range(K_MUESTRAS)]
+        if capa == capa_objetivo and regimen_objetivo == "orto_comp":
+            return compartidos[muestra_objetivo]
+        ultima_capa = capa == capa_objetivo
+        for h in range(n_cabezas):
+            orto_ph = [ortogonal(dim_cabeza, gen)
+                      for _ in range(K_MUESTRAS)]
+            if (ultima_capa and h == cabeza_objetivo
+                    and regimen_objetivo == "orto_ph"):
+                return orto_ph[muestra_objetivo]
+            for escala in ESCALAS_GL:
+                gl = [gl_general(dim_cabeza, escala, gen)
+                     for _ in range(K_MUESTRAS)]
+                if (ultima_capa and h == cabeza_objetivo
+                        and regimen_objetivo == "gl_e"
+                        and escala == escala_objetivo):
+                    return gl[muestra_objetivo]
+    raise ValueError(
+        f"no se encontró capa={capa_objetivo} cabeza={cabeza_objetivo} "
+        f"regimen={regimen_objetivo} muestra={muestra_objetivo}")
+
+
+def reconstruye_muchos(
+    objetivos: set[tuple],
+    n_capas: int,
+    n_cabezas: int,
+    dim_cabeza: int,
+    semilla: int = 0,
+) -> dict[tuple, torch.Tensor]:
+    """como `reconstruye_r`, pero en una sola pasada para muchos r's.
+
+    evita rejugar la secuencia desde cero por cada objetivo (o(n) en
+    vez de o(n²)): recorre el modelo entero una vez y captura cada r
+    pedido al pasar por su punto exacto.
+
+    args:
+        objetivos: conjunto de tuplas
+            (capa, cabeza, regimen, muestra, escala) — escala es
+            ``None`` salvo para regimen='gl_e'. en 'orto_comp' la r es
+            por capa y la misma para todas las cabezas, pero la clave
+            exige el índice real de la cabeza: se registra una entrada
+            por cabeza, no un comodín.
+        n_capas: capas totales del modelo (recorre 0..n_capas-1).
+        n_cabezas: cabezas por capa.
+        dim_cabeza: d_h.
+        semilla: semilla global del barrido.
+
+    returns:
+        dict objetivo -> tensor [d_h, d_h] en float64, con todas las
+        claves de `objetivos` presentes (lanza si falta alguna).
+    """
+    restantes = set(objetivos)
+    hallados: dict[tuple, torch.Tensor] = {}
+    gen = torch.Generator().manual_seed(semilla)
+    for capa in range(n_capas):
+        compartidos = [ortogonal(dim_cabeza, gen)
+                      for _ in range(K_MUESTRAS)]
+        for m, r in enumerate(compartidos):
+            for cab in range(n_cabezas):
+                clave = (capa, cab, "orto_comp", m, None)
+                if clave in restantes:
+                    hallados[clave] = r
+        for h in range(n_cabezas):
+            orto_ph = [ortogonal(dim_cabeza, gen)
+                      for _ in range(K_MUESTRAS)]
+            for m, r in enumerate(orto_ph):
+                clave = (capa, h, "orto_ph", m, None)
+                if clave in restantes:
+                    hallados[clave] = r
+            for escala in ESCALAS_GL:
+                gl = [gl_general(dim_cabeza, escala, gen)
+                     for _ in range(K_MUESTRAS)]
+                for m, r in enumerate(gl):
+                    clave = (capa, h, "gl_e", m, escala)
+                    if clave in restantes:
+                        hallados[clave] = r
+    faltan = restantes - set(hallados)
+    if faltan:
+        raise ValueError(f"objetivos no encontrados: {faltan}")
+    return hallados

src/weights.py

@@ -0,0 +1,241 @@
+"""carga de modelos y extracción por-cabeza de (w_v, w_o).
+
+reimplementación autocontenida, para este repo, de la extracción ya
+verificada en el paper 1 (angular-separation-vit): gpt-neox fusiona
+q,k,v por cabeza intercalado (``query_key_value``); timm concatena
+[q,k,v] por bloque y v ocupa el último tercio (``qkv``). convención
+de forma en todo el repo: w_v^(h) es [d_h, d], w_o^(h) es [d, d_h].
+"""
+
+import torch
+
+
+def cargar_pythia(
+    model_id: str = "EleutherAI/pythia-410m",
+    dtype: torch.dtype = torch.float32,
+):
+    """carga pythia-410m y verifica su anatomía contra el config real.
+
+    args:
+        model_id: identificador del modelo en hugging face hub.
+        dtype: precisión de carga.
+
+    returns:
+        el modelo en modo evaluación.
+    """
+    from transformers import AutoModelForCausalLM
+
+    modelo = AutoModelForCausalLM.from_pretrained(
+        model_id, dtype=dtype, attn_implementation="eager")
+    modelo.eval()
+    cfg = modelo.config
+    dim_cabeza = cfg.hidden_size // cfg.num_attention_heads
+    assert dim_cabeza == 64, f"dim_cabeza inesperada: {dim_cabeza}"
+    assert cfg.num_attention_heads == 16, "num_attention_heads != 16"
+    assert cfg.hidden_size == 1024, "hidden_size != 1024"
+    assert len(modelo.gpt_neox.layers) == 24, "num capas != 24"
+    return modelo
+
+
+@torch.no_grad()
+def w_v_w_o_pythia(
+    modelo,
+    capa: int,
+    n_cabezas: int = 16,
+    dim_cabeza: int = 64,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """(w_v, w_o) por cabeza de una capa de pythia, en float64.
+
+    query_key_value fusiona q, k y v por cabeza: cada cabeza ocupa
+    ``3*dim_cabeza`` filas contiguas ``[q_h|k_h|v_h]``; v_h es el
+    último tercio. dense es la proyección de salida (columnas por
+    cabeza).
+
+    args:
+        modelo: modelo gpt-neox (pythia) cargado.
+        capa: índice de capa.
+        n_cabezas: cabezas h.
+        dim_cabeza: d_h.
+
+    returns:
+        (w_v [h, d_h, d], w_o [h, d, d_h]), float64.
+    """
+    attn = modelo.gpt_neox.layers[capa].attention
+    w_qkv = attn.query_key_value.weight  # [3d, d]
+    w_dense = attn.dense.weight          # [d, d]
+    w_v, w_o = [], []
+    for h in range(n_cabezas):
+        base = h * 3 * dim_cabeza + 2 * dim_cabeza
+        w_v.append(w_qkv[base:base + dim_cabeza, :].double())
+        w_o.append(w_dense[:, h * dim_cabeza:(h + 1) * dim_cabeza]
+                   .double())
+    return torch.stack(w_v), torch.stack(w_o)
+
+
+def cargar_vitb(
+    ckpt_path: str,
+    model_name: str = "vit_base_patch16_224",
+    num_classes: int = 100,
+    img_size: int = 224,
+):
+    """carga la columna vit-b con los pesos de un checkpoint de a.
+
+    args:
+        ckpt_path: ruta al checkpoint (.pt con clave 'model',
+            prefijo 'backbone.' en las claves).
+        model_name: identificador timm de la columna.
+        num_classes: clases de la cabeza.
+        img_size: resolución de entrada.
+
+    returns:
+        el vit interno de timm (el que expone .blocks), en eval.
+    """
+    import timm
+
+    modelo = timm.create_model(
+        model_name, pretrained=False, num_classes=num_classes,
+        img_size=img_size)
+    blob = torch.load(ckpt_path, map_location="cpu", weights_only=False)
+    # el checkpoint viene de un wrapper HeadProjections del paper 1:
+    # las claves llevan 'backbone.model.' antes de la state_dict plana
+    # de timm ('backbone.' del checkpoint de entrenamiento, 'model.'
+    # del atributo submódulo del wrapper).
+    sd = {k.replace("backbone.model.", "", 1): v
+          for k, v in blob["model"].items()}
+    modelo.load_state_dict(sd)
+    return modelo.eval()
+
+
+@torch.no_grad()
+def w_v_w_o_vitb(
+    modelo,
+    capa: int,
+    n_cabezas: int = 12,
+    dim_cabeza: int = 64,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """(w_v, w_o) por cabeza de una capa de vit-b, en float64.
+
+    en timm el qkv concatena [q, k, v] por bloque; v ocupa el último
+    tercio y se reordena por cabeza. proj es la proyección de salida.
+
+    args:
+        modelo: el vit interno de timm.
+        capa: índice de capa.
+        n_cabezas: cabezas h.
+        dim_cabeza: d_h.
+
+    returns:
+        (w_v [h, d_h, d], w_o [h, d, d_h]), float64.
+    """
+    attn = modelo.blocks[capa].attn
+    w_qkv = attn.qkv.weight    # [3d, d]
+    w_proj = attn.proj.weight  # [d, d]
+    base_v = 2 * w_qkv.shape[1]
+    w_v, w_o = [], []
+    for h in range(n_cabezas):
+        fil = slice(base_v + h * dim_cabeza, base_v + (h + 1) * dim_cabeza)
+        col = slice(h * dim_cabeza, (h + 1) * dim_cabeza)
+        w_v.append(w_qkv[fil, :].double())
+        w_o.append(w_proj[:, col].double())
+    return torch.stack(w_v), torch.stack(w_o)
+
+
+@torch.no_grad()
+def escribe_v_o_vitb(
+    modelo,
+    capa: int,
+    h: int,
+    w_v_h: torch.Tensor,
+    w_o_h: torch.Tensor,
+    dim_cabeza: int = 64,
+) -> None:
+    """escribe (w_v, w_o) de una cabeza de vuelta en el modelo, in situ.
+
+    inversa de `w_v_w_o_vitb` para una sola cabeza: usada por la
+    validación end-to-end para materializar un modelo con los pesos
+    ya gaugeados-y-cuantizados antes del forward real.
+
+    args:
+        modelo: el vit interno de timm, modificado in situ.
+        capa: índice de capa.
+        h: índice de cabeza.
+        w_v_h: tensor [d_h, d] (cualquier dtype, se castea al del
+            modelo).
+        w_o_h: tensor [d, d_h].
+        dim_cabeza: d_h.
+    """
+    attn = modelo.blocks[capa].attn
+    w_qkv = attn.qkv.weight
+    w_proj = attn.proj.weight
+    base_v = 2 * w_qkv.shape[1]
+    fil = slice(base_v + h * dim_cabeza, base_v + (h + 1) * dim_cabeza)
+    col = slice(h * dim_cabeza, (h + 1) * dim_cabeza)
+    w_qkv[fil, :] = w_v_h.to(w_qkv.dtype)
+    w_proj[:, col] = w_o_h.to(w_proj.dtype)
+
+
+@torch.no_grad()
+def b_v_vitb(
+    modelo,
+    capa: int,
+    n_cabezas: int = 12,
+    dim_cabeza: int = 64,
+) -> torch.Tensor | None:
+    """sesgo de valor por cabeza de una capa de vit-b, en float64.
+
+    el sesgo de valor entra en la invariancia de gauge: como
+    v = x w_v^t + b_v, la compensación de w_o exige que b_v gire igual
+    que la weight (b_v <- r^t b_v). omitirlo en una columna con
+    qkv_bias rompe la invariancia, y el forward deja de medir el
+    gauge para medir otro modelo.
+
+    args:
+        modelo: el vit interno de timm.
+        capa: índice de capa.
+        n_cabezas: cabezas h.
+        dim_cabeza: d_h.
+
+    returns:
+        tensor [h, d_h] en float64, o None si la columna no lleva
+        qkv_bias.
+    """
+    attn = modelo.blocks[capa].attn
+    if attn.qkv.bias is None:
+        return None
+    b_qkv = attn.qkv.bias
+    base_v = 2 * (b_qkv.shape[0] // 3)
+    return torch.stack([
+        b_qkv[base_v + h * dim_cabeza:
+              base_v + (h + 1) * dim_cabeza].double()
+        for h in range(n_cabezas)])
+
+
+@torch.no_grad()
+def escribe_b_v_vitb(
+    modelo,
+    capa: int,
+    h: int,
+    b_v_h: torch.Tensor,
+    dim_cabeza: int = 64,
+) -> None:
+    """escribe el sesgo de valor de una cabeza, in situ.
+
+    inversa de `b_v_vitb` para una sola cabeza. el sesgo no se
+    cuantiza: el objeto cuantizado de la nota es el par de weights
+    (w_v, w_o), y el sesgo solo viaja para que el gauge siga siendo
+    un cambio de coordenadas y no un cambio de función.
+
+    args:
+        modelo: el vit interno de timm, modificado in situ.
+        capa: índice de capa.
+        h: índice de cabeza.
+        b_v_h: tensor [d_h], se castea al dtype del modelo.
+        dim_cabeza: d_h.
+    """
+    attn = modelo.blocks[capa].attn
+    if attn.qkv.bias is None:
+        raise ValueError("la columna no lleva qkv_bias")
+    b_qkv = attn.qkv.bias
+    base_v = 2 * (b_qkv.shape[0] // 3)
+    fil = slice(base_v + h * dim_cabeza, base_v + (h + 1) * dim_cabeza)
+    b_qkv[fil] = b_v_h.to(b_qkv.dtype)