Add tests for Hamiltonian class in tests/ folder

[Copilot]

No tests existed for qmp/hamiltonian/hamiltonian.py. This PR adds a pytest test suite covering all four public methods of Hamiltonian.

Test model

All tests use a 4-site 1D spinless free-fermion Hamiltonian (kind="fermi", n_qubytes=1):

H = Hamiltonian(
    {
        # Number operators (coefficient 1)
        ((0, 1), (0, 0)): 1.0,  # n₀
        ((1, 1), (1, 0)): 1.0,  # n₁
        ((2, 1), (2, 0)): 1.0,  # n₂
        ((3, 1), (3, 0)): 1.0,  # n₃
        # Nearest-neighbor hopping (coefficient 2)
        ((0, 1), (1, 0)): 2.0,  # c†₀c₁
        ((1, 1), (0, 0)): 2.0,  # c†₁c₀
        ((1, 1), (2, 0)): 2.0,  # c†₁c₂
        ((2, 1), (1, 0)): 2.0,  # c†₂c₁
        ((2, 1), (3, 0)): 2.0,  # c†₂c₃
        ((3, 1), (2, 0)): 2.0,  # c†₃c₂
    },
    kind="fermi",
)

The number operator coefficient (1) and hopping coefficient (2) are intentionally different to make it easy to verify both contributions independently. Hopping is nearest-neighbor only, matching a 1D spinless free-fermion chain. In the 1-particle sector the Hamiltonian matrix is tridiagonal:

[[1, 2, 0, 0],
 [2, 1, 2, 0],
 [0, 2, 1, 2],
 [0, 0, 2, 1]]

Coverage (22 tests)

• diagonal_term — vacuum, single-particle (n coefficient = 1), two non-adjacent particles (= 2), all occupied (= 4), batched 1-particle sector
• apply_within — distinguishing n vs t coefficients (H|site1⟩ gives [2, 1, 2]), nearest-neighbor-only hopping, Pauli-blocked diagonal from fully occupied state, complex amplitudes, full 1-particle sector matrix row sums
• find_relative — finds both neighbours, count_selected truncation (1 vs 2 results), Pauli-blocked fully occupied state, custom configs_exclude
• list_relative — lists ALL connections (vs find_relative's truncation), amplitude accumulation from multiple input configs, complex psi_i, custom exclusion, two-particle sector

The fixture is scope="session" to compile the C++ JIT extension once per test run.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>添加对hamiltonian.py中的测试</issue_title>
<issue_description>放到 tests文件夹中,

接口说明在hamiltonian.py 和 hamiltonian.cpp

对于apply_within, 可以构造一个 2 qubit 的例子来测试, 后续也可以添加稍微大一点的, 但注意这个是指数增长的, 所以不要太大.
其他3个函数类似.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes 添加对hamiltonian.py中的测试 #205

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[hzhangxyz]

还是改成4 qubit 的吧, 两项目, n + t, t只有相邻的有吧, 相当与是一个一维无自旋自由费米子. 另外 n 和 t的系数分别设置一下, 比如比如一个1 一个 2 . 这样好区分. 还有就是, 我没检查的一点, 也许你已经做了, find relative 是找最大的固定数目个config, 而 list是列出所有的.

[Copilot]

还是改成4 qubit 的吧, 两项目, n + t, t只有相邻的有吧, 相当与是一个一维无自旋自由费米子. 另外 n 和 t的系数分别设置一下, 比如比如一个1 一个 2 . 这��...

Done in 9e09079. The test model is now a 4-site 1D spinless free-fermion chain:

H = Σᵢ nᵢ  +  2 · Σ_{⟨i,j⟩} (c†ᵢcⱼ + c†ⱼcᵢ)

Number-operator coefficient = 1, nearest-neighbor hopping coefficient = 2. Key tests added:

• test_n_and_t_coefficients_are_distinguishable: H|site1⟩ gives [2, 1, 2] for configs [site0, site1, site2] – diagonal is 1 (n), off-diagonal is 2 (t).
• test_count_selected_limits_results: explicitly shows find_relative with count_selected=1 returns 1 config while list_relative returns all 2 neighbours.
• test_amplitudes_accumulate_from_multiple_input_configs: shows list_relative accumulating contributions from two input configs onto the same output config.

[Copilot]

Pull request overview

Adds a new pytest suite for qmp.hamiltonian.Hamiltonian, aiming to cover the four public methods using a small 4-site 1D spinless free-fermion model.

Changes:

• Introduces tests/hamiltonian_test.py covering diagonal_term, apply_within, find_relative, and list_relative.
• Uses a session-scoped fixture to amortize the C++/CUDA extension JIT compilation cost across tests.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The inline ket/binary comments for the config constants (e.g., C_site0, C_site1, …) don’t match the encoding described above (bit 0 = site 0) or the “Selected basis states” table in the module docstring (e.g., 1 corresponds to 0b0001, not |1000⟩). This is likely to confuse future readers when debugging test failures; please update these comments (or explicitly state the ket bit-order convention) so the written bitstrings/kets align with the actual integer values.

Suggested change

	C_site0 = torch.tensor([[1]], dtype=torch.uint8) # |1000⟩ – site 0 occupied
	C_site1 = torch.tensor([[2]], dtype=torch.uint8) # |0100⟩ – site 1 occupied
	C_site2 = torch.tensor([[4]], dtype=torch.uint8) # |0010⟩ – site 2 occupied
	C_site3 = torch.tensor([[8]], dtype=torch.uint8) # |0001⟩ – site 3 occupied
	C_sites02 = torch.tensor([[5]], dtype=torch.uint8) # |1010⟩ – sites 0,2 occupied
	C_sites12 = torch.tensor([[6]], dtype=torch.uint8) # |0110⟩ – sites 1,2 occupied
	C_sites13 = torch.tensor([[10]], dtype=torch.uint8) # |0101⟩ – sites 1,3 occupied
	C_site0 = torch.tensor([[1]], dtype=torch.uint8) # |0001⟩ – site 0 occupied
	C_site1 = torch.tensor([[2]], dtype=torch.uint8) # |0010⟩ – site 1 occupied
	C_site2 = torch.tensor([[4]], dtype=torch.uint8) # |0100⟩ – site 2 occupied
	C_site3 = torch.tensor([[8]], dtype=torch.uint8) # |1000⟩ – site 3 occupied
	C_sites02 = torch.tensor([[5]], dtype=torch.uint8) # |0101⟩ – sites 0,2 occupied
	C_sites12 = torch.tensor([[6]], dtype=torch.uint8) # |0110⟩ – sites 1,2 occupied
	C_sites13 = torch.tensor([[10]], dtype=torch.uint8) # |1010⟩ – sites 1,3 occupied