Re-upload project files (code + data)

Re-uploaded all project files, including source code and datasets.
Ensured consistency between data, preprocessing, and model components.

.gitattributes

@@ -39,3 +39,5 @@ artifacts/samples_prof_gpu0_seed1_perfect.png filter=lfs diff=lfs merge=lfs -tex
 artifacts/samples_prof_gpu0_seed1_symbol.png filter=lfs diff=lfs merge=lfs -text
 artifacts/srtrbm_filters.png filter=lfs diff=lfs merge=lfs -text
 stan.dgts filter=lfs diff=lfs merge=lfs -text
+artifacts/samples_gpu0_seed1_refined.png filter=lfs diff=lfs merge=lfs -text
+artifacts/samples_prof_gpu0_seed1_refined.png filter=lfs diff=lfs merge=lfs -text

analysis/AutoGPU.py

@@ -0,0 +1,50 @@
+from pynvml import *
+import time
+
+
+class GPUEnergyTracker:
+    """
+    GPU energy monitor using NVIDIA NVML.
+
+    Measures instantaneous power and integrates
+    it over time to estimate total GPU energy
+    consumption.
+    Units
+    Power  : Watts
+    Energy : Joules
+    """
+
+    def __init__(self, gpu_index=0):
+        nvmlInit()
+
+        self.handle = nvmlDeviceGetHandleByIndex(gpu_index)
+
+        self.energy_joules = 0.0
+
+        self.last_time = time.time()
+
+        self.last_power = self._read_power()
+
+    def _read_power(self):
+        power_mw = nvmlDeviceGetPowerUsage(self.handle)
+
+        return power_mw / 1000.0
+
+    def step(self):
+        current_time = time.time()
+
+        power = self._read_power()
+
+        dt = current_time - self.last_time
+
+        # trapezoidal integration
+        self.energy_joules += 0.5 * (self.last_power + power) * dt
+
+        self.last_power = power
+        self.last_time = current_time
+
+    def total_energy(self):
+        return self.energy_joules
+
+    def current_power(self):
+        return self.last_power

analysis/__init__.py

@@ -0,0 +1,7 @@
+from analysis.AutoGPU import (
+    GPUEnergyTracker
+)
+
+__all__ = [
+    "GPUEnergyTracker",
+]

artifacts/llm_output_gpu0_seed1.json

@@ -0,0 +1,20 @@
+{
+  "regime": "learning",
+  "phase": "ordered",
+  "failures": [],
+  "scores": {
+    "temperature": 0.46,
+    "gibbs": 0.43
+  },
+  "risk": {
+    "stagnation": 0.05,
+    "collapse": 0.0,
+    "over_ordering": 0.3
+  },
+  "actions": {},
+  "confidence": 0.2719435542821884,
+  "analysis": "High image_similarity (0.8597) and visually preserved digit structure indicate modes are retained and refinement matches the reference manifold. Learning_signal (0.328) and heating/positive trend slopes show continued parameter change, so the system is still learning. Entropy and diversity are low (entropy 0.3107 overall, current entropy 0.1565; diversity 0.2076), and mixing is slow (mcmc_tau_int 27.65), but per the strict rules these do not imply collapse when structural similarity is high. Beta is high (current beta 4.386) and outputs are structured → ordered phase. Overall classification: the system is in a learning regime with ordered phase. Epistemic note: confidence is limited by conflicting signals (very high similarity and active learning vs low diversity and poor mixing); therefore confidence is substantial but constrained by those contradictory indicators. [OVERRIDDEN: high structural similarity]",
+  "reason": "json|low_confidence_scaled",
+  "evidence": 0.2719435542821884,
+  "llm_conf_raw": 0.75
+}

artifacts/run.log

@@ -0,0 +1,212 @@
+Training: 100%|██████████████████████████████████████| 400/400 [04:51<00:00,  1.37it/s, T=0.923, flip=0.055, beta=4.386]
+
+[GPU 0] Running AIS...
+✔ AIS finished in 96.37 seconds
+coefficient (kappa): 784
+coefficient (kappa): 784
+
+[LLM] Start | B=1200 | T=0.9234
+[Debug] ESS=2.87 | k=13 | deltaE_band=[0.00,2.00] | in_band=111 | selected=13
+[Debug] d_model=0.9904, d_llm=1.0000
+[Step] Sample=101 | REJECT | d_model=0.990 | d_total=2.280 | p=0.102
+[Debug] d_model=1.0123, d_llm=0.0065
+[Step] Sample=542 | REJECT | d_model=1.012 | d_total=1.021 | p=0.360
+[Debug] d_model=1.0161, d_llm=0.7791
+[Step] Sample=922 | REJECT | d_model=1.016 | d_total=2.021 | p=0.133
+[Debug] d_model=1.0165, d_llm=-1.0241
+[Step] Sample=677 | ACCEPT | d_model=1.017 | d_total=-0.305 | p=1.000
+[Debug] d_model=0.9680, d_llm=-0.9760
+[Step] Sample=1044 | ACCEPT | d_model=0.968 | d_total=-0.291 | p=1.000
+[Debug] d_model=1.0358, d_llm=1.0429
+[Step] Sample=1052 | ACCEPT | d_model=1.036 | d_total=2.381 | p=0.092
+[Debug] d_model=1.0585, d_llm=-1.0636
+[Step] Sample=15 | ACCEPT | d_model=1.059 | d_total=-0.314 | p=1.000
+[Debug] d_model=1.0721, d_llm=0.0744
+[Step] Sample=385 | REJECT | d_model=1.072 | d_total=1.168 | p=0.311
+[Debug] d_model=1.0757, d_llm=1.0757
+[Step] Sample=641 | REJECT | d_model=1.076 | d_total=2.463 | p=0.085
+[Debug] d_model=1.0759, d_llm=-1.0733
+[Step] Sample=404 | ACCEPT | d_model=1.076 | d_total=-0.309 | p=1.000
+[Debug] d_model=1.0795, d_llm=-0.3774
+[Step] Sample=813 | REJECT | d_model=1.079 | d_total=0.593 | p=0.553
+[Debug] d_model=1.0859, d_llm=1.0780
+[Step] Sample=636 | REJECT | d_model=1.086 | d_total=2.477 | p=0.084
+[Debug] d_model=0.9026, d_llm=-0.8987
+[Step] Sample=218 | ACCEPT | d_model=0.903 | d_total=-0.257 | p=1.000
+
+[LLM Summary]
+LLM used  : 13/1200
+Accepted  : 6/13
+T         : 0.9234
+[LLM Done]
+
+
+Physical Refinement Diagnostics: 0.5296437740325928
+Binder cumulant (1): 0.6467613577842712
+Chi improvement: -0.12803667783737183
+Binder improvement: 0.0007802844047546387
+
+[LLM] Start | B=1200 | T=0.9234
+[Debug] ESS=1.88 | k=13 | deltaE_band=[0.00,2.00] | in_band=100 | selected=13
+[Debug] d_model=0.9798, d_llm=0.9763
+[Step] Sample=73 | REJECT | d_model=0.980 | d_total=2.239 | p=0.107
+[Debug] d_model=1.0320, d_llm=-0.7650
+[Step] Sample=749 | ACCEPT | d_model=1.032 | d_total=0.045 | p=0.956
+[Debug] d_model=0.9327, d_llm=0.9304
+[Step] Sample=758 | REJECT | d_model=0.933 | d_total=2.133 | p=0.118
+[Debug] d_model=1.0745, d_llm=-0.8507
+[Step] Sample=991 | ACCEPT | d_model=1.075 | d_total=-0.023 | p=1.000
+[Debug] d_model=0.9232, d_llm=-0.9211
+[Step] Sample=68 | ACCEPT | d_model=0.923 | d_total=-0.265 | p=1.000
+[Debug] d_model=0.9205, d_llm=0.9206
+[Step] Sample=213 | REJECT | d_model=0.921 | d_total=2.108 | p=0.121
+[Debug] d_model=0.9111, d_llm=0.9135
+[Step] Sample=970 | REJECT | d_model=0.911 | d_total=2.090 | p=0.124
+[Debug] d_model=0.9092, d_llm=0.9139
+[Step] Sample=76 | REJECT | d_model=0.909 | d_total=2.088 | p=0.124
+[Debug] d_model=0.8912, d_llm=-0.8984
+[Step] Sample=368 | ACCEPT | d_model=0.891 | d_total=-0.268 | p=1.000
+[Debug] d_model=1.1118, d_llm=1.1166
+[Step] Sample=875 | ACCEPT | d_model=1.112 | d_total=2.552 | p=0.078
+[Debug] d_model=1.1135, d_llm=-1.1141
+[Step] Sample=533 | ACCEPT | d_model=1.113 | d_total=-0.324 | p=1.000
+[Debug] d_model=1.1337, d_llm=1.1295
+[Step] Sample=597 | REJECT | d_model=1.134 | d_total=2.591 | p=0.075
+[Debug] d_model=1.1339, d_llm=1.1250
+[Step] Sample=696 | REJECT | d_model=1.134 | d_total=2.585 | p=0.075
+
+[LLM Summary]
+LLM used  : 13/1200
+Accepted  : 6/13
+T         : 0.9234
+[LLM Done]
+
+
+Secondary magnetic susceptibility: 0.5303375720977783
+Binder cumulant (2): 0.6477672457695007
+Chi improvement: -0.12793707847595215
+Binder improvement: 0.0005515813827514648
+
+Running energy analysis ↓
+
+
+Running diagnostics with the following calculations ↙
+
+✔ Energy distribution finished in 149.96 seconds
+✔ Energy landscape extremes finished in 0.06 seconds
+✔ Phase diagram finished in 1.17 seconds
+✔ RBM filters finished in 0.06 seconds
+✔ Sample quality metrics finished in 12.30 seconds
+
+Diagnostics completed in 164.88 seconds
+
+GPU Energy Used : 41135.66 Joules
+
+Device: cuda
+, ↘
+
+samples_gpu0_seed1_refined.png → Patches: torch.Size([1200, 1, 28, 28])
+samples_gpu0_seed1_refined.png → Avg MSE: 0.1186484
+Saved: samples_gpu0_seed1_perfect.png
+
+Device: cuda
+, ↘
+
+samples_prof_gpu0_seed1_refined.png → Patches: torch.Size([1200, 1, 28, 28])
+samples_prof_gpu0_seed1_refined.png → Avg MSE: 0.11937518
+Saved: samples_prof_gpu0_seed1_perfect.png
+
+DEBUG perfect_img_path: samples_prof_gpu0_seed1_perfect.png
+[IMAGE LPIPS] 0.14028222858905792
+
+[LLM RAW OUTPUT]
+ High image_similarity (0.86) and visibly preserved, sharp digit structure indicate the refinement preserves the reference manifold — a strong positive signal that modes are structurally captured. Diversity and entropy are low, and mixing (tau_int) is slow, but by the provided rules those alone do not imply failure. The system shows an active learning signal, positive temperature and beta trends, and heating — so weights appear to still be changing. Low entropy combined with high beta and high structural fidelity point to an ordered output regime rather than critical or disordered. Collapse risk is minimal because structural similarity and reconstruction quality are high, though low diversity raises a moderate risk of over-ordering (reduced micro-mode variety). Confidence is bounded by the evidence: similarity and learning flags are strong, but diversity/mixing provide limited contradictory information, so confidence is substantial but not maximal.
+
+{
+"analysis": "High image_similarity (0.8597) and visually preserved digit structure indicate modes are retained and refinement matches the reference manifold. Learning_signal (0.328) and heating/positive trend slopes show continued parameter change, so the system is still learning. Entropy and diversity are low (entropy 0.3107 overall, current entropy 0.1565; diversity 0.2076), and mixing is slow (mcmc_tau_int 27.65), but per the strict rules these do not imply collapse when structural similarity is high. Beta is high (current beta 4.386) and outputs are structured → ordered phase. Overall classification: the system is in a learning regime with ordered phase. Epistemic note: confidence is limited by conflicting signals (very high similarity and active learning vs low diversity and poor mixing); therefore confidence is substantial but constrained by those contradictory indicators.",
+"regime": "learning",
+"phase": "ordered",
+"scores": {
+"temperature": 0.92,
+"gibbs": 0.86
+},
+"risk": {
+"stagnation": 0.05,
+"collapse": 0.02,
+"over_ordering": 0.30
+},
+"confidence": 0.75
+}
+[SYS] EVIDENCE=0.272 | LLM=0.750 → FINAL=0.272
+
+[LLM CLEAN RESULT]
+ {'regime': 'learning', 'phase': 'ordered', 'failures': [], 'scores': {'temperature': 0.46, 'gibbs': 0.43}, 'risk': {'stagnation': 0.05, 'collapse': 0.0, 'over_ordering': 0.3}, 'actions': {}, 'confidence': 0.2719435542821884, 'analysis': 'High image_similarity (0.8597) and visually preserved digit structure indicate modes are retained and refinement matches the reference manifold. Learning_signal (0.328) and heating/positive trend slopes show continued parameter change, so the system is still learning. Entropy and diversity are low (entropy 0.3107 overall, current entropy 0.1565; diversity 0.2076), and mixing is slow (mcmc_tau_int 27.65), but per the strict rules these do not imply collapse when structural similarity is high. Beta is high (current beta 4.386) and outputs are structured → ordered phase. Overall classification: the system is in a learning regime with ordered phase. Epistemic note: confidence is limited by conflicting signals (very high similarity and active learning vs low diversity and poor mixing); therefore confidence is substantial but constrained by those contradictory indicators. [OVERRIDDEN: high structural similarity]', 'reason': 'json|low_confidence_scaled', 'evidence': 0.2719435542821884, 'llm_conf_raw': 0.75}
+[ANASIS] collapse=0.139 stagnation=0.320 healthy_align=0.540 → risk=0.406
+[ANALYSIS SIGNAL] 0.406
+[LLM OUTPUT SAVED] → llm_output_gpu0_seed1.json
+
+[LLM RESULT]
+
+{
+  "regime": "learning",
+  "phase": "ordered",
+  "failures": [],
+  "scores": {
+    "temperature": 0.46,
+    "gibbs": 0.43
+  },
+  "risk": {
+    "stagnation": 0.05,
+    "collapse": 0.0,
+    "over_ordering": 0.3
+  },
+  "actions": {},
+  "confidence": 0.2719435542821884,
+  "analysis": "High image_similarity (0.8597) and visually preserved digit structure
+indicate modes are retained and refinement matches the reference manifold. Learning_signal
+(0.328) and heating/positive trend slopes show continued parameter change, so the system
+is still learning. Entropy and diversity are low (entropy 0.3107 overall, current entropy
+0.1565; diversity 0.2076), and mixing is slow (mcmc_tau_int 27.65), but per the strict
+rules these do not imply collapse when structural similarity is high. Beta is high
+(current beta 4.386) and outputs are structured → ordered phase. Overall classification:
+the system is in a learning regime with ordered phase. Epistemic note: confidence is
+limited by conflicting signals (very high similarity and active learning vs low diversity
+and poor mixing); therefore confidence is substantial but constrained by those
+contradictory indicators. [OVERRIDDEN: high structural similarity]",
+  "reason": "json|low_confidence_scaled",
+  "evidence": 0.2719435542821884,
+  "llm_conf_raw": 0.75
+}
+Hybrid Thermodynamic RBM Final Results
+Seed: 1 | GPU: 0
+Final Temperature        : 0.923444
+Weight Norm              : 68.468369
+Spectral Gain            : 74.144559
+Train Log-Likelihood     : -411.152252
+Test Log-Likelihood      : -410.739502
+Train Pseudo-Likelihood  : -0.678435
+Test Pseudo-Likelihood   : -0.678006
+Reconstruction MSE       : 0.015900
+Reconstruction Accuracy  : 0.980278
+Mean Data Energy         : -652.020264
+Mean Model Energy        : -632.642517
+Energy Gap               : 19.377747
+GPU Energy Used          : 41135.66 J
+Log Partition (AIS)      : 1063.172485
+AIS ESS                  : 2483.00
+AIS Log-Weight Variance  : 1.972837
+MCMC tau_int             : 27.66
+MCMC tau_std             : 4.90
+MCMC tau_max             : 40.42
+MCMC tau_min             : 10.32
+MCMC ESS                 : 359672.06
+MCMC ESS / chain         : 299.73
+MCMC R-hat               : 1.1702
+MCMC ACF length          : 25
+Pixel Entropy            : 0.310680
+Sample Diversity         : 0.207591
+Mean Distribution L2     : 0.095660
+Professional Samples File: samples_prof_gpu0_seed1.png
+Generated Samples File   : samples_gpu0_seed1.png
+
+(srtrbm_env) gosachunt_uv0@GosachkPC:~/srtrbm_project$

correction/NO.py

@@ -0,0 +1,75 @@
+import torch
+
+
+class Refinement:
+
+    def __init__(self, model):
+        self.model = model
+
+    @torch.no_grad()
+    def mh_step(self, states, steps=6):
+        T = self.model.temperature()
+        current = states.clone()
+
+        for _ in range(steps):
+            proposal = self.model.gibbs_chain(current, T, steps=2)
+
+            F_cur = self.model.free_energy(current, T)
+            F_prop = self.model.free_energy(proposal, T)
+
+            delta = F_prop - F_cur
+
+            prob = torch.exp(torch.clamp(-delta / T, max=0))
+            accept = torch.rand_like(prob) < prob
+
+            accept = accept.view(-1, *([1] * (current.dim() - 1)))
+            current = torch.where(accept, proposal, current)
+
+        return current
+
+    @torch.no_grad()
+    def energy_guided_refine(self, states, steps=5):
+        T = self.model.temperature()
+        current = states.clone()
+
+        for _ in range(steps):
+            proposal = self.model.gibbs_chain(current, T, steps=2)
+
+            F_cur = self.model.free_energy(current, T)
+            F_prop = self.model.free_energy(proposal, T)
+
+            better = F_prop < F_cur
+
+            delta = F_prop - F_cur
+
+            prob = torch.exp(torch.clamp(-delta / T, max=0))
+            stochastic_accept = torch.rand_like(prob) < prob
+
+            accept = better | stochastic_accept
+            accept = accept.view(-1, *([1] * (current.dim() - 1)))
+
+            current = torch.where(accept, proposal, current)
+
+        return current
+
+    @torch.no_grad()
+    def soft_refine(self, states, steps=10):
+        T = self.model.temperature()
+        v = states.clone()
+
+        for _ in range(steps):
+            h_prob = torch.sigmoid((v @ self.model.W + self.model.hidden_bias) / T)
+            h = torch.bernoulli(h_prob)
+
+            v_prob = torch.sigmoid((h @ self.model.W.T + self.model.visible_bias) / T)
+
+            v = 0.7 * v + 0.3 * v_prob
+        return v
+
+    @torch.no_grad()
+    def myra_refine(self, states):
+        states = self.mh_step(states, steps=6)
+        states = self.energy_guided_refine(states, steps=5)
+        states = self.soft_refine(states, steps=8)
+
+        return states

correction/__init__.py

@@ -0,0 +1,5 @@
+from correction.NO import Refinement
+
+__all__ = [
+    "Refinement",
+]

graphs/SrtrbmEnergy.py

@@ -0,0 +1,177 @@
+import torch
+import numpy as np
+import matplotlib.pyplot as plt
+from scipy.stats import gaussian_kde
+from graphs.SrtrbmVisualization import save_digit_grid
+
+# Modern plotting style
+
+plt.style.use("seaborn-v0_8-whitegrid")
+
+COLORS = {
+    "data": "#1f77b4",  # deep blue
+    "model": "#ff7f0e",  # orange
+    "mean_data": "#1f77b4",
+    "mean_model": "#ff7f0e"
+}
+
+
+# Energy ranking
+
+@torch.no_grad()
+def compute_energy_ranking(model, data):
+    temperature = model.temperature()
+
+    energies = model.free_energy(data, temperature).detach()
+
+    idx = torch.argsort(energies)
+
+    return energies.cpu(), idx.cpu()
+
+
+# Energy landscape visualization
+
+@torch.no_grad()
+def visualize_energy_extremes(model, data, k=100):
+    _, idx = compute_energy_ranking(model, data)
+
+    N = len(data)
+
+    best = data[idx[:k]]
+    mid = data[idx[N // 2 - k // 2: N // 2 + k // 2]]
+    worst = data[idx[-k:]]
+
+    save_digit_grid(best, "lowest_energy_digits.png")
+    save_digit_grid(mid, "median_energy_digits.png")
+    save_digit_grid(worst, "highest_energy_digits.png")
+
+
+# Energy distribution analysis
+
+@torch.no_grad()
+def plot_data_vs_model_energy(model, data):
+    temperature = model.temperature()
+
+    # full dataset
+    n = int(data.shape[0])
+
+    # Data energy
+
+    F_data = model.free_energy(data[:n], temperature)
+    F_data = F_data.detach().cpu().numpy()
+
+    # Model sampling
+
+    samples = model.generate_ensemble_samples(
+        n_chains=n,
+        steps=2000,
+    )
+
+    F_model = model.free_energy(samples, temperature)
+    F_model = F_model.detach().cpu().numpy()
+
+    # Histogram range
+
+    lo = min(F_data.min(), F_model.min())
+    hi = max(F_data.max(), F_model.max())
+
+    bins = np.linspace(lo, hi, 120)
+
+    # Kernel density estimation
+
+    kde_data = gaussian_kde(F_data)
+    kde_model = gaussian_kde(F_model)
+
+    x = np.linspace(lo, hi, 500)
+
+    # Plot
+
+    plt.figure(figsize=(7, 5))
+
+    plt.hist(
+        F_data,
+        bins=bins,
+        density=True,
+        alpha=0.35,
+        color=COLORS["data"],
+        label="Data"
+    )
+
+    plt.hist(
+        F_model,
+        bins=bins,
+        density=True,
+        alpha=0.35,
+        color=COLORS["model"],
+        label="Model"
+    )
+
+    # KDE curves
+
+    plt.plot(
+        x,
+        kde_data(x),
+        color=COLORS["data"],
+        linewidth=2.5
+    )
+
+    plt.plot(
+        x,
+        kde_model(x),
+        color=COLORS["model"],
+        linewidth=2.5
+    )
+
+    # mean lines
+
+    mean_data = F_data.mean()
+    mean_model = F_model.mean()
+
+    plt.axvline(
+        mean_data,
+        linestyle="--",
+        linewidth=2,
+        color=COLORS["mean_data"]
+    )
+
+    plt.axvline(
+        mean_model,
+        linestyle=":",
+        linewidth=2,
+        color=COLORS["mean_model"]
+    )
+
+    energy_gap = abs(mean_data - mean_model)
+
+    plt.xlabel("Free Energy")
+
+    plt.ylabel("Probability Density")
+
+    plt.title(
+        f"Free Energy Distribution (ΔF = {energy_gap:.2f})"
+    )
+
+    plt.legend(frameon=False)
+
+    plt.grid(alpha=0.25)
+
+    plt.tight_layout()
+
+    plt.savefig(
+        "srtrbm_energy_data_vs_model_modern.pdf",
+        bbox_inches="tight"
+    )
+
+    plt.close()
+
+    # Return statistics
+
+    return {
+
+        "mean_data_energy": float(mean_data),
+
+        "mean_model_energy": float(mean_model),
+
+        "energy_gap": float(energy_gap)
+
+    }

graphs/SrtrbmMetrics.py

@@ -0,0 +1,220 @@
+import torch
+import numpy as np
+import matplotlib.pyplot as plt
+
+# Modern plotting style
+
+plt.style.use("seaborn-v0_8-whitegrid")
+
+COLORS = {
+    "flip": "#1f77b4",
+    "smooth": "#d62728",
+    "sus": "#2ca02c"
+}
+
+
+# Sample quality diagnostics
+
+@torch.no_grad()
+def sample_quality_metrics(model, real_data, n_samples=5000, diversity_pairs=3000):
+    samples = model.generate_ensemble_samples(
+        n_chains=n_samples,
+        steps=2000
+    ).float()
+
+    # Pixel entropy
+
+    p = samples.mean(0)
+
+    entropy = -(p * torch.log(p.clamp(min=1e-8)) +
+                (1 - p) * torch.log((1 - p).clamp(min=1e-8))).mean()
+
+    # Diversity
+
+    flat = samples.view(n_samples, -1)
+
+    device = flat.device
+
+    idx1 = torch.randint(0, n_samples, (diversity_pairs,), device=device)
+    idx2 = torch.randint(0, n_samples, (diversity_pairs,), device=device)
+
+    dists = torch.abs(flat[idx1] - flat[idx2]).mean(1)
+
+    diversity = dists.mean().item()
+
+    # Mean distribution distance
+
+    real_mean = real_data.float().mean(0)
+    gen_mean = samples.mean(0)
+
+    mean_l2 = torch.norm(real_mean - gen_mean) / np.sqrt(real_mean.numel())
+
+    return {
+        "pixel_entropy": entropy.item(),
+        "diversity": diversity,
+        "mean_l2": mean_l2.item()
+    }
+
+
+# Phase transition detection
+
+def detect_critical_beta(beta, flip):
+    beta = np.array(beta)
+    flip = np.array(flip)
+
+    if len(beta) < 5:
+        return beta.mean()
+
+    order = np.argsort(beta)
+
+    beta = beta[order]
+    flip = flip[order]
+
+    window = 7
+    kernel = np.ones(window) / window
+
+    flip_smooth = np.convolve(flip, kernel, mode="same")
+
+    susceptibility = -np.gradient(flip_smooth, beta)
+
+    idx = np.argmax(susceptibility)
+
+    return beta[idx]
+
+
+# Phase diagram visualization
+
+def plot_flip_beta(
+        model,
+        title,
+        filename,
+        fig_size=(10, 8),
+        density=True
+):
+    beta = np.array(model.spectral_beta_hist)
+    flip = np.array(model.flip_hist)
+
+    if len(beta) < 5:
+        return
+
+    # Sort
+
+    order = np.argsort(beta)
+
+    beta = beta[order]
+    flip = flip[order]
+
+    # Smooth
+
+    window = 9
+    kernel = np.ones(window) / window
+
+    flip_smooth = np.convolve(flip, kernel, mode="same")
+
+    # Susceptibility
+
+    susceptibility = -np.gradient(flip_smooth, beta)
+
+    beta_c = beta[np.argmax(susceptibility)]
+
+    # Figure
+
+    fig, axes = plt.subplots(3, 1, figsize=fig_size)
+
+    # Panel 1 — Phase diagram
+
+    if density:
+
+        hb = axes[0].hexbin(
+            beta,
+            flip,
+            gridsize=40,
+            cmap="viridis",
+            mincnt=1
+        )
+
+        fig.colorbar(
+            hb,
+            ax=axes[0],
+            label="Density",
+            fraction=0.045,
+            pad=0.03
+        )
+
+    else:
+
+        axes[0].scatter(
+            beta,
+            flip,
+            s=20,
+            alpha=0.35,
+            color=COLORS["flip"]
+        )
+
+    axes[0].plot(
+        beta,
+        flip_smooth,
+        linewidth=2.5,
+        color=COLORS["smooth"],
+        label="Smoothed flip rate"
+    )
+
+    axes[0].axvline(
+        beta_c,
+        linestyle="--",
+        linewidth=2,
+        color="black",
+        label=f"β_c ≈ {beta_c:.2f}"
+    )
+
+    axes[0].set_xlabel(r"$\beta_{\mathrm{spectral}}$")
+    axes[0].set_ylabel("Flip Rate")
+    axes[0].set_title(title)
+    axes[0].legend()
+
+    # Panel 2 — Smoothed flip
+
+    axes[1].plot(
+        beta,
+        flip_smooth,
+        linewidth=2.5,
+        color=COLORS["smooth"]
+    )
+
+    axes[1].axvline(
+        beta_c,
+        linestyle="--",
+        color="black"
+    )
+
+    axes[1].set_ylabel("Smoothed Flip")
+
+    # Panel 3 — Susceptibility
+
+    axes[2].plot(
+        beta,
+        susceptibility,
+        linewidth=2.5,
+        color=COLORS["sus"]
+    )
+
+    axes[2].axvline(
+        beta_c,
+        linestyle="--",
+        color="black"
+    )
+
+    axes[2].set_xlabel(r"$\beta_{\mathrm{spectral}}$")
+    axes[2].set_ylabel("Susceptibility")
+
+    # Layout
+
+    fig.subplots_adjust(
+        left=0.12,
+        right=0.96,
+        hspace=0.35
+    )
+
+    plt.savefig(filename, bbox_inches="tight")
+
+    plt.close()

graphs/SrtrbmVisualization.py

@@ -0,0 +1,116 @@
+import torch
+import numpy as np
+import torchvision.utils as vutils
+from PIL import Image
+
+
+# Save grid of digits
+
+@torch.no_grad()
+def save_digit_grid(data, filename, n_row=20):
+    imgs = data.reshape(-1, 1, 28, 28).detach().cpu()
+
+    grid = vutils.make_grid(
+        imgs,
+        nrow=n_row,
+        padding=2,
+        normalize=True
+    )
+
+    img = (grid * 255).clamp(0, 255).byte()
+
+    img = img.permute(1, 2, 0).numpy()
+
+    if img.shape[2] == 1:
+        img = img[:, :, 0]
+
+    Image.fromarray(img).save(filename)
+
+
+# RBM filters visualization
+
+@torch.no_grad()
+def visualize_rbm_filters(
+        model,
+        filename="srtrbm_filters.png",
+        n_filters=256
+):
+    W = model.W.detach().cpu()
+
+    n_filters = min(n_filters, W.shape[1])
+
+    filters = W[:, :n_filters].T
+
+    # normalize each filter
+
+    min_vals = filters.min(dim=1, keepdim=True)[0]
+    max_vals = filters.max(dim=1, keepdim=True)[0]
+
+    filters = (filters - min_vals) / (max_vals - min_vals + 1e-8)
+
+    filters = filters.reshape(-1, 1, 28, 28)
+
+    n_row = int(np.ceil(np.sqrt(n_filters)))
+
+    grid = vutils.make_grid(
+        filters,
+        nrow=n_row,
+        padding=2,
+        normalize=False
+    )
+
+    img = (grid * 255).clamp(0, 255).byte()
+
+    img = img.permute(1, 2, 0).numpy()
+
+    if img.shape[2] == 1:
+        img = img[:, :, 0]
+
+    Image.fromarray(img).save(filename)
+
+
+# Fantasy particles (model samples)
+
+@torch.no_grad()
+def visualize_fantasy_particles(
+        model,
+        filename="fantasy_particles.png",
+        n_chains=400,
+        steps=2000
+):
+    samples = model.generate_ensemble_samples(
+        n_chains=n_chains,
+        steps=steps
+    )
+
+    save_digit_grid(
+        samples,
+        filename,
+        n_row=int(np.sqrt(n_chains))
+    )
+
+
+# Training visual monitoring
+
+@torch.no_grad()
+def save_training_visuals(model, epoch):
+    samples = model.generate_ensemble_samples(
+        n_chains=400,
+        steps=3000
+    )
+
+    save_digit_grid(
+        samples,
+        f"samples_epoch_{epoch}.png",
+        n_row=20
+    )
+
+    visualize_rbm_filters(
+        model,
+        f"filters_epoch_{epoch}.png"
+    )
+
+    visualize_fantasy_particles(
+        model,
+        f"fantasy_epoch_{epoch}.png"
+    )

graphs/__init__.py

@@ -0,0 +1,29 @@
+from graphs.SrtrbmEnergy import (
+    compute_energy_ranking,
+    visualize_energy_extremes,
+    plot_data_vs_model_energy
+)
+
+from graphs.SrtrbmMetrics import (
+    sample_quality_metrics,
+    plot_flip_beta,
+    detect_critical_beta
+)
+
+from graphs.SrtrbmVisualization import (
+    save_digit_grid,
+    visualize_rbm_filters,
+    visualize_fantasy_particles
+)
+
+__all__ = [
+    "compute_energy_ranking",
+    "visualize_energy_extremes",
+    "plot_data_vs_model_energy",
+    "sample_quality_metrics",
+    "plot_flip_beta",
+    "detect_critical_beta",
+    "save_digit_grid",
+    "visualize_rbm_filters",
+    "visualize_fantasy_particles",
+]

llmeS/__init__.py

@@ -0,0 +1,22 @@
+from llmeS.client import SafeBookClient
+
+from llmeS.gateway import Evaluate
+from llmeS.gateway import ANASIS
+
+from llmeS.hook import find_connected_components_fast
+
+from llmeS.hook import LLMEnergy
+from llmeS.hook import LIES_gpu
+
+from llmeS.hook import to_sparse_gpu
+
+
+__all__ = [
+    "SafeBookClient",
+    "Evaluate",
+    "ANASIS",
+    "find_connected_components_fast",
+    "LLMEnergy",
+    "to_sparse_gpu",
+    "LIES_gpu",
+]

llmeS/client.py

@@ -0,0 +1,92 @@
+# GLOBAL LLM CLIENT (FULLY AGNOSTIC + SAFE)
+#
+# - Works with ANY backend
+# - Never crashes the system
+# - Normalizes output
+
+import os
+import time
+
+
+class BaseLLM:
+    """
+    User must implement this.
+
+    Expected:
+        generate(prompt, images=None) -> str | dict | None
+    """
+
+    def __init__(self, api_key=None):
+        self.api_key = api_key
+
+    def generate(self, prompt, images=None):
+        raise NotImplementedError
+
+
+class SafeBookClient:
+
+    def __init__(self):
+
+        api_key = os.getenv("LLM_API_KEY")
+
+        self.enabled = True
+
+        try:
+            self.backend = BaseLLM(api_key=api_key)
+
+        except Exception as e:
+            print("[LLM DISABLED]", str(e))
+            self.backend = None
+            self.enabled = False
+
+    def _normalize(self, result):
+        """
+        Normalize ANY backend output → string
+        """
+
+        if result is None:
+            return None
+
+        # string
+        if isinstance(result, str):
+            return result
+
+        # dict with text
+        if isinstance(result, dict):
+            if "text" in result:
+                return result["text"]
+
+            if "output" in result:
+                return result["output"]
+
+        # fallback
+        try:
+            return str(result)
+        except Exception:
+            return None
+
+    def generate(self, prompt, images=None):
+
+        if not self.enabled or self.backend is None:
+            return None
+
+        max_retries = 3
+        delay = 1.5
+
+        for attempt in range(max_retries):
+            try:
+                result = self.backend.generate(prompt, images=images)
+                return self._normalize(result)
+
+            except Exception as e:
+                if attempt == max_retries - 1:
+                    print("[LLM ERROR]", str(e))
+                    return None
+
+                time.sleep(delay * (attempt + 1))
+
+        return None
+
+
+# GLOBAL INSTANCE
+client = SafeBookClient()

llmeS/gateway.py

@@ -0,0 +1,632 @@
+# LLM GATEWAY (PROVIDER-AGNOSTIC INTERFACE)
+#
+# This module provides a high-level evaluation interface that integrates
+# thermodynamic metrics with LLM-based semantic interpretation.
+#
+# IMPORTANT DESIGN PRINCIPLE:
+# The system is strictly LLM-provider agnostic.
+# No specific API (OpenAI, Anthropic, Gemini, etc.) is assumed.
+#
+# All LLM interaction is routed through a global client:
+#
+#     raw = client.generate(prompt, images=[...])
+#
+# The client is expected to return raw text output only.
+# Any provider-specific formatting, API calls, or response schemas
+# must be handled inside the client backend implementation.
+#
+# This module does NOT depend on:
+#   - response objects
+#   - structured API outputs
+#   - provider-specific message formats
+#
+# Instead, it assumes:
+#   - raw string output from an LLM
+#   - JSON content embedded within that output
+#
+# The gateway is responsible for:
+#   1. Constructing structured prompts from system metrics
+#   2. Passing inputs (text + images) to the LLM client
+#   3. Extracting and validating JSON from raw responses
+#   4. Enforcing epistemic and structural constraints
+#
+# If no LLM backend is provided:
+#   - The system will gracefully degrade
+#   - A fallback result will be returned
+#
+# This design ensures full decoupling between:
+#   - thermodynamic learning (SR-TRBM)
+#   - semantic interpretation (LLM)
+#
+# Result:
+#   The system remains stable, extensible, and backend-independent.
+
+import torch.nn.functional as F
+from PIL import Image
+import numpy as np
+import warnings
+import base64
+import lpips
+import torch
+import os
+import json
+import math
+import copy
+import yaml
+
+warnings.filterwarnings("ignore", category=UserWarning)
+
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+lpips_model = lpips.LPIPS(net='vgg').to(device)
+lpips_model.eval()
+
+
+def encode_image(path):
+    with open(path, "rb") as f:
+        return "data:image/png;base64," + base64.b64encode(f.read()).decode("utf-8")
+
+
+def compute_lpips(path1, path2):
+    try:
+        img1 = Image.open(path1).convert("RGB").resize((256, 256))
+        img2 = Image.open(path2).convert("RGB").resize((256, 256))
+
+        img1 = np.array(img1).astype("float32") / 255.0
+        img2 = np.array(img2).astype("float32") / 255.0
+
+        img1 = torch.tensor(img1).permute(2, 0, 1).unsqueeze(0) * 2 - 1
+        img2 = torch.tensor(img2).permute(2, 0, 1).unsqueeze(0) * 2 - 1
+
+        img1 = img1.to(device)
+        img2 = img2.to(device)
+
+        with torch.no_grad():
+            dist = lpips_model(img1, img2)
+
+        return float(dist.item())
+
+    except Exception as eta:
+        print("[LPIPS ERROR]", str(eta))
+        return 1.0
+
+
+def preprocess(x):
+    if x.dim() == 2:
+        x = x.unsqueeze(0)
+    if x.shape[0] == 1:
+        x = x.repeat(3, 1, 1)
+
+    x = F.interpolate(x.unsqueeze(0), size=(256, 256), mode='bilinear', align_corners=False)
+
+    x = x * 2 - 1
+
+    return x
+
+
+def compute_lpips_diversity(samples, k=1000):
+    N = samples.shape[0]
+    total = 0.0
+
+    for _ in range(k):
+
+        while True:
+            inna = np.random.randint(0, N)
+            j = np.random.randint(0, N)
+            if inna != j:
+                break
+
+        img1 = preprocess(samples[inna]).to(device)
+        img2 = preprocess(samples[j]).to(device)
+
+        with torch.no_grad():
+            d = lpips_model(img1, img2)
+
+        total += d.item()
+
+    return float(total / (k + 1e-8))
+
+
+def load_core_principles(path="yaml/perception.yaml"):
+    try:
+        with open(path, "r") as f:
+            book = yaml.safe_load(f)
+    except FileNotFoundError:
+        print("[YAML NOT FOUND]", path)
+        return ""
+    except yaml.YAMLError as e1:
+        print("[YAML PARSE ERROR]", str(e1))
+        return ""
+
+    core = book.get("core", {})
+
+    blocks = []
+
+    for _, val in core.items():
+        title = val.get("title", "")
+        desc = val.get("description", "")
+        rules = val.get("rules", [])
+
+        block = []
+
+        if title:
+            block.append(f"{title}:")
+
+        if desc:
+            block.append(desc.strip())
+
+        for r in rules:
+            block.append(f"- {r}")
+
+        if val.get("priority") == "hard_constraint":
+            block.append("This principle is a HARD CONSTRAINT and ought to override weaker signals.")
+
+        blocks.append("\n".join(block))
+
+    return "\n\n".join(blocks)
+
+
+def _empty_result(reason, analysis=""):
+    return {
+        "regime": "unknown",
+        "phase": "unknown",
+        "failures": [],
+        "actions": {},
+        "confidence": 0.0,
+        "analysis": analysis.strip(),
+        "reason": reason
+    }
+
+
+def extract_json(raw):
+    raw = (raw or "").strip()
+
+    start = raw.find("{")
+    end = raw.rfind("}")
+
+    if start == -1 or end == -1:
+        return _empty_result("no_json", raw)
+
+    json_part = raw[start:end + 1]
+
+    try:
+        data = json.loads(json_part)
+
+    except json.JSONDecodeError as e2:
+        print("[JSON DECODE ERROR]", str(e2))
+        print("[RAW OUTPUT]", raw)
+        return _empty_result("json_decode_error", raw)
+
+    except TypeError as e2:
+        print("[TYPE ERROR]", str(e2))
+        return _empty_result("type_error", raw)
+
+    scores = data.get("scores") or {
+        "temperature": 0.0,
+        "gibbs": 0.0
+    }
+
+    return {
+        "regime": data.get("regime", "unknown"),
+        "phase": data.get("phase", "unknown"),
+        "failures": [] if data.get("failure", "none") == "none" else [data.get("failure")],
+        "scores": scores,
+        "risk": data.get("risk", {}),
+        "actions": {},
+        "confidence": float(data.get("confidence", 0.0)),
+        "analysis": data.get("analysis", ""),
+        "reason": "json"
+    }
+
+
+def extract_json_safe(raw):
+    raw = (raw or "").strip()
+
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return extract_json(raw)
+
+
+def load_object_context(perfect_image_path, metrics):
+    if not perfect_image_path:
+        return
+
+    json_path = perfect_image_path.replace(".png", "_objects.json")
+
+    if os.path.exists(json_path):
+        try:
+            with open(json_path, "r") as f:
+                data = json.load(f)
+
+            metrics["objects"] = data.get("objects", {})
+            metrics["domain"] = data.get("domain", {})
+
+        except (json.JSONDecodeError, OSError) as e3:
+            print("[OBJECT LOAD ERROR]", str(e3))
+
+            metrics["objects"] = {}
+            metrics["domain"] = {}
+    else:
+        metrics["objects"] = {}
+        metrics["domain"] = {}
+
+
+def Evaluate(metrics_input, refined_img_path, perfect_img_path, client=None):
+    print("DEBUG perfect_img_path:", perfect_img_path)
+
+    if client is None:
+        return _empty_result("no_client")
+
+    metrics_nomadic = copy.deepcopy(metrics_input)
+
+    if "samples" in metrics_input:
+        metrics_nomadic["lpips_diversity"] = compute_lpips_diversity(metrics_input["samples"])
+        metrics_nomadic["diversity"] = min(1.0, metrics_nomadic["lpips_diversity"])
+
+    if refined_img_path and perfect_img_path:
+        lpips_score = compute_lpips(refined_img_path, perfect_img_path)
+        metrics_nomadic["image_similarity"] = 1.0 - lpips_score
+
+        print("[IMAGE LPIPS]", lpips_score)
+
+    metrics_nomadic = enforce_hierarchy(metrics_nomadic)
+    load_object_context(perfect_img_path, metrics_nomadic)
+
+    metrics_str = json.dumps(metrics_nomadic, indent=2)
+
+    CORE_BLOCK = load_core_principles("yaml/perception.yaml")
+
+    prompt_main = f"""
+    You are analyzing a thermodynamic learning system.
+
+    {CORE_BLOCK}
+
+    {metrics_str}
+
+    CRITICAL INTERPRETATION RULES:
+
+    - High image_similarity indicates that generated samples match the reference structure.
+    - This is a strong POSITIVE signal of successful learning.
+
+    - Low diversity alone is NOT a failure condition.
+    - Converged systems naturally produce similar outputs.
+
+    - Poor mixing (high tau_int) does NOT imply collapse.
+
+    STRICT CONSTRAINT:
+
+    - Do NOT classify mode collapse if image_similarity is high.
+
+    Even if:
+    - diversity is low
+    - entropy is low
+    - mixing is slow
+
+    PRIORITY RULE:
+
+    - Structural similarity OVERRIDES diversity-based signals.
+
+    - High reconstruction quality + high similarity = HEALTHY system.
+
+    - If image_similarity is high AND reconstruction quality is high: classify the system as "stable" or "ordered", not as failure.
+
+    ---
+
+    Analyze visuals and metrics together.
+
+    IMAGE INTERPRETATION:
+
+    - High image_similarity → structures match (GOOD)
+    - Low image_similarity → structures differ
+
+    ---
+
+    IMPORTANT DEFINITIONS:
+
+    - A "mode" is NOT a digit class.
+    - Each digit contains many stylistic variations (micro-modes).
+    - Structural differences define modes, not visual similarity.
+
+    ---
+
+    COLLAPSE CRITERIA:
+
+    Only classify as "mode_collapse" if ALL of the following hold:
+    - repetitive structure
+    - low diversity
+    - structural degradation (low similarity)
+    - poor mixing
+
+    Do NOT classify collapse if:
+    - structure is preserved (high image_similarity)
+    - reconstruction quality is high
+
+    ---
+
+    ADDITIONAL CLASSIFICATION TASK:
+
+    Classify the system into the following categories:
+
+    - regime: one of ["learning", "stable", "stagnant", "converged"]
+    - phase: one of ["ordered", "critical", "disordered"]
+
+    Guidelines:
+
+    - ordered: low entropy, high beta, structured outputs
+    - disordered: high entropy, weak structure
+    - critical: balance between structure and diversity
+
+    - learning: weights are still changing (delta_w noticeable)
+    - stable: learning slowed but system remains healthy
+    - stagnant: little to no progress
+    - converged: learning has effectively finished
+
+    Notes:
+
+    - Choose the closest matching category based on the evidence.
+    - Avoid leaving these fields undefined.
+    - When uncertain, select the most plausible category rather than abstaining.
+
+    ---
+
+    OUTPUT INSTRUCTIONS:
+
+    - First explain your reasoning briefly.
+    - Then output a valid JSON block.
+
+    JSON ought to be the LAST part of your response.
+
+    RULES:
+
+    - Scores ought to be between 0 and 1
+    - Do NOT output discrete actions
+    - Higher score = stronger recommendation
+    """
+
+    prompt_format = """
+    FORMAT:
+
+    <reasoning>
+
+    {
+    "analysis": "...",
+
+    "regime": "...",
+    "phase": "...",
+
+    "scores": {
+    "temperature": 0.0,
+    "gibbs": 0.0
+    },
+
+    "risk": {
+    "stagnation": 0.0,
+    "collapse": 0.0,
+    "over_ordering": 0.0
+    },
+
+    "confidence": 0.0
+    }
+
+    EPISTEMIC INTERPRETATION (MANDATORY):
+
+    - You ought to interpret confidence as bounded by evidence.
+    - Confidence is not an independent belief; it is a function of evidence.
+
+    - If your internal belief is high but evidence is limited, you ought to explain the discrepancy.
+
+    - You ought to explicitly reflect this relationship in your analysis:
+
+        - High belief + low evidence → constrained confidence
+        - Low evidence → weak epistemic justification
+
+    - Do NOT just output a number. You ought to justify confidence in terms of evidence.
+
+    FORMAL RULE:
+    confidence ≤ evidence
+
+    INTERPRETATION RULE:
+    confidence represents only what is supported by evidence, not what is intuitively likely.
+
+    STRICT OUTPUT RULES:
+    - Output ONLY one JSON object
+    - Do NOT include text after JSON
+    - Do NOT include markdown (no ```json)
+    - JSON ought to be directly parseable by json.loads()
+    """
+
+    prompt = prompt_main + prompt_format
+
+    try:
+        img1 = encode_image(refined_img_path)
+        img2 = encode_image(perfect_img_path)
+
+        raw = client.generate(
+            prompt,
+            images=[img1, img2]
+        )
+
+        if raw is None or not str(raw).strip():
+            return _empty_result("empty_response")
+
+        if len(raw) < 2000:
+            print("\n[LLM RAW OUTPUT]\n", raw)
+        else:
+            print("\n[LLM RAW OUTPUT] (truncated)\n", raw[:2000])
+
+        result = extract_json_safe(raw)
+        result = validate_llm_output(result, metrics_nomadic)
+
+        if not result.get("analysis") or len(result.get("analysis", "").strip()) < 5:
+            result["analysis"] = "No meaningful analysis provided by LLM"
+
+        llm_conf = result.get("confidence", 0.0)
+        evidence = compute_evidence(metrics_nomadic)
+
+        final_conf = min(llm_conf, evidence)
+
+        sim = metrics_nomadic.get("image_similarity", 0.0)
+
+        if evidence < 0.1 and sim < 0.7:
+            final_conf = 0.0
+            result["reason"] = "no_evidence"
+
+        final_conf = max(0.0, min(1.0, final_conf))
+        result["confidence"] = final_conf
+        result["evidence"] = evidence
+        result["llm_conf_raw"] = llm_conf
+
+        print(f"[SYS] EVIDENCE={evidence:.3f} | LLM={llm_conf:.3f} → FINAL={final_conf:.3f}")
+
+        if result["confidence"] < 0.5:
+            for k in result.get("scores", {}):
+                result["scores"][k] = max(0.0, min(1.0, result["scores"][k] * 0.5))
+            if result.get("reason"):
+                result["reason"] += "|low_confidence_scaled"
+            else:
+                result["reason"] = "low_confidence_scaled"
+
+        print("\n[LLM CLEAN RESULT]\n", result)
+
+        if result.get("phase") == "unknown":
+            print("[WARNING] phase unresolved after parsing")
+
+        if result.get("regime") == "unknown":
+            print("[WARNING] regime unresolved after parsing")
+
+        return result
+
+    except (AttributeError, KeyError) as e4:
+        print("\n[RESPONSE FORMAT ERROR]", str(e4))
+        return _empty_result("response_format_error")
+
+    except RuntimeError as e4:
+        print("\n[RUNTIME ERROR]", str(e4))
+        return _empty_result("runtime_error")
+
+    except OSError as e4:
+        print("\n[IO ERROR]", str(e4))
+        return _empty_result("io_error")
+
+    except json.JSONDecodeError as e4:
+        print("\n[JSON ERROR]", str(e4))
+        return _empty_result("json_error")
+
+    except Exception as e4:
+        print("\n[UNEXPECTED ERROR]", type(e4).__name__, str(e4))
+        raise
+
+
+def compute_evidence(metrics):
+    signals = [
+        metrics.get("image_similarity", 0.0),
+        1 - metrics.get("std", 1.0),
+        metrics.get("flip_rate", 0.0),
+        metrics.get("diversity", 0.5),
+    ]
+
+    delta_w = metrics.get("delta_w", 0.0)
+    signals.append(min(1.0, delta_w * 1000))
+
+    return sum(signals) / len(signals)
+
+
+def enforce_hierarchy(metrics):
+    sim = metrics.get("image_similarity", 0.0)
+
+    if sim > 0.8:
+        if "diversity" in metrics:
+            metrics["diversity"] *= 0.3
+
+    return metrics
+
+
+def validate_llm_output(result, metrics):
+    sim = metrics.get("image_similarity", 0.0)
+
+    if sim > 0.8:
+        analysis = str(result.get("analysis", "")).lower()
+
+        if "collapse" in analysis and "no collapse" not in analysis:
+            result.setdefault("risk", {})
+            result["risk"]["collapse"] = 0.0
+            result["analysis"] += " [OVERRIDDEN: high structural similarity]"
+
+    return result
+
+
+def _cosine(a, b):
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(x * x for x in b))
+
+    return dot / (na * nb + 1e-8)
+
+
+def _embed(text):
+    text_log = text.lower()
+
+    return [
+        text_log.count("collapse") + text_log.count("failed"),
+        text_log.count("stagnation") + text_log.count("plateau"),
+        text_log.count("no learning") + text_log.count("stopped"),
+        text_log.count("learning"),
+        text_log.count("improving"),
+        text_log.count("stable"),
+        text_log.count("healthy"),
+        text_log.count("blur") + text_log.count("noisy"),
+        text_log.count("diversity")
+    ]
+
+
+def ANASIS(text, metrics=None):
+    if not text:
+        return 0.5
+
+    text_vec = _embed(text.lower())
+
+    ref_collapse = _embed("model collapse failure unstable diverging system")
+    ref_stagnation = _embed("learning stagnation plateau no progress stopped system")
+    ref_healthy = _embed("stable improving healthy well-trained diverse system")
+
+    sim_collapse = _cosine(text_vec, ref_collapse)
+    sim_stagnation = _cosine(text_vec, ref_stagnation)
+    sim_healthy = _cosine(text_vec, ref_healthy)
+
+    risk_signal = max(sim_collapse, sim_stagnation)
+
+    diversity_term = 0.0
+
+    if metrics is not None:
+        d = metrics.get("diversity", 0.5)
+        diversity_term = (1 - d) ** 2
+
+    energy = (
+            0.5 * risk_signal +
+            0.3 * (1 - sim_healthy) +
+            0.2 * diversity_term
+    )
+
+    energy = max(0.0, min(1.0, energy))
+    if sim_healthy == 0:
+        consistency = abs(1.0 - energy)
+    else:
+        consistency = abs(1 - (sim_healthy + energy))
+
+    consistency = max(0.0, min(1.0, consistency))
+
+    energy = max(0.0, min(1.0, energy))
+
+    final_score = energy - 0.1 * consistency
+
+    final_score = max(0.0, min(1.0, final_score))
+
+    print(
+        f"[ANASIS] collapse={sim_collapse:.3f} "
+        f"stagnation={sim_stagnation:.3f} "
+        f"healthy_align={consistency:.3f} "
+        f"→ risk={final_score:.3f}"
+    )
+
+    return final_score

llmeS/hook.py

@@ -0,0 +1,279 @@
+# LLM ENERGY MODULE (PROVIDER-AGNOSTIC SEMANTIC ENERGY)
+#
+# This module defines an LLM-based energy estimator that interprets
+# structured visual representations as probabilistic signals.
+#
+# DESIGN PRINCIPLE:
+# The LLM is treated as a black-box semantic energy oracle.
+# No assumptions are made about the underlying provider.
+#
+# All interaction is performed through a global client:
+#
+#     raw = client.generate(prompt)
+#
+# The client MUST return raw text output.
+# Any API-specific logic is handled externally.
+#
+# This module is responsible for:
+#   - constructing structured prompts from sparse representations
+#   - extracting probability distributions from raw LLM output
+#   - validating and normalizing probability vectors
+#
+# FAILURE MODE:
+# If the LLM backend fails or returns invalid output:
+#   - the function returns (None, error_code)
+#   - the main system continues without interruption
+#
+# ARCHITECTURAL ROLE:
+# This module provides a semantic energy term that augments
+# the thermodynamic model with external probabilistic signals.
+
+import json
+import torch
+import numpy as np
+import hashlib
+import torch.nn.functional as F
+
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+
+def extract_json_block(text: str):
+    stack = []
+    start_idx = None
+    for into, ch in enumerate(text):
+        if ch == "{":
+            if start_idx is None:
+                start_idx = into
+            stack.append(ch)
+        elif ch == "}":
+            if stack:
+                stack.pop()
+                if not stack and start_idx is not None:
+                    return text[start_idx:into + 1]
+    return None
+
+
+def upscale_to_64(grid_2d):
+    if grid_2d.dim() == 2:
+        grid_2d = grid_2d.unsqueeze(0).unsqueeze(0)
+    upscaled = F.interpolate(grid_2d, size=(64, 64), mode="bilinear", align_corners=False)
+    return upscaled.squeeze(0).squeeze(0)
+
+
+def _component_direction_pca(coordinates_np):
+    if len(coordinates_np) < 3:
+        return [0.0, 0.0]
+
+    cov = np.cov(coordinates_np.T)
+    eigenvalues, eigenvectors = np.linalg.eig(cov)
+    main_vec = eigenvectors[:, np.argmax(eigenvalues)]
+
+    norm = np.linalg.norm(main_vec) + 1e-12
+    main_vec = main_vec / norm
+
+    if main_vec[0] < 0:
+        main_vec = -main_vec
+
+    return [float(main_vec[0]), float(main_vec[1])]
+
+
+def _component_features(coordinates_list):
+    coordinate = np.array(coordinates_list)
+
+    if coordinate.size == 0:
+        return {
+            "size": 0,
+            "bbox": [0, 0, 0, 0],
+            "center": [0.0, 0.0],
+            "direction": [0.0, 0.0],
+            "aspect_ratio": 1.0
+        }
+
+    ys = coordinate[:, 0]
+    xs = coordinate[:, 1]
+
+    y1, y2 = int(ys.min()), int(ys.max())
+    x1, x2 = int(xs.min()), int(xs.max())
+
+    center = [float(ys.mean()), float(xs.mean())]
+    direction = _component_direction_pca(coordinate)
+
+    aspect_ratio = (y2 - y1 + 1) / (x2 - x1 + 1 + 1e-6)
+
+    return {
+        "size": int(len(coordinates_list)),
+        "bbox": [y1, x1, y2, x2],
+        "center": center,
+        "direction": direction,
+        "aspect_ratio": float(aspect_ratio)
+    }
+
+
+def find_connected_components_fast(grid_2d, threshold=0.15):
+    from scipy.ndimage import label
+
+    binary = (grid_2d > threshold).detach().cpu().numpy()
+    labeled, num = label(binary)
+
+    components = []
+    for into in range(1, num + 1):
+        coordinates_plus = np.argwhere(labeled == into)
+
+        components.append(coordinates_plus.tolist())
+
+    return components
+
+
+def to_sparse_gpu(grid_2d, threshold=0.15):
+    grid_2d = grid_2d.to(device)
+    mask = grid_2d > threshold
+
+    coordinate_grow = torch.nonzero(mask, as_tuple=False)
+
+    values = grid_2d[mask]
+
+    coordinates_cpu = coordinate_grow.cpu().numpy()
+    values_cpu = values.cpu().numpy()
+
+    active_pixels = [
+        [int(r), int(clm), round(float(v), 3)]
+        for (r, clm), v in zip(coordinates_cpu, values_cpu)
+    ]
+
+    if len(active_pixels) > 800:
+        step = max(1, len(active_pixels) // 800)
+        active_pixels = active_pixels[::step]
+
+    raw_components = find_connected_components_fast(grid_2d, threshold)
+
+    comp_objs = []
+    for comp in raw_components:
+        feats = _component_features(comp)
+
+        step = max(1, len(comp) // 50)
+        simplified = comp[::step]
+
+        comp_objs.append({
+            "points": simplified,
+            "size": feats["size"],
+            "bbox": feats["bbox"],
+            "center": feats["center"],
+            "direction": feats["direction"],
+            "aspect_ratio": feats["aspect_ratio"]
+        })
+
+    return json.dumps({
+        "size": list(grid_2d.shape),
+        "pixels": active_pixels,
+        "components": comp_objs
+    })
+
+
+def hash_repr(s: str):
+    return hashlib.md5(s.encode()).hexdigest()
+
+
+_cache = {}
+
+
+def LLMEnergy(image_repr: str, client=None):
+    if client is None:
+        return None, "no_client"
+
+    key = hash_repr(image_repr)
+    if key in _cache:
+        return _cache[key], None
+
+    prompt = f"""
+    You MUST follow:
+    1. Use components to infer topology
+    2. Use pixels to infer intensity
+    3. Use component directions to infer stroke flow
+    4. Use aspect ratios to refine structural interpretation
+    5. Output calibrated probabilities
+    
+    Return ONLY JSON:
+    {{"probs": [p0, p1, ..., p9]}}
+    
+    Image:
+    {image_repr}
+    """
+
+    try:
+        raw_output = client.generate(prompt)
+
+        if raw_output is None or not str(raw_output).strip():
+            return None, "empty_response"
+
+        raw_output = raw_output.strip()
+
+    except Exception as e:
+        return None, f"client_error: {e}"
+
+    try:
+        parsed_json = json.loads(raw_output)
+    except json.JSONDecodeError:
+        json_block = extract_json_block(raw_output)
+        if json_block is None:
+            return None, "json_not_found"
+        try:
+            parsed_json = json.loads(json_block)
+        except json.JSONDecodeError:
+            return None, "json_parse_error"
+
+    probs = parsed_json.get("probs")
+
+    if not isinstance(probs, list) or len(probs) != 10:
+        return None, "invalid_probs"
+
+    try:
+        prob_vector = np.array(probs, dtype=np.float32)
+    except ValueError:
+        return None, "non_numeric_probs"
+
+    total = prob_vector.sum()
+    if total <= 0:
+        return None, "invalid_distribution"
+
+    prob_vector /= total
+
+    result = {"probs": prob_vector.tolist()}
+    _cache[key] = result
+
+    return result, None
+
+
+def LIES_gpu(prob_vector, alpha=5.0, beta=2.0, gamma=2.0):
+    prob = torch.tensor(prob_vector, device=device)
+
+    eps = 1e-12
+    entropy = -torch.sum(prob * torch.log(prob + eps))
+    confidence = torch.max(prob)
+
+    top2 = torch.topk(prob, 2).values
+    margin_out = top2[0] - top2[1]
+
+    energy = alpha * entropy - beta * confidence - gamma * margin_out
+    return energy.item()
+
+
+def process_digit(grid_2d, client=None):
+    grid_2d = grid_2d.to(device)
+
+    if grid_2d.numel() == 784:
+        grid_2d = grid_2d.view(28, 28)
+        grid_2d = upscale_to_64(grid_2d)
+    elif grid_2d.numel() == 4096:
+        grid_2d = grid_2d.view(64, 64)
+    else:
+        raise ValueError("Unexpected input size")
+
+    image_repr = to_sparse_gpu(grid_2d, threshold=0.15)
+
+    result, err = LLMEnergy(image_repr, client)
+    if err:
+        return None, err
+
+    energy = LIES_gpu(result["probs"])
+
+    return {"probs": result["probs"], "energy": energy}, None

srtrbm_project_core.py

@@ -0,0 +1,1600 @@
+#   Self-Regulated Thermodynamic RBM (SR-TRBM)
+#
+#   SPDX-License-Identifier: BSD-3-Clause
+#
+#   Copyright © 2026 Görkem Can Süleymanoğlu
+#
+#   This implementation realizes a thermodynamically self-regulated
+#   energy-based model operating in a finite-time stochastic regime.
+#   The framework extends classical Restricted Boltzmann Machines by
+#   introducing endogenous control of sampling dynamics and bounded
+#   external energy corrections.
+#
+#   Training is performed using Persistent Contrastive Divergence 
+#   (PCD-k), where the negative phase is approximated by short-run 
+#   Gibbs chains. To use conductance collapse and Gibbs freezing,
+#   the model employs a hybrid temperature mechanism:
+#
+#       T = T_micro + T_macro
+#
+#   The microscopic component follows a feedback control law based 
+#   on the empirical flip rate r_t:
+#
+#       λ_{t+1} = λ_t - η (r_t - c_t)
+#
+#   where c_t is an exponentially smoothed reference, inducing
+#   closed-loop stabilization of stochastic transition intensity.
+#
+#   The model incorporates a localized LLM-guided refinement mechanism
+#   for proposals within an uncertainty band (ΔE ∈ [0, 2]).
+#
+#   LLM contributions are normalized via a running variance estimate:
+#       σ² ← EMA(ΔE_model²),   ΔE_llm ← ΔE_llm / σ
+#
+#   Designed for CUDA-enabled GPU execution with fixed seeds.
+#   Average runtime per seed: ~20–30 minutes on RTX-class GPUs.
+#   AIS estimation and multichain Gibbs sampling are dominant costs.
+#
+#   Thermal monitoring is recommended (e.g., nvidia-smi).
+#   Multi-seed runs should be executed sequentially.
+#
+#   Full license text is provided in the root LICENSE file.
+
+from graphs import SrtrbmVisualization
+from graphs import SrtrbmEnergy
+from graphs import SrtrbmMetrics
+
+from analysis.AutoGPU import GPUEnergyTracker
+from correction.NO import Refinement
+
+import torch
+import torch.nn.functional as F
+import torch.multiprocessing as mp
+import torchvision.utils as vutils
+from tqdm import tqdm
+from PIL import Image
+import numpy as np
+import subprocess
+import threading
+import textwrap
+import json
+import math
+import time
+import sys
+
+import matplotlib
+
+matplotlib.use("Agg")
+
+import matplotlib as mpl
+
+import matplotlib.pyplot as plt
+
+from sklearn.datasets import fetch_openml
+
+from llmeS.hook import LLMEnergy, to_sparse_gpu, LIES_gpu
+from llmeS.gateway import Evaluate, ANASIS
+from llmeS.client import SafeBookClient
+
+mpl.rcParams.update({
+    "font.family": "serif",
+    "font.serif": ["Times New Roman", "Times", "DejaVu Serif"],
+    "font.size": 11,
+    "axes.titlesize": 12,
+    "axes.labelsize": 11,
+    "legend.fontsize": 9,
+    "xtick.labelsize": 9,
+    "ytick.labelsize": 9,
+    "figure.dpi": 300,
+    "savefig.dpi": 300,
+    "pdf.fonttype": 42,
+    "ps.fonttype": 42
+})
+
+
+# Data Model
+
+def load_mnist(device_exact):
+    dataSet = fetch_openml("mnist_784", version=1, cache=True)
+    X_prime = dataSet.data.to_numpy(dtype="float32") / 255.0
+    X_prime = (X_prime > -0.0).astype("float32")
+
+    return torch.tensor(X_prime).to(device_exact)
+
+
+def susceptibility(samples):
+    spins = 2 * samples - 1
+
+    magnetization = spins.mean(dim=1)
+
+    chi = magnetization.var(unbiased=False)
+
+    return chi.item()
+
+
+def binder_cumulant(samples):
+    spins = 2 * samples - 1
+
+    spins = spins.reshape(spins.size(0), -1)
+
+    m = spins.mean(dim=1)
+
+    m2 = torch.mean(m ** 2)
+    m4 = torch.mean(m ** 4)
+
+    U = 1 - m4 / (3 * (m2 ** 2) + 1e-12)
+
+    return U.item()
+
+
+# Model Point
+
+class HybridThermodynamicRBM:
+
+    def __init__(
+            self,
+            n_visible,
+            n_hidden,
+            device_type="cuda",
+            learning_rate=5e-4,
+            epochs=400,
+            gibbs_steps=1,
+            batch_size=128,
+            lambda_gain=0.01,
+            flip_smoothing=0.01,
+            energy_temp_scale=0.001,
+            weight_decay=1e-4,
+            fixed_temperature=None
+    ):
+        self.v_bias = None
+        self.h_bias = None
+
+        self.analysis_history = []
+
+        self.abort_counter = getattr(self, "abort_counter", 0)
+
+        self.device = torch.device(device_type)
+
+        self.n_visible = n_visible
+        self.n_hidden = n_hidden
+        self.lr = learning_rate
+        self.epochs = epochs
+        self.gibbs_steps = gibbs_steps
+        self.batch_size = batch_size
+
+        # Thermodynamic parameters
+
+        self.lambda_gain = lambda_gain
+        self.flip_smoothing = flip_smoothing
+        self.energy_temp_scale = energy_temp_scale
+        self.weight_decay = weight_decay
+
+        self.fixed_temperature = fixed_temperature
+
+        self.command = 1.0
+        self.bias_decay = 0.0
+        self.energy_count = 0
+        self.lambda_llm = 1.29
+
+        self.llm_scale = 1.0
+
+        self.llm_scale_initialized = False
+
+        # Model parameters
+
+        self.coefficient_zeta = 0.05
+
+        self.W = torch.randn(n_visible, n_hidden, device=self.device) * self.coefficient_zeta
+
+        self.visible_bias = torch.zeros(n_visible, device=self.device)
+        self.hidden_bias = torch.zeros(n_hidden, device=self.device)
+
+        # Thermodynamic states
+
+        self.log_temperature = torch.tensor(0.0, device=self.device)
+        self.flip_reference = torch.tensor(0.0, device=self.device)
+        self.energy_avg = torch.tensor(0.0, device=self.device)
+
+        self.persistent_sampling = None
+
+        # Monitoring histories
+
+        self.flip_hist = []
+        self.c_hist = []
+        self.weight_norm_hist = []
+        self.beta_eff_hist = []
+        self.temp_hist = []
+        self.delta_w_hist = []
+        self.persistent_div_hist = []
+        self.T_micro_hist = []
+        self.T_macro_hist = []
+        self.F_data_hist = []
+        self.F_model_hist = []
+        self.F_gap_hist = []
+        self.true_beta_hist = []
+        self.spectral_beta_hist = []
+
+    # Temperature (Hybrid Rule)
+
+    def temperature(self):
+        if self.fixed_temperature is not None:
+            return torch.tensor(self.fixed_temperature, device=self.device, dtype=torch.float32)
+
+        micro = torch.exp(self.log_temperature)
+        macro = self.energy_temp_scale * self.energy_avg
+
+        T = micro + macro
+
+        return torch.clamp(T, min=1e-6, max=1e3)
+
+    # Energy
+
+    def raw_energy(self, v, h):
+        return - (v @ self.W * h).sum(1) \
+            - (v * self.visible_bias).sum(1) \
+            - (h * self.hidden_bias).sum(1)
+
+    def free_energy(self, v, T):
+        activation = (v @ self.W + self.hidden_bias) / T
+        return -(v * self.visible_bias).sum(1) / T \
+            - F.softplus(activation).sum(1)
+
+    @torch.no_grad()
+    def reconstruction_accuracy(self, data):
+
+        recon_prob = self.reconstruct(data)
+        recon_bin = (recon_prob > 0.5).float()
+
+        correct = (recon_bin == data).float().sum()
+        total = data.numel()
+
+        return (correct / total).item()
+
+    # Gibbs Sampling
+
+    @torch.no_grad()
+    def gibbs_chain(self, v, T, steps=None):
+
+        steps = steps if steps is not None else self.gibbs_steps
+
+        for _ in range(steps):
+            h = torch.bernoulli(torch.sigmoid((v @ self.W + self.hidden_bias) / T))
+            v = torch.bernoulli(torch.sigmoid((h @ self.W.T + self.visible_bias) / T))
+
+        return v
+
+    # Training
+
+    def train(self, data, energy_tracker=None):
+
+        N = data.shape[0]
+
+        persistent_v = torch.bernoulli(
+            torch.full((self.batch_size, self.n_visible), 0.5, device=self.device)
+        )
+
+        epoch_bar = tqdm(range(self.epochs), desc="Training", leave=True)
+
+        for _ in epoch_bar:
+
+            v_neg_all = []
+            W_before = self.W.clone()
+
+            perm = torch.randperm(N, device=self.device)
+            data = data[perm]
+
+            flip_rates = []
+            energy_gaps = []
+            F_data_batches = []
+            F_model_batches = []
+
+            for algebraic in range(0, N, self.batch_size):
+
+                T = self.temperature()
+
+                v_pos = data[algebraic:algebraic + self.batch_size]
+                if v_pos.shape[0] != self.batch_size:
+                    continue
+
+                # Negative phase (Persistent Contrastive Divergence - PCD-k)
+
+                v_prev = persistent_v
+
+                v_neg = self.gibbs_chain(v_prev, T, steps=self.gibbs_steps)
+
+                persistent_v = v_neg
+
+                flip = (v_neg != v_prev).float().mean()
+                flip_rates.append(flip)
+
+                # Expectations
+
+                h_pos = torch.sigmoid((v_pos @ self.W + self.hidden_bias) / T)
+                h_neg = torch.sigmoid((v_neg @ self.W + self.hidden_bias) / T)
+
+                dW = (v_pos.T @ h_pos - v_neg.T @ h_neg) / self.batch_size
+                dW -= self.weight_decay * self.W
+
+                self.W += self.lr * dW
+
+                # ℓ2 regularization on biases (bias decay) b_{t+1} = (1 - ηλ) b_t + η g_t
+
+                db_v = (v_pos - v_neg).mean(0) - self.bias_decay * self.visible_bias
+                db_h = (h_pos - h_neg).mean(0) - self.bias_decay * self.hidden_bias
+
+                self.visible_bias += self.lr * db_v
+                self.hidden_bias += self.lr * db_h
+
+                # Energy gap
+
+                F_data_batch = self.free_energy(v_pos, T).mean()
+                F_model_batch = self.free_energy(v_neg, T).mean()
+
+                energy_gaps.append(F_data_batch - F_model_batch)
+
+                F_data_batches.append(F_data_batch)
+                F_model_batches.append(F_model_batch)
+
+                v_neg_all.append(v_neg)
+
+                if energy_tracker is not None:
+                    energy_tracker.step()
+
+            # Epoch statistics
+
+            flip_epoch = torch.stack(flip_rates).mean()
+            energy_gap_epoch = torch.stack(energy_gaps).mean()
+
+            F_data_epoch = torch.stack(F_data_batches).mean().item()
+            F_model_epoch = torch.stack(F_model_batches).mean().item()
+
+            # Microscopic control
+
+            self.flip_reference = (
+                    (1 - self.flip_smoothing) * self.flip_reference
+                    + self.flip_smoothing * flip_epoch
+            )
+
+            error = flip_epoch - self.flip_reference
+
+            self.log_temperature = self.command * (
+                    self.log_temperature -
+                    self.lambda_gain * error
+            )
+
+            # Macroscopic control (Exact Cesàro average)
+
+            self.energy_count += 1
+
+            self.energy_avg = self.energy_avg + (
+                    energy_gap_epoch.detach() - self.energy_avg
+            ) / self.energy_count
+
+            # Diagnostics
+
+            current_T = self.temperature()
+
+            T_micro = torch.exp(self.log_temperature).item()
+
+            T_macro = (self.energy_temp_scale * self.energy_avg).item()
+
+            weight_norm = torch.norm(self.W).item()
+
+            with torch.no_grad():
+                u_vec = torch.randn(self.n_visible, 1, device=self.device)
+                u_vec = u_vec / (torch.norm(u_vec) + 1e-8)
+
+                for _ in range(self.gibbs_steps * 2):
+                    v_vec = torch.matmul(self.W.T, u_vec)
+                    v_vec = v_vec / (torch.norm(v_vec) + 1e-8)
+                    u_vec = torch.matmul(self.W, v_vec)
+                    u_vec = u_vec / (torch.norm(u_vec) + 1e-8)
+
+                spectral_norm = torch.norm(torch.matmul(self.W, v_vec)).item()
+
+            v_neg_all = torch.cat(v_neg_all, dim=0)
+
+            activations = (v_neg_all @ self.W + self.hidden_bias) / current_T
+            beta_eff = activations.std(dim=1).mean().item()
+
+            spectral_beta = spectral_norm / current_T.item()
+
+            true_beta = 1.0 / current_T.item()
+
+            delta_w = torch.norm(self.W - W_before).item()
+
+            # Store histories
+
+            self.flip_hist.append(flip_epoch.item())
+            self.c_hist.append(self.flip_reference.item())
+            self.weight_norm_hist.append(weight_norm)
+            self.beta_eff_hist.append(beta_eff)
+            self.temp_hist.append(current_T.item())
+            self.delta_w_hist.append(delta_w)
+            self.T_micro_hist.append(T_micro)
+            self.T_macro_hist.append(T_macro)
+            self.F_data_hist.append(F_data_epoch)
+            self.F_model_hist.append(F_model_epoch)
+            self.true_beta_hist.append(true_beta)
+            self.spectral_beta_hist.append(spectral_beta)
+            self.F_gap_hist.append(F_data_epoch - F_model_epoch)
+
+            # Progress bar
+
+            epoch_bar.set_postfix({
+                "T": f"{current_T.item():.3f}",
+                "flip": f"{flip_epoch.item():.3f}",
+                "beta": f"{beta_eff:.3f}"
+            })
+
+            persistent_div = torch.var(persistent_v.float())
+
+            self.persistent_div_hist.append(persistent_div.item())
+
+        return None
+
+    # Sampling
+
+    @torch.no_grad()
+    def generate_ensemble_samples(
+            self,
+            n_chains=1200,
+            steps=10000,
+            energy_tracker=None,
+    ):
+        """
+        Multichain Gibbs sampler with STABLE temperature (debug version).
+        """
+
+        device = self.device
+        T_base = self.temperature().item()
+
+        # Persistent init
+        if (
+                hasattr(self, "persistent_sampling")
+                and self.persistent_sampling is not None
+                and self.persistent_sampling.shape == (n_chains, self.n_visible)
+        ):
+            v = self.persistent_sampling
+        else:
+            v = torch.bernoulli(
+                torch.rand(n_chains, self.n_visible, device=device)
+            )
+
+        for _ in range(steps):
+
+            T = T_base
+
+            # h sample
+            h = torch.bernoulli(
+                torch.sigmoid((v @ self.W + self.hidden_bias) / T)
+            )
+
+            # additional Gibbs steps
+            for _ in range(self.gibbs_steps * 1):
+                v = torch.bernoulli(
+                    torch.sigmoid((h @ self.W.T + self.visible_bias) / T)
+                )
+                h = torch.bernoulli(
+                    torch.sigmoid((v @ self.W + self.hidden_bias) / T)
+                )
+
+            # final v update
+            v = torch.bernoulli(
+                torch.sigmoid((h @ self.W.T + self.visible_bias) / T)
+            )
+
+            if energy_tracker is not None:
+                energy_tracker.step()
+
+        return v
+
+    @torch.no_grad()
+    def llm_uncertainty_refinement(self, state, client=None):
+        """
+        LLM-guided refinement with physically consistent energy coupling.
+
+        The refinement operates on locally uncertain proposals determined by the model.
+        Only proposals with ΔE_model in the interval [0, 2] are considered, which
+        corresponds to the uncertainty region of the energy landscape.
+
+        The language model contributes as a bounded perturbation to the energy.
+        Its influence is normalized and constrained relative to the model energy,
+        ensuring that it cannot dominate the underlying distribution but can still
+        provide meaningful local corrections.
+
+        The same bit-flip is used during both selection and proposal stages to
+        preserve consistency in the transition dynamics.
+        """
+
+        batch_size, dim = state.shape
+        temperature = self.temperature()
+
+        debug = getattr(self, "debug", True)
+
+        if debug:
+            print(f"\n[LLM] Start | B={batch_size} | T={temperature:.4f}", flush=True)
+
+        refined_state = state.clone()
+
+        llm_cache = {}
+
+        def get_llm_energy(repr_str):
+            if repr_str in llm_cache:
+                return llm_cache[repr_str]
+
+            consequence, error = LLMEnergy(repr_str, client)
+            llm_cache[repr_str] = (consequence, error)
+
+            return consequence, error
+
+        # Generate single-bit proposals
+        flip_indices = torch.randint(0, dim, (batch_size,), device=state.device)
+
+        state_prop = state.clone()
+        state_prop[torch.arange(batch_size), flip_indices] = \
+            1 - state_prop[torch.arange(batch_size), flip_indices]
+
+        # Signed energy difference (no absolute value)
+        E_cur = self.free_energy(state, temperature)
+        E_prop = self.free_energy(state_prop, temperature)
+        delta_E = E_prop - E_cur
+
+        # Adaptive selection size using effective sample size (ESS)
+        weights = torch.softmax(-E_cur / (temperature + 1e-8), dim=0)
+
+        ess = 1.0 / torch.sum(weights ** 2)
+        ess_ratio = ess.item() / batch_size
+
+        k = int(batch_size * (1.0 - ess_ratio))
+        k = min(batch_size // 4, max(1, int(k / 90)))  # The number 90 is an arbitrary choice.
+
+        # Select uncertain samples where ΔE ∈ [0, 2]
+
+        low, high = 0.0, 2.0
+
+        mask = (delta_E >= low) & (delta_E <= high)
+        band_indices = torch.nonzero(mask).squeeze(1)
+
+        center = 1.0
+
+        if band_indices.numel() >= k:
+            band_delta = delta_E[band_indices]
+            _, order = torch.sort(torch.abs(band_delta - center))
+            selected_indices = band_indices[order[:k]]
+        else:
+            all_dist = torch.abs(delta_E - center)
+            _, order = torch.sort(all_dist)
+            selected_indices = order[:k]
+
+        selected_flips = flip_indices[selected_indices]
+
+        if debug:
+            print(
+                f"[Debug] ESS={ess.item():.2f} | k={k} | "
+                f"deltaE_band=[{low:.2f},{high:.2f}] | "
+                f"in_band={band_indices.numel()} | selected={selected_indices.numel()}"
+            )
+
+        accepted_count = 0
+        llm_usage_count = 0
+
+        for integer, ideal in enumerate(selected_indices):
+
+            current_sample = refined_state[ideal]
+            proposed_sample = current_sample.clone()
+
+            flip_idx = selected_flips[integer].item()
+            proposed_sample[flip_idx] = 1 - proposed_sample[flip_idx]
+
+            E_model_cur = self.free_energy(current_sample.unsqueeze(0), temperature)[0]
+            E_model_prop = self.free_energy(proposed_sample.unsqueeze(0), temperature)[0]
+
+            delta_model = E_model_prop - E_model_cur
+            delta_total = delta_model
+
+            if client is not None:
+
+                current_repr = to_sparse_gpu(current_sample.view(28, 28))
+                proposed_repr = to_sparse_gpu(proposed_sample.view(28, 28))
+
+                current_llm, err_cur = get_llm_energy(current_repr)
+                proposed_llm, err_prop = get_llm_energy(proposed_repr)
+
+                if not (err_cur or err_prop or current_llm is None or proposed_llm is None):
+
+                    llm_usage_count += 1
+
+                    probs_cur = current_llm["probs"]
+                    probs_prop = proposed_llm["probs"]
+
+                    E_llm_cur = LIES_gpu(probs_cur)
+                    E_llm_prop = LIES_gpu(probs_prop)
+
+                    delta_llm = torch.tensor(
+                        E_llm_prop - E_llm_cur,
+                        device=temperature.device
+                    )
+
+                    # Normalize relative to model energy scale
+                    scale_est = torch.abs(delta_model.detach()) + 1e-6
+
+                    if not self.llm_scale_initialized:
+                        self.llm_scale = scale_est ** 2
+                        self.llm_scale_initialized = True
+                    else:
+                        self.llm_scale = 0.97 * self.llm_scale + 0.03 * (delta_model ** 2)
+
+                    scale = torch.sqrt(self.llm_scale + 1e-6)
+
+                    delta_llm = delta_llm / scale
+
+                    # consistent bound
+                    bound = torch.abs(delta_model.detach()) / scale + 1e-6
+                    delta_llm = torch.clamp(delta_llm, -bound, bound)
+
+                    delta_total = delta_model + self.lambda_llm * delta_llm
+
+                    if debug:
+                        print(
+                            f"[Debug] d_model={delta_model.item():.4f}, "
+                            f"d_llm={delta_llm.item():.4f}"
+                        )
+
+            # Numerical stability for exponentiation
+            delta_total = torch.clamp(delta_total, -10.0, 10.0)
+
+            accept_prob = torch.minimum(
+                torch.tensor(1.0, device=delta_total.device),
+                torch.exp(-delta_total)
+            )
+
+            rand_val = torch.rand(1, device=temperature.device)
+
+            if rand_val < accept_prob:
+                refined_state[ideal] = proposed_sample
+                accepted_count += 1
+                accepted = True
+            else:
+                accepted = False
+
+            if debug:
+                status = "ACCEPT" if accepted else "REJECT"
+                print(
+                    f"[Step] Sample={ideal} | {status} | "
+                    f"d_model={delta_model.item():.3f} | "
+                    f"d_total={delta_total.item():.3f} | "
+                    f"p={accept_prob.item():.3f}"
+                )
+
+        if debug:
+            print("\n[LLM Summary]")
+            print(f"LLM used  : {llm_usage_count}/{batch_size}")
+            print(f"Accepted  : {accepted_count}/{k}")
+            print(f"T         : {temperature:.4f}")
+            print("[LLM Done]\n", flush=True)
+
+        return refined_state
+
+    @torch.no_grad()
+    def save_ensemble_samples(
+            self,
+            filename="samples_ensemble.png",
+            n_display=100,
+            steps=10000,
+            energy_tracker=None,
+            client=None
+    ):
+        samples = self.generate_ensemble_samples(
+            n_chains=n_display,
+            steps=steps,
+            energy_tracker=energy_tracker
+        )
+
+        samples_original = samples.clone().detach()
+
+        samples = self.llm_uncertainty_refinement(samples, client=client)
+
+        refiner = Refinement(self)
+
+        samples = refiner.myra_refine(samples)
+
+        samples = samples.view(-1, 1, 28, 28)
+        original_tmp = samples_original.view(-1, 1, 28, 28)
+
+        chi_final = susceptibility(samples)
+        chi_raw = susceptibility(original_tmp)
+
+        binder_final = binder_cumulant(samples)
+        binder_raw = binder_cumulant(original_tmp)
+
+        print("\nPhysical Refinement Diagnostics:", chi_final)
+
+        print("Binder cumulant (1):", binder_final)
+        print("Chi improvement:", chi_final - chi_raw)
+
+        print("Binder improvement:", binder_final - binder_raw)
+
+        grid = vutils.make_grid(
+            samples,
+            nrow=50,
+            padding=2
+        )
+
+        grid = (grid * 255).clamp(0, 255).byte()
+        nd_arr = grid.permute(1, 2, 0).cpu().numpy()
+
+        Image.fromarray(nd_arr).save(
+            filename.replace(".png", "_refined.png")
+        )
+
+        grid_0 = vutils.make_grid(
+            original_tmp,
+            nrow=50,
+            padding=2
+        )
+
+        grid_0 = (grid_0 * 255).clamp(0, 255).byte()
+        nd_arr1 = grid_0.permute(1, 2, 0).cpu().numpy()
+
+        Image.fromarray(nd_arr1).save(
+            filename.replace(".png", "_symbol.png")
+        )
+
+    @torch.no_grad()
+    def ensemble_diagnostics(
+            self,
+            n_chains=1200,
+            steps=10000,
+            burn_in_ratio=0.2,
+            thinning=1,
+    ):
+        device = self.device
+        temperature = self.temperature()
+
+        # Initialize chains
+        visible = torch.bernoulli(
+            torch.full((n_chains, self.n_visible), 0.5, device=device)
+        )
+
+        energy_trace = []
+
+        # MCMC sampling
+        for step in range(steps):
+            hidden = torch.bernoulli(
+                torch.sigmoid((visible @ self.W + self.hidden_bias) / temperature)
+            )
+            visible = torch.bernoulli(
+                torch.sigmoid((hidden @ self.W.T + self.visible_bias) / temperature)
+            )
+
+            energy_trace.append(self.free_energy(visible, temperature).detach())
+
+        energy_trace = torch.stack(energy_trace)  # (time, chains)
+
+        # Burn-in removal
+        burn = int(burn_in_ratio * steps)
+        if burn >= steps - 10:
+            burn = 0
+
+        energy_trace = energy_trace[burn:]
+
+        # Thinning
+        energy_trace = energy_trace[::thinning]
+
+        n_steps, n_chains = energy_trace.shape
+
+        # Not enough data safeguard
+        max_lag = n_steps // 2
+        if max_lag < 2:
+            return {
+                "tau_int": float("nan"),
+                "tau_std": float("nan"),
+                "tau_max": float("nan"),
+                "tau_min": float("nan"),
+                "ess": float("nan"),
+                "r_hat": float("nan"),
+                "n_eff_per_chain": float("nan"),
+                "autocorr_len": 0
+            }
+
+        # Center per chain
+        centered = energy_trace - energy_trace.mean(dim=0, keepdim=True)
+        var = torch.var(centered, dim=0, unbiased=True)
+
+        # Degenerate case
+        if torch.mean(var) < 1e-12:
+            return {
+                "tau_int": float("inf"),
+                "tau_std": float("nan"),
+                "tau_max": float("inf"),
+                "tau_min": float("inf"),
+                "ess": 0.0,
+                "r_hat": float("inf"),
+                "n_eff_per_chain": 0.0,
+                "autocorr_len": 0
+            }
+
+        # Lag construction (corrected: includes dense small lags)
+        small_lags = torch.arange(1, min(20, max_lag + 1), device=device)
+
+        log_lags = torch.logspace(
+            0, math.log10(max_lag), steps=10, device=device
+        ).long()
+
+        lag_values = torch.unique(torch.cat([small_lags, log_lags])).sort()[0]
+
+        samples_per_lag = 10000
+        acf_list = []
+
+        # Stochastic ACF estimation
+        for lag in lag_values:
+            if lag == 0:
+                acf_list.append(torch.ones(n_chains, device=device))
+                continue
+
+            if lag >= n_steps:
+                break
+
+            idealization = torch.randint(0, n_steps - lag, (samples_per_lag,), device=device)
+
+            x_t = centered[idealization]
+            x_t_lag = centered[idealization + lag]
+
+            rho = (x_t * x_t_lag).mean(dim=0) / (var + 1e-12)
+
+            acf_list.append(rho)
+
+        acf_tensor = torch.stack(acf_list)
+
+        # Integrated autocorrelation time (IPS)
+        tau_per_chain = torch.ones(n_chains, device=device)
+        active = torch.ones(n_chains, dtype=torch.bool, device=device)
+
+        for k in range(1, acf_tensor.shape[0]):
+            rho = acf_tensor[k]
+
+            positive = rho > 0
+            update_mask = active & positive
+
+            tau_per_chain[update_mask] += 2.0 * rho[update_mask]
+
+            active = active & positive
+
+            if not active.any():
+                break
+
+        tau_mean = tau_per_chain.mean().item()
+        tau_std = tau_per_chain.std().item()
+        tau_max = tau_per_chain.max().item()
+        tau_min = tau_per_chain.min().item()
+
+        # Effective sample size
+        ess_per_chain = n_steps / (tau_per_chain + 1e-8)
+        total_ess = torch.sum(ess_per_chain).item()
+
+        # R-hat (split chains)
+        half = n_steps // 2
+
+        if half < 10:
+            r_hat = float("nan")
+        else:
+            first_half = energy_trace[:half]
+            second_half = energy_trace[half:2 * half]
+
+            split = torch.cat([first_half, second_half], dim=1)
+
+            n_half = split.shape[0]
+
+            chain_means = split.mean(dim=0)
+
+            B = n_half * torch.var(chain_means, unbiased=True)
+            W = torch.mean(torch.var(split, dim=0, unbiased=True))
+
+            var_hat = (1 - 1 / n_half) * W + (1 / n_half) * B
+
+            r_hat = torch.sqrt(var_hat / (W + 1e-12)).item()
+
+        return {
+            "tau_int": tau_mean,
+            "tau_std": tau_std,
+            "tau_max": tau_max,
+            "tau_min": tau_min,
+            "ess": float(total_ess),
+            "r_hat": float(r_hat),
+            "n_eff_per_chain": float(ess_per_chain.mean().item()),
+            "autocorr_len": int(acf_tensor.shape[0])
+        }
+
+    @torch.no_grad()
+    def save_professional_samples(
+            self,
+            filename="samples_professional.png",
+            n_display=100,
+            steps=10000,
+            energy_tracker=None,
+            client=None
+    ):
+        samples = self.generate_ensemble_samples(
+            n_chains=n_display,
+            steps=steps,
+            energy_tracker=energy_tracker
+        )
+
+        samples_original = samples.clone().detach()
+
+        samples = self.llm_uncertainty_refinement(samples, client=client)
+
+        refiner = Refinement(self)
+
+        samples = refiner.myra_refine(samples)
+
+        samples = samples.view(-1, 1, 28, 28)
+        original_tmp = samples_original.view(-1, 1, 28, 28)
+
+        diagnostics = self.ensemble_diagnostics()
+
+        chi_final = susceptibility(samples)
+        chi_raw = susceptibility(original_tmp)
+
+        binder_final = binder_cumulant(samples)
+        binder_raw = binder_cumulant(original_tmp)
+
+        print("\nSecondary magnetic susceptibility:", chi_final)
+
+        print("Binder cumulant (2):", binder_final)
+        print("Chi improvement:", chi_final - chi_raw)
+
+        print("Binder improvement:", binder_final - binder_raw)
+
+        grid = vutils.make_grid(
+            samples,
+            nrow=50,
+            padding=2
+        )
+
+        grid = (grid * 255).clamp(0, 255).byte()
+        nd_arr = grid.permute(1, 2, 0).cpu().numpy()
+
+        Image.fromarray(nd_arr).save(
+            filename.replace(".png", "_refined.png")
+        )
+
+        grid1 = vutils.make_grid(
+            original_tmp,
+            nrow=50,
+            padding=2
+        )
+
+        grid1 = (grid1 * 255).clamp(0, 255).byte()
+        nd_arr2 = grid1.permute(1, 2, 0).cpu().numpy()
+
+        Image.fromarray(nd_arr2).save(
+            filename.replace(".png", "_symbol.png")
+        )
+
+        return diagnostics
+
+    # Ais Calculation
+
+    @torch.no_grad()
+    def ais_log_partition(self, n_runs=1000, n_intermediate=2000, energy_tracker=None):
+
+        device = self.device
+        T = self.temperature().item()
+
+        W = self.W
+        bv = self.visible_bias
+        bh = self.hidden_bias
+
+        nv, nh = self.n_visible, self.n_hidden
+
+        betas = torch.linspace(0.0, 1.0, n_intermediate, device=device) ** 2
+
+        # Base model: uniform Bernoulli(0.5)
+
+        logZ0 = (nv + nh) * math.log(2.0)
+
+        v = torch.bernoulli(torch.full((n_runs, nv), 0.5, device=device))
+        h = torch.bernoulli(torch.full((n_runs, nh), 0.5, device=device))
+
+        log_weights = torch.zeros(n_runs, device=device)
+
+        for k in range(1, n_intermediate):
+            beta_prev = betas[k - 1]
+            beta_curr = betas[k]
+
+            energy = (- (v @ W * h).sum(1)
+                      - (v * bv).sum(1)
+                      - (h * bh).sum(1)
+                      ) / T
+            # SINGLE temperature scaling point
+
+            log_weights += (beta_curr - beta_prev) * energy
+
+            h_prob = torch.sigmoid(beta_curr * (v @ W + bh) / T)
+            h = torch.bernoulli(h_prob)
+
+            v_prob = torch.sigmoid(beta_curr * (h @ W.T + bv) / T)
+            v = torch.bernoulli(v_prob)
+
+            if energy_tracker is not None:
+                energy_tracker.step()
+
+        logZ = logZ0 + torch.logsumexp(log_weights, dim=0) - math.log(n_runs)
+
+        log_w = log_weights - torch.max(log_weights).detach()
+
+        w = torch.exp(log_w)
+        w = w / torch.sum(w)
+        ess = 1.0 / torch.sum(w ** 2)
+
+        log_weight_var = torch.var(log_weights)
+
+        return logZ.item(), log_weight_var.item(), ess.item()
+
+    # Log-Likelihood
+
+    @torch.no_grad()
+    def log_likelihood(self, data, log_Z_2ox):
+        T = self.temperature()
+        Fv = self.free_energy(data, T)
+
+        return (-Fv - log_Z_2ox).mean().item()
+
+    @torch.no_grad()
+    def pseudo_likelihood(self, data):
+        T = self.temperature()
+        W = self.W
+        b = self.visible_bias
+        h_bias = self.hidden_bias
+
+        N, D = data.shape
+
+        # hidden pre-activation
+        wx = (data @ W + h_bias) / T  # (N, H)
+
+        log_probs = []
+
+        for interaction in range(D):
+            v_i = data[:, interaction]  # (N,)
+            W_i = W[interaction]  # (H,)
+
+            # flip effect
+            delta = (1 - 2 * v_i).unsqueeze(1) * W_i / T
+            wx_flip = wx + delta
+
+            # free energy difference
+            term = torch.sum(
+                F.softplus(wx_flip) - F.softplus(wx),
+                dim=1
+            )
+
+            logits = (b[interaction] / T) + term
+
+            # log P(v_i | rest)
+            log_prob_i = -F.binary_cross_entropy_with_logits(
+                logits,
+                v_i,
+                reduction='none'
+            )
+
+            log_probs.append(log_prob_i)
+
+        # average over dimensions
+        log_prob = torch.stack(log_probs, dim=1).mean(dim=1)
+
+        print("coefficient (kappa):", D)
+
+        # average over batch
+        return log_prob.mean().item()
+
+    @torch.no_grad()
+    def reconstruct(self, v):
+
+        T = self.temperature()
+
+        h = torch.sigmoid((v @ self.W + self.hidden_bias) / T)
+        v_recon = torch.sigmoid((h @ self.W.T + self.visible_bias) / T)
+
+        return v_recon
+
+
+# Multi-GPU Worker
+
+def worker(Gpu_Id, seed_round, consequences):
+    client = SafeBookClient()
+    torch.cuda.set_device(Gpu_Id)
+    torch.manual_seed(seed_round)
+    torch.cuda.manual_seed_all(seed_round)
+    energy_tracker = GPUEnergyTracker(Gpu_Id)
+
+    device_warm = torch.device(f"cuda:{Gpu_Id}")
+
+    # Data
+
+    data = load_mnist(device_warm)
+
+    train_data_um = data[:60000]
+    test_data_um = data[60000:]
+
+    last_model = HybridThermodynamicRBM(
+        n_visible=784,
+        n_hidden=512,
+        device_type=f"cuda:{Gpu_Id}",
+        fixed_temperature=None
+    )
+
+    train_result = last_model.train(
+        train_data_um,
+        energy_tracker=energy_tracker
+    )
+
+    if train_result == "ABORT":
+        print("[WORKER] Training aborted early")
+        return
+
+    def dots_spinner(stop_event_choose, elastic_label):
+        """
+        Lightweight terminal spinner used to indicate that a diagnostic
+        computation is currently running.
+        """
+        frames = ["   ", ".  ", ".. ", "..."]
+
+        integer = 0
+
+        while not stop_event_choose.is_set():
+            sys.stdout.write(f"\r▶ {elastic_label}{frames[integer % len(frames)]}")
+            sys.stdout.flush()
+            time.sleep(0.4)
+
+            integer += 1
+
+    print(f"\n[GPU {Gpu_Id}] Running AIS...")
+
+    stop_event = threading.Event()
+
+    spinner_thread = threading.Thread(target=dots_spinner, args=(stop_event, "AIS"))
+    spinner_thread.start()
+
+    ais_start = time.time()
+
+    try:
+        log_Z_3ox, ais_var, ais_ess = last_model.ais_log_partition(
+            n_runs=8000,
+            n_intermediate=12000,
+            energy_tracker=energy_tracker
+        )
+    except Exception as emerald:
+        print(f"\n✖ AIS failed: {emerald}")
+
+        log_Z_3ox, ais_var, ais_ess = float("nan"), float("nan"), float("nan")
+
+    ais_duration = time.time() - ais_start
+
+    stop_event.set()
+    spinner_thread.join()
+
+    sys.stdout.write(f"\r✔ AIS finished in {ais_duration:.2f} seconds\n")
+
+    train_ll = last_model.log_likelihood(train_data_um, log_Z_3ox)
+    Test_ll = last_model.log_likelihood(test_data_um, log_Z_3ox)
+    Train_pl = last_model.pseudo_likelihood(train_data_um)
+    Test_pl = last_model.pseudo_likelihood(test_data_um)
+
+    # Reconstruction
+
+    reconstruction = last_model.reconstruct(test_data_um)
+
+    reconstruction_mse = torch.mean(
+        (test_data_um - reconstruction) ** 2
+    ).item()
+
+    recon_acc = last_model.reconstruction_accuracy(test_data_um)
+
+    # Thermodynamic diagnostics
+
+    final_temperature = last_model.temperature().item()
+    weight_norm = torch.norm(last_model.W).item()
+
+    gain_spectral = weight_norm / final_temperature
+
+    sample_filename = f"samples_gpu{Gpu_Id}_seed{seed_round}.png"
+    prof_filename = f"samples_prof_gpu{Gpu_Id}_seed{seed_round}.png"
+
+    # Basit ensemble save
+
+    last_model.save_ensemble_samples(
+        filename=sample_filename,
+        n_display=1200,
+        steps=10000,
+        energy_tracker=energy_tracker,
+        client=client
+    )
+
+    # Professional ensemble + diagnostics
+
+    diagnostics = last_model.save_professional_samples(
+        filename=prof_filename,
+        n_display=1200,
+        steps=10000,
+        energy_tracker=energy_tracker,
+        client=client
+    )
+
+    print("\nRunning energy analysis ↓\n")
+
+    analysis_steps = [
+
+        ("Energy distribution",
+         lambda: SrtrbmEnergy.plot_data_vs_model_energy(last_model, train_data_um)),
+
+        ("Energy landscape extremes",
+         lambda: SrtrbmEnergy.visualize_energy_extremes(last_model, train_data_um)),
+
+        ("Phase diagram",
+         lambda: SrtrbmMetrics.plot_flip_beta(
+             last_model,
+             "SR-TRBM Phase Diagram",
+             filename="srtrbm_phase_diagram.pdf"
+         )),
+
+        ("RBM filters",
+         lambda: SrtrbmVisualization.visualize_rbm_filters(
+             last_model,
+             filename="srtrbm_filters.png",
+             n_filters=256
+         )),
+
+        ("Sample quality metrics",
+         lambda: SrtrbmMetrics.sample_quality_metrics(last_model, train_data_um)),
+    ]
+
+    quality = None
+    energy_stats = None
+
+    print("\nRunning diagnostics with the following calculations ↙\n")
+
+    total_start = time.time()
+
+    for name, fn in analysis_steps:
+
+        stop_event = threading.Event()
+        spinner_thread = threading.Thread(target=dots_spinner, args=(stop_event, name))
+        spinner_thread.start()
+        start = time.time()
+
+        try:
+            result_cache = fn()
+        except Exception as emerald:
+
+            print(f"\n✖ {name} failed:", emerald)
+
+            result_cache = None
+
+        duration = time.time() - start
+
+        stop_event.set()
+        spinner_thread.join()
+
+        sys.stdout.write(f"\r✔ {name} finished in {duration:.2f} seconds\n")
+
+        if name == "Energy distribution" and result_cache is not None:
+            energy_stats = result_cache
+        if name == "Sample quality metrics":
+            quality = result_cache
+
+    total_time = time.time() - total_start
+
+    print(f"\nDiagnostics completed in {total_time:.2f} seconds\n")
+
+    if quality is None:
+        quality = {
+            "pixel_entropy": float("nan"),
+            "diversity": float("nan"),
+            "mean_l2": float("nan")
+        }
+
+    if energy_stats is None:
+        energy_stats = {
+            "mean_data_energy": float("nan"),
+            "mean_model_energy": float("nan"),
+            "energy_gap": float("nan")
+        }
+
+    gpu_energy = energy_tracker.total_energy()
+
+    print(f"GPU Energy Used : {gpu_energy:.2f} Joules\n")
+
+    consequences.append({
+        "seed": seed_round,
+        "gpu": Gpu_Id,
+        "gpu_energy": gpu_energy,
+        "temperature": final_temperature,
+        "weight_norm": weight_norm,
+        "spectral_gain": gain_spectral,
+        "train_log_likelihood": train_ll,
+        "test_log_likelihood": Test_ll,
+        "train_pseudo_likelihood": Train_pl,
+        "test_pseudo_likelihood": Test_pl,
+        "reconstruction_mse": reconstruction_mse,
+        "reconstruction_accuracy": recon_acc,
+        "mean_data_energy": energy_stats["mean_data_energy"],
+        "mean_model_energy": energy_stats["mean_model_energy"],
+        "energy_gap": energy_stats["energy_gap"],
+        "logZ": log_Z_3ox,
+        "ais_ess": ais_ess,
+        "pixel_entropy": quality["pixel_entropy"],
+        "diversity": quality["diversity"],
+        "mean_l2": quality["mean_l2"],
+        "ais_log_weight_variance": ais_var,
+        "mcmc_tau_int": diagnostics["tau_int"],
+        "mcmc_tau_std": diagnostics["tau_std"],  # heterogeneity
+        "mcmc_tau_max": diagnostics["tau_max"],  # worst-case chain
+        "mcmc_tau_min": diagnostics["tau_min"],  # fastest chain
+        "mcmc_ess": diagnostics["ess"],
+        "mcmc_ess_per_chain": diagnostics["n_eff_per_chain"],
+        "mcmc_r_hat": diagnostics["r_hat"],
+        "mcmc_acf_len": diagnostics["autocorr_len"],
+        "prof_sample_file": prof_filename,
+        "sample_file": sample_filename
+    })
+
+    plt.figure(figsize=(10, 12))
+
+    # Flip rate
+
+    plt.subplot(3, 1, 1)
+    plt.plot(last_model.flip_hist, linewidth=2, label="Flip rate")
+    plt.plot(last_model.c_hist, linestyle="--", linewidth=2, label="Adaptive reference")
+    plt.title("Microscopic Flip Dynamics")
+    plt.ylabel("Flip Rate")
+    plt.grid(alpha=0.3)
+    plt.legend()
+
+    # Temperature evolution
+
+    plt.subplot(3, 1, 2)
+    plt.plot(last_model.temp_hist, linewidth=2)
+    plt.title(r"Global Temperature $T$")
+    plt.ylabel("Temperature")
+    plt.grid(alpha=0.3)
+
+    # Micro vs Macro
+
+    plt.subplot(3, 1, 3)
+    plt.plot(last_model.T_micro_hist, linewidth=2, label=r"$T_{micro}$")
+    plt.plot(last_model.T_macro_hist, linewidth=2, label=r"$T_{macro}$")
+    plt.title("Micro–Macro Temperature Decomposition")
+    plt.xlabel("Epoch")
+    plt.ylabel("Temperature Components")
+    plt.grid(alpha=0.3)
+    plt.legend()
+
+    plt.tight_layout()
+    plt.savefig("srtrbm_core_dynamics.pdf", bbox_inches="tight")
+    plt.close()
+
+    # Energy & Spectral Diagnostics
+
+    plt.figure(figsize=(10, 14))
+
+    # Weight norm
+
+    plt.subplot(4, 1, 1)
+    plt.plot(last_model.weight_norm_hist, linewidth=2)
+    plt.title("Weight Norm Evolution")
+    plt.ylabel(r"$||W||$")
+    plt.grid(alpha=0.3)
+
+    # Effective beta
+
+    plt.subplot(4, 1, 2)
+    plt.plot(last_model.beta_eff_hist, linewidth=2)
+    plt.title(r"Effective Inverse Temperature $\beta_{\mathrm{eff}}$")
+    plt.ylabel(r"$\beta_{\mathrm{eff}}$")
+    plt.grid(alpha=0.3)
+
+    # Free energy comparison
+
+    plt.subplot(4, 1, 3)
+    plt.plot(last_model.F_data_hist, linewidth=2, label=r"$F_{data}$")
+    plt.plot(last_model.F_model_hist, linewidth=2, label=r"$F_{model}$")
+    plt.title("Free Energy: Data vs Model")
+    plt.ylabel("Free Energy")
+    plt.grid(alpha=0.3)
+    plt.legend()
+
+    # Spectral beta
+
+    plt.subplot(4, 1, 4)
+    plt.plot(last_model.spectral_beta_hist)
+
+    plt.axhline(1.0, linestyle="--")
+
+    plt.title(r"Spectral Inverse Temperature $\beta_{spectral}$")
+    plt.xlabel("Epoch")
+    plt.ylabel(r"$\beta_{spectral}$")
+    plt.grid(alpha=0.3)
+
+    plt.tight_layout()
+    plt.savefig("srtrbm_energy_diagnostics.pdf", bbox_inches="tight")
+    plt.close()
+
+    sample_refined = sample_filename.replace(".png", "_refined.png")
+    prof_refined = prof_filename.replace(".png", "_refined.png")
+
+    samples_for_phase = last_model.generate_ensemble_samples(n_chains=1200, steps=10000)
+    samples_for_phase = samples_for_phase.view(-1, 1, 28, 28)
+
+    chi = susceptibility(samples_for_phase)
+
+    llm_metrics = {
+        "temperature": float(final_temperature),
+        "spectral_gain": float(gain_spectral),
+        "energy_gap": float(energy_stats["energy_gap"]),
+
+        "quality": {
+            "diversity": float(quality["diversity"]),
+            "entropy": float(quality["pixel_entropy"])
+        },
+
+        "sampling": {
+            "mcmc_tau_int": float(diagnostics["tau_int"])
+        },
+
+        "trend": {
+            "temp_slope": float(last_model.temp_hist[-1] - last_model.temp_hist[0]),
+            "beta_slope": float(last_model.beta_eff_hist[-1] - last_model.beta_eff_hist[0])
+        },
+
+        "phase": {
+            "susceptibility": float(chi)
+        },
+
+        "history": {
+            "gap_trend": float(last_model.F_gap_hist[-1] - last_model.F_gap_hist[0]),
+            "entropy_trend": float(last_model.persistent_div_hist[-1] - last_model.persistent_div_hist[0]),
+            "temp_trend": float(last_model.temp_hist[-1] - last_model.temp_hist[0]),
+            "beta_trend": float(last_model.beta_eff_hist[-1] - last_model.beta_eff_hist[0]),
+
+            "gap_std": float(np.std(last_model.F_gap_hist)),
+            "entropy_std": float(np.std(last_model.persistent_div_hist)),
+            "temp_std": float(np.std(last_model.temp_hist)),
+
+            "current": {
+                "entropy": float(last_model.persistent_div_hist[-1]),
+                "temperature": float(last_model.temp_hist[-1]),
+                "beta": float(last_model.beta_eff_hist[-1]),
+                "gap": float(last_model.F_gap_hist[-1])
+            },
+
+            "learning_signal": float(last_model.delta_w_hist[-1]),
+
+            "stagnation": bool(last_model.delta_w_hist[-1] < 1e-4),
+            "learning_active": bool(last_model.delta_w_hist[-1] > 1e-4),
+
+            "cooling": bool(last_model.temp_hist[-1] < last_model.temp_hist[0]),
+            "heating": bool(last_model.temp_hist[-1] > last_model.temp_hist[0]),
+
+            "trend_signature": [
+                float(np.sign(last_model.F_gap_hist[-1] - last_model.F_gap_hist[0])),
+                float(np.sign(last_model.persistent_div_hist[-1] - last_model.persistent_div_hist[0])),
+                float(np.sign(last_model.temp_hist[-1] - last_model.temp_hist[0]))
+            ]
+        }
+    }
+
+    subprocess.run([
+        "python3",
+        "supplement/cluster.py",
+        sample_refined,
+        sample_refined.replace("_refined.png", "_perfect.png")
+    ])
+
+    subprocess.run([
+        "python3",
+        "supplement/cluster.py",
+        prof_refined,
+        prof_refined.replace("_refined.png", "_perfect.png")
+    ])
+
+    prof_perfect = prof_refined.replace("_refined.png", "_perfect.png")
+
+    output_json = f"llm_output_gpu{Gpu_Id}_seed{seed_round}.json"
+
+    consequence = Evaluate(
+        llm_metrics,
+        prof_refined,
+        prof_perfect,
+        client=client
+    )
+
+    analysis_signal = ANASIS(consequence.get("analysis", ""))
+
+    print(f"[ANALYSIS SIGNAL] {analysis_signal:.3f}")
+
+    with open(output_json, "w", encoding="utf-8") as f:
+        json.dump(consequence, f, indent=2, ensure_ascii=False)
+
+    print(f"[LLM OUTPUT SAVED] → {output_json}")
+
+    print("\n[LLM RESULT]\n")
+
+    json_text = json.dumps(consequence, indent=2, ensure_ascii=False)
+
+    for line in json_text.split("\n"):
+        wrapped_lines = textwrap.wrap(line, width=90) or [""]
+
+        for word_line in wrapped_lines:
+            print(word_line)
+            sys.stdout.flush()
+            time.sleep(0.005)
+
+
+# Main Section
+
+if __name__ == "__main__":
+    mp.set_start_method("spawn", force=True)
+    available_gpus = torch.cuda.device_count()
+
+    seeds = [1]
+
+    if available_gpus < len(seeds):
+        raise RuntimeError("Not enough GPUs available.")
+
+    manager = mp.Manager()
+    results = manager.list()
+
+    processes = []
+
+    for gpu_id, seed in enumerate(seeds):
+        p = mp.Process(
+            target=worker,
+            args=(gpu_id, seed, results)
+        )
+
+        p.start()
+
+        processes.append(p)
+
+    for p in processes:
+        p.join()
+
+    print("Hybrid Thermodynamic RBM Final Results")
+
+    for result in list(results):
+        print(f"Seed: {result['seed']} | GPU: {result['gpu']}")
+        print(f"Final Temperature        : {result['temperature']:.6f}")
+        print(f"Weight Norm              : {result['weight_norm']:.6f}")
+        print(f"Spectral Gain            : {result['spectral_gain']:.6f}")
+        print(f"Train Log-Likelihood     : {result['train_log_likelihood']:.6f}")
+        print(f"Test Log-Likelihood      : {result['test_log_likelihood']:.6f}")
+        print(f"Train Pseudo-Likelihood  : {result['train_pseudo_likelihood']:.6f}")
+        print(f"Test Pseudo-Likelihood   : {result['test_pseudo_likelihood']:.6f}")
+        print(f"Reconstruction MSE       : {result['reconstruction_mse']:.6f}")
+        print(f"Reconstruction Accuracy  : {result['reconstruction_accuracy']:.6f}")
+        print(f"Mean Data Energy         : {result['mean_data_energy']:.6f}")
+        print(f"Mean Model Energy        : {result['mean_model_energy']:.6f}")
+        print(f"Energy Gap               : {result['energy_gap']:.6f}")
+        print(f"GPU Energy Used          : {result['gpu_energy']:.2f} J")
+        print(f"Log Partition (AIS)      : {result['logZ']:.6f}")
+        print(f"AIS ESS                  : {result['ais_ess']:.2f}")
+        print(f"AIS Log-Weight Variance  : {result['ais_log_weight_variance']:.6f}")
+        print(f"MCMC tau_int             : {result['mcmc_tau_int']:.2f}")
+        print(f"MCMC tau_std             : {result['mcmc_tau_std']:.2f}")
+        print(f"MCMC tau_max             : {result['mcmc_tau_max']:.2f}")
+        print(f"MCMC tau_min             : {result['mcmc_tau_min']:.2f}")
+        print(f"MCMC ESS                 : {result['mcmc_ess']:.2f}")
+        print(f"MCMC ESS / chain         : {result['mcmc_ess_per_chain']:.2f}")
+        print(f"MCMC R-hat               : {result['mcmc_r_hat']:.4f}")
+        print(f"MCMC ACF length          : {result['mcmc_acf_len']}")
+        print(f"Pixel Entropy            : {result['pixel_entropy']:.6f}")
+        print(f"Sample Diversity         : {result['diversity']:.6f}")
+        print(f"Mean Distribution L2     : {result['mean_l2']:.6f}")
+        print(f"Professional Samples File: {result['prof_sample_file']}")
+        print(f"Generated Samples File   : {result['sample_file']}")
+
+        print()
+
+# MYRA: A Feedback-Controlled Thermodynamic RBM for Hybrid Intelligence

stan.dgts

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7e46c191e61e65b2c38514ccbd3d25519528ed02c7a30598e7b95171674bbe3f
+size 188641741

supplement/cluster.py

@@ -0,0 +1,300 @@
+import sys
+import cv2
+import math
+import torch
+import numpy as np
+from PIL import Image
+import torch.nn as nn
+import torch.nn.functional as F
+
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+print("Device:", device)
+
+
+class ResidualBlock(nn.Module):
+    def __init__(self, in_ch, out_ch, stride=1):
+        super().__init__()
+
+        self.first_convolution = nn.Conv2d(in_ch, out_ch, 3, stride=stride, padding=1, bias=False)
+        self.first_normalization = nn.BatchNorm2d(out_ch)
+
+        self.second_convolution = nn.Conv2d(out_ch, out_ch, 3, padding=1, bias=False)
+        self.second_normalization = nn.BatchNorm2d(out_ch)
+
+        if in_ch != out_ch or stride != 1:
+            self.residual_projection = nn.Sequential(
+                nn.Conv2d(in_ch, out_ch, 1, stride=stride, bias=False),
+                nn.BatchNorm2d(out_ch)
+            )
+        else:
+            self.residual_projection = nn.Identity()
+
+    def forward(self, xerox):
+        identity = self.residual_projection(xerox)
+
+        out = self.first_convolution(xerox)
+        out = self.first_normalization(out)
+        out = F.relu(out)
+
+        out = self.second_convolution(out)
+        out = self.second_normalization(out)
+
+        out += identity
+        out = F.relu(out)
+
+        return out
+
+
+class MNISTEmbeddingModel(nn.Module):
+    def __init__(self):
+        super().__init__()
+
+        self.first_residual_stage = ResidualBlock(1, 32, stride=1)
+        self.second_residual_stage = ResidualBlock(32, 64, stride=2)
+        self.third_residual_stage = ResidualBlock(64, 128, stride=2)
+
+        self.global_pool = nn.AdaptiveAvgPool2d((1, 1))
+
+        self.embedding_projection_layer = nn.Linear(128, 256)
+        self.classification_layer = nn.Linear(256, 10, bias=False)
+
+    def forward(self, xcode):
+        xcode = self.first_residual_stage(xcode)
+        xcode = self.second_residual_stage(xcode)
+        xcode = self.third_residual_stage(xcode)
+
+        xcode = self.global_pool(xcode)
+        xcode = torch.flatten(xcode, 1)
+
+        embedding = F.normalize(self.embedding_projection_layer(xcode), dim=1)
+
+        W = F.normalize(self.classification_layer.weight, dim=1)
+        logit = embedding @ W.T
+
+        return logit
+
+    def get_embedding(self, x):
+        x = self.first_residual_stage(x)
+        x = self.second_residual_stage(x)
+        x = self.third_residual_stage(x)
+
+        x = self.global_pool(x)
+        x = torch.flatten(x, 1)
+
+        embedding = F.normalize(self.embedding_projection_layer(x), dim=1)
+        return embedding
+
+
+model = MNISTEmbeddingModel().to(device)
+
+ckpt = torch.load("zeta_mnist_hybrid.pt", map_location=device, weights_only=False)
+
+if "model_state" in ckpt:
+    raw_state = ckpt["model_state"]
+else:
+    raw_state = ckpt
+
+mapped = {}
+
+for k, v in raw_state.items():
+    nk = k
+
+    nk = nk.replace("block1", "first_residual_stage")
+    nk = nk.replace("block2", "second_residual_stage")
+    nk = nk.replace("block3", "third_residual_stage")
+
+    nk = nk.replace("conv1", "first_convolution")
+    nk = nk.replace("conv2", "second_convolution")
+
+    nk = nk.replace("bn1", "first_normalization")
+    nk = nk.replace("bn2", "second_normalization")
+
+    nk = nk.replace("shortcut", "residual_projection")
+
+    nk = nk.replace("embedding", "embedding_projection_layer")
+    nk = nk.replace("fc", "classification_layer")
+
+    nk = nk.replace("fc1", "embedding_projection_layer")
+    nk = nk.replace("fc2", "classification_layer")
+
+    mapped[nk] = v
+
+model.load_state_dict(mapped, strict=True)
+model.eval()
+
+data = torch.load("stan.dgts", map_location="cpu")
+images = data["images"].float()
+labels = data["labels"]
+
+if images.max() > 1:
+    images /= 255.0
+
+reference_bank = []
+
+SAMPLES_PER_CLASS = 6
+
+for d in range(10):
+    cls = images[labels == d]
+
+    center = cls.mean(dim=0, keepdim=True)
+    dists = ((cls - center) ** 2).mean(dim=(1, 2))
+
+    best = torch.argsort(dists)[:SAMPLES_PER_CLASS]
+    reference_bank.append(cls[best].to(device))
+
+print(", ↘\n")
+
+reference_embeddings = []
+
+with torch.no_grad():
+    for d in range(10):
+        emb = model.get_embedding(reference_bank[d].unsqueeze(1))
+        reference_embeddings.append(emb)
+
+
+def normalize_digit(patchX):
+    patchX = torch.tensor(patchX).float()
+
+    threshold_omega = patchX.mean()
+    maskY = patchX > threshold_omega
+
+    if maskY.sum() == 0:
+        return patchX.numpy()
+
+    coordinates0 = maskY.nonzero()
+    y0, x0 = coordinates0.min(dim=0).values
+    y1, x1 = coordinates0.max(dim=0).values + 1
+
+    digits = patchX[y0:y1, x0:x1]
+
+    digits = digits.unsqueeze(0).unsqueeze(0)
+    digits = F.interpolate(digits, size=(20, 20), mode='bilinear', align_corners=False)
+    digits = digits.squeeze()
+
+    canvasX = torch.zeros(28, 28)
+    canvasX[4:24, 4:24] = digits
+
+    return canvasX.numpy()
+
+
+def process_image(input_paths, output_paths):
+    image = Image.open(input_paths).convert("L")
+    image = np.array(image).astype(np.float32) / 255.0
+
+    patch_size = 29
+    step = 30
+
+    patches = []
+    coordinates = []
+
+    for y1 in range(0, image.shape[0] - patch_size + 1, step):
+        for x1 in range(0, image.shape[1] - patch_size + 1, step):
+
+            patch = image[y1:y1 + 28, x1:x1 + 28]
+
+            if patch.mean() < 0.005:
+                continue
+
+            patch = normalize_digit(patch)
+
+            patches.append(patch)
+            coordinates.append((y1, x1))
+
+    if len(patches) == 0:
+        print(f"{input_paths} → No valid patches")
+        return
+
+    patches = torch.from_numpy(np.stack(patches)).unsqueeze(1).to(device)
+    print(f"{input_paths} → Patches:", patches.shape)
+
+    with torch.no_grad():
+        logits_variable = model(patches)
+
+        probs = torch.softmax(logits_variable, dim=1)
+        conf, predictions = torch.max(probs, dim=1)
+
+    canvas = np.zeros(image.shape, dtype=np.float32)
+    mse_values = []
+
+    for integer, (y1, x1) in enumerate(coordinates):
+
+        top2 = torch.topk(probs[integer], 2)
+
+        if conf[integer] < 0.8 or (top2.values[0] - top2.values[1]) < 0.2:
+            patch_tensor = patches[integer].unsqueeze(0)
+
+            with torch.no_grad():
+                emb_patch = model.get_embedding(patch_tensor)
+
+            sims = []
+            for domino in range(10):
+                emb_bank = reference_embeddings[domino]
+                sims_matrix = torch.matmul(emb_patch, emb_bank.T)
+                sim = torch.logsumexp(sims_matrix / 0.1, dim=1).item()
+                sims.append(sim)
+
+            digit = int(np.argmax(sims))
+        else:
+            digit = predictions[integer].item()
+
+        bank = reference_bank[digit]
+        patch = patches[integer]  # (1,28,28)
+
+        distance = ((patch - bank) ** 2).mean(dim=(1, 2))
+
+        best_idx = torch.argmin(distance)
+
+        best_img = bank[best_idx].cpu().numpy()
+
+        _, bw = cv2.threshold(best_img, 0.2, 1.0, cv2.THRESH_BINARY)
+
+        num_labels, elastic, stats, _ = cv2.connectedComponentsWithStats((bw * 255).astype(np.uint8))
+
+        clean = np.zeros_like(best_img)
+
+        for into in range(1, num_labels):
+            if stats[into, cv2.CC_STAT_AREA] > 20:
+                clean[elastic == into] = 1.0
+
+        best_img = clean
+
+        with torch.no_grad():
+            emb_patch = model.get_embedding(patch.unsqueeze(0))
+
+            emb_best = model.get_embedding(
+                torch.from_numpy(best_img).to(device).unsqueeze(0).unsqueeze(0)
+            )
+
+        sim = torch.matmul(emb_patch, emb_best.T).item()
+
+        alpha = (sim + 1) / 2
+
+        original = patch.squeeze(0).cpu().numpy()
+
+        blended = alpha * best_img + (1 - alpha) * original
+
+        canvas[y1:y1 + 28, x1:x1 + 28] = blended
+
+        original = patch.squeeze(0).cpu().numpy()
+
+        mse = ((original - best_img) ** 2).mean()
+        mse_values.append(mse)
+
+    print(f"{input_paths} → Avg MSE:", sum(mse_values) / len(mse_values))
+
+    output = (canvas * 255).astype(np.uint8)
+    Image.fromarray(output).save(output_paths)
+
+    print(f"Saved: {output_paths}\n")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 3:
+        print("Usage: python3 cluster.py <input> <output>")
+        sys.exit(1)
+
+    input_path = sys.argv[1]
+
+    output_path = sys.argv[2]
+
+    process_image(input_path, output_path)

yaml/perception.yaml

@@ -0,0 +1,53 @@
+core:
+
+  image_semantics:
+    title: "IMAGE SEMANTICS (X vs Y)"
+
+    description: >
+      X represents the refined model output, reflecting what the system has learned.
+      Y represents the perfect reference, defining the target structural manifold.
+
+    rules:
+      - "X = refined output (learned structural expression)."
+      - "Y = perfect reference (ground-truth structural manifold)."
+      - "Y defines the expected diversity and structural space."
+      - "Evaluation depends on whether distinct structural configurations in Y are preserved as distinct representations in X."
+
+  structural_mode_principle:
+    priority: "hard_constraint"
+    title: "STRUCTURAL MODE PRINCIPLE"
+
+    description: >
+      Modes are defined by probabilistic structural equivalence, not superficial visual similarity.
+
+    rules:
+      - "Each sample consists of local structural elements (strokes, curves, segments, junctions)."
+      - "Two samples belong to the same mode if their elements align with high probability across the structure."
+      - "Consistent structural differences imply different modes."
+      - "Minor noise or insignificant variations do not define new modes."
+      - "Visual similarity is a weak signal and must not override structural or statistical evidence."
+      - "Mode identity depends on the distribution and organization of structural elements."
+
+  x_y_reasoning:
+    title: "STRUCTURAL COVERAGE REASONING"
+
+    description: >
+      Determine whether the learned representation (X) sufficiently captures the structural diversity defined by the reference manifold (Y).
+
+    rules:
+      - "If structures in X align with those in Y across diverse regions, modes are captured."
+      - "If multiple distinct structures in Y collapse into fewer representations in X, mode collapse or under-representation is likely."
+      - "If structural distinctions in Y are preserved in X, multiple modes are present."
+      - "If diversity in X is significantly lower than in Y, this indicates loss of modes."
+
+  refined_projection_principle:
+    title: "REFINED AS STRUCTURAL PROJECTION"
+
+    description: >
+      Refinement acts as a projection that reveals the true structural organization of samples.
+
+    rules:
+      - "Refinement exposes fine-grained structural variation."
+      - "Samples that appear similar before refinement may differ structurally after refinement."
+      - "If samples converge to similar structures after refinement, they likely belong to the same mode."
+      - "If they remain structurally distinct, they represent different modes."

zeta_mnist_hybrid.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:81f10f7049d6b7f0721eed7f0d16b0af15f741f6ea363a6baf30d3a62ae26d14
+size 1370347