moocore.whv_hype

moocore.whv_hype(data, /, *, ref, ideal, maximise=False, nsamples=100000, dist='uniform', seed=None, mu=None)

Approximation of the (weighted) hypervolume by Monte-Carlo sampling (2D only).

Return an estimation of the hypervolume of the space dominated by the input data following the procedure described by Auger et al.[1]. A weight distribution describing user preferences may be specified.

Warning

The current implementation only supports 2 objectives.

Parameters:

• data (numpy.ndarray) – Numpy array of numerical values, where each row gives the coordinates of a point in objective space. If the array is created from the read_datasets() function, remove the last (set) column.

• ref (numpy.ndarray or list) – Reference point as a numpy array or list. Must have same length as the number of columns of the dataset.

• ideal (numpy.ndarray or list) – Ideal point as a numpy array or list. Must have same length as the number of columns of the dataset.

• maximise (bool or or list of bool) – Whether the objectives must be maximised instead of minimised. Either a single boolean value that applies to all objectives or a list of booleans, with one value per objective. Also accepts a 1D numpy array with values 0 or 1 for each objective.

• nsamples (int, default: 100000) – Number of samples for Monte-Carlo sampling. Higher values give more accurate approximation of the true hypervolume but require more time.

• dist (Literal['uniform', 'point', 'exponential'], default: 'uniform') –

  Weight distribution [1]. The ones currently supported are:

  • uniform: corresponds to the default hypervolume (unweighted).

  • point : describes a goal in the objective space, where mu gives the coordinates of the goal. The resulting weight distribution is a multivariate normal distribution centred at the goal.

  • exponential : describes an exponential distribution with rate parameter 1/mu, i.e., \(\lambda = \frac{1}{\mu}\).

• seed (int or numpy.random.Generator) – Either an integer to seed the NumPy random number generator (RNG) or an instance of Numpy-compatible RNG. None uses the default RNG of Numpy.

• mu (float or 1D numpy.array) – Parameter of dist. See above for details.

Returns:

float – A single numerical value, the weighted hypervolume.

See also

read_datasets, hypervolume

References

[1] (1,2)

Anne Auger, Johannes Bader, Dimo Brockhoff, and Eckart Zitzler. Articulating user preferences in many-objective problems by sampling the weighted hypervolume. In Franz Rothlauf, editor, Proceedings of the Genetic and Evolutionary Computation Conference, GECCO 2009, pages 555–562. ACM Press, New York, NY, 2009.

Examples

>>> moocore.hypervolume([[2, 2]], ref=4)
4.0
>>> moocore.whv_hype([[2, 2]], ref=4, ideal=1, seed=42)
3.99807
>>> moocore.hypervolume([[3, 1]], ref=4)
3.0
>>> moocore.whv_hype([[3, 1]], ref=4, ideal=1, seed=42)
3.00555
>>> moocore.whv_hype(
...     [[2, 2]], ref=4, ideal=1, dist="exponential", mu=0.2, seed=42
... )
1.14624
>>> moocore.whv_hype(
...     [[3, 1]], ref=4, ideal=1, dist="exponential", mu=0.2, seed=42
... )
1.66815
>>> moocore.whv_hype(
...     [[2, 2]],
...     ref=4,
...     ideal=1,
...     dist="point",
...     mu=[2.9, 0.9],
...     seed=42,
... )
0.64485
>>> moocore.whv_hype(
...     [[3, 1]],
...     ref=4,
...     ideal=1,
...     dist="point",
...     mu=[2.9, 0.9],
...     seed=42,
... )
4.03632