> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haiqu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Multivariate Distribution Loading

#### Haiqu.multivariate\_distribution\_loading(num\_qubits, distribution\_name, interval=(0, 1), encoding='probability', num\_layers=1, truncation\_cutoff=1e-06, fine\_tuning\_iterations=20, 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](https://docs.scipy.org/doc/scipy/reference/stats.html#continuous-distributions) distributions use
[`distribution_loading()`](../index.md#haiqu.sdk.quantum_haiqu.Haiqu.distribution_loading). See the
[multivariate distributions catalog](https://docs.haiqu.ai/catalog/multivariate_distributions) 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()`](../index.md#haiqu.sdk.quantum_haiqu.Haiqu.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](https://docs.haiqu.ai/catalog/multivariate_distributions) 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.
  * **num\_layers** (*int*) -- The number of layers in the generated circuit (from 1 to 100 layers). More layers can
    improve the quality of the output distribution at the cost of a deeper circuit. Defaults to 1.
  * **truncation\_cutoff** (*Real*) -- The entanglement cutoff for later layers, from 0 to 1. Increasing this threshold may result
    in a smaller (but more approximate) circuit. Defaults to `1e-6`.
  * **fine\_tuning\_iterations** (*int*) -- The number of the gradient-based fine-tuning iterations applied after analytical
    compilation. Defaults to 20, maximal is 500.
  * **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](https://docs.scipy.org/doc/scipy/reference/stats.html#continuous-distributions) 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 job will first always produce the initial
    result and then limit the fine-tuning stage by the remaining time left.
    Defaults to 900 (15 min).
  * **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.
* **Return type:**
  DataLoadingJobModel

#### Examples

```python theme={null}
>>> job = haiqu.multivariate_distribution_loading(
...     num_qubits=8,
...     distribution_name="bivariate_gamma",
...     interval=((0, 15), (0, 15)),
...     distribution_params={"nu": 2.0, "rho": 0.5},
... )
>>> dl_gate = job.result()  # dl_gate is a Qiskit-compatible gate
```

Copula with explicit marginals:

```python theme={null}
>>> job = haiqu.multivariate_distribution_loading(
...     num_qubits=8,
...     distribution_name="gaussian_copula",
...     interval=((-3, 3), (0, 10)),
...     copula_params={"rho": 0.5},
...     marginal_distribution_names=["norm", "gamma"],
...     marginal_distribution_params=[{"loc": 0, "scale": 1}, {"a": 2.0}],
... )
```