nnscope 0.1.0__py3-none-any.whl

nnscope/stats.py

@@ -0,0 +1,112 @@
+"""Numbers the dashboard shows: norms, update ratios, histograms, activation statistics and 2-D projections."""
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+import numpy as np
+
+SATURATING = {"tanh": (-0.97, 0.97), "sigmoid": (0.03, 0.97)}   # outside this range the unit's gradient ≈ 0
+
+
+def sig(x: np.ndarray, digits: int = 4) -> list:
+    """Round to `digits` significant figures and return a JSON-friendly nested list."""
+    a = np.asarray(x, dtype=np.float64)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        mag = np.where(a == 0, 0, np.floor(np.log10(np.abs(a))))
+    scale = 10.0 ** (digits - 1 - mag)
+    r = np.round(a * scale) / scale
+    r[~np.isfinite(r)] = 0.0
+    return r.tolist()
+
+
+def fnum(x: Optional[float], digits: int = 5) -> Optional[float]:
+    if x is None or not np.isfinite(x):
+        return None
+    return float(f"{float(x):.{digits}g}")
+
+
+def select_neurons(n: int, max_n: int) -> List[int]:
+    """Indices of at most `max_n` neurons, evenly spread over `n` (all of them if n ≤ max_n)."""
+    if n <= max_n:
+        return list(range(n))
+    return sorted(set(np.round(np.linspace(0, n - 1, max_n)).astype(int).tolist()))
+
+
+def histogram(x: Optional[np.ndarray], bins: int = 30) -> Optional[dict]:
+    if x is None:
+        return None
+    a = np.asarray(x, dtype=np.float64).ravel()
+    a = a[np.isfinite(a)]
+    if a.size == 0:
+        return None
+    lo, hi = float(a.min()), float(a.max())
+    if hi - lo < 1e-12:
+        lo, hi = lo - 0.5, hi + 0.5
+    counts, _ = np.histogram(a, bins=bins, range=(lo, hi))
+    return {"lo": fnum(lo), "hi": fnum(hi), "counts": counts.tolist()}
+
+
+def layer_numbers(W: np.ndarray, dW: Optional[np.ndarray], prev_W: Optional[np.ndarray]) -> Dict[str, Optional[float]]:
+    """Per-layer scalars logged every step."""
+    w_norm = float(np.linalg.norm(W))
+    out = {
+        "w_norm": fnum(w_norm),
+        "w_mean_abs": fnum(np.mean(np.abs(W))),
+        "g_norm": fnum(np.linalg.norm(dW)) if dW is not None else None,
+        "g_mean_abs": fnum(np.mean(np.abs(dW))) if dW is not None else None,
+        "update_ratio": None,
+    }
+    if prev_W is not None and prev_W.shape == W.shape and w_norm > 0:
+        out["update_ratio"] = fnum(np.linalg.norm(W - prev_W) / max(np.linalg.norm(prev_W), 1e-12))
+    return out
+
+
+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*.
+    * tanh / sigmoid: a unit is *active* when it is not saturated; one saturated on every sample is flagged *saturated*.
+    """
+    if A is None:
+        return None
+    A = np.asarray(A, dtype=np.float64)
+    if A.ndim == 1:
+        A = A[:, None]
+    A = A.reshape(A.shape[0], -1)
+    if act in SATURATING:
+        lo, hi = SATURATING[act]
+        active = (A > lo) & (A < hi)
+        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"
+    frac = active.mean(axis=0)
+    dead = int(np.sum(frac == 0))
+    return {
+        "mean": A.mean(axis=0), "std": A.std(axis=0), "frac_active": frac,
+        "layer_mean": fnum(A.mean()), "layer_frac_active": fnum(frac.mean()), "dead": dead, "dead_kind": kind,
+        "batch": int(A.shape[0]),
+    }
+
+
+def project_2d(Z: np.ndarray, max_points: int = 1000, seed: int = 0):
+    """2-D view of features Z (n, k): raw coordinates if k ≤ 2, else PCA via SVD.
+
+    Returns (coords (m, 2), explained_variance_ratio or None, indices of the m points used).
+    """
+    Z = np.asarray(Z, dtype=np.float64)
+    Z = Z.reshape(Z.shape[0], -1)
+    idx = np.arange(Z.shape[0])
+    if Z.shape[0] > max_points:
+        idx = np.sort(np.random.default_rng(seed).choice(Z.shape[0], max_points, replace=False))
+    Z = Z[idx]
+    if Z.shape[1] == 1:
+        return np.column_stack([Z[:, 0], np.zeros(len(Z))]), None, idx
+    if Z.shape[1] == 2:
+        return Z, None, idx
+    Zc = Z - Z.mean(axis=0)
+    _, s, Vt = np.linalg.svd(Zc, full_matrices=False)
+    Vt = Vt[:2] * np.sign(Vt[np.arange(2), np.argmax(np.abs(Vt[:2]), axis=1)])[:, None]   # fixed sign → no flipping
+    var = s ** 2
+    explained = var[:2] / var.sum() if var.sum() > 0 else np.zeros(2)
+    return Zc @ Vt[:2].T, explained, idx

nnscope-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: nnscope
+Version: 0.1.0
+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
+Author-email: michaelks <michaelks540@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Dist: numpy>=1.21
+Requires-Dist: matplotlib>=3.5 ; extra == 'png'
+Requires-Python: >=3.9
+Project-URL: Homepage, https://github.com/Ashurali/nnscope
+Project-URL: Repository, https://github.com/Ashurali/nnscope
+Project-URL: Issues, https://github.com/Ashurali/nnscope/issues
+Project-URL: Changelog, https://github.com/Ashurali/nnscope/blob/master/CHANGELOG.md
+Provides-Extra: png
+Description-Content-Type: text/markdown
+
+# nnscope
+
+**Watch your NumPy neural network learn.** Add one line to the training loop of a network you wrote yourself, and nnscope
+shows it live in your browser: every weight, every gradient, every activation, the loss, and plain-language hints about
+what is going on. Afterwards you get a standalone HTML replay you can scrub through, share, or export as images.
+
+It was built for students implementing neural networks **from scratch** (forward pass, backprop and SGD in NumPy)
+who want to *see* what their code does: gradients flowing backwards, ReLUs dying, sigmoids saturating, a hidden layer slowly
+learning to separate the classes.
+
+![nnscope dashboard](https://raw.githubusercontent.com/Ashurali/nnscope/master/docs/dashboard.png)
+
+- **Zero setup:** depends only on NumPy. The dashboard is one self-contained HTML file served by Python's standard library.
+- **Works with your code:** auto-detects common NumPy model layouts, or pass plain arrays.
+- **Live and replay:** a live view while training, then `save_html()` for an offline replay with a timeline slider.
+- **Explains itself:** every panel has a (?) with the math behind it, and an insights feed diagnoses common problems.
+- **Responsive:** works on a phone (the network turns vertical), light and dark themes.
+
+## Install
+
+```bash
+pip install nnscope            # NumPy is the only dependency
+pip install "nnscope[png]"     # optional: PNG snapshots from Python via matplotlib
+```
+
+## Quickstart
+
+```python
+import nnscope
+
+scope = nnscope.Scope("my-mlp")                    # opens http://127.0.0.1:8765 in your browser
+for epoch in range(epochs):
+    ...                                             # your own forward pass, backprop and SGD step
+    scope.log(epoch, model=model, loss=train_loss, metrics={"test_loss": test_loss})
+
+scope.save_html("run.html")                         # standalone replay, no server needed
+scope.snapshot("run.svg")                           # network structure + loss curve as an image
+scope.wait()                                        # keep the live page up until Ctrl+C
+```
+
+In a Jupyter notebook, `scope.show()` puts the live dashboard inline. Use `nnscope.Scope(..., live=False)` to only record
+(for `save_html` / `snapshot`).
+
+## Connecting your network
+
+nnscope never runs your network; it only **reads arrays you already have**.
+
+**1. A model object (auto-detected).** Any object with a `.layers` list whose dense layers expose weights and biases,
+optionally with their gradients:
+
+| what | attribute names tried |
+|---|---|
+| weights | `W`, `weight`, `weights`, `kernel` |
+| biases | `b`, `bias` |
+| gradients | `dW`, `grad_W`, `W_grad`, `dweight`, … and `db`, `grad_b`, … |
+| cached input (→ activation stats of the previous layer) | `x`, `input`, `inputs`, `a_prev` |
+
+Layers without weights are recognised as activations by class name (`ReLU`, `Tanh`, `Sigmoid`, `LeakyReLU`, …), so the graph
+shows `relu`, `tanh`, … on each layer. CS231n-style parameter dicts (`{"W1": …, "b1": …}` plus a matching `grads` dict)
+and lists of `(W, b)` pairs work too.
+
+**2. Plain arrays.** No model object needed:
+
+```python
+scope.log(step, weights=[W1, W2], biases=[b1, b2], grads=[dW1, dW2], loss=loss)
+```
+
+Both `x @ W` (`W` is `(in, out)`) and `W @ x` (`W` is `(out, in)`) conventions are detected from how the shapes chain. Force
+one with `Scope(layout="in_out")` or `layout="out_in"` if a network is ambiguous (e.g. every layer square).
+
+**Optional extras for richer views:**
+
+```python
+scope.log(step, model=model, loss=loss,
+          activations=[a1, a2],     # per-layer outputs on a batch → activation statistics
+          deltas=[d1, d2, d3],      # per-layer ∂L/∂z on a batch → shown in the gradient-flow panel
+          latent=z, labels=y)       # features of any layer → latent-space scatter
+```
+
+## How to read the dashboard
+
+| Panel | What it shows | What to look for |
+|---|---|---|
+| **Network** | Neurons (circles) and weights (lines): blue positive, orange negative, thickness ∝ \|w\|. Toggle the lines to **gradients** ∂L/∂w or **updates** Δw, and the node colour to mean activation or % active. | Click a neuron: the **inspector** shows z = Σ wᵢ aᵢ + b with the real numbers from your batch, its strongest inputs, their gradients and how they changed. Dead ReLUs are ringed in red. |
+| **Loss & metrics** | Every scalar you log over time (log or linear scale). | Spikes: learning rate too high. Test loss rising while training loss falls: overfitting. |
+| **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. |
+| **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,
+the whole dashboard (PNG) or the raw run data (JSON).
+
+![deep sigmoid network: vanishing gradients](https://raw.githubusercontent.com/Ashurali/nnscope/master/docs/vanishing.png)
+
+## Examples
+
+The [`examples/`](https://github.com/Ashurali/nnscope/tree/master/examples) folder uses a tiny homework-style NumPy MLP ([`_mlp.py`](https://github.com/Ashurali/nnscope/blob/master/examples/_mlp.py)). Run them from that folder;
+add `--no-open` to skip opening a browser tab, or `--headless` to only write `runs/*.html` and `runs/*.svg`.
+
+| script | story |
+|---|---|
+| `01_quickstart_xor.py` | the basics: an MLP on XOR-like data, live |
+| `02_plain_arrays.py` | no model object: raw `W1, b1, W2, b2`, hand-written backprop, `deltas=` |
+| `03_latent_bottleneck.py --k 2` | watch a k-unit bottleneck layer separate two classes (try `--k 32`) |
+| `04_vanishing_gradients.py --act sigmoid` | deep sigmoid net: gradients vanish, the insight explains why (compare `--act relu`) |
+| `05_inr_spectral_bias.py [--fourier]` | fit an image f(x, y) → rgb: raw coordinates plateau, Fourier features keep improving |
+
+## API
+
+```python
+nnscope.Scope(name="run", *, live=True, port=8765, host="127.0.0.1", open_browser=True, max_neurons=32,
+              snapshot_every=None, max_snapshots=300, max_records=5000, layout="auto", latent_points=1000, quiet=False)
+```
+
+- `log(step=None, *, model=None, loss=None, metrics=None, weights=None, biases=None, grads=None, bias_grads=None, activations=None, deltas=None, latent=None, labels=None, snapshot=None)`
+- `save_html(path)`: standalone replay. `snapshot(path, step=None)`: `.svg` (no dependencies) or `.png` (matplotlib).
+- `show(height=820)`: Jupyter IFrame. `wait()`: serve until Ctrl+C. `close()`; also usable as a context manager.
+- `data()`: everything recorded so far as a JSON-serialisable dict.
+
+**Keeping it light.** Scalars are recorded at every `log`; full snapshots (edges, histograms, latent points) are thinned
+adaptively so a run keeps at most `max_snapshots` of them. Layers wider than `max_neurons` draw an evenly spaced subset
+(statistics always use all neurons). The live stream batches updates to about 10 per second.
+
+**Limitations.** Dense (fully-connected) layers only for now; convolutional layers are not drawn. The server binds to
+localhost by default.
+
+## Development
+
+```bash
+uv sync --dev
+uv run --dev pytest
+```
+
+## License
+
+MIT

nnscope-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+nnscope/__init__.py,sha256=uM7lw5W-qmVG8pMvyja1Igs5lBZFAmCnbbV5cclVjxY,346
+nnscope/adapters.py,sha256=RBLjC0NqrcX0xyBbWRWzr4xUial3ZxbnnUNZuAl-u5Q,9991
+nnscope/export.py,sha256=N7V0l_q0kmc424IEW8kHYrTS-zTKV7XNfosgt54LhDY,8393
+nnscope/insights.py,sha256=VFQc00rILr9f02EdLQHYWxgh6YbZ9bQZJbkwFCEgxEw,6256
+nnscope/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nnscope/scope.py,sha256=fJGlKUJ7Pf5HTVgPrzgLHfT5Si5AQGI3_KKwaOhPytQ,11767
+nnscope/server.py,sha256=pBYzHVp5SbyPvYmCdri9382iREeLIz1YiX00frutZRw,3732
+nnscope/static/index.html,sha256=fL4B48bdcdPczvE77Zl1iDyM_v04QAwHBXaUiv31n4w,53296
+nnscope/stats.py,sha256=pspFU_qLBFYHvpoDr5M1ERUgH30Nwfp3lG04tra2whk,4447
+nnscope-0.1.0.dist-info/licenses/LICENSE,sha256=0uVeJfLU3mjdYwRrEGRh4X0RQC0fbqX3Hc8BjSaZSJg,1064
+nnscope-0.1.0.dist-info/WHEEL,sha256=766qEDcnZQDL36MOdWBQ0gowd8OjUWAOwMNC7Vgvxts,81
+nnscope-0.1.0.dist-info/METADATA,sha256=FoJ01Fm89CHJShSgnxgQE5p3nH64Hah5jHpCVGHSIUw,9155
+nnscope-0.1.0.dist-info/RECORD,,

nnscope-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.20
+Root-Is-Purelib: true
+Tag: py3-none-any

nnscope-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.