more_math 1.5.0 → 1.6.0

data/lib/more_math/distributions.rb

@@ -3,61 +3,119 @@ require 'more_math/constants/functions_constants'
 
 module MoreMath
   # This class is used to compute the Normal Distribution.
+  #
+  # The normal distribution is a continuous probability distribution that
+  # describes real-valued random variables whose distributions are symmetric
+  # around their mean.
+  #
+  # @example Creating a normal distribution
+  #   # Standard normal (mean=0, std_dev=1)
+  #   norm = MoreMath::NormalDistribution.new
+  #
+  #   # Custom parameters
+  #   custom_norm = MoreMath::NormalDistribution.new(5.0, 2.0)  # mean=5, std_dev=2
+  #
+  # @example Calculating probabilities
+  #   norm = MoreMath::NormalDistribution.new
+  #   p = norm.probability(1.96)     # Cumulative probability at z=1.96
+  #   x = norm.inverse_probability(0.975)  # Inverse: find z such that P(Z <= z) = 0.975
   class NormalDistribution
     include Functions
     include Constants::FunctionsConstants
 
     # Creates a NormalDistribution instance for the values +mu+ and +sigma+.
+    #
+    # @param mu [Numeric] The mean of the distribution (default: 0.0)
+    # @param sigma [Numeric] The standard deviation of the distribution (default: 1.0)
     def initialize(mu = 0.0, sigma = 1.0)
       @mu, @sigma = mu.to_f, sigma.to_f
     end
 
+    # Returns the mean of this normal distribution.
+    #
+    # @return [Float] The mean value
     attr_reader :mu
 
+    # Returns the standard deviation of this normal distribution.
+    #
+    # @return [Float] The standard deviation value
     attr_reader :sigma
 
     # Returns the cumulative probability (p-value) of the NormalDistribution
     # for the value +x+.
+    #
+    # This calculates P(X <= x) where X ~ N(μ, σ²).
+    #
+    # @param x [Numeric] The value at which to calculate the cumulative probability
+    # @return [Float] The cumulative probability P(X <= x)
     def probability(x)
       0.5 * (1 + erf((x - @mu) / (@sigma * ROOT2)))
     end
 
     # Returns the inverse cumulative probability value of the
     # NormalDistribution for the probability +p+.
+    #
+    # This finds the value x such that P(X <= x) = p where X ~ N(μ, σ²).
+    #
+    # @param p [Numeric] The probability (0 < p < 1)
+    # @return [Float] The inverse cumulative probability (quantile)
     def inverse_probability(p)
       case
       when p <= 0
-        -1 / 0.0
+        -1 / 0.0  # Negative infinity
       when p >= 1
-        1 / 0.0
+        1 / 0.0   # Positive infinity
       when (p - 0.5).abs <= Float::EPSILON
-        @mu
+        @mu       # Median equals mean for normal distribution
       else
         begin
           NewtonBisection.new { |x| probability(x) - p }.solve(nil, 1_000_000)
         rescue
-          0 / 0.0
+          0 / 0.0   # NaN on error
         end
       end
     end
   end
 
+  # A predefined instance of the standard normal distribution (mean=0, std_dev=1).
+  #
+  # @return [NormalDistribution] Standard normal distribution instance
   STD_NORMAL_DISTRIBUTION = NormalDistribution.new
 
   # This class is used to compute the Chi-Square Distribution.
+  #
+  # The chi-square distribution is a continuous probability distribution
+  # that arises in the analysis of variance and goodness-of-fit tests.
+  #
+  # @example Creating a chi-square distribution
+  #   chi2 = MoreMath::ChiSquareDistribution.new(5)  # 5 degrees of freedom
+  #
+  # @example Calculating probabilities
+  #   chi2 = MoreMath::ChiSquareDistribution.new(5)
+  #   p = chi2.probability(10.645)  # Probability that X <= 10.645
   class ChiSquareDistribution
     include Functions
 
     # Creates a ChiSquareDistribution for +df+ degrees of freedom.
+    #
+    # @param df [Integer] The degrees of freedom
     def initialize(df)
       @df = df
       @df_half = @df / 2.0
     end
 
+    # Returns the degrees of freedom of this distribution.
+    #
+    # @return [Integer] The degrees of freedom
     attr_reader :df
 
     # Returns the cumulative probability (p-value) of the ChiSquareDistribution
     # for the value +x+.
+    #
+    # This calculates P(X <= x) where X ~ χ²(df).
+    #
+    # @param x [Numeric] The value at which to calculate the cumulative probability
+    # @return [Float] The cumulative probability P(X <= x)
     def probability(x)
       if x < 0
         0.0
@@ -67,7 +125,12 @@ module MoreMath
     end
 
     # Returns the inverse cumulative probability value of the
-    # NormalDistribution for the probability +p+.
+    # ChiSquareDistribution for the probability +p+.
+    #
+    # This finds the value x such that P(X <= x) = p where X ~ χ²(df).
+    #
+    # @param p [Numeric] The probability (0 < p < 1)
+    # @return [Float] The inverse cumulative probability (quantile)
     def inverse_probability(p)
       case
       when p <= 0, p >= 1
@@ -78,26 +141,47 @@ module MoreMath
           range = bisect.bracket 0.5..10
           bisect.solve(range, 1_000_000)
         rescue
-          0 / 0.0
+          0 / 0.0   # NaN on error
         end
       end
     end
   end
 
   # This class is used to compute the T-Distribution.
+  #
+  # The t-distribution (Student's t-distribution) is a probability distribution
+  # that is used when estimating the mean of a normally distributed population
+  # in situations where the sample size is small and the population standard
+  # deviation is unknown.
+  #
+  # @example Creating a t-distribution
+  #   t_dist = MoreMath::TDistribution.new(10)  # 10 degrees of freedom
+  #
+  # @example Calculating probabilities
+  #   t_dist = MoreMath::TDistribution.new(10)
+  #   p = t_dist.probability(2.228)  # Probability that X <= 2.228
   class TDistribution
     include Functions
 
     # Returns a TDistribution instance for the degrees of freedom +df+.
+    #
+    # @param df [Integer] The degrees of freedom
     def initialize(df)
       @df = df
     end
 
     # Degrees of freedom.
+    #
+    # @return [Integer] The degrees of freedom
     attr_reader :df
 
     # Returns the cumulative probability (p-value) of the TDistribution for the
     # t-value +x+.
+    #
+    # This calculates P(X <= x) where X ~ t(df).
+    #
+    # @param x [Numeric] The t-value at which to calculate the cumulative probability
+    # @return [Float] The cumulative probability P(X <= x)
     def probability(x)
       if x == 0
         0.5
@@ -113,19 +197,24 @@ module MoreMath
 
     # Returns the inverse cumulative probability (t-value) of the TDistribution
     # for the probability +p+.
+    #
+    # This finds the value x such that P(X <= x) = p where X ~ t(df).
+    #
+    # @param p [Numeric] The probability (0 < p < 1)
+    # @return [Float] The inverse cumulative probability (quantile)
     def inverse_probability(p)
       case
       when p <= 0
-        -1 / 0.0
+        -1 / 0.0  # Negative infinity
       when p >= 1
-        1 / 0.0
+        1 / 0.0   # Positive infinity
       else
         begin
           bisect = NewtonBisection.new { |x| probability(x) - p }
           range = bisect.bracket(-10..10)
           bisect.solve(range, 1_000_000)
         rescue
-          0 / 0.0
+          0 / 0.0   # NaN on error
         end
       end
     end

data/lib/more_math/entropy.rb

@@ -1,5 +1,41 @@
 module MoreMath
+  # Provides entropy calculation utilities for measuring information content
+  # and randomness in text data.
+  #
+  # This module implements Shannon entropy calculations to quantify the
+  # unpredictability or information content of text strings. It's commonly used
+  # in cryptography, data compression, and information theory applications.
+  #
+  # The entropy measures help determine how "random" or "predictable" a text is,
+  # which can be useful for:
+  # - Password strength analysis
+  # - Data compression efficiency estimation
+  # - Cryptographic security assessment
+  # - Text analysis and classification
+  #
+  # @example Basic usage
+  #   require 'more_math'
+  #   include MoreMath
+  #
+  #   text = "hello world"
+  #   puts entropy(text)        # => 2.3219280948873626
+  #   puts entropy_ratio(text)   # => 0.7428571428571429
+  #
+  # @example Using with different text samples
+  #   MoreMath::Entropy.entropy("aaaa")           # => 0.0 (no entropy)
+  #   MoreMath::Entropy.entropy("abcd")           # => 2.0 (maximum entropy)
   module Entropy
+    # Calculates the Shannon entropy of a text string.
+    #
+    # Shannon entropy measures the average amount of information (in bits) needed
+    # to encode characters in the text based on their frequencies.
+    #
+    # @example
+    #   MoreMath::Entropy.entropy("hello") # => 2.3219280948873626
+    #   MoreMath::Entropy.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 = text.chars
       size  = chars.size
@@ -11,14 +47,50 @@ module MoreMath
         end.abs
     end
 
+    # Calculates the ideal (maximum) entropy for a given character set size.
+    #
+    # This represents the maximum possible entropy when all characters in the
+    # alphabet have equal probability of occurrence.
+    #
+    # @example
+    #   MoreMath::Entropy.entropy_ideal(2)  # => 1.0
+    #   MoreMath::Entropy.entropy_ideal(256) # => 8.0
+    #
+    # @param size [Integer] The number of unique characters in the alphabet
+    # @return [Float] The maximum possible entropy in bits
     def entropy_ideal(size)
       size <= 1 and return 0.0
       frequency = 1.0 / size
       -1.0 * size * frequency * Math.log2(frequency)
     end
 
-    def entropy_ratio(text)
-      size = text.each_char.size
+
+    # Calculates the normalized entropy ratio of a text string.
+    #
+    # The ratio is calculated as actual entropy divided by ideal entropy,
+    # giving a value between 0 and 1 where:
+    # - 0 indicates no entropy (all characters are identical)
+    # - 1 indicates maximum entropy (uniform distribution across the alphabet)
+    #
+    # The normalization uses the specified alphabet size to calculate the
+    # theoretical maximum entropy for that character set.
+    #
+    # @example
+    #   MoreMath::Entropy.entropy_ratio("hello")     # => 0.6834
+    #   MoreMath::Entropy.entropy_ratio("aaaaa")     # => 0.0
+    #   MoreMath::Entropy.entropy_ratio("abcde")     # => 1.0
+    #
+    # @example With custom alphabet size
+    #   # Normalizing against a 26-letter alphabet (English)
+    #   MoreMath::Entropy.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.
+    #   Defaults to the total length of the text (`text.each_char.size`), which
+    #   normalizes the entropy relative to the text's own character space.
+    #   This allows comparison of texts with different lengths on the same scale.
+    # @return [Float] Normalized entropy ratio between 0 and 1
+    def entropy_ratio(text, size: text.each_char.size)
       size <= 1 and return 0.0
       entropy(text) / entropy_ideal(size)
     end

data/lib/more_math/exceptions.rb

@@ -1,6 +1,32 @@
 module MoreMath
+  # Module containing custom exception classes for the MoreMath library
   module Exceptions
+    # Base exception class for all MoreMath exceptions
+    #
+    # All custom exceptions in the MoreMath library inherit from this class
+    #
+    # @example Handling a MoreMath exception
+    #   begin
+    #     # Some MoreMath operation
+    #   rescue MoreMath::Exceptions::MoreMathException => e
+    #     puts "MoreMath error: #{e.message}"
+    #   end
     class MoreMathException < StandardError; end
+
+    # Exception raised when a mathematical computation diverges or fails to converge
+    #
+    # This exception is typically raised when numerical methods fail to produce
+    # meaningful results due to divergence, such as:
+    # - Non-converging series expansions
+    # - Divergent continued fractions
+    # - Failed root finding algorithms
+    #
+    # @example Handling a divergent computation
+    #   begin
+    #     # Some divergent operation
+    #   rescue MoreMath::Exceptions::DivergentException => e
+    #     puts "Computation diverged: #{e.message}"
+    #   end
     class DivergentException < MoreMathException ; end
   end
 end

data/lib/more_math/functions.rb

@@ -1,19 +1,44 @@
 require 'more_math/entropy'
 
 module MoreMath
+  # Provides mathematical functions and special functions for scientific computing.
+  #
+  # This module includes implementations of various mathematical functions commonly
+  # used in statistics, numerical analysis, and scientific computing. It extends
+  # Ruby's built-in Math module with additional functionality and provides
+  # specialized implementations for better accuracy and performance.
+  #
+  # @example Using mathematical functions
+  #   include MoreMath::Functions
+  #
+  #   # Gamma function calculation
+  #   gamma(5)        # => ~ 24.0 (4!)
+  #   gamma(0.5)      # => ~ 1.772 (sqrt(pi))
+  #
+  #   # Beta function calculation
+  #   beta(2, 3)      # => ~ 0.083 (B(2,3) = Gamma(2)*Gamma(3)/Gamma(5))
+  #
+  #   # Error function
+  #   erf(1)          # => ~ 0.843
   module Functions
     module_function
 
     include Math
     extend Math
 
-    # Returns the natural logarithm of Euler gamma function value for +x+ using
-    # the Lanczos approximation.
     if Math.respond_to?(:lgamma)
+      # The log_gamma function extends the factorial to real and complex
+      # numbers. For positive integers, Gamma(n) = (n-1)!.
+      #
+      # @param x [Numeric] The input value for which to calculate log_gamma
+      # @return [Float] Natural logarithm of the gamma function at x
+      # @raise [ZeroDivisionError] When x is zero or a negative integer
       def log_gamma(x)
         lgamma(x).first
       end
     else
+      # Returns the natural logarithm of Euler gamma function value for +x+
+      # using the Lanczos approximation if not provided by Ruby.
       def log_gamma(x)
         x = x.to_f
         if x.nan? || x <= 0
@@ -35,6 +60,13 @@ module MoreMath
     end
 
     # Returns the value of the gamma function, extended to a negative domain.
+    #
+    # The gamma function is defined for all complex numbers except non-positive integers.
+    # For positive real numbers, it extends the factorial: Gamma(n) = (n-1)!
+    #
+    # @param x [Numeric] The input value for which to calculate gamma
+    # @return [Float] The gamma function value at x
+    # @raise [ZeroDivisionError] When x is a non-positive integer
     def gamma(x)
       if x < 0.0
         return PI / (sin(PI * x) * exp(log_gamma(1 - x)))
@@ -44,6 +76,13 @@ module MoreMath
     end
 
     # Returns the natural logarithm of the beta function value for +(a, b)+.
+    #
+    # The beta function is defined as B(a,b) = Gamma(a)*Gamma(b)/Gamma(a+b)
+    # and is commonly used in statistics and probability theory.
+    #
+    # @param a [Numeric] First parameter of the beta function
+    # @param b [Numeric] Second parameter of the beta function
+    # @return [Float] Natural logarithm of the beta function at (a,b)
     def log_beta(a, b)
       log_gamma(a) + log_gamma(b) - log_gamma(a + b)
     rescue Errno::ERANGE, Errno::EDOM
@@ -51,6 +90,13 @@ module MoreMath
     end
 
     # Returns the value of the beta function for +(a, b)+, +a > 0, b > 0'.
+    #
+    # The beta function B(a,b) = Gamma(a)*Gamma(b)/Gamma(a+b) is used in
+    # statistical distributions and probability theory.
+    #
+    # @param a [Numeric] First parameter (must be > 0)
+    # @param b [Numeric] Second parameter (must be > 0)
+    # @return [Float] The beta function value at (a,b)
     def beta(a, b)
       if a > 0 && b > 0
         exp(log_beta(a, b))
@@ -62,6 +108,16 @@ module MoreMath
     # Return an approximation value of Euler's regularized beta function for
     # +x+, +a+, and +b+ with an error <= +epsilon+, but only iterate
     # +max_iterations+-times.
+    #
+    # The regularized incomplete beta function I_x(a,b) = B(x;a,b)/B(a,b)
+    # is used in statistics to compute probabilities for the beta distribution.
+    #
+    # @param x [Numeric] The upper limit of integration (0 <= x <= 1)
+    # @param a [Numeric] First shape parameter (a > 0)
+    # @param b [Numeric] Second shape parameter (b > 0)
+    # @param epsilon [Float] Convergence tolerance (default: 1E-16)
+    # @param max_iterations [Integer] Maximum number of iterations (default: 65536)
+    # @return [Float] Regularized incomplete beta function value
     def beta_regularized(x, a, b, epsilon: 1E-16, max_iterations: 1 << 16)
       x, a, b = x.to_f, a.to_f, b.to_f
       case
@@ -89,6 +145,16 @@ module MoreMath
     # Return an approximation of the regularized gammaP function for +x+ and
     # +a+ with an error of <= +epsilon+, but only iterate
     # +max_iterations+-times.
+    #
+    # The regularized lower incomplete gamma function P(a,x) = γ(a,x)/Γ(a)
+    # where γ(a,x) is the lower incomplete gamma function. This is used in
+    # statistics to compute probabilities for the gamma distribution.
+    #
+    # @param x [Numeric] Upper limit of integration (x >= 0)
+    # @param a [Numeric] Shape parameter (a > 0)
+    # @param epsilon [Float] Convergence tolerance (default: 1E-16)
+    # @param max_iterations [Integer] Maximum number of iterations (default: 65536)
+    # @return [Float] Regularized lower incomplete gamma function value
     def gammaP_regularized(x, a, epsilon: 1E-16, max_iterations: 1 << 16)
       x, a = x.to_f, a.to_f
       case
@@ -120,6 +186,16 @@ module MoreMath
     # Return an approximation of the regularized gammaQ function for +x+ and
     # +a+ with an error of <= +epsilon+, but only iterate
     # +max_iterations+-times.
+    #
+    # The regularized upper incomplete gamma function Q(a,x) = Γ(a,x)/Γ(a)
+    # where Γ(a,x) is the upper incomplete gamma function. This is used in
+    # statistics to compute probabilities for the gamma distribution.
+    #
+    # @param x [Numeric] Upper limit of integration (x >= 0)
+    # @param a [Numeric] Shape parameter (a > 0)
+    # @param epsilon [Float] Convergence tolerance (default: 1E-16)
+    # @param max_iterations [Integer] Maximum number of iterations (default: 65536)
+    # @return [Float] Regularized upper incomplete gamma function value
     def gammaQ_regularized(x, a, epsilon: 1E-16, max_iterations: 1 << 16)
       x, a = x.to_f, a.to_f
       case
@@ -143,7 +219,14 @@ module MoreMath
     end
 
     unless Math.respond_to?(:erf)
-      # Returns an approximate value for the error function's value for +x+.
+      # Returns an approximate value for the error function's value for +x+
+      # unless provided by Ruby.
+      #
+      # The error function erf(x) = (2/sqrt(pi)) * ∫₀ˣ e^(-t²) dt is used in probability,
+      # statistics, and partial differential equations.
+      #
+      # @param x [Numeric] Input value
+      # @return [Float] Error function value at x
       def erf(x)
         erf_a = MoreMath::Constants::FunctionsConstants::ERF_A
         r = sqrt(1 - exp(-x ** 2 * (4 / Math::PI + erf_a * x ** 2) / (1 + erf_a * x ** 2)))
@@ -152,11 +235,27 @@ module MoreMath
     end
 
     unless Math.respond_to?(:erfc)
+      # Returns the complementary error function value for +x+ unless provided
+      # by Ruby.
+      #
+      # The complementary error function erfc(x) = 1 - erf(x) is used in probability
+      # and statistics when computing tail probabilities.
+      #
+      # @param x [Numeric] Input value
+      # @return [Float] Complementary error function value at x
       def erfc(x)
         1.0 - erf(x)
       end
     end
 
+    # Computes the ceiling of the base +b+ logarithm of +n+.
+    #
+    # Returns the smallest integer k such that b^k >= n.
+    #
+    # @param n [Integer] The number to compute log for (must be > 0)
+    # @param b [Integer] The base of the logarithm (must be > 1)
+    # @return [Integer] Ceiling of log_b(n)
+    # @raise [ArgumentError] If n <= 0 or b <= 1
     def log_ceil(n, b = 2)
       raise ArgumentError, "n is required to be > 0" unless n > 0
       raise ArgumentError, "b is required to be > 1" unless b > 1
@@ -168,6 +267,14 @@ module MoreMath
       result
     end
 
+    # Computes the floor of the base +b+ logarithm of +n+.
+    #
+    # Returns the largest integer k such that b^k <= n.
+    #
+    # @param n [Integer] The number to compute log for (must be > 0)
+    # @param b [Integer] The base of the logarithm (must be > 1)
+    # @return [Integer] Floor of log_b(n)
+    # @raise [ArgumentError] If n <= 0 or b <= 1
     def log_floor(n, b = 2)
       raise ArgumentError, "n is required to be > 0" unless n > 0
       raise ArgumentError, "b is required to be > 1" unless b > 1
@@ -179,35 +286,64 @@ module MoreMath
       result
     end
 
-    # Returns the base +b+ logarithm of the number +x+. +b+  defaults to base
+    # Returns the base +b+ logarithm of the number +x+. +b+ defaults to base
     # 2, binary logarithm.
+    #
+    # @param x [Numeric] The number to compute log for (must be > 0)
+    # @param b [Numeric] The base of the logarithm (default: 2)
+    # @return [Float] Logarithm of x in base b
     def logb(x, b = 2)
       Math.log(x) / Math.log(b)
     end
 
     # Returns Cantor's tuple function for the tuple +*xs+ (the size must be at
     # least 2).
+    #
+    # The Cantor pairing function uniquely encodes pairs of natural numbers
+    # into a single natural number. This implementation extends it to tuples.
+    #
+    # @param xs [Array<Integer>] Array of integers to encode
+    # @return [Integer] Unique natural number representing the tuple
     def cantor_pairing(*xs)
       CantorPairingFunction.cantor_pairing(*xs)
     end
 
     # Returns the inverse of Cantor's tuple function for the value +c+. +n+ is
     # the length of the tuple (defaults to 2, a pair).
+    #
+    # Decodes a natural number back into its original tuple representation.
+    #
+    # @param c [Integer] The encoded natural number
+    # @param n [Integer] Length of the original tuple (default: 2)
+    # @return [Array<Integer>] Original tuple as array of integers
     def cantor_pairing_inv(c, n = 2)
       CantorPairingFunction.cantor_pairing_inv(c, n)
     end
 
     # Computes a Gödel number from +string+ in the +alphabet+ and returns it.
+    #
+    # Implements Gödel numbering to convert strings into unique natural numbers.
+    #
+    # @param string [String] The input string
+    # @param alphabet [Array<String>, Range<String>] The alphabet to use for conversion
+    # @return [Integer] Unique Gödel number representing the string
     def numberify_string(string, alphabet = 'a'..'z')
       NumberifyStringFunction.numberify_string(string, alphabet)
     end
 
     # Computes the string in the +alphabet+ from a Gödel number +number+ and
     # returns it. This is the inverse function of numberify_string.
+    #
+    # Converts a natural number back to its original string representation.
+    #
+    # @param number [Integer] The Gödel number to convert
+    # @param alphabet [Array<String>, Range<String>] The alphabet to use for conversion
+    # @return [String] Original string represented by the number
     def stringify_number(number, alphabet = 'a'..'z')
       NumberifyStringFunction.stringify_number(number, alphabet)
     end
 
+    # Includes entropy calculations functionality
     include Entropy
   end
 end