Add parameterized Qiskit LUCJ ansatz

[MarcoBarroca]

Summary

This adds a native Qiskit parameterized implementation of the spin-balanced LUCJ ansatz.

I had an internal prototype for this path, and spent time converting it into a proper ffsim PR: public helpers, input validation, tests, and a docs example, rather than just adding the prototype directly.

The main entry point is ffsim.qiskit.lucj_spin_balanced_ansatz, which builds the merged LUCJ circuit form used after ffsim.qiskit.PRE_INIT. The circuit exposes Qiskit parameters directly on the orbital-rotation and diagonal Coulomb gates, so it can be optimized in standard Qiskit workflows.

Closes #411.

Details

• Adds ffsim.qiskit.lucj_spin_balanced_ansatz.
• Adds lucj_spin_balanced_parameters for initializing the parameterized circuit from an existing spin-balanced UCJ operator.
• Adds lucj_spin_balanced_parameters_from_t2 for initializing from CCSD amplitudes.
• Supports restricted same-spin and opposite-spin interaction_pairs.
• Documents the Qiskit workflow in the LUCJ how-to guide.
• Tests equivalence against the existing UCJ-to-Qiskit path, including restricted interactions and t2 initialization.

Validation

Locally I ran:

• ruff check python/ffsim/qiskit/__init__.py python/ffsim/qiskit/lucj.py tests/python/qiskit/lucj_test.py
• ruff format --check python/ffsim/qiskit/__init__.py python/ffsim/qiskit/lucj.py tests/python/qiskit/lucj_test.py
• ruff check docs/how-to-guides/qiskit-lucj.ipynb
• pytest tests/python/qiskit/lucj_test.py
• pytest tests/python/qiskit/gates/ucj_test.py tests/python/variational/ucj_spin_balanced_test.py
• pytest tests/python/qiskit

[CLAassistant]

All committers have signed the CLA.

[MarcoBarroca]

I’m going to keep this as a draft for now while I do a deeper local validation pass.

In addition to the committed tests, I want to check a few things more exhaustively before marking this ready for review:

• random spin-balanced UCJ operators against the existing UCJOpSpinBalancedJW -> PRE_INIT -> decompose path
• random state evolution checks, including fixed particle-number sectors
• restricted interaction_pairs cases for both same-spin and opposite-spin interactions
• t2-based initialization across zero, dense, sparse, padded, and multi-repetition inputs
• parameter ordering and binding behavior on the generated Qiskit circuit
• validation behavior for bad inputs and duplicate/lower-triangular interaction pairs

The main thing I want to be sure of is that the new parameterized circuit is not just structurally reasonable, but actually matches the existing ffsim/Qiskit LUCJ behavior across representative cases. Once that internal pass looks clean, I’ll move this out of draft.

[MarcoBarroca]

I did the extra local validation I wanted to do before marking this ready.

Besides the tests in the PR, I ran randomized checks against the existing ffsim/Qiskit LUCJ path. That included full-state evolution, fixed particle-number sectors, restricted interaction pairs, and t2-based initialization cases. I also checked parameter ordering, parameter binding, and a few invalid-input paths.

Everything matched to numerical precision. The generated parameterized circuits agreed with the existing merged UCJ circuit behavior up to global phase, including the restricted-interaction cases.

Marking this ready for review now.