NonLinearUtilityAggregationFunction

class negmas.utilities.NonLinearUtilityAggregationFunction(issue_utilities: MutableMapping[Any, Union[Callable[[Any], Any], Mapping, Sequence]], f: Callable[[Dict[Any, Union[negmas.helpers.Distribution, float]]], Union[negmas.helpers.Distribution, float]], name: Optional[str] = None, reserved_value: Union[negmas.helpers.Distribution, float] = - inf, ami: Optional[negmas.common.AgentMechanismInterface] = None, outcome_type: Optional[Type] = None, id=None)[source]

Bases: negmas.utilities.UtilityFunction

A nonlinear utility function.

Allows for the modeling of a single nonlinear utility function that combines the utilities of different issues.

Parameters
  • issue_utilities – A set of mappings from issue values to utility functions. These are generic mappings so Callable(s) and Mapping(s) are both accepted

  • f – A nonlinear function mapping from a dict of utility_function-per-issue to a float

  • name – name of the utility function. If None a random name will be generated.

Notes

The utility is calculated as:

\[\begin{split}u = f\\left(u_0\\left(i_0\\right), u_1\\left(i_1\\right), ..., u_n\\left(i_n\\right)\\right)\end{split}\]

where \(u_j()\) is the utility function for issue \(j\) and \(i_j\) is value of issue \(j\) in the evaluated outcome.

Examples

>>> issues = [Issue((10.0, 20.0), 'price'), Issue(['delivered', 'not delivered'], 'delivery')
...           , Issue(5, 'quality')]
>>> print(list(map(str, issues)))
['price: (10.0, 20.0)', "delivery: ['delivered', 'not delivered']", 'quality: (0, 4)']
>>> g = NonLinearUtilityAggregationFunction({ 'price': lambda x: 2.0*x
...                                         , 'delivery': {'delivered': 10, 'not delivered': -10}
...                                         , 'quality': MappingUtilityFunction(lambda x: x-3)}
...         , f=lambda u: u['price']  + 2.0 * u['quality'])
>>> float(g({'quality': 2, 'price': 14.0, 'delivery': 'delivered'})) - ((2.0*14)+2.0*(2.0-3.0))
0.0
>>> g = NonLinearUtilityAggregationFunction({'price'    : lambda x: 2.0*x
...                                         , 'delivery': {'delivered': 10, 'not delivered': -10}}
...         , f=lambda u: 2.0 * u['price'] )
>>> float(g({'price': 14.0, 'delivery': 'delivered'})) - (2.0*(2.0*14))
0.0

Attributes Summary

ami

outcome_type

Methods Summary

eval(offer)

Calculate the utility value for a given outcome.

from_dict(d)

to_dict()

xml(issues)

Converts the function into a well formed XML string preferrably in GENIUS format.

Attributes Documentation

ami
outcome_type

Methods Documentation

eval(offer: Optional[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]])Optional[Union[negmas.helpers.Distribution, float]][source]

Calculate the utility value for a given outcome.

Parameters

offer – The offer to be evaluated.

Returns

The utility_function value which may be a distribution.

If None it means the utility_function value cannot be calculated.

Return type

UtilityValue

Remarks:
  • You cannot return None from overriden eval() functions but raise an exception (ValueError) if it was not possible to calculate the UtilityValue.

  • Typehint the return type as a UtilityValue instead of a float for the benefit of inspection code.

  • Return the reserved value if the offer was None

  • NEVER call the baseclass using super() when overriding this method. Calling super will lead to an infinite loop.

  • The default implementation assumes that is_better is defined and uses it to do the evaluation. Note that the default implementation of is_better does assume that eval is defined and uses it. This means that failing to define both leads to an infinite loop.

classmethod from_dict(d)[source]
to_dict()[source]
xml(issues: List[negmas.outcomes.Issue])str[source]

Converts the function into a well formed XML string preferrably in GENIUS format.

If the output has with </objective> then discount factor and reserved value should also be included If the output has </utility_space> it will not be appended in to_xml_str