Module io.jenetics.base
Package io.jenetics.engine

Class Codecs

java.lang.Object
io.jenetics.engine.Codecs
public final class Codecs extends Object
This class contains factory methods for creating common problem encodings.
Since:
3.2
Version:
5.2

  • Method Details

    • ofScalar

      public static InvertibleCodec<Integer,IntegerGene> ofScalar(IntRange domain)
      Return a scalar InvertibleCodec for the given range.
      Parameters:
      domain - the domain of the returned Codec
      Returns:
      a new scalar Codec with the given domain.
      Throws:
      NullPointerException - if the given domain is null

    • ofScalar

      public static InvertibleCodec<Long,LongGene> ofScalar(LongRange domain)
      Return a scalar InvertibleCodec for the given range.
      Parameters:
      domain - the domain of the returned Codec
      Returns:
      a new scalar Codec with the given domain.
      Throws:
      NullPointerException - if the given domain is null

    • ofScalar

      public static InvertibleCodec<Double,DoubleGene> ofScalar(DoubleRange domain)
      Return a scalar InvertibleCodec for the given range.
      Parameters:
      domain - the domain of the returned Codec
      Returns:
      a new scalar Codec with the given domain.
      Throws:
      NullPointerException - if the given domain is null

    • ofScalar

      public static <A> Codec<A,AnyGene<A>> ofScalar(Supplier<? extends A> supplier, Predicate<? super A> validator)
      Return a scala Codec with the given allele Supplier and allele validator. The supplier is responsible for creating new random alleles, and the validator can verify it.

      The following example shows a codec which creates and verifies BigInteger objects. 

      final Codec<BigInteger, AnyGene<BigInteger>> codec = Codecs.of(
    // Create new random 'BigInteger' object.
    () -> {
        final byte[] data = new byte[100];
        RandomRegistry.getRandom().nextBytes(data);
        return new BigInteger(data);
    },
    // Verify that bit 7 is set. (For illustration purpose.)
    bi -> bi.testBit(7)
);
      Type Parameters:
      A - the allele type
      Parameters:
      supplier - the allele-supplier which is used for creating new, random alleles
      validator - the validator used for validating the created gene. This predicate is used in the AnyGene.isValid() method.
      Returns:
      a new Codec with the given parameters
      Throws:
      NullPointerException - if one of the parameters is null
      See Also:

    • ofScalar

      public static <A> Codec<A,AnyGene<A>> ofScalar(Supplier<? extends A> supplier)
      Return a scala Codec with the given allele Supplier and allele validator. The supplier is responsible for creating new random alleles.
      Type Parameters:
      A - the allele type
      Parameters:
      supplier - the allele-supplier which is used for creating new, random alleles
      Returns:
      a new Codec with the given parameters
      Throws:
      NullPointerException - if the parameter is null
      See Also:

    • ofVector

      public static InvertibleCodec<int[],IntegerGene> ofVector(IntRange domain, int length)
      Return a vector InvertibleCodec for the given range. All vector values are restricted by the same domain.
      Parameters:
      domain - the domain of the vector values
      length - the vector length
      Returns:
      a new vector Codec
      Throws:
      NullPointerException - if the given domain is null
      IllegalArgumentException - if the length is smaller than one.

    • ofVector

      public static InvertibleCodec<int[],IntegerGene> ofVector(IntRange domain, IntRange length)
      Return a vector InvertibleCodec for the given range. All vector values are restricted by the same domain.
      Parameters:
      domain - the domain of the vector values
      length - the vector length range
      Returns:
      a new vector Codec
      Throws:
      NullPointerException - if the given domain is null
      IllegalArgumentException - if the length is smaller than one.
      Since:
      7.0

    • ofVector

      public static InvertibleCodec<long[],LongGene> ofVector(LongRange domain, int length)
      Return a vector InvertibleCodec for the given range. All vector values are restricted by the same domain.
      Parameters:
      domain - the domain of the vector values
      length - the vector length
      Returns:
      a new vector Codec
      Throws:
      NullPointerException - if the given domain is null
      IllegalArgumentException - if the length is smaller than one.

    • ofVector

      public static InvertibleCodec<long[],LongGene> ofVector(LongRange domain, IntRange length)
      Return a vector InvertibleCodec for the given range. All vector values are restricted by the same domain.
      Parameters:
      domain - the domain of the vector values
      length - the vector length range
      Returns:
      a new vector Codec
      Throws:
      NullPointerException - if the given domain is null
      IllegalArgumentException - if the length is smaller than one.
      Since:
      7.0

    • ofVector

      public static InvertibleCodec<double[],DoubleGene> ofVector(DoubleRange domain, int length)
      Return a vector InvertibleCodec for the given range. All vector values are restricted by the same domain. Use the following code if you want to create int[] arrays and still using DoubleGene. The int[] array elements are created by casting the double values to int values. 
      final Codec<int[], DoubleGene> codec = Codecs
    .ofVector(DoubleRange.of(0, 100), 100)
    .map(ArrayConversions::doubleToIntArray);
      If you want round the double values, you can use the following code. 
      final Codec<int[], DoubleGene> codec = Codecs
    .ofVector(DoubleRange.of(0, 100), 100)
    .map(ArrayConversions.doubleToIntArray(v -> (int)Math.round(v)));
      Parameters:
      domain - the domain of the vector values
      length - the vector length
      Returns:
      a new vector Codec
      Throws:
      NullPointerException - if the given domain is null
      IllegalArgumentException - if the length is smaller than one.

    • ofVector

      public static InvertibleCodec<double[],DoubleGene> ofVector(DoubleRange domain, IntRange length)
      Return a vector InvertibleCodec for the given range. All vector values are restricted by the same domain.
      Parameters:
      domain - the domain of the vector values
      length - the vector length range
      Returns:
      a new vector Codec
      Throws:
      NullPointerException - if the given domain is null
      IllegalArgumentException - if the length is smaller than one.
      Since:
      7.0

    • ofVector

      public static InvertibleCodec<int[],IntegerGene> ofVector(IntRange... domains)
      Create a vector InvertibleCodec for the given ranges. Each vector element might have a different domain. The vector length is equal to the number of domains.
      Parameters:
      domains - the domain ranges
      Returns:
      a new vector Codec
      Throws:
      NullPointerException - if one of the arguments is null
      IllegalArgumentException - if the domains array is empty

    • ofVector

      public static InvertibleCodec<long[],LongGene> ofVector(LongRange... domains)
      Create a vector InvertibleCodec for the given ranges. Each vector element might have a different domain. The vector length is equal to the number of domains.
      Parameters:
      domains - the domain ranges
      Returns:
      a new vector Codec
      Throws:
      NullPointerException - if one of the arguments is null
      IllegalArgumentException - if the domains array is empty

    • ofVector

      public static InvertibleCodec<double[],DoubleGene> ofVector(DoubleRange... domains)
      Create a vector InvertibleCodec for the given ranges. Each vector element might have a different domain. The vector length is equal to the number of domains.
      Parameters:
      domains - the domain ranges
      Returns:
      a new vector Codec
      Throws:
      NullPointerException - if one of the arguments is null
      IllegalArgumentException - if the domains array is empty

    • ofVector

      public static <A> Codec<ISeq<A>,AnyGene<A>> ofVector(Supplier<? extends A> supplier, Predicate<? super A> alleleValidator, Predicate<? super ISeq<A>> alleleSeqValidator, int length)
      Return a scala Codec with the given allele Supplier, allele validator and Chromosome length. The supplier is responsible for creating new random alleles, and the validator can verify it.

      The following example shows a codec which creates and verifies BigInteger object arrays. 

      final Codec<BigInteger[], AnyGene<BigInteger>> codec = Codecs.of(
    // Create new random 'BigInteger' object.
    () -> {
        final byte[] data = new byte[100];
        RandomRegistry.getRandom().nextBytes(data);
        return new BigInteger(data);
    },
    // Verify that bit 7 is set. (For illustration purpose.)
    bi -> bi.testBit(7),
    // The 'Chromosome' length.
    123
);
      Type Parameters:
      A - the allele type
      Parameters:
      supplier - the allele-supplier which is used for creating new, random alleles
      alleleValidator - the validator used for validating the created gene. This predicate is used in the AnyGene.isValid() method.
      alleleSeqValidator - the validator used for validating the created chromosome. This predicate is used in the AnyChromosome.isValid() method.
      length - the vector length
      Returns:
      a new Codec with the given parameters
      Throws:
      NullPointerException - if one of the parameters is null
      IllegalArgumentException - if the length of the vector is smaller than one.
      See Also:

    • ofVector

      public static <A> Codec<ISeq<A>,AnyGene<A>> ofVector(Supplier<? extends A> supplier, Predicate<? super A> validator, int length)
      Return a scala Codec with the given allele Supplier, allele validator and Chromosome length. The supplier is responsible for creating new random alleles, and the validator can verify it.
      Type Parameters:
      A - the allele type
      Parameters:
      supplier - the allele-supplier which is used for creating new, random alleles
      validator - the validator used for validating the created gene. This predicate is used in the AnyGene.isValid() method.
      length - the vector length
      Returns:
      a new Codec with the given parameters
      Throws:
      NullPointerException - if one of the parameters is null
      IllegalArgumentException - if the length of the vector is smaller than one.

    • ofVector

      public static <A> Codec<ISeq<A>,AnyGene<A>> ofVector(Supplier<? extends A> supplier, int length)
      Return a scala Codec with the given allele Supplier and Chromosome length. The supplier is responsible for creating new random alleles.
      Type Parameters:
      A - the allele type
      Parameters:
      supplier - the allele-supplier which is used for creating new, random alleles
      length - the vector length
      Returns:
      a new Codec with the given parameters
      Throws:
      NullPointerException - if one of the parameters is null
      IllegalArgumentException - if the length of the vector is smaller than one.

    • ofVector

      public static <S, G extends Gene<?, G>> Codec<ISeq<S>,G> ofVector(Codec<? extends S,G> codec, int length)
      Create a vector (ISeq) of domain objects, which are created with the given codec. 
      // Domain model of solution space.
record Path(WayPoint[] stops) {}

// Codec fora single GPS point (latitude, longitude).
final Codec<WayPoint, DoubleGene> wpc = Codec.combine(
    Codecs.ofScalar(DoubleRange.of(30, 50)), // latitude
    Codecs.ofScalar(DoubleRange.of(69, 72)), // longitude
    WayPoint::of
);

// Codec for the path object.
final Codec<Path, DoubleGene> pc = Codecs.ofVector(wpc, 10)
    .map(points -> points.toArray(WayPoint[]::new))
    .map(Path::new);

final Path path = pc.decode(pc.encoding().newInstance());
      Type Parameters:
      S - the type of the domain object
      G - the encoding gene type
      Parameters:
      codec - the codec for the domain object
      length - the length of the vector.
      Returns:
      a codec for a sequence of domain objects
      Throws:
      NullPointerException - if the given codec is null
      IllegalArgumentException - if the length is smaller than 1
      Since:
      8.1

    • ofPermutation

      public static InvertibleCodec<int[],EnumGene<Integer>> ofPermutation(int length)
      Create a permutation InvertibleCodec of integer in the range [0, length).
      Parameters:
      length - the number of permutation elements
      Returns:
      a permutation Codec of integers
      Throws:
      IllegalArgumentException - if the length is smaller than one.

    • ofPermutation

      public static <T> InvertibleCodec<ISeq<T>,EnumGene<T>> ofPermutation(ISeq<? extends T> alleles)
      Create a permutation InvertibleCodec with the given alleles.
      Type Parameters:
      T - the allele type
      Parameters:
      alleles - the alleles of the permutation
      Returns:
      a new permutation Codec
      Throws:
      IllegalArgumentException - if the given allele array is empty
      NullPointerException - if one of the alleles is null

    • ofMatrix

      public static InvertibleCodec<int[][],IntegerGene> ofMatrix(IntRange domain, int rows, int cols)
      Return a 2-dimensional matrix InvertibleCodec for the given range. All matrix values are restricted by the same domain. The dimension of the returned matrix is int[rows][cols].
      Parameters:
      domain - the domain of the matrix values
      rows - the number of rows of the matrix
      cols - the number of columns of the matrix
      Returns:
      a new matrix Codec
      Throws:
      NullPointerException - if the given domain is null
      IllegalArgumentException - if the rows or cols are smaller than one.
      Since:
      4.4

    • ofMatrix

      public static InvertibleCodec<long[][],LongGene> ofMatrix(LongRange domain, int rows, int cols)
      Return a 2-dimensional matrix InvertibleCodec for the given range. All matrix values are restricted by the same domain. The dimension of the returned matrix is long[rows][cols].
      Parameters:
      domain - the domain of the matrix values
      rows - the number of rows of the matrix
      cols - the number of columns of the matrix
      Returns:
      a new matrix Codec
      Throws:
      NullPointerException - if the given domain is null
      IllegalArgumentException - if the rows or cols are smaller than one.
      Since:
      4.4

    • ofMatrix

      public static InvertibleCodec<double[][],DoubleGene> ofMatrix(DoubleRange domain, int rows, int cols)
      Return a 2-dimensional matrix InvertibleCodec for the given range. All matrix values are restricted by the same domain. The dimension of the returned matrix is double[rows][cols].
      Parameters:
      domain - the domain of the matrix values
      rows - the number of rows of the matrix
      cols - the number of columns of the matrix
      Returns:
      a new matrix Codec
      Throws:
      NullPointerException - if the given domain is null
      IllegalArgumentException - if the rows or cols are smaller than one.
      Since:
      4.4

    • ofMapping

      public static <A, B, M extends Map<A, B>> InvertibleCodec<M,EnumGene<Integer>> ofMapping(ISeq<? extends A> source, ISeq<? extends B> target, Supplier<M> mapSupplier)
      Create a codec, which creates a mapping from the elements given in the source sequence to the elements given in the target sequence. The returned mapping can be seen as a function which maps every element of the target set to an element of the source set. 
      final ISeq<Integer> numbers = ISeq.of(1, 2, 3, 4, 5);
final ISeq<String> strings = ISeq.of("1", "2", "3");

final Codec<Map<Integer, String>, EnumGene<Integer>> codec =
    Codecs.ofMapping(numbers, strings, HashMap::new);
      If source.size() > target.size(), the created mapping is surjective, if source.size() < target.size(), the mapping is injective and if both sets have the same size, the returned mapping is bijective.
      Type Parameters:
      A - the type of the source elements
      B - the type of the target elements
      M - the type of the encoded Map
      Parameters:
      source - the source elements. Will be the keys of the encoded Map.
      target - the target elements. Will be the values of the encoded Map.
      mapSupplier - a function which returns a new, empty Map into which the mapping will be inserted
      Returns:
      a new mapping codec
      Throws:
      IllegalArgumentException - if the target sequences are empty
      NullPointerException - if one of the arguments is null
      Since:
      4.3

    • ofMapping

      public static <A, B> InvertibleCodec<Map<A,B>,EnumGene<Integer>> ofMapping(ISeq<? extends A> source, ISeq<? extends B> target)
      Create a codec, which creates a mapping from the elements given in the source sequence to the elements given in the target sequence. The returned mapping can be seen as a function which maps every element of the target set to an element of the source set. 
      final ISeq<Integer> numbers = ISeq.of(1, 2, 3, 4, 5);
final ISeq<String> strings = ISeq.of("1", "2", "3");

final Codec<Map<Integer, String>, EnumGene<Integer>> codec =
    Codecs.ofMapping(numbers, strings);
      If source.size() > target.size(), the created mapping is surjective, if source.size() < target.size(), the mapping is injective and if both sets have the same size, the returned mapping is bijective.
      Type Parameters:
      A - the type of the source elements
      B - the type of the target elements
      Parameters:
      source - the source elements. Will be the keys of the encoded Map.
      target - the target elements. Will be the values of the encoded Map.
      Returns:
      a new mapping codec
      Throws:
      IllegalArgumentException - if the target sequences are empty
      NullPointerException - if one of the arguments is null
      Since:
      4.3

    • ofSubSet

      public static <T> InvertibleCodec<ISeq<T>,BitGene> ofSubSet(ISeq<? extends T> basicSet)
      The subset InvertibleCodec can be used for problems where it is required to find the best variable-sized subset from a given basic set. A typical usage example of the returned Codec is the Knapsack problem.

      The following code snippet shows a simplified variation of the Knapsack problem. 

      public final class Main {
     // The basic set from where to choose an 'optimal' subset.
     private final static ISeq<Integer> SET =
         ISeq.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);

     // Fitness function directly takes an 'int' value.
     private static int fitness(final ISeq<Integer> subset) {
         assert(subset.size() <= SET.size());
         final int size = subset.stream()
            .mapToInt(Integer::intValue)
            .sum();
         return size <= 20 ? size : 0;
     }

     public static void main(final String[] args) {
         final Engine<BitGene, Double> engine = Engine
             .builder(Main::fitness, codec.ofSubSet(SET))
             .build();
         // ...
     }
 }
      Type Parameters:
      T - the element type of the basic set
      Parameters:
      basicSet - the basic set, from where to choose the optimal subset.
      Returns:
      a new codec which can be used for modelling subset problems.
      Throws:
      NullPointerException - if the given basicSet is null; null elements are allowed.
      IllegalArgumentException - if the basicSet size is smaller than one.

    • ofSubSet

      public static <T> InvertibleCodec<ISeq<T>,EnumGene<T>> ofSubSet(ISeq<? extends T> basicSet, int size)
      The subset InvertibleCodec can be used for problems where it is required to find the best fixed-size subset from a given basic set.
      Type Parameters:
      T - the element type of the basic set
      Parameters:
      basicSet - the basic set, from where to choose the optimal subset.
      size - the length of the desired subsets
      Returns:
      a new codec which can be used for modelling subset problems.
      Throws:
      NullPointerException - if the given basicSet is null; null elements are allowed.
      IllegalArgumentException - if basicSet.size() < size, size <= 0 or basicSet.size()*size will cause an integer overflow.
      Since:
      3.4
      See Also: