neuronet 7.0.230416 → 8.0.251113

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ae4f34320ea739510cafcdf20b058723dadcb9ac4fde8313529c91c444a5ec1
-  data.tar.gz: a1b493bcc891960a96d279203fa8c50959135832cb19946ed0f21150b984a4e1
+  metadata.gz: 34f23ce75292128094b31f4eac5245ac41a7b3cf42026aa4bbb2ce74e19fd255
+  data.tar.gz: ec4105888e4bc67361a9f4d1bde5edbfe94f7363bbe1233e39fc29fc3c2e6de7
 SHA512:
-  metadata.gz: 7a9b58b4f67ebdd293af8753a80ad6f94963a9d97f20996a6e225bb34ee79344f6766ed4fac7520ad57742f818083b0879a6d7a54fab0ba878d7a3838abc513c
-  data.tar.gz: f19e93126a1f485189d6d4ca1599617aebd10582eaa5757ffb5a446a39eba0389692fea85b8b9305fdb997788bed7421252b078d7ac06fa305f3568ab400b8fb
+  metadata.gz: 5222bf678484647b6911c489d304206ed3730438b7810a0a19e08a633a2e422e0afb2ff7cbb84272ffc7080136d361dd1d1ee9cdd3424b21aea6b274bd6f306c
+  data.tar.gz: 4082141fd54fedf66e3449334b5546abe0b78ee6306eee2e3acd15864ff93b446af8f0a0ed520d27e98c991f7bd3a62222b00b652d0289616ea5ea2c167eb5c7

data/CREDITS.md

@@ -0,0 +1,10 @@
+# Credits
+
+We want to credit where credit is due.
+This project owes thanks to the authors of this repository (see their commits),
+the third-party libraries we rely on (check the dependencies),
+and the diffuse pool of ideas and inspirations that shaped it.
+
+We welcome contributions to this list!
+If you feel someone or something is missing,
+please submit a pull request with the suggested addition.

data/README.md

@@ -1,118 +1,77 @@
 # Neuronet
 
-* [VERSION 7.0.230416](https://github.com/carlosjhr64/neuronet/releases)
-* [github](https://github.com/carlosjhr64/neuronet)
-* [rubygems](https://rubygems.org/gems/neuronet)
+* [VERSION 8.0.251113](https://github.com/carlosjhr64/neuronet/releases)
+* [github](https://www.github.com/carlosjhr64/neuronet)
+* [rubygems](https://rubygems.org/neuronet)
 
-## DESCRIPTION:
+## DESCRIPTION
 
 Library to create neural networks.
 
-This is primarily a math project meant to be used to investigate the behavior of
-different small neural networks.
+Features perceptron, MLP, and deep feed forward networks.
+Uses a logistic squash function.
 
-## INSTALL:
+## INSTALL
 ```console
-gem install neuronet
+$ gem install neuronet
 ```
-## SYNOPSIS:
+* Required Ruby version: `>= 3.4`
 
-The library is meant to be read, but here is a motivating example:
+## SYNOPSIS
+
+The library is meant to be read, but here are some quick bits:
 ```ruby
 require 'neuronet'
-include Neuronet
 
-ff = FeedForward.new([3,3])
+# Perceptron
 # It can mirror, equivalent to "copy":
-ff.last.mirror
-values = ff * [-1, 0, 1]
-values.map { '%.13g' % _1 } #=> ["-1", "0", "1"]
+np = Neuronet::Perceptron.new(3, 3)
+np.output_layer.mirror
+values = np * [-1, 0, 1] #=> [-1.0, 0.0, 1.0]
 # It can anti-mirror, equivalent to "not":
-ff.last.mirror(-1)
-values = ff * [-1, 0, 1]
-values.map { '%.13g' % _1 } #=> ["1", "0", "-1"]
-
-# It can "and";
-ff = FeedForward.new([2,2,1])
-ff[1].mirror(-1)
-ff.last.connect(ff.first)
-ff.last.average
-# Training "and" pairs:
+np.output_layer.mirror(-1)
+values = np * [-1, 0, 1] #=> [1.0, 0.0, -1.0]
+
+# MPL: Multi-Layer(3) Perceptron
+# It can "and".
+# In this example, NoisyMiddleNeuron is needed to differentiate the neurons:
+mlp = Neuronet::MLP.new(2, 4, 1,
+                        middle_neuron: Neuronet::NoisyMiddleNeuron)
 pairs = [
   [[1, 1], [1]],
   [[-1, 1], [-1]],
   [[1, -1], [-1]],
   [[-1, -1], [-1]],
 ]
-# Train until values match:
-ff.pairs(pairs) do
-  pairs.any? { |input, target| (ff * input).map { _1.round(1) } != target }
+while pairs.any? { |input, target| (mlp * input).map(&:round) != target }
+  mlp.pairs(pairs) # Training...
 end
-(ff * [-1, -1]).map{ _1.round } #=> [-1]
-(ff * [-1,  1]).map{ _1.round } #=> [-1]
-(ff * [ 1, -1]).map{ _1.round } #=> [-1]
-(ff * [ 1,  1]).map{ _1.round } #=> [1]
-
-# It can "or";
-ff = FeedForward.new([2,2,1])
-ff[1].mirror(-1)
-ff.last.connect(ff.first)
-ff.last.average
-# Training "or" pairs:
-pairs = [
-  [[1, 1], [1]],
-  [[-1, 1], [1]],
-  [[1, -1], [1]],
-  [[-1, -1], [-1]],
-]
-# Train until values match:
-ff.pairs(pairs) do
-  pairs.any? { |input, target| (ff * input).map { _1.round(1) } != target }
-end
-(ff * [-1, -1]).map{ _1.round } #=> [-1]
-(ff * [-1,  1]).map{ _1.round } #=> [1]
-(ff * [ 1, -1]).map{ _1.round } #=> [1]
-(ff * [ 1,  1]).map{ _1.round } #=> [1]
+(mlp * [1, 1]).map(&:round)   #=> [1]
+(mlp * [-1, 1]).map(&:round)  #=> [-1]
+(mlp * [1, -1]).map(&:round)  #=> [-1]
+(mlp * [-1, -1]).map(&:round) #=> [-1]
+
+# To export to a file:
+#     mlp.export_to_file(filename)
+# To import from a file:
+#     mlp.import_from_file(filename)
+# These will export/import the network's biases and weights.
 ```
-## CONTENTS:
-
-* [Neuronet wiki](https://github.com/carlosjhr64/neuronet/wiki)
+## HELP
 
-### Mju
+When reading the library, this is order the order I would read it:
 
-Mju is a Marklar which value depends on which Marklar is asked.
-Other known Marklars are Mu and Kappa.
-Hope it's not confusing...
-I tried to give related Marklars the same name.
-![Marklar](img/marklar.png)
-
-### Marshal
-
-Marshal works with Neuronet to save your networks:
-```ruby
-dump = Marshal.dump ff
-ff2 = Marshal.load dump
-ff2.inspect == ff.inspect #=> true
-```
-### Base
-
-* [Requires and autoloads](lib/neuronet.rb)
-* [Constants and lambdas](lib/neuronet/constants.rb)
-* [Connection](lib/neuronet/connection.rb)
 * [Neuron](lib/neuronet/neuron.rb)
 * [Layer](lib/neuronet/layer.rb)
-* [FeedForward](lib/neuronet/feed_forward.rb)
-
-### Scaled
+* [Feed Forward](lib/neuronet/feed_forward.rb)
 
-* [Scale](lib/neuronet/scale.rb)
-* [Gaussian](lib/neuronet/gaussian.rb)
-* [LogNormal](lib/neuronet/log_normal.rb)
-* [ScaledNetwork](lib/neuronet/scaled_network.rb)
+Once you understand these files, the rest should all make sense.
+For some math on neural networks,
+see the [Wiki](https://github.com/carlosjhr64/neuronet/wiki).
 
-## LICENSE:
+## LICENSE
 
-Copyright (c) 2023 CarlosJHR64
+Copyright (c) 2025 CarlosJHR64
 
 Permission is hereby granted, free of charge,
 to any person obtaining a copy of this software and
@@ -135,3 +94,5 @@ 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.
+
+## [CREDITS](CREDITS.md)

data/lib/neuronet/arrayable.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Neuronet
+  # Arrayable avoids explicit `to_a` calls for common Array methods.
+  module Arrayable
+    def each(&blk) = to_a.each { blk[it] }
+    def each_with_index(&blk) = to_a.each_with_index { |n, i| blk[n, i] }
+    def [](index) = to_a[index]
+    def map(&) = to_a.map(&)
+    def size = to_a.size
+    def reverse = to_a.reverse
+  end
+end

data/lib/neuronet/backpropagate.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Neuronet
+  # Backpropagate provides simple, clamp-limited weight/bias updates.
+  module Backpropagate
+    # Back-propagates errors, updating bias and connection weights.
+    # Clamps updates to [-max, +max].
+    # Recursively calls on connected neurons.
+    # rubocop: disable Metrics, Style
+    def backpropagate(error)
+      bmax = Config.bias_clamp
+      b = bias + error
+      self.bias = b.abs > bmax ? (b.positive? ? bmax : -bmax) : b
+
+      wmax = Config.weight_clamp
+      connections.each do |c|
+        n = c.neuron
+        w = c.weight + (n.activation * error)
+        c.weight = w.abs > wmax ? (w.positive? ? wmax : -wmax) : w
+        n.backpropagate(error)
+      end
+    end
+    # rubocop: enable Metrics, Style
+  end
+end

data/lib/neuronet/config.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Neuronet
+  # Maximum values for biases and weights
+  module Config
+    class << self; attr_accessor :bias_clamp, :weight_clamp; end
+    self.bias_clamp   = 18.0
+    self.weight_clamp = 9.0
+  end
+end

data/lib/neuronet/connection.rb

@@ -1,65 +1,9 @@
 # frozen_string_literal: true
 
-# Neuronet module / Connection class
 module Neuronet
-  # Connections between neurons are there own separate objects. In Neuronet, a
-  # neuron contains it's bias, and a list of it's connections. Each connection
-  # contains it's weight (strength) and connected neuron.
-  class Connection
-    attr_accessor :neuron, :weight
-
-    # Connection#initialize takes a neuron and a weight with a default of 0.0.
-    def initialize(neuron = Neuron.new, weight: 0.0)
-      @neuron = neuron
-      @weight = weight
-    end
-
-    # The connection's mu is the activation of the connected neuron.
-    def mu = @neuron.activation
-    alias activation mu
-
-    # The connection's mju is 𝑾𝓑𝒂'.
-    def mju = @weight * @neuron.derivative
-
-    # The connection kappa is a component of the neuron's sum kappa:
-    #   𝜿 := 𝑾 𝝀'
-    def kappa = @weight * @neuron.lamda
-
-    # The weighted activation of the connected neuron.
-    def weighted_activation = @neuron.activation * @weight
-
-    # Consistent with #update
-    alias partial weighted_activation
-
-    # Connection#update returns the updated activation of a connection, which is
-    # the weighted updated activation of the neuron it's connected to:
-    #   weight * neuron.update
-    # This method is the one to use whenever the value of the inputs are changed
-    # (or right after training).  Otherwise, both update and value should give
-    # the same result.  When back calculation are not needed, use
-    # Connection#weighted_activation instead.
-    def update = @neuron.update * @weight
-
-    # Connection#backpropagate modifies the connection's weight in proportion to
-    # the error given and passes that error to its connected neuron via the
-    # neuron's backpropagate method.
-    def backpropagate(error)
-      @weight += @neuron.activation * Neuronet.noise[error]
-      if @weight.abs > Neuronet.maxw
-        @weight = @weight.positive? ? Neuronet.maxw : -Neuronet.maxw
-      end
-      @neuron.backpropagate(error)
-      self
-    end
-    # On how to reduce the error, the above makes it obvious how to interpret
-    # the equipartition of errors among the connections.  Backpropagation is
-    # symmetric to forward propagation of errors. The error variable is the
-    # reduced error, 𝛆(see the wiki notes).
-
-    # A connection inspects itself as "weight*label:...".
-    def inspect = "#{Neuronet.format % @weight}*#{@neuron.inspect}"
-
-    # A connection puts itself as "weight*label".
-    def to_s = "#{Neuronet.format % @weight}*#{@neuron}"
+  # Connection is a lightweight struct for weighted neuron links.
+  Connection = Struct.new('Connection', :neuron, :weight) do
+    # Weighted activation value
+    def value = neuron.activation * weight
   end
 end

data/lib/neuronet/deep.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Neuronet
+  # Feed Forward
+  class Deep
+    include NetworkStats
+    include Exportable
+    include Trainable
+    include Arrayable
+
+    # rubocop: disable Metrics
+    def initialize(*sizes, input_neuron: InputNeuron,
+                   middle_neuron: MiddleNeuron,
+                   output_neuron: OutputNeuron)
+      length = sizes.length
+      raise 'Need at least 3 layers' if length < 3
+
+      @input_layer = InputLayer.new(sizes.shift, input_neuron:)
+      @output_layer = OutputLayer.new(sizes.pop, output_neuron:)
+      @hidden_layers = sizes.map { MiddleLayer.new(it, middle_neuron:) }
+      previous = @input_layer
+      @hidden_layers.each do |layer|
+        layer.connect(previous)
+        previous = layer
+      end
+      @output_layer.connect(previous)
+    end
+    # rubocop: enable Metrics
+
+    attr_reader :input_layer, :hidden_layers, :output_layer
+
+    def set(values)
+      @input_layer.set(values)
+    end
+
+    def update
+      @hidden_layers.each(&:update)
+    end
+
+    def values
+      @output_layer.values
+    end
+
+    def *(other)
+      set(other)
+      update
+      values
+    end
+
+    def to_a = [@input_layer, *@hidden_layers, @output_layer]
+  end
+end

data/lib/neuronet/exportable.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Neuronet
+  # Exportable serializes network biases and weights only.
+  # Human-readable, compact, excludes activations.
+  module Exportable
+    # Writes serialized network to writer(from self).
+    # rubocop: disable Metrics
+    def export(writer)
+      sizes = map(&:size)
+      writer.puts "# #{self.class}"
+      # The first "float" here is the number of layers in the FFN...
+      # Just to be consistent:
+      writer.puts "#{sizes.size.to_f} #{sizes.join(' ')}"
+      each_with_index do |layer, i|
+        next if i.zero? # skip input layer
+
+        layer.each_with_index do |neuron, j|
+          writer.puts "# neuron = FFN[#{i}, #{j}]"
+          writer.puts "#{neuron.bias} #{i} #{j}"
+          neuron.connections.each_with_index do |connection, k|
+            writer.puts "#{connection.weight} #{i} #{j} #{k}"
+          end
+        end
+      end
+    end
+    # rubocop: enable Metrics
+
+    def export_to_file(filename) = File.open(filename, 'w') { export it }
+    def import_from_file(filename) = File.open(filename, 'r') { import it }
+
+    # Reads and validates serialized network from reader to set self.
+    # rubocop: disable Metrics
+    def import(reader)
+      gets_data = lambda do |reader|
+        return nil unless (line = reader.gets)
+
+        line = reader.gets while line.start_with?('#')
+        fs, *is = line.strip.split
+        [fs.to_f, *is.map(&:to_i)]
+      end
+
+      size, *sizes = gets_data[reader]
+      raise 'Size/Sizes mismatch' unless size == sizes.size
+      raise 'Sizes mismatch' unless sizes == map(&:size)
+
+      each_with_index do |layer, i|
+        next if i.zero? # skip input layer
+
+        layer.each_with_index do |neuron, j|
+          bias, *indeces = gets_data[reader]
+          raise "bad bias index: #{indeces}" unless indeces == [i, j]
+
+          neuron.bias = bias
+          neuron.connections.each_with_index do |connection, k|
+            weight, *indeces = gets_data[reader]
+            raise "bad weight index: #{indeces}" unless indeces == [i, j, k]
+
+            connection.weight = weight
+          end
+        end
+      end
+      raise 'Expected end of file.' unless gets_data[reader].nil?
+    end
+    # rubocop: enable Metrics
+  end
+end

data/lib/neuronet/feed_forward.rb

@@ -1,89 +1,54 @@
 # frozen_string_literal: true
 
-# Neuronet module / FeedForward class
 module Neuronet
-  # A Feed Forward Network
-  class FeedForward < Array
+  # FeedForward is a fully connected neural network with >= 3 layers.
+  class FeedForward
+    # [NetwordStats](network_stats.rb)
+    include NetworkStats
+    # [Exportable](exportable.rb)
+    include Exportable
+    # [Trainable](trainable.rb)
+    include Trainable
+    # [Arrayble](arrayable.rb)
+    include Arrayable
+
     # Example:
-    #   ff = Neuronet::FeedForward.new([2, 3, 1])
-    def initialize(layers)
-      length = layers.length
-      raise 'Need at least 2 layers' if length < 2
+    #     ff = Neuronet::FeedForward.new(4, 8, 4)
+    def initialize(*sizes, full_neuron: Neuron)
+      length = sizes.length
+      raise 'Need at least 3 layers' if length < 3
 
-      super(length) { Layer.new(layers[_1]) }
-      1.upto(length - 1) { self[_1].connect(self[_1 - 1]) }
+      @layers = Array.new(length) { Layer.new(sizes[it], full_neuron:) }
+      1.upto(length - 1) { @layers[it].connect(@layers[it - 1]) }
+      @input_layer = @layers[0]
+      @output_layer = @layers[-1]
+      @hidden_layers = @layers[1...-1]
     end
 
-    # Set the input layer.
-    def set(input)
-      first.set(input)
-      self
-    end
+    attr_reader :input_layer, :hidden_layers, :output_layer
 
-    def input = first.values
+    # Sets the input values
+    def set(values)
+      @input_layer.set(values)
+    end
 
-    # Update the network.
+    # Updates hidden layers (input assumed set).
     def update
-      # update up the layers
-      1.upto(length - 1) { self[_1].partial }
-      self
+      @hidden_layers.each(&:update)
     end
 
-    def output = last.values
+    # Gets output
+    def values
+      @output_layer.values
+    end
 
-    # Consider:
-    #   m = Neuronet::FeedForward.new(layers)
-    # Want:
-    #   output = m * input
+    # Forward pass: set input, update, return output.
     def *(other)
       set(other)
       update
-      last.values
-    end
-
-    # 𝝁 + 𝜧 𝝁' + 𝜧 𝜧'𝝁" + 𝜧 𝜧'𝜧"𝝁"' + ...
-    # |𝜧| ~ |𝑾||𝓑𝒂|
-    # |∑𝑾| ~ √𝑁
-    # |𝓑𝒂| ~ ¼
-    # |𝝁| ~ 1+∑|𝒂'| ~ 1+½𝑁
-    def expected_mju!
-      sum = 0.0
-      mju = 1.0
-      reverse[1..].each do |layer|
-        n = layer.length
-        sum += mju * (1.0 + (0.5 * n))
-        mju *= 0.25 * Math.sqrt(layer.length)
-      end
-      @expected_mju = Neuronet.learning * sum
-    end
-
-    def expected_mju
-      @expected_mju || expected_mju!
-    end
-
-    def average_mju
-      last.average_mju
-    end
-
-    def train(target, mju = expected_mju)
-      last.train(target, mju)
-      self
-    end
-
-    def pair(input, target, mju = expected_mju)
-      set(input).update.train(target, mju)
+      values
     end
 
-    def pairs(pairs, mju = expected_mju)
-      pairs.shuffle.each { |input, target| pair(input, target, mju) }
-      return self unless block_given?
-
-      pairs.shuffle.each { |i, t| pair(i, t, mju) } while yield
-      self
-    end
-
-    def inspect = map(&:inspect).join("\n")
-
-    def to_s = map(&:to_s).join("\n")
+    def to_a = @layers
   end
 end

data/lib/neuronet/input_layer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Neuronet
+  # Input Layer
+  class InputLayer
+    include Arrayable
+
+    def initialize(length, input_neuron: InputNeuron)
+      @layer = Array.new(length) { input_neuron.new }
+      @endex = length - 1
+    end
+
+    def set(values)
+      0.upto(@endex) { @layer[it].set values[it] }
+    end
+
+    def to_a = @layer
+  end
+end

data/lib/neuronet/input_neuron.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Neuronet
+  # Input Neuron
+  class InputNeuron
+    include NeuronStats
+    include Squash
+
+    EMPTY = [].freeze
+
+    def initialize
+      @activation = 0.5
+    end
+
+    attr_reader :activation
+
+    def bias = nil
+    def connections = EMPTY
+    def value = nil
+
+    def set(value)
+      @activation = squash(value)
+    end
+
+    def backpropagate(_) = nil
+  end
+end