Skip to content

QSP Conventions

qsp_proc.conventions

QSP convention definitions (Angle, Symmetric, Laurent, Generalized).

AngleQSP

Angle-QSP polynomial validator based on Lemma 1.

The checks are sampled numerical versions of the four constraints: 1) parity n mod 2, 2) |P(x)| <= 1 for x in [-1, 1], 3) |P(x)| >= 1 for x in (-inf,-1] U [1,inf), 4) when n is even, P(i x) P*(i x) >= 1 for all real x.

Source code in src\qsp_proc\conventions\angle_qsp.py 
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
class AngleQSP:
    """Angle-QSP polynomial validator based on Lemma 1.

    The checks are sampled numerical versions of the four constraints:
    1) parity ``n mod 2``,
    2) ``|P(x)| <= 1`` for ``x in [-1, 1]``,
    3) ``|P(x)| >= 1`` for ``x in (-inf,-1] U [1,inf)``,
    4) when ``n`` is even, ``P(i x) P*(i x) >= 1`` for all real ``x``.
    """

    def __init__(
        self,
        target_degree: int | None = None,
        *,
        interior_samples: int = 2049,
        exterior_samples: int = 2049,
        imaginary_axis_samples: int = 2049,
        exterior_bound: float = 8.0,
        imaginary_axis_bound: float = 8.0,
        tol: float = 1e-12,
    ) -> None:
        """Initialize numerical validation settings.

        Args:
            target_degree: Optional Lemma-1 degree ``n``. If ``None``, uses
                the polynomial degree for parity and condition-4 branching.
            interior_samples: Number of samples on ``[-1, 1]``.
            exterior_samples: Number of samples on each exterior interval.
            imaginary_axis_samples: Number of samples on imaginary-axis grid.
            exterior_bound: Finite proxy for ``infinity`` in condition 3.
            imaginary_axis_bound: Sample range for condition 4.
            tol: Numerical tolerance used in inequality checks.
        """
        self._target_degree = target_degree
        self._interior_samples = interior_samples
        self._exterior_samples = exterior_samples
        self._imaginary_axis_samples = imaginary_axis_samples
        self._exterior_bound = exterior_bound
        self._imaginary_axis_bound = imaginary_axis_bound
        self._tol = tol

    @staticmethod
    def _as_chebyshev_poly(poly: ChebyshevPoly | Sequence[complex]) -> ChebyshevPoly:
        """Return a ``ChebyshevPoly`` from accepted inputs."""
        if isinstance(poly, ChebyshevPoly):
            return poly
        return ChebyshevPoly(poly)

    def _effective_degree(self, poly: ChebyshevPoly) -> int:
        """Return ``n`` used in Lemma 1 checks."""
        return poly.degree if self._target_degree is None else self._target_degree

    def condition_1_parity(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
        """Check Lemma-1 condition 1: parity equals ``n mod 2``.

        If ``target_degree`` is provided, this also enforces ``deg(P) < n``.
        """
        p = self._as_chebyshev_poly(poly)
        n = self._effective_degree(p)
        parity = p.parity(tol=self._tol)
        if parity < 0:
            return False
        if self._target_degree is not None and p.degree >= n:
            return False
        return parity == (n % 2)

    def condition_2_unit_interval(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
        """Check Lemma-1 condition 2 on sampled ``[-1, 1]``."""
        p = self._as_chebyshev_poly(poly)
        x = np.linspace(-1.0, 1.0, self._interior_samples, dtype=np.float64)
        return bool(np.all(np.abs(p(x)) <= 1.0 + self._tol))

    def condition_3_exterior(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
        """Check Lemma-1 condition 3 on sampled exterior intervals."""
        p = self._as_chebyshev_poly(poly)
        if self._exterior_bound <= 1.0:
            raise ValueError("exterior_bound must be greater than 1.0.")
        left = np.linspace(-self._exterior_bound, -1.0, self._exterior_samples, dtype=np.float64)
        right = np.linspace(1.0, self._exterior_bound, self._exterior_samples, dtype=np.float64)
        x = np.concatenate((left, right))
        return bool(np.all(np.abs(p(x)) >= 1.0 - self._tol))

    def condition_4_imaginary_axis(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
        """Check Lemma-1 condition 4 when ``n`` is even."""
        p = self._as_chebyshev_poly(poly)
        n = self._effective_degree(p)
        if n % 2 == 1:
            return True
        x = np.linspace(
            -self._imaginary_axis_bound,
            self._imaginary_axis_bound,
            self._imaginary_axis_samples,
            dtype=np.float64,
        )
        values = p(1j * x)
        return bool(np.all(np.real(values * np.conjugate(values)) >= 1.0 - self._tol))

    def validate_polynomial(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
        """Check all Lemma-1 conditions for an Angle-QSP polynomial."""
        p = self._as_chebyshev_poly(poly)
        return (
            self.condition_1_parity(p)
            and self.condition_2_unit_interval(p)
            and self.condition_3_exterior(p)
            and self.condition_4_imaginary_axis(p)
        )

    def completion_problem(self, poly: ChebyshevPoly | Sequence[complex]) -> CompletionProblem:
        """Return completion residual for ``|Q|^2 = 1 - |P|^2``."""
        p = self._as_chebyshev_poly(poly)

        def residual(x: float | np.ndarray) -> complex | np.ndarray:
            values = p(x)
            return 1.0 - values * np.conjugate(values)

        return CompletionProblem(residual=residual, target=0.0)

    def circuit_cost(self, degree: int) -> dict[str, int]:
        """Return coarse Angle-QSP gate counts from Sec. 3.3.2.

        This returns convention-level symbolic counts rather than hardware
        specific gate costs.
        """
        if degree < 0:
            raise ValueError("degree must be non-negative.")
        return {
            "degree": degree,
            "num_signal_operator_calls": degree,
            "num_single_qubit_phase_rotations": 2 * (degree + 1),
            "num_hadamards": 2,
            "num_controlled_signal_calls": 1,
        }

__init__(target_degree=None, *, interior_samples=2049, exterior_samples=2049, imaginary_axis_samples=2049, exterior_bound=8.0, imaginary_axis_bound=8.0, tol=1e-12)

Initialize numerical validation settings.

Parameters:

Name Type Description Default
target_degree int | None

Optional Lemma-1 degree n. If None, uses the polynomial degree for parity and condition-4 branching.

 None
interior_samples int

Number of samples on [-1, 1].

 2049
exterior_samples int

Number of samples on each exterior interval.

 2049
imaginary_axis_samples int

Number of samples on imaginary-axis grid.

 2049
exterior_bound float

Finite proxy for infinity in condition 3.

 8.0
imaginary_axis_bound float

Sample range for condition 4.

 8.0
tol float

Numerical tolerance used in inequality checks.

 1e-12
Source code in src\qsp_proc\conventions\angle_qsp.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def __init__(
    self,
    target_degree: int | None = None,
    *,
    interior_samples: int = 2049,
    exterior_samples: int = 2049,
    imaginary_axis_samples: int = 2049,
    exterior_bound: float = 8.0,
    imaginary_axis_bound: float = 8.0,
    tol: float = 1e-12,
) -> None:
    """Initialize numerical validation settings.

    Args:
        target_degree: Optional Lemma-1 degree ``n``. If ``None``, uses
            the polynomial degree for parity and condition-4 branching.
        interior_samples: Number of samples on ``[-1, 1]``.
        exterior_samples: Number of samples on each exterior interval.
        imaginary_axis_samples: Number of samples on imaginary-axis grid.
        exterior_bound: Finite proxy for ``infinity`` in condition 3.
        imaginary_axis_bound: Sample range for condition 4.
        tol: Numerical tolerance used in inequality checks.
    """
    self._target_degree = target_degree
    self._interior_samples = interior_samples
    self._exterior_samples = exterior_samples
    self._imaginary_axis_samples = imaginary_axis_samples
    self._exterior_bound = exterior_bound
    self._imaginary_axis_bound = imaginary_axis_bound
    self._tol = tol

condition_1_parity(poly)

Check Lemma-1 condition 1: parity equals n mod 2.

If target_degree is provided, this also enforces deg(P) < n.

Source code in src\qsp_proc\conventions\angle_qsp.py 
78
79
80
81
82
83
84
85
86
87
88
89
90
def condition_1_parity(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
    """Check Lemma-1 condition 1: parity equals ``n mod 2``.

    If ``target_degree`` is provided, this also enforces ``deg(P) < n``.
    """
    p = self._as_chebyshev_poly(poly)
    n = self._effective_degree(p)
    parity = p.parity(tol=self._tol)
    if parity < 0:
        return False
    if self._target_degree is not None and p.degree >= n:
        return False
    return parity == (n % 2)

condition_2_unit_interval(poly)

Check Lemma-1 condition 2 on sampled [-1, 1].

Source code in src\qsp_proc\conventions\angle_qsp.py 
92
93
94
95
96
def condition_2_unit_interval(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
    """Check Lemma-1 condition 2 on sampled ``[-1, 1]``."""
    p = self._as_chebyshev_poly(poly)
    x = np.linspace(-1.0, 1.0, self._interior_samples, dtype=np.float64)
    return bool(np.all(np.abs(p(x)) <= 1.0 + self._tol))

condition_3_exterior(poly)

Check Lemma-1 condition 3 on sampled exterior intervals.

Source code in src\qsp_proc\conventions\angle_qsp.py 
 98
 99
100
101
102
103
104
105
106
def condition_3_exterior(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
    """Check Lemma-1 condition 3 on sampled exterior intervals."""
    p = self._as_chebyshev_poly(poly)
    if self._exterior_bound <= 1.0:
        raise ValueError("exterior_bound must be greater than 1.0.")
    left = np.linspace(-self._exterior_bound, -1.0, self._exterior_samples, dtype=np.float64)
    right = np.linspace(1.0, self._exterior_bound, self._exterior_samples, dtype=np.float64)
    x = np.concatenate((left, right))
    return bool(np.all(np.abs(p(x)) >= 1.0 - self._tol))

condition_4_imaginary_axis(poly)

Check Lemma-1 condition 4 when n is even.

Source code in src\qsp_proc\conventions\angle_qsp.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
def condition_4_imaginary_axis(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
    """Check Lemma-1 condition 4 when ``n`` is even."""
    p = self._as_chebyshev_poly(poly)
    n = self._effective_degree(p)
    if n % 2 == 1:
        return True
    x = np.linspace(
        -self._imaginary_axis_bound,
        self._imaginary_axis_bound,
        self._imaginary_axis_samples,
        dtype=np.float64,
    )
    values = p(1j * x)
    return bool(np.all(np.real(values * np.conjugate(values)) >= 1.0 - self._tol))

validate_polynomial(poly)

Check all Lemma-1 conditions for an Angle-QSP polynomial.

Source code in src\qsp_proc\conventions\angle_qsp.py 
123
124
125
126
127
128
129
130
131
def validate_polynomial(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
    """Check all Lemma-1 conditions for an Angle-QSP polynomial."""
    p = self._as_chebyshev_poly(poly)
    return (
        self.condition_1_parity(p)
        and self.condition_2_unit_interval(p)
        and self.condition_3_exterior(p)
        and self.condition_4_imaginary_axis(p)
    )

completion_problem(poly)

Return completion residual for |Q|^2 = 1 - |P|^2.

Source code in src\qsp_proc\conventions\angle_qsp.py 
133
134
135
136
137
138
139
140
141
def completion_problem(self, poly: ChebyshevPoly | Sequence[complex]) -> CompletionProblem:
    """Return completion residual for ``|Q|^2 = 1 - |P|^2``."""
    p = self._as_chebyshev_poly(poly)

    def residual(x: float | np.ndarray) -> complex | np.ndarray:
        values = p(x)
        return 1.0 - values * np.conjugate(values)

    return CompletionProblem(residual=residual, target=0.0)

circuit_cost(degree)

Return coarse Angle-QSP gate counts from Sec. 3.3.2.

This returns convention-level symbolic counts rather than hardware specific gate costs.

Source code in src\qsp_proc\conventions\angle_qsp.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
def circuit_cost(self, degree: int) -> dict[str, int]:
    """Return coarse Angle-QSP gate counts from Sec. 3.3.2.

    This returns convention-level symbolic counts rather than hardware
    specific gate costs.
    """
    if degree < 0:
        raise ValueError("degree must be non-negative.")
    return {
        "degree": degree,
        "num_signal_operator_calls": degree,
        "num_single_qubit_phase_rotations": 2 * (degree + 1),
        "num_hadamards": 2,
        "num_controlled_signal_calls": 1,
    }

GeneralizedQSP

Generalized-QSP validator based on Lemma 4.

Lemma 4 requires exactly the unit-circle boundedness condition: |P(z)|^2 <= 1 for all z in U(1).

Source code in src\qsp_proc\conventions\generalized_qsp.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
class GeneralizedQSP:
    """Generalized-QSP validator based on Lemma 4.

    Lemma 4 requires exactly the unit-circle boundedness condition:
    ``|P(z)|^2 <= 1`` for all ``z in U(1)``.
    """

    def __init__(self, *, unit_circle_samples: int = 4096, tol: float = 1e-12) -> None:
        """Initialize numerical validation settings."""
        self._unit_circle_samples = unit_circle_samples
        self._tol = tol

    @staticmethod
    def _as_laurent(poly: LaurentPoly) -> LaurentPoly:
        """Validate and return Laurent polynomial input."""
        if not isinstance(poly, LaurentPoly):
            raise TypeError("GeneralizedQSP expects LaurentPoly input.")
        return poly

    def condition_1_unit_circle_bound(self, poly: LaurentPoly) -> bool:
        """Check Lemma-4 bound ``|P(z)|^2 <= 1`` on sampled ``U(1)``."""
        p = self._as_laurent(poly)
        theta = np.linspace(0.0, 2.0 * np.pi, self._unit_circle_samples, endpoint=False)
        z = np.exp(1j * theta)
        return bool(np.all(np.abs(p(z)) ** 2 <= 1.0 + self._tol))

    def validate_polynomial(self, poly: LaurentPoly) -> bool:
        """Validate a polynomial against the Lemma-4 condition."""
        return self.condition_1_unit_circle_bound(poly)

    def completion_problem(self, poly: LaurentPoly) -> GeneralizedCompletionProblem:
        """Return completion residual ``1 - |P(z)|^2``."""
        p = self._as_laurent(poly)

        def residual(z: complex | np.ndarray) -> float | np.ndarray:
            values = p(z)
            return np.real(1.0 - values * np.conjugate(values))

        return GeneralizedCompletionProblem(residual=residual)

    def circuit_cost(self, degree: int) -> dict[str, int]:
        """Return coarse G-QSP gate counts from Sec. 3.3.1."""
        if degree < 0:
            raise ValueError("degree must be non-negative.")
        return {
            "degree": degree,
            "num_controlled_signal_calls": degree + 1,
            "num_signal_processing_rotations": degree + 1,
            "ancilla_qubits": 1,
        }

__init__(*, unit_circle_samples=4096, tol=1e-12)

Initialize numerical validation settings.

Source code in src\qsp_proc\conventions\generalized_qsp.py 
31
32
33
34
def __init__(self, *, unit_circle_samples: int = 4096, tol: float = 1e-12) -> None:
    """Initialize numerical validation settings."""
    self._unit_circle_samples = unit_circle_samples
    self._tol = tol

condition_1_unit_circle_bound(poly)

Check Lemma-4 bound |P(z)|^2 <= 1 on sampled U(1).

Source code in src\qsp_proc\conventions\generalized_qsp.py 
43
44
45
46
47
48
def condition_1_unit_circle_bound(self, poly: LaurentPoly) -> bool:
    """Check Lemma-4 bound ``|P(z)|^2 <= 1`` on sampled ``U(1)``."""
    p = self._as_laurent(poly)
    theta = np.linspace(0.0, 2.0 * np.pi, self._unit_circle_samples, endpoint=False)
    z = np.exp(1j * theta)
    return bool(np.all(np.abs(p(z)) ** 2 <= 1.0 + self._tol))

validate_polynomial(poly)

Validate a polynomial against the Lemma-4 condition.

Source code in src\qsp_proc\conventions\generalized_qsp.py 
50
51
52
def validate_polynomial(self, poly: LaurentPoly) -> bool:
    """Validate a polynomial against the Lemma-4 condition."""
    return self.condition_1_unit_circle_bound(poly)

completion_problem(poly)

Return completion residual 1 - |P(z)|^2.

Source code in src\qsp_proc\conventions\generalized_qsp.py 
54
55
56
57
58
59
60
61
62
def completion_problem(self, poly: LaurentPoly) -> GeneralizedCompletionProblem:
    """Return completion residual ``1 - |P(z)|^2``."""
    p = self._as_laurent(poly)

    def residual(z: complex | np.ndarray) -> float | np.ndarray:
        values = p(z)
        return np.real(1.0 - values * np.conjugate(values))

    return GeneralizedCompletionProblem(residual=residual)

circuit_cost(degree)

Return coarse G-QSP gate counts from Sec. 3.3.1.

Source code in src\qsp_proc\conventions\generalized_qsp.py 
64
65
66
67
68
69
70
71
72
73
def circuit_cost(self, degree: int) -> dict[str, int]:
    """Return coarse G-QSP gate counts from Sec. 3.3.1."""
    if degree < 0:
        raise ValueError("degree must be non-negative.")
    return {
        "degree": degree,
        "num_controlled_signal_calls": degree + 1,
        "num_signal_processing_rotations": degree + 1,
        "ancilla_qubits": 1,
    }

LaurentQSP

Laurent-QSP polynomial validator based on Lemma 3.

Conditions checked numerically: 1) A and B are real-on-circle, 2) A and B are pure (reciprocal or anti-reciprocal), 3) A(e^{i theta})^2 + B(e^{i theta})^2 <= 1 on sampled unit-circle points.

Source code in src\qsp_proc\conventions\laurent_qsp.py 
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
class LaurentQSP:
    """Laurent-QSP polynomial validator based on Lemma 3.

    Conditions checked numerically:
    1) ``A`` and ``B`` are real-on-circle,
    2) ``A`` and ``B`` are pure (reciprocal or anti-reciprocal),
    3) ``A(e^{i theta})^2 + B(e^{i theta})^2 <= 1`` on sampled unit-circle points.
    """

    def __init__(self, *, unit_circle_samples: int = 4096, tol: float = 1e-12) -> None:
        """Initialize numerical validation settings."""
        self._unit_circle_samples = unit_circle_samples
        self._tol = tol

    @staticmethod
    def _as_laurent(poly: LaurentPoly) -> LaurentPoly:
        """Validate and return Laurent polynomial input."""
        if not isinstance(poly, LaurentPoly):
            raise TypeError("LaurentQSP expects LaurentPoly inputs.")
        return poly

    def condition_1_real_on_circle(self, a: LaurentPoly, b: LaurentPoly) -> bool:
        """Check Lemma-3 real-on-circle requirement for ``A`` and ``B``."""
        a_poly = self._as_laurent(a)
        b_poly = self._as_laurent(b)
        theta = np.linspace(0.0, 2.0 * np.pi, self._unit_circle_samples, endpoint=False)
        z = np.exp(1j * theta)
        a_values = a_poly(z)
        b_values = b_poly(z)
        return bool(
            np.max(np.abs(np.imag(a_values))) <= self._tol
            and np.max(np.abs(np.imag(b_values))) <= self._tol
        )

    def condition_2_pure(self, a: LaurentPoly, b: LaurentPoly) -> bool:
        """Check Lemma-3 purity (reciprocal or anti-reciprocal)."""
        a_poly = self._as_laurent(a)
        b_poly = self._as_laurent(b)
        a_pure = a_poly.is_reciprocal(tol=self._tol) or a_poly.is_anti_reciprocal(tol=self._tol)
        b_pure = b_poly.is_reciprocal(tol=self._tol) or b_poly.is_anti_reciprocal(tol=self._tol)
        return bool(a_pure and b_pure)

    def condition_3_bounded_sum(self, a: LaurentPoly, b: LaurentPoly) -> bool:
        """Check Lemma-3 bound ``A^2 + B^2 <= 1`` on ``U(1)``."""
        a_poly = self._as_laurent(a)
        b_poly = self._as_laurent(b)
        theta = np.linspace(0.0, 2.0 * np.pi, self._unit_circle_samples, endpoint=False)
        z = np.exp(1j * theta)
        lhs = np.real(a_poly(z)) ** 2 + np.real(b_poly(z)) ** 2
        return bool(np.all(lhs <= 1.0 + self._tol))

    def validate_polynomial(self, polys: tuple[LaurentPoly, LaurentPoly]) -> bool:
        """Validate a pair ``(A, B)`` against Lemma-3 constraints."""
        a, b = polys
        return (
            self.condition_1_real_on_circle(a, b)
            and self.condition_2_pure(a, b)
            and self.condition_3_bounded_sum(a, b)
        )

    def completion_problem(self, polys: tuple[LaurentPoly, LaurentPoly]) -> LaurentCompletionProblem:
        """Return completion residual ``1 - A^2 - B^2`` on the unit circle."""
        a, b = polys
        a_poly = self._as_laurent(a)
        b_poly = self._as_laurent(b)

        def residual(z: complex | np.ndarray) -> complex | np.ndarray:
            return 1.0 - a_poly(z) ** 2 - b_poly(z) ** 2

        return LaurentCompletionProblem(residual=residual)

    def circuit_cost(self, degree: int) -> dict[str, int]:
        """Return coarse Laurent-QSP gate counts from Sec. 3.3.3."""
        if degree < 0:
            raise ValueError("degree must be non-negative.")
        return {
            "degree": degree,
            "num_controlled_signal_calls": 2 * degree,
            "num_single_qubit_basis_changes": 2,
            "num_controlled_phase_gates": 1,
            "num_signal_processing_rotations": 2 * (2 * degree + 1),
            "ancilla_qubits": 2,
        }

__init__(*, unit_circle_samples=4096, tol=1e-12)

Initialize numerical validation settings.

Source code in src\qsp_proc\conventions\laurent_qsp.py 
34
35
36
37
def __init__(self, *, unit_circle_samples: int = 4096, tol: float = 1e-12) -> None:
    """Initialize numerical validation settings."""
    self._unit_circle_samples = unit_circle_samples
    self._tol = tol

condition_1_real_on_circle(a, b)

Check Lemma-3 real-on-circle requirement for A and B.

Source code in src\qsp_proc\conventions\laurent_qsp.py 
46
47
48
49
50
51
52
53
54
55
56
57
def condition_1_real_on_circle(self, a: LaurentPoly, b: LaurentPoly) -> bool:
    """Check Lemma-3 real-on-circle requirement for ``A`` and ``B``."""
    a_poly = self._as_laurent(a)
    b_poly = self._as_laurent(b)
    theta = np.linspace(0.0, 2.0 * np.pi, self._unit_circle_samples, endpoint=False)
    z = np.exp(1j * theta)
    a_values = a_poly(z)
    b_values = b_poly(z)
    return bool(
        np.max(np.abs(np.imag(a_values))) <= self._tol
        and np.max(np.abs(np.imag(b_values))) <= self._tol
    )

condition_2_pure(a, b)

Check Lemma-3 purity (reciprocal or anti-reciprocal).

Source code in src\qsp_proc\conventions\laurent_qsp.py 
59
60
61
62
63
64
65
def condition_2_pure(self, a: LaurentPoly, b: LaurentPoly) -> bool:
    """Check Lemma-3 purity (reciprocal or anti-reciprocal)."""
    a_poly = self._as_laurent(a)
    b_poly = self._as_laurent(b)
    a_pure = a_poly.is_reciprocal(tol=self._tol) or a_poly.is_anti_reciprocal(tol=self._tol)
    b_pure = b_poly.is_reciprocal(tol=self._tol) or b_poly.is_anti_reciprocal(tol=self._tol)
    return bool(a_pure and b_pure)

condition_3_bounded_sum(a, b)

Check Lemma-3 bound A^2 + B^2 <= 1 on U(1).

Source code in src\qsp_proc\conventions\laurent_qsp.py 
67
68
69
70
71
72
73
74
def condition_3_bounded_sum(self, a: LaurentPoly, b: LaurentPoly) -> bool:
    """Check Lemma-3 bound ``A^2 + B^2 <= 1`` on ``U(1)``."""
    a_poly = self._as_laurent(a)
    b_poly = self._as_laurent(b)
    theta = np.linspace(0.0, 2.0 * np.pi, self._unit_circle_samples, endpoint=False)
    z = np.exp(1j * theta)
    lhs = np.real(a_poly(z)) ** 2 + np.real(b_poly(z)) ** 2
    return bool(np.all(lhs <= 1.0 + self._tol))

validate_polynomial(polys)

Validate a pair (A, B) against Lemma-3 constraints.

Source code in src\qsp_proc\conventions\laurent_qsp.py 
76
77
78
79
80
81
82
83
def validate_polynomial(self, polys: tuple[LaurentPoly, LaurentPoly]) -> bool:
    """Validate a pair ``(A, B)`` against Lemma-3 constraints."""
    a, b = polys
    return (
        self.condition_1_real_on_circle(a, b)
        and self.condition_2_pure(a, b)
        and self.condition_3_bounded_sum(a, b)
    )

completion_problem(polys)

Return completion residual 1 - A^2 - B^2 on the unit circle.

Source code in src\qsp_proc\conventions\laurent_qsp.py 
85
86
87
88
89
90
91
92
93
94
def completion_problem(self, polys: tuple[LaurentPoly, LaurentPoly]) -> LaurentCompletionProblem:
    """Return completion residual ``1 - A^2 - B^2`` on the unit circle."""
    a, b = polys
    a_poly = self._as_laurent(a)
    b_poly = self._as_laurent(b)

    def residual(z: complex | np.ndarray) -> complex | np.ndarray:
        return 1.0 - a_poly(z) ** 2 - b_poly(z) ** 2

    return LaurentCompletionProblem(residual=residual)

circuit_cost(degree)

Return coarse Laurent-QSP gate counts from Sec. 3.3.3.

Source code in src\qsp_proc\conventions\laurent_qsp.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def circuit_cost(self, degree: int) -> dict[str, int]:
    """Return coarse Laurent-QSP gate counts from Sec. 3.3.3."""
    if degree < 0:
        raise ValueError("degree must be non-negative.")
    return {
        "degree": degree,
        "num_controlled_signal_calls": 2 * degree,
        "num_single_qubit_basis_changes": 2,
        "num_controlled_phase_gates": 1,
        "num_signal_processing_rotations": 2 * (2 * degree + 1),
        "ancilla_qubits": 2,
    }

SymmetricQSP

Symmetric-QSP validator based on Lemma 2.

Conditions checked numerically: 1) deg(P)=n and deg(Q)=n-1, 2) parity of P is n mod 2 and parity of Q is (n-1) mod 2, 3) |P(x)|^2 + (1-x^2)|Q(x)|^2 = 1 on [-1,1], 4) |P(x)| >= 1 on (-inf,-1] U [1,inf), 5) if n is odd, leading coefficient of Q is positive.

Source code in src\qsp_proc\conventions\sym_qsp.py 
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
class SymmetricQSP:
    """Symmetric-QSP validator based on Lemma 2.

    Conditions checked numerically:
    1) ``deg(P)=n`` and ``deg(Q)=n-1``,
    2) parity of ``P`` is ``n mod 2`` and parity of ``Q`` is ``(n-1) mod 2``,
    3) ``|P(x)|^2 + (1-x^2)|Q(x)|^2 = 1`` on ``[-1,1]``,
    4) ``|P(x)| >= 1`` on ``(-inf,-1] U [1,inf)``,
    5) if ``n`` is odd, leading coefficient of ``Q`` is positive.
    """

    def __init__(
        self,
        target_degree: int | None = None,
        *,
        interior_samples: int = 2049,
        exterior_samples: int = 2049,
        exterior_bound: float = 8.0,
        tol: float = 1e-12,
    ) -> None:
        """Initialize numerical validation settings."""
        self._target_degree = target_degree
        self._interior_samples = interior_samples
        self._exterior_samples = exterior_samples
        self._exterior_bound = exterior_bound
        self._tol = tol

    @staticmethod
    def _as_chebyshev_poly(poly: ChebyshevPoly | Sequence[complex]) -> ChebyshevPoly:
        """Return a ``ChebyshevPoly`` from accepted inputs."""
        if isinstance(poly, ChebyshevPoly):
            return poly
        return ChebyshevPoly(poly)

    def _effective_degree(self, p: ChebyshevPoly) -> int:
        """Return degree ``n`` used by this convention."""
        return p.degree if self._target_degree is None else self._target_degree

    def condition_1_degree(
        self,
        p: ChebyshevPoly | Sequence[complex],
        q: ChebyshevPoly | Sequence[complex],
    ) -> bool:
        """Check Lemma-2 condition 1 on degrees."""
        p_poly = self._as_chebyshev_poly(p)
        q_poly = self._as_chebyshev_poly(q)
        n = self._effective_degree(p_poly)
        return p_poly.degree == n and q_poly.degree == n - 1

    def condition_2_parity(
        self,
        p: ChebyshevPoly | Sequence[complex],
        q: ChebyshevPoly | Sequence[complex],
    ) -> bool:
        """Check Lemma-2 condition 2 on parity."""
        p_poly = self._as_chebyshev_poly(p)
        q_poly = self._as_chebyshev_poly(q)
        n = self._effective_degree(p_poly)
        p_parity = p_poly.parity(tol=self._tol)
        q_parity = q_poly.parity(tol=self._tol)
        if p_parity < 0 or q_parity < 0:
            return False
        return p_parity == (n % 2) and q_parity == ((n - 1) % 2)

    def condition_3_unit_interval_identity(
        self,
        p: ChebyshevPoly | Sequence[complex],
        q: ChebyshevPoly | Sequence[complex],
    ) -> bool:
        """Check Lemma-2 condition 3 on ``[-1,1]``."""
        p_poly = self._as_chebyshev_poly(p)
        q_poly = self._as_chebyshev_poly(q)
        x = np.linspace(-1.0, 1.0, self._interior_samples, dtype=np.float64)
        lhs = np.abs(p_poly(x)) ** 2 + (1.0 - x**2) * (np.abs(q_poly(x)) ** 2)
        return bool(np.allclose(lhs, 1.0, atol=self._tol, rtol=0.0))

    def condition_4_exterior(self, p: ChebyshevPoly | Sequence[complex]) -> bool:
        """Check Lemma-2 condition 4 on sampled exterior intervals."""
        p_poly = self._as_chebyshev_poly(p)
        if self._exterior_bound <= 1.0:
            raise ValueError("exterior_bound must be greater than 1.0.")
        left = np.linspace(-self._exterior_bound, -1.0, self._exterior_samples, dtype=np.float64)
        right = np.linspace(1.0, self._exterior_bound, self._exterior_samples, dtype=np.float64)
        x = np.concatenate((left, right))
        return bool(np.all(np.abs(p_poly(x)) >= 1.0 - self._tol))

    def condition_5_leading_q(
        self,
        p: ChebyshevPoly | Sequence[complex],
        q: ChebyshevPoly | Sequence[complex],
    ) -> bool:
        """Check Lemma-2 condition 5 when ``n`` is odd."""
        p_poly = self._as_chebyshev_poly(p)
        q_poly = self._as_chebyshev_poly(q)
        n = self._effective_degree(p_poly)
        q_coeffs = q_poly.coeffs
        if np.max(np.abs(np.imag(q_coeffs))) > self._tol:
            return False
        if n % 2 == 0:
            return True
        leading = float(np.real(q_coeffs[q_poly.degree]))
        return leading > 0.0

    def validate_polynomial(
        self,
        polys: tuple[ChebyshevPoly | Sequence[complex], ChebyshevPoly | Sequence[complex]],
    ) -> bool:
        """Validate a pair ``(P, Q)`` against all Lemma-2 conditions."""
        p, q = polys
        return (
            self.condition_1_degree(p, q)
            and self.condition_2_parity(p, q)
            and self.condition_3_unit_interval_identity(p, q)
            and self.condition_4_exterior(p)
            and self.condition_5_leading_q(p, q)
        )

    def completion_problem(self, p: ChebyshevPoly | Sequence[complex]) -> SymmetricCompletionProblem:
        """Return the symmetric completion target for ``|Q|^2``."""
        p_poly = self._as_chebyshev_poly(p)
        tol = self._tol

        def q_squared_target(x: float | np.ndarray) -> float | np.ndarray:
            x_arr = np.asarray(x, dtype=np.float64)
            numer = 1.0 - np.abs(p_poly(x_arr)) ** 2
            denom = 1.0 - x_arr**2
            values = np.full_like(x_arr, np.nan, dtype=np.float64)
            mask = np.abs(denom) > tol
            values[mask] = numer[mask] / denom[mask]
            if np.ndim(x_arr) == 0:
                return float(values)
            return values

        return SymmetricCompletionProblem(q_squared_target=q_squared_target)

    def circuit_cost(self, degree: int) -> dict[str, int]:
        """Return coarse symmetric-QSP gate counts."""
        if degree < 0:
            raise ValueError("degree must be non-negative.")
        reduced_phase_factors = (degree // 2) + 1
        return {
            "degree": degree,
            "reduced_phase_factors": reduced_phase_factors,
            "full_phase_factors": degree + 1,
            "num_signal_operator_calls": degree,
            "num_single_qubit_phase_rotations": degree + 1,
        }

__init__(target_degree=None, *, interior_samples=2049, exterior_samples=2049, exterior_bound=8.0, tol=1e-12)

Initialize numerical validation settings.

Source code in src\qsp_proc\conventions\sym_qsp.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def __init__(
    self,
    target_degree: int | None = None,
    *,
    interior_samples: int = 2049,
    exterior_samples: int = 2049,
    exterior_bound: float = 8.0,
    tol: float = 1e-12,
) -> None:
    """Initialize numerical validation settings."""
    self._target_degree = target_degree
    self._interior_samples = interior_samples
    self._exterior_samples = exterior_samples
    self._exterior_bound = exterior_bound
    self._tol = tol

condition_1_degree(p, q)

Check Lemma-2 condition 1 on degrees.

Source code in src\qsp_proc\conventions\sym_qsp.py 
63
64
65
66
67
68
69
70
71
72
def condition_1_degree(
    self,
    p: ChebyshevPoly | Sequence[complex],
    q: ChebyshevPoly | Sequence[complex],
) -> bool:
    """Check Lemma-2 condition 1 on degrees."""
    p_poly = self._as_chebyshev_poly(p)
    q_poly = self._as_chebyshev_poly(q)
    n = self._effective_degree(p_poly)
    return p_poly.degree == n and q_poly.degree == n - 1

condition_2_parity(p, q)

Check Lemma-2 condition 2 on parity.

Source code in src\qsp_proc\conventions\sym_qsp.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def condition_2_parity(
    self,
    p: ChebyshevPoly | Sequence[complex],
    q: ChebyshevPoly | Sequence[complex],
) -> bool:
    """Check Lemma-2 condition 2 on parity."""
    p_poly = self._as_chebyshev_poly(p)
    q_poly = self._as_chebyshev_poly(q)
    n = self._effective_degree(p_poly)
    p_parity = p_poly.parity(tol=self._tol)
    q_parity = q_poly.parity(tol=self._tol)
    if p_parity < 0 or q_parity < 0:
        return False
    return p_parity == (n % 2) and q_parity == ((n - 1) % 2)

condition_3_unit_interval_identity(p, q)

Check Lemma-2 condition 3 on [-1,1].

Source code in src\qsp_proc\conventions\sym_qsp.py 
89
90
91
92
93
94
95
96
97
98
99
def condition_3_unit_interval_identity(
    self,
    p: ChebyshevPoly | Sequence[complex],
    q: ChebyshevPoly | Sequence[complex],
) -> bool:
    """Check Lemma-2 condition 3 on ``[-1,1]``."""
    p_poly = self._as_chebyshev_poly(p)
    q_poly = self._as_chebyshev_poly(q)
    x = np.linspace(-1.0, 1.0, self._interior_samples, dtype=np.float64)
    lhs = np.abs(p_poly(x)) ** 2 + (1.0 - x**2) * (np.abs(q_poly(x)) ** 2)
    return bool(np.allclose(lhs, 1.0, atol=self._tol, rtol=0.0))

condition_4_exterior(p)

Check Lemma-2 condition 4 on sampled exterior intervals.

Source code in src\qsp_proc\conventions\sym_qsp.py 
101
102
103
104
105
106
107
108
109
def condition_4_exterior(self, p: ChebyshevPoly | Sequence[complex]) -> bool:
    """Check Lemma-2 condition 4 on sampled exterior intervals."""
    p_poly = self._as_chebyshev_poly(p)
    if self._exterior_bound <= 1.0:
        raise ValueError("exterior_bound must be greater than 1.0.")
    left = np.linspace(-self._exterior_bound, -1.0, self._exterior_samples, dtype=np.float64)
    right = np.linspace(1.0, self._exterior_bound, self._exterior_samples, dtype=np.float64)
    x = np.concatenate((left, right))
    return bool(np.all(np.abs(p_poly(x)) >= 1.0 - self._tol))

condition_5_leading_q(p, q)

Check Lemma-2 condition 5 when n is odd.

Source code in src\qsp_proc\conventions\sym_qsp.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
def condition_5_leading_q(
    self,
    p: ChebyshevPoly | Sequence[complex],
    q: ChebyshevPoly | Sequence[complex],
) -> bool:
    """Check Lemma-2 condition 5 when ``n`` is odd."""
    p_poly = self._as_chebyshev_poly(p)
    q_poly = self._as_chebyshev_poly(q)
    n = self._effective_degree(p_poly)
    q_coeffs = q_poly.coeffs
    if np.max(np.abs(np.imag(q_coeffs))) > self._tol:
        return False
    if n % 2 == 0:
        return True
    leading = float(np.real(q_coeffs[q_poly.degree]))
    return leading > 0.0

validate_polynomial(polys)

Validate a pair (P, Q) against all Lemma-2 conditions.

Source code in src\qsp_proc\conventions\sym_qsp.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
def validate_polynomial(
    self,
    polys: tuple[ChebyshevPoly | Sequence[complex], ChebyshevPoly | Sequence[complex]],
) -> bool:
    """Validate a pair ``(P, Q)`` against all Lemma-2 conditions."""
    p, q = polys
    return (
        self.condition_1_degree(p, q)
        and self.condition_2_parity(p, q)
        and self.condition_3_unit_interval_identity(p, q)
        and self.condition_4_exterior(p)
        and self.condition_5_leading_q(p, q)
    )

completion_problem(p)

Return the symmetric completion target for |Q|^2.

Source code in src\qsp_proc\conventions\sym_qsp.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def completion_problem(self, p: ChebyshevPoly | Sequence[complex]) -> SymmetricCompletionProblem:
    """Return the symmetric completion target for ``|Q|^2``."""
    p_poly = self._as_chebyshev_poly(p)
    tol = self._tol

    def q_squared_target(x: float | np.ndarray) -> float | np.ndarray:
        x_arr = np.asarray(x, dtype=np.float64)
        numer = 1.0 - np.abs(p_poly(x_arr)) ** 2
        denom = 1.0 - x_arr**2
        values = np.full_like(x_arr, np.nan, dtype=np.float64)
        mask = np.abs(denom) > tol
        values[mask] = numer[mask] / denom[mask]
        if np.ndim(x_arr) == 0:
            return float(values)
        return values

    return SymmetricCompletionProblem(q_squared_target=q_squared_target)

circuit_cost(degree)

Return coarse symmetric-QSP gate counts.

Source code in src\qsp_proc\conventions\sym_qsp.py 
160
161
162
163
164
165
166
167
168
169
170
171
def circuit_cost(self, degree: int) -> dict[str, int]:
    """Return coarse symmetric-QSP gate counts."""
    if degree < 0:
        raise ValueError("degree must be non-negative.")
    reduced_phase_factors = (degree // 2) + 1
    return {
        "degree": degree,
        "reduced_phase_factors": reduced_phase_factors,
        "full_phase_factors": degree + 1,
        "num_signal_operator_calls": degree,
        "num_single_qubit_phase_rotations": degree + 1,
    }

qsp_proc.conventions.angle_qsp

Lemma 1: Angle-QSP convention checks and helpers.

CompletionProblem dataclass

Container for the Angle-QSP completion relation.

This encodes the Lemma 1 completion target |Q(x)|^2 = 1 - |P(x)|^2.

Source code in src\qsp_proc\conventions\angle_qsp.py 
13
14
15
16
17
18
19
20
21
22
23
@dataclass(frozen=True)
class CompletionProblem:
    """Container for the Angle-QSP completion relation.

    This encodes the Lemma 1 completion target
    ``|Q(x)|^2 = 1 - |P(x)|^2``.
    """

    residual: Callable[[float | np.ndarray], complex | np.ndarray]
    target: float
    expression: str = "|Q(x)|^2 = 1 - |P(x)|^2"

AngleQSP

Angle-QSP polynomial validator based on Lemma 1.

The checks are sampled numerical versions of the four constraints: 1) parity n mod 2, 2) |P(x)| <= 1 for x in [-1, 1], 3) |P(x)| >= 1 for x in (-inf,-1] U [1,inf), 4) when n is even, P(i x) P*(i x) >= 1 for all real x.

Source code in src\qsp_proc\conventions\angle_qsp.py 
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
class AngleQSP:
    """Angle-QSP polynomial validator based on Lemma 1.

    The checks are sampled numerical versions of the four constraints:
    1) parity ``n mod 2``,
    2) ``|P(x)| <= 1`` for ``x in [-1, 1]``,
    3) ``|P(x)| >= 1`` for ``x in (-inf,-1] U [1,inf)``,
    4) when ``n`` is even, ``P(i x) P*(i x) >= 1`` for all real ``x``.
    """

    def __init__(
        self,
        target_degree: int | None = None,
        *,
        interior_samples: int = 2049,
        exterior_samples: int = 2049,
        imaginary_axis_samples: int = 2049,
        exterior_bound: float = 8.0,
        imaginary_axis_bound: float = 8.0,
        tol: float = 1e-12,
    ) -> None:
        """Initialize numerical validation settings.

        Args:
            target_degree: Optional Lemma-1 degree ``n``. If ``None``, uses
                the polynomial degree for parity and condition-4 branching.
            interior_samples: Number of samples on ``[-1, 1]``.
            exterior_samples: Number of samples on each exterior interval.
            imaginary_axis_samples: Number of samples on imaginary-axis grid.
            exterior_bound: Finite proxy for ``infinity`` in condition 3.
            imaginary_axis_bound: Sample range for condition 4.
            tol: Numerical tolerance used in inequality checks.
        """
        self._target_degree = target_degree
        self._interior_samples = interior_samples
        self._exterior_samples = exterior_samples
        self._imaginary_axis_samples = imaginary_axis_samples
        self._exterior_bound = exterior_bound
        self._imaginary_axis_bound = imaginary_axis_bound
        self._tol = tol

    @staticmethod
    def _as_chebyshev_poly(poly: ChebyshevPoly | Sequence[complex]) -> ChebyshevPoly:
        """Return a ``ChebyshevPoly`` from accepted inputs."""
        if isinstance(poly, ChebyshevPoly):
            return poly
        return ChebyshevPoly(poly)

    def _effective_degree(self, poly: ChebyshevPoly) -> int:
        """Return ``n`` used in Lemma 1 checks."""
        return poly.degree if self._target_degree is None else self._target_degree

    def condition_1_parity(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
        """Check Lemma-1 condition 1: parity equals ``n mod 2``.

        If ``target_degree`` is provided, this also enforces ``deg(P) < n``.
        """
        p = self._as_chebyshev_poly(poly)
        n = self._effective_degree(p)
        parity = p.parity(tol=self._tol)
        if parity < 0:
            return False
        if self._target_degree is not None and p.degree >= n:
            return False
        return parity == (n % 2)

    def condition_2_unit_interval(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
        """Check Lemma-1 condition 2 on sampled ``[-1, 1]``."""
        p = self._as_chebyshev_poly(poly)
        x = np.linspace(-1.0, 1.0, self._interior_samples, dtype=np.float64)
        return bool(np.all(np.abs(p(x)) <= 1.0 + self._tol))

    def condition_3_exterior(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
        """Check Lemma-1 condition 3 on sampled exterior intervals."""
        p = self._as_chebyshev_poly(poly)
        if self._exterior_bound <= 1.0:
            raise ValueError("exterior_bound must be greater than 1.0.")
        left = np.linspace(-self._exterior_bound, -1.0, self._exterior_samples, dtype=np.float64)
        right = np.linspace(1.0, self._exterior_bound, self._exterior_samples, dtype=np.float64)
        x = np.concatenate((left, right))
        return bool(np.all(np.abs(p(x)) >= 1.0 - self._tol))

    def condition_4_imaginary_axis(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
        """Check Lemma-1 condition 4 when ``n`` is even."""
        p = self._as_chebyshev_poly(poly)
        n = self._effective_degree(p)
        if n % 2 == 1:
            return True
        x = np.linspace(
            -self._imaginary_axis_bound,
            self._imaginary_axis_bound,
            self._imaginary_axis_samples,
            dtype=np.float64,
        )
        values = p(1j * x)
        return bool(np.all(np.real(values * np.conjugate(values)) >= 1.0 - self._tol))

    def validate_polynomial(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
        """Check all Lemma-1 conditions for an Angle-QSP polynomial."""
        p = self._as_chebyshev_poly(poly)
        return (
            self.condition_1_parity(p)
            and self.condition_2_unit_interval(p)
            and self.condition_3_exterior(p)
            and self.condition_4_imaginary_axis(p)
        )

    def completion_problem(self, poly: ChebyshevPoly | Sequence[complex]) -> CompletionProblem:
        """Return completion residual for ``|Q|^2 = 1 - |P|^2``."""
        p = self._as_chebyshev_poly(poly)

        def residual(x: float | np.ndarray) -> complex | np.ndarray:
            values = p(x)
            return 1.0 - values * np.conjugate(values)

        return CompletionProblem(residual=residual, target=0.0)

    def circuit_cost(self, degree: int) -> dict[str, int]:
        """Return coarse Angle-QSP gate counts from Sec. 3.3.2.

        This returns convention-level symbolic counts rather than hardware
        specific gate costs.
        """
        if degree < 0:
            raise ValueError("degree must be non-negative.")
        return {
            "degree": degree,
            "num_signal_operator_calls": degree,
            "num_single_qubit_phase_rotations": 2 * (degree + 1),
            "num_hadamards": 2,
            "num_controlled_signal_calls": 1,
        }

__init__(target_degree=None, *, interior_samples=2049, exterior_samples=2049, imaginary_axis_samples=2049, exterior_bound=8.0, imaginary_axis_bound=8.0, tol=1e-12)

Initialize numerical validation settings.

Parameters:

Name Type Description Default
target_degree int | None

Optional Lemma-1 degree n. If None, uses the polynomial degree for parity and condition-4 branching.

 None
interior_samples int

Number of samples on [-1, 1].

 2049
exterior_samples int

Number of samples on each exterior interval.

 2049
imaginary_axis_samples int

Number of samples on imaginary-axis grid.

 2049
exterior_bound float

Finite proxy for infinity in condition 3.

 8.0
imaginary_axis_bound float

Sample range for condition 4.

 8.0
tol float

Numerical tolerance used in inequality checks.

 1e-12
Source code in src\qsp_proc\conventions\angle_qsp.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def __init__(
    self,
    target_degree: int | None = None,
    *,
    interior_samples: int = 2049,
    exterior_samples: int = 2049,
    imaginary_axis_samples: int = 2049,
    exterior_bound: float = 8.0,
    imaginary_axis_bound: float = 8.0,
    tol: float = 1e-12,
) -> None:
    """Initialize numerical validation settings.

    Args:
        target_degree: Optional Lemma-1 degree ``n``. If ``None``, uses
            the polynomial degree for parity and condition-4 branching.
        interior_samples: Number of samples on ``[-1, 1]``.
        exterior_samples: Number of samples on each exterior interval.
        imaginary_axis_samples: Number of samples on imaginary-axis grid.
        exterior_bound: Finite proxy for ``infinity`` in condition 3.
        imaginary_axis_bound: Sample range for condition 4.
        tol: Numerical tolerance used in inequality checks.
    """
    self._target_degree = target_degree
    self._interior_samples = interior_samples
    self._exterior_samples = exterior_samples
    self._imaginary_axis_samples = imaginary_axis_samples
    self._exterior_bound = exterior_bound
    self._imaginary_axis_bound = imaginary_axis_bound
    self._tol = tol

condition_1_parity(poly)

Check Lemma-1 condition 1: parity equals n mod 2.

If target_degree is provided, this also enforces deg(P) < n.

Source code in src\qsp_proc\conventions\angle_qsp.py 
78
79
80
81
82
83
84
85
86
87
88
89
90
def condition_1_parity(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
    """Check Lemma-1 condition 1: parity equals ``n mod 2``.

    If ``target_degree`` is provided, this also enforces ``deg(P) < n``.
    """
    p = self._as_chebyshev_poly(poly)
    n = self._effective_degree(p)
    parity = p.parity(tol=self._tol)
    if parity < 0:
        return False
    if self._target_degree is not None and p.degree >= n:
        return False
    return parity == (n % 2)

condition_2_unit_interval(poly)

Check Lemma-1 condition 2 on sampled [-1, 1].

Source code in src\qsp_proc\conventions\angle_qsp.py 
92
93
94
95
96
def condition_2_unit_interval(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
    """Check Lemma-1 condition 2 on sampled ``[-1, 1]``."""
    p = self._as_chebyshev_poly(poly)
    x = np.linspace(-1.0, 1.0, self._interior_samples, dtype=np.float64)
    return bool(np.all(np.abs(p(x)) <= 1.0 + self._tol))

condition_3_exterior(poly)

Check Lemma-1 condition 3 on sampled exterior intervals.

Source code in src\qsp_proc\conventions\angle_qsp.py 
 98
 99
100
101
102
103
104
105
106
def condition_3_exterior(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
    """Check Lemma-1 condition 3 on sampled exterior intervals."""
    p = self._as_chebyshev_poly(poly)
    if self._exterior_bound <= 1.0:
        raise ValueError("exterior_bound must be greater than 1.0.")
    left = np.linspace(-self._exterior_bound, -1.0, self._exterior_samples, dtype=np.float64)
    right = np.linspace(1.0, self._exterior_bound, self._exterior_samples, dtype=np.float64)
    x = np.concatenate((left, right))
    return bool(np.all(np.abs(p(x)) >= 1.0 - self._tol))

condition_4_imaginary_axis(poly)

Check Lemma-1 condition 4 when n is even.

Source code in src\qsp_proc\conventions\angle_qsp.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
def condition_4_imaginary_axis(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
    """Check Lemma-1 condition 4 when ``n`` is even."""
    p = self._as_chebyshev_poly(poly)
    n = self._effective_degree(p)
    if n % 2 == 1:
        return True
    x = np.linspace(
        -self._imaginary_axis_bound,
        self._imaginary_axis_bound,
        self._imaginary_axis_samples,
        dtype=np.float64,
    )
    values = p(1j * x)
    return bool(np.all(np.real(values * np.conjugate(values)) >= 1.0 - self._tol))

validate_polynomial(poly)

Check all Lemma-1 conditions for an Angle-QSP polynomial.

Source code in src\qsp_proc\conventions\angle_qsp.py 
123
124
125
126
127
128
129
130
131
def validate_polynomial(self, poly: ChebyshevPoly | Sequence[complex]) -> bool:
    """Check all Lemma-1 conditions for an Angle-QSP polynomial."""
    p = self._as_chebyshev_poly(poly)
    return (
        self.condition_1_parity(p)
        and self.condition_2_unit_interval(p)
        and self.condition_3_exterior(p)
        and self.condition_4_imaginary_axis(p)
    )

completion_problem(poly)

Return completion residual for |Q|^2 = 1 - |P|^2.

Source code in src\qsp_proc\conventions\angle_qsp.py 
133
134
135
136
137
138
139
140
141
def completion_problem(self, poly: ChebyshevPoly | Sequence[complex]) -> CompletionProblem:
    """Return completion residual for ``|Q|^2 = 1 - |P|^2``."""
    p = self._as_chebyshev_poly(poly)

    def residual(x: float | np.ndarray) -> complex | np.ndarray:
        values = p(x)
        return 1.0 - values * np.conjugate(values)

    return CompletionProblem(residual=residual, target=0.0)

circuit_cost(degree)

Return coarse Angle-QSP gate counts from Sec. 3.3.2.

This returns convention-level symbolic counts rather than hardware specific gate costs.

Source code in src\qsp_proc\conventions\angle_qsp.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
def circuit_cost(self, degree: int) -> dict[str, int]:
    """Return coarse Angle-QSP gate counts from Sec. 3.3.2.

    This returns convention-level symbolic counts rather than hardware
    specific gate costs.
    """
    if degree < 0:
        raise ValueError("degree must be non-negative.")
    return {
        "degree": degree,
        "num_signal_operator_calls": degree,
        "num_single_qubit_phase_rotations": 2 * (degree + 1),
        "num_hadamards": 2,
        "num_controlled_signal_calls": 1,
    }

qsp_proc.conventions.laurent_qsp

Lemma 3: Laurent-QSP convention checks and helpers.

LaurentCompletionProblem dataclass

Container for the Laurent completion relation.

For Laurent-QSP we solve for complementary terms from A(z)^2 + B(z)^2 + C(z)^2 + D(z)^2 = 1 on z in U(1).

Source code in src\qsp_proc\conventions\laurent_qsp.py 
13
14
15
16
17
18
19
20
21
22
@dataclass(frozen=True)
class LaurentCompletionProblem:
    """Container for the Laurent completion relation.

    For Laurent-QSP we solve for complementary terms from
    ``A(z)^2 + B(z)^2 + C(z)^2 + D(z)^2 = 1`` on ``z in U(1)``.
    """

    residual: Callable[[complex | np.ndarray], complex | np.ndarray]
    expression: str = "C(z)^2 + D(z)^2 = 1 - A(z)^2 - B(z)^2"

LaurentQSP

Laurent-QSP polynomial validator based on Lemma 3.

Conditions checked numerically: 1) A and B are real-on-circle, 2) A and B are pure (reciprocal or anti-reciprocal), 3) A(e^{i theta})^2 + B(e^{i theta})^2 <= 1 on sampled unit-circle points.

Source code in src\qsp_proc\conventions\laurent_qsp.py 
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
class LaurentQSP:
    """Laurent-QSP polynomial validator based on Lemma 3.

    Conditions checked numerically:
    1) ``A`` and ``B`` are real-on-circle,
    2) ``A`` and ``B`` are pure (reciprocal or anti-reciprocal),
    3) ``A(e^{i theta})^2 + B(e^{i theta})^2 <= 1`` on sampled unit-circle points.
    """

    def __init__(self, *, unit_circle_samples: int = 4096, tol: float = 1e-12) -> None:
        """Initialize numerical validation settings."""
        self._unit_circle_samples = unit_circle_samples
        self._tol = tol

    @staticmethod
    def _as_laurent(poly: LaurentPoly) -> LaurentPoly:
        """Validate and return Laurent polynomial input."""
        if not isinstance(poly, LaurentPoly):
            raise TypeError("LaurentQSP expects LaurentPoly inputs.")
        return poly

    def condition_1_real_on_circle(self, a: LaurentPoly, b: LaurentPoly) -> bool:
        """Check Lemma-3 real-on-circle requirement for ``A`` and ``B``."""
        a_poly = self._as_laurent(a)
        b_poly = self._as_laurent(b)
        theta = np.linspace(0.0, 2.0 * np.pi, self._unit_circle_samples, endpoint=False)
        z = np.exp(1j * theta)
        a_values = a_poly(z)
        b_values = b_poly(z)
        return bool(
            np.max(np.abs(np.imag(a_values))) <= self._tol
            and np.max(np.abs(np.imag(b_values))) <= self._tol
        )

    def condition_2_pure(self, a: LaurentPoly, b: LaurentPoly) -> bool:
        """Check Lemma-3 purity (reciprocal or anti-reciprocal)."""
        a_poly = self._as_laurent(a)
        b_poly = self._as_laurent(b)
        a_pure = a_poly.is_reciprocal(tol=self._tol) or a_poly.is_anti_reciprocal(tol=self._tol)
        b_pure = b_poly.is_reciprocal(tol=self._tol) or b_poly.is_anti_reciprocal(tol=self._tol)
        return bool(a_pure and b_pure)

    def condition_3_bounded_sum(self, a: LaurentPoly, b: LaurentPoly) -> bool:
        """Check Lemma-3 bound ``A^2 + B^2 <= 1`` on ``U(1)``."""
        a_poly = self._as_laurent(a)
        b_poly = self._as_laurent(b)
        theta = np.linspace(0.0, 2.0 * np.pi, self._unit_circle_samples, endpoint=False)
        z = np.exp(1j * theta)
        lhs = np.real(a_poly(z)) ** 2 + np.real(b_poly(z)) ** 2
        return bool(np.all(lhs <= 1.0 + self._tol))

    def validate_polynomial(self, polys: tuple[LaurentPoly, LaurentPoly]) -> bool:
        """Validate a pair ``(A, B)`` against Lemma-3 constraints."""
        a, b = polys
        return (
            self.condition_1_real_on_circle(a, b)
            and self.condition_2_pure(a, b)
            and self.condition_3_bounded_sum(a, b)
        )

    def completion_problem(self, polys: tuple[LaurentPoly, LaurentPoly]) -> LaurentCompletionProblem:
        """Return completion residual ``1 - A^2 - B^2`` on the unit circle."""
        a, b = polys
        a_poly = self._as_laurent(a)
        b_poly = self._as_laurent(b)

        def residual(z: complex | np.ndarray) -> complex | np.ndarray:
            return 1.0 - a_poly(z) ** 2 - b_poly(z) ** 2

        return LaurentCompletionProblem(residual=residual)

    def circuit_cost(self, degree: int) -> dict[str, int]:
        """Return coarse Laurent-QSP gate counts from Sec. 3.3.3."""
        if degree < 0:
            raise ValueError("degree must be non-negative.")
        return {
            "degree": degree,
            "num_controlled_signal_calls": 2 * degree,
            "num_single_qubit_basis_changes": 2,
            "num_controlled_phase_gates": 1,
            "num_signal_processing_rotations": 2 * (2 * degree + 1),
            "ancilla_qubits": 2,
        }

__init__(*, unit_circle_samples=4096, tol=1e-12)

Initialize numerical validation settings.

Source code in src\qsp_proc\conventions\laurent_qsp.py 
34
35
36
37
def __init__(self, *, unit_circle_samples: int = 4096, tol: float = 1e-12) -> None:
    """Initialize numerical validation settings."""
    self._unit_circle_samples = unit_circle_samples
    self._tol = tol

condition_1_real_on_circle(a, b)

Check Lemma-3 real-on-circle requirement for A and B.

Source code in src\qsp_proc\conventions\laurent_qsp.py 
46
47
48
49
50
51
52
53
54
55
56
57
def condition_1_real_on_circle(self, a: LaurentPoly, b: LaurentPoly) -> bool:
    """Check Lemma-3 real-on-circle requirement for ``A`` and ``B``."""
    a_poly = self._as_laurent(a)
    b_poly = self._as_laurent(b)
    theta = np.linspace(0.0, 2.0 * np.pi, self._unit_circle_samples, endpoint=False)
    z = np.exp(1j * theta)
    a_values = a_poly(z)
    b_values = b_poly(z)
    return bool(
        np.max(np.abs(np.imag(a_values))) <= self._tol
        and np.max(np.abs(np.imag(b_values))) <= self._tol
    )

condition_2_pure(a, b)

Check Lemma-3 purity (reciprocal or anti-reciprocal).

Source code in src\qsp_proc\conventions\laurent_qsp.py 
59
60
61
62
63
64
65
def condition_2_pure(self, a: LaurentPoly, b: LaurentPoly) -> bool:
    """Check Lemma-3 purity (reciprocal or anti-reciprocal)."""
    a_poly = self._as_laurent(a)
    b_poly = self._as_laurent(b)
    a_pure = a_poly.is_reciprocal(tol=self._tol) or a_poly.is_anti_reciprocal(tol=self._tol)
    b_pure = b_poly.is_reciprocal(tol=self._tol) or b_poly.is_anti_reciprocal(tol=self._tol)
    return bool(a_pure and b_pure)

condition_3_bounded_sum(a, b)

Check Lemma-3 bound A^2 + B^2 <= 1 on U(1).

Source code in src\qsp_proc\conventions\laurent_qsp.py 
67
68
69
70
71
72
73
74
def condition_3_bounded_sum(self, a: LaurentPoly, b: LaurentPoly) -> bool:
    """Check Lemma-3 bound ``A^2 + B^2 <= 1`` on ``U(1)``."""
    a_poly = self._as_laurent(a)
    b_poly = self._as_laurent(b)
    theta = np.linspace(0.0, 2.0 * np.pi, self._unit_circle_samples, endpoint=False)
    z = np.exp(1j * theta)
    lhs = np.real(a_poly(z)) ** 2 + np.real(b_poly(z)) ** 2
    return bool(np.all(lhs <= 1.0 + self._tol))

validate_polynomial(polys)

Validate a pair (A, B) against Lemma-3 constraints.

Source code in src\qsp_proc\conventions\laurent_qsp.py 
76
77
78
79
80
81
82
83
def validate_polynomial(self, polys: tuple[LaurentPoly, LaurentPoly]) -> bool:
    """Validate a pair ``(A, B)`` against Lemma-3 constraints."""
    a, b = polys
    return (
        self.condition_1_real_on_circle(a, b)
        and self.condition_2_pure(a, b)
        and self.condition_3_bounded_sum(a, b)
    )

completion_problem(polys)

Return completion residual 1 - A^2 - B^2 on the unit circle.

Source code in src\qsp_proc\conventions\laurent_qsp.py 
85
86
87
88
89
90
91
92
93
94
def completion_problem(self, polys: tuple[LaurentPoly, LaurentPoly]) -> LaurentCompletionProblem:
    """Return completion residual ``1 - A^2 - B^2`` on the unit circle."""
    a, b = polys
    a_poly = self._as_laurent(a)
    b_poly = self._as_laurent(b)

    def residual(z: complex | np.ndarray) -> complex | np.ndarray:
        return 1.0 - a_poly(z) ** 2 - b_poly(z) ** 2

    return LaurentCompletionProblem(residual=residual)

circuit_cost(degree)

Return coarse Laurent-QSP gate counts from Sec. 3.3.3.

Source code in src\qsp_proc\conventions\laurent_qsp.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def circuit_cost(self, degree: int) -> dict[str, int]:
    """Return coarse Laurent-QSP gate counts from Sec. 3.3.3."""
    if degree < 0:
        raise ValueError("degree must be non-negative.")
    return {
        "degree": degree,
        "num_controlled_signal_calls": 2 * degree,
        "num_single_qubit_basis_changes": 2,
        "num_controlled_phase_gates": 1,
        "num_signal_processing_rotations": 2 * (2 * degree + 1),
        "ancilla_qubits": 2,
    }

qsp_proc.conventions.generalized_qsp

Lemma 4: Generalized-QSP convention checks and helpers.

GeneralizedCompletionProblem dataclass

Container for generalized-QSP completion relation.

In G-QSP, completion enforces |Q(z)|^2 = 1 - |P(z)|^2 on z in U(1).

Source code in src\qsp_proc\conventions\generalized_qsp.py 
13
14
15
16
17
18
19
20
21
@dataclass(frozen=True)
class GeneralizedCompletionProblem:
    """Container for generalized-QSP completion relation.

    In G-QSP, completion enforces ``|Q(z)|^2 = 1 - |P(z)|^2`` on ``z in U(1)``.
    """

    residual: Callable[[complex | np.ndarray], float | np.ndarray]
    expression: str = "|Q(z)|^2 = 1 - |P(z)|^2"

GeneralizedQSP

Generalized-QSP validator based on Lemma 4.

Lemma 4 requires exactly the unit-circle boundedness condition: |P(z)|^2 <= 1 for all z in U(1).

Source code in src\qsp_proc\conventions\generalized_qsp.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
class GeneralizedQSP:
    """Generalized-QSP validator based on Lemma 4.

    Lemma 4 requires exactly the unit-circle boundedness condition:
    ``|P(z)|^2 <= 1`` for all ``z in U(1)``.
    """

    def __init__(self, *, unit_circle_samples: int = 4096, tol: float = 1e-12) -> None:
        """Initialize numerical validation settings."""
        self._unit_circle_samples = unit_circle_samples
        self._tol = tol

    @staticmethod
    def _as_laurent(poly: LaurentPoly) -> LaurentPoly:
        """Validate and return Laurent polynomial input."""
        if not isinstance(poly, LaurentPoly):
            raise TypeError("GeneralizedQSP expects LaurentPoly input.")
        return poly

    def condition_1_unit_circle_bound(self, poly: LaurentPoly) -> bool:
        """Check Lemma-4 bound ``|P(z)|^2 <= 1`` on sampled ``U(1)``."""
        p = self._as_laurent(poly)
        theta = np.linspace(0.0, 2.0 * np.pi, self._unit_circle_samples, endpoint=False)
        z = np.exp(1j * theta)
        return bool(np.all(np.abs(p(z)) ** 2 <= 1.0 + self._tol))

    def validate_polynomial(self, poly: LaurentPoly) -> bool:
        """Validate a polynomial against the Lemma-4 condition."""
        return self.condition_1_unit_circle_bound(poly)

    def completion_problem(self, poly: LaurentPoly) -> GeneralizedCompletionProblem:
        """Return completion residual ``1 - |P(z)|^2``."""
        p = self._as_laurent(poly)

        def residual(z: complex | np.ndarray) -> float | np.ndarray:
            values = p(z)
            return np.real(1.0 - values * np.conjugate(values))

        return GeneralizedCompletionProblem(residual=residual)

    def circuit_cost(self, degree: int) -> dict[str, int]:
        """Return coarse G-QSP gate counts from Sec. 3.3.1."""
        if degree < 0:
            raise ValueError("degree must be non-negative.")
        return {
            "degree": degree,
            "num_controlled_signal_calls": degree + 1,
            "num_signal_processing_rotations": degree + 1,
            "ancilla_qubits": 1,
        }

__init__(*, unit_circle_samples=4096, tol=1e-12)

Initialize numerical validation settings.

Source code in src\qsp_proc\conventions\generalized_qsp.py 
31
32
33
34
def __init__(self, *, unit_circle_samples: int = 4096, tol: float = 1e-12) -> None:
    """Initialize numerical validation settings."""
    self._unit_circle_samples = unit_circle_samples
    self._tol = tol

condition_1_unit_circle_bound(poly)

Check Lemma-4 bound |P(z)|^2 <= 1 on sampled U(1).

Source code in src\qsp_proc\conventions\generalized_qsp.py 
43
44
45
46
47
48
def condition_1_unit_circle_bound(self, poly: LaurentPoly) -> bool:
    """Check Lemma-4 bound ``|P(z)|^2 <= 1`` on sampled ``U(1)``."""
    p = self._as_laurent(poly)
    theta = np.linspace(0.0, 2.0 * np.pi, self._unit_circle_samples, endpoint=False)
    z = np.exp(1j * theta)
    return bool(np.all(np.abs(p(z)) ** 2 <= 1.0 + self._tol))

validate_polynomial(poly)

Validate a polynomial against the Lemma-4 condition.

Source code in src\qsp_proc\conventions\generalized_qsp.py 
50
51
52
def validate_polynomial(self, poly: LaurentPoly) -> bool:
    """Validate a polynomial against the Lemma-4 condition."""
    return self.condition_1_unit_circle_bound(poly)

completion_problem(poly)

Return completion residual 1 - |P(z)|^2.

Source code in src\qsp_proc\conventions\generalized_qsp.py 
54
55
56
57
58
59
60
61
62
def completion_problem(self, poly: LaurentPoly) -> GeneralizedCompletionProblem:
    """Return completion residual ``1 - |P(z)|^2``."""
    p = self._as_laurent(poly)

    def residual(z: complex | np.ndarray) -> float | np.ndarray:
        values = p(z)
        return np.real(1.0 - values * np.conjugate(values))

    return GeneralizedCompletionProblem(residual=residual)

circuit_cost(degree)

Return coarse G-QSP gate counts from Sec. 3.3.1.

Source code in src\qsp_proc\conventions\generalized_qsp.py 
64
65
66
67
68
69
70
71
72
73
def circuit_cost(self, degree: int) -> dict[str, int]:
    """Return coarse G-QSP gate counts from Sec. 3.3.1."""
    if degree < 0:
        raise ValueError("degree must be non-negative.")
    return {
        "degree": degree,
        "num_controlled_signal_calls": degree + 1,
        "num_signal_processing_rotations": degree + 1,
        "ancilla_qubits": 1,
    }

qsp_proc.conventions.sym_qsp

Lemma 2: Symmetric-QSP convention checks and helpers.

SymmetricCompletionProblem dataclass

Container for the symmetric completion relation.

In the standard symmetric-QSP form this is |Q(x)|^2 = (1 - |P(x)|^2) / (1 - x^2) for x in (-1, 1).

Source code in src\qsp_proc\conventions\sym_qsp.py 
13
14
15
16
17
18
19
20
21
22
@dataclass(frozen=True)
class SymmetricCompletionProblem:
    """Container for the symmetric completion relation.

    In the standard symmetric-QSP form this is
    ``|Q(x)|^2 = (1 - |P(x)|^2) / (1 - x^2)`` for ``x in (-1, 1)``.
    """

    q_squared_target: Callable[[float | np.ndarray], float | np.ndarray]
    expression: str = "|Q(x)|^2 = (1 - |P(x)|^2) / (1 - x^2)"

SymmetricQSP

Symmetric-QSP validator based on Lemma 2.

Conditions checked numerically: 1) deg(P)=n and deg(Q)=n-1, 2) parity of P is n mod 2 and parity of Q is (n-1) mod 2, 3) |P(x)|^2 + (1-x^2)|Q(x)|^2 = 1 on [-1,1], 4) |P(x)| >= 1 on (-inf,-1] U [1,inf), 5) if n is odd, leading coefficient of Q is positive.

Source code in src\qsp_proc\conventions\sym_qsp.py 
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
class SymmetricQSP:
    """Symmetric-QSP validator based on Lemma 2.

    Conditions checked numerically:
    1) ``deg(P)=n`` and ``deg(Q)=n-1``,
    2) parity of ``P`` is ``n mod 2`` and parity of ``Q`` is ``(n-1) mod 2``,
    3) ``|P(x)|^2 + (1-x^2)|Q(x)|^2 = 1`` on ``[-1,1]``,
    4) ``|P(x)| >= 1`` on ``(-inf,-1] U [1,inf)``,
    5) if ``n`` is odd, leading coefficient of ``Q`` is positive.
    """

    def __init__(
        self,
        target_degree: int | None = None,
        *,
        interior_samples: int = 2049,
        exterior_samples: int = 2049,
        exterior_bound: float = 8.0,
        tol: float = 1e-12,
    ) -> None:
        """Initialize numerical validation settings."""
        self._target_degree = target_degree
        self._interior_samples = interior_samples
        self._exterior_samples = exterior_samples
        self._exterior_bound = exterior_bound
        self._tol = tol

    @staticmethod
    def _as_chebyshev_poly(poly: ChebyshevPoly | Sequence[complex]) -> ChebyshevPoly:
        """Return a ``ChebyshevPoly`` from accepted inputs."""
        if isinstance(poly, ChebyshevPoly):
            return poly
        return ChebyshevPoly(poly)

    def _effective_degree(self, p: ChebyshevPoly) -> int:
        """Return degree ``n`` used by this convention."""
        return p.degree if self._target_degree is None else self._target_degree

    def condition_1_degree(
        self,
        p: ChebyshevPoly | Sequence[complex],
        q: ChebyshevPoly | Sequence[complex],
    ) -> bool:
        """Check Lemma-2 condition 1 on degrees."""
        p_poly = self._as_chebyshev_poly(p)
        q_poly = self._as_chebyshev_poly(q)
        n = self._effective_degree(p_poly)
        return p_poly.degree == n and q_poly.degree == n - 1

    def condition_2_parity(
        self,
        p: ChebyshevPoly | Sequence[complex],
        q: ChebyshevPoly | Sequence[complex],
    ) -> bool:
        """Check Lemma-2 condition 2 on parity."""
        p_poly = self._as_chebyshev_poly(p)
        q_poly = self._as_chebyshev_poly(q)
        n = self._effective_degree(p_poly)
        p_parity = p_poly.parity(tol=self._tol)
        q_parity = q_poly.parity(tol=self._tol)
        if p_parity < 0 or q_parity < 0:
            return False
        return p_parity == (n % 2) and q_parity == ((n - 1) % 2)

    def condition_3_unit_interval_identity(
        self,
        p: ChebyshevPoly | Sequence[complex],
        q: ChebyshevPoly | Sequence[complex],
    ) -> bool:
        """Check Lemma-2 condition 3 on ``[-1,1]``."""
        p_poly = self._as_chebyshev_poly(p)
        q_poly = self._as_chebyshev_poly(q)
        x = np.linspace(-1.0, 1.0, self._interior_samples, dtype=np.float64)
        lhs = np.abs(p_poly(x)) ** 2 + (1.0 - x**2) * (np.abs(q_poly(x)) ** 2)
        return bool(np.allclose(lhs, 1.0, atol=self._tol, rtol=0.0))

    def condition_4_exterior(self, p: ChebyshevPoly | Sequence[complex]) -> bool:
        """Check Lemma-2 condition 4 on sampled exterior intervals."""
        p_poly = self._as_chebyshev_poly(p)
        if self._exterior_bound <= 1.0:
            raise ValueError("exterior_bound must be greater than 1.0.")
        left = np.linspace(-self._exterior_bound, -1.0, self._exterior_samples, dtype=np.float64)
        right = np.linspace(1.0, self._exterior_bound, self._exterior_samples, dtype=np.float64)
        x = np.concatenate((left, right))
        return bool(np.all(np.abs(p_poly(x)) >= 1.0 - self._tol))

    def condition_5_leading_q(
        self,
        p: ChebyshevPoly | Sequence[complex],
        q: ChebyshevPoly | Sequence[complex],
    ) -> bool:
        """Check Lemma-2 condition 5 when ``n`` is odd."""
        p_poly = self._as_chebyshev_poly(p)
        q_poly = self._as_chebyshev_poly(q)
        n = self._effective_degree(p_poly)
        q_coeffs = q_poly.coeffs
        if np.max(np.abs(np.imag(q_coeffs))) > self._tol:
            return False
        if n % 2 == 0:
            return True
        leading = float(np.real(q_coeffs[q_poly.degree]))
        return leading > 0.0

    def validate_polynomial(
        self,
        polys: tuple[ChebyshevPoly | Sequence[complex], ChebyshevPoly | Sequence[complex]],
    ) -> bool:
        """Validate a pair ``(P, Q)`` against all Lemma-2 conditions."""
        p, q = polys
        return (
            self.condition_1_degree(p, q)
            and self.condition_2_parity(p, q)
            and self.condition_3_unit_interval_identity(p, q)
            and self.condition_4_exterior(p)
            and self.condition_5_leading_q(p, q)
        )

    def completion_problem(self, p: ChebyshevPoly | Sequence[complex]) -> SymmetricCompletionProblem:
        """Return the symmetric completion target for ``|Q|^2``."""
        p_poly = self._as_chebyshev_poly(p)
        tol = self._tol

        def q_squared_target(x: float | np.ndarray) -> float | np.ndarray:
            x_arr = np.asarray(x, dtype=np.float64)
            numer = 1.0 - np.abs(p_poly(x_arr)) ** 2
            denom = 1.0 - x_arr**2
            values = np.full_like(x_arr, np.nan, dtype=np.float64)
            mask = np.abs(denom) > tol
            values[mask] = numer[mask] / denom[mask]
            if np.ndim(x_arr) == 0:
                return float(values)
            return values

        return SymmetricCompletionProblem(q_squared_target=q_squared_target)

    def circuit_cost(self, degree: int) -> dict[str, int]:
        """Return coarse symmetric-QSP gate counts."""
        if degree < 0:
            raise ValueError("degree must be non-negative.")
        reduced_phase_factors = (degree // 2) + 1
        return {
            "degree": degree,
            "reduced_phase_factors": reduced_phase_factors,
            "full_phase_factors": degree + 1,
            "num_signal_operator_calls": degree,
            "num_single_qubit_phase_rotations": degree + 1,
        }

__init__(target_degree=None, *, interior_samples=2049, exterior_samples=2049, exterior_bound=8.0, tol=1e-12)

Initialize numerical validation settings.

Source code in src\qsp_proc\conventions\sym_qsp.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def __init__(
    self,
    target_degree: int | None = None,
    *,
    interior_samples: int = 2049,
    exterior_samples: int = 2049,
    exterior_bound: float = 8.0,
    tol: float = 1e-12,
) -> None:
    """Initialize numerical validation settings."""
    self._target_degree = target_degree
    self._interior_samples = interior_samples
    self._exterior_samples = exterior_samples
    self._exterior_bound = exterior_bound
    self._tol = tol

condition_1_degree(p, q)

Check Lemma-2 condition 1 on degrees.

Source code in src\qsp_proc\conventions\sym_qsp.py 
63
64
65
66
67
68
69
70
71
72
def condition_1_degree(
    self,
    p: ChebyshevPoly | Sequence[complex],
    q: ChebyshevPoly | Sequence[complex],
) -> bool:
    """Check Lemma-2 condition 1 on degrees."""
    p_poly = self._as_chebyshev_poly(p)
    q_poly = self._as_chebyshev_poly(q)
    n = self._effective_degree(p_poly)
    return p_poly.degree == n and q_poly.degree == n - 1

condition_2_parity(p, q)

Check Lemma-2 condition 2 on parity.

Source code in src\qsp_proc\conventions\sym_qsp.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def condition_2_parity(
    self,
    p: ChebyshevPoly | Sequence[complex],
    q: ChebyshevPoly | Sequence[complex],
) -> bool:
    """Check Lemma-2 condition 2 on parity."""
    p_poly = self._as_chebyshev_poly(p)
    q_poly = self._as_chebyshev_poly(q)
    n = self._effective_degree(p_poly)
    p_parity = p_poly.parity(tol=self._tol)
    q_parity = q_poly.parity(tol=self._tol)
    if p_parity < 0 or q_parity < 0:
        return False
    return p_parity == (n % 2) and q_parity == ((n - 1) % 2)

condition_3_unit_interval_identity(p, q)

Check Lemma-2 condition 3 on [-1,1].

Source code in src\qsp_proc\conventions\sym_qsp.py 
89
90
91
92
93
94
95
96
97
98
99
def condition_3_unit_interval_identity(
    self,
    p: ChebyshevPoly | Sequence[complex],
    q: ChebyshevPoly | Sequence[complex],
) -> bool:
    """Check Lemma-2 condition 3 on ``[-1,1]``."""
    p_poly = self._as_chebyshev_poly(p)
    q_poly = self._as_chebyshev_poly(q)
    x = np.linspace(-1.0, 1.0, self._interior_samples, dtype=np.float64)
    lhs = np.abs(p_poly(x)) ** 2 + (1.0 - x**2) * (np.abs(q_poly(x)) ** 2)
    return bool(np.allclose(lhs, 1.0, atol=self._tol, rtol=0.0))

condition_4_exterior(p)

Check Lemma-2 condition 4 on sampled exterior intervals.

Source code in src\qsp_proc\conventions\sym_qsp.py 
101
102
103
104
105
106
107
108
109
def condition_4_exterior(self, p: ChebyshevPoly | Sequence[complex]) -> bool:
    """Check Lemma-2 condition 4 on sampled exterior intervals."""
    p_poly = self._as_chebyshev_poly(p)
    if self._exterior_bound <= 1.0:
        raise ValueError("exterior_bound must be greater than 1.0.")
    left = np.linspace(-self._exterior_bound, -1.0, self._exterior_samples, dtype=np.float64)
    right = np.linspace(1.0, self._exterior_bound, self._exterior_samples, dtype=np.float64)
    x = np.concatenate((left, right))
    return bool(np.all(np.abs(p_poly(x)) >= 1.0 - self._tol))

condition_5_leading_q(p, q)

Check Lemma-2 condition 5 when n is odd.

Source code in src\qsp_proc\conventions\sym_qsp.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
def condition_5_leading_q(
    self,
    p: ChebyshevPoly | Sequence[complex],
    q: ChebyshevPoly | Sequence[complex],
) -> bool:
    """Check Lemma-2 condition 5 when ``n`` is odd."""
    p_poly = self._as_chebyshev_poly(p)
    q_poly = self._as_chebyshev_poly(q)
    n = self._effective_degree(p_poly)
    q_coeffs = q_poly.coeffs
    if np.max(np.abs(np.imag(q_coeffs))) > self._tol:
        return False
    if n % 2 == 0:
        return True
    leading = float(np.real(q_coeffs[q_poly.degree]))
    return leading > 0.0

validate_polynomial(polys)

Validate a pair (P, Q) against all Lemma-2 conditions.

Source code in src\qsp_proc\conventions\sym_qsp.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
def validate_polynomial(
    self,
    polys: tuple[ChebyshevPoly | Sequence[complex], ChebyshevPoly | Sequence[complex]],
) -> bool:
    """Validate a pair ``(P, Q)`` against all Lemma-2 conditions."""
    p, q = polys
    return (
        self.condition_1_degree(p, q)
        and self.condition_2_parity(p, q)
        and self.condition_3_unit_interval_identity(p, q)
        and self.condition_4_exterior(p)
        and self.condition_5_leading_q(p, q)
    )

completion_problem(p)

Return the symmetric completion target for |Q|^2.

Source code in src\qsp_proc\conventions\sym_qsp.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def completion_problem(self, p: ChebyshevPoly | Sequence[complex]) -> SymmetricCompletionProblem:
    """Return the symmetric completion target for ``|Q|^2``."""
    p_poly = self._as_chebyshev_poly(p)
    tol = self._tol

    def q_squared_target(x: float | np.ndarray) -> float | np.ndarray:
        x_arr = np.asarray(x, dtype=np.float64)
        numer = 1.0 - np.abs(p_poly(x_arr)) ** 2
        denom = 1.0 - x_arr**2
        values = np.full_like(x_arr, np.nan, dtype=np.float64)
        mask = np.abs(denom) > tol
        values[mask] = numer[mask] / denom[mask]
        if np.ndim(x_arr) == 0:
            return float(values)
        return values

    return SymmetricCompletionProblem(q_squared_target=q_squared_target)

circuit_cost(degree)

Return coarse symmetric-QSP gate counts.

Source code in src\qsp_proc\conventions\sym_qsp.py 
160
161
162
163
164
165
166
167
168
169
170
171
def circuit_cost(self, degree: int) -> dict[str, int]:
    """Return coarse symmetric-QSP gate counts."""
    if degree < 0:
        raise ValueError("degree must be non-negative.")
    reduced_phase_factors = (degree // 2) + 1
    return {
        "degree": degree,
        "reduced_phase_factors": reduced_phase_factors,
        "full_phase_factors": degree + 1,
        "num_signal_operator_calls": degree,
        "num_single_qubit_phase_rotations": degree + 1,
    }