QSP

qsvt_phases

qsvt_phases(
    poly_coeffs: ndarray,
    cheb_basis: bool = True,
    tol: float = 1e-12,
) -> ndarray

Get QSVT phases that will generate the given Chebyshev polynomial. The phases are ready to be used in qsvt and qsvt_lcu functions in the classiq library. The convention is the reflection signal operator, and the measurement basis is the hadamard basis (see https://arxiv.org/abs/2105.02859 APPENDIX A.). The current implementation is using the pyqsp package, based on techniques in https://arxiv.org/abs/2003.02831.

Notes

1. The polynomial should have a definite parity, and bounded in magnitude by 1 in the interval [-1, 1].
2. The phase finding works in the Chebyshev basis. If the a monomial basis polynomial is provided, it will be converted to the chebyshev basis (and introduce an additional overhead).
3. The user is advised to get the polynomial using the qsp_approximate function.
4. If the function fails, try to scale down the polynomial by a factor, it should ease the angle finding.

Parameters:

Name	Type	Description	Default
poly_coeffs	ndarray	Array of polynomial coefficients (Chebyshev\Monomial, depending on cheb_basis).	required
cheb_basis	bool	Whether the poly coefficients are given in Chebyshev (True) or Monomial(False). Defaults to Chebyshev.	True
tol	float	Error tolerance for the phases.	1e-12

Returns: phases: array of the qsvt phases corresponding to the given polynomial.

qsp_approximate

qsp_approximate(
    f_target: Callable[[float], complex],
    degree: int,
    parity: int | None = None,
    interval: tuple[float, float] = (-1, 1),
    bound: float = 0.99,
    num_grid_points: int | None = None,
    plot: bool = False,
) -> tuple[ndarray, float]

Approximate the target function on the given (sub-)interval of [-1,1], using QSP-compatible chebyshev polynomials. The approximating polynomial is enforced to |P(x)| <= bound on all of [-1,1].

Note: scaling f_target by a factor < 1 might help the convergence and also a later qsp phase factor finiding.

Parameters:

Name	Type	Description	Default
f_target	Callable[[float], complex]	Real function to approximate within the given interval. Should be bounded by [-1, 1] in the given interval.	required
degree	int	Approximating polynomial degree.	required
parity	int | None	None - full polynomial, 0 - restrict to even polynomial, 1 - odd polynomial.	None
interval	tuple[float, float]	sub interval of [-1, 1] to approximate the function within.	(-1, 1)
bound	float	global polynomial bound on [-1,1] (defaults to 0.99).	0.99
num_grid_points	int | None	sets the number of grid points used for the polynomial approximation (defaults to max(2 * degree, 1000)).	None
plot	bool	A flag for plotting the resulting approximation vs the target function.	False

Returns:

Name	Type	Description
coeffs	ndarray	Array of Chebyshev coefficients. In case of definite parity, still a full coefficients array is returned.
max_error	float	(Approximated) maximum error between the target function and the approximating polynomial within the interval.

gqsp_phases

gqsp_phases(
    poly_coeffs: ndarray, cheb_basis: bool = False
) -> tuple[ndarray, ndarray, ndarray]

Compute GQSP phases for a polynomial in the monomial (power) basis.

The returned phases are compatible with Classiq's gqsp function and use the Wz signal operator convention.

Notes: - The polynomial must be bounded on the unit circle: |P(e^{itheta})| <= 1 for all theta in [0, 2pi). - Laurent polynomials are supported by degree shifting. If P(z) = sum_{k=m}^n c_k * z^k with m < 0, the phases correspond to the degree-shifted polynomial z^{-m} * P(z) (so the minimal degree is zero). - The phase finiding works in the monomial basis. If a Chebyshev basis polynomial is provided, it will be converted to the monomial basis (and introduce an additional overhead).

Parameters:

Name	Type	Description	Default
poly		array-like of complex, shape (d+1). Monomial coefficients in ascending order: [c_0, c_1, ..., c_d].	required
cheb_basis	bool	Whether the poly coefficients are given in Chebyshev (True) or Monomial(False). Defaults to Monomial.	False

Returns:

Name	Type	Description
phases	tuple[ndarray, ndarray, ndarray]	tuple of np.ndarray (thetas, phis, lambdas), ready to use with gqsp.

Raises:

Type	Description
ValueError	if |P(e^{i*theta})| > 1 anywhere on the unit circle.

poly_jacobi_anger_cos

poly_jacobi_anger_cos(degree: int, t: float) -> ndarray

Gets the Chebyshev polynomial coefficients approximating cos(t*x) using the Jacobi-Anger expansion. $$\cos(xt) = J_0(t) + 2\sum_{k=1}^{d/2} (-1)^k J_{2k}(t)\, T_{2k}(x) $$

Parameters:

Name	Type	Description	Default
degree	int	the degree of the approximating polynomial.	required
t	float	the parameter in cos(t*x). Can be negative.	required

Returns: coeffs: The Chebyshev approximating coefficients.

poly_jacobi_anger_sin

poly_jacobi_anger_sin(degree: int, t: float) -> ndarray

Gets the Chebyshev polynomial coefficients approximating sin(t*x) using the Jacobi-Anger expansion. \(\(\sin(xt) = 2\sum_{k=0}^{d/2} (-1)^k J_{2k+1}(t)\, T_{2k+1}(x)\)\)

Parameters:

Name	Type	Description	Default
degree	int	the degree of the approximating polynomial.	required
t	float	the parameter in sin(t*x).	required

Returns: coeffs: The Chebyshev approximating coefficients.

poly_jacobi_anger_exp_sin

poly_jacobi_anger_exp_sin(degree: int, t: float) -> ndarray

Gets the Chebyshev polynomial coefficients approximating exp(itsin(x)) using the Jacobi-Anger expansion: \(\(e^{it\sin(x)} = \sum_{k=-d}^{d} J_{k}(t) e^{ikx}\)\)

Parameters:

Name	Type	Description	Default
degree	int	the maximum degree of the approximating polynomial (negative and positive).	required
t	float	the parameter in exp(itsin(x)).	required

Returns: coeffs: The approximating coefficients in monomial basis, starting from the negative ones to the positive ones (length is 2*degree+1).

poly_jacobi_anger_exp_cos

poly_jacobi_anger_exp_cos(degree: int, t: float) -> ndarray

Gets the Chebyshev polynomial coefficients approximating exp(itcos(x)) using the Jacobi-Anger expansion: \(\(e^{it\cos(x)} = \sum_{k=-d}^{d} i^k J_{k}(t) e^{ikx}\)\)

Parameters:

Name	Type	Description	Default
degree	int	the maximum degree of the approximating polynomial (negative and positive).	required
t	float	the parameter in exp(itcos(x)).	required

Returns: coeffs: The approximating coefficients in monomial basis, starting from the negative ones to the positive ones (length is 2*degree+1).

poly_inversion

poly_inversion(
    degree: int, kappa: float
) -> tuple[ndarray, float]

Gets the Chebyshev odd polynomial coefficients approximating 1/x on [1/kappa, 1] and bounded by 1 in magnitude on [-1, 1]. Based on the paper https://arxiv.org/pdf/2507.15537.

To be used within the QSVT framework, the polynomial should be scaled to be bounded by 1 on [-1, 1].

The maximum absolute value of the returned polynomial on [-1, 1] can be larger than kappa, so the user should use the returned max_value to scale down the polynomial accordingly.

Parameters:

Name	Type	Description	Default
degree	int	The degree of the approximating polynomial.	required
kappa	float	The number defining the interval [1/kappa, 1], usually represents the condition number in the setting of matrix inversion.	required

Returns:

Name	Type	Description
coeffs	ndarray	The Chebyshev polynomial coefficients approximating 1/x on [1/kappa, 1] using the optimal polynomial of given degree.
max_value	float	An upper bound on the maximum absolute value of the polynomial on [-1, 1]. The value can be used to scale down the polynomial for the usage within QSVT.