Utilities Module

The utils module provides various utility functions for QSP operations.

qsppack.utils.get_unitary(phase, x)[source]

Compute QSP unitary matrix for given phase factors.

This function constructs the full QSP unitary matrix for a given set of phase factors at a specific point. The unitary is built by alternating W(x) gates and phase rotations.

Parameters:

  • phase (array_like) – Phase factors for the QSP circuit. These are used to construct the phase rotation gates in the circuit.

  • x (float) – Point at which to evaluate the unitary, must be in [-1, 1].

Returns:

Real part of the (1,1) element of the QSP unitary matrix, which represents the QSP approximation of the target function.

Return type:

float

Notes

The unitary is constructed as: U = R(phi_0) * W(x) * R(phi_1) * W(x) * … * R(phi_n) where R(phi) is a phase rotation gate and W(x) is the signal processing gate.

qsppack.utils.reduced_to_full(phi_cm, parity, targetPre)[source]

Convert reduced phase factors to full phase factors for QSP.

This function constructs the full set of phase factors required for the Quantum Signal Processing (QSP) unitary matrix from a reduced set. The conversion uses symmetry properties of the phase factors and handles both even and odd parity cases.

Parameters:

  • phi_cm (array_like) – Reduced phase factors. For even parity, these represent half the total phase factors; for odd parity, they represent the unique phase factors.

  • parity (int) –

    Parity of the phase factors:

    • 0 : even parity (full length = 2*len(phi_cm) - 1)

    • 1 : odd parity (full length = 2*len(phi_cm))

  • targetPre (bool) –

    Whether to adjust for target preparation:

    • True : add π/4 to the last phase factor

    • False : use phase factors as is

Returns:

Full phase factors constructed by mirroring the reduced factors. The length depends on parity:

  • For even parity: 2*len(phi_cm) - 1

  • For odd parity: 2*len(phi_cm)

Return type:

ndarray

Notes

The full phase factors are constructed by: 1. Copying the reduced factors to the right half 2. Mirroring them to the left half 3. Adjusting the last factor if targetPre is True

qsppack.utils.chebyshev_to_func(x, coef, parity, partialcoef)[source]

Convert Chebyshev coefficients to function values.

This function evaluates a polynomial represented in the Chebyshev basis at given points.

Parameters:

  • x (array_like or float) – Points at which to evaluate the polynomial. Can be a single point or an array of points.

  • coef (array_like) – Coefficients in Chebyshev basis, ordered from lowest to highest degree

  • parity (int) – Parity of the polynomial (0 for even, 1 for odd)

  • partialcoef (bool, optional) – Whether to return only coefficients of odd/even order

Returns:

Function values at the given points. Returns a scalar if input is scalar, array otherwise.

Return type:

ndarray or float

qsppack.utils.cvx_poly_coef(func, deg, opts)[source]

Compute coefficients for a polynomial approximation using convex optimization.

This function computes the coefficients of a polynomial that best approximates a target function over specified intervals in a least-squares sense. The function is called with a target function, the degree of the polynomial, and an options dictionary.

Parameters:

  • func (callable) – The target function to approximate.

  • deg (int) – The degree of the polynomial.

  • opts (dict) –

    Options dictionary with the following fields:

    • intervalslist

      [min, max] interval for x values.

    • nptsint

      Number of points to evaluate the function at.

    • objnormfloat

      Norm to use for optimization.

    • epsilfloat

      Epsilon for numerical stability.

    • fscalefloat

      Scale factor for function values.

    • isplotbool

      Whether to plot results.

Returns:

Coefficients of the best-fit polynomial in the Chebyshev basis.

Return type:

ndarray

qsppack.utils.F(phi, parity, opts)[source]

Compute the Chebyshev coefficients of P_im.

P_im is the imaginary part of the (1,1) element of the QSP unitary matrix.

Parameters:

  • phi (array_like) – Reduced phase factors

  • parity (int) – Parity of phi (0 for even, 1 for odd)

  • opts (dict) –

    Options dictionary with fields:
    • useRealbool

      Whether to use real matrix multiplication

Returns:

Chebyshev coefficients of P_im w.r.t. T_(2k) for even parity or T_(2k-1) for odd parity

Return type:

ndarray

qsppack.utils.F_Jacobian(phi, parity, opts)[source]

Compute the Jacobian matrix of Chebyshev coefficients.

Parameters:

  • phi (array_like) – Reduced phase factors

  • parity (int) – Parity of phi (0 for even, 1 for odd)

  • opts (dict) –

    Options dictionary with fields:
    • useRealbool

      Whether to use real matrix multiplication

Returns:

(f, df) where: - f is the function values (Chebyshev coefficients) - df is the Jacobian matrix (square matrix)

Return type:

tuple

These utility functions provide essential operations for QSP calculations, including unitary matrix generation, phase factor conversion, and polynomial coefficient manipulation.

Example usage:

import numpy as np
from qsppack.utils import get_unitary, reduced_to_full, chebyshev_to_func, F, F_Jacobian

# Generate unitary matrix for given phase factors
phase_factors = np.array([0.1, 0.2, 0.3])
unitary = get_unitary(phase_factors)

# Convert reduced phase factors to full set
full_phases = reduced_to_full(phase_factors)

# Convert Chebyshev coefficients to function values
cheb_coefs = np.array([1, 0, 1])
x = np.linspace(-1, 1, 100)
func_values = chebyshev_to_func(cheb_coefs, x)

# Evaluate F function and its Jacobian
x = 0.5
f_value = F(x)
jacobian = F_Jacobian(x)