guppyalgos.primitives.subroutines.fanout

Quantum fanout implementations.

Functions

fanout_basic(control, data_qs)

Apply basic fanout to one flat data register.

fanout_from_data(data, fan_out_flat_fn)

Build a single- or multi-register fanout from a flat Guppy operation.

fanout_log(control, data_qs)

Apply log depth fanout to one flat data register.

fanout_measurement_compute(q_target, ...)

Fan out a target qubit into a supplied zero-state register.

fanout_measurement_compute_total_qubits(...)

Return the peak qubit count required by fanout compute.

fanout_measurement_parity(q_target, qs_inputs)

Apply parity-based measurement-assisted fanout to a target register.

fanout_measurement_parity_total_qubits(...)

Return the qubit count required by parity-based measurement fanout.

fanout_measurement_uncompute(q_target, qs_copies)

Uncompute a fanout copy register back to zero in place.
guppyalgos.primitives.subroutines.fanout.fanout_basic(control, data_qs)

Apply basic fanout to one flat data register.

guppyalgos.primitives.subroutines.fanout.fanout_from_data(data, fan_out_flat_fn)

Build a single- or multi-register fanout from a flat Guppy operation.

The True entries in data identify selected data qubits. For nested data, selected qubits from every target register are gathered into one flat array before fan_out_flat_fn is called. The operation is invoked exactly once, rather than once per target register, and the qubits are then returned to their original locations.

This is useful for measurement-based fanout, where the flat operation can be implemented with a single measurement and feed-forward correction, rather than one measurement per target register, leading to constant depth.

Parameters:

  • data (list[bool] | list[list[bool]]) – Boolean mask for one target register or equally sized masks for a rectangular register array.

  • fan_out_flat_fn (GuppyFunctionDefinition) – In-place Guppy operation that borrows the control and flat data-qubit register.

Return type:

GuppyFunctionDefinition

Returns:

A Guppy function accepting a control and target register shape matching data.

Raises:

  • TypeError – If data is not a non-empty boolean list or nested list.

  • ValueError – If nested target masks have unequal lengths.

guppyalgos.primitives.subroutines.fanout.fanout_log(control, data_qs)

Apply log depth fanout to one flat data register.

guppyalgos.primitives.subroutines.fanout.fanout_measurement_compute(q_target, qs_target_copies)

Fan out a target qubit into a supplied zero-state register.

The circuit implements |y>|0>|0> -> |y>|y>|y> using measurement-assisted computation and feed-forward.

For fewer than three copies, sequential controlled operations are used. Larger registers use measurement-assisted fanout with n_state_qubits - 2 ancillas.

It is up to the user to generate the copy register.

Parameters:

  • q_target – Qubit whose computational-basis value is copied.

  • qs_target_copies – Caller-provided target register initialized to zero.

guppyalgos.primitives.subroutines.fanout.fanout_measurement_compute_total_qubits(n_state_qubits)

Return the peak qubit count required by fanout compute.

The count includes one control qubit, n_state_qubits supplied target qubits, and n_state_qubits - 2 equal-check ancillas when at least three copies are requested.

Parameters:

n_state_qubits (int) – Number of zero-initialized copy qubits to produce.

Return type:

int

Returns:

Total number of target, copy, and equal-check qubits.

guppyalgos.primitives.subroutines.fanout.fanout_measurement_parity(q_target, qs_inputs)

Apply parity-based measurement-assisted fanout to a target register.

Hadamard conjugation reverses the direction of the CNOTs represented by the parity circuit. The operation therefore maps |c>|x_0, ..., x_n-1> to |c>|x_0 XOR c, ..., x_n-1 XOR c>. This operation acts on an arbitrary input state. For four or more targets, the underlying LAQCC parity circuit allocates two ancilla registers, each containing n_state_qubits - 3 qubits. Smaller registers use no ancillas.

Parameters:

  • q_target – Control qubit whose value is fanned out.

  • qs_inputs – Target register. Its length determines the circuit and ancilla sizes at compile time.

Examples

With control |1> and three targets in |0, 0, 0>, the output targets are |1, 1, 1> and the control remains |1>.

guppyalgos.primitives.subroutines.fanout.fanout_measurement_parity_total_qubits(n_state_qubits)

Return the qubit count required by parity-based measurement fanout.

The count includes one control qubit, n_state_qubits target qubits, and two LAQCC ancilla registers of size n_state_qubits - 3 when the target register contains at least four qubits.

Parameters:

n_state_qubits (int) – Number of fanout target qubits.

Return type:

int

Returns:

Total number of control, target, and ancilla qubits.

guppyalgos.primitives.subroutines.fanout.fanout_measurement_uncompute(q_target, qs_copies)

Uncompute a fanout copy register back to zero in place.

The circuit implements |y>|y>|y> -> |y>|0>|0> using measurement-assisted computation and feed-forward.

This is the inverse cleanup operation for fanout_measurement_compute(). It non-destructively measures the copy register, corrects the target using the measurement parity, and resets the supplied copies to zero.

It is up to the user to discard the copy register after this operation.

Parameters:

  • q_target – Original target qubit used to create the copies.

  • qs_copies – Caller-owned copy register to restore to zero.