neuroplot 0.1.1__tar.gz → 0.1.2__tar.gz

{neuroplot-0.1.1 → neuroplot-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: neuroplot
-Version: 0.1.1
+Version: 0.1.2
 Summary: A lightweight, modular real-time visualization and diagnostics library for PyTorch.
 Description-Content-Type: text/markdown
 Requires-Dist: torch

neuroplot-0.1.2/neuroplot/README.md

@@ -0,0 +1,68 @@
+# NeuroPlot 🧠📊
+A lightweight, modular real-time training telemetry and visualization library for PyTorch.
+
+NeuroPlot provides live, multi-panel diagnostic monitoring during your training loops—allowing you to track decision boundaries, latent space representations, loss curves, and accuracy metrics seamlessly.
+
+## Features
+- Live Multi-Panel Dashboard: Watch decision boundaries and latent spaces evolve in real-time alongside loss and accuracy curves.
+- Automatic GIF Compilation: Automatically capture training progress and compile it into a clean GIF.
+- Best-Model Checkpointing: Automatically track and save the best-performing model weights.
+
+## Installation
+pip install neuroplot
+
+## Quick Start Usage Guide
+import torch
+import torch.nn as nn
+import torch.optim as optim
+import sklearn.datasets as datasets
+from neuroplot import LiveVisualizer
+
+# 1. Prepare data and model
+X, y = datasets.make_moons(n_samples=100, noise=0.1)
+x = torch.tensor(X, dtype=torch.float32)
+y = torch.tensor(y, dtype=torch.float32).view(-1, 1)
+
+class Moon_MLP(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.fc1 = nn.Linear(2, 8)
+        self.fc2 = nn.Linear(8, 8)
+        self.fc3 = nn.Linear(8, 1)
+
+    def forward(self, x):
+        x = torch.relu(self.fc1(x))
+        x = torch.relu(self.fc2(x))
+        x = torch.sigmoid(self.fc3(x))
+        return x
+
+model = Moon_MLP()
+optimizer = optim.Adam(model.parameters(), lr=0.01)
+
+# 2. Initialize NeuroPlot
+viz = LiveVisualizer(
+    plots=["boundary", "latent", "loss", "accuracy"], 
+    model=model, 
+    data=(x, y), 
+    update_every=50,
+    save_gif=True,
+    gif_name="neuroplot_demo.gif",
+    save_best_model=True,
+    checkpoint_path="best_model.pth"
+)
+
+# 3. Training Loop
+for epoch in range(1000):
+    y_pred = model(x)
+    loss = nn.BCELoss()(y_pred, y)
+    
+    preds = (y_pred >= 0.5).float()
+    acc = (preds == y).float().mean().item()
+
+    optimizer.zero_grad()
+    loss.backward()
+    optimizer.step()
+
+    viz.step(epoch, loss=loss.item(), accuracy=acc)
+
+viz.close()

{neuroplot-0.1.1 → neuroplot-0.1.2}/neuroplot/visualizer.py

@@ -1,10 +1,21 @@
 # import necessary libraries
 import torch
 import torch.nn as nn
+import matplotlib
 import matplotlib.pyplot as plt
 import numpy as np
 import os
 import tempfile
+import sys
+
+# --- FEATURE: Headless Fallback ---
+if not os.environ.get('DISPLAY') and sys.platform != 'darwin':
+    matplotlib.use('Agg')
+else:
+    try:
+        plt.ion()
+    except Exception:
+        matplotlib.use('Agg')
 
 try:
     import imageio
@@ -16,7 +27,7 @@ class LiveVisualizer:
     def __init__(self, plots, model=None, data=None, update_every=50, 
                  save_gif=False, gif_name="training_progress.gif",
                  save_best_model=False, checkpoint_path="best_model.pth",
-                 smooth_alpha=0.1):
+                 smooth_alpha=0.1, custom_plot_fn=None):
         self.plots = plots
         self.model = model
         self.data = data
@@ -26,10 +37,12 @@ class LiveVisualizer:
         self.save_best_model = save_best_model
         self.checkpoint_path = checkpoint_path
         self.smooth_alpha = smooth_alpha
+        self.custom_plot_fn = custom_plot_fn
         
         # Dynamic history dictionary
-        self.history = {plot_type: [] for plot_type in plots if plot_type not in ["boundary", "gradients", "latent"]}
-        self.smoothed_history = {plot_type: [] for plot_type in plots if plot_type not in ["boundary", "gradients", "latent"]}
+        ignored_plots = ["boundary", "gradients", "latent", "grad_norm", "regression_fit"]
+        self.history = {plot_type: [] for plot_type in plots if plot_type not in ignored_plots}
+        self.smoothed_history = {plot_type: [] for plot_type in plots if plot_type not in ignored_plots}
         self.custom_plots = {}
         
         # Best metric trackers
@@ -39,7 +52,7 @@ class LiveVisualizer:
         # GIF frame storage
         self.frames = []
         if self.save_gif and not IMAGEIO_AVAILABLE:
-            print("Warning: 'imageio' package not found. GIF saving will be skipped. Install via 'pip install imageio'.")
+            print("Warning: 'imageio' package not found. GIF saving will be skipped.")
             self.save_gif = False
 
         if self.save_gif:
@@ -56,7 +69,6 @@ class LiveVisualizer:
         cols = min(num_plots, 3)
         rows = (num_plots + cols - 1) // cols
         
-        plt.ion()
         self.fig, self.axes = plt.subplots(rows, cols, figsize=(5 * cols, 4 * rows))
         
         if num_plots == 1:
@@ -79,17 +91,14 @@ class LiveVisualizer:
         self.custom_plots[name] = func
 
     def _extract_hidden_activations(self, x):
-        """Helper to extract hidden layer representations for mechanistic tasks."""
         if self.model is None:
             return None
-        
         activation = {}
         def get_activation(name):
             def hook(model, input, output):
                 activation[name] = output.detach()
             return hook
 
-        # Automatically find the second-to-last linear layer or hook a fallback
         target_layer = None
         for name, module in self.model.named_modules():
             if isinstance(module, nn.Linear):
@@ -103,52 +112,72 @@ class LiveVisualizer:
             return activation.get('hidden', None)
         return None
 
-    def step(self, epoch, **metrics):
+    def step(self, epoch, loss=None, accuracy=None, **metrics):
         if epoch % self.update_every != 0:
             return
 
-        for key, value in metrics.items():
-            if key in self.history:
-                self.history[key].append(value)
-                prev_smooth = self.smoothed_history[key][-1] if self.smoothed_history[key] else value
-                smoothed_val = self.smooth_alpha * value + (1 - self.smooth_alpha) * prev_smooth
-                self.smoothed_history[key].append(smoothed_val)
+        if loss is not None:
+            if isinstance(loss, dict):
+                for k, v in loss.items():
+                    key_name = f"{k}_loss" if k != "loss" else "loss"
+                    if key_name not in self.history:
+                        self.history[key_name] = []
+                        self.smoothed_history[key_name] = []
+                    self.history[key_name].append(v)
+                    prev_smooth = self.smoothed_history[key_name][-1] if self.smoothed_history[key_name] else v
+                    self.smoothed_history[key_name].append(self.smooth_alpha * v + (1 - self.smooth_alpha) * prev_smooth)
+                    
+                    if (k == "loss" or key_name == "loss") and v < self.best_loss:
+                        self.best_loss = v
+                        if self.save_best_model and self.model is not None:
+                            torch.save(self.model.state_dict(), self.checkpoint_path)
+            else:
+                if "loss" not in self.history:
+                    self.history["loss"] = []
+                    self.smoothed_history["loss"] = []
+                self.history["loss"].append(loss)
+                prev_smooth = self.smoothed_history["loss"][-1] if self.smoothed_history["loss"] else loss
+                self.smoothed_history["loss"].append(self.smooth_alpha * loss + (1 - self.smooth_alpha) * prev_smooth)
                 
-                if key == "loss" and value < self.best_loss:
-                    self.best_loss = value
-                    if self.save_best_model and self.model is not None:
-                        torch.save(self.model.state_dict(), self.checkpoint_path)
-                elif key == "accuracy" and value > self.best_acc:
-                    self.best_acc = value
+                if loss < self.best_loss:
+                    self.best_loss = loss
                     if self.save_best_model and self.model is not None:
                         torch.save(self.model.state_dict(), self.checkpoint_path)
+
+        if accuracy is not None:
+            if "accuracy" not in self.history:
+                self.history["accuracy"] = []
+                self.smoothed_history["accuracy"] = []
+            self.history["accuracy"].append(accuracy)
+            prev_smooth = self.smoothed_history["accuracy"][-1] if self.smoothed_history["accuracy"] else accuracy
+            self.smoothed_history["accuracy"].append(self.smooth_alpha * accuracy + (1 - self.smooth_alpha) * prev_smooth)
+            if accuracy > self.best_acc:
+                self.best_acc = accuracy
+                if self.save_best_model and self.model is not None:
+                    torch.save(self.model.state_dict(), self.checkpoint_path)
+
+        for key, value in metrics.items():
+            if key not in self.history:
+                self.history[key] = []
+                self.smoothed_history[key] = []
+            self.history[key].append(value)
+            prev_smooth = self.smoothed_history[key][-1] if self.smoothed_history[key] else value
+            self.smoothed_history[key].append(self.smooth_alpha * value + (1 - self.smooth_alpha) * prev_smooth)
         
         for i, plot_type in enumerate(self.plots):
             ax = self.axes[i]
             ax.clear()
             
-            # 1. Metric Curves with EMA Trendlines
             if plot_type in self.history:
                 raw_values = self.history[plot_type]
                 smooth_values = self.smoothed_history[plot_type]
-                
                 ax.plot(raw_values, color='gray', alpha=0.3, lw=1, label='Raw')
-                ax.plot(smooth_values, color='red' if plot_type == 'loss' else 'green', lw=2, label='EMA Trend')
+                ax.plot(smooth_values, color='red' if 'loss' in plot_type else 'green', lw=2, label='EMA Trend')
                 ax.set_title(f"{plot_type.capitalize()} Curve")
                 ax.set_xlabel("Update Step")
                 ax.set_ylabel(plot_type.capitalize())
                 ax.grid(True, linestyle='--', alpha=0.6)
-                
-                if plot_type == "loss" and raw_values:
-                    best_idx = np.argmin(raw_values)
-                    ax.scatter(best_idx, raw_values[best_idx], color='gold', s=100, zorder=5, label=f'Best: {raw_values[best_idx]:.4f}')
-                    ax.legend(loc='upper right', fontsize=7)
-                elif plot_type == "accuracy" and raw_values:
-                    best_idx = np.argmax(raw_values)
-                    ax.scatter(best_idx, raw_values[best_idx], color='gold', s=100, zorder=5, label=f'Best: {raw_values[best_idx]:.4f}')
-                    ax.legend(loc='lower right', fontsize=7)
-
-            # 2. Decision Boundary Plot
+
             elif plot_type == "boundary" and self.model is not None and self.data is not None:
                 X, y = self.data
                 if self.grid_tensor is not None:
@@ -158,54 +187,54 @@ class LiveVisualizer:
                     self.model.train()
                     Z = Z.reshape(self.xx.shape)
                     ax.contourf(self.xx, self.yy, Z, levels=50, cmap=plt.cm.Spectral, alpha=0.7)
-                
                 ax.scatter(X[:, 0], X[:, 1], c=y.squeeze(), cmap=plt.cm.Spectral, edgecolors='k')
                 ax.set_title(f"Decision Boundary (Epoch {epoch})")
 
-            # 3. Mechanistic Latent Space / Internal Representation Warp Plot
             elif plot_type == "latent" and self.model is not None and self.data is not None:
                 X, y = self.data
                 hidden_acts = self._extract_hidden_activations(X)
                 if hidden_acts is not None:
                     h = hidden_acts.cpu().numpy()
-                    # If hidden dimension > 2, take the first 2 principal components or dimensions for visualization
                     h_x = h[:, 0]
                     h_y = h[:, 1] if h.shape[1] > 1 else np.zeros_like(h_x)
-                    
                     ax.scatter(h_x, h_y, c=y.squeeze(), cmap=plt.cm.Spectral, edgecolors='k', s=40)
                     ax.set_title(f"Internal Latent Space (Epoch {epoch})")
-                    ax.set_xlabel("Hidden Dim 1")
-                    ax.set_ylabel("Hidden Dim 2")
-                    ax.grid(True, linestyle='--', alpha=0.6)
-
-            # 4. Gradient Flow Plot
-            elif plot_type == "gradients" and self.model is not None:
-                ave_grads = []
-                layers = []
-                for n, p in self.model.named_parameters():
-                    if p.requires_grad and ("bias" not in n) and (p.grad is not None):
-                        layers.append(n.split(".")[0])
-                        ave_grads.append(p.grad.abs().mean().item())
-                
-                if ave_grads:
-                    ax.plot(ave_grads, alpha=0.7, color="blue", lw=2)
-                    ax.bar(range(len(ave_grads)), ave_grads, alpha=0.3, color="blue")
-                    ax.set_xticks(range(len(layers)))
-                    ax.set_xticklabels(layers, rotation=30, ha='right', fontsize=8)
-                    ax.set_title("Gradient Flow (Layer-wise)")
-                    ax.set_xlabel("Layers")
-                    ax.set_ylabel("Avg Gradient Magnitude")
-                    ax.set_yscale("log")
-                    ax.grid(True, linestyle='--', alpha=0.6)
-
-            # 5. Custom Callbacks
+
+            elif plot_type == "grad_norm" and self.model is not None:
+                total_norm = sum(p.grad.norm().item() ** 2 for p in self.model.parameters() if p.grad is not None) ** 0.5
+                if not hasattr(self, 'grad_norms'):
+                    self.grad_norms = []
+                self.grad_norms.append(total_norm)
+                ax.plot(self.grad_norms, color="purple", lw=2)
+                ax.set_title("Total Gradient Norm")
+                ax.set_xlabel("Update Step")
+                ax.grid(True, linestyle='--', alpha=0.6)
+
+            elif plot_type == "regression_fit" and self.model is not None and self.data is not None:
+                X, y = self.data
+                self.model.eval()
+                with torch.no_grad():
+                    preds = self.model(X).detach().cpu().numpy()
+                self.model.train()
+                y_np = y.cpu().numpy().squeeze()
+                preds = preds.squeeze()
+                ax.scatter(y_np, preds, color="teal", alpha=0.7, edgecolors='k')
+                min_v, max_v = min(y_np.min(), preds.min()), max(y_np.max(), preds.max())
+                ax.plot([min_v, max_v], [min_v, max_v], 'r--', label="Ideal (y=x)")
+                ax.set_title("Regression: Actual vs Predicted")
+                ax.legend(fontsize=7)
+                ax.grid(True, linestyle='--', alpha=0.6)
+
             elif plot_type in self.custom_plots:
                 self.custom_plots[plot_type](ax, self.model, self.data)
+            elif self.custom_plot_fn is not None and plot_type == "custom":
+                self.custom_plot_fn(ax, self.model, self.data)
 
         plt.tight_layout()
-        plt.draw()
-        self.fig.canvas.flush_events()
-        plt.pause(0.001)
+        if matplotlib.get_backend() != 'Agg':
+            plt.draw()
+            self.fig.canvas.flush_events()
+            plt.pause(0.001)
 
         if self.save_gif and IMAGEIO_AVAILABLE:
             frame_path = os.path.join(self.temp_dir.name, f"frame_{self.frame_count:04d}.png")
@@ -215,17 +244,12 @@ class LiveVisualizer:
 
     def close(self):
         plt.ioff()
-        
         if self.save_best_model:
-            abs_ckpt = os.path.abspath(self.checkpoint_path)
-            print(f"Best model automatically saved to:\n---> {abs_ckpt}")
-
+            print(f"Best model saved to: {os.path.abspath(self.checkpoint_path)}")
         if self.save_gif and IMAGEIO_AVAILABLE and self.frames:
-            abs_path = os.path.abspath(self.gif_name)
-            print(f"Compiling training progress into GIF...")
+            print("Compiling training progress into GIF...")
             images = [imageio.v3.imread(f) for f in self.frames]
             imageio.mimsave(self.gif_name, images, duration=200, loop=0)
             self.temp_dir.cleanup()
-            print(f"GIF successfully compiled and saved at:\n---> {abs_path}")
-
-        plt.show()
+        if matplotlib.get_backend() != 'Agg':
+            plt.show()

{neuroplot-0.1.1 → neuroplot-0.1.2}/neuroplot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: neuroplot
-Version: 0.1.1
+Version: 0.1.2
 Summary: A lightweight, modular real-time visualization and diagnostics library for PyTorch.
 Description-Content-Type: text/markdown
 Requires-Dist: torch

{neuroplot-0.1.1 → neuroplot-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "neuroplot"
-version = "0.1.1"
+version = "0.1.2"
 description = "A lightweight, modular real-time visualization and diagnostics library for PyTorch."
 readme = "neuroplot/README.md"
 dependencies = [

neuroplot-0.1.1/README.md

@@ -1,9 +0,0 @@
-# PyTorch Foundations
-
-Daily practice for mechanistic interpretability thesis.
-
-Rules:
-- One concept per day
-- One script per concept
-- Type every line, no copy-paste
-- Every day ends with a commit