nnscope 0.1.0__tar.gz → 0.1.2__tar.gz

{nnscope-0.1.0 → nnscope-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nnscope
-Version: 0.1.0
+Version: 0.1.2
 Summary: Watch your NumPy neural network learn: a live, replayable dashboard for weights, gradients, activations and loss.
 Keywords: neural-network,numpy,visualization,backpropagation,education,deep-learning,dashboard
 Author: michaelks
@@ -112,7 +112,7 @@ scope.log(step, model=model, loss=loss,
 | **Insights** | Plain-language diagnoses, each at the step where it appeared. Click to jump there. | Vanishing/exploding gradients, dead or saturated units, learning rate too high/low, overfitting. |
 | **Gradient flow** | Mean \|∂L/∂W\| per layer, input → output, log scale. | Bars shrinking towards the input = vanishing gradients (e.g. deep sigmoid nets). |
 | **Layer health** | ‖W‖, ‖∇W‖ and the update ratio ‖ΔW‖/‖W‖ per layer over time, plus W and ∇W histograms. | Update ratio ≈ 10⁻³ per SGD step is healthy; ≈ 10⁻¹ is too high. |
-| **Activations** | Per neuron: mean activation and fraction of samples where it is active. | Neurons at 0 % active pass no gradient back and have stopped learning. |
+| **Activations** | Per neuron: mean activation and fraction of samples where it is active. | A ReLU at 0 % active is *dead*: no gradient flows through it, so its own weights stop learning (it can revive only if earlier layers change). A LeakyReLU at 0 % is just *inactive* and still learns slowly. |
 | **Latent space** | Any layer's features (PCA if wider than 2), coloured by label, along the timeline. | Classes starting mixed and ending linearly separable: the network is building a representation. |
 
 Use the **timeline** at the bottom (or ← → and space) to replay training. **Export** saves the network (SVG/PNG), the loss curve,

{nnscope-0.1.0 → nnscope-0.1.2}/README.md

@@ -86,7 +86,7 @@ scope.log(step, model=model, loss=loss,
 | **Insights** | Plain-language diagnoses, each at the step where it appeared. Click to jump there. | Vanishing/exploding gradients, dead or saturated units, learning rate too high/low, overfitting. |
 | **Gradient flow** | Mean \|∂L/∂W\| per layer, input → output, log scale. | Bars shrinking towards the input = vanishing gradients (e.g. deep sigmoid nets). |
 | **Layer health** | ‖W‖, ‖∇W‖ and the update ratio ‖ΔW‖/‖W‖ per layer over time, plus W and ∇W histograms. | Update ratio ≈ 10⁻³ per SGD step is healthy; ≈ 10⁻¹ is too high. |
-| **Activations** | Per neuron: mean activation and fraction of samples where it is active. | Neurons at 0 % active pass no gradient back and have stopped learning. |
+| **Activations** | Per neuron: mean activation and fraction of samples where it is active. | A ReLU at 0 % active is *dead*: no gradient flows through it, so its own weights stop learning (it can revive only if earlier layers change). A LeakyReLU at 0 % is just *inactive* and still learns slowly. |
 | **Latent space** | Any layer's features (PCA if wider than 2), coloured by label, along the timeline. | Classes starting mixed and ending linearly separable: the network is building a representation. |
 
 Use the **timeline** at the bottom (or ← → and space) to replay training. **Export** saves the network (SVG/PNG), the loss curve,

{nnscope-0.1.0 → nnscope-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nnscope"
-version = "0.1.0"
+version = "0.1.2"
 description = "Watch your NumPy neural network learn: a live, replayable dashboard for weights, gradients, activations and loss."
 readme = "README.md"
 license = "MIT"
@@ -40,7 +40,10 @@ Issues = "https://github.com/Ashurali/nnscope/issues"
 Changelog = "https://github.com/Ashurali/nnscope/blob/master/CHANGELOG.md"
 
 [dependency-groups]
-dev = ["pytest>=7"]
+dev = [
+    "matplotlib>=3.9.4",
+    "pytest>=7",
+]
 
 [build-system]
 requires = ["uv_build>=0.12.3,<0.13.0"]

{nnscope-0.1.0 → nnscope-0.1.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "nnscope"
-version = "0.1.0"
+version = "0.1.2"
 description = "Watch your NumPy neural network learn: a live, replayable dashboard for weights, gradients, activations and loss."
 readme = "README.md"
 license = "MIT"
@@ -33,7 +33,10 @@ Issues = "https://github.com/Ashurali/nnscope/issues"
 Changelog = "https://github.com/Ashurali/nnscope/blob/master/CHANGELOG.md"
 
 [dependency-groups]
-dev = ["pytest>=7"]
+dev = [
+    "matplotlib>=3.9.4",
+    "pytest>=7",
+]
 
 [build-system]
 requires = ["uv_build>=0.12.3,<0.13.0"]

{nnscope-0.1.0 → nnscope-0.1.2}/src/nnscope/__init__.py

@@ -4,7 +4,7 @@
     scope = nnscope.Scope("my-mlp")
     scope.log(step, model=model, loss=loss)
 """
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 from .adapters import LayerView, extract_layers  # noqa: E402
 from .scope import Scope  # noqa: E402

{nnscope-0.1.0 → nnscope-0.1.2}/src/nnscope/export.py

@@ -134,9 +134,10 @@ def snapshot_image(data: dict, path: str, step: Optional[int] = None) -> str:
     if p.suffix.lower() != ".png":
         raise ValueError("snapshot path must end in .svg or .png")
     try:
-        import matplotlib
-        matplotlib.use("Agg")
-        import matplotlib.pyplot as plt
+        # A standalone Figure + Agg canvas: never touches pyplot's global state or the user's backend
+        # (switching the backend would silently break inline plots in a Jupyter notebook).
+        from matplotlib.backends.backend_agg import FigureCanvasAgg
+        from matplotlib.figure import Figure
         from matplotlib.patches import PathPatch
         from matplotlib.path import Path as MPath
     except ImportError:
@@ -144,7 +145,9 @@ def snapshot_image(data: dict, path: str, step: Optional[int] = None) -> str:
     structure, snap = data.get("structure"), _pick_snapshot(data, step)
     if structure is None or snap is None:
         raise ValueError("nothing to draw yet: call scope.log(...) at least once")
-    fig, (ax, bx) = plt.subplots(1, 2, figsize=(13, 5.4), gridspec_kw={"width_ratios": [1.7, 1]})
+    fig = Figure(figsize=(13, 5.4))
+    FigureCanvasAgg(fig)
+    ax, bx = fig.subplots(1, 2, gridspec_kw={"width_ratios": [1.7, 1]})
     pos, xs = _layout(structure, 0.0, 1.0, 0.0, 1.0)
     for l, Wl in enumerate(snap["W"]):
         m = max((abs(v) for row in Wl for v in row), default=1.0) or 1.0
@@ -164,5 +167,6 @@ def snapshot_image(data: dict, path: str, step: Optional[int] = None) -> str:
     for name, ser in _loss_series(data).items():
         bx.plot([s for s, _ in ser], [v for _, v in ser], label=name)
     bx.set_xlabel("step"); bx.set_title("loss & metrics"); bx.grid(alpha=0.3); bx.legend()
-    fig.tight_layout(); fig.savefig(p, dpi=150); plt.close(fig)
+    fig.tight_layout()
+    fig.savefig(p, dpi=150)
     return str(p)

{nnscope-0.1.0 → nnscope-0.1.2}/src/nnscope/insights.py

@@ -83,12 +83,19 @@ class InsightEngine:
             kind = l.get("dead_kind") or "dead"
             if dead is None or n <= 1:
                 continue
-            word = "dead" if kind == "dead" else "saturated"
-            self._check(f"{word}:{k}", dead / n >= 0.5, step, "warn", "activations",
-                        f"{dead} of {n} {act} units in {names[k]} are {word} on the logged batch "
-                        + ("(never positive → zero gradient forever). Lower the learning rate, use He init or LeakyReLU."
-                           if word == "dead" else "(stuck near ±1 → gradient ≈ 0). Inputs to this layer are too large; "
-                           "normalise inputs or use smaller initial weights."), out)
+            if kind == "saturated":
+                why = ("(stuck near ±1, so their gradient ≈ 0). Inputs to this layer are too large; normalise the inputs or use "
+                       "smaller initial weights.")
+            elif kind == "inactive":
+                why = ("(never positive). Unlike ReLU they still pass a small gradient (α·δ), so they can recover, but slowly.")
+            else:
+                why = ("(never positive, so no gradient flows through them and their own weights stop learning). "
+                       + ("In the first layer the inputs never change, so they will not come back. " if k == 0 else
+                          "They can only come back if the earlier layers' outputs change. ")
+                       + "Typical causes: too large first updates (lower the learning rate or warm it up) or poor init; "
+                         "LeakyReLU keeps a small gradient flowing.")
+            self._check(f"{kind}:{k}", dead / n >= 0.5, step, "warn", "activations",
+                        f"{dead} of {n} {act} units in {names[k]} are {kind} on the logged batch {why}", out)
 
         test_key = next((k for k in scalars if ("test" in k or "val" in k) and "loss" in k), None)
         if test_key and loss is not None and scalars[test_key] is not None and np.isfinite(scalars[test_key]):

{nnscope-0.1.0 → nnscope-0.1.2}/src/nnscope/server.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import json
 import queue
+import sys
 import threading
 import time
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -13,6 +14,17 @@ PUSH_INTERVAL = 0.1      # seconds: batch messages → at most ~10 pushes per se
 HEARTBEAT = 15.0
 
 
+class _QuietServer(ThreadingHTTPServer):
+    """Don't print a traceback when a browser closes a tab or reloads mid-request: that is normal, not an error."""
+
+    daemon_threads = True
+
+    def handle_error(self, request, client_address):
+        if isinstance(sys.exc_info()[1], (ConnectionError, TimeoutError)):
+            return
+        super().handle_error(request, client_address)
+
+
 def _handler_for(scope):
     class Handler(BaseHTTPRequestHandler):
         def log_message(self, *args):          # keep the user's console clean
@@ -83,12 +95,11 @@ def start_server(scope, host: str = "127.0.0.1", port: int = 8765):
     last_err = None
     for p in ([0] if port == 0 else list(range(port, port + 20)) + [0]):
         try:
-            server = ThreadingHTTPServer((host, p), handler)
+            server = _QuietServer((host, p), handler)
             break
         except OSError as err:
             last_err = err
     else:
         raise OSError(f"nnscope: no free port found ({last_err})")
-    server.daemon_threads = True
     threading.Thread(target=server.serve_forever, daemon=True, name="nnscope-server").start()
     return server, f"http://{host}:{server.server_address[1]}/"

{nnscope-0.1.0 → nnscope-0.1.2}/src/nnscope/static/index.html

@@ -212,9 +212,11 @@
     <div class="help" id="help-acts">
       <p>For each hidden layer, one cell per drawn neuron: the top strip is its <b>mean activation</b> on the logged batch, the bottom strip the
         <b>fraction of samples where it is active</b> (ReLU: output &gt; 0; tanh/sigmoid: not saturated).</p>
-      <p>A neuron with 0 % active passes no gradient back, so it has stopped learning (<b style="color:var(--bad)">dead ReLU</b> or
-        <b style="color:var(--bad)">saturated</b> unit). Activation stats need activations: they are read automatically from layers that cache
-        their input (e.g. <code>Linear.x</code>), or pass <code>activations=[a1, a2, …]</code>.</p></div>
+      <p>A ReLU at 0 % active is <b style="color:var(--bad)">dead</b>: no gradient flows through it, so its own weights stop learning.
+        It can only come back if its <i>inputs</i> change, which is impossible in the first layer, where the inputs are the data. A LeakyReLU
+        unit at 0 % is merely <b>inactive</b>: it still passes the small gradient α·δ and can recover. A tanh/sigmoid unit stuck near ±1 is
+        <b style="color:var(--bad)">saturated</b> (gradient ≈ 0). Activation stats need activations: they are read automatically from layers that
+        cache their input (e.g. <code>Linear.x</code>), or pass <code>activations=[a1, a2, …]</code>.</p></div>
     <div id="acts"></div>
   </section>
 
@@ -584,9 +586,11 @@ function drawLoss() {
   }
   if (!names.length) { ctx.fillStyle = css("--faint"); ctx.font = "13px system-ui"; ctx.textAlign = "center"; ctx.fillText("waiting for scope.log(..., loss=...)", w / 2, h / 2); return; }
   const shown = names.filter((n) => !UI.hidden.has(n));
-  const all = shown.flatMap((n) => S[n]);
+  const useLog = UI.logScale && shown.some((n) => S[n].some(([, v]) => v > 0));
+  // On a log scale, points ≤ 0 (e.g. a training error that reaches exactly 0) are skipped instead of forcing linear.
+  const pts = (n) => (useLog ? S[n].filter(([, v]) => v > 0) : S[n]);
+  const all = shown.flatMap(pts);
   if (!all.length) return;
-  const useLog = UI.logScale && all.every(([, v]) => v > 0);
   const f = useLog ? Math.log10 : (v) => v;
   let lo = Math.min(...all.map(([, v]) => f(v))), hi = Math.max(...all.map(([, v]) => f(v)));
   if (hi - lo < 1e-9) { lo -= 0.5; hi += 0.5; }
@@ -603,7 +607,7 @@ function drawLoss() {
   names.forEach((n, k) => {
     if (UI.hidden.has(n)) return;
     ctx.strokeStyle = k ? SERIES[k % SERIES.length] : css("--ink"); ctx.lineWidth = 1.8; ctx.beginPath();
-    S[n].forEach(([s, v], i) => (i ? ctx.lineTo(X(s), Y(v)) : ctx.moveTo(X(s), Y(v)))); ctx.stroke();
+    pts(n).forEach(([s, v], i) => (i ? ctx.lineTo(X(s), Y(v)) : ctx.moveTo(X(s), Y(v)))); ctx.stroke();
   });
   const cs = curSnap();
   if (cs) { ctx.strokeStyle = css("--warn"); ctx.setLineDash([4, 3]); ctx.beginPath(); ctx.moveTo(X(cs.step), P.t); ctx.lineTo(X(cs.step), h - P.b); ctx.stroke(); ctx.setLineDash([]); }
@@ -730,7 +734,7 @@ function drawActs() {
     box.innerHTML = rows.map((r) => `<div class="act-row"><div class="nm" id="actnm${r.k}"></div><canvas data-a="${r.k}"></canvas></div>`).join("");
   }
   rows.forEach(({ l, k, nd, rec }) => {
-    const dead = rec && rec.dead ? rec.dead : 0, kind = rec && rec.dead_kind === "saturated" ? "saturated" : "dead";
+    const dead = rec && rec.dead ? rec.dead : 0, kind = (rec && rec.dead_kind) || "dead";
     $("actnm" + k).innerHTML = `<b>layer ${k + 1}</b> · ${l.act || "linear"} · ${l.out} units` +
       (rec && rec.frac_active !== undefined && rec.frac_active !== null ? ` · ${Math.round(rec.frac_active * 100)}% active on average` : "") +
       (dead ? ` · <span class="dead">${dead} ${kind}</span>` : "");
@@ -757,7 +761,7 @@ function drawLatent() {
   cv.style.display = s ? "" : "none";
   if (!s) return;
   const { ctx, w, h } = setupCanvas(cv, Math.min(420, Math.max(260, cv.parentElement.clientWidth * 0.75)));
-  const { xy, labels, explained, dim } = s.latent, P = { l: 34, r: 10, t: 10, b: 30 };
+  const { xy, labels, explained, dim } = s.latent, P = { l: 34, r: 10, t: 22, b: 30 };
   const xs = xy.map((p) => p[0]), ys = xy.map((p) => p[1]);
   const pad = (a, b) => { const d = (b - a) || 1; return [a - 0.06 * d, b + 0.06 * d]; };
   const [x0, x1] = pad(Math.min(...xs), Math.max(...xs)), [y0, y1] = pad(Math.min(...ys), Math.max(...ys));
@@ -775,11 +779,13 @@ function drawLatent() {
   const ax = explained ? [`PC1 (${Math.round(explained[0] * 100)}% var)`, `PC2 (${Math.round(explained[1] * 100)}% var)`] : ["z1", "z2"];
   ctx.fillText(`${ax[0]} · ${dim}-D features · step ${s.step}`, P.l + (w - P.l - P.r) / 2, h - 8);
   ctx.save(); ctx.translate(12, P.t + (h - P.t - P.b) / 2); ctx.rotate(-Math.PI / 2); ctx.fillText(ax[1], 0, 0); ctx.restore();
-  if (cats) {
+  if (cats) {                                      // legend outside the plot area, above it, so it never hides points
     const uniq = [...new Set(labels)].sort((a, b) => a - b);
-    ctx.textAlign = "left";
-    uniq.forEach((u, k) => { ctx.fillStyle = PALETTE[(+u) % PALETTE.length]; ctx.fillRect(P.l + 8, P.t + 8 + k * 16, 10, 10);
-      ctx.fillStyle = css("--ink"); ctx.fillText(`class ${+u}`, P.l + 24, P.t + 17 + k * 16); });
+    ctx.textAlign = "left"; let lx = P.l;
+    uniq.forEach((u) => {
+      ctx.fillStyle = PALETTE[(+u) % PALETTE.length]; ctx.fillRect(lx, 4, 10, 10);
+      ctx.fillStyle = css("--ink"); ctx.fillText(`class ${+u}`, lx + 14, 13); lx += ctx.measureText(`class ${+u}`).width + 30;
+    });
   }
 }
 

{nnscope-0.1.0 → nnscope-0.1.2}/src/nnscope/stats.py

@@ -64,7 +64,8 @@ def layer_numbers(W: np.ndarray, dW: Optional[np.ndarray], prev_W: Optional[np.n
 def activation_numbers(A: Optional[np.ndarray], act: Optional[str]) -> Optional[dict]:
     """Per-neuron statistics of a batch of activations A (batch, units).
 
-    * relu-like: a unit is *active* when its output > 0; a unit never active on the batch is *dead*.
+    * relu-like: a unit is *active* when its output > 0; a unit never active on the batch is *dead* (no gradient flows
+      through it). For leaky_relu such a unit is only *inactive*: it still passes the small gradient α·δ.
     * tanh / sigmoid: a unit is *active* when it is not saturated; one saturated on every sample is flagged *saturated*.
     """
     if A is None:
@@ -79,7 +80,7 @@ def activation_numbers(A: Optional[np.ndarray], act: Optional[str]) -> Optional[
         kind = "saturated"
     else:
         active = A > 0 if act in (None, "relu", "leaky_relu", "elu", "gelu", "swish", "softplus") else np.abs(A) > 1e-8
-        kind = "dead"
+        kind = "inactive" if act == "leaky_relu" else "dead"
     frac = active.mean(axis=0)
     dead = int(np.sum(frac == 0))
     return {