Add persistence

Solved #3

Author: ammario

README.md

@@ -60,6 +60,40 @@ And, if you're struggling with excess memory usage, consider:
 * Reducing $m_L$ a.k.a `Graph.Ml` (the level generation parameter)
 
 
-## Roadmap
+## Persistence
 
-- [ ] [#3](https://github.com/coder/hnsw/issues/3) Persistence / serialization
+While all graph operations are in-memory, `hnsw` provides facilities for loading/saving from persistent storage.
+
+For an `io.Reader`/`io.Writer` interface use `Graph.Export` and `Graph.Import`.
+
+If you're storing within a filesystem, you can use the more convenient `SavedGraph` instead:
+
+```go
+path := "some.graph"
+g1, err := LoadSavedGraph[hnsw.Vector](path)
+if err != nil {
+    panic(err)
+}
+// Insert some vectors
+for i := 0; i < 128; i++ {
+    g1.Add(MakeVector(strconv.Itoa(i), []float32{float32(i)}))
+}
+
+// Save to disk
+err = g1.Save()
+if err != nil {
+    panic(err)
+}
+
+// Later...
+// g2 is a copy of g1
+g2, err := LoadSavedGraph[Vector](path)
+if err != nil {
+    panic(err)
+}
+```
+
+See more:
+* [Export](https://pkg.go.dev/github.com/coder/hnsw#Graph.Export)
+* [Import](https://pkg.go.dev/github.com/coder/hnsw#Graph.Import)
+* [SavedGraph](https://pkg.go.dev/github.com/coder/hnsw#SavedGraph)

analyzer.go

@@ -17,16 +17,16 @@ func (a *Analyzer[T]) Height() int {
 func (a *Analyzer[T]) Connectivity() []float64 {
 	var layerConnectivity []float64
 	for _, layer := range a.Graph.layers {
-		if len(layer.nodes) == 0 {
+		if len(layer.Nodes) == 0 {
 			continue
 		}
 
 		var sum float64
-		for _, node := range layer.nodes {
+		for _, node := range layer.Nodes {
 			sum += float64(len(node.neighbors))
 		}
 
-		layerConnectivity = append(layerConnectivity, sum/float64(len(layer.nodes)))
+		layerConnectivity = append(layerConnectivity, sum/float64(len(layer.Nodes)))
 	}
 
 	return layerConnectivity
@@ -36,7 +36,7 @@ func (a *Analyzer[T]) Connectivity() []float64 {
 func (a *Analyzer[T]) Topography() []int {
 	var topography []int
 	for _, layer := range a.Graph.layers {
-		topography = append(topography, len(layer.nodes))
+		topography = append(topography, len(layer.Nodes))
 	}
 	return topography
 }

distance.go

@@ -1,6 +1,9 @@
 package hnsw
 
-import "math"
+import (
+	"math"
+	"reflect"
+)
 
 // DistanceFunc is a function that computes the distance between two vectors.
 type DistanceFunc func(a, b []float32) float32
@@ -34,3 +37,26 @@ func EuclideanDistance(a, b []float32) float32 {
 	}
 	return float32(math.Sqrt(float64(sum)))
 }
+
+var distanceFuncs = map[string]DistanceFunc{
+	"euclidean": EuclideanDistance,
+	"cosine":    CosineDistance,
+}
+
+func distanceFuncToName(fn DistanceFunc) (string, bool) {
+	for name, f := range distanceFuncs {
+		fnptr := reflect.ValueOf(fn).Pointer()
+		fptr := reflect.ValueOf(f).Pointer()
+		if fptr == fnptr {
+			return name, true
+		}
+	}
+	return "", false
+}
+
+// RegisterDistanceFunc registers a distance function with a name.
+// A distance function must be registered here before a graph can be
+// exported and imported.
+func RegisterDistanceFunc(name string, fn DistanceFunc) {
+	distanceFuncs[name] = fn
+}