Class PermutationSampler

java.lang.Object
org.apache.commons.rng.sampling.PermutationSampler
All Implemented Interfaces:
ObjectSampler<int[]>, SharedStateObjectSampler<int[]>, SharedStateSampler<SharedStateObjectSampler<int[]>>

public class PermutationSampler extends Object implements SharedStateObjectSampler<int[]>
Class for representing permutations of a sequence of integers.

Sampling uses UniformRandomProvider.nextInt(int).

This class also contains utilities for shuffling an int[] array in-place.

  • Field Details

    • domain

      private final int[] domain
      Domain of the permutation.
    • size

      private final int size
      Size of the permutation.
    • rng

      private final UniformRandomProvider rng
      RNG.
  • Constructor Details

    • PermutationSampler

      public PermutationSampler(UniformRandomProvider rng, int n, int k)
      Creates a generator of permutations.

      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 permutation of n taken k.

      Parameters:
      rng - Generator of uniformly distributed random numbers.
      n - Domain of the permutation.
      k - Size of the permutation.
      Throws:
      IllegalArgumentException - if n <= 0 or k <= 0 or k > n.
    • PermutationSampler

      private PermutationSampler(UniformRandomProvider rng, PermutationSampler source)
      Parameters:
      rng - Generator of uniformly distributed random numbers.
      source - Source to copy.
  • Method Details

    • sample

      public int[] sample()
      Description copied from interface: ObjectSampler
      Create an object sample.
      Specified by:
      sample in interface ObjectSampler<int[]>
      Returns:
      a random permutation.
      See Also:
    • withUniformRandomProvider

      public PermutationSampler 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
    • shuffle

      public static void shuffle(UniformRandomProvider rng, int[] list)
      Shuffles the entries of the given array.
      Parameters:
      rng - Random number generator.
      list - Array whose entries will be shuffled (in-place).
      See Also:
    • shuffle

      public static void shuffle(UniformRandomProvider rng, int[] list, int start, boolean towardHead)
      Shuffles the entries of the given array, using the Fisher-Yates algorithm. The start and towardHead parameters select which part of the array is randomized and which is left untouched.

      Sampling uses UniformRandomProvider.nextInt(int).

      Parameters:
      rng - Random number generator.
      list - Array whose entries will be shuffled (in-place).
      start - Index at which shuffling begins.
      towardHead - Shuffling is performed for index positions between start and either the end (if false) or the beginning (if true) of the array.
    • natural

      public static int[] natural(int n)
      Creates an array representing the natural number n.
      Parameters:
      n - Natural number.
      Returns:
      an array whose entries are the numbers 0, 1, ..., n-1. If n == 0, the returned array is empty.