[unitaryHack 2025] Refactor gate decomposition to support controlled gates

[GiacomoFrn]

Description

This PR addresses the first step of issue #1585, which aims to generalize the decompose() method for all gates, including controlled gates.

Summary of changes

• Refactored all custom gates in gates.py to implement a new internal method _base_decompose(), which defines their standard decomposition.
• Modified the decompose() method in abstract.py to support controlled gates by:
  • Calling _base_decompose() on the base gate (i.e., the gate with no control qubits),
  • Using control_mask_after_stripping() to determine which gates in the decomposition require controls,
  • Adding controls only to the necessary gates, avoiding redundant controlled gates,
  • Preserving the correct qubit ordering and control structure.

Notes

• The new _base_decompose() method is for internal use only and separates decomposition logic from control logic.
• The behavior for non-controlled gates remains unchanged.
• The new logic improves circuit efficiency by not applying controls to gates that cancel out.

[GiacomoFrn]

Hi @renatomello,
I'm reaching out with a couple of doubts about how I could improve my PR. There are two main issues I’d like to clarify:

1. Controlled gate behavior: I noticed that when a gate has a _controlled_gate defined (like U3), the expected behavior — adding a control to each gate in the decomposition — doesn't work as intended. Instead, I only get a single CU3 gate, and the decomposition is skipped. Also, when I inspect the resulting gate, the is_controlled_by flag is not set to True, which makes me think that the control is handled differently in this case (perhaps by directly creating the controlled version, like CU3). I'm unsure how to intercept or modify this behavior — do you have any suggestions?

2. Control optimization: I’ve implemented a simple version of the control optimization that handles basic sandwich-like identity cases. However, I'm not sure how to scale this to more general decompositions, where the gate set might be arbitrary (e.g., universal gates). A numerical approach to identify identity-like patterns seems too costly, while hardcoding all possible identities feels inelegant. Do you have any thoughts on a better strategy?

Thanks in advance for your time and help!

[GiacomoFrn]

Hi @scarrazza, now all tests should pass!

[GiacomoFrn]

Hi @scarrazza,
apologies — earlier I was only checking the failing tests related to my change, and while my fix resolved those, it caused other tests to fail.

I've now run the full test suite and confirmed that all tests pass. That said, I'm aware that the solution may not be the most elegant, so I’d be happy to improve it with your input.

Summary of the issue and fix:

• The current strategy for decomposing multi-controlled gates involves first decomposing the uncontrolled base gate, then applying single controls to the resulting gates.
• However, this approach broke the following test:

@pytest.mark.parametrize("use_toffolis", [True, False])
def test_x_decomposition_errors(use_toffolis):
    gate = gates.X(0).controlled_by(1, 2, 3, 4)
    with pytest.raises(ValueError):
        _ = gate.decompose(2, 3, use_toffolis=use_toffolis)

• The test expects a ValueError to be raised by the X gate’s _base_decompose when invalid free qubits are provided. But with the new strategy, only the base X(0) is passed through _base_decompose, and the error was no longer triggered.
• I initially tried to fix this by passing the control qubits to the decomposition, but that was a mistake.
• The final fix: I now explicitly recreate the base gate before the decomposition step and check for this error condition directly, so that the test behaves as expected. Then I create a new base gate to run through the decomposition.

Let me know if you see a cleaner way to handle this — happy to revise it further.

[renatomello]

@GiacomoFrn I'm sorry for the delay, I'll revisit this PR tomorrow.

[renatomello]

@GiacomoFrn I like your solution the best. Can you comment on the issue so I can assign it to you, please? Could you also star our repo?

[renatomello]

BTW @GiacomoFrn: #1659