HasRange

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

Bases: HasMinMax, UFun, Protocol

Has a defined range of utility values (a minimum and a maximum) and defined best and worst outcomes

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.

best()

Returns best outcome

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

extreme_outcomes([outcome_space, issues, ...])

Finds the best and worst outcomes

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

max()

Returns maximum utility

min()

Returns minimum utility

minmax([outcome_space, issues, outcomes, ...])

Finds the range of the given utility function for the given outcomes

worst()

Returns worst outcome

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

Call self as a function.

best() → tuple[source]

Returns best outcome

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

Evaluates the ufun without normalization (See eval_normalized )

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

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.

extreme_outcomes(outcome_space: OutcomeSpace | None = None, issues: list[Issue] | None = None, outcomes: list[Outcome] | int | None = None, max_cardinality=1000) → tuple[Outcome, Outcome][source]

Finds the best and worst outcomes

Parameters:

  • ufun – The utility function

  • issues – list of issues (optional)

  • outcomes – A collection of outcomes (optional)

  • max_cardinality – the maximum number of outcomes to try sampling (if sampling is used and outcomes are not given)

Returns:

(worst, best) outcomes

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

max() → Distribution | float[source]

Returns maximum utility

min() → Distribution | float[source]

Returns minimum utility

minmax(outcome_space: OutcomeSpace | None = None, issues: list[Issue] | None = None, outcomes: list[Outcome] | int | None = None, max_cardinality=1000, above_reserve=False) → tuple[float, float][source]

Finds the range of the given utility function for the given outcomes

Parameters:

  • self – The utility function

  • issues – List of issues (optional)

  • outcomes – A collection of outcomes (optional)

  • max_cardinality – the maximum number of outcomes to try sampling (if sampling is used and outcomes are not given)

  • above_reserve – If given, the minimum and maximum will be set to reserved value if they were less than it.

Returns:

(lowest, highest) utilities in that order

worst() → tuple[source]

Returns worst outcome