io.jenetics.ext.moea

Interface Vec<T>

Type Parameters:

T - the underlying array type, like int[] or double[]

All Superinterfaces:

Comparable<Vec<T>>

public interface Vec<T>
extends Comparable<Vec<T>>

The Vec interface represents the fitness result of a multi-objective fitness function. It also defines a set of static factory methods which allows you to create Vec instance from a given int[], long[] or double[] array.

final Vec<double[]> point2D = Vec.of(0.1, 5.4); final Vec<int[]> point3D = Vec.of(1, 2, 3);

The underlying array is just wrapped and not copied. This means you can change the values of the Vec once it is created, Not copying the underlying array is done for performance reason. Changing the Vec data is, of course, never a good idea.

Since:

4.1

Version:

4.1

Author:

Franz Wilhelmstötter

See Also:

VecFactory, Pareto efficiency

Implementation Note:

Although the Vec interface extends the Comparable interface, it violates its general contract. It only implements the pareto dominance relation, which defines a partial order. So, trying to sort a list of Vec objects, might lead to an exception (thrown by the sorting method) at runtime.

Method Summary

Modifier and Type	Method and Description
ElementComparator<T>	comparator() Return the comparator for comparing the elements of this MO vector.
default int	compare(Vec<T> other, int index) Compares the this vector with the other at the given component index.
default int	compareTo(Vec<T> other) The default implementation uses the dominance(Vec) function for defining a partial order of two vectors.
T	data() Return the underlying data structure.
ElementDistance<T>	distance() Return a function which calculates the element distance of a vector at a given element index.
default double	distance(Vec<T> other, int index) Calculates the distance between two vector elements at the given index.
Comparator<T>	dominance() Return the comparator which defines the (Pareto) dominance measure.
static <C extends Comparable<? super C>> int	dominance(C[] u, C[] v) Calculates the Pareto Dominance of the two vectors u and v.
static int	dominance(double[] u, double[] v) Calculates the Pareto Dominance of the two vectors u and v.
static int	dominance(int[] u, int[] v) Calculates the Pareto Dominance of the two vectors u and v.
static int	dominance(long[] u, long[] v) Calculates the Pareto Dominance of the two vectors u and v.
static <T> int	dominance(T[] u, T[] v, Comparator<? super T> comparator) Calculates the Pareto Dominance of the two vectors u and v.
default int	dominance(Vec<T> other) Calculates the Pareto Dominance of vector value() and other.
int	length() Return the number of vector elements.
static <C extends Comparable<? super C>> Vec<C[]>	of(C[] array) Wraps the given array into a Vec object.
static <C extends Comparable<? super C>> Vec<C[]>	of(C[] array, ElementDistance<C[]> distance) Wraps the given array into a Vec object.
static Vec<double[]>	of(double... array) Wraps the given array into a Vec object.
static Vec<int[]>	of(int... array) Wraps the given array into a Vec object.
static Vec<long[]>	of(long... array) Wraps the given array into a Vec object.
static <T> Vec<T[]>	of(T[] array, Comparator<? super T> comparator, ElementDistance<T[]> distance) Wraps the given array into a Vec object.

Method Detail

data

T data()

Return the underlying data structure.

Returns:

the underlying data structure

length

int length()

Return the number of vector elements.

Returns:

the number of vector elements

comparator

ElementComparator<T> comparator()

Return the comparator for comparing the elements of this MO vector.

Returns:

the comparator for comparing the elements of this MO vector

distance

ElementDistance<T> distance()

Return a function which calculates the element distance of a vector at a given element index.

Returns:

a function which calculates the element distance of a vector at a given element index

dominance

Comparator<T> dominance()

Return the comparator which defines the (Pareto) dominance measure.

Returns:

the comparator which defines the (Pareto) dominance measure

compare

default int compare(Vec<T> other,
                    int index)

Compares the this vector with the other at the given component index.

Parameters:

other - the other vector

index - the component index

Returns:

a negative integer, zero, or a positive integer as this[index] is less than, equal to, or greater than other[index]

Throws:

NullPointerException - if the other object is null

IllegalArgumentException - if the index is out of the valid range [0, length())

distance

default double distance(Vec<T> other,
                        int index)

Calculates the distance between two vector elements at the given index.

Parameters:

other - the second vector

index - the vector element index

Returns:

the distance between two vector elements

Throws:

NullPointerException - if the other vector is null

IllegalArgumentException - if the index is out of the valid range [0, length())

dominance

default int dominance(Vec<T> other)

Calculates the Pareto Dominance of vector value() and other.

Parameters:

other - the other vector

Returns:

1 if value() ≻ other, -1 if other ≻ value() and 0 otherwise

Throws:

NullPointerException - if the other vector is null

compareTo

default int compareTo(Vec<T> other)

The default implementation uses the dominance(Vec) function for defining a partial order of two vectors.

Specified by:

compareTo in interface Comparable<Vec<T>>

Parameters:

other - the other vector

Returns:

1 if value() ≻ other, -1 if other ≻ value() and 0 otherwise

Throws:

NullPointerException - if the other vector is null

dominance

static <C extends Comparable<? super C>> int dominance(C[] u,
                                                       C[] v)

Calculates the Pareto Dominance of the two vectors u and v.

Type Parameters:

C - the element type of vector u and v

Parameters:

u - the first vector

v - the second vector

Returns:

1 if u ≻ v, -1 if v ≻ u and 0 otherwise

Throws:

NullPointerException - if one of the arguments is null

IllegalArgumentException - if u.length != v.length

See Also:

Pareto.dominance(Comparable[], Comparable[])

dominance

static <T> int dominance(T[] u,
                         T[] v,
                         Comparator<? super T> comparator)

Calculates the Pareto Dominance of the two vectors u and v.

Type Parameters:

T - the element type of vector u and v

Parameters:

u - the first vector

v - the second vector

comparator - the element comparator which is used for calculating the dominance

Returns:

1 if u ≻ v, -1 if v ≻ u and 0 otherwise

Throws:

NullPointerException - if one of the arguments is null

IllegalArgumentException - if u.length != v.length

See Also:

Pareto.dominance(Object[], Object[], Comparator)

dominance

static int dominance(int[] u,
                     int[] v)

Calculates the Pareto Dominance of the two vectors u and v.

Parameters:

u - the first vector

v - the second vector

Returns:

1 if u ≻ v, -1 if v ≻ u and 0 otherwise

Throws:

NullPointerException - if one of the arguments is null

IllegalArgumentException - if u.length != v.length

See Also:

Pareto.dominance(int[], int[])

dominance

static int dominance(long[] u,
                     long[] v)

Calculates the Pareto Dominance of the two vectors u and v.

Parameters:

u - the first vector

v - the second vector

Returns:

1 if u ≻ v, -1 if v ≻ u and 0 otherwise

Throws:

NullPointerException - if one of the arguments is null

IllegalArgumentException - if u.length != v.length

See Also:

Pareto.dominance(long[], long[])

dominance

static int dominance(double[] u,
                     double[] v)

Calculates the Pareto Dominance of the two vectors u and v.

Parameters:

u - the first vector

v - the second vector

Returns:

1 if u ≻ v, -1 if v ≻ u and 0 otherwise

Throws:

NullPointerException - if one of the arguments is null

IllegalArgumentException - if u.length != v.length

See Also:

Pareto.dominance(double[], double[])

of

static <C extends Comparable<? super C>> Vec<C[]> of(C[] array)

Wraps the given array into a Vec object.

Type Parameters:

C - the array element type

Parameters:

array - the wrapped array

Returns:

the given array wrapped into a Vec object.

Throws:

NullPointerException - if one of the arguments is null

IllegalArgumentException - if the array length is zero

of

static <C extends Comparable<? super C>> Vec<C[]> of(C[] array,
                                                     ElementDistance<C[]> distance)

Wraps the given array into a Vec object.

Type Parameters:

C - the array element type

Parameters:

array - the wrapped array

distance - the array element distance measure

Returns:

the given array wrapped into a Vec object.

Throws:

NullPointerException - if one of the arguments is null

IllegalArgumentException - if the array length is zero

of

static <T> Vec<T[]> of(T[] array,
                       Comparator<? super T> comparator,
                       ElementDistance<T[]> distance)

Wraps the given array into a Vec object.

Type Parameters:

T - the array element type

Parameters:

array - the wrapped array

comparator - the (natural order) comparator of the array elements

distance - the distance function between two vector elements

Returns:

the given array wrapped into a Vec object.

Throws:

NullPointerException - if one of the arguments is null

IllegalArgumentException - if the array length is zero

of

static Vec<int[]> of(int... array)

Wraps the given array into a Vec object.

Parameters:

array - the wrapped array

Returns:

the given array wrapped into a Vec object.

Throws:

NullPointerException - if the given array is null

IllegalArgumentException - if the array length is zero

of

static Vec<long[]> of(long... array)

Wraps the given array into a Vec object.

Parameters:

array - the wrapped array

Returns:

the given array wrapped into a Vec object.

Throws:

NullPointerException - if the given array is null

IllegalArgumentException - if the array length is zero

of

static Vec<double[]> of(double... array)

Wraps the given array into a Vec object.

Parameters:

array - the wrapped array

Returns:

the given array wrapped into a Vec object.

Throws:

NullPointerException - if the given array is null

IllegalArgumentException - if the array length is zero