feat(templates): Implement enhanced, object-oriented lattice module

This commit introduces a new, robust lattice module under `tensorcircuit.templates.lattice` and addresses all reviewer feedback, significantly enhancing its functionality, usability, and robustness.

The new module provides an `AbstractLattice` base class, a `TILattice` class for procedurally generated periodic structures (e.g., `SquareLattice`, `HoneycombLattice`), and a `CustomizeLattice` class for user-defined geometries.

Key features and improvements include:

- A benchmark-proven, high-performance neighbor search for `CustomizeLattice`, which defaults to a KDTree-based algorithm (when Scipy is available) after performance data confirmed its superiority over the baseline distance-matrix method across all tested scales (N=10 to 2000).

- Dynamic modification APIs for `CustomizeLattice`:
  - `from_lattice()`: To convert any lattice type into a customizable one.
  - `add_sites()`: To dynamically add new sites.
  - `remove_sites()`: To dynamically remove existing sites.

- The `show()` visualization method's default behavior has been fixed (`show_bonds_k=None`) to prevent warnings on lattices with un-calculated neighbors, improving user experience.

- Comprehensive test coverage has been added for all new features, including API contracts, dynamic modifications, edge cases, and visualization logic.

- Full documentation and type hints are provided for all public APIs, conforming to the project's coding standards.

Author: Stellogic

.gitignore

@@ -31,3 +31,4 @@ docs/source/locale/zh/LC_MESSAGES/textbook.po
 docs/source/locale/zh/LC_MESSAGES/whitepapertoc_cn.po
 docs/source/locale/zh/LC_MESSAGES/textbooktoc.po
 test.qasm
+venv/

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Change Log
 
 ## Unreleased
+- Add `Lattice` module (`tensorcircuit.templates.lattice`) for creating and manipulating various lattice geometries, including `SquareLattice`, `HoneycombLattice`, and `CustomizeLattice`.
 
 ## v1.2.1
 

tensorcircuit/templates/.benchmarks/benchmark_neighbors.py

@@ -0,0 +1,86 @@
+# benchmark_neighbors.py
+"""
+A script to benchmark the performance of neighbor-finding algorithms
+for the CustomizeLattice class.
+
+This script compares the KDTree-based method against the baseline
+all-to-all distance matrix method across a range of lattice sizes.
+
+To run this script from the project root directory:
+python benchmark_neighbors.py
+"""
+import logging
+import timeit
+from typing import Any, Dict, List
+
+
+
+logging.getLogger("tensorcircuit.templates.lattice").setLevel(logging.WARNING)
+
+
+def run_benchmark() -> None:
+    """
+    Executes the benchmark test and prints the results in a formatted table.
+    """
+    site_counts: List[int] = [10, 50, 100, 200, 500, 1000, 1500, 2000]
+    max_k: int = 1
+    number_of_runs: int = 5
+    results: List[Dict[str, Any]] = []
+
+    print("=" * 75)
+    print("Starting neighbor finding benchmark for CustomizeLattice...")
+    print(f"Each test will be run {number_of_runs} times to get a stable average.")
+    print("=" * 75)
+    print(
+        f"{'Sites (N)':>10} | {'KDTree Time (s)':>18} | {'Baseline Time (s)':>20} | {'Speedup':>10}"
+    )
+    print("-" * 75)
+
+    for n_sites in site_counts:
+        setup_code = f"""
+import numpy as np
+from tensorcircuit.templates.lattice import CustomizeLattice
+
+np.random.seed(42)
+coords = np.random.rand({n_sites}, 2)
+ids = list(range({n_sites}))
+lat = CustomizeLattice(dimensionality=2, identifiers=ids, coordinates=coords)
+"""
+        stmt_kdtree = f"lat._build_neighbors(max_k={max_k})"
+        stmt_baseline = f"lat._build_neighbors_by_distance_matrix(max_k={max_k})"
+
+        try:
+            time_kdtree = (
+                timeit.timeit(stmt=stmt_kdtree, setup=setup_code, number=number_of_runs)
+                / number_of_runs
+            )
+            time_baseline = (
+                timeit.timeit(
+                    stmt=stmt_baseline, setup=setup_code, number=number_of_runs
+                )
+                / number_of_runs
+            )
+
+            speedup = time_baseline / time_kdtree if time_kdtree > 0 else float("inf")
+            results.append(
+                {
+                    "n_sites": n_sites,
+                    "time_kdtree": time_kdtree,
+                    "time_baseline": time_baseline,
+                    "speedup": speedup,
+                }
+            )
+            print(
+                f"{n_sites:>10} | {time_kdtree:>18.6f} | {time_baseline:>20.6f} | {speedup:>9.2f}x"
+            )
+
+        except Exception as e:
+            print(f"An error occurred at N={n_sites}: {e}")
+            break
+
+    print("-" * 75)
+    print("Benchmark complete.")
+
+
+if __name__ == "__main__":
+    run_benchmark()

tensorcircuit/templates/__init__.py

@@ -5,5 +5,6 @@
 from . import graphs
 from . import measurements
 from . import conversions
+from . import lattice
 
 costfunctions = measurements