test: ✅ add benchmarking setup to compare against kyroy/kdtree

The benchmarking setup I've added compares the API performance between my library and the `kyroy/kdtree` library, providing valuable insights into the performance characteristics of each one.

The APIs compared against each other are listed in the table below:

| S. No. | rishitc/go-kd-tree  | kyroy/kdtree |
|:------:|---------------------|--------------|
|    1   | NewKDTreeWithValues | New          |
|    2   | RangeSearch         | RangeSearch  |
|    3   | Values              | Points       |
|    4   | Insert              | Insert       |
|    5   | Remove              | Remove       |
|    6   | Balance             | Balance      |
|    7   | KNN                 | KNN          |

Certain APIs, such as `String,` have not been benchmarked because they are not performance-critical and are primarily used for debugging and educational purposes. Additionally, there is no standard way of representing a tree as a string, so the benchmark results are heavily dependent on your library's chosen format of data representation as a string.

In this benchmarking setup, we no longer generate the benchmarking dataset on the fly every time we benchmark. Instead, we generate the benchmarking dataset once and store it in a `.csv` file (if it does not already exist), which is later read and stored in memory before running any benchmarks.
This new approach significantly reduces the time taken to run a benchmark.

To simplify running the benchmarking setup, which uses build flags, I've included a template command in the file `internal/benchmarks/README.md` that can be easily modified and used to run the benchmarks locally.

Finally, I have removed the file used to benchmark old and new approaches for implementing different APIs.

Author: rishitc

.gitignore

@@ -57,4 +57,10 @@ Temporary Items
 # iCloud generated files
 *.icloud
 
-# End of https://www.toptal.com/developers/gitignore/api/go,macos
+# End of https://www.toptal.com/developers/gitignore/api/go,macos
+
+# Ignore generated benchmarking dataset files
+benchmarks/dataset/*.csv
+
+# Ignore pkg folder and its contents
+/pkg/*

go.mod

@@ -4,12 +4,14 @@ go 1.22.5
 
 require (
 	github.com/google/flatbuffers v24.3.25+incompatible
+	github.com/kyroy/kdtree v0.0.0-20200419114247-70830f883f1d
 	github.com/stretchr/testify v1.9.0
 	golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56
 )
 
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/kyroy/priority-queue v0.0.0-20180327160706-6e21825e7e0c // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,14 +1,24 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/google/flatbuffers v24.3.25+incompatible h1:CX395cjN9Kke9mmalRoL3d81AtFUxJM+yDthflgJGkI=
 github.com/google/flatbuffers v24.3.25+incompatible/go.mod h1:1AeVuKshWv4vARoZatz6mlQ0JxURH0Kv5+zNeJKJCa8=
+github.com/jupp0r/go-priority-queue v0.0.0-20160601094913-ab1073853bde h1:+5PMaaQtDUwOcJIUlmX89P0J3iwTvErTmyn5WghzXAQ=
+github.com/jupp0r/go-priority-queue v0.0.0-20160601094913-ab1073853bde/go.mod h1:RDgD/dfPmIwFH0qdUOjw71HjtWg56CtyLIoHL+R1wJw=
+github.com/kyroy/kdtree v0.0.0-20200419114247-70830f883f1d h1:1n5M/49q9H6QtNJiiVL/W5mqgT1UdlGQ7oLP+DkJ1vs=
+github.com/kyroy/kdtree v0.0.0-20200419114247-70830f883f1d/go.mod h1:6oJGQK7VSg3RxSQ7QspgqpCmKjIbAslgT2wBXbFJUZw=
+github.com/kyroy/priority-queue v0.0.0-20180327160706-6e21825e7e0c h1:1c7+XOOGQ19cXjZ1Ss/irljQxgPvb+8z+jNEprCXl20=
+github.com/kyroy/priority-queue v0.0.0-20180327160706-6e21825e7e0c/go.mod h1:R477L6j2/dUcE0q0aftk0kR5Xt93W7g1066AodcJhEo=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 h1:2dVuKD2vS7b0QIHQbpyTISPd0LeHDbnYEryqj5Q1ug8=
 golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56/go.mod h1:M4RDyNAINzryxdtnbRXRL/OHtkFuWGRjvuhBJpk2IlY=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/benchmarks/README.md

@@ -0,0 +1,10 @@
+# Benchmarking Guide
+
+## How to run the benchmarks?
+
+* The benchmarks can be run by using the below command:
+  * Ensure to fill in the placeholder values in the command with appropriate values before running it.
+
+```bash
+go test -benchtime=100x -tags trace -benchmem -run=^$ -bench ^<benchmark_function_name>$ github.com/rishitc/go-kd-tree/benchmarks/<competitor_folder_name>
+```

internal/benchmarks/dataset/2d_generator.go

@@ -0,0 +1,42 @@
+//go:build trace
+
+package dataset
+
+import (
+	"encoding/csv"
+	"fmt"
+	"math/rand"
+	"os"
+	"strconv"
+)
+
+func Trace2DGenerator(tracePath string) {
+	// Open the file for writing
+	file, err := os.Create(tracePath)
+	if err != nil {
+		panic(err)
+	}
+	defer file.Close()
+
+	// Create a CSV writer
+	writer := csv.NewWriter(file)
+	defer writer.Flush()
+
+	// Create a map to store unique pairs
+	uniquePairs := make(map[string]struct{})
+
+	// Generate unique pairs
+	for len(uniquePairs) < 1000000 {
+		x := rand.Intn(1000000)
+		y := rand.Intn(1000000)
+		pair := fmt.Sprintf("%d,%d", x, y)
+
+		if _, exists := uniquePairs[pair]; !exists {
+			uniquePairs[pair] = struct{}{}
+			err := writer.Write([]string{strconv.Itoa(x), strconv.Itoa(y)})
+			if err != nil {
+				panic(err)
+			}
+		}
+	}
+}

internal/benchmarks/go-kd-tree/go-kd-tree_test.go

@@ -0,0 +1,151 @@
+//go:test trace
+package gokdtree_test
+
+import (
+	"errors"
+	"math/rand/v2"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	kdtree "github.com/rishitc/go-kd-tree"
+	"github.com/rishitc/go-kd-tree/internal/benchmarks/dataset"
+	"github.com/rishitc/go-kd-tree/internal/types"
+)
+
+const dimensions2DCount = 2
+
+var (
+	tracePath = filepath.Join("..", "dataset", "input_2d_trace.csv")
+	trace     []types.Tensor2D
+)
+
+func init() {
+	if _, err := os.Stat(tracePath); errors.Is(err, os.ErrNotExist) {
+		dataset.Trace2DGenerator(tracePath)
+	}
+	trace, _ = ReadTensor2DTrace(tracePath)
+}
+
+func BenchmarkGoKDTreeCreation(b *testing.B) {
+	var tree *kdtree.KDTree[types.Tensor2D]
+	for i := 0; i < b.N; i++ {
+		tree = kdtree.NewKDTreeWithValues(dimensions2DCount, trace)
+	}
+	runtime.KeepAlive(tree)
+}
+
+func BenchmarkGoKDTreeInsert(b *testing.B) {
+	var tree *kdtree.KDTree[types.Tensor2D]
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		t := kdtree.NewKDTreeWithValues(dimensions2DCount, trace[:len(trace)-1])
+		e := trace[len(trace)-1]
+		b.StartTimer()
+
+		t.Insert(e)
+	}
+	runtime.KeepAlive(tree)
+}
+
+func BenchmarkGoKDTreeRemove(b *testing.B) {
+	var point types.Tensor2D
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		tree := kdtree.NewKDTreeWithValues(dimensions2DCount, trace)
+		// Select random element to remove
+		ti := rand.IntN(len(trace))
+		e := trace[ti]
+		b.StartTimer()
+
+		tree.Remove(e)
+	}
+	runtime.KeepAlive(point)
+}
+
+func BenchmarkGoKDTreeKNN(b *testing.B) {
+	var points []types.Tensor2D
+	tree := kdtree.NewKDTreeWithValues(dimensions2DCount, trace)
+	b.ResetTimer()
+
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		ti := rand.IntN(len(trace))
+		e := trace[ti]
+		b.StartTimer()
+
+		points = tree.KNN(e, 100)
+	}
+	runtime.KeepAlive(points)
+}
+
+func BenchmarkGoKDTreeValues(b *testing.B) {
+	var points []types.Tensor2D
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		tree := kdtree.NewKDTreeWithValues(dimensions2DCount, trace)
+		b.StartTimer()
+
+		points = tree.Values()
+	}
+	runtime.KeepAlive(points)
+}
+
+func BenchmarkGoKDTreeRangeSearch(b *testing.B) {
+	var points []types.Tensor2D
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		tree := kdtree.NewKDTreeWithValues(dimensions2DCount, trace)
+		b.StartTimer()
+
+		points = tree.RangeSearch(func(td types.Tensor2D, i int) kdtree.RelativePosition {
+			const (
+				xs = -1
+				xe = 801
+				ys = 0
+				ye = 251
+			)
+			switch i {
+			case -1:
+				if x, y := td[0], td[1]; xs <= x && x < xe && ys <= y && y < ye {
+					return kdtree.InRange
+				}
+				return kdtree.AfterRange
+			case 0:
+				if x := td[0]; x < xs {
+					return kdtree.BeforeRange
+				} else if x >= xe {
+					return kdtree.AfterRange
+				} else {
+					return kdtree.InRange
+				}
+			case 1:
+				if y := td[1]; y < ys {
+					return kdtree.BeforeRange
+				} else if y >= ye {
+					return kdtree.AfterRange
+				} else {
+					return kdtree.InRange
+				}
+			}
+			return kdtree.AfterRange
+		})
+	}
+	runtime.KeepAlive(points)
+}
+
+func BenchmarkGoKDTreeBalance(b *testing.B) {
+	var tree *kdtree.KDTree[types.Tensor2D]
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		tree = kdtree.NewKDTreeWithValues(dimensions2DCount, []types.Tensor2D{})
+		for _, e := range trace {
+			tree.Insert(e)
+		}
+		b.StartTimer()
+
+		tree.Balance()
+	}
+	runtime.KeepAlive(tree)
+}

internal/benchmarks/go-kd-tree/utils_test.go

@@ -0,0 +1,17 @@
+package gokdtree_test
+
+import (
+	"github.com/rishitc/go-kd-tree/internal/benchmarks"
+	"github.com/rishitc/go-kd-tree/internal/types"
+)
+
+func ReadTensor2DTrace(filename string) ([]types.Tensor2D, error) {
+	trace, err := benchmarks.Read2DTrace(filename)
+	tensorTrace := make([]types.Tensor2D, 0, len(trace))
+
+	for _, e := range trace {
+		tensorTrace = append(tensorTrace, types.Tensor2D(e))
+	}
+
+	return tensorTrace, err
+}

internal/benchmarks/kyro/kyro_kdtree_bench_test.go

@@ -0,0 +1,118 @@
+//go:test trace
+package kyro_test
+
+import (
+	"errors"
+	"math/rand/v2"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/kyroy/kdtree"
+	"github.com/kyroy/kdtree/kdrange"
+	"github.com/rishitc/go-kd-tree/internal/benchmarks/dataset"
+)
+
+var (
+	tracePath = filepath.Join("..", "dataset", "input_2d_trace.csv")
+	trace     []kdtree.Point
+)
+
+func init() {
+	if _, err := os.Stat(tracePath); errors.Is(err, os.ErrNotExist) {
+		dataset.Trace2DGenerator(tracePath)
+	}
+	trace, _ = ReadPoint2DTrace(tracePath)
+}
+
+func BenchmarkKyroKDTreeCreation(b *testing.B) {
+	var tree *kdtree.KDTree
+	for i := 0; i < b.N; i++ {
+		tree = kdtree.New(trace)
+	}
+	runtime.KeepAlive(tree)
+}
+
+func BenchmarkKyroKDTreeInsert(b *testing.B) {
+	var tree *kdtree.KDTree
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		t := kdtree.New(trace[:len(trace)-1])
+		e := trace[len(trace)-1]
+		b.StartTimer()
+
+		t.Insert(e)
+	}
+	runtime.KeepAlive(tree)
+}
+
+func BenchmarkKyroKDTreeRemove(b *testing.B) {
+	var point kdtree.Point
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		tree := kdtree.New(trace)
+		// Select random element to remove
+		ti := rand.IntN(len(trace))
+		e := trace[ti]
+		b.StartTimer()
+
+		point = tree.Remove(e)
+	}
+	runtime.KeepAlive(point)
+}
+
+func BenchmarkKyroKDTreeKNN(b *testing.B) {
+	var points []kdtree.Point
+	tree := kdtree.New(trace)
+	b.ResetTimer()
+
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		ti := rand.IntN(len(trace))
+		e := trace[ti]
+		b.StartTimer()
+
+		points = tree.KNN(e, 100)
+	}
+	runtime.KeepAlive(points)
+}
+
+func BenchmarkKyroKDTreePoints(b *testing.B) {
+	var points []kdtree.Point
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		tree := kdtree.New(trace)
+		b.StartTimer()
+
+		points = tree.Points()
+	}
+	runtime.KeepAlive(points)
+}
+
+func BenchmarkKyroKDTreeRangeSearch(b *testing.B) {
+	var points []kdtree.Point
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		tree := kdtree.New(trace)
+		b.StartTimer()
+
+		points = tree.RangeSearch(kdrange.New(-1, 800, 0, 250))
+	}
+	runtime.KeepAlive(points)
+}
+
+func BenchmarkKyroKDTreeBalance(b *testing.B) {
+	var tree *kdtree.KDTree
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		tree = kdtree.New([]kdtree.Point{})
+		for _, e := range trace {
+			tree.Insert(e)
+		}
+		b.StartTimer()
+
+		tree.Balance()
+	}
+	runtime.KeepAlive(tree)
+}