UFun

class negmas.preferences.UFun(*args, **kwargs)[source]

Bases: CardinalProb, Protocol

Can be called to map an Outcome to a Distribution or a float

Attributes Summary

`base_type`	Returns the utility_function base type ignoring discounting and similar wrappings.
`type`	Returns the preferences type.

Methods Summary

`__call__`(offer)	Call self as a function.
`difference_prob`(first, second)	Returns a numeric difference between the utility of the two given outcomes
`eval`(offer)	Evaluates the ufun without normalization (See `eval_normalized` )
`eval_normalized`(offer[, above_reserve, ...])	Evaluates the ufun normalizing the result between zero and one
`is_better`(first, second)	Compares two offers using the `ufun` returning whether the first is strictly better than the second
`is_equivalent`(first, second)	Compares two offers using the `ufun` returning whether the first is strictly equivelent than the second
`is_not_better`(first, second)	Compares two offers using the `ufun` returning whether the first is worse or equivalent than the second
`is_not_worse`(first, second)	Compares two offers using the `ufun` returning whether the first is better than the second
`is_session_dependent`()	Does the utiltiy of an outcome depend on the `NegotiatorMechanismInterface`?
`is_state_dependent`()	Does the utiltiy of an outcome depend on the negotiation state?
`is_stationary`()	Is the ufun stationary (i.e. utility value of an outcome is a constant)?.
`is_volatile`()	Does the utiltiy of an outcome depend on factors outside the negotiation?
`is_worse`(first, second)	Compares two offers using the `ufun` returning whether the first is strictly worse than the second
`minmax`()	Finds the minimum and maximum for the ufun

Attributes Documentation

base_type: Returns the utility_function base type ignoring discounting and similar wrappings.

type: Returns the preferences type.

Methods Documentation

__call__(offer: tuple | None) → Distribution | float[source]: Call self as a function.

abstractmethod difference_prob(first: tuple, second: tuple) → Distribution: Returns a numeric difference between the utility of the two given outcomes

eval(offer: tuple) → Distribution | float[source]: Evaluates the ufun without normalization (See eval_normalized )

eval_normalized(offer: tuple | None, above_reserve: bool = True, expected_limits: bool = True) → Distribution | float[source]

Evaluates the ufun normalizing the result between zero and one

Parameters:

offer (Outcome | None) – offer
above_reserve (bool) – If True, zero corresponds to the reserved value not the minimum
expected_limits (bool) – If True, the expectation of the utility limits will be used for normalization instead of the maximum range and minimum lowest limit

Remarks:

If the maximum and the minium are equal, finite and above reserve, will return 1.0.
If the maximum and the minium are equal, initinte or below reserve, will return 0.0.
For probabilistic ufuns, a distribution will still be returned.
The minimum and maximum will be evaluated freshly every time. If they are already caached in the ufun, the cache will be used.

abstractmethod is_better(first: tuple | None, second: tuple | None) → bool

Compares two offers using the ufun returning whether the first is strictly better than the second

Parameters:

first – First outcome to be compared
second – Second outcome to be compared

Remarks:

Should raise ValueError if the comparison cannot be done

abstractmethod is_equivalent(first: tuple | None, second: tuple | None) → bool

Compares two offers using the ufun returning whether the first is strictly equivelent than the second

Parameters:

first – First outcome to be compared
second – Second outcome to be compared

Remarks:

Should raise ValueError if the comparison cannot be done

abstractmethod is_not_better(first: tuple, second: tuple | None) → bool

Compares two offers using the ufun returning whether the first is worse or equivalent than the second

Parameters:

first – First outcome to be compared
second – Second outcome to be compared

Remarks:

Should raise ValueError if the comparison cannot be done

abstractmethod is_not_worse(first: tuple | None, second: tuple | None) → bool

Compares two offers using the ufun returning whether the first is better than the second

Parameters:

first – First outcome to be compared
second – Second outcome to be compared
state – The negotiation state at which the comparison is done

Remarks:

Should raise ValueError if the comparison cannot be done

abstractmethod is_session_dependent() → bool: Does the utiltiy of an outcome depend on the NegotiatorMechanismInterface?

abstractmethod is_state_dependent() → bool: Does the utiltiy of an outcome depend on the negotiation state?

abstractmethod is_stationary() → bool: Is the ufun stationary (i.e. utility value of an outcome is a constant)?

abstractmethod is_volatile() → bool

Does the utiltiy of an outcome depend on factors outside the negotiation?

Remarks:

A volatile preferences is one that can change even for the same mechanism state due to outside influence

abstractmethod is_worse(first: tuple | None, second: tuple | None) → bool

Compares two offers using the ufun returning whether the first is strictly worse than the second

Parameters:

first – First outcome to be compared
second – Second outcome to be compared

Remarks:

Should raise ValueError if the comparison cannot be done

abstractmethod minmax() → tuple[float, float][source]: Finds the minimum and maximum for the ufun