Merge functionalities into old cc_<geminal>.py files from their _NEW counterpart

[q-pratz-chem]

Consolidating the legacy CC/geminal wavefunction implementations with their corresponding _NEW variants.

The primary goal of this PR is to:

1. Copy missing functionality from _NEW implementations into the canonical/legacy implementations,
2. Verify that the merged implementation preserves existing functionality,
3. Resolve inconsistencies between old and _NEW implementations where needed,
4. Improve documentation and mathematical consistency,
5. Eventually, remove the duplicated _NEW files once consolidation is complete.

This PR focuses mainly on review, consolidation, documentation cleanup, and targeted testing additions where functionality differences existed.

---

Main Changes in Files

pccd_ap1rog.py

Merged functionality from _NEW into the canonical implementation, including:

• s_type functionality and overlap filtering logic,
• _olp_double_derivative,
• associated documentation updates,
• and new tests for the merged functionality.

The seniority-0 reference-wavefunction check from _NEW was not adopted because it incorrectly used slicing over :nspatial instead of nelec // 2.

Important Note

The _NEW implementation of _olp_deriv and _olp_double_derivative uses:

occ_indices(sd)

rather than:

occ_indices(sd2)

This behavior was preserved for now because the implementation was used in calculations associated with the paper results. Further investigation is still needed to confirm whether this behavior is theoretically correct.

---

ap1rog_spin.py

ap1rog_generalized.py

apg1ro_d.py

apg1ro_sd.py

apset1rog_d.py

apset1rog_sd.py

No functional differences were found between the canonical and _NEW implementations (aside from parent import filenames, which were left unchanged since only old files are modified to accommodate the functionalities from their _NEW variants).

For these files:

• Wavefunction equations and docstrings were corrected and modernized,
• Excitation-operator structure and overlap-generation workflow were clarified,
• Mathematical notation was updated to better reflect the actual implementation.

No new tests were added for these files because no functionality changes were introduced during the merge review. Additional tests can be included to improve test coverage through a separate branch.

---

Additional Notes

A major focus of this PR was improving consistency between:

• the mathematical ansatz described in the docstrings,
• the excitation operators actually generated in code,
• and the overlap/filtering workflow implemented in the CC infrastructure.

Older layered operator expressions- a series of parentheses for doubles and single operators- could lead to confusion on the ordering of operators. So, those were replaced with excitation-pool formulations that more accurately reflect the implementation behavior.

[kzsigmond]

The docstrings are on the longer side, and there is some repetition in a few places. I didn’t annotate every instance, but the main patterns I noticed are:

• Repeated description of the excitation pool (appearing both before and after the equation)
• Some inconsistency in orbital notation. At times general indices (e.g. pq) are used, while elsewhere the text refers to excitations from occupied to virtual orbitals. It might improve clarity to standardize notation, e.g. i, j for occupied, a, b for virtual, and p, q for general orbitals, as is commonly used in quantum chemistry.
• The description of the seniority restriction could likely be shortened. For end users, it is usually sufficient to know what is being restricted; the equations here don’t add much additional usability value and may be more useful at the developer or reference level.

---

One possible structure for the docstrings could be:

1. Brief equation for the wavefunction, with concise explanation of symbols where needed (e.g. excitation pool definitions)
2. Key behavioral details (e.g. single excitations can be restricted via s_type, refwfn must be a seniority-0 reference). This can stay fairly high-level since the detailed parameter behavior is already documented in s_type and refwfn
3. Pointer to the relevant paper for users who want the full formalism

The main goal of the docstrings is to explain the API and how to use it, rather than fully reproducing the level of detail of a paper. In fact, too much detail can sometimes obscure important usage constraints, such as the requirement that refwfn has seniority 0.

---

As a longer-term improvement (not necessary for this release), it might also be useful to add a separate reStructuredText page for geminal wavefunctions in the documentation. That could be a better place for the detailed discussion.

[q-pratz-chem]

The conflict in pccd_ap1rog_NEW.py and other *_NEW.py files is intentional since this file is being deleted as part of this PR's consolidation work. The functionality has been merged into pccd_ap1rog.py. I can create a small PR to delete those files from mqcomplab/main first; once it gets approved, this conflict should be resolved.