IPUtilityFunction

class negmas.utilities.IPUtilityFunction(outcomes: Iterable[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]], distributions: Optional[Iterable[negmas.helpers.Distribution]] = None, issue_names: Optional[Iterable[str]] = None, name=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

Independent Probabilistic Utility Function.

Parameters
  • outcomes – Iterable of outcomes

  • distributions – the distributions. One for each outcome

  • name – ufun name

Examples

>>> f = IPUtilityFunction(outcomes=[('o1',), ('o2',)]
...         , distributions=[UtilityDistribution(dtype='uniform', loc=0.0, scale=0.5)
...         , UtilityDistribution(dtype='uniform', loc=0.1, scale=0.5)])
>>> f(('o1',))
U(0.0, 0.5)
>>> f = IPUtilityFunction(outcomes=[{'cost': 10, 'dist': 20}, {'cost': 10, 'dist': 30}]
...         , distributions=[UtilityDistribution(dtype='uniform', loc=0.0, scale=0.5)
...         , UtilityDistribution(dtype='uniform', loc=0.1, scale=0.5)])
>>> f({'cost': 10, 'dist': 30})
U(0.1, 0.6)

Methods Summary

distribution(outcome)

Returns the distributon associated with a specific outcome :param outcome:

eval(offer)

Calculate the utility_function value for a given outcome.

from_mapping(mapping[, range, uncertainty, …])

Generates a distribution from which u may have been sampled :param mapping: mapping from outcomes to float values :param range: range of the utility_function values :param uncertainty: uncertainty level :param variability: The variability within the ufun :param reserved_value: The reserved value

from_ufun(u[, range, uncertainty, variability])

Generates a distribution from which u may have been sampled :param u: :param range: range of the utility_function values :param uncertainty: uncertainty level

key(outcome)

Returns the key of the given outcome in self.distributions.

sample()

Samples the utility_function distribution to create a mapping utility function

xml(issues)

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

Methods Documentation

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

Returns the distributon associated with a specific outcome :param outcome:

Returns:

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

Calculate the utility_function value for a given outcome.

Parameters

offer – The offer to be evaluated.

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

  • Return A UtilityValue not a float for real-valued utilities for the benefit of inspection code.

Returns

The utility_function value which may be a distribution. If None it means the utility_function value cannot be calculated.

Return type

UtilityValue

classmethod from_mapping(mapping: Dict[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]], float], range: Tuple[float, float] = (0.0, 1.0), uncertainty: float = 0.5, variability: float = 0.0, reserved_value: float = - inf)negmas.utilities.IPUtilityFunction[source]

Generates a distribution from which u may have been sampled :param mapping: mapping from outcomes to float values :param range: range of the utility_function values :param uncertainty: uncertainty level :param variability: The variability within the ufun :param reserved_value: The reserved value

Examples

  • No uncertainty

>>> mapping=dict(zip([('o1',), ('o2',)], [0.3, 0.7]))
>>> p = IPUtilityFunction.from_mapping(mapping, uncertainty=0.0)
>>> print(p)
{('o1',): U(0.3, 0.3), ('o2',): U(0.7, 0.7)}
  • Full uncertainty

>>> mapping=dict(zip([('o1',), ('o2',)], [0.3, 0.7]))
>>> p = IPUtilityFunction.from_mapping(mapping, uncertainty=1.0)
>>> print(p)
{('o1',): U(0.0, 1.0), ('o2',): U(0.0, 1.0)}
  • some uncertainty

>>> mapping=dict(zip([('o1',), ('o2',)], [0.3, 0.7]))
>>> p = IPUtilityFunction.from_mapping(mapping, uncertainty=0.1)
>>> print([_.scale for _ in p.distributions.values()])
[0.1, 0.1]
>>> for k, v in p.distributions.items():
...     assert v.loc <= mapping[k]
Returns

a new IPUtilityFunction

classmethod from_ufun(u: negmas.utilities.MappingUtilityFunction, range: Tuple[float, float] = (0.0, 1.0), uncertainty: float = 0.5, variability: float = 0.0)negmas.utilities.IPUtilityFunction[source]

Generates a distribution from which u may have been sampled :param u: :param range: range of the utility_function values :param uncertainty: uncertainty level

Examples

  • No uncertainty

>>> u = MappingUtilityFunction(mapping=dict(zip([('o1',), ('o2',)], [0.3, 0.7])))
>>> p = IPUtilityFunction.from_ufun(u, uncertainty=0.0)
>>> print(p)
{('o1',): U(0.3, 0.3), ('o2',): U(0.7, 0.7)}
  • Full uncertainty

>>> u = MappingUtilityFunction(mapping=dict(zip([('o1',), ('o2',)], [0.3, 0.7])))
>>> p = IPUtilityFunction.from_ufun(u, uncertainty=1.0)
>>> print(p)
{('o1',): U(0.0, 1.0), ('o2',): U(0.0, 1.0)}
  • some uncertainty

>>> u = MappingUtilityFunction(mapping=dict(zip([('o1',), ('o2',)], [0.3, 0.7])))
>>> p = IPUtilityFunction.from_ufun(u, uncertainty=0.1)
>>> print([_.scale for _ in p.distributions.values()])
[0.1, 0.1]
>>> for k, v in p.distributions.items():
...     assert v.loc <= u(k)
Returns

a new IPUtilityFunction

key(outcome: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]])[source]

Returns the key of the given outcome in self.distributions.

Parameters

outcome

Returns

tuple

Examples:

>>> f = IPUtilityFunction(outcomes=[('o1',), ('o2',)]
...         , distributions=[UtilityDistribution(dtype='uniform', loc=0.0, scale=0.5)
...         , UtilityDistribution(dtype='uniform', loc=0.1, scale=0.5)])
>>> f.key({0:'o1'})
('o1',)
>>> f.key(('o1',))
('o1',)
>>> f.distributions
{('o1',): U(0.0, 0.5), ('o2',): U(0.1, 0.6)}
>>> f.distribution(('o1',))
U(0.0, 0.5)
>>> f = IPUtilityFunction(outcomes=[{'cost': 10, 'dist': 20}, {'dist': 30, 'cost': 10}]
...         , distributions=[UtilityDistribution(dtype='uniform', loc=0.0, scale=0.5)
...         , UtilityDistribution(dtype='uniform', loc=0.1, scale=0.5)])
>>> f.key({'dist': 30, 'cost': 10})
(10, 30)
>>> f.key({'cost': 10, 'dist': 30})
(10, 30)
>>> f.distributions
{(10, 20): U(0.0, 0.5), (10, 30): U(0.1, 0.6)}
>>> f.distribution((10, 20.0))
U(0.0, 0.5)
>>> f.distribution({'cost': 10, 'dist': 20})
U(0.0, 0.5)
sample()negmas.utilities.MappingUtilityFunction[source]

Samples the utility_function distribution to create a mapping utility function

Examples

>>> import random
>>> f = IPUtilityFunction(outcomes=[('o1',), ('o2',)]
...         , distributions=[UtilityDistribution(dtype='uniform', loc=0.0, scale=0.2)
...         , UtilityDistribution(dtype='uniform', loc=0.4, scale=0.5)])
>>> u = f.sample()
>>> assert u(('o1',)) <= 0.2
>>> assert 0.4 <= u(('o2',)) <= 0.9
Returns

MappingUtilityFunction

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