C[Toffoli] swaps control register depending on control value

[petim0]

The controlled version of Toffoli() has inconsistent register ordering depending on the value of cvs
See this minimal example:

from qualtran.bloqs.basic_gates import Toffoli, CNOT
from qualtran import CtrlSpec, QBit

print(Toffoli().controlled(CtrlSpec(QBit(), cvs=0)).signature)
print(Toffoli().controlled(CtrlSpec(QBit(), cvs=1)).signature)

>>> Signature((
        Register(name='ctrl2', dtype=QBit(), _shape=(), side=<Side.THRU: 3>), 
        Register(name='ctrl', dtype=QBit(), _shape=(2,), side=<Side.THRU: 3>), 
        Register(name='target', dtype=QBit(), _shape=(), side=<Side.THRU: 3>)))
>>> Signature((
        Register(name='ctrl2', dtype=QBit(), _shape=(2,), side=<Side.THRU: 3>), 
        Register(name='ctrl', dtype=QBit(), _shape=(), side=<Side.THRU: 3>), 
        Register(name='target', dtype=QBit(), _shape=(), side=<Side.THRU: 3>)))

We see here that when we change the control value from 0 to 1, the control registers are swapped:

• In the first case ctrl2 is contains the new control and ctrl holds the initial 2 controls
• In the second case ctrl2 holds the initial 2 controls and ctrl is the new control qubit.

It is an issue since when the control value is a parameter of the bloq we must call bb.add(...) differently which adds a lot of overhead.

Note: This does not happens when the qdtype of CtrlSpec is not a QBit

[mpharrigan]

Thanks for the report!

In general, uncontrolled_bloq.controlled() is allowed to return a new bloq with a different signature than uncontrolled_bloq. This is so we can support e.g. CNOT().controlled() -> Toffoli. This is a particularly surprising example, and we should probably fix it. The signatures are different because the bloqs are different:

ControlledViaAnd(subbloq=Toffoli(), ctrl_spec=CtrlSpec(qdtypes=(QBit(),), cvs=(array(0),)))
ControlledViaAnd(subbloq=CNOT(), ctrl_spec=CtrlSpec(qdtypes=(QBit(),), cvs=(array([1, 1]),)))

i.e. the first is a controlled toffoli with one additional control bit and the latter is a controlled cnot with two additional control bits.

---

It is an issue since when the control value is a parameter of the bloq we must call bb.add(...) differently which adds a lot of overhead.

Yes, even if we fix this particular inconsistency: in general, there are no guarantees about what the signature of bloq.controlled() will be. If you want to support adding the controlled version of any bloq, you have to use the somewhat more complicated ctrl_bloq, adder = bloq.get_ctrl_system(...) method. This returns the controlled bloq but also a function that can be used to add the controlled bloq . That function will have the following classical signature

            def _my_add_controlled(
                bb: 'BloqBuilder', ctrl_soqs: Sequence['SoquetT'], in_soqs: Dict[str, 'SoquetT']
            ) -> Tuple[Iterable['SoquetT'], Iterable['SoquetT']]:

class AddControlledT(Protocol):
    """The signature for the `add_controlled` callback part of `ctrl_system`.

    See `Bloq.get_ctrl_system` for details.

    Args:
        bb: A bloq builder to use for adding.
        ctrl_soqs: The soquets that represent the control lines. These must be compatible with
            the ControlSpec; specifically with the control registers implied
            by `activation_function_dtypes`.
        in_soqs: The soquets that plug in to the normal, uncontrolled bloq.

    Returns:
        ctrl_soqs: The output control soquets.
        out_soqs: The output soquets from the uncontrolled bloq.
    """

so you can do something like

ctrl_bloq, adder = my_bloq.get_ctrl_system(CtrlSpec(...))
[my_ctrl_var,], (x, y, z) = adder(bb, [my_ctrl_var], dict(x=x, y=y, other_arguments_to_my_bloq=z))
...

That's if you want to automatically process the controlled version of any subbloq. If you just want to handle Toffoli with cv=0 and cv=1, we can just make those consistent

[mpharrigan]

Related issue #1556

[mpharrigan]

This will be fixed by #1771

[petim0]

Thanks for the quick answer and fix!
Your example on how to use get_ctrl_system was also really helpful and it indeed makes my issue way less annoying.

I do feel like the Qualtran docs lacks examples. And sometimes the right docs are hard to find, a few things that are only in docstrings would probably be really useful in the “Fundamentals” section as well. But this is a totally different discussion than this issue and is more related to #503 or #562