HasRange

class negmas.preferences.HasRange(*args, **kwargs)

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)

Call self as a function.

Return type:

Union[Distribution, float]

best()

Returns best outcome

Return type:

tuple

abstract difference_prob(first, second)

Returns a numeric difference between the utility of the two given outcomes

Return type:

Distribution

eval(offer)

Evaluates the ufun without normalization (See eval_normalized )

Return type:

Union[Distribution, float]

eval_normalized(offer, above_reserve=True, expected_limits=True)

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

Return type:

Union[Distribution, float]

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=None, issues=None, outcomes=None, max_cardinality=1000)

Finds the best and worst outcomes

Parameters:

• ufun – The utility function

• issues (list[Issue] | None) – list of issues (optional)

• outcomes (list[tuple] | int | None) – A collection of outcomes (optional)

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

Return type:

tuple[tuple, tuple]

Returns:

(worst, best) outcomes

abstract is_better(first, second)

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

Parameters:

• first (tuple | None) – First outcome to be compared

• second (tuple | None) – Second outcome to be compared

Return type:

bool

Remarks:

• Should raise ValueError if the comparison cannot be done

abstract is_equivalent(first, second)

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

Parameters:

• first (tuple | None) – First outcome to be compared

• second (tuple | None) – Second outcome to be compared

Return type:

bool

Remarks:

• Should raise ValueError if the comparison cannot be done

abstract is_not_better(first, second)

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

Parameters:

• first (tuple) – First outcome to be compared

• second (tuple | None) – Second outcome to be compared

Return type:

bool

Remarks:

• Should raise ValueError if the comparison cannot be done

abstract is_not_worse(first, second)

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

Parameters:

• first (tuple | None) – First outcome to be compared

• second (tuple | None) – Second outcome to be compared

• state – The negotiation state at which the comparison is done

Return type:

bool

Remarks:

• Should raise ValueError if the comparison cannot be done

abstract is_session_dependent()

Does the utiltiy of an outcome depend on the NegotiatorMechanismInterface?

Return type:

bool

abstract is_state_dependent()

Does the utiltiy of an outcome depend on the negotiation state?

Return type:

bool

abstract is_stationary()

Is the ufun stationary (i.e. utility value of an outcome is a constant)?

Return type:

bool

abstract is_volatile()

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

Return type:

bool

Remarks:

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

abstract is_worse(first, second)

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

Parameters:

• first (tuple | None) – First outcome to be compared

• second (tuple | None) – Second outcome to be compared

Return type:

bool

Remarks:

• Should raise ValueError if the comparison cannot be done

max()

Returns maximum utility

Return type:

Union[Distribution, float]

min()

Returns minimum utility

Return type:

Union[Distribution, float]

minmax(outcome_space=None, issues=None, outcomes=None, max_cardinality=1000, above_reserve=False)

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

Parameters:

• self – The utility function

• issues (list[Issue] | None) – List of issues (optional)

• outcomes (list[tuple] | int | None) – 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.

Return type:

tuple[float, float]

Returns:

(lowest, highest) utilities in that order

worst()

Returns worst outcome

Return type:

tuple