SamplingInverseUtilityFunction

class negmas.preferences.SamplingInverseUtilityFunction(ufun: BaseUtilityFunction, max_samples_per_call: int = 10000)

Bases: InverseUFun

A utility function inverter that uses sampling.

Nothing is done during initialization so the fixed cost of this inverter is minimal. Nevertheless, each time the system is asked to find an outcome within some range, it uses random sampling which is very inefficient and suffers from the curse of dimensionality.

Attributes Summary

initialized
ufun

Methods Summary

__call__(rng, normalized)	Calling an inverse ufun directly is equivalent to calling one_in()
all(rng)	Finds all outcomes with in the given utility value range
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 some outcomes with the given utility value (if discrete, all)
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

Attributes Documentation

initialized: bool

ufun: UFun

Methods Documentation

__call__(rng: float | tuple[float, float], normalized: bool) → tuple | None

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

all(rng: float | tuple[float, float]) → list[tuple]

Finds all outcomes with in the given utility value range

Parameters:

rng – The range. If a value, outcome utilities must match it exactly

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

abstractmethod best() → tuple

Finds the best outcome

best_in(rng: float | tuple[float, float], normalized: bool) → tuple | None

Finds an outcome with highest utility within the given range

Parameters:

• rng – The range (or single value) of utility values to search for outcomes

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

extreme_outcomes() → tuple[tuple | None, tuple | None]

Finds the worst and best outcomes that can be returned.

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.

abstractmethod max() → float

Finds the maximum utility value that can be returned.

Remarks:

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

abstractmethod min() → float

Finds the minimum utility value that can be returned.

Remarks:

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

minmax() → tuple[float, float]

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

Remarks:

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

next_better() → tuple | None

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

next_worse() → tuple | None

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

one_in(rng: float | tuple[float, float], normalized: float, fallback_to_higher: bool = True, fallback_to_best: bool = True) → tuple | None

Finds an outcmoe with the given utility value.

Parameters:

• rng – The range (or single value) of utility values to search for outcomes

• normalized – 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.

some(rng: float | tuple[float, float], normalized: bool, n: int | None = None) → list[tuple]

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

Parameters:

• rng – The range. If a value, outcome utilities must match it exactly

• n – The maximum number of outcomes to return

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

abstractmethod within_fractions(rng: tuple[float, float]) → list[tuple]

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

abstractmethod within_indices(rng: tuple[int, int]) → list[tuple]

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

Remarks:

• Works only for discrete outcome spaces

abstractmethod worst() → tuple

Finds the worst outcome

worst_in(rng: float | tuple[float, float], normalized: bool) → tuple | None

Finds an outcome with lowest utility within the given range

Parameters:

• rng – The range (or single value) of utility values to search for outcomes

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