games_dice 0.4.2 → 0.6.0

data/ext/games_dice/probabilities.h

@@ -7,41 +7,15 @@
 
 #include <ruby.h>
 
-void init_probabilities_class();
+void init_probabilities_class(void);
 
 typedef struct _pd {
+    struct _pd *next;
+    struct _pd **owner_link;
     int offset;
     int slots;
     double *probs;
     double *cumulative;
   } ProbabilityList;
 
-inline int pl_min( ProbabilityList *pl );
-
-inline int pl_max( ProbabilityList *pl );
-
-ProbabilityList *pl_add_distributions( ProbabilityList *pl_a, ProbabilityList *pl_b );
-
-ProbabilityList *pl_add_distributions_mult( int mul_a, ProbabilityList *pl_a, int mul_b, ProbabilityList *pl_b );
-
-inline double pl_p_eql( ProbabilityList *pl, int target );
-
-inline double pl_p_gt( ProbabilityList *pl, int target );
-
-inline double pl_p_lt( ProbabilityList *pl, int target );
-
-inline double pl_p_le( ProbabilityList *pl, int target );
-
-inline double pl_p_ge( ProbabilityList *pl, int target );
-
-inline double pl_expected( ProbabilityList *pl );
-
-ProbabilityList *pl_given_ge( ProbabilityList *pl, int target );
-
-ProbabilityList *pl_given_le( ProbabilityList *pl, int target );
-
-ProbabilityList *pl_repeat_sum( ProbabilityList *pl, int n );
-
-ProbabilityList *pl_repeat_n_sum_k( ProbabilityList *pl, int n, int k, int kbest );
-
 #endif

data/games_dice.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency 'parslet', '~> 2.0'
 
-  gem.files         = `git ls-files -z`.split("\0").select { |file| File.file?(file) }
+  gem.files         = `git ls-files -z`.split("\0").select { |file| File.file?(file) && file != 'Gemfile.lock' }
   gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
   gem.extensions    = gem.files.grep(%r{/extconf\.rb$})
   gem.require_paths = ['lib']

data/lib/games_dice/bunch.rb

@@ -23,6 +23,8 @@ module GamesDice
   #  d.explain_result # => "4, 9, 2, 9, 1. Keep: 9 + 9 = 18"
   #
   class Bunch
+    include RecipeQueries
+    include ProbabilityHelpers
     include KeepHelpers
     include ExplainHelpers
 
@@ -51,6 +53,7 @@ module GamesDice
                     else
                       GamesDice::Die.new(@sides, options[:prng])
                     end
+      initialize_recipe
     end
 
     # Name to help identify bunch
@@ -75,7 +78,10 @@ module GamesDice
 
     # Result of most-recent roll, or nil if no roll made yet.
     # @return [Integer,nil]
-    attr_reader :result
+    def result
+      refresh_recipe
+      @result
+    end
 
     # @!attribute [r] label
     # Description that will be used in explanations with more than one bunch
@@ -105,80 +111,88 @@ module GamesDice
     # allowing inspection of how the result was obtained.
     # @return [Array<GamesDice::DieResult>, nil] Sequence of GamesDice::DieResult objects.
     def result_details
+      refresh_recipe
       return nil unless @raw_result_details
 
       @raw_result_details.map { |r| r.is_a?(Integer) ? GamesDice::DieResult.new(r) : r }
     end
 
     # @!attribute [r] min
-    # Minimum possible result from a call to #roll
+    # Lower bound on the value returned by #roll. No roll will be below this value.
+    # For some complex dice, this may be lower than any value that can actually
+    # be rolled, because calculating the exact minimum would take too much work.
     # @return [Integer]
     def min
+      refresh_recipe
       n = @keep_mode ? [@keep_number, @ndice].min : @ndice
       n * @single_die.min
     end
 
     # @!attribute [r] max
-    # Maximum possible result from a call to #roll
+    # Upper bound on the value returned by #roll. No roll will exceed this value.
+    # For some complex dice, this may be higher than any value that can actually
+    # be rolled, because calculating the exact maximum would take too much work.
     # @return [Integer]
     def max
+      refresh_recipe
       n = @keep_mode ? [@keep_number, @ndice].min : @ndice
       n * @single_die.max
     end
 
-    # Calculates the probability distribution for the bunch. When the bunch is composed of dice with
-    # open-ended re-roll rules, there are some arbitrary limits imposed to prevent large amounts of
-    # recursion.
-    # @return [GamesDice::Probabilities] Probability distribution of bunch.
+    # Calculates the probability distribution for the bunch.
+    #
+    # Very unlikely sequences of rerolls may be left out to keep calculation
+    # time reasonable. This changes the probability of any result by at most
+    # 1e-10 (one in ten billion) across the whole bunch, in addition to normal
+    # floating-point rounding.
+    #
+    # Raises ProbabilityLimitError if this accuracy cannot be achieved within
+    # the calculation's work limits.
+    # @return [GamesDice::Probabilities] Probability distribution of the bunch.
     def probabilities
-      return @probabilities if @probabilities
-
-      @probabilities = if @keep_mode && @ndice > @keep_number
-                         @single_die.probabilities.repeat_n_sum_k(@ndice, @keep_number, @keep_mode)
-                       else
-                         @single_die.probabilities.repeat_sum(@ndice)
-                       end
-
-      @probabilities
+      probabilities_for_budget(ProbabilityBudget::LIMIT)
     end
 
     # Simulates rolling the bunch of identical dice
     # @return [Integer] Sum of all rolled dice, or sum of all keepers
     def roll
-      generate_raw_results
-      return @result if !@keep_mode || @keep_number.to_i >= @ndice
-
-      use_dice = case @keep_mode
-                 when :keep_best then @raw_result_details.sort[-@keep_number..]
-                 when :keep_worst then @raw_result_details.sort[0..(@keep_number - 1)]
-                 end
-
-      @result = use_dice.sum
+      with_recipe do
+        generate_raw_results
+        @used_result_details = select_keepers
+        @result = @used_result_details.sum
+      end
     end
 
     # @!attribute [r] explain_result
     # Explanation of result, or nil if no call to #roll yet.
     # @return [String,nil]
     def explain_result
+      refresh_recipe
       return nil unless @result
 
-      # With #keep_mode, we may need to show unused and used dice separately
-      used_dice = result_details
-      used_dice, = find_used_dice_due_to_keep_mode(result_details) if @keep_mode && @keep_number < @ndice
-
+      used_dice = @used_result_details.map { |result| result.is_a?(Integer) ? DieResult.new(result) : result }
       build_explanation(used_dice)
     end
 
     private
 
-    def generate_raw_results
-      @result = 0
-      @raw_result_details = []
+    def recipe_sources
+      [[[@single_die], @single_die.class]]
+    end
 
-      @ndice.times do
-        @result += @single_die.roll
-        @raw_result_details << @single_die.result
-      end
+    def recipe_labels
+      [@name]
+    end
+
+    def select_keepers
+      return @raw_result_details if !@keep_mode || @keep_number >= @ndice
+      return @raw_result_details.sort[-@keep_number..] if @keep_mode == :keep_best
+
+      @raw_result_details.sort[0...@keep_number]
+    end
+
+    def generate_raw_results
+      @raw_result_details = Array.new(@ndice) { @single_die.roll }
     end
 
     def name_number_sides_from_hash(options)

data/lib/games_dice/bunch_helpers.rb

@@ -2,6 +2,40 @@
 
 module GamesDice
   class Bunch
+    # @!visibility private
+    # Private distribution and aggregate-error helpers.
+    module ProbabilityHelpers
+      private
+
+      def probabilities_for_budget(limit)
+        refresh_recipe
+        return @probabilities if valid_probability_cache?(limit)
+
+        with_recipe do
+          distribution = single_distribution(limit)
+          result = repeated_distribution(distribution)
+          @probability_error = ProbabilityBudget.check(ProbabilityBudget.scale(single_error, @ndice), limit)
+          @probabilities = result
+        end
+      end
+
+      def repeated_distribution(distribution)
+        return distribution.repeat_sum(@ndice) unless @keep_mode && @ndice > @keep_number
+
+        distribution.repeat_n_sum_k(@ndice, @keep_number, @keep_mode)
+      end
+
+      def single_error
+        @single_die.is_a?(ComplexDie) ? @single_die.instance_variable_get(:@probability_error) : 0.0
+      end
+
+      def single_distribution(limit)
+        return @single_die.probabilities unless @single_die.is_a?(ComplexDie)
+
+        @single_die.__send__(:probabilities_for_budget, ProbabilityBudget.share(limit, @ndice))
+      end
+    end
+
     # @!visibility private
     # Private extension methods for GamesDice::Bunch keep rules
     module KeepHelpers
@@ -14,25 +48,12 @@ module GamesDice
           @keep_mode = nil
         when :keep_best, :keep_worst
           @keep_number = Integer(options[:keep_number] || 1)
+          raise ArgumentError, ":keep_number must be 1 or more, but got #{@keep_number}" unless @keep_number.positive?
         else
           raise ArgumentError, ":keep_mode can be nil, :keep_best or :keep_worst. Got #{options[:keep_mode].inspect}"
         end
       end
 
-      def find_used_dice_due_to_keep_mode(used_dice, unused_dice = [])
-        full_dice = result_details.sort_by(&:total)
-        case @keep_mode
-        when :keep_best
-          used_dice = full_dice[-@keep_number..]
-          unused_dice = full_dice[0..(full_dice.length - 1 - @keep_number)]
-        when :keep_worst
-          used_dice = full_dice[0..(@keep_number - 1)]
-          unused_dice = full_dice[@keep_number..]
-        end
-
-        [used_dice, unused_dice]
-      end
-
       def explain_kept_dice(used_dice)
         separator = @single_die.maps ? ', ' : ' + '
         ". Keep: #{used_dice.map(&:explain_total).join(separator)}"

data/lib/games_dice/complex_die.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'games_dice/complex_die_helpers'
+require 'games_dice/probability_calculation'
 
 module GamesDice
   # This class models a die that is built up from a simpler unit by adding rules to re-roll
@@ -25,6 +26,7 @@ module GamesDice
   #
   class ComplexDie
     include RollHelpers
+    include RecipeQueries
     include ProbabilityHelpers
     include MinMaxHelpers
 
@@ -51,6 +53,7 @@ module GamesDice
       @total = nil
       @result = nil
 
+      initialize_recipe
       @probabilities_complete = true
     end
 
@@ -65,14 +68,25 @@ module GamesDice
     attr_reader :maps
 
     # @return [GamesDice::DieResult, nil] Result of last call to #roll, nil if no call made yet
-    attr_reader :result
+    def result
+      refresh_recipe
+      @result
+    end
 
-    # Whether or not #probabilities includes all possible outcomes.
-    # True if all possible results are represented and assigned a probability. Dice with open-ended re-rolls
-    # may have calculations cut short, and will result in a false value of this attribute. Even when this
-    # attribute is false, probabilities should still be accurate to nearest 1e-9.
-    # @return [Boolean, nil] Depending on completeness when generating #probabilities
-    attr_reader :probabilities_complete
+    # Whether the probability calculation included all possible sequences of rerolls.
+    # After calling #probabilities, true means none were left out. False means
+    # very unlikely sequences were skipped to keep calculation time reasonable.
+    # Even when false, this changes the probability of any result by at most
+    # 1e-10 (one in ten billion), in addition to normal floating-point rounding.
+    #
+    # Call #probabilities before checking this value. A new die starts with true,
+    # even though no calculation has run yet.
+    # @return [Boolean, nil] Whether the calculation is complete, or nil if its
+    #   result was cleared after a recipe change or a failed calculation.
+    def probabilities_complete
+      refresh_recipe
+      @probabilities_complete
+    end
 
     # @!attribute [r] sides
     # @return [Integer] Number of sides.
@@ -83,49 +97,77 @@ module GamesDice
     # @!attribute [r] explain_result
     # @return [String,nil] Explanation of result, or nil if no call to #roll yet.
     def explain_result
-      @result.explain_value
+      refresh_recipe
+      @result&.explain_value
     end
 
-    # The minimum possible result from a call to #roll. This is not always the same as the theoretical
-    # minimum, due to limits on the maximum number of rerolls.
+    # Lower bound on the numeric value of a roll (#roll.value).
+    # No roll will have a value below this bound.
+    # For some complex dice, this may be lower than any value that can actually
+    # be rolled, because calculating the exact minimum would take too much work.
+    #
+    # Raises ProbabilityLimitError if a lower bound cannot be found within
+    # the calculation's work limits.
     # @!attribute [r] min
     # @return [Integer]
     def min
+      refresh_recipe
       return @min_result if @min_result
 
-      calc_minmax
+      with_recipe { calc_minmax }
       @min_result
     end
 
+    # Upper bound on the numeric value of a roll (#roll.value).
+    # No roll will have a value above this bound.
+    # For some complex dice, this may be higher than any value that can actually
+    # be rolled, because calculating the exact maximum would take too much work.
+    #
+    # Raises ProbabilityLimitError if an upper bound cannot be found within
+    # the calculation's work limits.
     # @!attribute [r] max
-    # @return [Integer] Maximum possible result from a call to #roll
+    # @return [Integer]
     def max
+      refresh_recipe
       return @max_result if @max_result
 
-      calc_minmax
+      with_recipe { calc_minmax }
       @max_result
     end
 
-    # Calculates the probability distribution for the die. For open-ended re-roll rules, there are some
-    # arbitrary limits imposed to prevent large amounts of recursion. Probabilities should be to nearest
-    # 1e-9 at worst.
-    # @return [GamesDice::Probabilities] Probability distribution of die.
+    # Calculates the probability distribution for the die.
+    #
+    # Very unlikely sequences of rerolls may be left out to keep calculation
+    # time reasonable. This changes the probability of any result by at most
+    # 1e-10 (one in ten billion), in addition to normal floating-point rounding.
+    #
+    # Raises ProbabilityLimitError if this accuracy cannot be achieved within
+    # the calculation's work limits.
+    # @return [GamesDice::Probabilities] Probability distribution of the die.
     def probabilities
-      @probabilities ||= calculate_probabilities
+      probabilities_for_budget(ProbabilityBudget::LIMIT)
     end
 
     # Simulates rolling the die
     # @param [Symbol] reason Assign a reason for rolling the first die.
     # @return [GamesDice::DieResult] Detailed results from rolling the die, including resolution of rules.
     def roll(reason = :basic)
-      @result = GamesDice::DieResult.new(@basic_die.roll, reason)
-      roll_apply_rerolls
-      roll_apply_maps
-      @result
+      with_recipe do
+        rerolls = @rerolls&.dup
+        maps = @maps&.dup
+        @result = GamesDice::DieResult.new(@basic_die.roll, reason)
+        roll_apply_rerolls(rerolls)
+        roll_apply_maps(maps)
+        @result
+      end
     end
 
     private
 
+    def recipe_sources
+      [[@rerolls, RerollRule], [@maps, MapRule]]
+    end
+
     def construct_rerolls(rerolls_input)
       check_and_construct rerolls_input, GamesDice::RerollRule, 'rerolls'
     end