Skip to content

Sampling API

Sampling configuration lives in gmm_divergence.sampling. These objects are used by Monte Carlo divergence estimators and sampled fitting objectives.

gmm_divergence.sampling

Public sampling configuration API.

Draw dataclass 

Draw(n_samples: int = 10000, rng: Generator | int | None = None)

Bases: SampleSpec, BatchSampleSpec

Draw fresh samples from the Gaussian-family distribution being estimated.

Use this when the estimator or fitting objective should own sampling. Passing a seed or generator through rng makes repeated calls reproducible.

n_samples class-attribute instance-attribute 

n_samples: int = 10000

Number of samples to draw.

rng class-attribute instance-attribute 

rng: Generator | int | None = None

Random generator or seed used when drawing samples.

sample 

sample(distribution: GaussianLike) -> FloatArray

Return the batch of samples corresponding to the given distribution.

Source code in src/gmm_divergence/_core/_sampling.py 
60
61
62
63
@override
def sample(self, distribution: GaussianLike) -> FloatArray:
    """Return the batch of samples corresponding to the given distribution."""
    return distribution.sample(n_samples=self.n_samples, rng=self.rng)

sample_batches 

sample_batches(distributions: Sequence[GaussianLike]) -> FloatArray

Return one independently drawn sample batch per distribution.

Source code in src/gmm_divergence/_core/_sampling.py 
65
66
67
68
69
70
71
72
@override
def sample_batches(self, distributions: Sequence[GaussianLike]) -> FloatArray:
    """Return one independently drawn sample batch per distribution."""
    rng = np.random.default_rng(self.rng)
    return _sample_each_distribution(
        distributions,
        lambda distribution: distribution.sample(n_samples=self.n_samples, rng=rng),
    )

Stratified dataclass 

Stratified(n_samples: int = 10000, rng: Generator | int | None = None)

Bases: SampleSpec, BatchSampleSpec

Draw stratified samples from a Gaussian-family distribution.

For a Gaussian mixture, component sample counts are allocated deterministically from the mixture weights, then samples are drawn from each component. Every positive-weight component receives at least one sample, so n_samples must be at least the number of positive-weight components. A single Gaussian is treated as a one-component mixture.

n_samples class-attribute instance-attribute 

n_samples: int = 10000

Total number of samples to draw.

rng class-attribute instance-attribute 

rng: Generator | int | None = None

Random generator or seed used when drawing samples.

sample 

sample(distribution: GaussianLike) -> FloatArray

Return the batch of samples corresponding to the given distribution.

Source code in src/gmm_divergence/_core/_sampling.py 
94
95
96
97
@override
def sample(self, distribution: GaussianLike) -> FloatArray:
    """Return the batch of samples corresponding to the given distribution."""
    return stratified_mixture_samples(distribution, self).samples

sample_batches 

sample_batches(distributions: Sequence[GaussianLike]) -> FloatArray

Return one stratified sample batch per distribution.

Source code in src/gmm_divergence/_core/_sampling.py 
 99
100
101
102
103
104
105
@override
def sample_batches(self, distributions: Sequence[GaussianLike]) -> FloatArray:
    """Return one stratified sample batch per distribution."""
    return _sample_each_distribution(
        distributions,
        lambda distribution: stratified_mixture_samples(distribution, self).samples,
    )

Samples dataclass 

Samples(samples: ArrayLike)

Bases: SampleSpec

Use precomputed samples from a single Gaussian-family reference distribution.

samples instance-attribute 

samples: ArrayLike

Sample array with shape (n_samples, n_features).

sample 

sample(distribution: GaussianLike) -> FloatArray

Return the batch of samples corresponding to the given distribution.

Source code in src/gmm_divergence/_core/_sampling.py 
115
116
117
118
@override
def sample(self, distribution: GaussianLike) -> FloatArray:
    """Return the batch of samples corresponding to the given distribution."""
    return as_points(self.samples, n_features=distribution.dim, name="samples")

SampleBatches dataclass 

SampleBatches(samples: ArrayLike)

Bases: BatchSampleSpec

Use precomputed sample batches for a sequence of candidate distributions.

samples instance-attribute 

samples: ArrayLike

Sample array with shape (n_distributions, n_samples, n_features).

sample_batches 

sample_batches(distributions: Sequence[GaussianLike]) -> FloatArray

Return precomputed sample batches for the given distributions.

Source code in src/gmm_divergence/_core/_sampling.py 
128
129
130
131
132
133
134
135
136
137
@override
def sample_batches(self, distributions: Sequence[GaussianLike]) -> FloatArray:
    """Return precomputed sample batches for the given distributions."""
    expected_dim = distributions[0].dim if distributions else 0
    return as_sample_batches(
        self.samples,
        n_distributions=len(distributions),
        n_features=expected_dim,
        name="samples",
    )