Add reproducible Simhash benchmark

Author: preciz

.formatter.exs

@@ -1,4 +1,4 @@
 # Used by "mix format"
 [
-  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+  inputs: ["{mix,.formatter}.exs", "{bench,config,lib,test}/**/*.{ex,exs}"]
 ]

CHANGELOG.md

@@ -8,6 +8,11 @@ Release dates are based on the [Hex.pm release history](https://hex.pm/packages/
 
 ## [Unreleased]
 
+### Changed
+
+- Replaced the historical Simhash performance claim with a packaged, reproducible
+  benchmark script using pinned Similarity, simhash-ex, and Benchee versions.
+
 ## [0.5.1] - 2026-08-23
 
 ### Changed

README.md

@@ -88,28 +88,25 @@ Similarity.sorensen_dice("this that", "just that")
 ```
 
 ## Performance
-Similarity.simhash is 2x faster than simhash-ex v1.1.0 package.
 
+The reproducible [Simhash benchmark](bench/simhash.exs) uses `Mix.install/1` to
+install pinned versions of Benchee, Similarity, and
+[simhash-ex](https://github.com/UniversalAvenue/simhash-ex). It verifies that both
+implementations return the same score before benchmarking them:
+
+```console
+$ elixir bench/simhash.exs
 ```
-Benchmark suite executing with the following configuration:
-warmup: 2 s
-time: 5 s
-memory time: 0 ns
-parallel: 1
-inputs: none specified
-Estimated total run time: 14 s
-
-Benchmarking simhash-ex...
-Benchmarking similarity.simhash...
-
-Name                         ips        average  deviation         median         99th %
-similarity.simhash        3.67 K      272.69 μs     ±6.50%      267.84 μs      353.05 μs
-simhash-ex                1.75 K      572.14 μs    ±12.31%      552.22 μs      781.02 μs
-
-Comparison:
-similarity.simhash        3.67 K
-simhash-ex                1.75 K - 2.10x slower +299.46 μs
-```
+
+On Linux with an AMD Ryzen 7 8845HS, Elixir 1.20.3, and Erlang/OTP 29.0.5:
+
+| Implementation | Average time | Throughput | Memory |
+| --- | ---: | ---: | ---: |
+| Similarity 0.5.1 | 55.80 μs | 17.92 K ips | 126.82 KB |
+| simhash-ex `e04aa01` | 143.60 μs | 6.96 K ips | 262.54 KB |
+
+For this input, Similarity was 2.57× faster and used 52% less memory. Results vary
+by hardware and runtime version.
 
 ## License
 

bench/simhash.exs

@@ -0,0 +1,29 @@
+Mix.install([
+  {:benchee, "== 1.5.1"},
+  {:similarity, "== 0.5.1"},
+  # simhash-ex is published as :simhash; this revision supports current Elixir.
+  {:simhash,
+   git: "https://github.com/UniversalAvenue/simhash-ex.git",
+   ref: "e04aa014e39ea2a7f53baf30f9d23c1e7cf6cd21"}
+])
+
+left = "pork belly jerky brisket tenderloin shank kevin spare ribs"
+right = "porchetta pork loin. Leberkas ball tip biltong, beef ribs"
+
+similarity_score = Similarity.simhash(left, right)
+simhash_ex_score = Simhash.similarity(left, right)
+
+unless similarity_score == simhash_ex_score do
+  raise "implementations returned different scores: " <>
+          "#{similarity_score} != #{simhash_ex_score}"
+end
+
+Benchee.run(
+  %{
+    "similarity 0.5.1" => fn -> Similarity.simhash(left, right) end,
+    "simhash-ex e04aa01" => fn -> Simhash.similarity(left, right) end
+  },
+  warmup: 2,
+  time: 5,
+  memory_time: 2
+)

mix.exs

@@ -37,6 +37,7 @@ defmodule Similarity.MixProject do
 
   defp package do
     [
+      files: ~w(lib bench .formatter.exs mix.exs README.md LICENSE CHANGELOG.md),
       maintainers: ["Barna Kovacs"],
       licenses: ["MIT"],
       links: %{"GitHub" => "https://github.com/preciz/similarity"}