nnscope 0.1.1__tar.gz → 0.1.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nnscope
-Version: 0.1.1
+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.1 → 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.1 → nnscope-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nnscope"
-version = "0.1.1"
+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"

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

@@ -1,6 +1,6 @@
 [project]
 name = "nnscope"
-version = "0.1.1"
+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"

{nnscope-0.1.1 → 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.1"
+__version__ = "0.1.2"
 
 from .adapters import LayerView, extract_layers  # noqa: E402
 from .scope import Scope  # noqa: E402

{nnscope-0.1.1 → 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.1 → 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.1 → 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>
 
@@ -732,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>` : "");

{nnscope-0.1.1 → 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 {