Distribution Loading

​

Haiqu.distribution_loading(num_qubits, distribution_name, interval_start, interval_end, loc=0, scale=1, encoding=‘probability’, synthesis_options=None, num_layers=None, truncation_cutoff=None, max_time=900, name=None, job_description=None, **shape)

​

NOTE

Amplitude indexing (Qiskit little-endian). The prepared state has 2**num_qubits amplitudes. data[i] is the amplitude for computational-basis index i, where the rightmost bit of i is qubit 0 (q_0). For example, with 2 qubits, data = [a, b, c, d] prepares a|00⟩ + b|01⟩ + c|10⟩ + d|11⟩. Apply the returned gate with circuit.append(gate, range(num_qubits)) so gate wire k acts on q_k. Inspect amplitudes after loading with statevector_run().

​

NOTE

Discretization order. The interval [interval_start, interval_end] is divided into 2**num_qubits equal bins. Bin i (counting from 0) spans increasing position along the interval, and its midpoint value becomes amplitude index i using the same Qiskit little-endian basis indexing as vector_loading() (rightmost bit of i is q_0).

• Parameters:
  • num_qubits (int) — The number of qubits in the generated circuit (from 1 to 1000 qubits).
  • distribution_name (str) — The name of the distribution. Can be any of the continuous distributions in scipy.stats or a characteristic function.
  • interval_start (Real) — The beginning of the interval.
  • interval_end (Real) — The end of the interval. The interval width interval_end - interval_start must be at least 1e-08.
  • loc (Real) — The location to which to shift the distribution. Defaults to 0.
  • scale (Real) — The scaling factor by which to stretch the distribution (must be positive). Defaults to 1.
  • encoding (str) — How function values map to amplitudes. "probability" (default): amplitudes are proportional to sqrt(f(x)), so measurement probabilities are proportional to f(x). "amplitude": amplitudes are proportional to f(x).
  • synthesis_options (dict | DataLoadingSynthesisOptions) — How the circuit preparing the data is synthesized. Pass one of AnalyticalSynthesisOptions, BlockwiseSynthesisOptions or VariationalSynthesisOptions, or an equivalent dict whose "method" key names one of them. Those three classes document every option each method accepts, what it means and what it defaults to. Defaults to None, which this method unwraps into AnalyticalSynthesisOptions(num_layers=1, layer_type="V", bond_dim_layer=2, entanglement_cutoff=1e-6, fine_tuning_iterations=0).
  • num_layers (int) — Deprecated. Pass num_layers inside synthesis_options.
  • truncation_cutoff (Real) — Deprecated. Renamed to entanglement_cutoff inside synthesis_options.
  • 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.
  • **shape — Additional distribution parameters, required by some distributions. Refer to the distribution documentation in scipy.stats or the characteristic functions catalog for more details.
• Returns: The Data Loading job that will generate the circuit for the probability distribution. : Call job.result() to retrieve a Qiskit-compatible gate (HaiquCircuitGate) that prepares the requested probability distribution on num_qubits qubits. job.quality is the achieved state fidelity vs. the ideal target distribution; job.info exposes loader metadata (fidelity). Run help(job.result) for the full description of result and info contents. In a notebook, a link to the job on the Dashboard is also displayed when haiqu.verbosity is "high".
• Return type: DataLoadingJobModel

​

Examples

>>> num_qubits = 4
>>> job = haiqu.distribution_loading(
...     num_qubits=num_qubits,
...     distribution_name="norm",
...     interval_start=-3,
...     interval_end=3,
...     name=f"Normal distribution ({num_qubits} qubits)",
... )
>>> dl_gate = job.result()  # dl_gate is a Qiskit-compatible gate
>>> fidelity = job.quality
>>> print(f"Normal distribution was loaded with fidelity {fidelity:.6f}")
Normal distribution was loaded with fidelity 0.999484
>>> circuit = qiskit.QuantumCircuit(num_qubits)
>>> circuit.append(dl_gate, range(num_qubits))
>>> circuit.draw()
     ┌────────────────────────────────────────────────────────────┐
q_0: ┤0                                                           ├
     │                                                            │
q_1: ┤1                                                           ├
     │  Haiqucircuit(circ-12345678-1234-5678-1234-567812345678,4) │
q_2: ┤2                                                           ├
     │                                                            │
q_3: ┤3                                                           ├
     └────────────────────────────────────────────────────────────┘

​

Haiqu.distribution_loading_estimates(num_qubits, distribution_name, interval_start, interval_end, loc=0, scale=1, encoding=‘probability’, synthesis_options=None, num_layers=None, truncation_cutoff=None, max_time=900, name=None, job_description=None, **shape)

• Parameters:
  • num_qubits (int) — The number of qubits in the generated circuit (from 1 to 1000 qubits).
  • distribution_name (str) — The name of the distribution. Can be any of the continuous distributions in scipy.stats or a characteristic function.
  • interval_start (Real) — The beginning of the interval.
  • interval_end (Real) — The end of the interval. The interval width interval_end - interval_start must be at least 1e-08.
  • loc (Real) — The location to which to shift the distribution. Defaults to 0.
  • scale (Real) — The scaling factor by which to stretch the distribution (must be positive). Defaults to 1.
  • encoding (str) — How function values map to amplitudes. "probability" (default): amplitudes are proportional to sqrt(f(x)), so measurement probabilities are proportional to f(x). "amplitude": amplitudes are proportional to f(x).
  • synthesis_options (dict | DataLoadingSynthesisOptions) — How the circuit preparing the data is synthesized. Pass one of AnalyticalSynthesisOptions, BlockwiseSynthesisOptions or VariationalSynthesisOptions, or an equivalent dict whose "method" key names one of them. Those three classes document every option each method accepts, what it means and what it defaults to. Defaults to None, which this method unwraps into AnalyticalSynthesisOptions(num_layers=1, layer_type="V", bond_dim_layer=2, entanglement_cutoff=1e-6, fine_tuning_iterations=0).
  • num_layers (int) — Deprecated. Pass num_layers inside synthesis_options.
  • truncation_cutoff (Real) — Deprecated. Renamed to entanglement_cutoff inside synthesis_options.
  • 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.
  • **shape — Additional distribution parameters, required by some distributions. Refer to the distribution documentation in scipy.stats or the characteristic functions catalog for more details.
• Returns: The estimated time (in seconds) and cost (in Haiqu Credits).
• Return type: DataLoadingEstimatesModel

​

Examples

>>> est = haiqu.distribution_loading_estimates(
...     num_qubits=10,
...     distribution_name="norm",
...     interval_start=-3,
...     interval_end=3
... )
>>> est
DataLoadingEstimatesModel(estimated_time=0.22770169152050562, estimated_cost=0.010079648405964921)
>>> est.draw()  # in Jupyter notebook