API Reference

Performance indicators for multiobjective optimization: dominance with tolerance, non-dominated filtering, Purity, Γ-spread, Δ-spread, Covering and exact hypervolume. All objectives are minimized.

A point set is any AbstractVector of objective vectors, for example a Vector{Vector{Float64}}, eachcol(M) or eachrow(M). See purity, gamma_spread, delta_spread, covering and hypervolume.

Tolerance(atol, rtol)
Tolerance(tol)
Tolerance()

Componentwise tolerance used to compare objective values. For components a and b, the tolerance is

ε = max(atol, rtol * max(|a|, |b|))

Tolerance(tol) sets atol = rtol = tol, which gives ε = tol * max(1, |a|, |b|), the rule of [8]. Tolerance() uses tol = √eps(Float64) ≈ 1.49e-8, and Tolerance(0) compares exactly. Both values must be finite and nonnegative.

Examples

julia> isequivalent([1.0, 2.0], [1.0 + 1e-10, 2.0])
true

julia> isequivalent([1.0, 2.0], [1.0 + 1e-10, 2.0]; tol = Tolerance(0))
false

DominanceRelation

Result of compare(u, v) for minimization: Dominates (u dominates v), DominatedBy (v dominates u), Equivalent (every component within the tolerance) or Incomparable.

compare(u, v; tol = Tolerance()) -> DominanceRelation

Compare objective vectors u and v (minimization) under the componentwise tolerance ε_i of Tolerance:

• Dominates: u_i ≤ v_i + ε_i for all i and u_j < v_j - ε_j for some j;
• DominatedBy: the same with u and v swapped;
• Equivalent: |u_i - v_i| ≤ ε_i for all i;
• Incomparable: otherwise.

This is the rule of [8]; Tolerance(0) gives Pareto dominance.

Examples

julia> compare([1.0, 2.0], [2.0, 3.0])
Dominates::DominanceRelation = 1

julia> compare([1.0, 3.0], [2.0, 2.0])
Incomparable::DominanceRelation = 3

dominates(u, v; tol = Tolerance()) -> Bool
dominates(relation::AbstractDominance, u, v; tol = Tolerance()) -> Bool

Whether u dominates v (minimization). Without relation, or with StrictDominance, this is compare(u, v; tol) == Dominates. With WeakDominance it is weakly_dominates.

weakly_dominates(u, v; tol = Tolerance()) -> Bool

Whether u weakly dominates v: u_i ≤ v_i + ε_i for every component, that is, u dominates v or is equivalent to it. This is the "covers" relation of [4] and [5] (Def. 4).

Examples

julia> weakly_dominates([1.0, 2.0], [1.0, 2.0])
true

julia> dominates([1.0, 2.0], [1.0, 2.0])
false

isequivalent(u, v; tol = Tolerance()) -> Bool

Whether |u_i - v_i| ≤ ε_i for every component (see Tolerance).

AbstractDominance

Supertype of the relations accepted by covering and dominates(relation, u, v): WeakDominance and StrictDominance.

WeakDominance()

u weakly dominates v: it dominates or is equivalent to v. See weakly_dominates.

StrictDominance()

u dominates v and is not equivalent to it. See dominates.

nondominated_indices(F; tol = Tolerance()) -> Vector{Int}

Indices, in increasing order, of the points of F that no other point of F dominates under compare. Equivalent points are all kept; use unique_points to keep one representative. The result does not depend on the order of F.

Examples

julia> nondominated_indices([[1.0, 3.0], [2.0, 2.0], [2.0, 4.0], [1.0, 3.0]])
3-element Vector{Int64}:
 1
 2
 4

nondominated(F; tol = Tolerance())

The points of F selected by nondominated_indices, in their original order.

unique_indices(F; tol = Tolerance()) -> Vector{Int}

Indices of the first point of each group of equivalent points of F (see isequivalent): a point is kept unless an earlier kept point is equivalent to it.

unique_points(F; tol = Tolerance())

The points of F selected by unique_indices, in their original order.

Examples

julia> unique_points([[1.0, 2.0], [1.0 + 1e-12, 2.0], [0.0, 3.0]])
2-element Vector{Vector{Float64}}:
 [1.0, 2.0]
 [0.0, 3.0]

ideal_point(F) -> Vector

Componentwise minimum of the points of F. Throws an ArgumentError if F is empty.

Examples

julia> ideal_point([[1.0, 3.0], [2.0, 2.0]])
2-element Vector{Float64}:
 1.0
 2.0

nadir_point(F) -> Vector

Componentwise maximum of the points of F. Applied to the non-dominated points of a reference set, this is the nadir point of that set. Throws an ArgumentError if F is empty.