refactor(circuit)!: build UCC from an ffsim UCCSD operator - #324
Open
mrossinek wants to merge 1 commit into
Open
refactor(circuit)!: build UCC from an ffsim UCCSD operator#324mrossinek wants to merge 1 commit into
mrossinek wants to merge 1 commit into
Conversation
Mirrors the UCJ change: the gate reimplemented the amplitude conventions and the parameter-vector packing alongside the part that is actually this package's concern, namely turning the amplitudes into a mapper-agnostic fermionic circuit. The first half duplicated ffsim, so this narrows the gate to the second half and takes the ffsim operator directly. Verified rather than assumed: the removed `num_parameters`/`from_parameters` agreed with ffsim's `n_params`/`from_parameters` (14 parameters at norb=4, nocc=2, with identical t1/t2), and a restricted operator applied through this gate reproduces ffsim's own state vector exactly on coupled-cluster amplitudes. Unlike UCJ, this drops capability ffsim cannot currently replace, which is why it is a separate commit: `from_t_amplitudes`, the `spinless` variant and the opt-in `antisymmetric` parameterization all go. Users needing those can build an Evolution over their own cluster operator, which also hands them control over the Trotter ordering of its terms. Note that ffsim ships no Qiskit gate for UCCSD at all, so this gate remains the only route from one of its UCCSD operators to a circuit -- under Jordan-Wigner or any other encoding. What remains is the part with no ffsim equivalent: the cluster generator and its conjugate-paired grouping, which keeps every factor of the product formula Hermitian and hence unitary. A term-by-term split would not even preserve the norm, so the grouping tests are kept verbatim; the two that previously reached this machinery only through the spinless variant are ported to the restricted one, which exercises the same paths on a spinful register. One pre-existing convention difference is now documented rather than changed: the cluster operator only ever sees the part of a same-spin t2 that is symmetric under the simultaneous exchange t2[i,j,a,b] = t2[j,i,b,a], while ffsim reads the raw tensor. Coupled-cluster amplitudes always carry that symmetry (verified against PySCF), so the two agree exactly on any physical input; only a hand-built asymmetric tensor can tell them apart. As with UCJ, the class docstring's example now needs ffsim, so it is gated with `.. skip: start if(not HAS_FFSIM)` (the SkipParser this relies on is registered in python/conftest.py by the preceding commit). Without the guard the example fails collection on Windows, where ffsim cannot be installed. Refs #318 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
mrossinek
force-pushed
the
ucc-from-ffsim-op
branch
from
September 4, 2026 15:41
a688fc7 to
8a3da5c
Compare
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.
Mirrors the UCJ change: the gate reimplemented the amplitude conventions and the parameter-vector packing alongside the part that is actually this package's concern, namely turning the amplitudes into a mapper-agnostic fermionic circuit. The first half duplicated ffsim, so this narrows the gate to the second half and takes the ffsim operator directly.
Verified rather than assumed: the removed
num_parameters/from_parametersagreed with ffsim'sn_params/from_parameters(14 parameters at norb=4, nocc=2, with identical t1/t2), and a restricted operator applied through this gate reproduces ffsim's own state vector exactly on coupled-cluster amplitudes.Unlike UCJ, this drops capability ffsim cannot currently replace, which is why it is a separate commit:
from_t_amplitudes, thespinlessvariant and the opt-inantisymmetricparameterization all go. Users needing those can build an Evolution over their own cluster operator, which also hands them control over the Trotter ordering of its terms. Note that ffsim ships no Qiskit gate for UCCSD at all, so this gate remains the only route from one of its UCCSD operators to a circuit -- under Jordan-Wigner or any other encoding.What remains is the part with no ffsim equivalent: the cluster generator and its conjugate-paired grouping, which keeps every factor of the product formula Hermitian and hence unitary. A term-by-term split would not even preserve the norm, so the grouping tests are kept verbatim; the two that previously reached this machinery only through the spinless variant are ported to the restricted one, which exercises the same paths on a spinful register.
One pre-existing convention difference is now documented rather than changed: the cluster operator only ever sees the part of a same-spin t2 that is symmetric under the simultaneous exchange t2[i,j,a,b] = t2[j,i,b,a], while ffsim reads the raw tensor. Coupled-cluster amplitudes always carry that symmetry (verified against PySCF), so the two agree exactly on any physical input; only a hand-built asymmetric tensor can tell them apart.
Refs #318