Skip to main content

Haiqu.multivariate_distribution_loading(num_qubits, distribution_name, interval=(0, 1), encoding=‘probability’, synthesis_options=None, num_layers=None, truncation_cutoff=None, fine_tuning_iterations=None, distribution_params=None, copula_params=None, marginal_distribution_names=None, marginal_distribution_params=None, max_time=900, name=None, job_description=None)

Generate a quantum circuit that prepares a multivariate probability distribution or a copula-based joint PDF. Given the description of a multivariate probability distribution function (PDF), this method creates a Data Loading job that runs in the Haiqu cloud. The result of this job is a circuit which can be used to supply the joint PDF to a quantum algorithm for processing. For one-dimensional scipy.stats distributions use distribution_loading(). See the multivariate distributions catalog for the full list of supported distributions and copulas.

NOTE

Joint distributions of two variables are supported at present, so num_qubits, interval and the copula marginals must describe two dimensions.

NOTE

Dimension order (NumPy C ordering). Dimensions occupy the statevector in C (row-major) order: the first dimension is the slowest-varying and takes the high-order qubits, the last dimension is the fastest-varying and takes the low-order qubits. With num_qubits=(n_0, n_1) the amplitudes reshape as np.reshape(statevector, (2**n_0, 2**n_1)), so the grid point (i_0, i_1) is amplitude index i_0 * 2**n_1 + i_1. Each dimension is discretized into 2**n_k equal bins over its interval, with bin 0 at the interval start, and the bits within the statevector index follow the same Qiskit little-endian convention as vector_loading().
  • Parameters:
    • num_qubits (int | Sequence *[*int ]) — Either the total number of qubits, split evenly across the dimensions, or a sequence of per-dimension qubit counts such as (3, 1) for an uneven split. A total must therefore be a multiple of the number of dimensions.
    • distribution_name (str) — The name of a multivariate distribution (e.g. bivariate_gamma, bivariate_student_t, bivariate_von_mises, marshall_olkin_weibull, bivariate_poisson_normal_approx) or a copula (gaussian_copula, clayton_copula, gumbel_copula, frank_copula). Names ending in _copula select copula loading and require copula_params with marginal distributions instead of distribution_params. See the multivariate distributions catalog for the full list.
    • interval (Sequence) — The spatial domain. Either a single pair (a, b) shared by all dimensions, or a sequence of per-dimension interval pairs. Each interval width b - a must be at least 1e-08. Defaults to (0, 1).
    • encoding (str) — How the pdf maps to amplitudes. "probability" (default): amplitudes are proportional to sqrt(pdf), so measurement probabilities are proportional to the pdf. "amplitude": amplitudes are proportional to the pdf.
    • 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=2, layer_type="V", bond_dim_layer=2, entanglement_cutoff=1e-6, fine_tuning_iterations=20).
    • num_layers (int) — Deprecated. Pass num_layers inside synthesis_options.
    • truncation_cutoff (Real) — Deprecated. Renamed to entanglement_cutoff inside synthesis_options.
    • fine_tuning_iterations (int) — Deprecated. Pass fine_tuning_iterations inside synthesis_options instead.
    • distribution_params (dict | None) — Keyword arguments of a direct multivariate distribution (e.g. {"nu": 2.0, "rho": 0.5} for bivariate_gamma). Only valid for direct multivariate distributions.
    • copula_params (dict | None) — Keyword arguments of the named copula (e.g. {"rho": 0.5} for gaussian_copula). Only valid for copulas.
    • marginal_distribution_names (Sequence *[*str ] | None) — scipy.stats 1D distribution names used as copula marginals, e.g. ["norm", "gamma"]. Only valid for copulas.
    • marginal_distribution_params (Sequence *[*dict ] | None) — Dictionaries of scipy.stats marginal parameters, in the same order as marginal_distribution_names.
    • 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 joint PDF. : Call job.result() to retrieve a Qiskit-compatible gate (HaiquCircuitGate) that prepares the requested distribution. job.quality is the circuit-to-MPS compilation fidelity. In a notebook, a link to the job on the Dashboard is also displayed when haiqu.verbosity is "high".
  • Return type: DataLoadingJobModel

Examples

Copula with explicit marginals: