Skip to content

refactor(circuit)!: build UCC from an ffsim UCCSD operator - #324

Open
mrossinek wants to merge 1 commit into
ucj-from-ffsim-opfrom
ucc-from-ffsim-op
Open

refactor(circuit)!: build UCC from an ffsim UCCSD operator#324
mrossinek wants to merge 1 commit into
ucj-from-ffsim-opfrom
ucc-from-ffsim-op

Conversation

@mrossinek

Copy link
Copy Markdown
Member

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.

Refs #318

@coveralls

coveralls commented Sep 4, 2026

Copy link
Copy Markdown

Coverage Status

Coverage is 98.165%ucc-from-ffsim-op into ucj-from-ffsim-op. No base build found for ucj-from-ffsim-op.

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants