Module org.cicirello.jpt
Package org.cicirello.sequences

Class SequenceSampler

java.lang.Object
org.cicirello.sequences.SequenceSampler
public final class SequenceSampler extends Object
SequenceSampler is a class of utility methods related to efficiently generating random samples of array elements, without replacement.

  • Method Summary

    Modifier and Type
    Method
    Description
    static byte[]
    sample(byte[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static byte[]
    sample(byte[] source, int k, byte[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static char[]
    sample(char[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static char[]
    sample(char[] source, int k, char[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static double[]
    sample(double[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static double[]
    sample(double[] source, int k, double[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static float[]
    sample(float[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static float[]
    sample(float[] source, int k, float[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static int[]
    sample(int[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static int[]
    sample(int[] source, int k, int[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static long[]
    sample(long[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static long[]
    sample(long[] source, int k, long[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static short[]
    sample(short[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static short[]
    sample(short[] source, int k, short[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static char[]
    sample(String source, double p)
    Generates a random sample, without replacement, from a given String with a specified probability of a character's inclusion in the sample.
    static char[]
    sample(String source, int k, char[] target)
    Generates a random sample of k chars, without replacement, from a given source String.
    static <T> T[]
    sample(T[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static <T> T[]
    sample(T[] source, int k, T[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static byte[]
    sampleInsertion(byte[] source, int k, byte[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceInsertionSampler class.
    static char[]
    sampleInsertion(char[] source, int k, char[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceInsertionSampler class.
    static double[]
    sampleInsertion(double[] source, int k, double[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceInsertionSampler class.
    static float[]
    sampleInsertion(float[] source, int k, float[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceInsertionSampler class.
    static int[]
    sampleInsertion(int[] source, int k, int[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceInsertionSampler class.
    static long[]
    sampleInsertion(long[] source, int k, long[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceInsertionSampler class.
    static short[]
    sampleInsertion(short[] source, int k, short[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceInsertionSampler class.
    static char[]
    sampleInsertion(String source, int k, char[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceInsertionSampler class.
    static <T> T[]
    sampleInsertion(T[] source, int k, T[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceInsertionSampler class.
    static byte[]
    samplePool(byte[] source, int k, byte[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequencePoolSampler class.
    static char[]
    samplePool(char[] source, int k, char[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequencePoolSampler class.
    static double[]
    samplePool(double[] source, int k, double[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequencePoolSampler class.
    static float[]
    samplePool(float[] source, int k, float[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequencePoolSampler class.
    static int[]
    samplePool(int[] source, int k, int[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequencePoolSampler class.
    static long[]
    samplePool(long[] source, int k, long[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequencePoolSampler class.
    static short[]
    samplePool(short[] source, int k, short[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequencePoolSampler class.
    static char[]
    samplePool(String source, int k, char[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequencePoolSampler class.
    static <T> T[]
    samplePool(T[] source, int k, T[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequencePoolSampler class.
    static byte[]
    sampleReservoir(byte[] source, int k, byte[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceReservoirSampler class.
    static char[]
    sampleReservoir(char[] source, int k, char[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceReservoirSampler class.
    static double[]
    sampleReservoir(double[] source, int k, double[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceReservoirSampler class.
    static float[]
    sampleReservoir(float[] source, int k, float[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceReservoirSampler class.
    static int[]
    sampleReservoir(int[] source, int k, int[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceReservoirSampler class.
    static long[]
    sampleReservoir(long[] source, int k, long[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceReservoirSampler class.
    static short[]
    sampleReservoir(short[] source, int k, short[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceReservoirSampler class.
    static char[]
    sampleReservoir(String source, int k, char[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceReservoirSampler class.
    static <T> T[]
    sampleReservoir(T[] source, int k, T[] target)
    Deprecated.
    This method is deprecated, and replaced by the SequenceReservoirSampler class.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • sample

      public static byte[] sample(byte[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static char[] sample(char[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static double[] sample(double[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static float[] sample(float[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static int[] sample(int[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static long[] sample(long[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static short[] sample(short[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static char[] sample(String source, double p)
      Generates a random sample, without replacement, from a given String with a specified probability of a character's inclusion in the sample.
      Parameters:
      source - The String from which to sample.
      p - The probability that a character is included in the sample. The expected sample size is source.length() * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static <T> T[] sample(T[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Type Parameters:
      T - The type of array elements.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static int[] sample(int[] source, int k, int[] target)
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static long[] sample(long[] source, int k, long[] target)
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static short[] sample(short[] source, int k, short[] target)
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static byte[] sample(byte[] source, int k, byte[] target)
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static char[] sample(char[] source, int k, char[] target)
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static char[] sample(String source, int k, char[] target)
      Generates a random sample of k chars, without replacement, from a given source String. All n choose k combinations are equally likely, where n is the length of the source String.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length()).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length()
      NegativeArraySizeException - if k < 0

    • sample

      public static double[] sample(double[] source, int k, double[] target)
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static float[] sample(float[] source, int k, float[] target)
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static <T> T[] sample(T[] source, int k, T[] target)
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Type Parameters:
      T - The type of array elements.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleReservoir

      @Deprecated public static int[] sampleReservoir(int[] source, int k, int[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceReservoirSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      Uses the reservoir sampling algorithm (Algorithm R) from J. Vitter's 1985 article "Random Sampling with a Reservoir" from ACM Transactions on Mathematical Software. The runtime is O(n) and it generates O(n-k) random numbers. Thus, it is an especially good choice as k approaches n. Only constant extra space required.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleReservoir

      @Deprecated public static long[] sampleReservoir(long[] source, int k, long[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceReservoirSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      Uses the reservoir sampling algorithm (Algorithm R) from J. Vitter's 1985 article "Random Sampling with a Reservoir" from ACM Transactions on Mathematical Software. The runtime is O(n) and it generates O(n-k) random numbers. Thus, it is an especially good choice as k approaches n. Only constant extra space required.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleReservoir

      @Deprecated public static short[] sampleReservoir(short[] source, int k, short[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceReservoirSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      Uses the reservoir sampling algorithm (Algorithm R) from J. Vitter's 1985 article "Random Sampling with a Reservoir" from ACM Transactions on Mathematical Software. The runtime is O(n) and it generates O(n-k) random numbers. Thus, it is an especially good choice as k approaches n. Only constant extra space required.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleReservoir

      @Deprecated public static byte[] sampleReservoir(byte[] source, int k, byte[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceReservoirSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      Uses the reservoir sampling algorithm (Algorithm R) from J. Vitter's 1985 article "Random Sampling with a Reservoir" from ACM Transactions on Mathematical Software. The runtime is O(n) and it generates O(n-k) random numbers. Thus, it is an especially good choice as k approaches n. Only constant extra space required.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleReservoir

      @Deprecated public static char[] sampleReservoir(char[] source, int k, char[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceReservoirSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      Uses the reservoir sampling algorithm (Algorithm R) from J. Vitter's 1985 article "Random Sampling with a Reservoir" from ACM Transactions on Mathematical Software. The runtime is O(n) and it generates O(n-k) random numbers. Thus, it is an especially good choice as k approaches n. Only constant extra space required.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleReservoir

      @Deprecated public static char[] sampleReservoir(String source, int k, char[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceReservoirSampler class.
      Generates a random sample of k chars, without replacement, from a given source String. All n choose k combinations are equally likely, where n is the length of the source String.

      Uses the reservoir sampling algorithm (Algorithm R) from J. Vitter's 1985 article "Random Sampling with a Reservoir" from ACM Transactions on Mathematical Software. The runtime is O(n) and it generates O(n-k) random numbers. Thus, it is an especially good choice as k approaches n. Only constant extra space required.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length()).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length()
      NegativeArraySizeException - if k < 0

    • sampleReservoir

      @Deprecated public static double[] sampleReservoir(double[] source, int k, double[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceReservoirSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      Uses the reservoir sampling algorithm (Algorithm R) from J. Vitter's 1985 article "Random Sampling with a Reservoir" from ACM Transactions on Mathematical Software. The runtime is O(n) and it generates O(n-k) random numbers. Thus, it is an especially good choice as k approaches n. Only constant extra space required.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleReservoir

      @Deprecated public static float[] sampleReservoir(float[] source, int k, float[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceReservoirSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      Uses the reservoir sampling algorithm (Algorithm R) from J. Vitter's 1985 article "Random Sampling with a Reservoir" from ACM Transactions on Mathematical Software. The runtime is O(n) and it generates O(n-k) random numbers. Thus, it is an especially good choice as k approaches n. Only constant extra space required.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleReservoir

      @Deprecated public static <T> T[] sampleReservoir(T[] source, int k, T[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceReservoirSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      Uses the reservoir sampling algorithm (Algorithm R) from J. Vitter's 1985 article "Random Sampling with a Reservoir" from ACM Transactions on Mathematical Software. The runtime is O(n) and it generates O(n-k) random numbers. Thus, it is an especially good choice as k approaches n. Only constant extra space required.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Type Parameters:
      T - The type of array elements.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • samplePool

      @Deprecated public static int[] samplePool(int[] source, int k, int[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequencePoolSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal, 25(1):45-47, 1982.

      The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than sampleReservoir when k < n-k. However, this uses O(n) extra space, whereas the reservoir algorithm uses no extra space.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • samplePool

      @Deprecated public static long[] samplePool(long[] source, int k, long[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequencePoolSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal, 25(1):45-47, 1982.

      The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than sampleReservoir when k < n-k. However, this uses O(n) extra space, whereas the reservoir algorithm uses no extra space.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • samplePool

      @Deprecated public static short[] samplePool(short[] source, int k, short[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequencePoolSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal, 25(1):45-47, 1982.

      The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than sampleReservoir when k < n-k. However, this uses O(n) extra space, whereas the reservoir algorithm uses no extra space.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • samplePool

      @Deprecated public static byte[] samplePool(byte[] source, int k, byte[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequencePoolSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal, 25(1):45-47, 1982.

      The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than sampleReservoir when k < n-k. However, this uses O(n) extra space, whereas the reservoir algorithm uses no extra space.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • samplePool

      @Deprecated public static char[] samplePool(char[] source, int k, char[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequencePoolSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal, 25(1):45-47, 1982.

      The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than sampleReservoir when k < n-k. However, this uses O(n) extra space, whereas the reservoir algorithm uses no extra space.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • samplePool

      @Deprecated public static char[] samplePool(String source, int k, char[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequencePoolSampler class.
      Generates a random sample of k chars, without replacement, from a given source String. All n choose k combinations are equally likely, where n is the length of the source String.

      This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal, 25(1):45-47, 1982.

      The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than sampleReservoir when k < n-k. However, this uses O(n) extra space, whereas the reservoir algorithm uses no extra space.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source to sample.
      k - The number of random samples (must be no greater than source.length()).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length()
      NegativeArraySizeException - if k < 0

    • samplePool

      @Deprecated public static double[] samplePool(double[] source, int k, double[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequencePoolSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal, 25(1):45-47, 1982.

      The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than sampleReservoir when k < n-k. However, this uses O(n) extra space, whereas the reservoir algorithm uses no extra space.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • samplePool

      @Deprecated public static float[] samplePool(float[] source, int k, float[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequencePoolSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal, 25(1):45-47, 1982.

      The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than sampleReservoir when k < n-k. However, this uses O(n) extra space, whereas the reservoir algorithm uses no extra space.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • samplePool

      @Deprecated public static <T> T[] samplePool(T[] source, int k, T[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequencePoolSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal, 25(1):45-47, 1982.

      The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than sampleReservoir when k < n-k. However, this uses O(n) extra space, whereas the reservoir algorithm uses no extra space.

      This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying source of randomness.

      Type Parameters:
      T - The type of array elements.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleInsertion

      @Deprecated public static int[] sampleInsertion(int[] source, int k, int[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceInsertionSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the insertion sampling algorithm described in:

      Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(k2) and it generates O(k) random numbers. Thus, it is a better choice than both sampleReservoir and samplePool when k2 < n. Just like sampleReservoir, the sampleInsertion method only requires O(1) extra space, while samplePool requires O(n) extra space.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleInsertion

      @Deprecated public static long[] sampleInsertion(long[] source, int k, long[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceInsertionSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the insertion sampling algorithm described in:

      Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(k2) and it generates O(k) random numbers. Thus, it is a better choice than both sampleReservoir and samplePool when k2 < n. Just like sampleReservoir, the sampleInsertion method only requires O(1) extra space, while samplePool requires O(n) extra space.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleInsertion

      @Deprecated public static short[] sampleInsertion(short[] source, int k, short[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceInsertionSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the insertion sampling algorithm described in:

      Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(k2) and it generates O(k) random numbers. Thus, it is a better choice than both sampleReservoir and samplePool when k2 < n. Just like sampleReservoir, the sampleInsertion method only requires O(1) extra space, while samplePool requires O(n) extra space.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleInsertion

      @Deprecated public static byte[] sampleInsertion(byte[] source, int k, byte[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceInsertionSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the insertion sampling algorithm described in:

      Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(k2) and it generates O(k) random numbers. Thus, it is a better choice than both sampleReservoir and samplePool when k2 < n. Just like sampleReservoir, the sampleInsertion method only requires O(1) extra space, while samplePool requires O(n) extra space.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleInsertion

      @Deprecated public static char[] sampleInsertion(char[] source, int k, char[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceInsertionSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the insertion sampling algorithm described in:

      Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(k2) and it generates O(k) random numbers. Thus, it is a better choice than both sampleReservoir and samplePool when k2 < n. Just like sampleReservoir, the sampleInsertion method only requires O(1) extra space, while samplePool requires O(n) extra space.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleInsertion

      @Deprecated public static char[] sampleInsertion(String source, int k, char[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceInsertionSampler class.
      Generates a random sample of k chars, without replacement, from a given source String. All n choose k combinations are equally likely, where n is the length of the source String.

      This implements the insertion sampling algorithm described in:

      Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(k2) and it generates O(k) random numbers. Thus, it is a better choice than both sampleReservoir and samplePool when k2 < n. Just like sampleReservoir, the sampleInsertion method only requires O(1) extra space, while samplePool requires O(n) extra space.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source to sample.
      k - The number of random samples (must be no greater than source.length()).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length()
      NegativeArraySizeException - if k < 0

    • sampleInsertion

      @Deprecated public static double[] sampleInsertion(double[] source, int k, double[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceInsertionSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the insertion sampling algorithm described in:

      Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(k2) and it generates O(k) random numbers. Thus, it is a better choice than both sampleReservoir and samplePool when k2 < n. Just like sampleReservoir, the sampleInsertion method only requires O(1) extra space, while samplePool requires O(n) extra space.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleInsertion

      @Deprecated public static float[] sampleInsertion(float[] source, int k, float[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceInsertionSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the insertion sampling algorithm described in:

      Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(k2) and it generates O(k) random numbers. Thus, it is a better choice than both sampleReservoir and samplePool when k2 < n. Just like sampleReservoir, the sampleInsertion method only requires O(1) extra space, while samplePool requires O(n) extra space.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sampleInsertion

      @Deprecated public static <T> T[] sampleInsertion(T[] source, int k, T[] target)
      Deprecated.
      This method is deprecated, and replaced by the SequenceInsertionSampler class.
      Generates a random sample of k elements, without replacement, from a given source array. All n choose k combinations are equally likely, where n is the length of the source array.

      This implements the insertion sampling algorithm described in:

      Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(k2) and it generates O(k) random numbers. Thus, it is a better choice than both sampleReservoir and samplePool when k2 < n. Just like sampleReservoir, the sampleInsertion method only requires O(1) extra space, while samplePool requires O(n) extra space.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Type Parameters:
      T - The type of array elements.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0