InverseUFun

class negmas.preferences.InverseUFun(ufun)[source]

Bases: Protocol

Can be used to get one or more outcomes at a given range

Methods Summary

__call__(rng, normalized)

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

best()

Finds the best outcome

best_in(rng, normalized)

Finds an outcome with highest utility within the given range

extreme_outcomes()

Finds the worst and best outcomes that can be returned.

init()

Used to intialize the inverse ufun.

max()

Finds the maximum utility value that can be returned.

min()

Finds the minimum utility value that can be returned.

minmax()

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

next_better()

Returns the rational outcome with utility just below 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 outcmoe with the given utility value.

some(rng, normalized[, n])

Finds a list of outcomes with utilities in the given range.

within_fractions(rng)

Finds outocmes within the given fractions of utility values.

within_indices(rng)

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

worst()

Finds the worst outcome

worst_in(rng, normalized)

Finds an outcome with lowest utility within the given range

Methods Documentation

abstract __call__(rng, normalized)[source]

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

Return type:

tuple | None

abstract best()[source]

Finds the best outcome

Return type:

tuple

abstract best_in(rng, normalized)[source]

Finds an outcome with highest utility within the given range

Parameters:

  • rng (float | tuple[float, float]) – The range (or single value) of utility values to search for outcomes

  • normalized (bool) – if True, the input rng will be understood as ranging from 0-1 (1=max, 0=min) independent of the ufun actual range

Return type:

tuple | None

abstract extreme_outcomes()[source]

Finds the worst and best outcomes that can be returned.

Return type:

tuple[tuple, tuple]

Remarks:

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

init()[source]

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

abstract max()[source]

Finds the maximum utility value that can be returned.

Return type:

float

Remarks:

  • May be different from the maximum of the whole ufun if there is approximation

abstract min()[source]

Finds the minimum utility value that can be returned.

Return type:

float

Remarks:

  • May be different from the minimum of the whole ufun if there is approximation

abstract minmax()[source]

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

Return type:

tuple[float, float]

Remarks:

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

next_better()[source]

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

Return type:

tuple | None

next_worse()[source]

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

Return type:

tuple | None

abstract one_in(rng, normalized, fallback_to_higher=True, fallback_to_best=True)[source]

Finds an outcmoe with the given utility value.

Parameters:

  • rng (float | tuple[float, float]) – The range (or single value) of utility values to search for outcomes

  • normalized (bool) – if True, the input rng will be understood as ranging from 0-1 (1=max, 0=min) independent of the ufun actual range

  • fall_back_to_higher – if True, any outcome above the minimum in the range will be returned if nothing can be found in the range

  • fall_back_to_best – if True, the best outcome will always be offered if no outcome in the given range is found.

Return type:

tuple | None

abstract some(rng, normalized, n=None)[source]

Finds a list of outcomes with utilities in the given range.

Parameters:

  • rng (float | tuple[float, float]) – The range (or single value) of utility values to search for outcomes

  • normalized (bool) – if True, the input rng will be understood as ranging from 0-1 (1=max, 0=min) independent of the ufun actual range

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

Return type:

list[tuple]

Remarks:

  • If the ufun outcome space is continuous a sample of outcomes is returned

  • If the ufun outcome space is discrete all outcomes in the range are returned

abstract within_fractions(rng)[source]

Finds outocmes within the given fractions of utility values. rng is always assumed to be normalized between 0-1

Return type:

list[tuple]

abstract within_indices(rng)[source]

Finds outocmes 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

abstract worst()[source]

Finds the worst outcome

Return type:

tuple

abstract worst_in(rng, normalized)[source]

Finds an outcome with lowest utility within the given range

Parameters:

  • rng (float | tuple[float, float]) – The range (or single value) of utility values to search for outcomes

  • normalized (bool) – if True, the input rng will be understood as ranging from 0-1 (1=max, 0=min) independent of the ufun actual range

Return type:

tuple | None