NeuroLens

Watch neural networks train, live. NeuroLens is a fast C++/OpenGL window that shows what your model is doing while it trains: loss curves, gradient flow through every layer, update sizes, and the neurons themselves. Built-in checks tell you when something goes wrong: NaN loss, exploding gradients, a learning rate that is too high, overfitting.

pip install neurolens

import neurolens

neurolens.launch()                        # opens the window
mon = neurolens.monitor(model, optimizer) # any PyTorch model

for step, (x, y) in enumerate(loader):
    loss = loss_fn(model(x), y)
    optimizer.zero_grad(); loss.backward(); optimizer.step()
    mon.step(step, loss=loss)

Live network view	LR far too high: the checks catch it

Contents: Quick start · Training monitor · Network view · Any framework · How it works · Protocol · Examples · Troubleshooting · Roadmap · Contributing

Why NeuroLens

• Works with any PyTorch model. CNNs, transformers and LoRA fine-tunes all work: monitor() only reads parameters and gradients.
• Tells you what's wrong. It runs about ten rule-of-thumb checks continuously, and each warning says what to try.
• Never slows training down. Data goes out on a background thread. If the window is closed or busy, data is dropped instead of blocking your loop.
• Open the window any time. Curves are replayed from step 0, so you can start the viewer halfway through a run.
• No setup. The viewer is compiled into the wheel. There is nothing to build, no browser, and no server.
• Any language. It uses a tiny plain-text TCP protocol, so a few lines of code are enough to send data from JAX, TensorFlow, C++ or a shell script.

Quick start

1. Install on macOS (Intel or Apple Silicon) or Linux, with Python 3.9+:

   pip install neurolens              # add [torch] to also install PyTorch
   

2. Add three lines to your training script:

   import neurolens
   neurolens.launch()                          # once, before training
   mon = neurolens.monitor(model, optimizer)   # once, before training
   ...
   mon.step(step, loss=loss)                    # every step, after optimizer.step()
   

3. Run your script as usual. The window opens, and curves appear within a second.

Windows is not supported yet (help wanted). Platforms without a prebuilt wheel compile the viewer during pip install. That needs a C++ compiler, plus OpenGL and X11 headers on Linux.

Start the viewer

From a terminal:

neurolens                  # opens the window and waits for your training script
neurolens model.nlens      # opens a saved network
neurolens --help           # all options

Or from Python, in a script or notebook: neurolens.launch(). If a viewer is already open, launch() does nothing.

Training monitor

mon = neurolens.monitor(model, optimizer)

for step, (x, y) in enumerate(loader):
    out = model(x)
    loss = loss_fn(out, y)
    optimizer.zero_grad()
    loss.backward()
    optimizer.step()
    mon.step(step, loss=loss, acc=(out.argmax(1) == y).float().mean())  # before the next zero_grad

    if step % 500 == 0:
        mon.log(step, val_loss=evaluate(), val_acc=val_acc)  # sent as is, not averaged

Options: monitor(model, optimizer, every=0.5, max_layers=40, track_updates=True, port=5757). Metrics are averaged over every seconds. Large models are grouped into max_layers rows. Update sizes need the optimizer and one temporary copy of the trainable weights per send, and turn off automatically above 200M trainable values. With LoRA, only the adapters count toward that limit.

Network view

For MLPs, you can watch the neurons themselves, during training or inference:

handle = neurolens.watch(model, labels=["cat", "dog", "bird"])
model(x)            # each forward pass lights up the network (max 20 per second)
handle.remove()

Connections glow by |activation × weight|. Gold means positive and red means negative, and the signal travels from left to right. Hover a neuron to see its value, and click it to mute it and watch how the output changes. Layers wider than 64 neurons are drawn as an evenly spaced sample.

Any framework

v = neurolens.Viewer()
v.metric("loss", 0.42, step)                                  # curves
v.layer_stats([("encoder", grad_norm, weight_norm, update_ratio), ...])
v.topology([784, 128, 10], ["relu", "softmax"])               # network view
v.weights(0, W0, b0)                                          # shape (out, in)
v.input(x)                # the viewer runs the forward pass, or:
v.frame([x, h, y])        # send real activations
v.status(epoch=3)

Save a network to a file with neurolens.save_torch(model, "net.nlens") or neurolens.save_nlens(...). Open it later with neurolens net.nlens.

How it works

 your training script                                 NeuroLens window
┌─────────────────────────────┐                     ┌───────────────────────────┐
│ monitor() / watch() hooks   │  TCP 127.0.0.1:5757  │ C++ / OpenGL, 60+ fps     │
│ read params, grads, acts    │ ── plain text ──────▶│ curves · layer health     │
│ background thread, drops    │   one command/line   │ checks · network view     │
│ data rather than block      │                      │                           │
└─────────────────────────────┘                     └───────────────────────────┘

• Separate process. The viewer runs in its own process, so a slow frame never stalls a training step, and a crashed training run never takes the window down.
• Lightweight hooks. The Python side is a few hooks and a socket. It measures about every half second (every=0.5), so the cost per training step is close to zero.
• Analysis lives in the viewer. The checks run in the viewer, on the data it receives, so a client in any language gets them too.

Protocol

.nlens files and the TCP stream (127.0.0.1:5757) use the same plain-text commands, one per line. You can try them by hand with nc localhost 5757.

Examples

git clone https://github.com/Yaiphaba189/TrainLens && cd TrainLens
# each example opens the viewer window itself with neurolens.launch()
python examples/torch_monitor_cnn.py          # CNN: the monitor flags overfitting
python examples/torch_monitor_cnn.py --lr 3   # learning rate far too high
python examples/torch_spiral_train.py         # MLP: network view plus monitor, then inference
python examples/numpy_xor_train.py            # no PyTorch: plain numpy

Troubleshooting

Limits

• The network view draws dense layers only: MLPs, or the MLP head of a bigger model. The training monitor has no such limit.
• watch() finds layers in the order they are registered, which matches nn.Sequential.
• The viewer accepts connections from this machine only (127.0.0.1). Use an SSH tunnel for remote training, as shown above.

Roadmap

• Windows support: the viewer needs Winsock networking.
• Remote and notebook training: Colab and Kaggle.
• Network view for convolution and attention layers.
• monitor() helpers for JAX and TensorFlow.
• Export a run (curves and checks) to a report you can share.

Ideas and pull requests are welcome. See CONTRIBUTING.md.

Contributing

See CONTRIBUTING.md. MIT licensed. Inspired by m607stars/Neural-Network-Visualization-using-OpenGL.