Organization (and deprecation) of cirq-core/optimizers in cirq-core/transformers

[tanujkhattar]

Background

Currently, all optimizers in cirq are present in a single directory -- cirq-core/cirq/optimizers/*. It contains not only transformers (which transform/optimize circuits) but also utility methods like analytical decompositions of matrices into target operations.
Also, after #4708 and #4692; almost all existing optimizers would need to be re-implemented to

• Use the newly added moment preserving primitives
• Not mutate the input circuits (as proposed in the new transformer API https://tinyurl.com/cirq-circuit-transformers-api)

Proposal

The proposal is to

1. Create a new cirq/transformers/
2. Move decomposition utilities from cirq/optimizers to sub directories under cirq/transformers/
3. Deprecate the existing transformers in cirq/optimizers in favor of new implementations using the moment preserving primitives and following the new non-mutating API, which would be added at top-level in cirq/transformers/.

cirq-core/cirq/transformers/heuristic_decompositions/*

• gate_tabulation.py and corresponding math_utils.py (see Bring GateTabulation out of cirq-google to cirq-core #4461)
• numerical optimization based approximate compilation proposed in Compiling: heuristic for compiling 2 qubits gates to the native gateset #4362

Note: Heuristic compilation is an active area of research and is an important primitive for compensating for actual gate angles calibrated via techniques like Floquet / XEB calibration. We can expect more primitives to get added here in future.

cirq-core/cirq/transformers/analytical_decompositions/*

• clifford_decomposition.py
• controlled_gate_decomposition.py
• cphase_to_fsim.py
• decompositions.py --> single_qubit_decompositions.py
• three_qubit_decomposition.py
• two_qubit_decompositions.py --> two_qubit_to_cz.py
• two_qubit_state_preparation.py
• two_qubit_to_fsim.py
• two_qubit_to_sqrt_iswap.py

Newer versions of the following existing transformers in cirq-core/cirq/optimizers/* will get added in cirq-core/cirq/transformers/*

• align_left.py
• align_right.py
• convert_to_cz_and_single_gates.py
• drop_empty_moments.py
• drop_negligible.py
• eject_phased_paulis.py
• eject_z.py
• expand_composite.py
• merge_interactions.py
• merge_interactions_to_sqrt_iswap.py
• merge_single_qubit_gates.py
• stratify.py
• synchronize_terminal_measurements.py
• transformer_primitives.py

Deprecation Plan

• For analytical decomposers, the existing files will simply get moved from cirq/optimizers/* to cirq/transformers/analytical_decompositions. Existing methods will go through a deprecation cycle and the change should not impact usages of the form cirq.<method>.
• For existing transformers -- it would be a large breaking change to deprecate all existing transformers in the favour of newer moment-preserving non mutating versions but this is unavoidable and need to happen as part of the larger effort on redesigning transformers. The existing transformers can be left around for a few versions for the user code to get updated since the new versions would be implemented independently of existing versions.

cc @MichaelBroughton @dstrain115 @dabacon Thoughts?
Part of roadmap #3238

[MichaelBroughton]

I like the looks of this plan.

Create a new cirq/transformers/
Move decomposition utilities from cirq/optimizers to sub directories under cirq/transformers/
Deprecate the existing transformers in cirq/optimizers in favor of new implementations using the moment preserving primitives and following the new non-mutating API, which would be added at top-level in cirq/transformers/.

Where possible, I would be in favor of doing this one module at a time and not all at once so multiple people can work on this at once and also take the opportunity for the rewrite/cleanup of their module one module at a time.

[dstrain115]

This is fine with me, but we should announce this broadly. We already mentioned at a cirq cync, but it might be worth an email to cirq-announce. We could maybe combine this with a forward-looking "What's changing in cirq 1.0" email to all of cirq-announce that explains all the changes we are planning to do.