neuralplex 0.3.0__tar.gz → 0.3.1__tar.gz

{neuralplex-0.3.0 → neuralplex-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: neuralplex
-Version: 0.3.0
+Version: 0.3.1
 Summary: An object oriented neural network implementation.
 Project-URL: Homepage, https://github.com/adamjpatterson/neuralplex
 Project-URL: Issues, https://github.com/adamjpatterson/neuralplex/issues
@@ -36,13 +36,23 @@ An object oriented educational/experimental neural network implementation.
 
 ## Installation
 
+To use the published package:
+
+```bash
+python -m pip install neuralplex
+```
+
+To explore the notebooks or modify the package, clone the repository and install
+the checkout:
+
 ```bash
 git clone https://github.com/adamjpatterson/neuralplex.git
 cd neuralplex
 python -m pip install -e .
 ```
 
-Install from this checkout to use the implementation documented below.
+Follow each example’s setup instructions below to install its notebook and
+visualization dependencies.
 
 ## How it works
 
@@ -58,6 +68,12 @@ from neuralplex import Network, Layer, Neuron
 
 #### Set a step.
 
+`step` is the learning rate: it controls the size of weight and bias updates.
+Each update subtracts `step` times the corresponding gradient.
+`Layer(step=...)` supplies an initial default only to neurons whose `step` is
+`None`. Changing `layer.step` later does not change the neurons; update each
+`neuron.step` directly to change its learning rate.
+
 ```python
 STEP = 0.01
 ```
@@ -97,9 +113,11 @@ hidden layers. Linear layers are sufficient for the nibble conversion task.
 
 `train` minimizes half the sum of squared output errors. It runs the forward
 pass, accumulates gradients backward through every connection, and only then
-updates weights and biases. A weight's gradient is `delta * source.value`;
+updates weights and biases. `delta` is the derivative of the loss with respect
+to the neuron's weighted sum plus bias, before activation.
+A weight's gradient is `delta * source.value`;
 the bias gradient is `delta`. The code uses explicit loops, not automatic
-differentiation. Every non-input neuron needs a positive step.
+differentiation. Every non-input neuron needs a finite, positive `step` for training.
 
 `Neuron(bias=...)` sets the bias. Each incoming connection has its own weight,
 stored in `receiver.weights[source]`. `Network(..., seed=42)` initializes
@@ -110,6 +128,11 @@ weights. Visualization modules read connections directly from
 
 ### Detach and reconnect between training steps
 
+You can change an existing connection weight through `receiver.weights[source]`.
+To add or remove connections, use `connectRHS`/`connectLHS` and
+`disconnectRHS`/`disconnectLHS` rather than inserting or deleting dictionary
+entries. These methods keep incoming weights and outgoing connections consistent.
+
 ```python
 hidden = n1.layers[1].neurons[0]
 incoming = dict(hidden.weights)
@@ -126,9 +149,9 @@ for target, weight in outgoing.items():
 
 The neuron's bias, activation, and learning rate remain on the object. For one
 edge, use `source.disconnectRHS(target)` and `source.connectRHS(target, weight)`.
-Removing an edge does not cascade. A computational node without inputs uses
-its bias; an empty hidden layer left by detachment is allowed. Connections must
-run from earlier to later layers; input/output neurons cannot be detached.
+Removing an edge does not cascade. A non-input neuron without incoming
+connections outputs `activation(bias)`; an empty hidden layer left by detachment
+is allowed. Connections must run from earlier to later layers; input/output neurons cannot be detached.
 Change structure only between training steps, not concurrently with training.
 
 ## Examples

{neuralplex-0.3.0 → neuralplex-0.3.1}/README.md

@@ -22,13 +22,23 @@ An object oriented educational/experimental neural network implementation.
 
 ## Installation
 
+To use the published package:
+
+```bash
+python -m pip install neuralplex
+```
+
+To explore the notebooks or modify the package, clone the repository and install
+the checkout:
+
 ```bash
 git clone https://github.com/adamjpatterson/neuralplex.git
 cd neuralplex
 python -m pip install -e .
 ```
 
-Install from this checkout to use the implementation documented below.
+Follow each example’s setup instructions below to install its notebook and
+visualization dependencies.
 
 ## How it works
 
@@ -44,6 +54,12 @@ from neuralplex import Network, Layer, Neuron
 
 #### Set a step.
 
+`step` is the learning rate: it controls the size of weight and bias updates.
+Each update subtracts `step` times the corresponding gradient.
+`Layer(step=...)` supplies an initial default only to neurons whose `step` is
+`None`. Changing `layer.step` later does not change the neurons; update each
+`neuron.step` directly to change its learning rate.
+
 ```python
 STEP = 0.01
 ```
@@ -83,9 +99,11 @@ hidden layers. Linear layers are sufficient for the nibble conversion task.
 
 `train` minimizes half the sum of squared output errors. It runs the forward
 pass, accumulates gradients backward through every connection, and only then
-updates weights and biases. A weight's gradient is `delta * source.value`;
+updates weights and biases. `delta` is the derivative of the loss with respect
+to the neuron's weighted sum plus bias, before activation.
+A weight's gradient is `delta * source.value`;
 the bias gradient is `delta`. The code uses explicit loops, not automatic
-differentiation. Every non-input neuron needs a positive step.
+differentiation. Every non-input neuron needs a finite, positive `step` for training.
 
 `Neuron(bias=...)` sets the bias. Each incoming connection has its own weight,
 stored in `receiver.weights[source]`. `Network(..., seed=42)` initializes
@@ -96,6 +114,11 @@ weights. Visualization modules read connections directly from
 
 ### Detach and reconnect between training steps
 
+You can change an existing connection weight through `receiver.weights[source]`.
+To add or remove connections, use `connectRHS`/`connectLHS` and
+`disconnectRHS`/`disconnectLHS` rather than inserting or deleting dictionary
+entries. These methods keep incoming weights and outgoing connections consistent.
+
 ```python
 hidden = n1.layers[1].neurons[0]
 incoming = dict(hidden.weights)
@@ -112,9 +135,9 @@ for target, weight in outgoing.items():
 
 The neuron's bias, activation, and learning rate remain on the object. For one
 edge, use `source.disconnectRHS(target)` and `source.connectRHS(target, weight)`.
-Removing an edge does not cascade. A computational node without inputs uses
-its bias; an empty hidden layer left by detachment is allowed. Connections must
-run from earlier to later layers; input/output neurons cannot be detached.
+Removing an edge does not cascade. A non-input neuron without incoming
+connections outputs `activation(bias)`; an empty hidden layer left by detachment
+is allowed. Connections must run from earlier to later layers; input/output neurons cannot be detached.
 Change structure only between training steps, not concurrently with training.
 
 ## Examples

neuralplex-0.3.1/src/neuralplex/__about__.py

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

{neuralplex-0.3.0 → neuralplex-0.3.1}/src/neuralplex/layer.py

@@ -1,3 +1,4 @@
+from math import isfinite
 from typing import Self
 from random import Random
 
@@ -6,8 +7,8 @@ from neuralplex.neuron import Neuron
 
 class Layer:
     def __init__(self, neurons: list[Neuron], step: float | None = None):
-        if step is not None and step <= 0:
-            raise ValueError("step must be positive")
+        if step is not None and (not isfinite(step) or step <= 0):
+            raise ValueError("step must be finite and positive")
         self.neurons = neurons
         self.step = step
         for neuron in neurons:

{neuralplex-0.3.0 → neuralplex-0.3.1}/src/neuralplex/network.py

@@ -1,3 +1,4 @@
+from math import isfinite
 from random import Random
 
 from neuralplex.layer import Layer
@@ -48,8 +49,8 @@ class Network:
             raise ValueError("Supply one target value per output neuron")
         for layer in self.layers[1:]:
             for neuron in layer.neurons:
-                if neuron.step is None or neuron.step <= 0:
-                    raise ValueError("Every computational neuron needs a positive step")
+                if neuron.step is None or not isfinite(neuron.step) or neuron.step <= 0:
+                    raise ValueError("Every computational neuron needs a finite, positive step")
         self.predict(X_train)
 
         # Clear all gradients, including those accumulated at input neurons.

{neuralplex-0.3.0 → neuralplex-0.3.1}/src/neuralplex/neuron.py

@@ -1,4 +1,4 @@
-from math import tanh
+from math import isfinite, tanh
 from random import uniform
 from typing import Self
 
@@ -10,8 +10,8 @@ class Neuron:
                  name=None, activation: str = "linear"):
         if activation not in ("linear", "tanh"):
             raise ValueError("activation must be 'linear' or 'tanh'")
-        if step is not None and step <= 0:
-            raise ValueError("step must be positive")
+        if step is not None and (not isfinite(step) or step <= 0):
+            raise ValueError("step must be finite and positive")
         self.bias = bias
         self.step = step
         self.name = name

{neuralplex-0.3.0 → neuralplex-0.3.1}/tests/test.py

@@ -89,6 +89,22 @@ class TestCorrectness(unittest.TestCase):
         with self.assertRaises(ValueError):
             model.predict([1, 2, 3])
 
+    def test_invalid_learning_rates(self):
+        for step in [0, -0.1, float('nan'), float('inf'), float('-inf')]:
+            with self.subTest(step=step):
+                with self.assertRaises(ValueError):
+                    Neuron(step=step)
+                with self.assertRaises(ValueError):
+                    Layer([Neuron()], step=step)
+
+                model = Network([Layer([Neuron()]), Layer([Neuron()], step=0.1)], seed=42)
+                output = model.output_layer.neurons[0]
+                before = (dict(output.weights), output.bias)
+                output.step = step  # Manual changes must also be checked before training.
+                with self.assertRaises(ValueError):
+                    model.train([1], [1])
+                self.assertEqual((output.weights, output.bias), before)
+
     def test_missing_step_and_external_connections(self):
         a, b, outside = Neuron(), Neuron(), Neuron()
         model = Network([Layer([a]), Layer([b])])

neuralplex-0.3.0/src/neuralplex/__about__.py

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