guppyalgos.primitives.subroutines.ladders

Reusable patterns for quantum algorithms.

These are not necessarily algorithmic primitives, but rather patterns that appear in multiple primitives.

Functions

ccx_v_chain(controls_a, controls_b, target)	Apply the CCX V chain in linear depth with 2n - 1 Toffoli gates.
ccx_v_chain_logdepth(n)	Build the CCX V chain in O(n) gates and O(log n) depth, ancilla free.
cnx_ladder_logdepth(k, n[, inverse])	Build a ladder of k C^nX gates in logarithmic depth.
cnx_ladder_logdepth_num_ancilla(k)	Count the clean ancillae the log depth cnx ladder needs.
log_toffoli_ladder_num_ancilla(n_qubits)	Count the clean ancillae the log depth Toffoli ladder needs.

Classes

CXLadderLinear()	Linear depth CX Ladder.
CXLadderLog()	Log depth CX Ladder from https://arxiv.org/abs/2501.16802.
Ladder()	Protocol for ladders of gates.
ToffoliLadderLinear()	Linear-depth Toffoli ladder.
ToffoliLadderLog()	Log depth Toffoli ladder from https://arxiv.org/abs/2510.00840 (Algorithm 1).

class guppyalgos.primitives.subroutines.ladders.CXLadderLinear

Linear depth CX Ladder.

Protocols: Ladder

ascending(qs)

Apply ascending linear CX ladder.

Return type:

None

ascending_dagger(qs)

Apply ascending linear CX ladder dagger.

Return type:

None

descending(qs)

Apply descending linear CX ladder.

Return type:

None

descending_dagger(qs)

Apply descending linear CX ladder dagger.

Return type:

None

class guppyalgos.primitives.subroutines.ladders.CXLadderLog

Log depth CX Ladder from https://arxiv.org/abs/2501.16802.

Log-depth increases the gate count.

Protocols: Ladder

ascending(qs)

Apply ascending log-depth CX ladder.

Return type:

None

ascending_dagger(qs)

Apply ascending log-depth CX ladder dagger.

Return type:

None

descending(qs)

Apply descending log-depth CX ladder.

Return type:

None

descending_dagger(qs)

Apply descending log-depth CX ladder dagger.

Return type:

None

class guppyalgos.primitives.subroutines.ladders.Ladder

Protocol for ladders of gates.

The ladder has an orientation, with gates oriented in a consistent way. Here ‘ascending’ means that the ladder has gates oriented on increasing indices, e.g. a linear cx ladder:

for i in range(n-1):

cx(qs[i], qs[i+1])

descending instead has the ladder oriented the other way.

ascending(qs)

Apply ladder ascending in qubit index.

Return type:

None

ascending_dagger(qs)

Apply dagger of ascending ladder.

Return type:

None

descending(qs)

Apply ladder descending in qubit index.

Return type:

None

descending_dagger(qs)

Apply dagger of descending ladder.

Return type:

None

class guppyalgos.primitives.subroutines.ladders.ToffoliLadderLinear

Linear-depth Toffoli ladder.

Protocols: Ladder

ascending(qs)

Apply ascending linear Toffoli ladder.

Return type:

None

ascending_dagger(qs)

Apply ascending linear Toffoli ladder dagger.

Return type:

None

descending(qs)

Apply descending linear Toffoli ladder.

Return type:

None

descending_dagger(qs)

Apply descending linear Toffoli ladder dagger.

Return type:

None

n_gates(n_qubits)

Return the number of Toffoli gates in the ladder.

Return type:

int

num_ancilla(n)

Return the number of ancillas required for this ladder.

Return type:

int

class guppyalgos.primitives.subroutines.ladders.ToffoliLadderLog

Log depth Toffoli ladder from https://arxiv.org/abs/2510.00840 (Algorithm 1).

Log depth increases the gate count.

Protocols: Ladder

ascending(qs)

Apply ascending log depth Toffoli ladder.

Return type:

None

ascending_dagger(qs)

Apply ascending log depth Toffoli ladder dagger.

Return type:

None

ascending_dagger_with_cca(qs, anc)

Apply ascending log depth Toffoli ladder dagger on the given ancillae.

Return type:

None

ascending_with_cca(qs, anc)

Apply ascending log depth Toffoli ladder on the given ancillae.

Return type:

None

descending(qs)

Apply descending log depth Toffoli ladder.

Return type:

None

descending_dagger(qs)

Apply descending log depth Toffoli ladder dagger.

Return type:

None

descending_dagger_with_cca(qs, anc)

Apply descending log depth Toffoli ladder dagger on the given ancillae.

Return type:

None

descending_with_cca(qs, anc)

Apply descending log depth Toffoli ladder on the given ancillae.

Return type:

None

n_gates(n_qubits)

Return the number of Toffoli gates in the ladder.

Return type:

int

num_ancilla(n_q)

Return the number of ancilla qubits.

Return type:

int

guppyalgos.primitives.subroutines.ladders.ccx_v_chain(controls_a, controls_b, target)

Apply the CCX V chain in linear depth with 2n - 1 Toffoli gates.

Parameters:

• controls_a (array[qubit, n]) – Chain register, restored at the end.

• controls_b (array[qubit, n]) – Second control of each Toffoli.

• target (qubit) – Qubit flipped by the middle Toffoli.

guppyalgos.primitives.subroutines.ladders.ccx_v_chain_logdepth(n)

Build the CCX V chain in O(n) gates and O(log n) depth, ancilla free.

Parameters:

n (int) – Number of (controls_a, controls_b) pairs.

Return type:

GuppyFunctionDefinition

Returns:

A Guppy function implementing the CCX V chain.

Ref:

Vivien Vandaele, “Asymptotically Optimal Quantum Circuits for Comparators and Incrementers”, https://arxiv.org/abs/2603.12917

guppyalgos.primitives.subroutines.ladders.cnx_ladder_logdepth(k, n, inverse=False)

Build a ladder of k C^nX gates in logarithmic depth.

Parameters:

• k (int) – Length of the ladder.

• n (int) – Number of controls of each gate.

• inverse (bool) – Apply the reverse gate sequence.

Return type:

GuppyFunctionDefinition

Returns:

A Guppy function implementing the C^nX ladder in logarithmic depth.

guppyalgos.primitives.subroutines.ladders.cnx_ladder_logdepth_num_ancilla(k)

Count the clean ancillae the log depth cnx ladder needs.

Parameters:

k (int) – Length of the ladder.

Return type:

int

guppyalgos.primitives.subroutines.ladders.log_toffoli_ladder_num_ancilla(n_qubits)

Count the clean ancillae the log depth Toffoli ladder needs.

Parameters:

n_qubits (int) – Number of data qubits the ladder acts on.

Return type:

int