Repository navigation
Fill out the docs for the Boson, Fermion, Hubbard and t-J operators - #58
Merged
Merged
Conversation
Codecov Report❌ Patch coverage is
🚀 New features to boost your workflow:
|
Rewrite the two stub pages to the structure of the spin operator page: conventions with basis ordering and symmetry sectors, an operator overview table, and the autodocs API section. Upgrade the corresponding docstrings to match, adding the math definitions, matrix elements and `Compatible symmetries:` lines that were missing. Also add the default-symmetry method to `boson_space`, which every other module has and its own docstring already advertised, and bump the Documenter compat bound to 1.9, the version that introduced `checkdocs = :public`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Closes the main part of #45. Both stub pages now follow the structure of the spin operator page: conventions with basis ordering and symmetry sectors, an operator overview table, and the autodocs API section. Since both modules take two independent symmetry arguments, the overview tables carry separate particle and spin columns. This is exact rather than an approximation: every availability predicate in the test suite factorizes into an independent condition per symmetry axis. The basis-ordering sections document the parity-sorted reference order (|0>, |updn>, |up>, |dn> for Hubbard) rather than the enumeration order used in the prose so far, and give a recipe for reading off the dense order of the symmetric spaces instead of tabulating it, since it follows TensorKit's sector sorting and is not part of the interface. The t-J page additionally documents the slave-fermion keyword, including the warning that the transformation does not distribute over tensor products, and the projection relation to the Hubbard model. Upgrade the docstrings of both modules to match: math definitions where they were missing, and an explicit `Compatible symmetries:` line replacing the ad-hoc prose notes. Since #57 made the t-J operator docstrings inherit their description from the Hubbard docstring of the same name, that prose now lives in `HubbardOperators` and reaches `TJOperators` through the inheritance, which imposes two rules on it: - Anything true only of the Hubbard space goes into an admonition, the mechanism #57 already uses to keep the staggered-gauge note out of the t-J docs. That now also covers the listings of nonzero matrix elements, which are basis-specific, and the remarks about `SU2Irrep` particle symmetry, which t-J does not have. The shared prose is worded to hold in both spaces, which is why the eigenvalue listings characterize the states they act on instead of enumerating a fixed basis. - The symmetry line is derived rather than restated. t-J supports exactly the Hubbard combinations minus `SU2Irrep` particle symmetry, because the eta-pairing doublet (|updn>, |0>) loses its doubly occupied state to the projection, so `_project_symmetries` strips that one entry from the inherited line. The spin symmetries carry over verbatim, for all 31 operators of the registry. Along the way: - `HubbardOperators.h_num` is `1 - n`, so it takes the value -1 on the doubly occupied state rather than counting holes as its docstring claimed. Document what it actually does, and point to the t-J module, where it is a genuine projector. - Fix a few typos and an inconsistent float literal. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…metries" `h_num` was implemented as `1 - n`, which returns -1 on the doubly occupied state instead of counting holes as its docstring described. Implement it as the projector onto the empty state, `(1 - nꜛ)(1 - nꜜ)`, matching both the documented intent and `TJOperators.h_num`. The bug survived because it is invisible through the t-J projection: the discrepancy lives entirely on the doubly occupied state, which the projector removes, so `TJOperators.h_num` agreed either way. Add tests pinning down the two properties that distinguish them, idempotency and `nʰ + n = 1 + nꜛnꜜ`. Symmetry availability is unchanged: the projector onto the empty state is still a spin scalar and still not an eta-pairing scalar. With the implementation fixed the docstring no longer has to warn that the operator contradicts its own name, and what remains of the caveat -- that the doubly occupied state is not a hole -- is Hubbard-specific, so it moves into an admonition and stops being inherited by `TJOperators.h_num`. The pointer to `ud_num` moves along with it, which it has to: an unqualified `@ref` to `ud_num` in the shared prose cannot resolve on the t-J page, since that module has no such binding. Also harmonize on "Supported symmetries" package-wide, replacing the "Compatible symmetries" wording used in the docstrings and in the quantum gates overview table. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Replace the LaTeX commands that have a direct unicode equivalent, matching the
convention the package already used for kets, arrows and greek letters:
\rangle, \uparrow, \dagger, \otimes, \eta, \mapsto, \cdot, \ldots, \mathbf{S}
and friends, along with the simple radicals \sqrt{2} and \sqrt{n}.
Kept as LaTeX where there is no unicode equivalent, or where the command is
structural rather than a symbol: \mathrm, \text, \tfrac, \underbrace, the
pmatrix environments, the spacing macros, and the two radicals that have to
span a compound expression.
Validating every math expression against KaTeX turned up two rendering bugs
that the docs build cannot catch, since Documenter renders math in the browser:
`↤` and `bꜛ`/`bꜜ` have no font metrics and came out blank in math mode. Move
the former into the fenced matrix-element blocks used elsewhere in the module,
and the latter into code spans, where they belong anyway.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Yue-Zhengyuan
previously approved these changes
Jul 31, 2026
Member
|
There are still some mentions of where the nonzero elements are in the operators, which I think are unnecessary. |
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
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.
Closes #45.
spinoperators.mdandquantumgates.mdwere full documentation pages; the other four were 9-line bare@autodocsstubs. This brings all six to the same structure — Conventions (basis ordering, symmetry sectors), an operator overview table, then the@autodocsAPI section. Since@autodocsonly renders what the docstrings contain, the docstrings were upgraded in step: math definitions, matrix elements, and an explicitSupported symmetries:line where Boson/Fermion had none and Hubbard had only ad-hoc prose.Rendered preview
Mostly prose, tables and math, so much easier to review rendered than as a diff:
Full preview: https://quantumkithub.github.io/TensorKitTensors.jl/previews/PR58/
Notable decisions
has_*(P, S)predicate in the test suite factorizes into an independent condition per axis.|0⟩, |↑↓⟩, |↑⟩, |↓⟩, not the enumeration used so far, which is not an index order anywhere and read as a competing convention againstbasis_transform.slave_fermion, including the warning thattransform_slave_fermiondoes not distribute over⊗.Fitting the t-J docstrings to #57
#57 made each t-J operator docstring inherit its description from the
HubbardOperatorsdocstring of the same name, so this prose lives inHubbardOperatorsand reachesTJOperatorsthrough the inheritance. Two rules follow:SU2Irrep-particle remarks (t-J has no such symmetry). Shared prose is worded to hold in both spaces, so eigenvalue listings characterize the states they act on rather than enumerate a fixed basis.SU2Irrepparticle symmetry — the η-pairing doublet(|↑↓⟩, |0⟩)loses its doubly occupied state to the projection — so_project_symmetriesstrips that entry from the inherited line. Spin symmetries carry over verbatim for all 31 operators.Trade-off worth flagging: per-operator prose true only of t-J has no home under this design (that
nnever exceeds one, thatnʰ + n = 1). Both are stated on the t-J page instead.Bugs found along the way
HubbardOperators.h_numdid not count holes. It was1 - n, returning-1on the doubly occupied state; now(1 - nꜛ)(1 - nꜜ), the projector onto the empty state. Invisible through the t-J projection — the discrepancy lives entirely on|↑↓⟩, which the projector removes — soTJOperators.h_numagreed either way. Tests now pin down idempotency andnʰ + n = 1 + nꜛnꜜ.boson_space(; cutoff)was aMethodError, unlike every other module's space constructor, while its docstring already advertised the symmetry argument as optional.@refcannot name a Hubbard-only binding.h_num'sSee also ud_numbroke cross-references on the t-J page; it moves into the admonition with the rest of the double-occupancy caveat.Also
Documentercompat bumped to1.9, which introducedcheckdocs = :public(on 1.8.x the symbol is unvalidated and silently disables the check).operatorpagesputs Hubbard before t-J, since the t-J page refers to it several times. Harmonized onSupported symmetriespackage-wide. Assorted typos, andT→eltinFermionOperatorsfor consistency.Verification
🤖 Generated with Claude Code