feat: add grid and triangle hex graph generation functions with tagging support

Author: elecbug

v2/graph/node.go

@@ -12,13 +12,15 @@ type Weight float64
 type Node struct {
 	ID    NodeID            // ID is the unique identifier for the node.
 	edges map[NodeID]Weight // Edges maps the destination NodeID to the weight of the edge.
+	tags  map[string]string // Tags can hold additional metadata about the node.
 }
 
 // NewNode creates a new node with the given ID.
 func NewNode(id NodeID) *Node {
 	return &Node{
 		ID:    id,
 		edges: make(map[NodeID]Weight),
+		tags:  make(map[string]string),
 	}
 }
 
@@ -60,6 +62,50 @@ func (n *Node) edgeWeight(to NodeID) (Weight, error) {
 	return weight, nil
 }
 
+/* Tagging */
+
+// AddTag adds a key-value pair as a tag to the node.
+// It returns an error if a tag with the same key already exists.
+func (n *Node) AddTag(key, value string) error {
+	if n.HasTag(key) {
+		return fmt.Errorf("tag with key %s already exists", key)
+	}
+
+	n.tags[key] = value
+	return nil
+}
+
+// UpdateTag updates the value of an existing tag on the node.
+// If the tag does not exist, it will be added.
+func (n *Node) UpdateTag(key, value string) {
+	n.tags[key] = value
+}
+
+// RemoveTag removes a tag from the node by its key. It returns an error if the tag does not exist.
+func (n *Node) RemoveTag(key string) error {
+	if _, exists := n.tags[key]; !exists {
+		return fmt.Errorf("tag with key %s does not exist", key)
+	}
+
+	delete(n.tags, key)
+	return nil
+}
+
+// HasTag checks if a tag with the specified key exists on the node.
+func (n *Node) HasTag(key string) bool {
+	_, exists := n.tags[key]
+	return exists
+}
+
+// Tag retrieves the value of a tag by its key. It returns an error if the tag does not exist.
+func (n *Node) Tag(key string) (string, bool) {
+	value, exists := n.tags[key]
+	if !exists {
+		return "", false
+	}
+	return value, true
+}
+
 /* Connectivity */
 
 // Neighbors returns a slice of NodeIDs representing the neighbors of this node.

v2/graph/standard/common.go

@@ -14,6 +14,8 @@ type WeightedFunc func(from, to graph.NodeID) *graph.Weight
 type GraphType string
 
 const (
+	Grid            GraphType = "grid"
+	TriangleHex     GraphType = "triangle_hex"
 	ErdosRenyi      GraphType = "erdos_renyi"
 	BarabasiAlbert  GraphType = "barabasi_albert"
 	WattsStrogatz   GraphType = "watts_strogatz"
@@ -52,6 +54,26 @@ func Unweighted() WeightedFunc {
 // StandardGraph generates a graph based on the provided configuration. It supports various graph types and parameters.
 func StandardGraph(seed int, directed bool, weightFunc WeightedFunc, config GraphConfig) (*graph.Graph, error) {
 	switch config.Type {
+	case Grid:
+		rows, ok := config.Params["rows"].(int)
+		if !ok {
+			return nil, fmt.Errorf("invalid parameter 'rows' for grid graph")
+		}
+		cols, ok := config.Params["cols"].(int)
+		if !ok {
+			return nil, fmt.Errorf("invalid parameter 'cols' for grid graph")
+		}
+		torus, ok := config.Params["torus"].(bool)
+		if !ok {
+			return nil, fmt.Errorf("invalid parameter 'torus' for grid graph")
+		}
+		return GridGraph(seed, directed, weightFunc, rows, cols, torus)
+	case TriangleHex:
+		edge, ok := config.Params["edge"].(int)
+		if !ok {
+			return nil, fmt.Errorf("invalid parameter 'edge' for triangle hex graph")
+		}
+		return TriangleHexGraph(seed, directed, weightFunc, edge)
 	case ErdosRenyi:
 		n, ok := config.Params["n"].(int)
 		if !ok {

v2/graph/standard/grid.go

@@ -0,0 +1,74 @@
+package standard
+
+import (
+	"fmt"
+
+	"github.com/elecbug/netkit/v2/graph"
+)
+
+// GridGraph generates a grid graph with the specified number of rows and columns.
+// If torus is true, the graph will wrap around at the edges, creating a toroidal structure.
+func GridGraph(seed int, directed bool, weightFunc WeightedFunc, rows, cols int, torus bool) (*graph.Graph, error) {
+	if weightFunc == nil {
+		weightFunc = Unweighted()
+	}
+	if rows < 0 || cols < 0 {
+		return nil, fmt.Errorf("rows and cols must be non-negative")
+	}
+
+	g := graph.New(directed, true)
+
+	nodeID := func(row, col int) graph.NodeID {
+		return graph.NodeID(fmt.Sprintf("%d", row*cols+col))
+	}
+
+	for i := 0; i < rows; i++ {
+		for j := 0; j < cols; j++ {
+			g.AddNode(nodeID(i, j))
+			if node, err := g.Node(nodeID(i, j)); err != nil {
+				return nil, fmt.Errorf("failed to retrieve node: %w", err)
+			} else {
+				node.AddTag("x", fmt.Sprintf("%d", i))
+				node.AddTag("y", fmt.Sprintf("%d", j))
+			}
+		}
+	}
+
+	for i := 0; i < rows; i++ {
+		for j := 0; j < cols; j++ {
+			id := nodeID(i, j)
+
+			if torus {
+				if rows > 2 {
+					ni := (i + 1) % rows
+					if err := g.AddEdge(id, nodeID(ni, j), weightFunc(id, nodeID(ni, j))); err != nil {
+						return nil, fmt.Errorf("failed to add edge: %w", err)
+					}
+				}
+			} else {
+				if i < rows-1 {
+					if err := g.AddEdge(id, nodeID(i+1, j), weightFunc(id, nodeID(i+1, j))); err != nil {
+						return nil, fmt.Errorf("failed to add edge: %w", err)
+					}
+				}
+			}
+
+			if torus {
+				if cols > 2 {
+					nj := (j + 1) % cols
+					if err := g.AddEdge(id, nodeID(i, nj), weightFunc(id, nodeID(i, nj))); err != nil {
+						return nil, fmt.Errorf("failed to add edge: %w", err)
+					}
+				}
+			} else {
+				if j < cols-1 {
+					if err := g.AddEdge(id, nodeID(i, j+1), weightFunc(id, nodeID(i, j+1))); err != nil {
+						return nil, fmt.Errorf("failed to add edge: %w", err)
+					}
+				}
+			}
+		}
+	}
+
+	return g, nil
+}

v2/graph/standard/random_geometric.go

@@ -33,6 +33,12 @@ func RandomGeometricGraph(seed int, directed bool, weightFunc WeightedFunc, n in
 		if err := g.AddNode(id); err != nil {
 			return nil, fmt.Errorf("failed to add node: %w", err)
 		}
+		if node, err := g.Node(id); err != nil {
+			return nil, fmt.Errorf("failed to retrieve node: %w", err)
+		} else {
+			node.AddTag("x", fmt.Sprintf("%f", rr.Float64()))
+			node.AddTag("y", fmt.Sprintf("%f", rr.Float64()))
+		}
 		positions[id] = point{
 			x: rr.Float64(),
 			y: rr.Float64(),

v2/graph/standard/standart_graph_test.go

@@ -6,11 +6,14 @@ import (
 	"sync"
 	"testing"
 
+	"github.com/elecbug/netkit/v2/graph"
 	"github.com/elecbug/netkit/v2/graph/standard"
 )
 
 func TestStandardGraph(t *testing.T) {
 	fmt.Println("Test Standard Graph Generation")
+	testGridGraph(t)
+	testTriangleHexGraph(t)
 	testBarabasiAlbertGraph(t)
 	testErdosRenyiGraph(t)
 	testRandomGeometricGraph(t)
@@ -553,6 +556,104 @@ func testWattsStrogatzGraph(t *testing.T) {
 	}
 }
 
+// testGridGraph tests the grid graph generation function.
+func testGridGraph(t *testing.T) {
+	fmt.Println("- Test Grid Graph")
+
+	rows := 10
+	cols := 10
+	torus := false
+
+	g, err := standard.GridGraph(0, false, standard.Unweighted(), rows, cols, torus)
+	if err != nil {
+		t.Fatalf("failed to generate grid graph: %v", err)
+	}
+
+	expectedNodes := rows * cols
+	if len(g.Nodes()) != expectedNodes {
+		t.Errorf("expected %d nodes, got %d", expectedNodes, len(g.Nodes()))
+	}
+
+	for i := 0; i < rows; i++ {
+		for j := 0; j < cols; j++ {
+			id := graph.NodeID(fmt.Sprintf("%d", i*cols+j))
+			node, err := g.Node(id)
+			if err != nil {
+				t.Errorf("failed to get node: %v", err)
+				continue
+			}
+
+			x, okX := node.Tag("x")
+			y, okY := node.Tag("y")
+			if !okX || !okY {
+				t.Errorf("node %s is missing tags", id)
+				continue
+			}
+
+			if x != fmt.Sprintf("%d", i) || y != fmt.Sprintf("%d", j) {
+				t.Errorf("node %s has incorrect tags: x=%s, y=%s", id, x, y)
+			}
+
+			expectedDegree := 4
+			if i == 0 || i == rows-1 {
+				expectedDegree--
+			}
+			if j == 0 || j == cols-1 {
+				expectedDegree--
+			}
+
+			if node.Degree() != expectedDegree {
+				t.Errorf("node %s has degree %d, expected %d", id, node.Degree(), expectedDegree)
+			}
+		}
+	}
+}
+
+// testTriangleHexGraph tests the triangle hex graph generation function.
+func testTriangleHexGraph(t *testing.T) {
+	fmt.Println("- Test Triangle Hex Graph")
+
+	edge := 3
+
+	g, err := standard.TriangleHexGraph(0, false, standard.Unweighted(), edge)
+	if err != nil {
+		t.Fatalf("failed to generate triangle hex graph: %v", err)
+	}
+
+	expectedNodes := 3*edge*(edge+1)/2 + 1
+	if len(g.Nodes()) != expectedNodes {
+		t.Errorf("expected %d nodes, got %d", expectedNodes, len(g.Nodes()))
+	}
+
+	for i := 0; i < expectedNodes; i++ {
+		nodeID := graph.NodeID(fmt.Sprintf("%d", i))
+
+		node, err := g.Node(nodeID)
+		if err != nil {
+			t.Errorf("failed to get node: %v", err)
+			continue
+		}
+
+		q, okQ := node.Tag("q")
+		r, okR := node.Tag("r")
+		if !okQ || !okR {
+			t.Errorf("node %s is missing tags", nodeID)
+			continue
+		}
+
+		qInt := 0
+		rInt := 0
+		fmt.Sscanf(q, "%d", &qInt)
+		fmt.Sscanf(r, "%d", &rInt)
+
+		expectedDegree := degreeOfTriangleHex(qInt, rInt, edge)
+
+		if node.Degree() != expectedDegree {
+			t.Errorf("node %s (q=%d, r=%d) has degree %d, expected %d", nodeID, qInt, rInt, node.Degree(), expectedDegree)
+		}
+	}
+}
+
 // testGenerateFromConfig tests the StandardGraph function with various configurations.
 func testGenerateFromConfig(t *testing.T) {
 	fmt.Println("- Test StandardGraph with Config")
@@ -673,3 +774,37 @@ func poissonLowerExtreme(n int, lambda float64) int {
 
 	return -1
 }
+
+// degreeOfTriangleHex calculates the degree of a node in the triangle hex graph based on its q and r coordinates and the edge length.
+func degreeOfTriangleHex(q, r, n int) int {
+	dirs := [][2]int{
+		{1, 0},
+		{-1, 0},
+		{0, 1},
+		{0, -1},
+		{1, -1},
+		{-1, 1},
+	}
+
+	degree := 0
+
+	for _, d := range dirs {
+		nq := q + d[0]
+		nr := r + d[1]
+
+		if exists(nq, nr, n) {
+			degree++
+		}
+	}
+
+	return degree
+}
+
+// exists checks if the coordinates (q, r) are valid for a node in the triangle hex graph with edge length n.
+func exists(q, r, n int) bool {
+	limit := n - 1
+
+	return q >= -limit && q <= limit &&
+		r >= -limit && r <= limit &&
+		q+r >= -limit && q+r <= limit
+}