added Fermionic and Jordan-Wigner MPO encodings of 1D Fermi-Hubbard model#220
Merged
aaronleesander merged 22 commits intoMay 15, 2026
Merged
Conversation
…qs into 1D_Fermi_Hubbard_MPO
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
aaronleesander
changed the title
Member
|
@CodeRabbit full review |
Contributor
✅ Actions performedFull review triggered. |
Contributor
📝 WalkthroughSummary by CodeRabbit
WalkthroughThis PR adds MPO.fermi_hubbard_1d() with fermionic and Jordan–Wigner builders, validates boundary-slicing for length==1, adds dense-reference tests covering both representations (including length=1 and cross-checks), adds a MyST-NB example and toctree entry, updates CHANGELOG, and changes the local pre-commit ChangesFermi-Hubbard MPO Feature
Sequence DiagramsequenceDiagram
participant Client
participant MPO_factory as MPO.fermi_hubbard_1d
participant FermionicBuilder as _fermi_hubbard_1d_fermionic
participant JWBuilder as _fermi_hubbard_1d_jordan_wigner
participant Validator as check_if_valid_mpo
Client->>MPO_factory: call(length, t, u, jordan_wigner)
MPO_factory->>MPO_factory: validate inputs (length / even check for JW)
alt jordan_wigner == False
MPO_factory->>FermionicBuilder: build fermionic MPO tensors
FermionicBuilder->>Validator: check_if_valid_mpo(MPO)
Validator-->>FermionicBuilder: valid/raise
else jordan_wigner == True
MPO_factory->>JWBuilder: build JW Pauli-string MPO via from_pauli_sum
end
MPO_factory-->>Client: return MPO
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 7
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/examples/fermi_hubbard_mpo.md (1)
41-58: 🧹 Nitpick | 🔵 Trivial | 💤 Low valueConsider adding a trailing newline at end of file.
Most text files conventionally end with a newline character. While not critical, adding one would align with common style practices.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/examples/fermi_hubbard_mpo.md` around lines 41 - 58, Add a single trailing newline character to the end of the Markdown file so it ends with a newline (update docs/examples/fermi_hubbard_mpo.md); no content changes needed—just ensure the file terminates with a newline after the final paragraph referencing MPO.fermi_hubbard_1d and create_1d_fermi_hubbard_circuit.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/mqt/yaqs/core/data_structures/networks.py`:
- Around line 1559-1567: The outer method redundantly checks "length < 1" before
calling cls._fermi_hubbard_1d_fermionic, duplicating validation already done
inside that helper; remove the redundant block (the "if length < 1: ... raise
ValueError" and its message) so the public method only validates the
Jordan-Wigner-specific even/≥2 case and then delegates to
_fermi_hubbard_1d_fermionic (preserving that helper’s own length validation),
leaving _fermi_hubbard_1d_jordan_wigner and _fermi_hubbard_1d_fermionic as the
single sources of truth for input checks.
- Around line 1521-1558: The JW branch of fermi_hubbard_1d currently builds only
the (U/4) Z_up Z_down on each site and omits the constant and single-Z
chemical-potential pieces, so the JW MPO is not algebraically equivalent to U
n_up n_down; update the jordan_wigner=True construction in fermi_hubbard_1d to
expand U n_up n_down = (U/4)(I - Z_up - Z_down + Z_up Z_down) by adding per-site
(U/4)*I and single-site (-U/4)*Z_up and (-U/4)*Z_down terms alongside the
existing (U/4)*Z_up Z_down term (ensure the sign and prefactors match), and
adjust how those local operator terms are inserted into the MPO tensors so the
JW and non-JW branches represent the same Hamiltonian up to the JW mapping.
- Around line 1604-1613: The code creates tensors via a fresh transpose for
tensors[0] and tensors[-1], causing an overwrite when length == 1 and producing
incompatible leg shapes for to_matrix(); fix by reusing the already-transposed
slot and applying the left and right slices on the same array instead of
re-transposing: after building tensors (the list comp using tensor and
np.transpose), mutate tensors[0] in-place (e.g. tensors[0] =
tensors[0][:,:,0:1,:].astype(np.complex128)) and tensors[-1] =
tensors[-1][:,:,:,5:6].astype(np.complex128), and handle the length == 1 case by
chaining both slices on tensors[0] so it ends up with the correct
(bond,left,right) shapes; apply the same change in the bose_hubbard builder;
keep check_if_valid_mpo() and to_matrix() behavior unchanged.
- Around line 1575-1602: The builder labeled "fermionic" actually implements
two-species hardcore bosons because c_up/c_down lack Jordan-Wigner Z-strings;
fix by either (A) implementing proper JW signs: modify c_down and c_down_dag to
include the parity-string (Z) factor so {c_up,c_down}=0 (adjust the
onsite/tensor entries using c_up, c_down, c_up_dag, c_down_dag accordingly), or
(B) update the function/docstring for the fermi_hubbard builder (and the dense
reference _fermi_hubbard_1d_fermionic_dense) to state this is a non-JW
hardcore-boson convention and recommend using jordan_wigner=True for true
fermions; ensure tests reflect the chosen behavior.
- Around line 1521-1543: The raw docstring for the 1D Fermi-Hubbard MPO (the
r""" docstring in the function that constructs the Hamiltonian MPO) contains
doubled backslashes (e.g. \\rangle, \\sum, \\dagger, \\uparrow) which produces
literal double backslashes in Sphinx; either remove the leading r from the
docstring and keep the doubled backslashes, or keep the r prefix and change all
doubled backslashes to single backslashes (e.g. \rangle, \sum, \dagger,
\uparrow) so :math: directives render correctly; apply the same fix in
tests/core/data_structures/test_networks.py lines ~296–298 where the doubled
escapes appear.
In `@tests/core/data_structures/test_networks.py`:
- Around line 521-553: Add tests to cover the single-site fermionic case and the
fermion↔JW cross-representation equivalence: create a test named e.g.
test_fermi_hubbard_1d_length_one that calls MPO.fermi_hubbard_1d(1, t, u) and
compares mpo.to_matrix() to _fermi_hubbard_1d_fermionic_dense(1, t, u) with
np.testing.assert_allclose, and add a test (e.g.
test_fermi_hubbard_1d_cross_representation) that for small L compares
MPO.fermi_hubbard_1d(L, t, u).to_matrix() to MPO.fermi_hubbard_1d(2*L, t, u,
jordan_wigner=True).to_matrix() under the 4↔pair-of-qubits isomorphism (use the
existing dense builders _fermi_hubbard_1d_fermionic_dense and
_fermi_hubbard_1d_jordan_wigner_dense or compare via appropriate basis
reshaping) to catch the on-site U-term mismatch noted in networks.py.
- Around line 292-336: The test's dense reference
(_fermi_hubbard_1d_fermionic_dense) is recreating the same on-site tensor
construction as the MPO (c_up = kron(c,I), c_down = kron(I,c)) and therefore
cannot detect a missing Jordan–Wigner (JW) string in the MPO; replace the
reference construction with an independent JW-based one: build a length*2 chain
of spinless fermion creation/annihilation operators (single-qubit c, c_dag) with
proper JW Z-strings between them to implement fermionic anticommutation,
assemble the full 2^(2*L) dense Hamiltonian on the interleaved chain, then
group/site-pair the interleaved sites into local dimension-4 sites by
reshaping/partial tensoring to get a (4**L,4**L) matrix and compare that to
MPO.fermi_hubbard_1d (or to the current _fermi_hubbard_1d_fermionic_dense) via
unitary equivalence or norm difference; ensure the independent construction
references the single-site c/c_dag (not c_up/c_down) and explicitly includes JW
Z-strings so the test fails if the MPO omits them.
---
Outside diff comments:
In `@docs/examples/fermi_hubbard_mpo.md`:
- Around line 41-58: Add a single trailing newline character to the end of the
Markdown file so it ends with a newline (update
docs/examples/fermi_hubbard_mpo.md); no content changes needed—just ensure the
file terminates with a newline after the final paragraph referencing
MPO.fermi_hubbard_1d and create_1d_fermi_hubbard_circuit.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 46ff4f13-969b-460e-a59b-e9c1cb4a9b8d
📒 Files selected for processing (6)
.pre-commit-config.yamlCHANGELOG.mddocs/examples/fermi_hubbard_mpo.mddocs/index.mdsrc/mqt/yaqs/core/data_structures/networks.pytests/core/data_structures/test_networks.py
Member
|
@CodeRabbit full review |
Contributor
✅ Actions performedFull review triggered. |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.pre-commit-config.yaml:
- Line 128: The pre-commit hook's language key was changed to "system" which is
not a recognized pre-commit language; revert the value for the YAML key
"language" from "system" back to "unsupported" (or document why "system" is
required) so the hook uses the supported "unsupported" language type; look for
the occurrence of the "language:" key with value "system" and update it to
"unsupported" (or add a comment explaining the deliberate deviation).
In `@CHANGELOG.md`:
- Around line 14-15: Add a missing PR reference definition for the tag [`#220`]
used in CHANGELOG.md: locate the PR links/references section in CHANGELOG.md and
add a reference entry for [`#220`] with the correct URL and optional author
attribution so the changelog link resolves (the tag to add is "[`#220`]" that
matches the entry "- added Fermionic and Jordan-Wigner MPO encodings...").
Ensure the reference uses the same markdown link style as the other PR
definitions in the file.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 921633e6-af85-41a9-bf89-cdffc780b41d
📒 Files selected for processing (6)
.pre-commit-config.yamlCHANGELOG.mddocs/examples/fermi_hubbard_mpo.mddocs/index.mdsrc/mqt/yaqs/core/data_structures/networks.pytests/core/data_structures/test_networks.py
aaronleesander
approved these changes
May 15, 2026
aaronleesander
merged commit 94994dc
into
munich-quantum-toolkit:main
21 of 23 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Implementation of a MPO construction for the one-dimensional Fermi-Hubbard model both in the fermionic space and in the qubit space after applying the Jordan-Wigner transformation.
Checklist: