Source code for pennylane.transforms.decompositions.phase_gradient_state_prep_decomp

# Copyright 2026 Xanadu Quantum Technologies Inc.

# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at

#     http://www.apache.org/licenses/LICENSE-2.0

# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
r"""Jones distillation decomposition for phase-gradient state preparation."""

import math
from collections import defaultdict
from functools import lru_cache

import pennylane as qp
from pennylane.decomposition import register_resources
from pennylane.typing import Wire
from pennylane.wires import WireError, Wires, validate_no_wire_overlaps


def _jones_num_rounds(num_wires):
    """Return the number of Jones distillation rounds."""
    if num_wires < 3:
        return 0

    numerator = 2 * num_wires - 2 * math.log2(math.pi)
    return max(1, math.ceil(math.log2(numerator / math.log2(9))))


def _jones_register_sizes(num_wires):
    """Return register sizes from the two-qubit seed through the final round."""
    if num_wires < 3:
        return (num_wires,)

    # Children have floor(s/2) + 1 qubits. Halving even registers exactly (e.g. 7 -> 14) misses
    # the target infidelity at finite sizes.
    sizes = [num_wires]
    for _ in range(_jones_num_rounds(num_wires) - 1):
        sizes.append(max(3, sizes[-1] // 2 + 1))
    return (2, *reversed(sizes))


_MAX_SIMULATED_SIZE = 16


@lru_cache
def _jones_success_probabilities(register_sizes):
    """Return the success probability of each distillation round.

    Rounds are simulated as coefficient squaring in the Fourier basis. Rounds producing more than
    ``_MAX_SIMULATED_SIZE`` wires succeed with probability one up to about ``1e-4`` and are not
    simulated.
    """
    dim = 2 ** register_sizes[0]
    state = qp.math.exp(-2j * math.pi * qp.math.arange(dim, like="numpy") / dim) / math.sqrt(dim)

    probabilities = []
    for child_size, output_size in zip(register_sizes[:-1], register_sizes[1:], strict=True):
        if output_size > _MAX_SIMULATED_SIZE:
            probabilities.append(1.0)
            continue

        dim = 2**output_size
        tail_dim = 2 ** (output_size - child_size)
        tail = qp.math.ones(tail_dim, like="numpy") / math.sqrt(tail_dim)
        squared = (qp.math.fft.ifft(qp.math.kron(state, tail)) * math.sqrt(dim)) ** 2
        probabilities.append(float(qp.math.sum(qp.math.abs(squared) ** 2)))
        state = qp.math.fft.fft(squared / qp.math.linalg.norm(squared)) / math.sqrt(dim)

    return tuple(probabilities)


def _jones_seed(wires):
    """Prepare the Clifford seed from Jones, Eq. (4), conjugated to the negative-phase convention,
    i.e., with S replaced by S†."""
    for wire in wires:
        qp.Hadamard(wire)
    if wires:
        qp.Z(wires[0])
    if len(wires) > 1:
        qp.adjoint(qp.S(wires[1]))


def _reset(wires):
    """Reset a register with Z Pauli measurements and X corrections."""
    for wire in wires:
        qp.cond(qp.pauli_measure("Z", wire), qp.X)(wire)


def _distillation_attempt(
    level, output_wires, scratch_wires, register_sizes, mode
):  # pylint: disable=too-many-arguments
    """Prepare two children and perform one symmetric Jones distillation attempt."""
    output_size = register_sizes[level]
    child_size = register_sizes[level - 1]
    source_wires = scratch_wires[:output_size]
    work_wires = scratch_wires[output_size : 2 * output_size - 1]
    remaining_wires = scratch_wires[2 * output_size - 1 :]

    output_tail = output_wires[child_size:]
    source_tail = source_wires[child_size:]

    _prepare_distilled_state(
        level - 1,
        output_wires[:child_size],
        output_tail + scratch_wires,
        register_sizes,
        mode,
    )
    _prepare_distilled_state(
        level - 1,
        source_wires[:child_size],
        source_tail + output_tail + work_wires + remaining_wires,
        register_sizes,
        mode,
    )

    for wire in output_tail + source_tail:
        qp.Hadamard(wire)

    qp.SemiAdder(source_wires, output_wires, work_wires)

    if mode == "postselect":
        # Catalyst does not honour postselection on pauli_measure yet, and default.qubit cannot
        # execute pauli_measure, so the postselected branch uses standard mid-circuit measurements
        for wire in source_wires:
            qp.Hadamard(wire)
            qp.measure(wire, reset=True, postselect=0)
        return True

    measurements = [qp.pauli_measure("X", wire) for wire in source_wires]
    _reset(source_wires)
    success = qp.math.sum(qp.math.array(measurements, like="jax")) == 0
    success_probability = _jones_success_probabilities(register_sizes)[level - 1]

    @qp.cond(qp.math.logical_not(success))
    @qp.hint({"branch-prob": 1 - success_probability})
    def reset_output():
        _reset(output_wires)

    reset_output()
    return success


def _prepare_distilled_state(level, output_wires, scratch_wires, register_sizes, mode):
    """Recursively prepare one node while preserving completed sibling registers."""
    if level == 0:
        _jones_seed(output_wires)
        return

    def not_success(success):
        return qp.math.logical_not(success)

    expected_attempts = (
        1 / _jones_success_probabilities(register_sizes)[level - 1]
        if mode == "repeat-until-success"
        else 1
    )

    @qp.hint({"num-iters": expected_attempts})
    @qp.while_loop(not_success)
    def retry(success):
        # Using the carry keeps MLIR canonicalization from rebuilding the loop and dropping the hint
        return qp.math.logical_or(
            success,
            _distillation_attempt(level, output_wires, scratch_wires, register_sizes, mode),
        )

    retry(False)


def _distillation_resources(num_wires, mode):
    """Resources in the statically captured tree, counting each retry body once."""
    register_sizes = _jones_register_sizes(num_wires)
    resources = defaultdict(int)

    if len(register_sizes) == 1:
        resources[qp.Hadamard] += num_wires
        if num_wires:
            resources[qp.Z] += 1
        if num_wires > 1:
            resources[qp.adjoint(qp.S(Wire[1]))] += 1
        return resources

    num_states = 2 ** (len(register_sizes) - 1)
    seed_size = register_sizes[0]
    resources[qp.Hadamard] += num_states * seed_size
    resources[qp.Z] += num_states
    resources[qp.adjoint(qp.S(Wire[1]))] += num_states

    for level, (child_size, output_size) in enumerate(
        zip(register_sizes[:-1], register_sizes[1:], strict=True), start=1
    ):
        num_nodes = 2 ** (len(register_sizes) - level - 1)
        adder = qp.SemiAdder(Wire[output_size], Wire[output_size], Wire[output_size - 1])
        resources[adder] += num_nodes
        resources[qp.Hadamard] += num_nodes * 2 * (output_size - child_size)
        if mode == "postselect":
            resources[qp.Hadamard] += num_nodes * output_size
            mid_measure = qp.ops.MidMeasure(Wire[1], reset=True, postselect=0)
            resources[mid_measure] += num_nodes * output_size
        else:
            # source measurements, then source and output resets
            resources[qp.ops.PauliMeasure("X", Wire[1])] += num_nodes * output_size
            resources[qp.ops.PauliMeasure("Z", Wire[1])] += 2 * num_nodes * output_size
            resources[qp.X] += 2 * num_nodes * output_size

    return resources


[docs] def make_phase_gradient_distillation_decomp(aux_wires, work_wires, mode="repeat-until-success"): r"""Create a decomposition rule for :class:`~.PhaseGradientStatePrep` based on Jones distillation. The rule implements the Fourier-state distillation protocol from `Jones (2013) <https://arxiv.org/abs/1303.3066>`__ and uses only Clifford gates, :class:`~.SemiAdder`, (Pauli) mid-circuit measurements, and classical control. The prepared state is approximate: the number of distillation rounds grows as :math:`\mathcal{O}(\log n)` for an :math:`n`-qubit register and targets an infidelity of at most :math:`\sin^2(\pi/2^n)`. The output, auxiliary, and work registers require :math:`n`, :math:`n`, and :math:`n-1` wires, respectively. All wires must be distinct and start in :math:`|0\rangle`. The decomposition uses the negative-phase convention of :class:`~.PhaseGradientStatePrep`. Args: aux_wires (WiresLike): auxiliary register with the same size as the output register, i.e. the target register of the ``PhaseGradientStatePrep`` operator to be decomposed. work_wires (WiresLike): at least :math:`n-1` clean wires used by :class:`~.SemiAdder` mode (str): ``"repeat-until-success"`` (default) or ``"postselect"``, see below Returns: pennylane.decomposition.DecompositionRule: the fixed decomposition rule **Example** The rule is passed to :func:`qp.decompose` via ``fixed_decomps``: .. code-block:: python import pennylane as qp qp.decomposition.enable_graph() registers = qp.registers({"grad": 3, "aux": 3, "work": 2}) rule = qp.transforms.decompositions.make_phase_gradient_distillation_decomp( registers["aux"], registers["work"] ) gate_set = { "Hadamard", "S", "Adjoint(S)", "T", "Adjoint(T)", "CNOT", "X", "Z", "measure", "PauliMeasure", } @qp.qjit(capture=True) @qp.decompose(gate_set=gate_set, fixed_decomps={qp.PhaseGradientStatePrep: rule}) @qp.qnode(qp.device("lightning.qubit", wires=8)) def circuit(): qp.PhaseGradientStatePrep(registers["grad"]) return qp.state() Only Clifford+T gates and (Pauli) mid-circuit measurements remain: >>> sorted(qp.analyze(circuit)().resources.quantum_operations) ['Adjoint(S)', 'Adjoint(T)', 'CNOT', 'Hadamard', 'MidCircuitMeasure', 'PPM-w1', 'PauliX', 'PauliZ', 'T'] """ # ``mode="repeat-until-success"`` implements local retries with nested # :func:`~.while_loop`\ s and requires program capture. Each loop is annotated with its # expected number of attempts via :func:`~.hint`, such that :func:`~.analyze` reports expected # resource counts. ``mode="postselect"`` represents the successful branch and is useful for # analytic simulation and fidelity checks. if mode not in {"repeat-until-success", "postselect"}: raise ValueError("mode must be 'repeat-until-success' or 'postselect'; " f"got {mode!r}.") aux_wires = Wires(aux_wires) work_wires = Wires(work_wires) num_work_wires = max(0, len(aux_wires) - 1) if len(work_wires) < num_work_wires: raise WireError( "work_wires must contain at least len(aux_wires) - 1 wires; " f"got {len(work_wires)} work wires and {len(aux_wires)} auxiliary wires." ) work_wires = work_wires[:num_work_wires] def resource_fn(wires): return _distillation_resources(len(wires), mode) @register_resources(resource_fn, exact=False) def phase_gradient_distillation(wires): output_wires = Wires(wires) num_wires = len(output_wires) if len(aux_wires) != num_wires: raise WireError( "aux_wires must have the same size as the PhaseGradientStatePrep register; " f"got {len(aux_wires)} auxiliary wires and {num_wires} output wires." ) validate_no_wire_overlaps( {"wires": output_wires, "aux_wires": aux_wires, "work_wires": work_wires} ) register_sizes = _jones_register_sizes(num_wires) _prepare_distilled_state( len(register_sizes) - 1, list(output_wires), list(aux_wires + work_wires), register_sizes, mode, ) return phase_gradient_distillation