Package org.apache.commons.rng.sampling

Class CombinationSampler

java.lang.Object

org.apache.commons.rng.sampling.CombinationSampler

All Implemented Interfaces:

ObjectSampler<int[]>, SharedStateObjectSampler<int[]>, SharedStateSampler<SharedStateObjectSampler<int[]>>

public class CombinationSampler
extends Object
implements SharedStateObjectSampler<int[]>

Class for representing combinations of a sequence of integers.

A combination is a selection of items from a collection, such that (unlike permutations) the order of selection does not matter. This sampler can be used to generate a combination in an unspecified order and is faster than the corresponding PermutationSampler.

Note that the sample order is unspecified. For example a sample combination of 2 from 4 may return [0,1] or [1,0] as the two are equivalent, and the order of a given combination may change in subsequent samples.

The sampler can be used to generate indices to select subsets where the order of the subset is not important.

Sampling uses UniformRandomProvider.nextInt(int).

See Also:

• PermutationSampler

Field Summary

Fields

Modifier and Type	Field	Description
private final int[]	domain	Domain of the combination.
private final UniformRandomProvider	rng	RNG.
private final int	steps	The number of steps of a full shuffle to perform.
private final boolean	upper	The section to copy the domain from after a partial shuffle.

Constructor Summary

Constructors

Modifier	Constructor	Description
	CombinationSampler(UniformRandomProvider rng, int n, int k)	Creates a generator of combinations.
private	CombinationSampler(UniformRandomProvider rng, CombinationSampler source)

Method Summary

Modifier and Type	Method	Description
int[]	sample()	Return a combination of k whose entries are selected randomly, without repetition, from the integers 0, 1, ..., n-1 (inclusive).
CombinationSampler	withUniformRandomProvider(UniformRandomProvider rng)	Create a new instance of the sampler with the same underlying state using the given uniform random provider as the source of randomness.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.commons.rng.sampling.ObjectSampler

samples, samples

Field Details

domain

private final int[] domain

Domain of the combination.

steps

private final int steps

The number of steps of a full shuffle to perform.

upper

private final boolean upper

The section to copy the domain from after a partial shuffle.

rng

private final UniformRandomProvider rng

RNG.

Constructor Details

CombinationSampler

public CombinationSampler(UniformRandomProvider rng,
 int n,
 int k)

Creates a generator of combinations.

The sample() method will generate an integer array of length k whose entries are selected randomly, without repetition, from the integers 0, 1, ..., n-1 (inclusive). The returned array represents a combination of n taken k.

In contrast to a permutation, the returned array is not guaranteed to be in a random order. The sample() method returns the array in an unspecified order.

If n <= 0 or k <= 0 or k > n then no combination is required and an exception is raised.

Parameters:

rng - Generator of uniformly distributed random numbers.

n - Domain of the combination.

k - Size of the combination.

Throws:

IllegalArgumentException - if n <= 0 or k <= 0 or k > n.

CombinationSampler

private CombinationSampler(UniformRandomProvider rng,
 CombinationSampler source)

Parameters:

rng - Generator of uniformly distributed random numbers.

source - Source to copy.

Method Details

sample

public int[] sample()

Return a combination of k whose entries are selected randomly, without repetition, from the integers 0, 1, ..., n-1 (inclusive).

The order of the returned array is not guaranteed to be in a random order as the order of a combination does not matter.

Specified by:

sample in interface ObjectSampler<int[]>

Returns:

a random combination.

withUniformRandomProvider

public CombinationSampler withUniformRandomProvider(UniformRandomProvider rng)

Create a new instance of the sampler with the same underlying state using the given uniform random provider as the source of randomness.

Specified by:

withUniformRandomProvider in interface SharedStateSampler<SharedStateObjectSampler<int[]>>

Parameters:

rng - Generator of uniformly distributed random numbers.

Returns:

the sampler

Since:

1.3