dicey 0.16.2 → 0.17.0

data/lib/dicey/{sum_frequency_calculators/kronecker_substitution.rb → distribution_calculators/polynomial_convolution.rb}

@@ -3,17 +3,24 @@
 require_relative "base_calculator"
 
 module Dicey
-  module SumFrequencyCalculators
-    # Calculator for lists of dice with integer sides (fast).
+  module DistributionCalculators
+    # Calculator for lists of dice with integer sides (fast),
+    # using polynomial convolution.
     #
     # Example dice: (1,2,3,4), (0,1,-5,6), (5,4,5,4,5).
     #
-    # Based on Kronecker substitution method for polynomial multiplication.
+    # Discrete random variables can be represented as polynomials,
+    # while probability mass function of a sum of independent random variables
+    # is a convolution of their probability mass functions,
+    # which corresponds to multiplication of polynomials.
+    #
+    # Uses Kronecker substitution method for polynomial multiplication.
+    # @see https://en.wikipedia.org/wiki/Convolution#Discrete_convolution
     # @see https://en.wikipedia.org/wiki/Kronecker_substitution
     # @see https://arxiv.org/pdf/0712.4046v1.pdf
     #   David Harvey, Faster polynomial multiplication via multi-point Kronecker substitution
     #   (in particular section 3)
-    class KroneckerSubstitution < BaseCalculator
+    class PolynomialConvolution < BaseCalculator
       private
 
       def validate(dice)
@@ -21,7 +28,7 @@ module Dicey
       end
 
       def calculate_heuristic(dice_count, sides_count)
-        (dice_count**3.2) * 100 * (sides_count**1.9)
+        (2 * dice_count**3 - 4_250_000) + (26 * sides_count**2 + 230_000)
       end
 
       def calculate(dice, **nil)
@@ -32,9 +39,9 @@ module Dicey
         extract_coefficients(product, evaluation_point, offset, polynomials.count)
       end
 
-      # Turn dice into hashes where keys are side values and values are numbers of those sides,
+      # Turn dice into hashes where keys are side values and values are counts of those sides,
       # representing corresponding polynomials where
-      # side values are powers and numbers are coefficients.
+      # side values are powers and counts are coefficients.
       #
       # @param dice [Enumerable<NumericDie>]
       # @return [Array<Hash{Integer => Integer}>]
@@ -56,7 +63,7 @@ module Dicey
         1 << coefficient_magnitude
       end
 
-      # Get values of polynomials if +evaluation_point+ is substituted for the variable.
+      # Calculate values of polynomials at +evaluation_point+.
       #
       # @param polynomials [Array<Hash{Integer => Integer}>]
       # @param evaluation_point [Integer]

data/lib/dicey/distribution_calculators/trivial.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "base_calculator"
+
+require_relative "../mixins/vectorize_dice"
+
+module Dicey
+  module DistributionCalculators
+    # Distribution calculator with fast paths for some trivial cases (very fast).
+    #
+    # Currently included cases:
+    # - single {AbstractDie}, even without +VectorNumber+ (categorical distribution),
+    # - two of the same {RegularDie} (simple multinomial distribution).
+    #
+    # You probably shouldn't use this one manually, it's mostly there for {AutoSelector}.
+    class Trivial < BaseCalculator
+      include Mixins::VectorizeDice
+
+      private
+
+      def validate(dice)
+        dice.size == 1 || two_regular_dice?(dice)
+      end
+
+      def two_regular_dice?(dice)
+        dice.size == 2 && RegularDie === dice.first && dice.first == dice.last
+      end
+
+      def calculate_heuristic(_dice_count, sides_count)
+        -5_000_000 + (328 * sides_count - 89800)
+      end
+
+      def calculate(dice, **nil)
+        die = dice.first
+        if dice.size == 1
+          categorical(die)
+        else
+          bimultinomial(die)
+        end
+      end
+
+      def categorical(die)
+        die = vectorize_dice(die)
+        die.sides_list.tally
+      end
+
+      # Simplest multinomial distribution: two regular dice.
+      def bimultinomial(die)
+        middle = die.sides_num
+        (1...(die.sides_num * 2)).each_with_object({}) do |i, hash|
+          hash[i + 1] = middle - (middle - i).abs
+        end
+      end
+    end
+  end
+end

data/lib/dicey/distribution_properties_calculator.rb

@@ -11,8 +11,11 @@ module Dicey
   # - mode(s), median, arithmetic mean;
   # - important moments (expected value, variance, skewness, kurtosis).
   #
-  # It is notable that most dice create symmetric distributions,
-  # which means that skewness is 0, while properties denoting center in some way
+  # Distributions are assumed to be complete populations,
+  # i.e. this class is unsuitable for samples.
+  #
+  # It is notable that common dice create symmetric distributions,
+  # which means that skewness is 0, while measures of central tendency
   # (median, mean, ...) are all equal.
   # Mode is often not unique, but includes this center.
   class DistributionPropertiesCalculator

data/lib/dicey/mixins/missing_math.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Dicey
+  module Mixins
+    # @api private
+    # Some math functions missing from Math, though without argument range checks.
+    module MissingMath
+      module_function
+
+      # Calculate number of combinations of +n+ elements taken +k+ at a time.
+      #
+      # Unlike plain binomial coefficients, combinations are defined as 0 for +k > n+.
+      #
+      # @param n [Integer] natural integer
+      # @param k [Integer] natural integer
+      # @return [Integer]
+      def combinations(n, k) # rubocop:disable Naming/MethodParameterName
+        return 0 if k > n
+        return 1 if k.zero? || k == n
+
+        factorial_quo(n, k) / factorial(n - k)
+      end
+
+      # Calculate factorial of a natural number.
+      #
+      # @param n [Integer] natural integer
+      # @return [Integer]
+      def factorial(n) # rubocop:disable Naming/MethodParameterName
+        (n < 23) ? Math.gamma(n + 1).to_i : (1..n).reduce(:*)
+      end
+
+      # Calculate +n! / k!+ where +n >= k+.
+      #
+      # @param n [Integer] natural integer
+      # @param k [Integer] natural integer
+      # @return [Integer]
+      def factorial_quo(n, k) # rubocop:disable Naming/MethodParameterName
+        return Math.gamma(n + 1).to_i / Math.gamma(k + 1).to_i if n < 23 && k < 23
+
+        ((k + 1)..n).reduce(:*)
+      end
+    end
+  end
+end

data/lib/dicey/mixins/rational_to_integer.rb

@@ -4,6 +4,7 @@ module Dicey
   # @api private
   # Various mixins with shared methods.
   module Mixins
+    # @api private
     # Mix-in for converting rationals with denominator of 1 to integers.
     module RationalToInteger
       private

data/lib/dicey/mixins/vectorize_dice.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Dicey
-  # @api private
   module Mixins
+    # @api private
     # Mix-in for converting dice with non-numeric sides into dice with +VectorNumber+ sides.
     module VectorizeDice
       private
@@ -10,20 +10,25 @@ module Dicey
       # Vectorize non-numeric sides for AbstractDie instances,
       # leaving NumericDie instances unchanged.
       #
-      # Check for VectorNumber availability *before* calling.
+      # If +VectorNumber+ is not available, returns the original dice.
       #
-      # @param dice [Array<AbstractDie>]
-      # @return [Array<AbstractDie>] a new array of dice
+      # @param dice [Array<AbstractDie>, AbstractDie]
+      # @return [Array<AbstractDie>, AbstractDie] dice with vectorized sides
       def vectorize_dice(dice)
-        dice.map do |die|
-          next die if NumericDie === die
+        return dice unless defined?(VectorNumber)
+        return vectorize_die_sides(dice) if AbstractDie === dice
 
-          sides =
-            die.sides_list.map do |side|
-              (Numeric === side || VectorNumber === side) ? side : VectorNumber.new([side])
-            end
-          die.class.new(sides)
-        end
+        dice.map { vectorize_die_sides(_1) }
+      end
+
+      def vectorize_die_sides(die)
+        return die if NumericDie === die
+
+        die.class.new(
+          die.sides_list.map do |side|
+            (Numeric === side || VectorNumber === side) ? side : VectorNumber.new([side])
+          end
+        )
       end
     end
   end

data/lib/dicey/mixins/warn_about_vector_number.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Dicey
+  module Mixins
+    # @api private
+    # Mix-in for warning about missing VectorNumber gem.
+    module WarnAboutVectorNumber
+      private
+
+      def warn_about_vector_number
+        warn <<~TEXT
+          Dice with non-numeric sides need gem "vector_number" to be present and available.
+          If this is intended, please install the gem.
+        TEXT
+        false
+      end
+    end
+  end
+end

data/lib/dicey/numeric_die.rb

@@ -7,7 +7,7 @@ module Dicey
   #
   # The only inherent difference in behavior compared to {AbstractDie} is
   # that this class checks values for sides on initialization.
-  # However, other classes may reject {AbstractDie} even with all numeric sides.
+  # {AbstractDie} may be rejected where only numeric dice are expected.
   class NumericDie < AbstractDie
     # @param sides_list [Array<Numeric>, Range<Numeric>, Enumerable<Numeric>]
     # @raise [DiceyError] if +sides_list+ contains non-numerical values or is empty

data/lib/dicey/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dicey
-  VERSION = "0.16.2"
+  VERSION = "0.17.0"
 end

data/lib/dicey.rb

@@ -7,13 +7,34 @@ rescue LoadError
   # VectorNumber not available, sad
 end
 
-# A library for rolling dice and calculating roll frequencies.
+# A library for calculating roll distributions and rolling dice.
+#
+# Includes several classes of dice:
+# - {AbstractDie}, the base and most generic class;
+# - {NumericDie}, a subclass for strictly numeric dice;
+# - {RegularDie}, for the most common dice.
+#
+# See {AbstractDie} for API and more information.
+#
+# Roll distributions can be calculated via one of several algorithms
+# in {DistributionCalculators},
+# with automatic selection available via {DistributionCalculators::AutoSelector}.
+#
+# There are also a couple of utility classes:
+# - {DistributionPropertiesCalculator} for analyzing a distribution;
+# - {DieFoundry} for creating dice from strings.
 module Dicey
   # General error for Dicey.
   class DiceyError < StandardError; end
 
-  Dir["dicey/mixins/*.rb", base: __dir__].each { require_relative _1 }
-  Dir["dicey/*.rb", base: __dir__].each { require_relative _1 }
-  Dir["dicey/output_formatters/*.rb", base: __dir__].each { require_relative _1 }
-  Dir["dicey/sum_frequency_calculators/*.rb", base: __dir__].each { require_relative _1 }
+  require_relative "dicey/abstract_die"
+  require_relative "dicey/numeric_die"
+  require_relative "dicey/regular_die"
+
+  require_relative "dicey/die_foundry"
+
+  require_relative "dicey/distribution_properties_calculator"
+  Dir["dicey/distribution_calculators/*.rb", base: __dir__].each { require_relative _1 }
+
+  require_relative "dicey/version"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dicey
 version: !ruby/object:Gem::Version
-  version: 0.16.2
+  version: 0.17.0
 platform: ruby
 authors:
-- Alexandr Bulancov
+- Alexander Bulancov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-10 00:00:00.000000000 Z
+date: 2025-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: vector_number
@@ -26,8 +26,8 @@ dependencies:
         version: 0.4.3
 description: |
   Dicey provides a CLI executable and a Ruby API for fast calculation of
-  frequency/probability distributions of dice rolls,
-  with support for all kinds of numeric dice, even Complex ones!
+  distribution of weights or probabilities of dice rolls,
+  with support for all kinds of numeric dice, and non-numeric ones too!
   Results can be exported as JSON, YAML or a gnuplot data file.
 
   It can also be used to roll dice. While not the primary focus,
@@ -46,30 +46,35 @@ files:
 - exe/dicey-to-gnuplot
 - lib/dicey.rb
 - lib/dicey/abstract_die.rb
+- lib/dicey/cli.rb
 - lib/dicey/cli/blender.rb
+- lib/dicey/cli/calculator_runner.rb
+- lib/dicey/cli/calculator_test_runner.rb
+- lib/dicey/cli/formatters/base_list_formatter.rb
+- lib/dicey/cli/formatters/base_map_formatter.rb
+- lib/dicey/cli/formatters/gnuplot_formatter.rb
+- lib/dicey/cli/formatters/json_formatter.rb
+- lib/dicey/cli/formatters/list_formatter.rb
+- lib/dicey/cli/formatters/null_formatter.rb
+- lib/dicey/cli/formatters/yaml_formatter.rb
 - lib/dicey/cli/options.rb
+- lib/dicey/cli/roller.rb
 - lib/dicey/die_foundry.rb
+- lib/dicey/distribution_calculators/auto_selector.rb
+- lib/dicey/distribution_calculators/base_calculator.rb
+- lib/dicey/distribution_calculators/binomial.rb
+- lib/dicey/distribution_calculators/empirical.rb
+- lib/dicey/distribution_calculators/iterative.rb
+- lib/dicey/distribution_calculators/multinomial_coefficients.rb
+- lib/dicey/distribution_calculators/polynomial_convolution.rb
+- lib/dicey/distribution_calculators/trivial.rb
 - lib/dicey/distribution_properties_calculator.rb
+- lib/dicey/mixins/missing_math.rb
 - lib/dicey/mixins/rational_to_integer.rb
 - lib/dicey/mixins/vectorize_dice.rb
+- lib/dicey/mixins/warn_about_vector_number.rb
 - lib/dicey/numeric_die.rb
-- lib/dicey/output_formatters/gnuplot_formatter.rb
-- lib/dicey/output_formatters/hash_formatter.rb
-- lib/dicey/output_formatters/json_formatter.rb
-- lib/dicey/output_formatters/key_value_formatter.rb
-- lib/dicey/output_formatters/list_formatter.rb
-- lib/dicey/output_formatters/null_formatter.rb
-- lib/dicey/output_formatters/yaml_formatter.rb
 - lib/dicey/regular_die.rb
-- lib/dicey/roller.rb
-- lib/dicey/sum_frequency_calculators/auto_selector.rb
-- lib/dicey/sum_frequency_calculators/base_calculator.rb
-- lib/dicey/sum_frequency_calculators/brute_force.rb
-- lib/dicey/sum_frequency_calculators/empirical.rb
-- lib/dicey/sum_frequency_calculators/kronecker_substitution.rb
-- lib/dicey/sum_frequency_calculators/multinomial_coefficients.rb
-- lib/dicey/sum_frequency_calculators/runner.rb
-- lib/dicey/sum_frequency_calculators/test_runner.rb
 - lib/dicey/version.rb
 homepage: https://github.com/trinistr/dicey
 licenses:
@@ -77,9 +82,9 @@ licenses:
 metadata:
   homepage_uri: https://github.com/trinistr/dicey
   bug_tracker_uri: https://github.com/trinistr/dicey/issues
-  documentation_uri: https://rubydoc.info/gems/dicey/0.16.2
-  source_code_uri: https://github.com/trinistr/dicey/tree/v0.16.2
-  changelog_uri: https://github.com/trinistr/dicey/blob/v0.16.2/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/dicey/0.17.0
+  source_code_uri: https://github.com/trinistr/dicey/tree/v0.17.0
+  changelog_uri: https://github.com/trinistr/dicey/blob/v0.17.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options:
@@ -101,6 +106,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Calculator for dice roll frequency/probability distributions. Also rolls
-  dice.
+summary: Dice roll weights/probabilities distribution calculator. Also rolls dice.
 test_files: []

data/lib/dicey/output_formatters/gnuplot_formatter.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "key_value_formatter"
-
-module Dicey
-  module OutputFormatters
-    # Formats a hash as a text file suitable for consumption by Gnuplot.
-    #
-    # Will transform Rational probabilities to Floats.
-    class GnuplotFormatter < KeyValueFormatter
-      SEPARATOR = " "
-
-      private
-
-      def transform(key, value)
-        [derationalize(key), derationalize(value)]
-      end
-
-      def derationalize(value)
-        value.is_a?(Rational) ? value.to_f : value
-      end
-    end
-  end
-end

data/lib/dicey/output_formatters/hash_formatter.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-module Dicey
-  # Processors which turn data to text.
-  module OutputFormatters
-    # Base formatter for outputting in formats which can be converted from a Hash directly.
-    # Can add an optional description into the result.
-    # @abstract
-    class HashFormatter
-      # @param hash [Hash{Object => Object}]
-      # @param description [String] text to add to result as an extra key
-      # @return [String]
-      def call(hash, description = nil)
-        hash = hash.transform_keys { to_primitive(_1) }
-        hash.transform_values! { to_primitive(_1) }
-        output = {}
-        output["description"] = description if description
-        output["results"] = hash
-        output.public_send(self.class::METHOD)
-      end
-
-      private
-
-      def to_primitive(value)
-        return value if primitive?(value)
-        return value.to_f if Numeric === value
-
-        value.to_s
-      end
-
-      def primitive?(value)
-        value.is_a?(Integer) || value.is_a?(Float) || value.is_a?(String)
-      end
-    end
-  end
-end

data/lib/dicey/output_formatters/json_formatter.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "hash_formatter"
-
-module Dicey
-  module OutputFormatters
-    # Formats a hash as a JSON document under +results+ key, with optional +description+ key.
-    class JSONFormatter < HashFormatter
-      METHOD = :to_json
-    end
-  end
-end

data/lib/dicey/output_formatters/key_value_formatter.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../mixins/rational_to_integer"
-
-module Dicey
-  module OutputFormatters
-    # Base formatter for outputting lists of key-value pairs separated by newlines.
-    # Can add an optional description into the result.
-    # @abstract
-    class KeyValueFormatter
-      include Mixins::RationalToInteger
-
-      # @param hash [Hash{Object => Object}]
-      # @param description [String] text to add as a comment.
-      # @return [String]
-      def call(hash, description = nil)
-        initial_string = description ? "# #{description}\n" : +""
-        hash.each_with_object(initial_string) do |(key, value), output|
-          output << line(transform(key, value)) << "\n"
-        end
-      end
-
-      private
-
-      def transform(key, value)
-        [rational_to_integer(key), rational_to_integer(value)]
-      end
-
-      def line((key, value))
-        "#{key}#{self.class::SEPARATOR}#{value}"
-      end
-    end
-  end
-end

data/lib/dicey/output_formatters/list_formatter.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "key_value_formatter"
-
-module Dicey
-  module OutputFormatters
-    # Formats a hash as list of key => value pairs, similar to a Ruby Hash.
-    class ListFormatter < KeyValueFormatter
-      SEPARATOR = " => "
-    end
-  end
-end

data/lib/dicey/output_formatters/null_formatter.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Dicey
-  module OutputFormatters
-    # Formatter that doesn't format anything and always returns an empty string.
-    class NullFormatter
-      # @param hash [Hash{Object => Object}]
-      # @param description [String] text to add as a comment.
-      # @return [String] always an empty string
-      def call(hash, description = nil) # rubocop:disable Lint/UnusedMethodArgument
-        ""
-      end
-    end
-  end
-end

data/lib/dicey/output_formatters/yaml_formatter.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "hash_formatter"
-
-module Dicey
-  module OutputFormatters
-    # Formats a hash as a YAML document under +results+ key, with optional +description+ key.
-    class YAMLFormatter < HashFormatter
-      METHOD = :to_yaml
-    end
-  end
-end

data/lib/dicey/roller.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "die_foundry"
-
-require_relative "mixins/rational_to_integer"
-require_relative "mixins/vectorize_dice"
-
-module Dicey
-  # Let the dice roll!
-  #
-  # This is the implementation of roll mode for the CLI.
-  class Roller
-    include Mixins::RationalToInteger
-    include Mixins::VectorizeDice
-
-    # @param arguments [Array<String>] die definitions
-    # @param format [#call] formatter for output
-    # @return [nil]
-    # @raise [DiceyError]
-    def call(arguments, format:, **)
-      raise DiceyError, "no dice!" if arguments.empty?
-
-      dice = arguments.flat_map { |definition| die_foundry.cast(definition) }
-      result = roll_dice(dice)
-
-      format.call({ "roll" => rational_to_integer(result) }, AbstractDie.describe(dice))
-    rescue TypeError
-      warn <<~TEXT
-        Dice with non-numeric sides need gem "vector_number" to be present and available.
-        If this is intended, please install the gem.
-      TEXT
-      raise DiceyError, "can not roll dice with non-numeric sides!"
-    end
-
-    private
-
-    def die_foundry
-      @die_foundry ||= DieFoundry.new
-    end
-
-    def roll_dice(dice)
-      dice = vectorize_dice(dice) if defined?(VectorNumber)
-      dice.sum(&:roll)
-    end
-  end
-end

data/lib/dicey/sum_frequency_calculators/auto_selector.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "brute_force"
-require_relative "kronecker_substitution"
-require_relative "multinomial_coefficients"
-
-module Dicey
-  module SumFrequencyCalculators
-    # Tool to automatically select a calculator for a given set of dice.
-    #
-    # Calculator is guaranteed to be compatible, with a strong chance of being the most performant.
-    #
-    # @see BaseCalculator#heuristic_complexity
-    class AutoSelector
-      # Calculators to consider when selecting a match.
-      AVAILABLE_CALCULATORS = [
-        KroneckerSubstitution.new,
-        MultinomialCoefficients.new,
-        BruteForce.new,
-      ].freeze
-
-      # @param calculators [Array<BaseCalculator>]
-      #   calculators which this instance will consider
-      def initialize(calculators = AVAILABLE_CALCULATORS)
-        @calculators = calculators
-      end
-
-      # Determine best (or adequate) calculator for a given set of dice
-      # based on heuristics from the list of available calculators.
-      #
-      # @param dice [Enumerable<NumericDie>]
-      # @return [BaseCalculator, nil] +nil+ if no calculator is compatible
-      def call(dice)
-        compatible = @calculators.select { _1.valid_for?(dice) }
-        return if compatible.empty?
-
-        compatible.min_by { _1.heuristic_complexity(dice) }
-      end
-    end
-  end
-end