Fourier Loading

​

Haiqu.fourier_loading(fourier_coefficients, num_qubits=None, min_freqs=None, long_range=False, num_layers=2, truncation_cutoff=1e-06, fine_tuning_iterations=20, max_time=900, name=None, job_description=None)

​

NOTE

​

NOTE

​

NOTE

• Parameters:
  • fourier_coefficients (Sequence *[*Number ] | np.ndarray) — The multidimensional array of Fourier coefficients, ascending in frequency along every axis, which is not the order np.fft.fftn returns (see the frequency-layout note above). May be real or complex, and is normalized in the process. This is the layout that compute_fourier_coefficients() returns, which is the recommended way to obtain it; an analytically known spectrum can equally be written down directly.
  • num_qubits (int | Sequence *[*int ] | None) — The number of output qubits per dimension. An integer is shared by all dimensions, a sequence sets them individually in the order of the coefficient array’s axes. Each entry must be at least ceil(log2(n)) for a dimension holding n frequencies; every qubit above that minimum interpolates the state onto a finer grid. If None (default), the minimum that fits the coefficients is used, which performs no interpolation.
  • min_freqs (int | Sequence *[*int ] | None) — The integer frequency that the first coefficient of each dimension carries. An integer is shared by all dimensions, a sequence sets them individually in the order of the coefficient array’s axes. If None (default), each dimension is assumed to hold a band centred on zero and takes -(n // 2) for its length n. It is applied as a frequency-shift layer, so a value that disagrees with how the coefficients were obtained silently encodes the wrong state — see the frequency-layout note above.
  • long_range (bool) — Whether to allow long-range gates in the Fourier part of the circuit. The prepared state is the same either way, while False (default) keeps the gates on a linear chain.
  • num_layers (int) — The number of layers used to synthesize the coefficients (from 1 to 100 layers). More layers can improve the quality of the output at the cost of a deeper circuit. Defaults to 2.
  • truncation_cutoff (Real) — The entanglement cutoff for later layers. Increasing this threshold may result in a smaller (but more approximate) circuit. Defaults to 1e-6.
  • fine_tuning_iterations (int) — The maximum number of fine-tuning iterations to perform after each layer is added. Increasing this limit may improve the quality of the circuit by using more classical resources. Defaults to 20, maximal is 500.
  • max_time (int | float) — Soft time limit for the job (in seconds). The data loading job will first always produce the initial result and then limit the fine-tuning stage by the remaining time left. If time limit exceeds during the fine-tuning - the best current result will be returned. Defaults to 900 (15 min). Max allowed job time is 15 min. The job can take more wall clock time than user specified max_time due to latency, initialization overheads or if the initial result already takes more time.
  • name (str | None) — The name for the job and the produced circuit. If None (default), a name will be automatically generated.
  • job_description (str | None) — The description for the job.
• Returns: The Data Loading job that will generate the circuit for the band-limited state. : Call job.result() to retrieve a Qiskit-compatible gate (HaiquCircuitGate) that prepares the state. job.quality is the achieved state fidelity vs. the supplied coefficients; job.info exposes loader metadata (fidelity, num_qubits_per_dimension). Run help(job.result) for the full description of result and info contents.
• Return type: DataLoadingJobModel

​

Examples

>>> import numpy as np
>>> from haiqu.sdk.utils import compute_fourier_coefficients
>>> grid = np.arange(64) / 64
>>> cosine = np.cos(2 * np.pi * 3 * grid)
>>> coefficients, min_freqs, truncation_fidelity = compute_fourier_coefficients(
...     cosine, freq_ranges=[(-3, 3)], return_fidelity=True
... )
>>> print(coefficients.shape, min_freqs, f"{truncation_fidelity:.6f}")
(7,) [-3] 1.000000
>>> job = haiqu.fourier_loading(coefficients, num_qubits=6, min_freqs=min_freqs)
>>> fl_gate = job.result()  # fl_gate is a Qiskit-compatible gate
>>> print(f"Cosine was loaded with fidelity {job.quality:.6f}")
Cosine was loaded with fidelity 1.000000

>>> axis = np.arange(32) / 32
>>> x, y = np.meshgrid(axis, axis, indexing="ij")
>>> gaussian = np.exp(-((x - 0.4) ** 2 + (y - 0.5) ** 2) / (4 * 0.15 ** 2))
>>> coefficients, min_freqs, truncation_fidelity = compute_fourier_coefficients(
...     gaussian, freq_ranges=[(-4, 4), (-4, 4)], return_fidelity=True
... )
>>> print(coefficients.shape, min_freqs, f"{truncation_fidelity:.6f}")
(9, 9) [-4, -4] 0.999535
>>> job = haiqu.fourier_loading(coefficients, num_qubits=8, min_freqs=min_freqs)
>>> fl_gate = job.result()
>>> print(f"{job.num_qubits} qubits, synthesis fidelity {job.quality:.6f}")
16 qubits, synthesis fidelity 0.999998
>>> print(f"Fidelity against the original array is about {truncation_fidelity * job.quality:.6f}")
Fidelity against the original array is about 0.999533

​

haiqu.sdk.utils.compute_fourier_coefficients(state, freq_ranges, return_fidelity=False)

• Parameters:
  • state (np.ndarray | Sequence) — Values of the target on a (possibly coarse) uniform grid. The array is treated as periodic on that grid, so a non-periodic target may need many frequencies; symmetrizing it along a dimension can help.
  • freq_ranges (Sequence *[*Sequence *[*int ] ]) — One (min_freq, max_freq) pair per dimension, giving the inclusive frequency band to retain. Each band must lie inside the range the grid resolves, [-(n // 2), n - n // 2 - 1] for an axis of length n.
  • return_fidelity (bool) — Whether to also return the retained fraction of the spectral energy. Defaults to False.
• Returns: The complex coefficient array of shape max_freq - min_freq + 1 per dimension, normalized to unit norm, and the per-dimension min_freq values. With return_fidelity a third value is appended: the squared overlap between the reconstruction from the retained frequencies and state. It is 1.0 when the bands cover the whole resolved spectrum, and also when they cover the entire support of a finite Fourier series, however few frequencies that is.
• Return type: tuple[np.ndarray, list[int]] | tuple[np.ndarray, list[int], float]

• Raises: ValueError — If the number of bands does not match the number of dimensions, a band is not a pair, min_freq exceeds max_freq, or a band falls outside the resolved range.

​

Examples

>>> import numpy as np
>>> from haiqu.sdk.utils import compute_fourier_coefficients
>>> grid = np.arange(64) / 64
>>> cosine = np.cos(2 * np.pi * 3 * grid)  # only the -3 and +3 harmonics are non-zero
>>> coefficients, min_freqs, fidelity = compute_fourier_coefficients(
...     cosine, freq_ranges=[(-3, 3)], return_fidelity=True
... )
>>> print(coefficients.shape, min_freqs, f"{fidelity:.6f}")
(7,) [-3] 1.000000