Preserve cached values in Circuit more granularly

[daxfohl]

This PR improves the resilience of the cached member fields in Circuit. Most importantly, _placement_cache, which is used to speed up Circuit.append() from O(N) to O(1), is made to be resilient and consistent across insert and batch inserts, add and mul operations, and copy. Prior to this PR, performing any of those actions on a circuit would delete the cache, and append would fall back to O(N) behavior from that point on.

Summary of changes:

• _PlacementCache has new methods insert_moment(index, count) and put(index, mop), that update the key indices to account for new moments or operations. Circuit has new corresponding _insert_moments(...) and _put_ops(...) methods to modify the circuit and update the cache atomically, and logic strewn around Circuit has been updated to use those methods when possible.
• Circuit.copy() now preserves all cache values.
• All cached values except _placement_cache are now immutable types, so copy doesn't have to make copies.
• A simple optimization to Moment.with_operations(*ops) gave a 15% speedup in the common case of len(ops)==1.

Overall, the performance of append and insert individually are unaffected by this change; measured time is equal, but the performance when mixing inserts and appends is improved from O(N) to O(1). It also cleans up the code a bit IMO, with less need to place self._mutated() everywhere.

Fixes #7464

[daxfohl]

Okay, I lean toward not making the change in _from_moments. I see a lot of places across the codebase that uses _from_moments or unfreeze to make a quick copy of a circuit, edit some operations (which would destroy the cache anyway), and then copy the result back or re-freeze it. Therefore _from_moments needs to be as fast as possible.

At some point, it would be possible to add a parameter to allow each use case to choose whether to create the cache or not, but that would be a separate PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.37%. Comparing base (ad37bb7) to head (8bac7ec).
⚠️ Report is 96 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7649      +/-   ##
==========================================
- Coverage   99.38%   99.37%   -0.01%     
==========================================
  Files        1090     1090              
  Lines       98248    98317      +69     
==========================================
+ Hits        97643    97706      +63     
- Misses        605      611       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[daxfohl]

Updated PR to undo the change to _from_moments and also Circuit(*moments) constructor to be safe. You can click on the diff link to see how it affects tests. Basically just the freeze cycles don't retain the cache, and of course manually calling from_moments creates a circuit without a placement cache.

[github-actions]

This pull request has been automatically labeled as stale because 90 days have passed without comments or other activity. If no further activity occurs and the status/stale label is not removed by a maintainer within 60 days, this pull request will be closed. If you would like to restore its active status, please leave a comment here; doing so will cause the staleness handler to remove the label.

If you have questions or feedback about this process, we welcome your input. You can open a new issue to let us know (please also reference this issue there, for continuity), or reach out to the project maintainers at quantum-oss-maintainers@google.com.