neurolume 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. neurolume-0.1.0/LICENSE +21 -0
  2. neurolume-0.1.0/PKG-INFO +330 -0
  3. neurolume-0.1.0/README.md +289 -0
  4. neurolume-0.1.0/pyproject.toml +71 -0
  5. neurolume-0.1.0/python/neurolume/__init__.py +20 -0
  6. neurolume-0.1.0/python/neurolume/adapters/__init__.py +5 -0
  7. neurolume-0.1.0/python/neurolume/adapters/base.py +111 -0
  8. neurolume-0.1.0/python/neurolume/adapters/keras_adapter.py +389 -0
  9. neurolume-0.1.0/python/neurolume/adapters/torch_adapter.py +581 -0
  10. neurolume-0.1.0/python/neurolume/demo.py +74 -0
  11. neurolume-0.1.0/python/neurolume/export.py +60 -0
  12. neurolume-0.1.0/python/neurolume/feature_maps.py +64 -0
  13. neurolume-0.1.0/python/neurolume/keras.py +69 -0
  14. neurolume-0.1.0/python/neurolume/live.py +454 -0
  15. neurolume-0.1.0/python/neurolume/py.typed +0 -0
  16. neurolume-0.1.0/python/neurolume/qt.py +79 -0
  17. neurolume-0.1.0/python/neurolume/schema.py +289 -0
  18. neurolume-0.1.0/python/neurolume/server.py +266 -0
  19. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_AMS-Regular-BQhdFMY1.woff2 +0 -0
  20. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_AMS-Regular-DMm9YOAa.woff +0 -0
  21. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_AMS-Regular-DRggAlZN.ttf +0 -0
  22. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Caligraphic-Bold-ATXxdsX0.ttf +0 -0
  23. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Caligraphic-Bold-BEiXGLvX.woff +0 -0
  24. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Caligraphic-Bold-Dq_IR9rO.woff2 +0 -0
  25. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Caligraphic-Regular-CTRA-rTL.woff +0 -0
  26. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Caligraphic-Regular-Di6jR-x-.woff2 +0 -0
  27. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Caligraphic-Regular-wX97UBjC.ttf +0 -0
  28. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Fraktur-Bold-BdnERNNW.ttf +0 -0
  29. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Fraktur-Bold-BsDP51OF.woff +0 -0
  30. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Fraktur-Bold-CL6g_b3V.woff2 +0 -0
  31. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Fraktur-Regular-CB_wures.ttf +0 -0
  32. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Fraktur-Regular-CTYiF6lA.woff2 +0 -0
  33. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Fraktur-Regular-Dxdc4cR9.woff +0 -0
  34. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Main-Bold-Cx986IdX.woff2 +0 -0
  35. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Main-Bold-Jm3AIy58.woff +0 -0
  36. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Main-Bold-waoOVXN0.ttf +0 -0
  37. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Main-BoldItalic-DxDJ3AOS.woff2 +0 -0
  38. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Main-BoldItalic-DzxPMmG6.ttf +0 -0
  39. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Main-BoldItalic-SpSLRI95.woff +0 -0
  40. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Main-Italic-3WenGoN9.ttf +0 -0
  41. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Main-Italic-BMLOBm91.woff +0 -0
  42. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Main-Italic-NWA7e6Wa.woff2 +0 -0
  43. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Main-Regular-B22Nviop.woff2 +0 -0
  44. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Main-Regular-Dr94JaBh.woff +0 -0
  45. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Main-Regular-ypZvNtVU.ttf +0 -0
  46. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Math-BoldItalic-B3XSjfu4.ttf +0 -0
  47. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Math-BoldItalic-CZnvNsCZ.woff2 +0 -0
  48. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Math-BoldItalic-iY-2wyZ7.woff +0 -0
  49. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Math-Italic-DA0__PXp.woff +0 -0
  50. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Math-Italic-flOr_0UB.ttf +0 -0
  51. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Math-Italic-t53AETM-.woff2 +0 -0
  52. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_SansSerif-Bold-CFMepnvq.ttf +0 -0
  53. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_SansSerif-Bold-D1sUS0GD.woff2 +0 -0
  54. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_SansSerif-Bold-DbIhKOiC.woff +0 -0
  55. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_SansSerif-Italic-C3H0VqGB.woff2 +0 -0
  56. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_SansSerif-Italic-DN2j7dab.woff +0 -0
  57. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_SansSerif-Italic-YYjJ1zSn.ttf +0 -0
  58. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_SansSerif-Regular-BNo7hRIc.ttf +0 -0
  59. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_SansSerif-Regular-CS6fqUqJ.woff +0 -0
  60. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_SansSerif-Regular-DDBCnlJ7.woff2 +0 -0
  61. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Script-Regular-C5JkGWo-.ttf +0 -0
  62. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Script-Regular-D3wIWfF6.woff2 +0 -0
  63. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Script-Regular-D5yQViql.woff +0 -0
  64. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Size1-Regular-C195tn64.woff +0 -0
  65. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Size1-Regular-Dbsnue_I.ttf +0 -0
  66. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Size1-Regular-mCD8mA8B.woff2 +0 -0
  67. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Size2-Regular-B7gKUWhC.ttf +0 -0
  68. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Size2-Regular-Dy4dx90m.woff2 +0 -0
  69. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Size2-Regular-oD1tc_U0.woff +0 -0
  70. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Size3-Regular-CTq5MqoE.woff +0 -0
  71. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Size3-Regular-DgpXs0kz.ttf +0 -0
  72. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Size4-Regular-BF-4gkZK.woff +0 -0
  73. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Size4-Regular-DWFBv043.ttf +0 -0
  74. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Size4-Regular-Dl5lxZxV.woff2 +0 -0
  75. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Typewriter-Regular-C0xS9mPB.woff +0 -0
  76. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Typewriter-Regular-CO6r4hn1.woff2 +0 -0
  77. neurolume-0.1.0/python/neurolume/static/assets/KaTeX_Typewriter-Regular-D3Ib7_Hf.ttf +0 -0
  78. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-cyrillic-400-normal-BSMlKf0J.woff2 +0 -0
  79. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-cyrillic-400-normal-CEL4l2ZJ.woff +0 -0
  80. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-cyrillic-500-normal-Ael50iVv.woff +0 -0
  81. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-cyrillic-500-normal-Bq9vWWag.woff2 +0 -0
  82. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-cyrillic-ext-400-normal-DMdlQ8Kv.woff +0 -0
  83. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-cyrillic-ext-400-normal-xuaO2J-f.woff2 +0 -0
  84. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-cyrillic-ext-500-normal-BIfNGwUT.woff +0 -0
  85. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-cyrillic-ext-500-normal-BqneJy0T.woff2 +0 -0
  86. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-latin-400-normal-CvHOgSBP.woff +0 -0
  87. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-latin-400-normal-DMJ8VG8y.woff2 +0 -0
  88. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-latin-500-normal-CB9ihrfo.woff +0 -0
  89. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-latin-500-normal-DSY6xOcd.woff2 +0 -0
  90. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-latin-ext-400-normal-BmRBH3aV.woff2 +0 -0
  91. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-latin-ext-400-normal-D3D2R8hC.woff +0 -0
  92. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-latin-ext-500-normal-CAhNIIs5.woff2 +0 -0
  93. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-latin-ext-500-normal-CZ70TYgx.woff +0 -0
  94. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-vietnamese-400-normal-BulugwFq.woff2 +0 -0
  95. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-vietnamese-400-normal-DDuiU_S-.woff +0 -0
  96. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-vietnamese-500-normal-C8zxqsMH.woff +0 -0
  97. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-mono-vietnamese-500-normal-DZ4AoWbu.woff2 +0 -0
  98. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-sans-cyrillic-ext-wght-normal-d45eAU9y.woff2 +0 -0
  99. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-sans-cyrillic-wght-normal-BAAhND-U.woff2 +0 -0
  100. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-sans-greek-wght-normal-CmyJS8uq.woff2 +0 -0
  101. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-sans-latin-ext-wght-normal-CIII54If.woff2 +0 -0
  102. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-sans-latin-wght-normal-IvpUvPa2.woff2 +0 -0
  103. neurolume-0.1.0/python/neurolume/static/assets/ibm-plex-sans-vietnamese-wght-normal-Dg1JeJN0.woff2 +0 -0
  104. neurolume-0.1.0/python/neurolume/static/assets/index-BXnWQi2p.css +1 -0
  105. neurolume-0.1.0/python/neurolume/static/assets/index-D-Lwaa28.js +4062 -0
  106. neurolume-0.1.0/python/neurolume/static/assets/live-B-d7TNM4.js +92 -0
  107. neurolume-0.1.0/python/neurolume/static/assets/notes-BJmosK-V.css +1 -0
  108. neurolume-0.1.0/python/neurolume/static/assets/notes-BKaGThLj.js +328 -0
  109. neurolume-0.1.0/python/neurolume/static/export/index.html +7 -0
  110. neurolume-0.1.0/python/neurolume/static/export/viewer.css +1 -0
  111. neurolume-0.1.0/python/neurolume/static/export/viewer.js +4479 -0
  112. neurolume-0.1.0/python/neurolume/static/index.html +7 -0
  113. neurolume-0.1.0/python/neurolume/system.py +231 -0
  114. neurolume-0.1.0/python/neurolume/weights.py +57 -0
  115. neurolume-0.1.0/python/neurolume.egg-info/PKG-INFO +330 -0
  116. neurolume-0.1.0/python/neurolume.egg-info/SOURCES.txt +130 -0
  117. neurolume-0.1.0/python/neurolume.egg-info/dependency_links.txt +1 -0
  118. neurolume-0.1.0/python/neurolume.egg-info/entry_points.txt +2 -0
  119. neurolume-0.1.0/python/neurolume.egg-info/requires.txt +23 -0
  120. neurolume-0.1.0/python/neurolume.egg-info/top_level.txt +1 -0
  121. neurolume-0.1.0/setup.cfg +4 -0
  122. neurolume-0.1.0/tests/test_demo.py +25 -0
  123. neurolume-0.1.0/tests/test_export.py +18 -0
  124. neurolume-0.1.0/tests/test_feature_maps.py +40 -0
  125. neurolume-0.1.0/tests/test_imports.py +22 -0
  126. neurolume-0.1.0/tests/test_keras_adapter.py +159 -0
  127. neurolume-0.1.0/tests/test_live.py +252 -0
  128. neurolume-0.1.0/tests/test_qt.py +44 -0
  129. neurolume-0.1.0/tests/test_schema.py +87 -0
  130. neurolume-0.1.0/tests/test_system.py +170 -0
  131. neurolume-0.1.0/tests/test_torch_adapter.py +280 -0
  132. neurolume-0.1.0/tests/test_weights.py +33 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Freddie Ellis
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,330 @@
1
+ Metadata-Version: 2.4
2
+ Name: neurolume
3
+ Version: 0.1.0
4
+ Summary: See your PyTorch and Keras models as interactive diagrams, and watch them train.
5
+ Author: Freddie Ellis
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Freddie-Ellis/neurolume
8
+ Project-URL: Source, https://github.com/Freddie-Ellis/neurolume
9
+ Project-URL: Issues, https://github.com/Freddie-Ellis/neurolume/issues
10
+ Keywords: neural network,visualisation,pytorch,keras,deep learning,training,architecture
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Intended Audience :: Education
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
18
+ Classifier: Topic :: Scientific/Engineering :: Visualization
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: numpy>=1.24
24
+ Requires-Dist: pydantic>=2.5
25
+ Requires-Dist: tornado>=6.4
26
+ Provides-Extra: torch
27
+ Requires-Dist: torch>=2.0; extra == "torch"
28
+ Provides-Extra: tensorflow
29
+ Requires-Dist: tensorflow>=2.15; extra == "tensorflow"
30
+ Provides-Extra: keras
31
+ Requires-Dist: keras>=3.0; extra == "keras"
32
+ Provides-Extra: qt
33
+ Requires-Dist: qtpy>=2.4; extra == "qt"
34
+ Provides-Extra: dev
35
+ Requires-Dist: pytest>=8.0; extra == "dev"
36
+ Requires-Dist: ruff>=0.6; extra == "dev"
37
+ Requires-Dist: build>=1.2; extra == "dev"
38
+ Provides-Extra: examples
39
+ Requires-Dist: torchvision>=0.17; extra == "examples"
40
+ Dynamic: license-file
41
+
42
+ # Neurolume
43
+
44
+ **See your PyTorch and Keras models as interactive diagrams, and watch them train... (If it's working)**
45
+
46
+ Neurolume runs your model once to learn its shape, then opens an interactive
47
+ viewer in the browser: every layer as a panel, every dense connection as a
48
+ line, feature maps painted with what the model actually sees. Several models
49
+ wired together become one schematic you can open level by level. While you
50
+ train, the same viewer shows the loss, whether the model is overfitting, its
51
+ predictions against the truth, and how its parameters change, and lets you
52
+ scrub back through the run.
53
+
54
+ ![A 784-512-256-10 MLP in the Neurolume viewer](https://raw.githubusercontent.com/Freddie-Ellis/neurolume/main/docs/images/mlp.png)
55
+
56
+ - One call: `neurolume.show(model, sample)`. No account, no log files, nothing to set up.
57
+ - PyTorch and Keras 3, CNNs (with real feature maps), residual and branching models.
58
+ - Systems: several networks plus plain blocks (sensors, losses, outputs) in one diagram, nested as deep as you like.
59
+ - Live training: a calmer, more readable alternative to TensorBoard, in the browser or embedded in a Qt app.
60
+ - Export to one standalone HTML file that opens anywhere, offline.
61
+
62
+ ## Install
63
+
64
+ ```bash
65
+ pip install "neurolume[torch]" # with PyTorch
66
+ pip install "neurolume[keras]" # with Keras 3, plus a backend: TensorFlow, JAX or PyTorch
67
+ ```
68
+
69
+ Neurolume needs Python 3.10 or later. The viewer runs in any modern browser;
70
+ nothing else needs installing. (Keras with PyTorch underneath: install `torch`
71
+ too and set `KERAS_BACKEND=torch`.)
72
+
73
+ ## Example 1: a model
74
+
75
+ ```python
76
+ import neurolume
77
+ import torch
78
+ from torch import nn
79
+
80
+
81
+ class MLP(nn.Module):
82
+ def __init__(self) -> None:
83
+ super().__init__()
84
+ self.flatten = nn.Flatten()
85
+ self.fc1 = nn.Linear(784, 512)
86
+ self.relu1 = nn.ReLU()
87
+ self.dropout = nn.Dropout(0.2)
88
+ self.fc2 = nn.Linear(512, 256)
89
+ self.relu2 = nn.ReLU()
90
+ self.fc3 = nn.Linear(256, 10)
91
+
92
+ def forward(self, x: torch.Tensor) -> torch.Tensor:
93
+ x = self.flatten(x)
94
+ x = self.dropout(self.relu1(self.fc1(x)))
95
+ x = self.relu2(self.fc2(x))
96
+ return self.fc3(x)
97
+
98
+
99
+ neurolume.show(MLP(), (1, 28, 28)) # the shape of one input: 1 channel, 28 x 28 pixels
100
+ ```
101
+
102
+ This opens the viewer shown at the top of this page. Each layer is a panel;
103
+ the lines between them are the strongest weights, brighter where the weight is
104
+ larger. Click a layer for its details, scroll to zoom, drag to pan.
105
+
106
+ The second argument, `sample`, tells Neurolume what goes into the model:
107
+
108
+ - the **shape** of one input, without the batch dimension, like `(1, 28, 28)`.
109
+ Enough to draw the architecture.
110
+ - **real data**, such as a batch of images. Convolution layers then show their
111
+ actual feature maps for that input.
112
+
113
+ Neurolume follows the data through your model's `forward` method to find the
114
+ layers and how they connect, so a PyTorch model needs a `forward` (or must be
115
+ an `nn.Sequential`). Keras models that start with `keras.Input` don't need a
116
+ sample at all.
117
+
118
+ Run it: [`examples/mlp.py`](examples/mlp.py).
119
+
120
+ ## Example 2: a system of networks
121
+
122
+ Real projects are often several networks wired together. Add each one, plus
123
+ any plain blocks such as data sources or losses, and connect them:
124
+
125
+ ```python
126
+ import neurolume
127
+ from torch import nn
128
+
129
+
130
+ def mlp(*sizes):
131
+ layers = []
132
+ for i, (inputs, outputs) in enumerate(zip(sizes, sizes[1:])):
133
+ layers.append(nn.Linear(inputs, outputs))
134
+ if i < len(sizes) - 2:
135
+ layers.append(nn.ReLU())
136
+ return nn.Sequential(*layers)
137
+
138
+
139
+ system = neurolume.System("Sensor autoencoder")
140
+ sensor = system.block("sensor", label="Sensor", description="32 readings per sample", output_shape=[32])
141
+ encoder = system.add("encoder", mlp(32, 64, 64, 16), (32,), label="Encoder")
142
+ decoder = system.add("decoder", mlp(16, 64, 64, 32), (16,), label="Decoder")
143
+ classifier = system.add("classifier", mlp(16, 12, 3), (16,), label="Classifier")
144
+ loss = system.block("loss", label="Reconstruction loss", description="Mean squared error", input_shape=[32])
145
+ prediction = system.block("prediction", label="Fault type", input_shape=[3])
146
+
147
+ system.connect(sensor, encoder, label="readings")
148
+ system.connect(encoder, decoder, label="latent")
149
+ system.connect(encoder, classifier, label="latent")
150
+ system.connect(decoder, loss)
151
+ system.connect(classifier, prediction, label="logits")
152
+
153
+ neurolume.show(system)
154
+ ```
155
+
156
+ ![A system of three networks and three blocks](https://raw.githubusercontent.com/Freddie-Ellis/neurolume/main/docs/images/system.png)
157
+
158
+ The viewer opens on an overview: one card per network or block, with labelled
159
+ links between them. Click a card (or zoom into it) to open its layers; press
160
+ `Esc` or zoom out to go back. Blocks can carry Markdown notes with LaTeX maths
161
+ (`notes=...`), shown when you click them.
162
+
163
+ Run it: [`examples/system.py`](examples/system.py).
164
+
165
+ ## Example 3: systems inside systems
166
+
167
+ A component can itself be a System, or a model with parts of its own. Each one
168
+ opens to its own overview, as many levels deep as you need:
169
+
170
+ ```python
171
+ import neurolume
172
+ from autoencoder import Autoencoder # a model with self.encoder and self.decoder
173
+ from system import build_system # the System from example 2
174
+
175
+ plant = neurolume.System("Plant monitor")
176
+ camera = plant.block("camera", label="Camera", description="Noisy 28 x 28 frames", output_shape=[1, 28, 28])
177
+ denoiser = plant.add("denoiser", Autoencoder(), (1, 28, 28), label="Denoiser")
178
+ sensors = plant.block("sensors", label="Sensor bus", description="32 readings per tick", output_shape=[32])
179
+ detector = plant.add("detector", build_system(), label="Fault detector") # a whole System as one component
180
+ alarm = plant.block("alarm", label="Alarm", description="Raise a ticket on a fault", input_shape=[3])
181
+ display = plant.block("display", label="Operator screen", input_shape=[784])
182
+
183
+ plant.connect(camera, denoiser, label="frames")
184
+ plant.connect(denoiser, display, label="clean frames")
185
+ plant.connect(sensors, detector, label="readings")
186
+ plant.connect(detector, alarm, label="fault type", from_="prediction") # the detector has two outputs
187
+
188
+ neurolume.show(plant)
189
+ ```
190
+
191
+ ![A system containing a model with parts and another whole system](https://raw.githubusercontent.com/Freddie-Ellis/neurolume/main/docs/images/nested-system.png)
192
+
193
+ The "Denoiser" card opens to its encoder and decoder; the "Fault detector"
194
+ card opens to the whole system from example 2. Links from outside attach to
195
+ its ends: the readings reach its sensor block, and the fault type leaves from
196
+ its prediction block. The tree at the bottom left shows every level.
197
+
198
+ A single PyTorch module that keeps its parts in attributes (`self.encoder`,
199
+ `self.decoder`) is split into networks like this automatically. Pass
200
+ `group_submodules=False` to `show` to keep it as one network.
201
+
202
+ Run it: [`examples/nested_system.py`](examples/nested_system.py).
203
+
204
+ ## Watching a model train (beta)
205
+
206
+ Swap `show` for `watch` and log as you go:
207
+
208
+ ```python
209
+ live = neurolume.watch(model, (8,))
210
+ for step in range(steps):
211
+ loss = train_step() # forward, backward, optimiser step
212
+ live.log(step, loss=loss) # after backward(); tensors are fine
213
+ if step % 100 == 0:
214
+ live.log(step, split="val", loss=val_loss)
215
+ live.predictions(step, predicted, target) # e.g. on a validation batch
216
+ live.finish() # the viewer stays open until Ctrl+C
217
+ ```
218
+
219
+ ![The Training panel: an overfitting verdict, predictions vs truth, loss curves and parameter charts](https://raw.githubusercontent.com/Freddie-Ellis/neurolume/main/docs/images/live.png)
220
+
221
+ The viewer gains a run strip (step, the main metric, its trend) and a
222
+ **Training** panel:
223
+
224
+ - **Summary:** whether the run is `improving`, `levelling off`, `converged`,
225
+ `getting worse` or `overfitting` (validation getting worse while training
226
+ still improves), the gap between validation and training, and the best
227
+ validation point.
228
+ - **Predictions vs truth:** a predicted-against-true scatter with R² and mean
229
+ error, or a confusion matrix when the targets are class labels.
230
+ - **Metrics:** a chart for each metric you log, with training and validation
231
+ together. Smooth, log-scale, reorder, hide, combine or pin them; the layout is
232
+ remembered per model.
233
+ - **Parameters:** the weight norm (how large the weights are overall), the
234
+ gradient norm, how fast the parameters move, and how their values are spread
235
+ over time.
236
+
237
+ The network itself updates too: lines brighten and fade as the weights change
238
+ (or show the change since the start, or the gradient), and CNN feature maps
239
+ repaint as the filters learn. Drag the **timeline** to scrub back through the
240
+ run. `live.save("run.nlrun")` keeps it; `neurolume.open_run("run.nlrun")` opens
241
+ it again later.
242
+
243
+ `log()` costs microseconds; the model is read at most every half second
244
+ (`every_seconds=0.5`): about 1% of training time for an MLP, and live feature
245
+ maps are kept under 2%.
246
+
247
+ - **Keras:** `model.fit(x, y, callbacks=[neurolume.keras.Live(x[:64], validation=(x_val, y_val))])`.
248
+ - **Systems:** `neurolume.watch(system)` follows every network, nested ones
249
+ included; `live.log(step, network="critic", loss=...)` logs per network.
250
+
251
+ Run it: [`examples/live_training.py`](examples/live_training.py) (a small
252
+ model that overfits on purpose), [`examples/live_resnet.py`](examples/live_resnet.py)
253
+ (ResNet-18 with live feature maps), [`examples/live_nested_system.py`](examples/live_nested_system.py)
254
+ (example 3's plant monitor, every network training at once),
255
+ [`examples/keras_live.py`](examples/keras_live.py).
256
+
257
+ ## Sharing: a standalone HTML file
258
+
259
+ ```python
260
+ neurolume.export_html(model, (1, 28, 28), "model.html")
261
+ neurolume.export_html(live, path="run.html") # a training run, with its charts and timeline
262
+ ```
263
+
264
+ One file with the viewer and your model inside. It opens from disk or an email
265
+ attachment, offline, with no Python. The **Export** button in the viewer's
266
+ Settings does the same.
267
+
268
+ ## Embedding in a Qt app
269
+
270
+ ```python
271
+ from neurolume.qt import NeurolumeWidget # import before creating the QApplication
272
+
273
+ widget = NeurolumeWidget(model, (1, 28, 28))
274
+ layout.addWidget(widget)
275
+ session = widget.watch(model, sample) # or show a live run, and log() to it
276
+ ```
277
+
278
+ A `QWebEngineView` with the same viewer, for your own tools and training
279
+ loggers. Needs `pip install "neurolume[qt]" PySide6`. See
280
+ [`examples/qt_widget.py`](examples/qt_widget.py) and
281
+ [`examples/qt_live.py`](examples/qt_live.py) (a logger with Start/Stop, training
282
+ on a background thread).
283
+
284
+ ## Viewer controls
285
+
286
+ | Action | Control |
287
+ | --- | --- |
288
+ | Zoom | Scroll |
289
+ | Pan | Drag |
290
+ | Layer or block details | Click |
291
+ | Open a network | Click, or zoom in |
292
+ | Back to the overview | Zoom out, or `Esc` |
293
+ | Fit to screen | Double-click, or `F` |
294
+ | Light or dark | `T` |
295
+
296
+ Settings (top right) has the colour map, the theme, how many neurons and
297
+ connections to draw, and Export.
298
+
299
+ ## How it works
300
+
301
+ Python runs your model once on the sample (with `torch.fx`, or Keras's own
302
+ layer graph) and describes it as a JSON graph: layers, shapes, connections,
303
+ the strongest weights, feature maps. A small local server
304
+ ([Tornado](https://www.tornadoweb.org)) hands that graph to a TypeScript and
305
+ three.js viewer in your browser. During training, the same server streams
306
+ metrics and weights over a WebSocket. Nothing leaves your machine.
307
+
308
+ ## Development
309
+
310
+ ```bash
311
+ git clone https://github.com/Freddie-Ellis/neurolume
312
+ cd neurolume
313
+ pip install -e ".[dev,torch]"
314
+ pytest
315
+ ```
316
+
317
+ The viewer lives in `frontend/` (TypeScript, Vite, three.js; Node 18+). After
318
+ changing it, rebuild it into the Python package with
319
+ `scripts/build_frontend.ps1` (PowerShell), and run its tests with `npm test` in
320
+ `frontend/`. For live reloading, run `neurolume.show(model, x, port=8000)` and
321
+ `npm run dev` in `frontend/`.
322
+
323
+ The JSON schema in `python/neurolume/schema.py` is the contract between
324
+ Python and the viewer: after changing it, bump `SCHEMA_VERSION` and run
325
+ `python scripts/generate_schema_ts.py`. The roadmap is
326
+ [`docs/project-plan.md`](docs/project-plan.md).
327
+
328
+ ## Licence
329
+
330
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,289 @@
1
+ # Neurolume
2
+
3
+ **See your PyTorch and Keras models as interactive diagrams, and watch them train... (If it's working)**
4
+
5
+ Neurolume runs your model once to learn its shape, then opens an interactive
6
+ viewer in the browser: every layer as a panel, every dense connection as a
7
+ line, feature maps painted with what the model actually sees. Several models
8
+ wired together become one schematic you can open level by level. While you
9
+ train, the same viewer shows the loss, whether the model is overfitting, its
10
+ predictions against the truth, and how its parameters change, and lets you
11
+ scrub back through the run.
12
+
13
+ ![A 784-512-256-10 MLP in the Neurolume viewer](https://raw.githubusercontent.com/Freddie-Ellis/neurolume/main/docs/images/mlp.png)
14
+
15
+ - One call: `neurolume.show(model, sample)`. No account, no log files, nothing to set up.
16
+ - PyTorch and Keras 3, CNNs (with real feature maps), residual and branching models.
17
+ - Systems: several networks plus plain blocks (sensors, losses, outputs) in one diagram, nested as deep as you like.
18
+ - Live training: a calmer, more readable alternative to TensorBoard, in the browser or embedded in a Qt app.
19
+ - Export to one standalone HTML file that opens anywhere, offline.
20
+
21
+ ## Install
22
+
23
+ ```bash
24
+ pip install "neurolume[torch]" # with PyTorch
25
+ pip install "neurolume[keras]" # with Keras 3, plus a backend: TensorFlow, JAX or PyTorch
26
+ ```
27
+
28
+ Neurolume needs Python 3.10 or later. The viewer runs in any modern browser;
29
+ nothing else needs installing. (Keras with PyTorch underneath: install `torch`
30
+ too and set `KERAS_BACKEND=torch`.)
31
+
32
+ ## Example 1: a model
33
+
34
+ ```python
35
+ import neurolume
36
+ import torch
37
+ from torch import nn
38
+
39
+
40
+ class MLP(nn.Module):
41
+ def __init__(self) -> None:
42
+ super().__init__()
43
+ self.flatten = nn.Flatten()
44
+ self.fc1 = nn.Linear(784, 512)
45
+ self.relu1 = nn.ReLU()
46
+ self.dropout = nn.Dropout(0.2)
47
+ self.fc2 = nn.Linear(512, 256)
48
+ self.relu2 = nn.ReLU()
49
+ self.fc3 = nn.Linear(256, 10)
50
+
51
+ def forward(self, x: torch.Tensor) -> torch.Tensor:
52
+ x = self.flatten(x)
53
+ x = self.dropout(self.relu1(self.fc1(x)))
54
+ x = self.relu2(self.fc2(x))
55
+ return self.fc3(x)
56
+
57
+
58
+ neurolume.show(MLP(), (1, 28, 28)) # the shape of one input: 1 channel, 28 x 28 pixels
59
+ ```
60
+
61
+ This opens the viewer shown at the top of this page. Each layer is a panel;
62
+ the lines between them are the strongest weights, brighter where the weight is
63
+ larger. Click a layer for its details, scroll to zoom, drag to pan.
64
+
65
+ The second argument, `sample`, tells Neurolume what goes into the model:
66
+
67
+ - the **shape** of one input, without the batch dimension, like `(1, 28, 28)`.
68
+ Enough to draw the architecture.
69
+ - **real data**, such as a batch of images. Convolution layers then show their
70
+ actual feature maps for that input.
71
+
72
+ Neurolume follows the data through your model's `forward` method to find the
73
+ layers and how they connect, so a PyTorch model needs a `forward` (or must be
74
+ an `nn.Sequential`). Keras models that start with `keras.Input` don't need a
75
+ sample at all.
76
+
77
+ Run it: [`examples/mlp.py`](examples/mlp.py).
78
+
79
+ ## Example 2: a system of networks
80
+
81
+ Real projects are often several networks wired together. Add each one, plus
82
+ any plain blocks such as data sources or losses, and connect them:
83
+
84
+ ```python
85
+ import neurolume
86
+ from torch import nn
87
+
88
+
89
+ def mlp(*sizes):
90
+ layers = []
91
+ for i, (inputs, outputs) in enumerate(zip(sizes, sizes[1:])):
92
+ layers.append(nn.Linear(inputs, outputs))
93
+ if i < len(sizes) - 2:
94
+ layers.append(nn.ReLU())
95
+ return nn.Sequential(*layers)
96
+
97
+
98
+ system = neurolume.System("Sensor autoencoder")
99
+ sensor = system.block("sensor", label="Sensor", description="32 readings per sample", output_shape=[32])
100
+ encoder = system.add("encoder", mlp(32, 64, 64, 16), (32,), label="Encoder")
101
+ decoder = system.add("decoder", mlp(16, 64, 64, 32), (16,), label="Decoder")
102
+ classifier = system.add("classifier", mlp(16, 12, 3), (16,), label="Classifier")
103
+ loss = system.block("loss", label="Reconstruction loss", description="Mean squared error", input_shape=[32])
104
+ prediction = system.block("prediction", label="Fault type", input_shape=[3])
105
+
106
+ system.connect(sensor, encoder, label="readings")
107
+ system.connect(encoder, decoder, label="latent")
108
+ system.connect(encoder, classifier, label="latent")
109
+ system.connect(decoder, loss)
110
+ system.connect(classifier, prediction, label="logits")
111
+
112
+ neurolume.show(system)
113
+ ```
114
+
115
+ ![A system of three networks and three blocks](https://raw.githubusercontent.com/Freddie-Ellis/neurolume/main/docs/images/system.png)
116
+
117
+ The viewer opens on an overview: one card per network or block, with labelled
118
+ links between them. Click a card (or zoom into it) to open its layers; press
119
+ `Esc` or zoom out to go back. Blocks can carry Markdown notes with LaTeX maths
120
+ (`notes=...`), shown when you click them.
121
+
122
+ Run it: [`examples/system.py`](examples/system.py).
123
+
124
+ ## Example 3: systems inside systems
125
+
126
+ A component can itself be a System, or a model with parts of its own. Each one
127
+ opens to its own overview, as many levels deep as you need:
128
+
129
+ ```python
130
+ import neurolume
131
+ from autoencoder import Autoencoder # a model with self.encoder and self.decoder
132
+ from system import build_system # the System from example 2
133
+
134
+ plant = neurolume.System("Plant monitor")
135
+ camera = plant.block("camera", label="Camera", description="Noisy 28 x 28 frames", output_shape=[1, 28, 28])
136
+ denoiser = plant.add("denoiser", Autoencoder(), (1, 28, 28), label="Denoiser")
137
+ sensors = plant.block("sensors", label="Sensor bus", description="32 readings per tick", output_shape=[32])
138
+ detector = plant.add("detector", build_system(), label="Fault detector") # a whole System as one component
139
+ alarm = plant.block("alarm", label="Alarm", description="Raise a ticket on a fault", input_shape=[3])
140
+ display = plant.block("display", label="Operator screen", input_shape=[784])
141
+
142
+ plant.connect(camera, denoiser, label="frames")
143
+ plant.connect(denoiser, display, label="clean frames")
144
+ plant.connect(sensors, detector, label="readings")
145
+ plant.connect(detector, alarm, label="fault type", from_="prediction") # the detector has two outputs
146
+
147
+ neurolume.show(plant)
148
+ ```
149
+
150
+ ![A system containing a model with parts and another whole system](https://raw.githubusercontent.com/Freddie-Ellis/neurolume/main/docs/images/nested-system.png)
151
+
152
+ The "Denoiser" card opens to its encoder and decoder; the "Fault detector"
153
+ card opens to the whole system from example 2. Links from outside attach to
154
+ its ends: the readings reach its sensor block, and the fault type leaves from
155
+ its prediction block. The tree at the bottom left shows every level.
156
+
157
+ A single PyTorch module that keeps its parts in attributes (`self.encoder`,
158
+ `self.decoder`) is split into networks like this automatically. Pass
159
+ `group_submodules=False` to `show` to keep it as one network.
160
+
161
+ Run it: [`examples/nested_system.py`](examples/nested_system.py).
162
+
163
+ ## Watching a model train (beta)
164
+
165
+ Swap `show` for `watch` and log as you go:
166
+
167
+ ```python
168
+ live = neurolume.watch(model, (8,))
169
+ for step in range(steps):
170
+ loss = train_step() # forward, backward, optimiser step
171
+ live.log(step, loss=loss) # after backward(); tensors are fine
172
+ if step % 100 == 0:
173
+ live.log(step, split="val", loss=val_loss)
174
+ live.predictions(step, predicted, target) # e.g. on a validation batch
175
+ live.finish() # the viewer stays open until Ctrl+C
176
+ ```
177
+
178
+ ![The Training panel: an overfitting verdict, predictions vs truth, loss curves and parameter charts](https://raw.githubusercontent.com/Freddie-Ellis/neurolume/main/docs/images/live.png)
179
+
180
+ The viewer gains a run strip (step, the main metric, its trend) and a
181
+ **Training** panel:
182
+
183
+ - **Summary:** whether the run is `improving`, `levelling off`, `converged`,
184
+ `getting worse` or `overfitting` (validation getting worse while training
185
+ still improves), the gap between validation and training, and the best
186
+ validation point.
187
+ - **Predictions vs truth:** a predicted-against-true scatter with R² and mean
188
+ error, or a confusion matrix when the targets are class labels.
189
+ - **Metrics:** a chart for each metric you log, with training and validation
190
+ together. Smooth, log-scale, reorder, hide, combine or pin them; the layout is
191
+ remembered per model.
192
+ - **Parameters:** the weight norm (how large the weights are overall), the
193
+ gradient norm, how fast the parameters move, and how their values are spread
194
+ over time.
195
+
196
+ The network itself updates too: lines brighten and fade as the weights change
197
+ (or show the change since the start, or the gradient), and CNN feature maps
198
+ repaint as the filters learn. Drag the **timeline** to scrub back through the
199
+ run. `live.save("run.nlrun")` keeps it; `neurolume.open_run("run.nlrun")` opens
200
+ it again later.
201
+
202
+ `log()` costs microseconds; the model is read at most every half second
203
+ (`every_seconds=0.5`): about 1% of training time for an MLP, and live feature
204
+ maps are kept under 2%.
205
+
206
+ - **Keras:** `model.fit(x, y, callbacks=[neurolume.keras.Live(x[:64], validation=(x_val, y_val))])`.
207
+ - **Systems:** `neurolume.watch(system)` follows every network, nested ones
208
+ included; `live.log(step, network="critic", loss=...)` logs per network.
209
+
210
+ Run it: [`examples/live_training.py`](examples/live_training.py) (a small
211
+ model that overfits on purpose), [`examples/live_resnet.py`](examples/live_resnet.py)
212
+ (ResNet-18 with live feature maps), [`examples/live_nested_system.py`](examples/live_nested_system.py)
213
+ (example 3's plant monitor, every network training at once),
214
+ [`examples/keras_live.py`](examples/keras_live.py).
215
+
216
+ ## Sharing: a standalone HTML file
217
+
218
+ ```python
219
+ neurolume.export_html(model, (1, 28, 28), "model.html")
220
+ neurolume.export_html(live, path="run.html") # a training run, with its charts and timeline
221
+ ```
222
+
223
+ One file with the viewer and your model inside. It opens from disk or an email
224
+ attachment, offline, with no Python. The **Export** button in the viewer's
225
+ Settings does the same.
226
+
227
+ ## Embedding in a Qt app
228
+
229
+ ```python
230
+ from neurolume.qt import NeurolumeWidget # import before creating the QApplication
231
+
232
+ widget = NeurolumeWidget(model, (1, 28, 28))
233
+ layout.addWidget(widget)
234
+ session = widget.watch(model, sample) # or show a live run, and log() to it
235
+ ```
236
+
237
+ A `QWebEngineView` with the same viewer, for your own tools and training
238
+ loggers. Needs `pip install "neurolume[qt]" PySide6`. See
239
+ [`examples/qt_widget.py`](examples/qt_widget.py) and
240
+ [`examples/qt_live.py`](examples/qt_live.py) (a logger with Start/Stop, training
241
+ on a background thread).
242
+
243
+ ## Viewer controls
244
+
245
+ | Action | Control |
246
+ | --- | --- |
247
+ | Zoom | Scroll |
248
+ | Pan | Drag |
249
+ | Layer or block details | Click |
250
+ | Open a network | Click, or zoom in |
251
+ | Back to the overview | Zoom out, or `Esc` |
252
+ | Fit to screen | Double-click, or `F` |
253
+ | Light or dark | `T` |
254
+
255
+ Settings (top right) has the colour map, the theme, how many neurons and
256
+ connections to draw, and Export.
257
+
258
+ ## How it works
259
+
260
+ Python runs your model once on the sample (with `torch.fx`, or Keras's own
261
+ layer graph) and describes it as a JSON graph: layers, shapes, connections,
262
+ the strongest weights, feature maps. A small local server
263
+ ([Tornado](https://www.tornadoweb.org)) hands that graph to a TypeScript and
264
+ three.js viewer in your browser. During training, the same server streams
265
+ metrics and weights over a WebSocket. Nothing leaves your machine.
266
+
267
+ ## Development
268
+
269
+ ```bash
270
+ git clone https://github.com/Freddie-Ellis/neurolume
271
+ cd neurolume
272
+ pip install -e ".[dev,torch]"
273
+ pytest
274
+ ```
275
+
276
+ The viewer lives in `frontend/` (TypeScript, Vite, three.js; Node 18+). After
277
+ changing it, rebuild it into the Python package with
278
+ `scripts/build_frontend.ps1` (PowerShell), and run its tests with `npm test` in
279
+ `frontend/`. For live reloading, run `neurolume.show(model, x, port=8000)` and
280
+ `npm run dev` in `frontend/`.
281
+
282
+ The JSON schema in `python/neurolume/schema.py` is the contract between
283
+ Python and the viewer: after changing it, bump `SCHEMA_VERSION` and run
284
+ `python scripts/generate_schema_ts.py`. The roadmap is
285
+ [`docs/project-plan.md`](docs/project-plan.md).
286
+
287
+ ## Licence
288
+
289
+ MIT. See [LICENSE](LICENSE).