dicey 0.0.1 → 0.13.1

data/lib/dicey/output_formatters/key_value_formatter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+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
+      # @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 << "#{key}#{self.class::SEPARATOR}#{value}\n"
+        end
+      end
+    end
+  end
+end

data/lib/dicey/output_formatters/list_formatter.rb

@@ -0,0 +1,12 @@
+# 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/yaml_formatter.rb

@@ -0,0 +1,12 @@
+# 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/regular_die.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "numeric_die"
+
+module Dicey
+  # Regular die, which has N sides with numbers from 1 to N.
+  class RegularDie < NumericDie
+    # Characters to use for small dice.
+    D6 = "⚀⚁⚂⚃⚄⚅"
+
+    # Create a list of regular dice with the same number of sides.
+    #
+    # @param dice [Integer]
+    # @param sides [Integer]
+    # @return [Array<RegularDie>]
+    def self.create_dice(dice, sides)
+      (1..dice).map { new(sides) }
+    end
+
+    # @param sides [Integer]
+    def initialize(sides)
+      super((1..sides))
+    end
+
+    # Dice with 1–6 sides are displayed with a single character.
+    # More than that, and we get into the square bracket territory.
+    # @return [String]
+    def to_s
+      (sides_num <= D6.size) ? D6[sides_num - 1] : "[#{sides_num}]"
+    end
+  end
+end

data/lib/dicey/roller.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "die_foundry"
+
+module Dicey
+  # Let the dice roll!
+  class Roller
+    # @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.map { |definition| die_foundry.cast(definition) }
+      dice.each(&:roll)
+
+      result = dice.sum(&:current)
+      format.call({ "roll" => result }, AbstractDie.describe(dice))
+    end
+
+    private
+
+    def die_foundry
+      @die_foundry ||= DieFoundry.new
+    end
+  end
+end

data/lib/dicey/sum_frequency_calculators/base_calculator.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Dicey
+  module SumFrequencyCalculators
+    # Base frequencies calculator.
+    # @abstract
+    class BaseCalculator
+      # Possible values for +result_type+ argument in {#call}.
+      RESULT_TYPES = %i[frequencies probabilities].freeze
+
+      # @param dice [Enumerable<AbstractDie>]
+      # @param result_type [Symbol] one of {RESULT_TYPES}
+      # @return [Hash{Numeric => Numeric}] frequencies of each sum
+      # @raise [DiceyError] if +result_type+ is invalid
+      # @raise [DiceyError] if dice list is invalid for the calculator
+      # @raise [DiceyError] if calculator returned obviously wrong results
+      def call(dice, result_type: :frequencies)
+        unless RESULT_TYPES.include?(result_type)
+          raise DiceyError, "#{result_type} is not a valid result type!"
+        end
+        raise DiceyError, "#{self.class} can not handle these dice!" unless valid_for?(dice)
+
+        frequencies = calculate(dice)
+        verify_result(frequencies, dice)
+        frequencies = sort_result(frequencies)
+        transform_result(frequencies, result_type)
+      end
+
+      # Whether this calculator can be used for the list of dice.
+      #
+      # @param dice [Enumerable<AbstractDie>]
+      # @return [Boolean]
+      def valid_for?(dice)
+        dice.is_a?(Enumerable) && dice.all? { _1.is_a?(AbstractDie) } && validate(dice)
+      end
+
+      private
+
+      # Do additional validation on the dice list.
+      # (see #valid_for?)
+      def validate(_dice)
+        true
+      end
+
+      # Peform frequencies calculation.
+      # (see #call)
+      def calculate(dice)
+        raise NotImplementedError
+      end
+
+      # Check that resulting frequencies actually add up to what they are supposed to be.
+      #
+      # @param frequencies [Hash{Numeric => Integer}]
+      # @param dice [Enumerable<AbstractDie>]
+      # @return [void]
+      # @raise [DiceyError] if result is wrong
+      def verify_result(frequencies, dice)
+        valid = frequencies.values.sum == dice.map(&:sides_num).reduce(:*)
+        raise DiceyError, "calculator #{self.class} returned invalid results!" unless valid
+      end
+
+      # Depending on the order of sides, result may not be in an ascending order,
+      # so it's best to fix that for presentation (if possible).
+      def sort_result(frequencies)
+        frequencies.sort.to_h
+      rescue
+        # Probably Complex numbers got into the mix, leave as is.
+        frequencies
+      end
+
+      # Transform calculated frequencies to requested result_type, if needed.
+      #
+      # @param frequencies [Hash{Numeric => Integer}]
+      # @param result_type [Symbol] one of {RESULT_TYPES}
+      # @return [Hash{Numeric => Numeric}]
+      def transform_result(frequencies, result_type)
+        case result_type
+        when :frequencies
+          frequencies
+        when :probabilities
+          total = frequencies.values.sum
+          frequencies.transform_values { _1.fdiv(total) }
+        else
+          # Invalid, but was already checked in #call.
+        end
+      end
+    end
+  end
+end

data/lib/dicey/sum_frequency_calculators/brute_force.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "base_calculator"
+
+module Dicey
+  module SumFrequencyCalculators
+    # Calculator for a collection of {NumericDie} using exhaustive search (very slow).
+    class BruteForce < BaseCalculator
+      private
+
+      # def validate(dice)
+      #   dice.all? { |die| die.is_a?(NumericDie) }
+      # end
+
+      def calculate(dice)
+        # TODO: Replace `combine_dice_enumerators` with `Enumerator.product`.
+        combine_dice_enumerators(dice).map(&:sum).tally
+      end
+
+      # Get an enumerator which goes through all possible permutations of dice sides.
+      #
+      # @param dice [Enumerable<NumericDie>]
+      # @return [Enumerator<Array>]
+      def combine_dice_enumerators(dice)
+        sides_num_list = dice.map(&:sides_num)
+        total = sides_num_list.reduce(:*)
+        Enumerator.new(total) do |yielder|
+          current_values = dice.map(&:next)
+          remaining_iterations = sides_num_list
+          total.times do
+            yielder << current_values
+            iterate_dice(dice, remaining_iterations, current_values)
+          end
+        end
+      end
+
+      # Iterate through dice, getting next side for first die,
+      # then getting next side for second die, resetting first die, and so on.
+      # This is analogous to incrementing by 1 in a positional system
+      # where each position is a die.
+      #
+      # @param dice [Enumerable<NumericDie>]
+      # @param remaining_iterations [Array<Integer>]
+      # @param current_values [Array<Numeric>]
+      # @return [void]
+      def iterate_dice(dice, remaining_iterations, current_values)
+        dice.each_with_index do |die, i|
+          value = die.next
+          current_values[i] = value
+          remaining_iterations[i] -= 1
+          break if remaining_iterations[i].nonzero?
+
+          remaining_iterations[i] = die.sides_num
+        end
+      end
+    end
+  end
+end

data/lib/dicey/sum_frequency_calculators/kronecker_substitution.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "base_calculator"
+
+module Dicey
+  module SumFrequencyCalculators
+    # Calculator for lists of dice with non-negative integer sides (fast).
+    #
+    # Example dice: (1,2,3,4), (0,1,5,6), (5,4,5,4,5).
+    #
+    # Based on Kronecker substitution method for polynomial multiplication.
+    # @see https://en.wikipedia.org/wiki/Kronecker_substitution
+    # @see https://arxiv.org/pdf/0712.4046v1.pdf in particular section 3
+    class KroneckerSubstitution < BaseCalculator
+      private
+
+      def validate(dice)
+        dice.all? { |die| die.sides_list.all? { _1.is_a?(Integer) && _1 >= 0 } }
+      end
+
+      def calculate(dice)
+        polynomials = build_polynomials(dice)
+        evaluation_point = find_evaluation_point(polynomials)
+        values = evaluate_polynomials(polynomials, evaluation_point)
+        product = values.reduce(:*)
+        extract_coefficients(product, evaluation_point)
+      end
+
+      # Turn dice into hashes where keys are side values and values are numbers of those sides,
+      # representing corresponding polynomials where
+      # side values are powers and numbers are coefficients.
+      #
+      # @param dice [Enumerable<NumericDie>]
+      # @return [Array<Hash{Integer => Integer}>]
+      def build_polynomials(dice)
+        dice.map { _1.sides_list.tally }
+      end
+
+      # Find a power of 2 which is larger in magnitude than any resulting polynomial coefficients,
+      # and so able to hold each coefficient without overlap.
+      #
+      # @param polynomials [Array<Hash{Integer => Integer}>]
+      # @return [Integer]
+      def find_evaluation_point(polynomials)
+        polynomial_length = polynomials.flat_map(&:keys).max + 1
+        e = Math.log2(polynomial_length).ceil
+        b = polynomials.flat_map(&:values).max.bit_length
+        coefficient_magnitude = (polynomials.size * b) + ((polynomials.size - 1) * e)
+        1 << coefficient_magnitude
+      end
+
+      # Get values of polynomials if +evaluation_point+ is substituted for the variable.
+      #
+      # @param polynomials [Array<Hash{Integer => Integer}>]
+      # @param evaluation_point [Integer]
+      # @return [Array<Integer>]
+      def evaluate_polynomials(polynomials, evaluation_point)
+        polynomials.map do |polynomial|
+          polynomial.sum { |power, coefficient| (evaluation_point**power) * coefficient }
+        end
+      end
+
+      # Unpack coefficients from the product of polynomial values,
+      # building resulting polynomial.
+      #
+      # @param product [Integer]
+      # @param evaluation_point [Integer]
+      # @return [Hash{Integer => Integer}]
+      def extract_coefficients(product, evaluation_point)
+        window = evaluation_point - 1
+        window_shift = window.bit_length
+        (0..).each_with_object({}) do |power, result|
+          coefficient = product & window
+          result[power] = coefficient unless coefficient.zero?
+          product >>= window_shift
+          break result if product.zero?
+        end
+      end
+    end
+  end
+end

data/lib/dicey/sum_frequency_calculators/multinomial_coefficients.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "base_calculator"
+
+module Dicey
+  module SumFrequencyCalculators
+    # Calculator for multiple equal dice with sides forming an arithmetic sequence (fast).
+    #
+    # Example dice: (1,2,3,4), (-2,-1,0,1,2), (0,0.2,0.4,0.6), (-1,-2,-3).
+    #
+    # Based on extension of Pascal's triangle for a higher number of coefficients.
+    # @see https://en.wikipedia.org/wiki/Pascal%27s_triangle
+    # @see https://en.wikipedia.org/wiki/Trinomial_triangle
+    class MultinomialCoefficients < BaseCalculator
+      private
+
+      def validate(dice)
+        first_die = dice.first
+        return false unless first_die.is_a?(NumericDie)
+        return false unless dice.all? { _1 == first_die }
+        return true if first_die.sides_num == 1
+
+        arithmetic_sequence?(first_die.sides_list)
+      end
+
+      # @param sides_list [Array<Numeric>]
+      # @return [false, Array<Numeric>]
+      def arithmetic_sequence?(sides_list)
+        increment = sides_list[1] - sides_list[0]
+        return false if increment.zero?
+
+        sides_list.each_cons(2) { return false if _1 + increment != _2 }
+      end
+
+      # @param dice [Array<NumericDie>]
+      # @return [Hash{Numeric => Integer}]
+      def calculate(dice)
+        first_die = dice.first
+        number_of_sides = first_die.sides_num
+        number_of_dice = dice.size
+
+        frequencies = multinomial_coefficients(number_of_dice, number_of_sides)
+        result_sums_list(first_die.sides_list, number_of_dice).zip(frequencies).to_h
+      end
+
+      # Calculate coefficients for a multinomial of the form
+      # <tt>(x^1 +...+ x^m)^n</tt>, where +m+ is the number of sides and +n+ is the number of dice.
+      #
+      # @param dice [Integer] number of dice, must be positive
+      # @param sides [Integer] number of sides, must be positive
+      # @param throw_away_garbage [Boolean] whether to discard unused coefficients (debug option)
+      # @return [Array<Integer>]
+      def multinomial_coefficients(dice, sides, throw_away_garbage: true)
+        # This builds a triangular matrix where each first element is a 1.
+        # Each element is a sum of +m+ elements in the previous row
+        # with indices less or equal to its, with out-of-bounds indices corresponding to 0s.
+        # Example for m=3:
+        # 1
+        # 1 1 1
+        # 1 2 3 2 1
+        # 1 3 6 7 6 3 1, etc.
+        coefficients = [[1]]
+        (1..dice).each do |row_index|
+          row = next_row_of_coefficients(row_index, sides - 1, coefficients.last)
+          if throw_away_garbage
+            coefficients[0] = row
+          else
+            coefficients << row
+          end
+        end
+        coefficients.last
+      end
+
+      # @param row_index [Integer]
+      # @param window_size [Integer]
+      # @param previous_row [Array<Integer>]
+      # @return [Array<Integer>]
+      def next_row_of_coefficients(row_index, window_size, previous_row)
+        length = (row_index * window_size) + 1
+        (0..length).map do |col_index|
+          # Have to clamp to 0 to prevent accessing array from the end.
+          window_range = ((col_index - window_size).clamp(0..)..col_index)
+          window_range.sum { |i| previous_row.fetch(i, 0) }
+        end
+      end
+
+      # Get sequence of sums which correspond to calculated frequencies.
+      #
+      # @param sides_list [Enumerable<Numeric>]
+      # @param number_of_dice [Integer]
+      # @return [Array<Numeric>]
+      def result_sums_list(sides_list, number_of_dice)
+        first = number_of_dice * sides_list.first
+        last = number_of_dice * sides_list.last
+        return [first] if first == last
+
+        increment = sides_list[1] - sides_list[0]
+        Enumerator
+          .produce(first) { _1 + increment }
+          .take_while { (_1 < last) == (first < last) || _1 == last }
+      end
+    end
+  end
+end

data/lib/dicey/sum_frequency_calculators/runner.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../die_foundry"
+
+require_relative "brute_force"
+require_relative "kronecker_substitution"
+require_relative "multinomial_coefficients"
+
+module Dicey
+  module SumFrequencyCalculators
+    # The defaultest runner which calculates roll frequencies from command-line dice.
+    class Runner
+      # Transform die definitions to roll frequencies.
+      #
+      # @param arguments [Array<String>] die definitions
+      # @param roll_calculators [Array<BaseCalculator>] list of calculators to use
+      # @param format [#call] formatter for output
+      # @param result [Symbol] result type selector
+      # @return [nil]
+      # @raise [DiceyError]
+      def call(arguments, roll_calculators:, format:, result:, **)
+        raise DiceyError, "no dice!" if arguments.empty?
+
+        dice = arguments.map { |definition| die_foundry.cast(definition) }
+        frequencies = roll_calculators.find { _1.valid_for?(dice) }&.call(dice, result_type: result)
+        raise DiceyError, "no calculator could handle these dice!" unless frequencies
+
+        format.call(frequencies, AbstractDie.describe(dice))
+      end
+
+      private
+
+      def die_foundry
+        @die_foundry ||= DieFoundry.new
+      end
+    end
+  end
+end

data/lib/dicey/sum_frequency_calculators/test_runner.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "brute_force"
+require_relative "kronecker_substitution"
+require_relative "multinomial_coefficients"
+
+module Dicey
+  module SumFrequencyCalculators
+    # A simple testing facility for roll frequency calculators.
+    class TestRunner
+      # These are manually calculated frequencies,
+      # with test cases for pretty much all variations of what this program can handle.
+      TEST_DATA = [
+        [[1], { 1 => 1 }],
+        [[10], { 1 => 1, 2 => 1, 3 => 1, 4 => 1, 5 => 1, 6 => 1, 7 => 1, 8 => 1, 9 => 1, 10 => 1 }],
+        [[2, 2], { 2 => 1, 3 => 2, 4 => 1 }],
+        [[3, 3], { 2 => 1, 3 => 2, 4 => 3, 5 => 2, 6 => 1 }],
+        [[4, 4], { 2 => 1, 3 => 2, 4 => 3, 5 => 4, 6 => 3, 7 => 2, 8 => 1 }],
+        [[9, 9],
+         { 2 => 1, 3 => 2, 4 => 3, 5 => 4, 6 => 5, 7 => 6, 8 => 7, 9 => 8, 10 => 9,
+           11 => 8, 12 => 7, 13 => 6, 14 => 5, 15 => 4, 16 => 3, 17 => 2, 18 => 1 }],
+        [[2, 2, 2], { 3 => 1, 4 => 3, 5 => 3, 6 => 1 }],
+        [[3, 3, 3], { 3 => 1, 4 => 3, 5 => 6, 6 => 7, 7 => 6, 8 => 3, 9 => 1 }],
+        [[2, 2, 2, 2], { 4 => 1, 5 => 4, 6 => 6, 7 => 4, 8 => 1 }],
+        [[1, 2, 3], { 3 => 1, 4 => 2, 5 => 2, 6 => 1 }],
+        [[3, 2, 1], { 3 => 1, 4 => 2, 5 => 2, 6 => 1 }],
+        [[[0], 1], { 1 => 1 }],
+        [[4, 6], { 2 => 1, 3 => 2, 4 => 3, 5 => 4, 6 => 4, 7 => 4, 8 => 3, 9 => 2, 10 => 1 }],
+        [[[3, 17, 21]], { 3 => 1, 17 => 1, 21 => 1 }],
+        [[[3, 3, 3, 3, 3, 5, 5, 5]], { 3 => 5, 5 => 3 }],
+        [[[1, 4, 6], [1, 4, 6]], { 2 => 1, 5 => 2, 7 => 2, 8 => 1, 10 => 2, 12 => 1 }],
+        [[[3, 4, 3], [1, 3, 2]], { 4 => 2, 5 => 3, 6 => 3, 7 => 1 }],
+        [[[0, 0], [0, 0, 0], [0], [0, 0, 0, 0]], { 0 => 24 }],
+        [[[0], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]], { 0 => 12 }],
+        [[[-0.5, 0.5, 1], 6],
+         { 0.5 => 1, 1.5 => 2, 2 => 1, 2.5 => 2, 3 => 1, 3.5 => 2, 4 => 1,
+           4.5 => 2, 5 => 1, 5.5 => 2, 6 => 1, 6.5 => 1, 7 => 1 }],
+        [Array.new(3) { [-0.25, 0.0, 0.25, 0.5, 0.75] },
+         { -0.75 => 1, -0.5 => 3, -0.25 => 6, 0.0 => 10, 0.25 => 15, 0.5 => 18, 0.75 => 19,
+           1.0 => 18, 1.25 => 15, 1.5 => 10, 1.75 => 6, 2.0 => 3, 2.25 => 1 }],
+        [[[1.i, 2.i, 3.i], [1, 2, 3]],
+         { Complex(1, 1) => 1, Complex(2, 1) => 1, Complex(3, 1) => 1,
+           Complex(1, 2) => 1, Complex(2, 2) => 1, Complex(3, 2) => 1,
+           Complex(1, 3) => 1, Complex(2, 3) => 1, Complex(3, 3) => 1 }],
+      ].freeze
+
+      # Strings for displaying test results.
+      RESULT_TEXT = { pass: "✔", fail: "✘ 🠐 failure!", skip: "☂", crash: "⛐ 🠐 crash!" }.freeze
+      # Which test results are considered failures.
+      FAILURE_RESULTS = %i[fail crash].freeze
+
+      # Check all tests defined in {TEST_DATA} with every passed calculator.
+      #
+      # @param roll_calculators [Array<BaseCalculator>]
+      # @param report_style [Symbol] one of: +:full+, +:quiet+;
+      #   +:quiet+ style does not output any text
+      # @return [Boolean] whether there are no failing tests
+      def call(*, roll_calculators:, report_style:, **)
+        results = TEST_DATA.to_h { |test| run_test(test, roll_calculators) }
+        full_report(results) if report_style == :full
+        results.values.none? do |test_result|
+          test_result.values.any? { FAILURE_RESULTS.include?(_1) }
+        end
+      end
+
+      private
+
+      # @param test [Array(Array<Integer, Array<Numeric>>, Hash{Numeric => Integer})]
+      #   pair of a dice list definition and expected results
+      # @param calculators [Array<BaseCalculator>]
+      # @return [Array(Array<NumericDie>, Hash{BaseCalculator => Symbol})]
+      #   result of running the test in a format suitable for +#to_h+
+      def run_test(test, calculators)
+        dice = build_dice(test.first)
+        test_result =
+          calculators.each_with_object({}) do |calculator, hash|
+            hash[calculator] = run_test_on_calculator(calculator, dice, test.last)
+          end
+        [dice, test_result]
+      end
+
+      # Build a list of {NumericDie} objects from a plain definition.
+      #
+      # @param definition [Array<Integer, Array<Integer>>]
+      # @return [Array<NumericDie>]
+      def build_dice(definition)
+        definition.map { _1.is_a?(Integer) ? RegularDie.new(_1) : NumericDie.new(_1) }
+      end
+
+      # Determine test result for the selected calculator.
+      def run_test_on_calculator(calculator, dice, expectation)
+        return :skip unless calculator.valid_for?(dice)
+
+        (calculator.call(dice) == expectation) ? :pass : :fail
+      rescue
+        :crash
+      end
+
+      # Print results of running all tests.
+      def full_report(results)
+        results.each do |dice, test_result|
+          print "#{AbstractDie.describe(dice)}:\n"
+          test_result.each do |calculator, result|
+            print "  #{calculator.class}: "
+            puts RESULT_TEXT[result]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dicey/version.rb

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

data/lib/dicey.rb

@@ -1,3 +1,11 @@
-$:.unshift File.dirname(__FILE__)
+# frozen_string_literal: true
 
-require 'dicey/dice'
+# A library for rolling dice and calculating roll frequencies.
+module Dicey
+  # General error for Dicey.
+  class DiceyError < StandardError; end
+
+  Dir["#{__dir__}/dicey/*.rb"].each { require _1 }
+  Dir["#{__dir__}/dicey/output_formatters/*.rb"].each { require _1 }
+  Dir["#{__dir__}/dicey/sum_frequency_calculators/*.rb"].each { require _1 }
+end

data/sig/dicey.rbs

@@ -0,0 +1,3 @@
+module Dicey
+  VERSION: String
+end