Add LATEST InsertStrategy to complement EARLIEST

[codrut3]

Scans forward from a given insert location and inserts an operation into the latest possible moment. If no moment is available, inserts the operation in a new moment.

Fixes #7611

[codrut3]

I updated circuit.insert to support the LATEST strategy.

Handling a single operation is rather straightforward. However, insert allows inserting an operation tree, so I spent some time thinking the best way to do this:

• I reverse the order in which operations are inserted (starting from last). Otherwise for something like [cirq.X(q[0]), cirq.Y(q[0])] the result of inserting in direct order with LATEST would be [cirq.Y(q[0]), cirq.X(q[0])] which doesn't make sense to me.
• The insert method still returns the moment index after the latest inserted operation. If someone calls insert repeatedly for consecutive operations, using this value as the new insert index makes sense.
• Moments or operations are never inserted before the starting index k. This is different from EARLIEST, where the first batch is inserted in moments up to k, but the next batch can potentially be put in moment k+1, the second in moment k+2, and so on. If I can't insert at k, I add a new moment (which will then be the moment at index k).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.57%. Comparing base (c8d141b) to head (07a3649).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #7804   +/-   ##
=======================================
  Coverage   99.57%   99.57%           
=======================================
  Files        1102     1102           
  Lines       98638    98710   +72     
=======================================
+ Hits        98214    98290   +76     
+ Misses        424      420    -4     

☔ 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.

[NoureldinYosri]

LGTM but I would like @pavoljuhas to take a look since this is a big change to circuit construction

[NoureldinYosri]

why note set the default to zero ?

[pavoljuhas]

+1 Since _latest_available_moment is an internal method with only one in-class caller, let us make the start_moment_index argument mandatory.

[NoureldinYosri]

[super optional] nit: turn the not a or not b or not c into not (a and b and c)

[pavoljuhas]

LGTM with a couple of smallish adjustments, please see inline comments.

Thank you for taking care of this!

[pavoljuhas]

+1 Since _latest_available_moment is an internal method with only one in-class caller, let us make the start_moment_index argument mandatory.

[pavoljuhas]

Suggested change

	Batches are inserted into reverse order.
	Batches are processed in reverse order.

[pavoljuhas]

LGTM with a couple of suggestions:

1. the corner case c.insert(index, []) returns index with the EARLIEST strategy, but 0 with the LATEST. Let us make this consistent, ie, return index for either strategy. Please also add a test for this case.

2. I found it a bit tricky to follow the _insert_latest code with Moment and Operation blocks interspersed. Would you mind applying the patch below which regroups them to (a) Moment-only and (b) Operation only blocks?

diff --git a/cirq-core/cirq/circuits/circuit.py b/cirq-core/cirq/circuits/circuit.py
index 74c08354..6ecfcb41 100644
--- a/cirq-core/cirq/circuits/circuit.py
+++ b/cirq-core/cirq/circuits/circuit.py
@@ -2214,5 +2214,4 @@ class Circuit(AbstractCircuit):
         """
-        batches = batches[::-1]
         max_latest_index = -1  # Maximum index of a changed moment
-        for batch in batches:
+        for batch in reversed(batches):
             for moment_or_op in batch:
@@ -2220,22 +2219,22 @@ class Circuit(AbstractCircuit):
                 if isinstance(moment_or_op, Moment):
-                    p = k
+                    self._moments.insert(k, moment_or_op)
+                    max_latest_index = max(k, max_latest_index + 1)
                 else:
+                    end_moment_index = len(self.moments)
                     p = self._latest_available_moment(moment_or_op, start_moment_index=k)
                     if p < k:
-                        self._moments.insert(k, Moment())
-                        # All later moments shift by 1, so increase the max index
-                        max_latest_index += 1
-                        p = k
-                # Place
-                if isinstance(moment_or_op, Moment):
-                    self._moments.insert(p, moment_or_op)
-                    # All later moments shift by 1, so increase the max index
-                    max_latest_index += 1
-                elif p == len(self._moments):
-                    self._moments.append(Moment(moment_or_op))
-                else:
-                    self._moments[p] = self._moments[p].with_operation(moment_or_op)
-                max_latest_index = max(p, max_latest_index)
-        self._mutated(preserve_placement_cache=False)
-        return max_latest_index + 1
+                        self._moments.insert(k, Moment.from_ops(moment_or_op))
+                        max_latest_index = max(k, max_latest_index + 1)
+                    elif p < end_moment_index:
+                        self._moments[p] = self._moments[p].with_operation(moment_or_op)
+                        max_latest_index = max(p, max_latest_index)
+                    else:
+                        assert p == end_moment_index
+                        self._moments.append(Moment.from_ops(moment_or_op))
+                        max_latest_index = end_moment_index
+        # handle returned position index for empty batch
+        pos = k if max_latest_index == -1 else max_latest_index + 1
+        if max_latest_index != -1:
+            self._mutated(preserve_placement_cache=False)
+        return pos