tensorcircuit-nightly 1.2.1.dev20250726__tar.gz → 1.3.0.dev20250727__tar.gz

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/CHANGELOG.md

@@ -2,10 +2,14 @@
 
 ## Unreleased
 
+## v1.3.0
+
 ### Added
 
 - Add `Lattice` module (`tensorcircuit.templates.lattice`) for creating and manipulating various lattice geometries, including `SquareLattice`, `HoneycombLattice`, and `CustomizeLattice`.
 
+- Add `tc.templates.hamiltonians` for commom systems.
+
 - Add `DistributedContractor` in experimental module with new examples for fast implementation of distribution circuit simulation on jax backend.
 
 - Add `circuit.amplitude_before()` method to return the corresponding tensornetwork nodes.
@@ -20,6 +24,10 @@
 
 - Fix `to_dlpack` for jax version >= 0.7.
 
+- Fix large eps issue in entanglement calculation of FGS.
+
+- Fix cmatrix non-refresh issue for `post_select` in FGS.
+
 ## v1.2.1
 
 ### Fixed

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensorcircuit-nightly
-Version: 1.2.1.dev20250726
+Version: 1.3.0.dev20250727
 Summary: nightly release for tensorcircuit
 Home-page: https://github.com/refraction-ray/tensorcircuit-dev
 Author: TensorCircuit Authors
@@ -70,7 +70,7 @@ TensorCircuit-NG is the actively maintained official version and a [fully compat
 
 Please begin with [Quick Start](/docs/source/quickstart.rst) in the [full documentation](https://tensorcircuit-ng.readthedocs.io/).
 
-For more information on software usage, sota algorithm implementation and engineer paradigm demonstration, please refer to 80+ [example scripts](/examples) and 30+ [tutorial notebooks](https://tensorcircuit-ng.readthedocs.io/en/latest/#tutorials). API docstrings and test cases in [tests](/tests) are also informative. One can also refer to tensorcircuit-ng [deepwiki](https://deepwiki.com/tensorcircuit/tensorcircuit-ng) by LLM.
+For more information on software usage, sota algorithm implementation and engineer paradigm demonstration, please refer to 80+ [example scripts](/examples) and 30+ [tutorial notebooks](https://tensorcircuit-ng.readthedocs.io/en/latest/#tutorials). API docstrings and test cases in [tests](/tests) are also informative. One can also refer to tensorcircuit-ng [deepwiki](https://deepwiki.com/tensorcircuit/tensorcircuit-ng) or [Context7 MCP](https://context7.com/tensorcircuit/tensorcircuit-ng).
 
 For beginners, please refer to [quantum computing lectures with TC-NG](https://github.com/sxzgroup/qc_lecture) to learn both quantum computing basics and representative usage of TensorCircuit-NG.
 

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/README.md

@@ -35,7 +35,7 @@ TensorCircuit-NG is the actively maintained official version and a [fully compat
 
 Please begin with [Quick Start](/docs/source/quickstart.rst) in the [full documentation](https://tensorcircuit-ng.readthedocs.io/).
 
-For more information on software usage, sota algorithm implementation and engineer paradigm demonstration, please refer to 80+ [example scripts](/examples) and 30+ [tutorial notebooks](https://tensorcircuit-ng.readthedocs.io/en/latest/#tutorials). API docstrings and test cases in [tests](/tests) are also informative. One can also refer to tensorcircuit-ng [deepwiki](https://deepwiki.com/tensorcircuit/tensorcircuit-ng) by LLM.
+For more information on software usage, sota algorithm implementation and engineer paradigm demonstration, please refer to 80+ [example scripts](/examples) and 30+ [tutorial notebooks](https://tensorcircuit-ng.readthedocs.io/en/latest/#tutorials). API docstrings and test cases in [tests](/tests) are also informative. One can also refer to tensorcircuit-ng [deepwiki](https://deepwiki.com/tensorcircuit/tensorcircuit-ng) or [Context7 MCP](https://context7.com/tensorcircuit/tensorcircuit-ng).
 
 For beginners, please refer to [quantum computing lectures with TC-NG](https://github.com/sxzgroup/qc_lecture) to learn both quantum computing basics and representative usage of TensorCircuit-NG.
 

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/docs/source/tutorial.rst

@@ -18,6 +18,8 @@ Jupyter Tutorials
     tutorials/mera.ipynb
     tutorials/gradient_benchmark.ipynb
     tutorials/contractors.ipynb
+    tutorials/stabilizer_circuit.ipynb
+    tutorials/fermion_gaussian_states.ipynb
     tutorials/operator_spreading.ipynb
     tutorials/optimization_and_expressibility.ipynb
     tutorials/vqex_mbl.ipynb
@@ -28,4 +30,5 @@ Jupyter Tutorials
     tutorials/imag_time_evo.ipynb
     tutorials/classical_shadows.ipynb
     tutorials/sklearn_svc.ipynb
+    tutorials/distributed_simulation.ipynb
     tutorials/qcloud_sdk_demo.ipynb

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/tensorcircuit/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.2.1.dev20250726"
+__version__ = "1.3.0.dev20250727"
 __author__ = "TensorCircuit Authors"
 __creator__ = "refraction-ray"
 

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/tensorcircuit/fgs.py

@@ -310,7 +310,7 @@ class FGSSimulator:
         lbd, _ = backend.eigh(m)
         lbd = backend.real(lbd)
         lbd = backend.relu(lbd)
-        eps = 1e-6
+        eps = 1e-9
 
         entropy = backend.sum(backend.log(lbd**n + (1 - lbd) ** n + eps))
         s = 1 / (2 * (1 - n)) * entropy
@@ -449,7 +449,7 @@ class FGSSimulator:
         lbd = backend.real(lbd)
         lbd = backend.relu(lbd)
         #         lbd /= backend.sum(lbd)
-        eps = 1e-6
+        eps = 1e-9
         entropy = -backend.sum(
             lbd * backend.log(lbd + eps) + (1 - lbd) * backend.log(1 - lbd + eps)
         )
@@ -793,6 +793,7 @@ class FGSSimulator:
         alpha1 = alpha1 * mask02d + backend.tile(newcol[:, None], [1, self.L]) * mask12d
         q, _ = backend.qr(alpha1)
         self.alpha = q
+        self.cmatrix = None
 
     def cond_measure(self, ind: int, status: float, with_prob: bool = False) -> Tensor:
         """

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/tensorcircuit/results/counts.py

@@ -12,6 +12,19 @@ ct = Dict[str, int]
 
 
 def reverse_count(count: ct) -> ct:
+    """
+    Reverse the bit string keys in a count dictionary.
+
+    :param count: A dictionary mapping bit strings to counts
+    :type count: ct
+    :return: A new dictionary with reversed bit string keys
+    :rtype: ct
+
+    :Example:
+
+    >>> reverse_count({"01": 10, "10": 20})
+    {'10': 10, '01': 20}
+    """
     ncount = {}
     for k, v in count.items():
         ncount[k[::-1]] = v
@@ -19,15 +32,56 @@ def reverse_count(count: ct) -> ct:
 
 
 def sort_count(count: ct) -> ct:
+    """
+    Sort the count dictionary by counts in descending order.
+
+    :param count: A dictionary mapping bit strings to counts
+    :type count: ct
+    :return: A new dictionary sorted by count values (descending)
+    :rtype: ct
+
+    :Example:
+
+    >>> sort_count({"00": 5, "01": 15, "10": 10})
+    {'01': 15, '10': 10, '00': 5}
+    """
     return {k: v for k, v in sorted(count.items(), key=lambda item: -item[1])}
 
 
 def normalized_count(count: ct) -> Dict[str, float]:
+    """
+    Normalize the count dictionary to represent probabilities.
+
+    :param count: A dictionary mapping bit strings to counts
+    :type count: ct
+    :return: A new dictionary with probabilities instead of counts
+    :rtype: Dict[str, float]
+
+    :Example:
+
+    >>> normalized_count({"00": 5, "01": 15})
+    {'00': 0.25, '01': 0.75}
+    """
     shots = sum([v for k, v in count.items()])
     return {k: v / shots for k, v in count.items()}
 
 
 def marginal_count(count: ct, keep_list: Sequence[int]) -> ct:
+    """
+    Compute the marginal distribution of a count dictionary over specified qubits.
+
+    :param count: A dictionary mapping bit strings to counts
+    :type count: ct
+    :param keep_list: List of qubit indices to keep in the marginal distribution
+    :type keep_list: Sequence[int]
+    :return: A new count dictionary with marginal distribution
+    :rtype: ct
+
+    :Example:
+
+    >>> marginal_count({"001": 10, "110": 20}, [0, 2])
+    {'01': 10, '10': 20}
+    """
     import qiskit
 
     count = reverse_count(count)
@@ -36,6 +90,21 @@ def marginal_count(count: ct, keep_list: Sequence[int]) -> ct:
 
 
 def count2vec(count: ct, normalization: bool = True) -> Tensor:
+    """
+    Convert count dictionary to probability vector.
+
+    :param count: A dictionary mapping bit strings to counts
+    :type count: ct
+    :param normalization: Whether to normalize the counts to probabilities, defaults to True
+    :type normalization: bool, optional
+    :return: Probability vector as numpy array
+    :rtype: Tensor
+
+    :Example:
+
+    >>> count2vec({"00": 2, "10": 3, "11": 5})
+    array([0.2, 0. , 0.3, 0.5])
+    """
     nqubit = len(list(count.keys())[0])
     probability = [0] * 2**nqubit
     shots = sum([v for k, v in count.items()])
@@ -47,6 +116,21 @@ def count2vec(count: ct, normalization: bool = True) -> Tensor:
 
 
 def vec2count(vec: Tensor, prune: bool = False) -> ct:
+    """
+    Convert probability vector to count dictionary.
+
+    :param vec: Probability vector
+    :type vec: Tensor
+    :param prune: Whether to remove near-zero probabilities, defaults to False
+    :type prune: bool, optional
+    :return: Count dictionary
+    :rtype: ct
+
+    :Example:
+
+    >>> vec2count(np.array([0.2, 0.3, 0.1, 0.4]))
+    {'00': 0.2, '01': 0.3, '10': 0.1, '11': 0.4}
+    """
     from ..quantum import count_vector2dict
 
     if isinstance(vec, list):
@@ -63,6 +147,16 @@ def vec2count(vec: Tensor, prune: bool = False) -> ct:
 
 
 def kl_divergence(c1: ct, c2: ct) -> float:
+    """
+    Compute the Kullback-Leibler divergence between two count distributions.
+
+    :param c1: First count dictionary
+    :type c1: ct
+    :param c2: Second count dictionary
+    :type c2: ct
+    :return: KL divergence value
+    :rtype: float
+    """
     eps = 1e-4  # typical value for inverse of the total shots
     c1 = normalized_count(c1)  # type: ignore
     c2 = normalized_count(c2)  # type: ignore
@@ -113,6 +207,11 @@ def merge_count(*counts: ct) -> ct:
     :type counts: ct
     :return: Merged count dictionary
     :rtype: ct
+
+    :Example:
+
+    >>> merge_count({"00": 10, "01": 20}, {"00": 5, "10": 15})
+    {'00': 15, '01': 20, '10': 15}
     """
     merged: ct = {}
     for count in counts:

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/tensorcircuit/stabilizercircuit.py

@@ -169,7 +169,6 @@ class StabilizerCircuit(AbstractCircuit):
         if with_prob:
             num_random_measurements = 0
             for i in index:
-                print(i, s1.peek_z(i))
                 if s1.peek_z(i) == 0:
                     num_random_measurements += 1
             probability = (0.5) ** num_random_measurements

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/tensorcircuit/templates/__init__.py

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

tensorcircuit_nightly-1.3.0.dev20250727/tensorcircuit/templates/hamiltonians.py

@@ -0,0 +1,153 @@
+from typing import Any, List, Tuple, Union
+import numpy as np
+from ..cons import dtypestr, backend
+from ..quantum import PauliStringSum2COO
+from .lattice import AbstractLattice
+
+
+def _create_empty_sparse_matrix(shape: Tuple[int, int]) -> Any:
+    """
+    Helper function to create a backend-agnostic empty sparse matrix.
+    """
+    indices = backend.convert_to_tensor(backend.zeros((0, 2), dtype="int32"))
+    values = backend.convert_to_tensor(backend.zeros((0,), dtype=dtypestr))  # type: ignore
+    return backend.coo_sparse_matrix(indices=indices, values=values, shape=shape)  # type: ignore
+
+
+def heisenberg_hamiltonian(
+    lattice: AbstractLattice,
+    j_coupling: Union[float, List[float], Tuple[float, ...]] = 1.0,
+) -> Any:
+    """
+    Generates the sparse matrix of the Heisenberg Hamiltonian for a given lattice.
+
+    The Heisenberg Hamiltonian is defined as:
+    H = J * Σ_{<i,j>} (X_i X_j + Y_i Y_j + Z_i Z_j)
+    where the sum is over all unique nearest-neighbor pairs <i,j>.
+
+    :param lattice: An instance of a class derived from AbstractLattice,
+        which provides the geometric information of the system.
+    :type lattice: AbstractLattice
+    :param j_coupling: The coupling constants. Can be a single float for an
+        isotropic model (Jx=Jy=Jz) or a list/tuple of 3 floats for an
+        anisotropic model (Jx, Jy, Jz). Defaults to 1.0.
+    :type j_coupling: Union[float, List[float], Tuple[float, ...]], optional
+    :return: The Hamiltonian as a backend-agnostic sparse matrix.
+    :rtype: Any
+    """
+    num_sites = lattice.num_sites
+    neighbor_pairs = lattice.get_neighbor_pairs(k=1, unique=True)
+
+    if isinstance(j_coupling, (float, int)):
+        js = [float(j_coupling)] * 3
+    else:
+        if len(j_coupling) != 3:
+            raise ValueError("j_coupling must be a float or a list/tuple of 3 floats.")
+        js = [float(j) for j in j_coupling]
+
+    if not neighbor_pairs:
+        return _create_empty_sparse_matrix(shape=(2**num_sites, 2**num_sites))
+    if num_sites == 0:
+        raise ValueError("Cannot generate a Hamiltonian for a lattice with zero sites.")
+
+    pauli_map = {"X": 1, "Y": 2, "Z": 3}
+
+    ls: List[List[int]] = []
+    weights: List[float] = []
+
+    pauli_terms = ["X", "Y", "Z"]
+    for i, j in neighbor_pairs:
+        for idx, pauli_char in enumerate(pauli_terms):
+            if abs(js[idx]) > 1e-9:
+                string = [0] * num_sites
+                string[i] = pauli_map[pauli_char]
+                string[j] = pauli_map[pauli_char]
+                ls.append(string)
+                weights.append(js[idx])
+
+    hamiltonian_matrix = PauliStringSum2COO(ls, weight=weights, numpy=False)
+
+    return hamiltonian_matrix
+
+
+def rydberg_hamiltonian(
+    lattice: AbstractLattice, omega: float, delta: float, c6: float
+) -> Any:
+    """
+    Generates the sparse matrix of the Rydberg atom array Hamiltonian.
+
+    The Hamiltonian is defined as:
+    H = Σ_i (Ω/2)X_i - Σ_i δ(1 - Z_i)/2 + Σ_{i<j} V_ij (1-Z_i)/2 (1-Z_j)/2
+      = Σ_i (Ω/2)X_i + Σ_i (δ/2)Z_i + Σ_{i<j} (V_ij/4)(Z_iZ_j - Z_i - Z_j)
+    where V_ij = C6 / |r_i - r_j|^6.
+
+    Note: Constant energy offset terms (proportional to the identity operator)
+    are ignored in this implementation.
+
+    :param lattice: An instance of a class derived from AbstractLattice,
+        which provides site coordinates and the distance matrix.
+    :type lattice: AbstractLattice
+    :param omega: The Rabi frequency (Ω) of the driving laser field.
+    :type omega: float
+    :param delta: The laser detuning (δ).
+    :type delta: float
+    :param c6: The Van der Waals interaction coefficient (C6).
+    :type c6: float
+    :return: The Hamiltonian as a backend-agnostic sparse matrix.
+    :rtype: Any
+    """
+    num_sites = lattice.num_sites
+    if num_sites == 0:
+        raise ValueError("Cannot generate a Hamiltonian for a lattice with zero sites.")
+
+    pauli_map = {"X": 1, "Y": 2, "Z": 3}
+    ls: List[List[int]] = []
+    weights: List[float] = []
+
+    for i in range(num_sites):
+        x_string = [0] * num_sites
+        x_string[i] = pauli_map["X"]
+        ls.append(x_string)
+        weights.append(omega / 2.0)
+
+    z_coefficients = np.zeros(num_sites)
+
+    for i in range(num_sites):
+        z_coefficients[i] += delta / 2.0
+
+    dist_matrix = lattice.distance_matrix
+
+    for i in range(num_sites):
+        for j in range(i + 1, num_sites):
+            distance = dist_matrix[i, j]
+
+            if distance < 1e-9:
+                continue
+
+            interaction_strength = c6 / (distance**6)
+            coefficient = interaction_strength / 4.0
+
+            zz_string = [0] * num_sites
+            zz_string[i] = pauli_map["Z"]
+            zz_string[j] = pauli_map["Z"]
+            ls.append(zz_string)
+            weights.append(coefficient)
+
+            # The interaction term V_ij * n_i * n_j, when expanded using
+            # n_i = (1-Z_i)/2, becomes (V_ij/4)*(I - Z_i - Z_j + Z_i*Z_j).
+            # This contributes a positive term (+V_ij/4) to the ZZ interaction,
+            # but negative terms (-V_ij/4) to the single-site Z_i and Z_j operators.
+
+            z_coefficients[i] -= coefficient
+            z_coefficients[j] -= coefficient
+
+    for i in range(num_sites):
+        if abs(z_coefficients[i]) > 1e-9:
+            z_string = [0] * num_sites
+            z_string[i] = pauli_map["Z"]
+            ls.append(z_string)
+            weights.append(z_coefficients[i])  # type: ignore
+
+    hamiltonian_matrix = PauliStringSum2COO(ls, weight=weights, numpy=False)
+
+    return hamiltonian_matrix

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/tensorcircuit/utils.py

@@ -11,6 +11,13 @@ import time
 
 
 def gpu_memory_share(flag: bool = True) -> None:
+    """
+    Set the GPU memory growth mode
+
+    :param flag: whether to set the GPU memory growth mode, defaults to True
+    :type flag: bool
+    :return: None
+    """
     # TODO(@refraction-ray): the default torch behavior should be True
     # preallocate behavior for torch to be investigated
     if flag is True:

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/tensorcircuit_nightly.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensorcircuit-nightly
-Version: 1.2.1.dev20250726
+Version: 1.3.0.dev20250727
 Summary: nightly release for tensorcircuit
 Home-page: https://github.com/refraction-ray/tensorcircuit-dev
 Author: TensorCircuit Authors
@@ -70,7 +70,7 @@ TensorCircuit-NG is the actively maintained official version and a [fully compat
 
 Please begin with [Quick Start](/docs/source/quickstart.rst) in the [full documentation](https://tensorcircuit-ng.readthedocs.io/).
 
-For more information on software usage, sota algorithm implementation and engineer paradigm demonstration, please refer to 80+ [example scripts](/examples) and 30+ [tutorial notebooks](https://tensorcircuit-ng.readthedocs.io/en/latest/#tutorials). API docstrings and test cases in [tests](/tests) are also informative. One can also refer to tensorcircuit-ng [deepwiki](https://deepwiki.com/tensorcircuit/tensorcircuit-ng) by LLM.
+For more information on software usage, sota algorithm implementation and engineer paradigm demonstration, please refer to 80+ [example scripts](/examples) and 30+ [tutorial notebooks](https://tensorcircuit-ng.readthedocs.io/en/latest/#tutorials). API docstrings and test cases in [tests](/tests) are also informative. One can also refer to tensorcircuit-ng [deepwiki](https://deepwiki.com/tensorcircuit/tensorcircuit-ng) or [Context7 MCP](https://context7.com/tensorcircuit/tensorcircuit-ng).
 
 For beginners, please refer to [quantum computing lectures with TC-NG](https://github.com/sxzgroup/qc_lecture) to learn both quantum computing basics and representative usage of TensorCircuit-NG.
 

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/tensorcircuit_nightly.egg-info/SOURCES.txt

@@ -105,6 +105,7 @@ tensorcircuit/templates/chems.py
 tensorcircuit/templates/conversions.py
 tensorcircuit/templates/dataset.py
 tensorcircuit/templates/graphs.py
+tensorcircuit/templates/hamiltonians.py
 tensorcircuit/templates/lattice.py
 tensorcircuit/templates/measurements.py
 tensorcircuit_nightly.egg-info/PKG-INFO
@@ -124,6 +125,7 @@ tests/test_dmcircuit.py
 tests/test_ensemble.py
 tests/test_fgs.py
 tests/test_gates.py
+tests/test_hamiltonians.py
 tests/test_interfaces.py
 tests/test_keras.py
 tests/test_lattice.py

{tensorcircuit_nightly-1.2.1.dev20250726 → tensorcircuit_nightly-1.3.0.dev20250727}/tests/test_fgs.py

@@ -170,6 +170,14 @@ def test_post_select(backend, highp):
             np.testing.assert_allclose(c.get_cmatrix(), c1.get_cmatrix(), atol=1e-5)
 
 
+@pytest.mark.parametrize("backend", [lf("npb"), lf("tfb"), lf("jaxb")])
+def test_post_select_cmatrix_refresh(backend, highp):
+    sim_post = tc.FGSSimulator(L=2, filled=[0])
+    sim_post.evol_hp(0, 1, np.pi / 4)
+    sim_post.post_select(0, keep=1)
+    np.testing.assert_allclose(1 - sim_post.get_cmatrix()[0, 0], 1, atol=1e-6)
+
+
 @pytest.mark.parametrize("backend", [lf("tfb"), lf("jaxb")])
 def test_jittable_measure(backend):
     @tc.backend.jit

tensorcircuit_nightly-1.3.0.dev20250727/tests/test_hamiltonians.py

@@ -0,0 +1,159 @@
+import pytest
+import numpy as np
+from pytest_lazyfixture import lazy_fixture as lf
+
+import tensorcircuit as tc
+
+from tensorcircuit.templates.lattice import (
+    ChainLattice,
+    SquareLattice,
+    CustomizeLattice,
+)
+from tensorcircuit.templates.hamiltonians import (
+    heisenberg_hamiltonian,
+    rydberg_hamiltonian,
+)
+
+PAULI_X = np.array([[0, 1], [1, 0]], dtype=complex)
+PAULI_Y = np.array([[0, -1j], [1j, 0]], dtype=complex)
+PAULI_Z = np.array([[1, 0], [0, -1]], dtype=complex)
+PAULI_I = np.eye(2, dtype=complex)
+
+
+class TestHeisenbergHamiltonian:
+    """
+    Test suite for the heisenberg_hamiltonian function.
+    """
+
+    def test_empty_lattice(self):
+        """
+        Test that an empty lattice produces a 0x0 matrix.
+        """
+        empty_lattice = CustomizeLattice(
+            dimensionality=2, identifiers=[], coordinates=[]
+        )
+        h = heisenberg_hamiltonian(empty_lattice)
+        assert h.shape == (1, 1)
+        assert h.nnz == 0
+
+    def test_single_site(self):
+        """
+        Test that a single-site lattice (no bonds) produces a 2x2 zero matrix.
+        """
+        single_site_lattice = ChainLattice(size=(1,), pbc=False)
+        h = heisenberg_hamiltonian(single_site_lattice)
+        assert h.shape == (2, 2)
+        assert h.nnz == 0
+
+    @pytest.mark.parametrize("backend", [lf("npb"), lf("tfb"), lf("jaxb")])
+    def test_two_sites_chain(self, backend):
+        """
+        Test a two-site chain against a manually calculated Hamiltonian.
+        This is the most critical test for scientific correctness.
+        """
+        lattice = ChainLattice(size=(2,), pbc=False)
+        j_coupling = -1.5  # Test with a non-trivial coupling constant
+        h_generated = heisenberg_hamiltonian(lattice, j_coupling=j_coupling)
+
+        # Manually construct the expected Hamiltonian: H = J * (X_0X_1 + Y_0Y_1 + Z_0Z_1)
+        xx = np.kron(PAULI_X, PAULI_X)
+        yy = np.kron(PAULI_Y, PAULI_Y)
+        zz = np.kron(PAULI_Z, PAULI_Z)
+        h_expected = j_coupling * (xx + yy + zz)
+
+        assert h_generated.shape == (4, 4)
+        print(tc.backend.to_dense(h_generated))
+        assert np.allclose(tc.backend.to_dense(h_generated), h_expected, atol=1e-5)
+
+    def test_square_lattice_properties(self):
+        """
+        Test properties of a larger lattice (2x2 square) without full matrix comparison.
+        """
+        lattice = SquareLattice(size=(2, 2), pbc=True)  # 4 sites, 8 bonds with PBC
+        h = heisenberg_hamiltonian(lattice, j_coupling=1.0)
+
+        assert h.shape == (16, 16)
+        assert h.nnz > 0
+        h_dense = tc.backend.to_dense(h)
+        assert np.allclose(h_dense, h_dense.conj().T)
+
+
+class TestRydbergHamiltonian:
+    """
+    Test suite for the rydberg_hamiltonian function.
+    """
+
+    def test_single_site_rydberg(self):
+        """
+        Test a single atom, which should only have driving and detuning terms.
+        """
+        lattice = ChainLattice(size=(1,), pbc=False)
+        omega, delta, c6 = 2.0, 0.5, 100.0
+        h_generated = rydberg_hamiltonian(lattice, omega, delta, c6)
+
+        h_expected = (omega / 2.0) * PAULI_X + (delta / 2.0) * PAULI_Z
+
+        assert h_generated.shape == (2, 2)
+        assert np.allclose(tc.backend.to_dense(h_generated), h_expected)
+
+    def test_two_sites_rydberg(self):
+        """
+        Test a two-site chain for Rydberg Hamiltonian, including interaction.
+        """
+        lattice = ChainLattice(size=(2,), pbc=False, lattice_constant=1.5)
+        omega, delta, c6 = 1.0, -0.5, 10.0
+        h_generated = rydberg_hamiltonian(lattice, omega, delta, c6)
+
+        v_ij = c6 / (1.5**6)
+
+        h1 = (omega / 2.0) * (np.kron(PAULI_X, PAULI_I) + np.kron(PAULI_I, PAULI_X))
+        z0_coeff = delta / 2.0 - v_ij / 4.0
+        z1_coeff = delta / 2.0 - v_ij / 4.0
+        h2 = z0_coeff * np.kron(PAULI_Z, PAULI_I) + z1_coeff * np.kron(PAULI_I, PAULI_Z)
+        h3 = (v_ij / 4.0) * np.kron(PAULI_Z, PAULI_Z)
+
+        h_expected = h1 + h2 + h3
+
+        assert h_generated.shape == (4, 4)
+        h_generated_dense = tc.backend.to_dense(h_generated)
+
+        assert np.allclose(h_generated_dense, h_expected)
+
+    def test_zero_distance_robustness(self):
+        """
+        Test that the function does not crash when two atoms have zero distance.
+        """
+        lattice = CustomizeLattice(
+            dimensionality=2,
+            identifiers=[0, 1],
+            coordinates=[[0.0, 0.0], [0.0, 0.0]],
+        )
+
+        try:
+            h = rydberg_hamiltonian(lattice, omega=1.0, delta=1.0, c6=1.0)
+            # The X terms contribute 8 non-zero elements.
+            # The Z terms (Z0+Z1) have diagonal elements that cancel out,
+            # resulting in only 2 non-zero elements. Total nnz = 8 + 2 = 10.
+            assert h.nnz == 10
+        except ZeroDivisionError:
+            pytest.fail("The function failed to handle zero distance between sites.")
+
+    @pytest.mark.parametrize("backend", [lf("npb"), lf("tfb"), lf("jaxb")])
+    def test_anisotropic_heisenberg(self, backend):
+        """
+        Test the anisotropic Heisenberg model with different Jx, Jy, Jz.
+        """
+        lattice = ChainLattice(size=(2,), pbc=False)
+        j_coupling = [-1.0, 0.5, 2.0]  # Jx, Jy, Jz
+        h_generated = heisenberg_hamiltonian(lattice, j_coupling=j_coupling)
+
+        # Manually construct the expected Hamiltonian
+        jx, jy, jz = j_coupling
+        xx = np.kron(PAULI_X, PAULI_X)
+        yy = np.kron(PAULI_Y, PAULI_Y)
+        zz = np.kron(PAULI_Z, PAULI_Z)
+        h_expected = jx * xx + jy * yy + jz * zz
+
+        h_generated_dense = tc.backend.to_dense(h_generated)
+        assert h_generated_dense.shape == (4, 4)
+        assert np.allclose(h_generated_dense, h_expected)