Coherent Control with qmc.control

1. The minimal example: controlled-RX¶

The simplest, most practical use of qmc.control is to make a controlled version of one of the gates Qamomile provides. For example, below we pass the one-qubit gate qmc.rx(q, angle) to qmc.control to obtain a two-qubit controlled-RX gate.

To confirm the control actually takes effect, we transpile both kernels to Qiskit, run them on the simulator, and check the target measurement. With angle=math.pi, RX(pi) maps |0> to |1>, so the target ends up |1> on every shot when the control is |1>, and stays |0> otherwise.

A few points to note:

• You can write crx = qmc.control(qmc.rx) either inside or outside a qkernel. Either way the returned value is reusable; bind it to a name and call it as many times as you like.

• When you call crx(c, t, angle=...), the control qubits come first as positional arguments, then the targets, then any classical keyword arguments. The order mirrors the qmc.rx(q, angle) signature of the gate being controlled, with a control prefixed.

• The keyword name for the classical parameter is whatever the controlled gate uses (angle for qmc.rx, theta for qmc.p, etc.) — qmc.control does not rename it.

2. Two modes at a glance¶

qmc.control has two modes. Which one you are in is decided entirely by the type you pass for num_controls: a Python int puts you in concrete mode, a qmc.UInt handle (or any UInt expression like n - 1) puts you in symbolic mode. Everything else about the call follows from that choice.

Most of qmc.control’s features (power=, default values, classical-kwarg reordering, sub-kernels that take Vector[Qubit], the multi-argument control shapes, ...) behave identically in both modes; 3. Patterns that work in BOTH modes collects those. 4. Concrete-mode-only patterns covers the features that require concrete mode, and 5. Symbolic-mode patterns the symbolic-mode-specific features.

3. Patterns that work in BOTH modes¶

Each feature in this section behaves the same way in either mode. The cells below use concrete mode for brevity, but the same feature is available in symbolic mode too — the only differences are that num_controls is a UInt expression and the qubit-count match is checked at transpile time. 5. Symbolic-mode patterns covers the symbolic-only argument shapes.

3.1 Controlling any callable¶

qmc.control accepts either a built-in gate function (qmc.rx, qmc.h, qmc.p, ...) or any user-defined @qmc.qkernel. The example below uses two controlled operations in one kernel: ch (the controlled qmc.h) and cg (the controlled user-defined _h_then_rx).

3.2 Sub-kernel taking Vector[Qubit]¶

A controlled kernel may take a Vector[Qubit] argument. The caller passes a Vector or a VectorView of the matching length.

3.3 Default values from the controlled kernel’s signature¶

When the controlled kernel declares a Python default for a classical parameter, the caller may omit that keyword.

3.4 Controlling U^k with power=¶

Passing power=k controls the k-th power U^k instead of U itself. power accepts a Python int (resolved at compile time) or a qmc.UInt handle (resolved at transpile time from bindings), and works regardless of whether num_controls is concrete or symbolic. The resolved value must be a strictly positive integer; zero, negative values, and bool are rejected. A symbolic power changes circuit structure, so supply it through bindings, not runtime parameters.

Global phase becomes observable under coherent control¶

Multiplying an otherwise standalone operation by exp(1j * phi) does not change ordinary measurement probabilities. Qamomile nevertheless keeps the phase as part of the current lexical circuit region. When a reversible region is coherently controlled, the same factor becomes a relative phase on the all-active control subspace. This matters whenever an algorithm stores information in a subroutine’s phase rather than only in its measurement probabilities.

Qamomile provides two related ways to attach this phase:

• qmc.global_phase(fn, phi) invokes fn normally, preserves all of its outputs, and then attaches exp(1j * phi) to the surrounding region.

• qmc.control(fn)(..., global_phase=phi) attaches the phase at that controlled call site.

The ordinary qmc.global_phase wrapper does not require fn to be reversible: fn may measure, reset, allocate qubits, return classical values, or be entirely classical. Reversibility is checked only if a containing qkernel is later compiled through qmc.control, qmc.inverse, or another reversible transform. For a reversible operation U, the precise controlled-call meaning is control((exp(1j * phi) * U) ** power). Therefore power=k repeats the phase k times, while an inverse negates the phase together with inverting U. global_phase is a reserved call-site keyword; if the target callable also has an ordinary parameter named global_phase, pass that parameter positionally.

A scalar body whose formal target is Qubit can be called with a Vector[Qubit] or VectorView[Qubit]. Qamomile then broadcasts the complete scalar unitary to every element, exactly like an explicit loop. If $U = e^{i\phi}V$ and the target has $N$ elements, the result is $U^{\otimes N} = e^{iN\phi}V^{\otimes N}$; power=k also multiplies that phase by $k$. To attach one phase to the register as a whole, define the controlled body with a Vector[Qubit] parameter and attach the phase to that vector body, so it remains one logical call.

A phase attached inside a runtime if branch or while body stays in that branch or iteration. It is not moved to the top-level circuit or discarded. A target that cannot preserve the requested scoped or standalone phase fails explicitly during capability verification or materialization.

3.5 Multiple separate positional control args (CCX style)¶

With num_controls=2, the call site lists each control qubit as its own positional argument before the target. The example below is the canonical CCX (Toffoli): two controls c0, c1 and a target t. The same pattern extends to num_controls=3 (CCCX), num_controls=4, etc., as long as you have that many distinct Qubit handles to pass in.

3.6 Mixing scalar Qubit and VectorView controls¶

The positional control prefix may freely mix scalar Qubit handles, VectorView slices, and whole Vector[Qubit]s, as long as the total qubit count adds up to num_controls. Here the three controls for a num_controls=3 controlled-H come from qs[0] (a scalar Qubit, 1 qubit) plus qs[1:3] (a VectorView, 2 qubits).

4. Concrete-mode-only patterns¶

Almost every control-argument shape works in both modes (3. Patterns that work in BOTH modes), and symbolic mode adds its own features (5. Symbolic-mode patterns). Concrete mode additionally supports a single scalar control and activation on a specified computational-basis value.

4.1 A single scalar control¶

A single scalar Qubit as the lone control requires concrete mode. In symbolic mode a single control argument is read as the pool form and must be a Vector / VectorView; a control whose count is fixed at one has no reason to be symbolic anyway. This is exactly the minimal controlled-RX of 1. The minimal example: controlled-RX; the controlled-X (CNOT) below has the same shape.

4.2 Activating on a control-register value¶

Ordinary coherent control activates when every control is 1. control_value=v instead activates when the flattened control register represents the concrete integer v. Flattening follows call order; each Vector / VectorView contributes elements from index zero upward, and the first flattened control is bit zero (LSB). Thus control_value=2 over two controls means (bit_0, bit_1) = (0, 1).

Qamomile represents this as one value-activated controlled operation. Its portable lowering is equivalent to applying X before and after the control on every zero-valued bit, so those temporary X gates cancel on the returned controls. The example deliberately mixes a scalar control and a one-element VectorView to make the flattening order explicit.

control_value=None is the default all-ones control. Supplying the explicit all-ones value 2**num_controls - 1 is canonicalized to that same default. Any other value must satisfy 0 <= control_value < 2**num_controls. Non-default control_value is intentionally concrete-only. To activate on a value other than all ones, construct qmc.control with a concrete Python int width rather than a qmc.UInt. This keeps the activation bit pattern unambiguous when the operation is created.

5. Symbolic-mode patterns¶

This section covers what you get when num_controls is a qmc.UInt handle (or any UInt expression like n - 1): the number of active controls is decided at transpile time from bindings, not at the moment qmc.control(..., num_controls=...) is evaluated. 5.5 Multi-arg control prefix also shows the symbolic counterpart of 3.5 Multiple separate positional control args (CCX style) / 3.6 Mixing scalar Qubit and VectorView controls.

Two call-site shapes are supported for the control side:

• Single-pool form (5.1 num_controls = n over a whole pool – 5.4 control_indices with UInt entries): one Vector[Qubit] or VectorView is passed as the control argument, and the entire pool — or the subset chosen by control_indices — acts as the active controls.

• Multi-arg form (5.5 Multi-arg control prefix): the control prefix is several positional arguments (scalar Qubit, VectorView, Vector[Qubit], or a mix) whose qubit counts sum to num_controls. This is what concrete mode already does (3.5 Multiple separate positional control args (CCX style) / 3.6 Mixing scalar Qubit and VectorView controls), lifted to a symbolic num_controls.

The control_indices keyword is symbolic-mode only; it picks which slots of a single-pool argument wire in as active controls (the rest pass through untouched). control_indices is valid only with the single-pool form; combining it with the multi-arg form is rejected.

5.1 num_controls = n over a whole pool¶

The simplest symbolic shape: num_controls=n with the entire pool (length n) used as the active controls. The parameter n is made concrete at transpile time via bindings.

5.2 Canonical n - 1 multi-controlled form¶

A frequent shape in multi-controlled-X designs: the first n - 1 qubits of a register become controls, the last one becomes the target. The bound on num_controls is the symbolic expression n - 1, and the control argument is the slice qs[0:n - 1].

5.3 Selecting a subset with control_indices¶

When the control pool is wider than the number of active controls you want, the control_indices keyword (symbolic mode only) picks which pool slots are wired in. The remaining slots are left untouched. The indices do not have to be contiguous.

5.4 control_indices with UInt entries¶

Each entry inside control_indices may be a Python int literal, a qmc.UInt handle, or any arithmetic expression over UInt values. Cheap structural checks on literal int entries (rejecting bool, negative values, and entries that duplicate another literal int in the list) are done at compose time; everything else — length agreement with num_controls, range against the pool size, and any check that depends on a UInt resolving to a concrete value — is deferred to transpile time once bindings make the parameters concrete.

5.5 Multi-arg control prefix¶

When you want to split the controls across several positional arguments — typically because you want some slots of a single Vector to be active controls and another slot to be the target — symbolic mode accepts the same multi-arg shape concrete mode does (3.5 Multiple separate positional control args (CCX style) / 3.6 Mixing scalar Qubit and VectorView controls). Several slots taken from the same Vector[Qubit] may sit in the control prefix as long as they are disjoint (non-overlapping). The qubit counts of the control-prefix args are matched against num_controls at transpile time.

Note that control_indices cannot be used with the multi-arg form (see the reject case in 6. Rejected and edge-case patterns). If you need subset selection, use the single-pool form (5.3 Selecting a subset with control_indices / 5.4 control_indices with UInt entries); if you need the multi-arg flexibility, treat the whole prefix as active.

6. Rejected and edge-case patterns¶

This section walks through rejected call shapes one at a time, asserting the expected exception with a small expect_error helper. It ends with a concrete sliced-QFT case that is supported and worth keeping as a regression example for nested controlled emission on backends that can convert the nested block to a gate (Qiskit in this tutorial).

6.1 Control qubit count crosses an argument boundary (concrete)¶

Concrete mode walks the positional arguments in order, folding each one into the control list until the running total reaches num_controls. If a VectorView or Vector pushes the running total past num_controls, the call is rejected.

6.2 control_indices in concrete mode (concrete)¶

control_indices only makes sense when there is a control pool to select from, which is a symbolic-mode concept. Supplying it alongside a concrete num_controls raises ValueError at compose time.

6.3 Symbolic-length VectorView in concrete mode (concrete)¶

Concrete mode must determine each control argument’s qubit count at compile time. A slice whose length depends on a UInt is not supported in concrete mode and raises ValueError before ownership moves.

6.4 Same-pool slot reused as target — single-pool form (symbolic)¶

With the single-pool form (cg(pool, ...) combined with control_indices), it is tempting to take one of the pool’s inactive slots and pass it as the target — e.g. cg(pool, pool[2], control_indices=[0, 1, 3]) so that pool[2] becomes the target of the controlled-U. The call is rejected by the linear-type borrow tracker: the pool is already consumed as one argument while pool[2] is borrowed for another, which surfaces as UnreturnedBorrowError at compose time.

Workarounds (preferred order):

1. Multi-arg symbolic form (5.5 Multi-arg control prefix). Pass each slot or sub-view as its own positional argument: cg(pool[0], pool[1], pool[3], pool[2]) (or the slice/scalar mix the controlled-increment example uses). Each argument is a separate borrow from pool, the borrow tracker checks disjointness, and num_controls matches the qubit-count sum at transpile time.

2. Concrete mode (3.6 Mixing scalar Qubit and VectorView controls). If num_controls is a Python int, the same multi-arg shape works without any symbolic plumbing.

6.5 Multi-arg control prefix + control_indices (symbolic)¶

The two symbolic-mode features are mutually exclusive. control_indices only makes sense over a single control pool (one Vector argument); combining it with multiple positional control args raises ValueError at compose time.

6.6 Single scalar control in symbolic mode (symbolic)¶

A single scalar Qubit control is the one shape that needs concrete mode. In symbolic mode a lone control argument is read as the single-pool form, which requires a Vector / VectorView.

6.7 Controlled QFT over a sub-kernel UInt slice (concrete)¶

A controlled sub-kernel may call qmc.qft / qmc.iqft on a Vector[Qubit] argument whose size is known at the call site. For example, controlled_qft = qmc.control(apply_qft) works when apply_qft(q) applies QFT to all of q.

The same now holds for the narrower Qiskit-backed pattern below: the wrapped sub-kernel receives a classical UInt argument and uses it to form a q[:m] slice before calling QFT. Qamomile strips the slice marker inside the nested controlled block after borrow checking, so a controlled-U emitter whose block-to-gate conversion succeeds can lower the sliced composite block. Backends without block-to-gate conversion may still reject this multi-target fallback.

7. Summary¶

qmc.control(fn, num_controls=...) makes a controlled version of any Qamomile built-in gate or user-defined kernel. It has two modes, decided by the type of num_controls: a Python int gives concrete mode, and a qmc.UInt (or a UInt expression like n - 1) gives symbolic mode. Concrete mode also supports control_value, including zero-controls, using the same LSB-first order in which control arguments are flattened. In either mode, power, global phase, scalar-to-vector broadcast, inverse, and nested control preserve the complete controlled unitary. Invalid widths, overlapping control and target wires, and unsupported reversible bodies fail explicitly.