Support hyperedges in TensorCircuit using cotengra.

This change introduces compatibility for hyperedges (represented by CopyNodes in TensorNetwork) when using the cotengra contractor.
It processes the tensor network graph to merge edges connected via CopyNodes into hyperedges for cotengra's path finding, and then correctly executes the contraction path by absorbing CopyNodes into tensors during contraction.

Key changes:
- `tensorcircuit/cons.py`:
    - Updated `_get_path_cache_friendly` to use UnionFind to group edges connected by CopyNodes.
    - Optimized to skip UnionFind overhead if no CopyNodes are present.
    - Updated `_base` to absorb CopyNodes when contracting nodes that share them.
    - Added post-processing to absorb any remaining CopyNodes connected to the final result.
- Added `examples/hyperedge_demo.py` demonstrating the feature, including a large-scale example.
- Added `tests/test_hyperedge.py` for verification using pytest fixtures.

Co-authored-by: refraction-ray <35157286+refraction-ray@users.noreply.github.com>

Author: google-labs-jules[bot]

examples/hyperedge_demo.py

@@ -7,6 +7,7 @@
 import tensornetwork as tn
 import tensorcircuit as tc
 
+
 def hyperedge_demo():
     print("Demonstrating hyperedge contraction with cotengra...")
 
@@ -31,7 +32,7 @@ def hyperedge_demo():
 
     res = tc.contractor(nodes)
     print("Single Hyperedge Result:", res.tensor)
-    expected = 1*1*1 + 2*2*2
+    expected = 1 * 1 * 1 + 2 * 2 * 2
     print(f"Expected: {expected}")
     assert np.allclose(res.tensor, expected)
 
@@ -42,7 +43,9 @@ def hyperedge_demo():
     dim = 2
 
     # Create 20 random tensors connected to a single CopyNode
-    input_tensors = [tn.Node(np.random.rand(dim), name=f"T{i}") for i in range(num_legs)]
+    input_tensors = [
+        tn.Node(np.random.rand(dim), name=f"T{i}") for i in range(num_legs)
+    ]
     cn_large = tn.CopyNode(num_legs, dim, name="CN_Large")
 
     for i, t in enumerate(input_tensors):
@@ -70,5 +73,6 @@ def hyperedge_demo():
     print(f"Expected: {expected_sum}")
     assert np.allclose(res_large.tensor, expected_sum)
 
+
 if __name__ == "__main__":
     hyperedge_demo()

tests/test_hyperedge.py

@@ -3,6 +3,7 @@
 import tensorcircuit as tc
 import pytest
 
+
 @pytest.fixture
 def contractor_setup(request):
     """
@@ -21,6 +22,7 @@ def contractor_setup(request):
     # Reset to default
     tc.set_contractor("greedy")
 
+
 @pytest.mark.parametrize("contractor_setup", ["cotengra", "greedy"], indirect=True)
 def test_single_hyperedge(contractor_setup):
     # A(i), B(i), C(i)
@@ -48,6 +50,7 @@ def test_single_hyperedge(contractor_setup):
     res = tc.contractor(nodes)
     assert np.allclose(res.tensor, 9.0)
 
+
 @pytest.mark.parametrize("contractor_setup", ["cotengra"], indirect=True)
 def test_chained_hyperedge(contractor_setup):
     # A(i), B(i), C(i), D(i)
@@ -63,7 +66,7 @@ def test_chained_hyperedge(contractor_setup):
 
     a[0] ^ cn1[0]
     b[0] ^ cn1[1]
-    cn1[2] ^ cn2[0] # Link
+    cn1[2] ^ cn2[0]  # Link
     c[0] ^ cn2[1]
     d[0] ^ cn2[2]
 
@@ -72,6 +75,7 @@ def test_chained_hyperedge(contractor_setup):
     # sum i A_i B_i C_i D_i = 1+16 = 17
     assert np.allclose(res.tensor, 17.0)
 
+
 @pytest.mark.parametrize("contractor_setup", ["cotengra"], indirect=True)
 def test_dangling_hyperedge(contractor_setup):
     # A(i), B(i), Output(i)
@@ -85,11 +89,12 @@ def test_dangling_hyperedge(contractor_setup):
     # cn[2] is dangling
 
     nodes = [a, b, cn]
-    res = tc.contractor(nodes) # Should return a tensor of shape (2,)
+    res = tc.contractor(nodes)  # Should return a tensor of shape (2,)
 
     # Expected: C_i = A_i * B_i => [1, 4]
     assert np.allclose(res.tensor, np.array([1.0, 4.0]))
 
+
 @pytest.mark.parametrize("contractor_setup", ["cotengra"], indirect=True)
 def test_tensorcircuit_circuit_hyperedge_support(contractor_setup):
     # While TC circuit doesn't typically create CopyNodes directly in gates,