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:

4.4

Author:

Franz Wilhelmstötter

Method Summary

Modifier and Type	Method and Description
static <A,B> Codec<Map<A,B>,EnumGene<Integer>>	ofMapping(ISeq<? extends A> source, ISeq<? extends B> target) Create a codec, which creates a a mapping from the elements given in the source sequence to the elements given in the target sequence.
static <A,B,M extends Map<A,B>> Codec<M,EnumGene<Integer>>	ofMapping(ISeq<? extends A> source, ISeq<? extends B> target, Supplier<M> mapSupplier) Create a codec, which creates a a mapping from the elements given in the source sequence to the elements given in the target sequence.
static Codec<double[][],DoubleGene>	ofMatrix(DoubleRange domain, int rows, int cols) Return a 2-dimensional matrix Codec for the given range.
static Codec<int[][],IntegerGene>	ofMatrix(IntRange domain, int rows, int cols) Return a 2-dimensional matrix Codec for the given range.
static Codec<long[][],LongGene>	ofMatrix(LongRange domain, int rows, int cols) Return a 2-dimensional matrix Codec for the given range.
static Codec<int[],EnumGene<Integer>>	ofPermutation(int length) Create a permutation Codec of integer in the range [0, length).
static <T> Codec<ISeq<T>,EnumGene<T>>	ofPermutation(ISeq<? extends T> alleles) Create a permutation Codec with the given alleles.
static Codec<Double,DoubleGene>	ofScalar(DoubleRange domain) Return a scalar Codec for the given range.
static Codec<Integer,IntegerGene>	ofScalar(IntRange domain) Return a scalar Codec for the given range.
static Codec<Long,LongGene>	ofScalar(LongRange domain) Return a scalar Codec for the given range.
static <A> Codec<A,AnyGene<A>>	ofScalar(Supplier<? extends A> supplier) Return a scala Codec with the given allele Supplier and allele validator.
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.
static <T> Codec<ISeq<T>,BitGene>	ofSubSet(ISeq<? extends T> basicSet) The subset Codec can be used for problems where it is required to find the best variable-sized subset from given basic set.
static <T> Codec<ISeq<T>,EnumGene<T>>	ofSubSet(ISeq<? extends T> basicSet, int size) The subset Codec can be used for problems where it is required to find the best fixed-size subset from given basic set.
static Codec<double[],DoubleGene>	ofVector(DoubleRange... domains) Create a vector Codec for the given ranges.
static Codec<double[],DoubleGene>	ofVector(DoubleRange domain, int length) Return a vector Codec for the given range.
static Codec<int[],IntegerGene>	ofVector(IntRange... domains) Create a vector Codec for the given ranges.
static Codec<int[],IntegerGene>	ofVector(IntRange domain, int length) Return a vector Codec for the given range.
static Codec<long[],LongGene>	ofVector(LongRange... domains) Create a vector Codec for the given ranges.
static Codec<long[],LongGene>	ofVector(LongRange domain, int length) Return a vector Codec for the given range.
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.
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.
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.

Methods inherited from class java.lang.Object

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

Method Detail

ofScalar

public static Codec<Integer,IntegerGene> ofScalar(IntRange domain)

Return a scalar Codec 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 Codec<Long,LongGene> ofScalar(LongRange domain)

Return a scalar Codec 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 Codec<Double,DoubleGene> ofScalar(DoubleRange domain)

Return a scalar Codec 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:

AnyGene.of(Supplier, Predicate), AnyChromosome.of(Supplier, Predicate)

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:

ofScalar(Supplier, Predicate), AnyGene.of(Supplier), AnyChromosome.of(Supplier)

ofVector

public static Codec<int[],IntegerGene> ofVector(IntRange domain,
                                                int length)

Return a vector Codec 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 Codec<long[],LongGene> ofVector(LongRange domain,
                                              int length)

Return a vector Codec 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 Codec<double[],DoubleGene> ofVector(DoubleRange domain,
                                                  int length)

Return a vector Codec 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 Codec<int[],IntegerGene> ofVector(IntRange... domains)

Create a vector Codec 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 Codec<long[],LongGene> ofVector(LongRange... domains)

Create a vector Codec 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 Codec<double[],DoubleGene> ofVector(DoubleRange... domains)

Create a vector Codec 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:

AnyChromosome.of(Supplier, Predicate, Predicate, int)

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.

ofPermutation

public static Codec<int[],EnumGene<Integer>> ofPermutation(int length)

Create a permutation Codec 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.

ofMatrix

public static Codec<int[][],IntegerGene> ofMatrix(IntRange domain,
                                                  int rows,
                                                  int cols)

Return a 2-dimensional matrix Codec 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 Codec<long[][],LongGene> ofMatrix(LongRange domain,
                                                int rows,
                                                int cols)

Return a 2-dimensional matrix Codec 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 Codec<double[][],DoubleGene> ofMatrix(DoubleRange domain,
                                                    int rows,
                                                    int cols)

Return a 2-dimensional matrix Codec 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

ofPermutation

public static <T> Codec<ISeq<T>,EnumGene<T>> ofPermutation(ISeq<? extends T> alleles)

Create a permutation Codec 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

ofMapping

public static <A,B,M extends Map<A,B>> Codec<M,EnumGene<Integer>> ofMapping(ISeq<? extends A> source,
                                                                            ISeq<? extends B> target,
                                                                            Supplier<M> mapSupplier)

Create a codec, which creates a 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 argument is null

Since:

4.3

ofMapping

public static <A,B> Codec<Map<A,B>,EnumGene<Integer>> ofMapping(ISeq<? extends A> source,
                                                                ISeq<? extends B> target)

Create a codec, which creates a 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 argument is null

Since:

4.3

ofSubSet

public static <T> Codec<ISeq<T>,BitGene> ofSubSet(ISeq<? extends T> basicSet)

The subset Codec can be used for problems where it is required to find the best variable-sized subset from 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() .collect(Collectors.summingInt(Integer::intValue)); 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> Codec<ISeq<T>,EnumGene<T>> ofSubSet(ISeq<? extends T> basicSet,
                                                      int size)

The subset Codec can be used for problems where it is required to find the best fixed-size subset from 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:

PermutationChromosome, PermutationChromosome.of(ISeq, int)