Skip to main content

​
Multivariate Distribution Loading

Haiqu SDK supports loading named multidimensional probability density functions (PDFs) into quantum circuits with haiqu.multivariate_distribution_loading.
Circuit fidelity is stored in job.quality. This is the MPS-to-circuit compilation fidelity.
For a dd-dimensional distribution with njn_j qubits allocated to dimension jj, the qubit layout groups dimensions sequentially: dimension 11 occupies qubits q0(1),…,qn1−1(1)q^{(1)}_0, \ldots, q^{(1)}_{n_1-1}, dimension 22 occupies q0(2),…,qn2−1(2)q^{(2)}_0, \ldots, q^{(2)}_{n_2-1}, and so on up to dimension dd, where q0(j)q^{(j)}_0 is the least-significant-bit qubit for dimension jj. If num_qubits=(n_1, ..., n_d), the circuit uses njn_j qubits for dimension jj. Each qubit group encodes a grid index in binary: for dimension jj, the integer index ij=q0(j)⋅20+q1(j)⋅21+⋯+qnj−1(j)⋅2nj−1i_j = q^{(j)}_0 \cdot 2^0 + q^{(j)}_1 \cdot 2^1 + \cdots + q^{(j)}_{n_j-1} \cdot 2^{n_j-1} maps to the grid point xij(j)=highj−lowj2nj−1ij+lowj∈[lowj,highj].x^{(j)}_{i_j} = \frac{\mathrm{high}_j - \mathrm{low}_j}{2^{n_j} - 1} i_j + \mathrm{low}_j \in [\mathrm{low}_j, \mathrm{high}_j]. Qiskit uses the qubit-ordering convention ∣qN−1,…,q1,q0⟩|q_{N-1}, \ldots, q_1, q_0\rangle (most-significant qubit on the left), so the statevector index ordering is the reverse of the layout above: the full register reads ∣qnd−1(d),…,q0(d),…,qn1−1(1),…,q0(1)⟩|q^{(d)}_{n_d-1}, \ldots, q^{(d)}_0, \ldots, q^{(1)}_{n_1-1}, \ldots, q^{(1)}_0\rangle in Qiskit notation.

​
Encoding Modes

For a dd-dimensional grid point xi=(xi1(1),…,xid(d))\mathbf{x}_\mathbf{i} = (x^{(1)}_{i_1}, \ldots, x^{(d)}_{i_d}) and density ff, the two modes encode: ψiamplitude=f(xi)∑kf(xk)2\psi_{\mathbf{i}}^{\mathrm{amplitude}} = \frac{f(\mathbf{x}_\mathbf{i})}{\sqrt{\sum_{\mathbf{k}} f(\mathbf{x}_\mathbf{k})^2}} ψiprobability=f(xi)∑kf(xk)\psi_{\mathbf{i}}^{\mathrm{probability}} = \sqrt{\frac{f(\mathbf{x}_\mathbf{i})}{\sum_{\mathbf{k}} f(\mathbf{x}_\mathbf{k})}}
Use encoding="probability" when distribution_name refers to a PDF and measurement outcomes should sample from that PDF.

​
Parameters

​
Supported Direct 2D Distributions

​
Bivariate Student-t

Name in SDK: bivariate_student_t A heavy-tail generalization of the bivariate Gaussian. It is useful when the joint distribution needs Gaussian-like correlation structure while retaining robustness to tail events and outliers. The density is the standard two-dimensional Student-t PDF with location vector mu, scale matrix sigma, and degrees of freedom nu. f(x,y)=Γ((ν+2)/2)Γ(ν/2)νπ∣Σ∣1/2(1+(z−μ)TΣ−1(z−μ)ν)−(ν+2)/2f(x,y) = \frac{\Gamma((\nu+2)/2)}{\Gamma(\nu/2)\nu\pi|\Sigma|^{1/2}}\left(1 + \frac{(z-\mu)^T\Sigma^{-1}(z-\mu)}{\nu}\right)^{-(\nu+2)/2} where z=(x,y)Tz=(x,y)^T.

​
Bivariate Gamma

Name in SDK: bivariate_gamma Kibble’s bivariate Gamma distribution with Gamma marginals and a positive dependence parameter. The implementation uses the scaled modified Bessel function for numerical stability. f(x,y)=(xy)(ν−1)/2Γ(ν)(1−ρ)ρ(ν−1)/2exp⁡(−x+y1−ρ)Iν−1(2ρxy1−ρ)f(x,y) = \frac{(xy)^{(\nu-1)/2}}{\Gamma(\nu)(1-\rho)\rho^{(\nu-1)/2}}\exp\left(-\frac{x+y}{1-\rho}\right)I_{\nu-1}\left(\frac{2\sqrt{\rho xy}}{1-\rho}\right) where Iν−1I_{\nu-1} is the modified Bessel function of the first kind. For rho=0, the implementation returns the product of two independent Gamma densities.

​
Bivariate von Mises

Name in SDK: bivariate_von_mises A circular analogue of the bivariate Gaussian, defined on angular variables. The implementation uses the Sine model and computes the normalizing constant numerically. f(θ1,θ2)=exp⁡(κ1cos⁡(θ1−μ1)+κ2cos⁡(θ2−μ2)+λsin⁡(θ1−μ1)sin⁡(θ2−μ2))f(\theta_1,\theta_2) = \exp\left(\kappa_1\cos(\theta_1-\mu_1) + \kappa_2\cos(\theta_2-\mu_2) + \lambda\sin(\theta_1-\mu_1)\sin(\theta_2-\mu_2)\right)

​
Marshall-Olkin Bivariate Weibull

Name in SDK: marshall_olkin_weibull A shock model with independent failure sources for each variable and a shared common shock. The implemented density is the absolutely continuous part; the singular mass on the diagonal x = y is not represented. For x < y, the density is: f(x,y)=λ1(λ2+λ3)k2(xy)k−1exp⁡(−λ1xk−(λ2+λ3)yk)f(x,y) = \lambda_1(\lambda_2+\lambda_3)k^2(xy)^{k-1}\exp\left(-\lambda_1x^k-(\lambda_2+\lambda_3)y^k\right) For x > y, the density is: f(x,y)=λ2(λ1+λ3)k2(xy)k−1exp⁡(−(λ1+λ3)xk−λ2yk)f(x,y) = \lambda_2(\lambda_1+\lambda_3)k^2(xy)^{k-1}\exp\left(-(\lambda_1+\lambda_3)x^k-\lambda_2y^k\right) On x = y, the absolutely continuous density returned by this function is 0.

​
Bivariate Poisson Normal Approximation

Name in SDK: bivariate_poisson_normal_approx A continuous Gaussian approximation to a bivariate Poisson model constructed from X = Z_1 + Z_3 and Y = Z_2 + Z_3, where each Z_i is Poisson-distributed. The shared component Z_3 induces covariance. μ=[λ1+λ3, λ2+λ3]\mu = [\lambda_1+\lambda_3,\ \lambda_2+\lambda_3] Σ11=λ1+λ3,Σ22=λ2+λ3,Σ12=Σ21=λ3\Sigma_{11} = \lambda_1+\lambda_3,\quad \Sigma_{22} = \lambda_2+\lambda_3,\quad \Sigma_{12} = \Sigma_{21} = \lambda_3

​
Copula-Based Joint PDFs

Copula loading builds a joint PDF from two scipy.stats marginals and a supported copula density using Sklar’s theorem. f(x,y)=c(FX(x),FY(y))fX(x)fY(y)f(x,y) = c(F_X(x), F_Y(y)) f_X(x) f_Y(y) Use a copula name in distribution_name, provide the copula parameters in copula_params, and provide exactly two marginal names and parameter dictionaries. The supported copula densities are: cGaussian(u,v)=11−ρ2exp⁡(ρ(2xy−ρ(x2+y2))2(1−ρ2)),x=Φ−1(u), y=Φ−1(v)c_{\mathrm{Gaussian}}(u,v) = \frac{1}{\sqrt{1-\rho^2}}\exp\left(\frac{\rho(2xy-\rho(x^2+y^2))}{2(1-\rho^2)}\right),\quad x=\Phi^{-1}(u),\ y=\Phi^{-1}(v) cClayton(u,v)=(1+θ)(uv)−(θ+1)(u−θ+v−θ−1)−1/θ−2c_{\mathrm{Clayton}}(u,v) = (1+\theta)(uv)^{-(\theta+1)}(u^{-\theta}+v^{-\theta}-1)^{-1/\theta-2} cGumbel(u,v)=exp⁡(−A1/θ)(st)θ−1A1/θ−2A1/θ+θ−1uv,s=−ln⁡u, t=−ln⁡v, A=sθ+tθc_{\mathrm{Gumbel}}(u,v) = \exp(-A^{1/\theta})(st)^{\theta-1}A^{1/\theta-2}\frac{A^{1/\theta}+\theta-1}{uv},\quad s=-\ln u,\ t=-\ln v,\ A=s^\theta+t^\theta cFrank(u,v)=−θ(e−θ−1)e−θ(u+v)(e−θ−1+(e−θu−1)(e−θv−1))2c_{\mathrm{Frank}}(u,v) = \frac{-\theta(e^{-\theta}-1)e^{-\theta(u+v)}}{\left(e^{-\theta}-1+(e^{-\theta u}-1)(e^{-\theta v}-1)\right)^2}
distribution_params are only valid for direct 2D distributions. For copulas, use copula_params, marginal_distribution_names, and marginal_distribution_params.

​
Normal and Lognormal Distributions

Normal and lognormal marginals can be loaded via the copula interface using scipy.stats distribution names. Both examples below use a Gaussian copula, which preserves the familiar Gaussian dependence structure.

​
Bivariate Normal

Use "norm" as both marginal names. The loc and scale parameters correspond to the mean and standard deviation of each margin.

​
Bivariate Lognormal

Use "lognorm" as both marginal names. In scipy.stats, lognorm is parameterized by shape s (the standard deviation of the underlying normal in log-space), loc (shift, usually 0), and scale (equal to exp(mu) where mu is the mean of the underlying normal).
The lognormal interval must exclude zero. Use a small positive lower bound such as 0.01 rather than 0.0 to avoid evaluating the density at the boundary.