more_math 1.10.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b375aa122041b022a2c6b6457cbd6ba9a87691e75a816696c004b57824a5c50e
-  data.tar.gz: ea3ae210dc593238418ea80b9d8c86b156b7fd53be2971349cbda9985e59aee1
+  metadata.gz: 9cec08e9525ca81297ec96ef655884adc76c51dd751aa77f3c2d9092796853b9
+  data.tar.gz: cbdd8862d8150d5bcc8f00d9aa6c2f0629601aa83a5ec992876facd6c9d208c3
 SHA512:
-  metadata.gz: e28aaa3aaf79ab42eac1fbf4c4a678d7676279ebf326fed10e8c094d0040ad1d664b8a5e9b137a68c25077496886036c67fc377cfb0e1f4027d2c3abaf2ccbc8
-  data.tar.gz: 8f8f81bd9beb6c9b7f040d58ac6a90acb3fe4a9394896cd4822c148f7ee362e9c0ee5004785953a9f292b7fac2cf23177676cd46ed17f344e19337399b473cd8
+  metadata.gz: a55392037367f21c5af96ce557f85470ee9a75a58047580f944c5822af87240c754be75fe8d4a9fd93c070c1c01a793fbbb161b57889e92b9d7f9bad7e3e07cf
+  data.tar.gz: 6349577e9373872abdb696cf8abe2b2f0bf8ed0c7f318bb5fc103256f0d6042744aae2fb04ab91233a090ff2112dee8cb96c89cb0786ae95e68bf2c506f1aeb7

data/CHANGES.md

@@ -1,5 +1,25 @@
 # Changes
 
+## 2026-01-22 v1.11.0
+
+- Added new entropy helper methods: `entropy_probabilities`,
+  `entropy_per_symbol`, `minimum_entropy_per_symbol`,
+  `collision_entropy_per_symbol`, `entropy_total`, `minimum_entropy_total`, and
+  `collision_entropy_total` to `lib/more_math/entropy.rb`
+- Replaced the old `entropy` method with an alias to `entropy_per_symbol`
+- Updated documentation for `entropy_ratio` to clarify the `size:` keyword
+  argument
+- Removed the `entropy_ratio_minimum` method and its corresponding test cases
+  from the codebase
+- Enhanced test coverage in `tests/entropy_test.rb` with new unit tests for the
+  added helper methods
+    - Updated existing test assertions to use `assert_in_delta` for floating-point
+      comparisons
+    - Added descriptive comments to the test `setup` method
+    - Ensured all new methods return correct values for empty, uniform, and
+      varied symbol strings
+- Corrected example values in `entropy_ratio` documentation
+
 ## 2026-01-19 v1.10.0
 
 - Added new `entropy_maximum` method to calculate theoretical maximum entropy

data/lib/more_math/entropy.rb

@@ -25,31 +25,128 @@ module MoreMath
   #   entropy("aaaa")           # => 0.0 (no entropy)
   #   entropy("abcd")           # => 2.0 (actual entropy)
   module Entropy
-    # Calculates the Shannon entropy in bits of a text string.
+    # Calculates the probability distribution of symbols in the given input.
+    #
+    # This method computes the frequency of each symbol in the input and
+    # converts these frequencies into probabilities by dividing by the total
+    # number of symbols.
+    #
+    # @param symbols [String, Array<String>] The sequence of symbols to
+    #   calculate probabilities for
+    # @return [Hash<String, Float>] A hash mapping each symbol to its
+    #   probability value
+    def entropy_probabilities(symbols)
+      symbols = symbols.chars if symbols.respond_to?(:chars)
+
+      freq  = symbols.tally
+      total = symbols.size
+
+      freq.transform_values { |c| c.to_f / total }
+    end
+
+    # Calculates the Shannon entropy per symbol in the given symbols.
     #
-    # Shannon entropy measures the average amount of information (in bits) needed
-    # to encode characters in the text based on their frequencies.
+    # This method computes the entropy of a sequence of symbols, measuring the
+    # average information content or unpredictability of the symbols.
     #
-    # @example
-    #   entropy("hello") # => 2.3219280948873626
-    #   entropy("aaaa")  # => 0.0
-    #
-    # @param text [String] The input text to calculate entropy for
-    # @return [Float] The Shannon entropy in bits
-    def entropy(text)
-      chars = nil
-      if text.respond_to?(:chars)
-        chars = text.chars
-      else
-        chars = text
-      end
-      size  = chars.size
-
-      chars.each_with_object(Hash.new(0.0)) { |c, h| h[c] += 1 }.
-        each_value.reduce(0.0) do |entropy, count|
-          frequency = count / size
-          entropy + frequency * Math.log2(frequency)
-        end.abs
+    # @param symbols [String, Array<String>] The sequence of symbols to calculate entropy for
+    # @return [Float] The entropy value in bits per symbol
+    def entropy_per_symbol(symbols)
+      symbols = symbols.chars if symbols.respond_to?(:chars)
+
+      symbols.empty? and return 0.0
+
+      probs = entropy_probabilities(symbols)
+
+      -probs.values.sum { |p| p * Math.log2(p) }
+    end
+    alias entropy entropy_per_symbol
+
+    # Calculates the minimum entropy per symbol in the given symbols.
+    #
+    # This method determines the minimum possible entropy for a sequence of
+    # symbols, which represents the entropy when all symbols are equally
+    # likely.
+    #
+    # @param symbols [String, Array<String>] The sequence of symbols to
+    #   calculate minimum entropy for
+    # @return [Float] The minimum entropy value in bits per symbol
+    def minimum_entropy_per_symbol(symbols)
+      symbols = symbols.chars if symbols.respond_to?(:chars)
+
+      symbols.empty? and return 0.0
+
+      probs = entropy_probabilities(symbols)
+
+      -Math.log2(probs.values.max)
+    end
+
+    # Calculates the collision entropy per symbol in the given symbols.
+    #
+    # This method computes the collision entropy, which measures the
+    # unpredictability of the most likely outcome in a symbol sequence. It's
+    # based on the sum of squared probabilities of each symbol.
+    #
+    # @param symbols [String, Array<String>] The sequence of symbols to
+    #   calculate collision entropy for
+    # @return [Float] The collision entropy value in bits per symbol
+    def collision_entropy_per_symbol(symbols)
+      symbols = symbols.chars if symbols.respond_to?(:chars)
+
+      symbols.empty? and return 0.0
+
+      probs = entropy_probabilities(symbols)
+
+      -Math.log2(probs.values.sum { |p| p * p })
+    end
+
+    # Calculates the total entropy for a sequence of symbols.
+    #
+    # This method computes the total information content of a symbol sequence
+    # by multiplying the entropy per symbol by the total number of symbols.
+    #
+    # @param symbols [String, Array<String>] The sequence of symbols to
+    #   calculate total entropy for
+    # @return [Float] The total entropy value in bits for the entire symbol
+    #   sequence
+    def entropy_total(symbols)
+      symbols = symbols.chars if symbols.respond_to?(:chars)
+
+      entropy_per_symbol(symbols) * symbols.size
+    end
+
+    # Calculates the total minimum entropy for a sequence of symbols.
+    #
+    # This method computes the total information content of a symbol sequence
+    # using the minimum entropy per symbol, multiplied by the total number of
+    # symbols. It represents the theoretical minimum possible entropy for the
+    # given sequence.
+    #
+    # @param symbols [String, Array<String>] The sequence of symbols to
+    #   calculate total minimum entropy for
+    # @return [Float] The total minimum entropy value in bits for the entire
+    #   symbol sequence
+    def minimum_entropy_total(symbols)
+      symbols = symbols.chars if symbols.respond_to?(:chars)
+
+      minimum_entropy_per_symbol(symbols) * symbols.size
+    end
+
+    # Calculates the total collision entropy for a sequence of symbols.
+    #
+    # This method computes the total information content of a symbol sequence
+    # using the collision entropy per symbol, multiplied by the total number of
+    # symbols. Collision entropy measures the unpredictability of the most
+    # likely outcome in a symbol sequence.
+    #
+    # @param symbols [String, Array<String>] The sequence of symbols to
+    #   calculate total collision entropy for
+    # @return [Float] The total collision entropy value in bits for the entire
+    #   symbol sequence
+    def collision_entropy_total(symbols)
+      symbols = symbols.chars if symbols.respond_to?(:chars)
+
+      collision_entropy_per_symbol(symbols) * symbols.size
     end
 
     # Calculates the ideal (maximum) entropy for a given character set size.
@@ -80,54 +177,21 @@ module MoreMath
     # theoretical maximum entropy for that character set.
     #
     # @example
-    #   entropy_ratio("hello")     # => 0.6834
-    #   entropy_ratio("aaaaa")     # => 0.0
-    #   entropy_ratio("abcde")     # => 1.0
+    #   entropy_ratio("hello", size: 26) # => 0.4088
+    #   entropy_ratio("aaaaa", size: 26) # => 0.0
+    #   entropy_ratio("abcde", size: 5)  # => 1.0
+    #   entropy_ratio("abcde", size: 26) # => 0.4939
     #
-    # @example With custom alphabet size
-    #   # Normalizing against a 26-letter alphabet (English)
-    #   entropy_ratio("hello", size: 26) # => 0.394...
     #
     # @param text [String] The input text to calculate entropy ratio for
-    # @param size [Integer] The size of the character set to normalize against (alphabet size).
+    # @param size [Integer] The size of the character set to normalize against
+    #   (alphabet size).
     # @return [Float] Normalized entropy ratio between 0 and 1
     def entropy_ratio(text, size:)
       size <= 1 and return 0.0
       entropy(text) / entropy_ideal(size)
     end
 
-    # Calculates the minimum entropy ratio with confidence interval adjustment
-    #
-    # This method computes a adjusted entropy ratio that accounts for
-    # statistical uncertainty by incorporating the standard error and a
-    # confidence level.
-    #
-    # @param text [String] The input text to calculate entropy ratio for
-    # @param size [Integer] The size of the character set to normalize against
-    #   (alphabet size).
-    # @param alpha [Float] The significance level for the confidence interval (default: 0.05)
-    # @return [Float] The adjusted entropy ratio within the confidence interval
-    # @raise [ArgumentError] When alphabet size is less than 2
-    # @raise [ArgumentError] When text is empty
-    def entropy_ratio_minimum(text, size:, alpha: 0.05)
-      raise ArgumentError, 'alphabet size must be ≥ 2' if size < 2
-      raise ArgumentError, 'text must not be empty'    if text.empty?
-
-      n = text.size
-      k = size
-
-      ratio = MoreMath::Functions.entropy_ratio(text, size: k)
-
-      logk = Math.log2(k)
-      diff = logk - 1.0 / Math.log(2)
-      var  = (diff ** 2) / (logk ** 2) * (1.0 - 1.0 / k) / n
-      se   = Math.sqrt(var)          # standard error
-
-      z = STD_NORMAL_DISTRIBUTION.inverse_probability(1.0 - alpha / 2.0)
-
-      (ratio - z * se).clamp(0, 1)
-    end
-
     # Calculates the maximum possible entropy for a given text and alphabet
     # size.
     #

data/lib/more_math/version.rb

@@ -1,6 +1,6 @@
 module MoreMath
   # MoreMath version
-  VERSION         = '1.10.0'
+  VERSION         = '1.11.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/more_math.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: more_math 1.10.0 ruby lib
+# stub: more_math 1.11.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "more_math".freeze
-  s.version = "1.10.0".freeze
+  s.version = "1.11.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]

data/tests/entropy_test.rb

@@ -6,6 +6,12 @@ require 'tins'
 class EntropyTest < Test::Unit::TestCase
   include MoreMath::Functions
 
+  # The setup method initializes instance variables with various string values.
+  #
+  # This method prepares the object with predefined string constants for
+  # testing and demonstration purposes. It sets up empty strings, strings of
+  # specific lengths, and strings containing various character sets
+  # including ASCII, Unicode, and Japanese characters.
   def setup
     @empty  = ''
     @low    = ?A * 42
@@ -16,27 +22,27 @@ class EntropyTest < Test::Unit::TestCase
   end
 
   def test_entropy
-    assert_equal 0, entropy(@empty)
-    assert_equal 0, entropy(@low)
-    assert_in_delta 3.951, entropy(@string), 1E-3
-    assert_in_delta 4.431, entropy(@high), 1E-3
-    assert_in_delta 3.700, entropy(@random), 1E-3
-    assert_in_delta 2.807, entropy(@hi), 1E-3
+    assert_in_delta 0.0, entropy(@empty), 1e-12
+    assert_in_delta 0.0, entropy(@low),    1e-12
+    assert_in_delta 3.951, entropy(@string), 1e-3
+    assert_in_delta 4.431, entropy(@high),   1e-3
+    assert_in_delta 3.700, entropy(@random), 1e-3
+    assert_in_delta 2.807, entropy(@hi),     1e-3
   end
 
   def test_entropy_ideal
-    assert_equal 0, entropy_ideal(-1)
-    assert_equal 0, entropy_ideal(0)
-    assert_equal 0, entropy_ideal(0.5)
-    assert_equal 0, entropy_ideal(1)
-    assert_in_delta 1,     entropy_ideal(2), 1E-3
-    assert_in_delta 1.584, entropy_ideal(3), 1E-3
-    assert_in_delta 3,     entropy_ideal(8), 1E-3
-    assert_in_delta 3.321, entropy_ideal(10), 1E-3
-    assert_in_delta 4,     entropy_ideal(16), 1E-3
+    assert_in_delta 0.0, entropy_ideal(-1), 1e-12
+    assert_in_delta 0.0, entropy_ideal(0),  1e-12
+    assert_in_delta 0.0, entropy_ideal(0.5), 1e-12
+    assert_in_delta 0.0, entropy_ideal(1),  1e-12
+    assert_in_delta 1.0,   entropy_ideal(2), 1e-3
+    assert_in_delta 1.584, entropy_ideal(3), 1e-3
+    assert_in_delta 3.0,   entropy_ideal(8), 1e-3
+    assert_in_delta 3.321, entropy_ideal(10), 1e-3
+    assert_in_delta 4.0,   entropy_ideal(16), 1e-3
   end
 
-  def test_entropy_mamxium
+  def test_entropy_maximum
     text = 'A' * 64
     assert_equal 0, entropy_maximum(text, size: -1)
     assert_equal 0, entropy_maximum(text, size: 0)
@@ -47,34 +53,75 @@ class EntropyTest < Test::Unit::TestCase
   end
 
   def test_entropy_ratio
-    assert_equal 0,        entropy_ratio(@empty, size: 128)
-    assert_equal 0,        entropy_ratio(@low, size: 128)
-    assert_in_delta 0.564, entropy_ratio(@string, size: 128), 1E-3
-    assert_in_delta 0.633, entropy_ratio(@high, size: 128), 1E-3
-    assert_in_delta 1.0,   entropy_ratio(@random, size: @random.size), 1E-3
-    assert_in_delta 0.462, entropy_ratio(@random, size: 256), 1E-3
-    assert_in_delta 0.253, entropy_ratio(@hi, size: 2_136), 1E-3
+    assert_in_delta 0.0, entropy_ratio(@empty, size: 128), 1e-12
+    assert_in_delta 0.0, entropy_ratio(@low, size: 128), 1e-12
+    assert_in_delta 0.564, entropy_ratio(@string, size: 128), 1e-3
+    assert_in_delta 0.633, entropy_ratio(@high, size: 128), 1e-3
+    assert_in_delta 1.0,   entropy_ratio(@random, size: @random.size), 1e-3
+    assert_in_delta 0.462, entropy_ratio(@random, size: 256), 1e-3
+    assert_in_delta 0.253, entropy_ratio(@hi, size: 2_136), 1e-3
   end
 
-  def test_entropy_ratio_minimum_basic
-    # A fairly long random token over a 16‑symbol alphabet
-    token = Tins::Token.new(length: 128, alphabet: Tins::Token::BASE16_LOWERCASE_ALPHABET)
+  def test_entropy_probabilities
+    probs = entropy_probabilities('ABAB')
+    assert_equal 0.5, probs['A']
+    assert_equal 0.5, probs['B']
 
-    limit = entropy_ratio_minimum(token, size: 16)
+    probs = entropy_probabilities('AAAA')
+    assert_equal 1.0, probs['A']
 
-    # Bounds must be ≧ 0
-    assert_operator limit, :>=, 0.0
+    probs = entropy_probabilities([])
+    assert_equal({}, probs)
 
-    # The observed ratio should be ≧ limit
-    ratio = entropy_ratio(token, size: 16)
-    assert_operator ratio, :>=, limit
+    # Ensure the method accepts an Array of symbols
+    probs = entropy_probabilities(['x', 'y', 'x'])
+    assert_equal 2.0 / 3.0, probs['x']
+    assert_equal 1.0 / 3.0, probs['y']
   end
 
-  def test_entropy_ratio_minimum_small
-    # Very short string – the interval will stay below 1.0
-    str = 'a'          # alphabet size 2 (binary)
-    limit = entropy_ratio_minimum(str, size: 2)
+  def test_minimum_entropy_per_symbol
+    # Uniform distribution → entropy equals log2(size)
+    assert_in_delta 2.0, minimum_entropy_per_symbol('ABCD'), 1e-12
 
-    assert_equal 0.0, limit
+    # Single symbol → 0
+    assert_in_delta 0.0, minimum_entropy_per_symbol('AAAA'), 1e-12
+
+    # Empty string → 0
+    assert_in_delta 0.0, minimum_entropy_per_symbol(''), 1e-12
+  end
+
+  def test_collision_entropy_per_symbol
+    # For a uniform distribution, collision entropy = log2(size)
+    assert_in_delta 2.0, collision_entropy_per_symbol('ABCD'), 1e-12
+
+    # All symbols the same → 0
+    assert_in_delta 0.0, collision_entropy_per_symbol('AAAA'), 1e-12
+
+    # Empty string → 0
+    assert_in_delta 0.0, collision_entropy_per_symbol(''), 1e-12
+  end
+
+  def test_entropy_total
+    text = 'ABCD'
+    per = entropy_per_symbol(text)
+    assert_in_delta per * text.size, entropy_total(text), 1e-12
+
+    assert_in_delta 0.0, entropy_total(''), 1e-12
+  end
+
+  def test_minimum_entropy_total
+    text = 'ABCD'
+    per = minimum_entropy_per_symbol(text)
+    assert_in_delta per * text.size, minimum_entropy_total(text), 1e-12
+
+    assert_in_delta 0.0, minimum_entropy_total(''), 1e-12
+  end
+
+  def test_collision_entropy_total
+    text = 'ABCD'
+    per = collision_entropy_per_symbol(text)
+    assert_in_delta per * text.size, collision_entropy_total(text), 1e-12
+
+    assert_in_delta 0.0, collision_entropy_total(''), 1e-12
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: more_math
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.11.0
 platform: ruby
 authors:
 - Florian Frank