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 usedistribution_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, sonum_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. Withnum_qubits=(n_0, n_1)the amplitudes reshape asnp.reshape(statevector, (2**n_0, 2**n_1)), so the grid point(i_0, i_1)is amplitude indexi_0 * 2**n_1 + i_1. Each dimension is discretized into2**n_kequal 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 asvector_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_copulaselect copula loading and requirecopula_paramswith marginal distributions instead ofdistribution_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 widthb - amust be at least 1e-08. Defaults to(0, 1). - encoding (str) — How the pdf maps to amplitudes.
"probability"(default): amplitudes are proportional tosqrt(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,BlockwiseSynthesisOptionsorVariationalSynthesisOptions, 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 toNone, which this method unwraps intoAnalyticalSynthesisOptions(num_layers=2, layer_type="V", bond_dim_layer=2, entanglement_cutoff=1e-6, fine_tuning_iterations=20). - num_layers (int) — Deprecated. Pass
num_layersinsidesynthesis_options. - truncation_cutoff (Real) — Deprecated. Renamed to
entanglement_cutoffinsidesynthesis_options. - fine_tuning_iterations (int) — Deprecated. Pass
fine_tuning_iterationsinsidesynthesis_optionsinstead. - distribution_params (dict | None) — Keyword arguments of a direct multivariate distribution (e.g.
{"nu": 2.0, "rho": 0.5}forbivariate_gamma). Only valid for direct multivariate distributions. - copula_params (dict | None) — Keyword arguments of the named copula (e.g.
{"rho": 0.5}forgaussian_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.statsmarginal parameters, in the same order asmarginal_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.
- 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
- 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.qualityis the circuit-to-MPS compilation fidelity. In a notebook, a link to the job on the Dashboard is also displayed whenhaiqu.verbosityis"high". - Return type: DataLoadingJobModel