Add mixed distribution support to TrueMeasure

[Laasya-73]

Summary

This PR adds support for finite mixed distributions through a new Mixture TrueMeasure.

Given component distributions with densities

$$\rho_0(x), \rho_1(x), \ldots, \rho_{s-1}(x)$$

and probabilities

$$p_0, p_1, \ldots, p_{s-1}, \qquad p_j > 0, \qquad \sum_{j=0}^{s-1} p_j = 1,$$

the resulting mixed distribution has density

$$\rho(x) = \sum_{j=0}^{s-1} p_j \rho_j(x).$$

To sample from the mixture, Mixture uses one additional uniform coordinate. For a component dimension d, the outer sampler therefore has dimension d + 1.

For

$$u = (u_0, u_1, \ldots, u_d) \in [0,1]^{d+1},$$

the first coordinate $u_0$ selects a component according to the cumulative probabilities, and the remaining coordinates $(u_1, \ldots, u_d)$ are passed through the selected component's existing TrueMeasure transform. The resulting sample is in dimension d.

Implementation

• Adds a general Mixture TrueMeasure that can combine different compatible TrueMeasure components.
• Requires all components to have the same output dimension.
• Validates component types, probabilities, and the required d + 1 sampler dimension.
• Uses each selected component's recursive transform, so composed TrueMeasures are preserved.
• Computes mixture weights as the probability-weighted sum of the component weights.
• Supports replicated samples and same-dimension spawning.
• Exposes Mixture through the public qmcpy API.

A new demo notebook shows the selection mechanism as well as mixtures involving different component types, including Gaussian, zero-inflated, bounded, heavy-tailed, composed, and multidimensional examples.

Tests

Added focused tests for component selection, cumulative-probability boundaries, validation, mixture weights, composed transforms, spawning, and replicated samples.

[fjhickernell]

Thanks for doing this Laasya.

We talked and I requested an example showing the advantage of mixture sampling over non-mixture sampling. Let me know when you have added that.

[Laasya-73]

Thanks for doing this Laasya.

We talked and I requested an example showing the advantage of mixture sampling over non-mixture sampling. Let me know when you have added that.

Sure!!

[sou-cheng-choi]

@Laasya-73

1. Remove unnecessary line breaks and add "Open in Colab" badge to the demo by running terminal command, make format. The badge will work once this PR is merged into develop branch.

2. Do you plan to add mean, variance, standard deviation, and covariance to Mixture in this PR?

3. Why is weight value being 1 outside bounded support at 1.5 in the following example? Also, at any point in the bounded support, shouldn't the weight just be 0.5?

mb = Mixture(DigitalNetB2(2), [Uniform(DigitalNetB2(1), 0, 1), Uniform(DigitalNetB2(1), 2, 3)], [0.5, 0.5])
w = mb._weight(np.array([[0.5], [2.5], [1.5]]))   # currently prints [1, 1, 1]

4. Should we use right instead of left for line 125 (self._cumulative_probabilities, flat_x[:, 0], side="left") in mixture.py?

5. In abstract_true_measure.py:84, measure.d == measure.discrete_distrib.d by construction. However, line 75 of mixture essentially validates measure.discrete_distrib.d == measure.d + 1. The mismatch of dimensions result in exception as in the following example:

m = Mixture(DigitalNetB2(2, seed=7), [Gaussian(DigitalNetB2(1), mean=-2, covariance=1), Gaussian(DigitalNetB2(1), mean=2, covariance=1)], [0.3, 0.7])
g = CustomFun(m, lambda t: t[..., 0] ** 2)
CubQMCNetG(g).integrate() 
# ValueError: all the input array dimensions except for the concatenation axis must match exactly, but along dimension 1, the array at index 0 has size 1 and the array at index 1 has size 2

[Laasya-73]

@sou-cheng-choi

Thank you. I’ll run make format for the demo formatting and Colab badge. And yes, I’m planning to add mean, variance, standard_deviation, and covariance support to Mixture.