fix(Edge): make equals/hashCode order-sensitive for directed-graph safety

The previous Edge.equals/hashCode (commit 11acb09) treated (v1, v2) and
(v2, v1) as the same edge to model undirected semantics. That made it
impossible to add both directions of an edge to a JUNG
DirectedSparseGraph: JUNG's addEdge calls containsEdge(e) which delegates
to Edge.equals, sees the reverse as already present, and throws
IllegalArgumentException ("edge already exists with endpoints <A, B> and
cannot be added with endpoints <B, A>").

This caused 17 pre-existing test failures across the directed-graph
analyzers (CycleAnalyzer, StronglyConnectedComponentsAnalyzer,
TopologicalSortAnalyzer, GraphTemporalDynamicsEngine).

Changes
- Edge.equals: order-sensitive on (vertex1, vertex2), still checks type
  and weight, still ignores label.
- Edge.hashCode: consistent with the new equals (order-sensitive).
- New Edge.equalsUndirected(Edge): preserves the legacy symmetric
  comparison for callers that want unordered-pair semantics. Use it
  explicitly when modeling undirected relationships on top of the
  standard equals contract.
- Class javadoc updated to reflect ordered-pair identity.

Tests
- 15 new EdgeTest cases covering reflexivity, label-exclusion,
  order-sensitivity (regression guard), null/foreign-type handling,
  hashCode stability, equalsUndirected behavior, and a direct
  DirectedSparseGraph integration test that both directions can coexist.
- GraphTemporalDynamicsEngineTest.createGraph: dedupe undirected edges
  via findEdge so test fixtures stay simple graphs (the old helper
  relied on the bug to silently swallow duplicates).
- testDegreeEntropyIncreases: rebuilt the third snapshot with distinct
  edges (the previous version contained duplicate {A,D} pairs that
  collapsed under simple-graph semantics).

Net effect on mvn test: 18 fewer failing tests (54 -> 36) with no
new regressions; build still has 29F/8E of unrelated pre-existing
failures (force-directed layout stack overflow, graph-labeling AIOOBE,
shortest-path zero-weight handling, etc.).

Author: sauravbhattacharya001

Gvisual/src/gvisual/Edge.java

@@ -18,9 +18,12 @@
  *       {@code sg} (study group). See {@link EdgeType} for the full
  *       palette and metadata.</li>
  *   <li>Two endpoint identifiers ({@link #getVertex1()} and
- *       {@link #getVertex2()}). The edge is treated as <b>undirected</b>:
- *       {@code (v1, v2)} equals {@code (v2, v1)} for {@link #equals(Object)}
- *       and {@link #hashCode()} purposes.</li>
+ *       {@link #getVertex2()}). The endpoint pair is treated as
+ *       <b>ordered</b> for {@link #equals(Object)} / {@link #hashCode()}
+ *       so the class can be used safely in directed graphs (where
+ *       {@code A->B} and {@code B->A} are distinct edges). For
+ *       undirected/symmetric comparisons, use
+ *       {@link #equalsUndirected(Edge)}.</li>
  *   <li>A scalar {@link #getWeight() weight} (typically interaction
  *       intensity — frequency × duration).</li>
  *   <li>An optional human-readable {@link #getLabel() label}.</li>
@@ -215,8 +218,21 @@ public boolean isActiveDuring(long start, long end)
     }
 
     /**
-     * Two Edges are equal if they connect the same vertices (in either order),
-     * have the same type, and the same weight.
+     * Two Edges are equal if they have the same endpoints <em>in the same
+     * order</em> ({@code vertex1} and {@code vertex2}), the same type, and
+     * the same weight.
+     *
+     * <p><b>History:</b> previously this method treated {@code (v1, v2)}
+     * and {@code (v2, v1)} as equal in an attempt to model undirected
+     * semantics. That made it impossible to put an {@code Edge} into a
+     * {@code DirectedSparseGraph} alongside its reverse: JUNG's
+     * {@code containsEdge(e)} (which calls {@code Edge#equals}) reported
+     * the reverse edge as already present and {@code addEdge} threw
+     * {@code IllegalArgumentException}. The directed-graph use-cases
+     * (strongly connected components, topological sort, cycle analysis,
+     * temporal dynamics, etc.) are now first-class in the codebase, so
+     * {@code equals} is order-sensitive. Callers that want the legacy
+     * undirected comparison should use {@link #equalsUndirected(Edge)}.
      */
     @Override
     public boolean equals(Object obj)
@@ -226,7 +242,26 @@ public boolean equals(Object obj)
         Edge other = (Edge) obj;
         if (Float.compare(weight, other.weight) != 0) return false;
         if (!java.util.Objects.equals(edgeType, other.edgeType)) return false;
-        // Undirected: (v1,v2) == (v2,v1)
+        return java.util.Objects.equals(vertex1, other.vertex1)
+            && java.util.Objects.equals(vertex2, other.vertex2);
+    }
+
+    /**
+     * Returns {@code true} if this edge connects the same pair of
+     * vertices as {@code other} in <em>either</em> order, with the same
+     * type and weight. Useful when modeling undirected relationships on
+     * top of the standard {@link #equals(Object)} contract.
+     *
+     * @param other the edge to compare against; may be {@code null}
+     * @return true if both edges share an unordered endpoint pair, type,
+     *         and weight
+     */
+    public boolean equalsUndirected(Edge other)
+    {
+        if (this == other) return true;
+        if (other == null) return false;
+        if (Float.compare(weight, other.weight) != 0) return false;
+        if (!java.util.Objects.equals(edgeType, other.edgeType)) return false;
         boolean sameOrder = java.util.Objects.equals(vertex1, other.vertex1)
                          && java.util.Objects.equals(vertex2, other.vertex2);
         boolean reverseOrder = java.util.Objects.equals(vertex1, other.vertex2)
@@ -235,16 +270,18 @@ public boolean equals(Object obj)
     }
 
     /**
-     * Hash code consistent with {@link #equals}: order-independent on vertices.
+     * Hash code consistent with {@link #equals(Object)}: order-sensitive
+     * on the endpoint pair.
      */
     @Override
     public int hashCode()
     {
-        // Use addition so vertex order doesn't matter
-        int vertexHash = (vertex1 == null ? 0 : vertex1.hashCode())
-                       + (vertex2 == null ? 0 : vertex2.hashCode());
-        return 31 * (31 * vertexHash + (edgeType == null ? 0 : edgeType.hashCode()))
-             + Float.floatToIntBits(weight);
+        int h = 1;
+        h = 31 * h + (vertex1 == null ? 0 : vertex1.hashCode());
+        h = 31 * h + (vertex2 == null ? 0 : vertex2.hashCode());
+        h = 31 * h + (edgeType == null ? 0 : edgeType.hashCode());
+        h = 31 * h + Float.floatToIntBits(weight);
+        return h;
     }
 
     /**

Gvisual/test/gvisual/EdgeTest.java

@@ -143,8 +143,149 @@ public void testVerticesWithSpecialCharacters() {
 
     @Test
     public void testSelfLoop() {
-        // Edge class doesn't prevent self-loops — verify it stores them
+        // Edge class doesn't prevent self-loops - verify it stores them
         Edge e = new Edge("f", "X", "X");
         assertEquals(e.getVertex1(), e.getVertex2());
     }
+
+    // --- equals / hashCode contract (order-sensitive, directed-safe) ---
+
+    @Test
+    public void testEqualsReflexive() {
+        Edge e = new Edge("f", "A", "B");
+        e.setWeight(1.5f);
+        assertEquals(e, e);
+    }
+
+    @Test
+    public void testEqualsSameFieldsAreEqual() {
+        Edge a = new Edge("f", "A", "B");
+        a.setWeight(2.0f);
+        Edge b = new Edge("f", "A", "B");
+        b.setWeight(2.0f);
+        assertEquals(a, b);
+        assertEquals(a.hashCode(), b.hashCode());
+    }
+
+    @Test
+    public void testEqualsIgnoresLabel() {
+        // Labels are display-only and excluded from identity.
+        Edge a = new Edge("f", "A", "B");
+        a.setLabel("close");
+        Edge b = new Edge("f", "A", "B");
+        b.setLabel("acquaintance");
+        assertEquals(a, b);
+        assertEquals(a.hashCode(), b.hashCode());
+    }
+
+    @Test
+    public void testEqualsIsOrderSensitive() {
+        // Regression: previously equals treated (A,B) == (B,A), which made
+        // it impossible to store both directions of an edge in a
+        // DirectedSparseGraph (JUNG's addEdge would reject the reverse).
+        Edge ab = new Edge("link", "A", "B");
+        Edge ba = new Edge("link", "B", "A");
+        assertNotEquals(ab, ba);
+        // Hash codes should also differ for the swapped-vertex case so
+        // hash-based containers don't collide spuriously.
+        assertNotEquals(ab.hashCode(), ba.hashCode());
+    }
+
+    @Test
+    public void testEqualsDifferentTypeNotEqual() {
+        Edge a = new Edge("f", "A", "B");
+        Edge b = new Edge("c", "A", "B");
+        assertNotEquals(a, b);
+    }
+
+    @Test
+    public void testEqualsDifferentWeightNotEqual() {
+        Edge a = new Edge("f", "A", "B");
+        a.setWeight(1.0f);
+        Edge b = new Edge("f", "A", "B");
+        b.setWeight(2.0f);
+        assertNotEquals(a, b);
+    }
+
+    @Test
+    public void testEqualsAgainstNullAndOtherType() {
+        Edge a = new Edge("f", "A", "B");
+        assertNotEquals(a, null);
+        assertNotEquals(a, "not-an-edge");
+    }
+
+    @Test
+    public void testHashCodeStableAcrossInvocations() {
+        Edge e = new Edge("f", "A", "B");
+        e.setWeight(3.25f);
+        int h1 = e.hashCode();
+        int h2 = e.hashCode();
+        int h3 = e.hashCode();
+        assertEquals(h1, h2);
+        assertEquals(h2, h3);
+    }
+
+    @Test
+    public void testEqualsHandlesNullEndpoints() {
+        Edge a = new Edge();
+        Edge b = new Edge();
+        // Two default-constructed edges have identical (all-null/zero) state.
+        assertEquals(a, b);
+        assertEquals(a.hashCode(), b.hashCode());
+    }
+
+    // --- equalsUndirected (legacy symmetric comparison) ---
+
+    @Test
+    public void testEqualsUndirectedTreatsReverseAsEqual() {
+        Edge ab = new Edge("f", "A", "B");
+        Edge ba = new Edge("f", "B", "A");
+        assertTrue(ab.equalsUndirected(ba));
+        assertTrue(ba.equalsUndirected(ab));
+    }
+
+    @Test
+    public void testEqualsUndirectedStillChecksTypeAndWeight() {
+        Edge ab = new Edge("f", "A", "B");
+        ab.setWeight(1.0f);
+        Edge baDiffType = new Edge("c", "B", "A");
+        baDiffType.setWeight(1.0f);
+        Edge baDiffWeight = new Edge("f", "B", "A");
+        baDiffWeight.setWeight(2.0f);
+        assertFalse(ab.equalsUndirected(baDiffType));
+        assertFalse(ab.equalsUndirected(baDiffWeight));
+    }
+
+    @Test
+    public void testEqualsUndirectedHandlesNull() {
+        Edge ab = new Edge("f", "A", "B");
+        assertFalse(ab.equalsUndirected(null));
+    }
+
+    @Test
+    public void testEqualsUndirectedReflexive() {
+        Edge ab = new Edge("f", "A", "B");
+        assertTrue(ab.equalsUndirected(ab));
+    }
+
+    // --- Directed-graph integration (the bug this commit fixes) ---
+
+    @Test
+    public void testDirectedGraphAcceptsBothDirections() {
+        // Regression test for the equals/hashCode bug: with order-insensitive
+        // equals, this addEdge throws IllegalArgumentException because
+        // JUNG considers the reverse edge already present.
+        edu.uci.ics.jung.graph.DirectedSparseGraph<String, Edge> g =
+                new edu.uci.ics.jung.graph.DirectedSparseGraph<>();
+        g.addVertex("A");
+        g.addVertex("B");
+        Edge ab = new Edge("link", "A", "B");
+        ab.setLabel("e1");
+        Edge ba = new Edge("link", "B", "A");
+        ba.setLabel("e2");
+        assertTrue("forward edge should be added", g.addEdge(ab, "A", "B"));
+        assertTrue("reverse edge should be added in a directed graph",
+                g.addEdge(ba, "B", "A"));
+        assertEquals(2, g.getEdgeCount());
+    }
 }

Gvisual/test/gvisual/GraphTemporalDynamicsEngineTest.java

@@ -26,10 +26,11 @@ public void setUp() {
     private Graph<String, Edge> createGraph(String[][] edges) {
         Graph<String, Edge> g = new UndirectedSparseGraph<>();
         for (String[] e : edges) {
-            Edge edge = new Edge("f", e[0], e[1]);
             if (!g.containsVertex(e[0])) g.addVertex(e[0]);
             if (!g.containsVertex(e[1])) g.addVertex(e[1]);
-            g.addEdge(edge, e[0], e[1]);
+            // Skip duplicate undirected pairs so the snapshot stays a simple graph.
+            if (g.findEdge(e[0], e[1]) != null) continue;
+            g.addEdge(new Edge("f", e[0], e[1]), e[0], e[1]);
         }
         return g;
     }
@@ -443,10 +444,13 @@ public void testNodeTrajectoryLimitedTo20() {
     @Test
     public void testDegreeEntropyIncreases() {
         List<Graph<String, Edge>> snapshots = new ArrayList<>();
-        // Uniform degree -> varied degree
-        snapshots.add(createGraph(new String[][]{{"A","B"},{"B","C"},{"C","D"},{"D","A"}})); // all degree 2
-        snapshots.add(createGraph(new String[][]{{"A","B"},{"B","C"},{"C","D"},{"D","A"},{"A","C"}})); // A,C degree 3
-        snapshots.add(createGraph(new String[][]{{"A","B"},{"B","C"},{"C","D"},{"D","A"},{"A","C"},{"A","D"},{"B","D"}}));
+        // Snapshot 0: uniform degree (4-cycle, every vertex has degree 2 -> entropy 0).
+        snapshots.add(createGraph(new String[][]{{"A","B"},{"B","C"},{"C","D"},{"D","A"}}));
+        // Snapshot 1: add diagonal A-C, so A and C become degree 3, B and D stay 2.
+        snapshots.add(createGraph(new String[][]{{"A","B"},{"B","C"},{"C","D"},{"D","A"},{"A","C"}}));
+        // Snapshot 2: extend with a pendant E off A and a pendant F off B -> degree mix {1,1,2,3,3,4}.
+        snapshots.add(createGraph(new String[][]{
+                {"A","B"},{"B","C"},{"C","D"},{"D","A"},{"A","C"},{"A","E"},{"B","F"}}));
         GraphTemporalDynamicsEngine.TemporalDynamicsReport report = engine.analyze(snapshots);
         // First snapshot: all same degree -> entropy = 0 (one bin)
         assertEquals(0.0, report.snapshots.get(0).degreeEntropy, 0.01);