contrek 1.3.9 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b6523977828bd1e9398d438e045ed1335826630c472a8d1caff6cf0b09ed94e
-  data.tar.gz: 247332cbd56024ef7e7847294c1ffa32bc59d0a13ef65dc23f5bd6641126b993
+  metadata.gz: 8d3c8751ab1e2182443227811912d1b0ad864dde99b62aae50c51b1265314bf3
+  data.tar.gz: d3a1ad93edd90e4ebb41a4e1371cd0ed5a2c134fbc093f898a920b8e81e8c249
 SHA512:
-  metadata.gz: c632b70f8e0130d39a70c7d13e37f0a0fbec38e045a0c681e7327adc9cf62655e9d35897e0b0f0963777297fd04d4be171f1204a4b9b6974c03344d8318910fd
-  data.tar.gz: 8941c3749e72b0d3fbdf90fb5a5516b8e7730c3b71a826e6332a87809333b48d9dd18d2136e3917693d6c0009a035ffce4c904295263a1163fa81e542de2fd7c
+  metadata.gz: e423133c5e9dfe2f490c84e2c47bdd585d9771949ccf8dbd1afd21b254dea876c7bc18f5cd1e71e327d50cec3de2a7abe5bcb39029f578ab043b43c9a785b607
+  data.tar.gz: 3b343824bbe74a380e6e3f084d628c00a7b3efeac373cf65a80b50de66827d5c62b44a4e33ed248b3144336a35c7712e96681b8f754e1dbcee280680b3caf9ab

data/CHANGELOG.md

@@ -150,3 +150,6 @@ All notable changes to this project will be documented in this file.
 
 ## [1.3.9] - 2026-08-09
 - Removed the curses development dependency along with the old TerminalTracker; actually Bitmaps::Rendering.to_window renders visually better results.
+
+## [1.4.0] - 2026-08-13
+- Added deterministic merge mode usefull when you need a byte-for-byte reproducible outputs across different runs (by default, the merge stage is non-deterministic to maximize performance and thread utilization).

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    contrek (1.3.9)
+    contrek (1.4.0)
       chunky_png (~> 1.4)
       concurrent-ruby (~> 1.3.5)
       rice (= 4.5.0)

data/README.md

@@ -376,11 +376,9 @@ The native implementation uses the number of available CPU cores reported by the
 
 ## A note about determinism
 
-The tracing stage itself is deterministic.
+By default, the merge stage is **non-deterministic** to maximize performance and thread utilization.
 
-The merge stage is not.
-
-Each stripe is processed independently and adjacent stripes are merged as soon as they become available. Depending on thread scheduling, the merge order may differ from one execution to another.
+Each stripe is processed independently, and adjacent stripes are merged opportunistically as soon as they become available. Depending on thread scheduling, the merge order may differ between runs.
 
 For example, given three stripes:
 
@@ -400,7 +398,13 @@ while another execution may produce:
 B1 + (B2 + B3)
 ```
 
-Both executions generate equivalent polygons, but the order of intermediate merge operations is differentso the final coordinate sequence is not guaranteed to be byte-for-byte identical across executions.
+Both executions generate equivalent polygons, but the order of intermediate merge operations is different so the final coordinate sequence is not guaranteed to be byte-for-byte identical across executions.
+
+If you require byte-for-byte reproducible outputs across different runs, you can enable the **deterministic merge mode** (setting `deterministic: true`).
+
+In deterministic mode, stripes are merged strictly according to a fixed binary reduction tree based on their order and index.
+
+> **Requirement:** Deterministic mode requires an **even number of stripes/tiles** to process correctly.
 
 ## Native execution
 

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/FinderUtils.cpp

@@ -28,6 +28,7 @@ void FinderUtils::sanitize_options(pf_Options& options, const Options& incoming_
     options.named_sequences);
   options.bounds = incoming_options.get<bool>("bounds", options.bounds);
   options.unsafe_mode = incoming_options.get<bool>("unsafe_mode", options.unsafe_mode);
+  options.deterministic = incoming_options.get<bool>("deterministic", options.deterministic);
 
   if (const Options* compress = incoming_options.get_options("compress")) {
     options.compress_uniq = compress->get<bool>("uniq", options.compress_uniq);

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/PolygonFinder.h

@@ -53,6 +53,7 @@ struct pf_Options {
   bool named_sequences = false;
   bool unsafe_mode = false;
   bool bounds = false;
+  bool deterministic = false;
   int connectivity_offset = 0;
   float compress_visvalingam_tolerance = 10.0;
   int number_of_tiles = 1;

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/Cluster.cpp

@@ -135,16 +135,17 @@ Tile* Cluster::merge_tiles() {
       }
     }
   }
-
-  double past_tot_outer = tiles_.front()->benchmarks.outer + tiles_.back()->benchmarks.outer;
-  double past_tot_inner = tiles_.front()->benchmarks.inner + tiles_.back()->benchmarks.inner;
+  Tile* first_tile = tiles_.front();
+  Tile* last_tile = tiles_.back();
+  double past_tot_outer = first_tile->benchmarks.outer + last_tile->benchmarks.outer;
+  double past_tot_inner = first_tile->benchmarks.inner + last_tile->benchmarks.inner;
   Benchmarks b{
     tot_outer + past_tot_outer,
     tot_inner + past_tot_inner
   };
 
   Tile* tile = new Tile(
-    this->finder_, tiles_.front()->start_x(), tiles_.back()->end_x(), tiles_.front()->name() + tiles_.back()->name(), b);
+    this->finder_, first_tile->start_x(), last_tile->end_x(), first_tile->name() + last_tile->name(), first_tile->index() / 2, b, first_tile->order() + 1);
 
   tile->assign_shapes(new_shapes);
   for (const auto shape : detach_shapes) {

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/Finder.cpp

@@ -10,6 +10,7 @@
 #include <utility>
 #include <vector>
 #include <string>
+#include <algorithm>
 #include "Finder.h"
 #include "../../bitmaps/Bitmap.h"
 #include "../../matchers/Matcher.h"
@@ -35,6 +36,9 @@ Finder::Finder(int number_of_threads, Bitmap *bitmap, Matcher *matcher, const Op
   if (cw < 1.0) {
     throw std::runtime_error("One pixel tile width minimum!");
   }
+  if (this->options_.deterministic && (this->options_.number_of_tiles % 2 != 0)) {
+    throw std::invalid_argument("Deterministic mode requires an even number of tiles!");
+  }
   int x = 0;
   for (int tile_index = 0; tile_index < this->options_.number_of_tiles; tile_index++)
   { int tile_end_x = static_cast<int>(cw * (tile_index + 1));
@@ -65,14 +69,14 @@ Finder::Finder(int number_of_threads, Bitmap *bitmap, Matcher *matcher, const Op
       }
 
       Tile* tile = new Tile(this, payload.tile_start_x, payload.tile_end_x,
-                            std::to_string(payload.tile_index), Benchmarks {0, 0});
+                            std::to_string(payload.tile_index), payload.tile_index, Benchmarks {0, 0});
       tile->initial_process(finder);
       tiles_.queue_push(tile);
     });
 
     x = tile_end_x - 1;
   }
-  this->process_tiles();
+  this->process_tiles(this->options_.deterministic);
   reports["init"] = cpu_timer.stop();
 }
 
@@ -82,7 +86,7 @@ Finder::Finder(int number_of_threads, const Options& options)
   reports["init"] = 0;
 }
 
-void Finder::process_tiles() {
+void Finder::process_tiles(bool deterministic) {
   std::vector<Tile*> arriving_tiles;
 
   while (true) {
@@ -97,7 +101,14 @@ void Finder::process_tiles() {
       arriving_tiles.begin(),
       arriving_tiles.end(),
       [&](Tile* t) {
-        return (t->start_x() == (tile->end_x() - 1)) || ((t->end_x() - 1) == tile->start_x());
+        bool is_adjacent = (t->start_x() == (tile->end_x() - 1)) ||
+                           ((t->end_x() - 1) == tile->start_x());
+        if (!is_adjacent) return false;
+        if (deterministic && !this->last_couple(tile, t)) {
+          if (tile->order() != t->order()) return false;
+          if (std::min(t->index(), tile->index()) % 2 != 0) return false;
+        }
+        return true;
       });
 
     if (it != arriving_tiles.end()) {
@@ -124,6 +135,13 @@ void Finder::process_tiles() {
   }
 }
 
+bool Finder::last_couple(const Tile* tile_a, const Tile* tile_b) const {
+  bool a_is_first = tile_a->index() < tile_b->index();
+  const Tile* first = a_is_first ? tile_a : tile_b;
+  const Tile* last  = a_is_first ? tile_b : tile_a;
+  return (first->start_x() == 0) && (last->end_x() == this->maximum_width());
+}
+
 Finder::~Finder() {
   if (this->whole_tile) {
     delete this->whole_tile;  // last tile to be deleted (not owned by a cluster)

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/Finder.h

@@ -40,13 +40,14 @@ class Finder : public Poolable {
   std::mutex finders_mutex;
   std::map<std::string, double> reports;
   CpuTimer cpu_timer;
+  bool last_couple(const Tile* tile_a, const Tile* tile_b) const;
 
  protected:
   Queue<Tile*> tiles_;
   int maximum_width_;
   int height = 0;
   Tile* whole_tile = nullptr;
-  void process_tiles();
+  void process_tiles(bool deterministic = false);
 
  public:
   using Poolable::Poolable;

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/Merger.cpp

@@ -48,7 +48,7 @@ void Merger::add_tile(ProcessResult& result)
   }
 
   int end_x = this->current_x + result.width;
-  Tile* tile = new Tile(this, this->current_x, end_x, std::to_string(tiles_.size()), Benchmarks {0, 0});
+  Tile* tile = new Tile(this, this->current_x, end_x, std::to_string(tiles_.size()), tiles_.size(), Benchmarks {0, 0});
   tile->assign_raw_polygons(result.polygons, result.treemap);
   tiles_.queue_push(tile);
 

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/Tile.cpp

@@ -20,12 +20,14 @@
 class Shape;
 class Polyline;
 
-Tile::Tile(Finder *finder, int start_x, int end_x, std::string name, const Benchmarks& b)
+Tile::Tile(Finder *finder, int start_x, int end_x, std::string name, int index, const Benchmarks& b, int order)
 : finder(finder),
   start_x_(start_x),
   end_x_(end_x),
   name_(name),
-  benchmarks(b) {
+  index_(index),
+  benchmarks(b),
+  order_(order) {
   this->shapes_pool = new ShapePool();
   this->shapes_pool->set_owner(this);
   this->shapes_pools.push_back(this->shapes_pool);

data/ext/cpp_polygon_finder/PolygonFinder/src/polygon/finder/concurrent/Tile.h

@@ -29,11 +29,13 @@ class Tile {
   Finder *finder;
   int start_x_;
   int end_x_;
+  int index_;
+  int order_;
   std::string name_;
   std::vector<Shape*> shapes_;
 
  public:
-  Tile(Finder *finder, int start_x, int end_x, std::string name, const Benchmarks& b);
+  Tile(Finder *finder, int start_x, int end_x, std::string name, int index, const Benchmarks& b, int order = 0);
   virtual ~Tile();
   Tile *prev = nullptr;
   Tile *next = nullptr;
@@ -41,6 +43,8 @@ class Tile {
   Cluster *cluster = nullptr;
   int start_x() const { return start_x_; }
   int end_x() const { return end_x_; }
+  int index() const { return index_; }
+  int order() const { return order_; }
   std::string name() const { return name_; }
   const std::vector<Shape*>& shapes() const { return shapes_; }
   std::vector<Shape*>& shapes() { return shapes_; }

data/lib/contrek/finder/concurrent/cluster.rb

@@ -106,6 +106,8 @@ module Contrek
           start_x: @tiles.first.start_x,
           end_x: @tiles.last.end_x,
           benchmarks: {outer: tot_outer + past_tot_outer, inner: tot_inner + past_tot_inner},
+          index: @tiles.first.index / 2,
+          order: @tiles.first.order + 1,
           name: @tiles.first.name + @tiles.last.name
         )
 

data/lib/contrek/finder/concurrent/finder.rb

@@ -39,6 +39,7 @@ module Contrek
           x = 0
           current_versus = options[:versus]
           raise "Define versus!" if current_versus.nil?
+          raise ArgumentError, "Deterministic mode requires an even number of tiles!" if options[:deterministic] && @number_of_tiles.odd?
 
           @number_of_tiles.times do |tile_index|
             tile_end_x = (cw * (tile_index + 1)).to_i
@@ -62,7 +63,7 @@ module Contrek
                 finder: self,
                 start_x: payload[:tile_start_x],
                 end_x: payload[:tile_end_x],
-                name: payload[:tile_index].to_s
+                index: payload[:tile_index]
               )
               tile.initial_process!(finder)
               @tiles << tile
@@ -70,7 +71,7 @@ module Contrek
 
             x = tile_end_x - 1
           end
-          process_tiles!(bitmap, height: bitmap.h)
+          process_tiles!(bitmap, height: bitmap.h, deterministic: @options[:deterministic])
         end.real
       end
 
@@ -106,7 +107,12 @@ module Contrek
 
       private
 
-      def process_tiles!(bitmap, height:)
+      def last_couple?(tile_a, tile_b)
+        ordereds = [tile_a, tile_b].sort_by(&:index)
+        ordereds.first.start_x == 0 && ordereds.last.end_x == maximum_width
+      end
+
+      def process_tiles!(bitmap, height:, deterministic: false)
         arriving_tiles = []
         loop do
           tile = @tiles.pop
@@ -114,7 +120,17 @@ module Contrek
             @whole_tile = tile
             return
           end
-          if (twin_tile = arriving_tiles.find { |b| (b.start_x == (tile.end_x - 1)) || ((b.end_x - 1) == tile.start_x) })
+          twin_tile = arriving_tiles.find do |t|
+            is_adjacent = (t.start_x == (tile.end_x - 1)) || ((t.end_x - 1) == tile.start_x)
+            next false unless is_adjacent
+            if deterministic && !last_couple?(tile, t)
+              next false if tile.order != t.order
+              next false if [t.index, tile.index].min.odd?
+            end
+            true
+          end
+
+          if twin_tile
             cluster = Cluster.new(finder: self, height: height)
             if twin_tile.start_x == (tile.end_x - 1)
               cluster.add(tile)
@@ -126,13 +142,12 @@ module Contrek
             enqueue!(cluster: cluster) do |payload|
               merged_tile = payload[:cluster].merge_tiles!
               @tiles << merged_tile
-              # usefull external access to each merged_tile
-              @block&.call(merged_tile, bitmap)
+              @block&.call(merged_tile, bitmap) # usefull external access to each merged_tile
             end
             arriving_tiles.delete(twin_tile)
-            next
+          else
+            arriving_tiles << tile
           end
-          arriving_tiles << tile
         end
       end
     end

data/lib/contrek/finder/concurrent/merger.rb

@@ -35,7 +35,7 @@ module Contrek
           finder: self,
           start_x: @current_x,
           end_x: end_x,
-          name: @tiles.size.to_s
+          index: @tiles.size
         )
         tile.assign_raw_polygons!(result[:polygons])
 

data/lib/contrek/finder/concurrent/tile.rb

@@ -3,14 +3,16 @@
 module Contrek
   module Concurrent
     class Tile
-      attr_reader :start_x, :end_x, :benchmarks, :shapes, :name
+      attr_reader :start_x, :end_x, :benchmarks, :shapes, :name, :index, :order
       attr_accessor :prev, :next, :circular_next, :cluster
 
-      def initialize(finder:, start_x:, end_x:, name:, benchmarks: {})
+      def initialize(finder:, start_x:, end_x:, index:, name: nil, benchmarks: {}, order: 0)
         @finder = finder
         @start_x = start_x
         @end_x = end_x
-        @name = name
+        @index = index
+        @order = order
+        @name = name || index.to_s
         @prev = nil
         @next = nil
         @benchmarks = {outer: 0, inner: 0}.merge(benchmarks)

data/lib/contrek/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Contrek
-  VERSION = "1.3.9"
+  VERSION = "1.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: contrek
 version: !ruby/object:Gem::Version
-  version: 1.3.9
+  version: 1.4.0
 platform: ruby
 authors:
 - Emanuele Cesaroni