neuralplex 0.3.2__tar.gz → 0.4.0__tar.gz

{neuralplex-0.3.2 → neuralplex-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: neuralplex
-Version: 0.3.2
+Version: 0.4.0
 Summary: A neural network implementation built as an explicit graph of neurons and weighted connections.
 Project-URL: Homepage, https://github.com/adamjpatterson/neuralplex
 Project-URL: Issues, https://github.com/adamjpatterson/neuralplex/issues
@@ -20,7 +20,7 @@ A neural network implementation built as an explicit graph of neurons and weight
 
 ## Introduction
 
-**Neural-pleX** represents individual neurons and their connections explicitly, with manual backpropagation. The Neural-pleX API consists of Network, Layer, and Neuron constructors. The networks can be easily [visualized](#visualizations-of-the-network-before-and-after-training) using a visualization library.
+**Neural-pleX** represents individual neurons and their connections explicitly. Backpropagation is done using explicitly computed gradients. The object-oriented API consists of Network, Layer, and Neuron constructors. The networks can be easily [visualized](#visualizations-of-the-network-before-and-after-training) using a visualization library.
 
 ## Table of contents
 
@@ -113,7 +113,7 @@ print("Without the connection:", after)
 source.connectRHS(receiver, weight=weight)
 ```
 
-Try several inputs: a connection's effect can depend on the input. To explore a whole hidden neuron, `n1.detach(neuron)` removes it from its layer and disconnects all its incoming and outgoing edges. Save those weights before detaching if you want to restore it, then add the neuron back to its layer and reconnect its edges. Its bias, activation, and learning rate remain on the object.
+Try several inputs: a connection's effect can depend on the input.
 
 You can also change an existing weight through `receiver.weights[source]`. Use the connection methods to add or remove edges so incoming weights and outgoing connections stay consistent.
 
@@ -139,7 +139,7 @@ pip install .
 
 Open [the nibble challenge notebook](https://github.com/adamjpatterson/neuralplex/blob/main/examples/the_nibble_challenge/main.ipynb). It introduces all sixteen four-bit inputs, constructs a 4 → 8 → 1 network, compares initial and trained predictions, and lets you change an input to inspect weights and activations. With seed 42, a step of 0.01, and 10,000 training examples, the displayed R² rounds to 1.000000000.
 
-Training and evaluation both use all sixteen nibbles.
+Training and evaluation both use all sixteen nibbles; this experiment provides no evidence of generalization. The notebook imports `visualize_network` from [its visualization module](https://github.com/adamjpatterson/neuralplex/blob/main/examples/the_nibble_challenge/visualizations.py).
 
 ##### Visualizations of the network before and after training
 
@@ -149,7 +149,7 @@ Training and evaluation both use all sixteen nibbles.
 - Node area above a small visibility floor is proportional to absolute activation. Green nodes are inputs, red nodes are hidden, and yellow is the output.
 - Both panels use the same input, positions, and scales. Node size represents activity, not importance, and does not encode the activation's sign.
 
-The notebook imports `visualize_network` from [its visualization module](https://github.com/adamjpatterson/neuralplex/blob/main/examples/the_nibble_challenge/visualizations.py).
+This visualization demonstrates that an irregular-looking network can learn a simple mapping almost perfectly: individual connections can reinforce or cancel one another.
 
 ### The digits experiment
 
@@ -179,13 +179,11 @@ The notebook imports `plot_predictions` and `plot_confusion_matrix` from [its vi
 
 The prediction figure shows the first twelve test images. The confusion matrix includes all 450 test images; rows show the true digit and columns show the predicted digit.
 
-![Digits predictions](https://raw.githubusercontent.com/adamjpatterson/neuralplex/main/images/digits_predictions.png)
-
-![Digits confusion matrix](https://raw.githubusercontent.com/adamjpatterson/neuralplex/main/images/digits_confusion_matrix.png)
+![Digits predictions and confusion matrix](https://raw.githubusercontent.com/adamjpatterson/neuralplex/main/images/digits_results.png)
 
 ## Tests
 
-The suite in `tests/test.py` checks forward calculations, manual gradients, parameter updates, detachment and reconnection, and input validation.
+The suite in `tests/test.py` checks forward calculations, manual gradients, parameter updates, connection removal and restoration, and input validation.
 
 #### Run all tests.
 
@@ -203,7 +201,7 @@ The [documentation-image project](https://github.com/adamjpatterson/neuralplex/b
 python generate_images.py
 ```
 
-It writes the nibble network image, digits predictions, and confusion matrix to `images/`.
+It writes the nibble network image and the combined digits predictions and confusion matrix image to `images/`.
 
 ## Support
 

{neuralplex-0.3.2 → neuralplex-0.4.0}/README.md

@@ -6,7 +6,7 @@ A neural network implementation built as an explicit graph of neurons and weight
 
 ## Introduction
 
-**Neural-pleX** represents individual neurons and their connections explicitly, with manual backpropagation. The Neural-pleX API consists of Network, Layer, and Neuron constructors. The networks can be easily [visualized](#visualizations-of-the-network-before-and-after-training) using a visualization library.
+**Neural-pleX** represents individual neurons and their connections explicitly. Backpropagation is done using explicitly computed gradients. The object-oriented API consists of Network, Layer, and Neuron constructors. The networks can be easily [visualized](#visualizations-of-the-network-before-and-after-training) using a visualization library.
 
 ## Table of contents
 
@@ -99,7 +99,7 @@ print("Without the connection:", after)
 source.connectRHS(receiver, weight=weight)
 ```
 
-Try several inputs: a connection's effect can depend on the input. To explore a whole hidden neuron, `n1.detach(neuron)` removes it from its layer and disconnects all its incoming and outgoing edges. Save those weights before detaching if you want to restore it, then add the neuron back to its layer and reconnect its edges. Its bias, activation, and learning rate remain on the object.
+Try several inputs: a connection's effect can depend on the input.
 
 You can also change an existing weight through `receiver.weights[source]`. Use the connection methods to add or remove edges so incoming weights and outgoing connections stay consistent.
 
@@ -125,7 +125,7 @@ pip install .
 
 Open [the nibble challenge notebook](https://github.com/adamjpatterson/neuralplex/blob/main/examples/the_nibble_challenge/main.ipynb). It introduces all sixteen four-bit inputs, constructs a 4 → 8 → 1 network, compares initial and trained predictions, and lets you change an input to inspect weights and activations. With seed 42, a step of 0.01, and 10,000 training examples, the displayed R² rounds to 1.000000000.
 
-Training and evaluation both use all sixteen nibbles.
+Training and evaluation both use all sixteen nibbles; this experiment provides no evidence of generalization. The notebook imports `visualize_network` from [its visualization module](https://github.com/adamjpatterson/neuralplex/blob/main/examples/the_nibble_challenge/visualizations.py).
 
 ##### Visualizations of the network before and after training
 
@@ -135,7 +135,7 @@ Training and evaluation both use all sixteen nibbles.
 - Node area above a small visibility floor is proportional to absolute activation. Green nodes are inputs, red nodes are hidden, and yellow is the output.
 - Both panels use the same input, positions, and scales. Node size represents activity, not importance, and does not encode the activation's sign.
 
-The notebook imports `visualize_network` from [its visualization module](https://github.com/adamjpatterson/neuralplex/blob/main/examples/the_nibble_challenge/visualizations.py).
+This visualization demonstrates that an irregular-looking network can learn a simple mapping almost perfectly: individual connections can reinforce or cancel one another.
 
 ### The digits experiment
 
@@ -165,13 +165,11 @@ The notebook imports `plot_predictions` and `plot_confusion_matrix` from [its vi
 
 The prediction figure shows the first twelve test images. The confusion matrix includes all 450 test images; rows show the true digit and columns show the predicted digit.
 
-![Digits predictions](https://raw.githubusercontent.com/adamjpatterson/neuralplex/main/images/digits_predictions.png)
-
-![Digits confusion matrix](https://raw.githubusercontent.com/adamjpatterson/neuralplex/main/images/digits_confusion_matrix.png)
+![Digits predictions and confusion matrix](https://raw.githubusercontent.com/adamjpatterson/neuralplex/main/images/digits_results.png)
 
 ## Tests
 
-The suite in `tests/test.py` checks forward calculations, manual gradients, parameter updates, detachment and reconnection, and input validation.
+The suite in `tests/test.py` checks forward calculations, manual gradients, parameter updates, connection removal and restoration, and input validation.
 
 #### Run all tests.
 
@@ -189,7 +187,7 @@ The [documentation-image project](https://github.com/adamjpatterson/neuralplex/b
 python generate_images.py
 ```
 
-It writes the nibble network image, digits predictions, and confusion matrix to `images/`.
+It writes the nibble network image and the combined digits predictions and confusion matrix image to `images/`.
 
 ## Support
 

{neuralplex-0.3.2 → neuralplex-0.4.0}/docs/README.md

@@ -1,6 +1,6 @@
 # README image generation
 
-This project generates the repository's three README illustrations.
+This project generates the repository's two README illustrations.
 
 ## Setup and run
 
@@ -26,8 +26,7 @@ The generator uses seed **42** with these settings:
 The script prints the nibble R² and digits accuracy, and overwrites:
 
 - `../images/nibble_multiweight.png`
-- `../images/digits_predictions.png`
-- `../images/digits_confusion_matrix.png`
+- `../images/digits_results.png`
 
 Review the regenerated images and update any reported README results when changing these settings.
 

{neuralplex-0.3.2 → neuralplex-0.4.0}/docs/generate_images.py

@@ -68,14 +68,14 @@ def visualize_network(before, after, inputs):
     return figure
 
 
-def plot_predictions(images, labels, predictions=None, title='Sample digits'):
+def plot_predictions(figure, images, labels, predictions=None, title='Sample digits'):
     """Return a figure of the first twelve supplied images, without selecting successes."""
     count = min(12, len(images))
     if count == 0:
         raise ValueError('Supply at least one image')
     columns = min(4, count)
     rows = (count + columns - 1) // columns
-    figure, axes = plt.subplots(rows, columns, figsize=(2 * columns, 2 * rows), squeeze=False)
+    axes = figure.subplots(rows, columns, squeeze=False)
     for index, axis in enumerate(axes.flat):
         axis.axis('off')
         if index >= len(images):
@@ -86,13 +86,12 @@ def plot_predictions(images, labels, predictions=None, title='Sample digits'):
             label += f'   Predicted: {predictions[index]}'
         axis.set_title(label, fontsize=10)
     figure.suptitle(title)
-    figure.tight_layout()
     return figure
 
 
-def plot_confusion_matrix(matrix):
+def plot_confusion_matrix(figure, matrix):
     """Return a figure; rows are true digits and columns are predicted digits."""
-    figure, axis = plt.subplots(figsize=(7, 6))
+    axis = figure.subplots()
     heatmap = axis.imshow(matrix, cmap='Blues')
     axis.set(xticks=range(10), yticks=range(10), xlabel='Predicted digit',
              ylabel='True digit', title='Neural-pleX: held-out confusion matrix')
@@ -101,7 +100,6 @@ def plot_confusion_matrix(matrix):
             axis.text(column, row, str(matrix[row, column]), ha='center', va='center',
                       color='white' if matrix[row, column] > matrix.max() / 2 else 'black')
     figure.colorbar(heatmap, ax=axis)
-    figure.tight_layout()
     return figure
 
 
@@ -152,14 +150,14 @@ def main():
     accuracy = accuracy_score(truth, predictions)
     matrix = confusion_matrix(truth, predictions, labels=list(range(10)))
     print(f'Digits accuracy: {accuracy:.2%} ({len(train)} train, {len(test)} test)')
-    figure = plot_predictions(digits.images[test[:12]], truth[:12], predictions[:12],
-                              title=f'Neural-pleX: held-out digits (overall accuracy {accuracy:.1%})')
-    figure.savefig(output / 'digits_predictions.png', dpi=150)
+    figure = plt.figure(figsize=(15, 6), layout='constrained')
+    predictions_panel, matrix_panel = figure.subfigures(1, 2, width_ratios=[8, 7])
+    plot_predictions(predictions_panel, digits.images[test[:12]], truth[:12], predictions[:12],
+                     title=f'Neural-pleX: held-out digits (overall accuracy {accuracy:.1%})')
+    plot_confusion_matrix(matrix_panel, matrix)
+    figure.savefig(output / 'digits_results.png', dpi=150)
     plt.close(figure)
-    figure = plot_confusion_matrix(matrix)
-    figure.savefig(output / 'digits_confusion_matrix.png', dpi=150)
-    plt.close(figure)
-    print(f'Wrote three README images to {output}')
+    print(f'Wrote two README images to {output}')
 
 
 if __name__ == '__main__':

neuralplex-0.4.0/src/neuralplex/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{neuralplex-0.3.2 → neuralplex-0.4.0}/src/neuralplex/network.py

@@ -72,17 +72,3 @@ class Network:
                 for source in neuron.weights:
                     neuron.weights[source] -= neuron.step * neuron.delta * source.value
                 neuron.bias -= neuron.step * neuron.delta
-
-    def detach(self, neuron: Neuron) -> None:
-        """Remove a hidden neuron and its edges, between training steps."""
-        if neuron in self.input_layer.neurons or neuron in self.output_layer.neurons:
-            raise ValueError("Input and output neurons cannot be detached")
-        for layer in self.layers[1:-1]:
-            if neuron in layer.neurons:
-                for source in list(neuron.neuronsLHS):
-                    neuron.disconnectLHS(source)
-                for receiver in list(neuron.neuronsRHS):
-                    neuron.disconnectRHS(receiver)
-                layer.neurons.remove(neuron)
-                return
-        raise ValueError("Neuron is not a hidden member of this network")

{neuralplex-0.3.2 → neuralplex-0.4.0}/tests/test.py

@@ -56,38 +56,43 @@ class TestCorrectness(unittest.TestCase):
             model.train([1, 2], [1])
 
 
-    def test_detach_and_reattach(self):
-        inputs = [Neuron(name=f'i{i}') for i in range(3)]
-        hidden, output = Neuron(name='h'), Neuron(name='o')
-        model = Network([Layer(inputs), Layer([hidden], step=0.01), Layer([output], step=0.01)], seed=42)
-        incoming = dict(hidden.weights)
-        outgoing = output.weights[hidden]
-        before = model.predict([1, 2, 3])
-        model.detach(hidden)
+    def test_disconnect_and_reconnect(self):
+        source, hidden, output = Neuron(), Neuron(), Neuron()
+        model = Network([Layer([source]), Layer([hidden], step=0.01),
+                         Layer([output], step=0.01)], seed=42)
+        hidden.weights[source] = 2.0
+        output.weights[hidden] = 3.0
+        before = model.predict([1])
+        self.assertEqual(before, [6.0])
+
+        weight = output.weights[hidden]
+        hidden.disconnectRHS(output)
+        hidden.disconnectRHS(output)  # Removing an absent edge is harmless.
         self.assertEqual(output.weights, {})
-        self.assertEqual(hidden.weights, {})
         self.assertEqual(hidden.neuronsRHS, [])
-        self.assertTrue(all(not n.neuronsRHS for n in inputs))
-        self.assertEqual(model.predict([1, 2, 3]), [0])
-        model.layers[1].neurons.append(hidden)
-        for source, weight in incoming.items():
-            source.connectRHS(hidden, weight)
-        hidden.connectRHS(output, outgoing)
+        self.assertEqual(model.predict([1]), [0.0])
+        hidden.connectRHS(output, weight)
         hidden.connectRHS(output, 999)  # Existing edges keep their weights.
-        self.assertEqual(model.predict([1, 2, 3]), before)
-        self.assertEqual(hidden.weights, incoming)
-        self.assertEqual(output.weights, {hidden: outgoing})
+        self.assertEqual(output.weights, {hidden: weight})
         self.assertEqual(hidden.neuronsRHS, [output])
-        for source in inputs:
-            self.assertEqual(source.neuronsRHS, [hidden])
-        inputs[0].disconnectRHS(hidden)
-        inputs[0].disconnectRHS(hidden)
-        model.train([1, 2, 3], [1])
-        with self.assertRaises(ValueError):
-            model.detach(output)
-        output.connectRHS(inputs[0])
+        self.assertEqual(model.predict([1]), before)
+
+        weight = hidden.weights[source]
+        hidden.disconnectLHS(source)
+        hidden.disconnectLHS(source)
+        self.assertEqual(hidden.weights, {})
+        self.assertEqual(source.neuronsRHS, [])
+        self.assertEqual(model.predict([1]), [0.0])
+        hidden.connectLHS(source, weight)
+        self.assertEqual(hidden.weights, {source: weight})
+        self.assertEqual(source.neuronsRHS, [hidden])
+        self.assertEqual(model.predict([1]), before)
+        model.train([1], [5])
+        self.assertLess(abs(model.predict([1])[0] - 5), abs(before[0] - 5))
+
+        output.connectRHS(source)
         with self.assertRaises(ValueError):
-            model.predict([1, 2, 3])
+            model.predict([1])
 
     def test_invalid_learning_rates(self):
         for step in [0, -0.1, float('nan'), float('inf'), float('-inf')]:

neuralplex-0.3.2/src/neuralplex/__about__.py

@@ -1 +0,0 @@
-__version__ = "0.3.2"