PresortingInverseUtilityFunction

class negmas.preferences.PresortingInverseUtilityFunction(ufun, levels=10, max_cache_size=10000000000, rational_only=False, n_waypints=10, eps=1e-12, rel_eps=1e-06)

Bases: InverseUFun

A utility function inverter that uses pre-sorting.

The outcome-space is sampled if it is continuous and enumerated if it is discrete during the call to init() and an ordered list of outcomes with their utility values is then cached.

Parameters:

• ufun (BaseUtilityFunction) – The utility function to be inverted

• levels (int) – discretization levels per issue

• max_cache_size (int) – maximum allowed number of outcomes in the resulting inverse

• rational_only (bool) – If true, rational outcomes will be sorted but irrational outcomes will not be sorted (should be faster if the reserved value is high)

• n_waypoints – Used to speedup sampling outcomes at given utilities. The larger, the slower init() will be but the faster worst_in() and best_in()

• eps (float) – Absolute difference between utility values to consider them equal (zero or negative to disable).

• rel_eps (float) – Relative difference between utility values to consider them equal (zero or negative to disable).

Remarks:

• The actual limit used to judge ufun equality is max(eps, rel_eps * range) where range is the difference between max and min utilities for rational outcomes. Set both eps, rel_eps to zero or a negative number to disable cycling through outcomes with equal utilities (or set cycle=False when calling the appropriate function).

Attributes Summary

initialized
ufun

Methods Summary

__call__(rng, normalized)	Calling an inverse ufun directly is equivalent to calling one_in()
all(rng, normalized)	Finds all outcomes with in the given utility value range
best()	Finds the best outcome (of the rational outcomes if constructed with sort_rational_only)
best_in(rng, normalized[, cycle])	Finds an outcome with the highest possible utility within the given range (if any)
extreme_outcomes()	Finds the worst and best outcomes that can be returned.
init()	Used to intialize the inverse ufun.
max()	Finds the maximum rational utility value (of the rational outcomes if constructed with sort_rational_only)
min()	Finds the minimum utility value (of the rational outcomes if constructed with sort_rational_only)
minmax()	Finds the minimum and maximum utility values that can be returned.
next_better()	Returns the rational outcome with utility just above the last one returned from this function
next_worse()	Returns the rational outcome with utility just below the last one returned from this function
one_in(rng, normalized[, ...])	Finds an outcome within the given range of utilities.
outcome_at(indx)	rtype: tuple | None
reset()	rtype: None
some(rng, normalized[, n])	Finds some outcomes with the given utility value (if discrete, all)
utility_at(indx)	rtype: float
within_fractions(rng)	Finds outcomes within the given fractions of utility values (the fractions must be between zero and one).
within_indices(rng)	Finds outcomes within the given indices with the best at index 0 and the worst at largest index.
worst()	Finds the worst outcome (of the rational outcomes if constructed with sort_rational_only)
worst_in(rng, normalized[, cycle])	Finds an outcome with the lowest possible utility within the given range (if any)

Attributes Documentation

initialized: bool

ufun: UFun

Methods Documentation

__call__(rng, normalized)

Calling an inverse ufun directly is equivalent to calling one_in()

Return type:

tuple | None

all(rng, normalized)

Finds all outcomes with in the given utility value range

Parameters:

rng (float | tuple[float, float]) – The range. If a value, outcome utilities must match it exactly

Return type:

list[tuple]

Remarks:

• If issues or outcomes are not None, then init_inverse will be called first

• If the outcome-space is discrete, this method will return all outcomes in the given range

best()

Finds the best outcome (of the rational outcomes if constructed with sort_rational_only)

Return type:

tuple | None

best_in(rng, normalized, cycle=True)

Finds an outcome with the highest possible utility within the given range (if any)

Parameters:

• rng (float | tuple[float, float]) – Range of utilities to find the outcome within

• normalized (bool) – If true, the range will be interpreted as on a scaled ufun with range (0-1)

• cycle (bool) – If given, the system will cycle between outcomes with the same utility value (up to eps)

Return type:

tuple | None

Remarks:

• Returns None if no such outcome exists

• This is an O(log(n)) operation (where n is the number of outcomes)

extreme_outcomes()

Finds the worst and best outcomes that can be returned.

Return type:

tuple[tuple | None, tuple | None]

Remarks:

These may be different from the results of ufun.extreme_outcomes() as they can be approximate.

init()

Used to intialize the inverse ufun. Any computationally expensive initialization should be done here not in the constructor.

max()

Finds the maximum rational utility value (of the rational outcomes if constructed with sort_rational_only)

Return type:

float

min()

Finds the minimum utility value (of the rational outcomes if constructed with sort_rational_only)

Return type:

float

minmax()

Finds the minimum and maximum utility values that can be returned.

Remarks: :rtype: tuple[float, float]

• These may be different from the results of ufun.minmax() as they can be approximate.

• Will only consider rational outcomes if constructed with sort_rational_only

next_better()

Returns the rational outcome with utility just above the last one returned from this function

Return type:

tuple | None

next_worse()

Returns the rational outcome with utility just below the last one returned from this function

Return type:

tuple | None

one_in(rng, normalized, fallback_to_higher=True, fallback_to_best=True)

Finds an outcome within the given range of utilities.

Return type:

tuple | None

Remarks:

• This is an O(log(n)) operation (where n is the number of outcomes)

• We only search rational outcomes

outcome_at(indx)

Return type:

tuple | None

reset()

Return type:

None

some(rng, normalized, n=None)

Finds some outcomes with the given utility value (if discrete, all)

Parameters:

• rng (float | tuple[float, float]) – The range. If a value, outcome utilities must match it exactly

• normalized (bool) – if given, consider the range as a normalized range betwwen 0 and 1 representing lowest and highest utilities.

• n (int | None) – The maximum number of outcomes to return

Return type:

list[tuple]

Remarks:

• If issues or outcomes are not None, then init_inverse will be called first

• If the outcome-space is discrete, this method will return all outcomes in the given range

utility_at(indx)

Return type:

float

within_fractions(rng)

Finds outcomes within the given fractions of utility values (the fractions must be between zero and one).

Return type:

list[tuple]

Remarks:

• This is an O(n) operation (where n is the number of outcomes)

within_indices(rng)

Finds outcomes within the given indices with the best at index 0 and the worst at largest index.

Return type:

list[tuple]

Remarks:

• Works only for discrete outcome spaces

worst()

Finds the worst outcome (of the rational outcomes if constructed with sort_rational_only)

Return type:

tuple | None

worst_in(rng, normalized, cycle=True)

Finds an outcome with the lowest possible utility within the given range (if any)

Parameters:

• rng (float | tuple[float, float]) – Range of utilities to find the outcome within

• normalized (bool) – If true, the range will be interpreted as on a scaled ufun with range (0-1)

• cycle (bool) – If given, the system will cycle between outcomes with the same utility value (up to eps)

Return type:

tuple | None

Remarks:

• Returns None if no such outcome exists, or the worst outcome in the given range is irrational

• This is an O(log(n)) operation (where n is the number of outcomes)