UniformUtilityFunction

class negmas.preferences.UniformUtilityFunction(loc, scale, *args, **kwargs)[source]

Bases: negmas.preferences.prob.locscale.ILSUtilityFunction

A utility function which represents the loc and scale deviations as any crisp ufun

Attributes Summary

`base_type`	Returns the utility_function base type ignoring discounting and similar wrappings.
`id`	The unique ID of this entity
`name`	A convenient name of the entity (intended primarily for printing/logging/debugging).
`owner`
`reserved_distribution`	rtype `Distribution`
`short_type_name`	rtype `str`
`type`	Returns the utility_function type.
`type_name`	rtype `str`
`uuid`	The unique ID of this entity

Methods Summary

`__call__`(offer)	Calculate the utility_function value for a given outcome.
`argrank`(outcomes[, descending])	Ranks the given list of outcomes with weights.
`argrank_with_weights`(outcomes[, descending])	Ranks the given list of outcomes with weights.
`best`()	rtype `tuple`
`changes`()	rtype `list`[`PreferencesChange`]
`checkpoint`(path[, file_name, info, ...])	Saves a checkpoint of the current object at the given path.
`checkpoint_info`(file_name)	Returns the information associated with a dump of the object saved in the given file
`create`(args, *kwargs)	Creates an object and returns a proxy to it.
`difference`(first, second)	Returns a numeric difference between the utility of the two given outcomes
`difference_prob`(first, second)	Returns a numeric difference between the utility of the two given outcomes
`eu`(offer)	calculates the expected utility value of the input outcome
`eval`(offer)	rtype `ScipyDistribution`
`eval_normalized`(offer[, above_reserve, ...])	Evaluates the ufun normalizing the result between zero and one
`extreme_outcomes`([outcome_space, issues, ...])	rtype tuple[Outcome, Outcome]
`from_checkpoint`(file_name[, return_info])	Creates an object from a saved checkpoint
`from_dict`(d)
`from_genius`(file_name, **kwargs)	Imports a utility function from a GENIUS XML file.
`from_xml_str`(xml_str, issues[, ...])	Imports a utility function from a GENIUS XML string.
`generate_bilateral`(outcomes[, ...])	Generates a couple of utility functions
`generate_random`(n, outcomes[, normalized, scale])	Generates N mapping utility functions
`generate_random_bilateral`(outcomes[, scale])	Generates a couple of utility functions
`invert`([inverter])	Inverts the ufun, initializes it and caches the result.
`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)	Is `first` at least as good as `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`()	Are the preferences stationary (i.e.
`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`()	rtype `Union`[`Distribution`, `float`]
`min`()	rtype `Union`[`Distribution`, `float`]
`minmax`([outcome_space, issues, outcomes, ...])	Finds the range of the given utility function for the given outcomes
`normalize`([to, minmax])	rtype T
`normalize_for`([to, outcome_space, issues, ...])	rtype T
`rank`(outcomes[, descending])	Ranks the given list of outcomes with weights.
`rank_with_weights`(outcomes[, descending])	Ranks the given list of outcomes with weights.
`sample_outcome_with_utility`(rng[, ...])	Samples an outcome in the given utiltity range or return None if not possible
`scale_by`(scale[, scale_reserved])	rtype WeightedUtilityFunction \| T
`scale_max`(to[, rng])	rtype T
`scale_max_for`(to[, outcome_space, issues, ...])	rtype T
`scale_min`(to[, rng])	rtype T
`scale_min_for`(to[, outcome_space, issues, ...])	rtype T
`shift_by`(offset[, shift_reserved])	rtype WeightedUtilityFunction \| T
`shift_max_for`(to[, outcome_space, issues, ...])	rtype T
`shift_min_for`(to[, outcome_space, issues, ...])	rtype T
`spawn`([spawn_as, spawn_params])
`spawn_object`(args, *kwargs)
`to_crisp`()	rtype `UtilityFunction`
`to_dict`()	rtype `dict`[`str`, `Any`]
`to_genius`(file_name[, issues])	Exports a utility function to a GENIUS XML file.
`to_prob`()	rtype `ProbUtilityFunction`
`to_stationary`()
`to_xml_str`([issues, discount_factor])	Exports a utility function to a well formatted string
`worst`()	rtype `tuple`

Attributes Documentation

base_type

Returns the utility_function base type ignoring discounting and similar wrappings.

Return type: str

id: The unique ID of this entity

name: A convenient name of the entity (intended primarily for printing/logging/debugging).

owner: Rational | None = None

reserved_distribution

Return type: Distribution

short_type_name

Return type: str

type

Returns the utility_function type.

Each class inheriting from this UtilityFunction class will have its own type. The default type is the empty string.

Examples

>>> from negmas.preferences import *
>>> from negmas.outcomes import make_issue
>>> print(LinearAdditiveUtilityFunction((lambda x:x, lambda x:x), issues=[make_issue((0, 1), (0, 1))]).type)
linear_additive
>>> print(MappingUtilityFunction([lambda x: x], issues=[make_issue((0.0, 1.0))]).type)
mapping

Returns: utility_function type
Return type: str

type_name

Return type: str

uuid: The unique ID of this entity

Methods Documentation

__call__(offer)

Calculate the utility_function value for a given outcome.

Parameters: offer (Outcome | None) – The offer to be evaluated.

Remarks:

It calls the abstract method eval after opationally adjusting the outcome type.

It is preferred to override eval instead of directly overriding this method

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

Return a float from your eval implementation.

Return the reserved value if the offer was None

Return type: Distribution
Returns: The utility of the given outcome

argrank(outcomes, descending=True)

Ranks the given list of outcomes with weights. None stands for the null outcome.

Return type: list[list[Outcome | None]]
Returns: A list of lists of integers giving the outcome index in the input. The list is sorted by utlity value

argrank_with_weights(outcomes, descending=True)

Ranks the given list of outcomes with weights. None stands for the null outcome.

Returns

an list of integers giving the index in the input array (outcomes) of an outcome (at the given utility level)
- the weight of that outcome
The list is sorted by weights descendingly

Return type

A list of tuples each with two values

best()

Return type: tuple

changes()

Return type: list[PreferencesChange]

checkpoint(path, file_name=None, info=None, exist_ok=False, single_checkpoint=True, step_attribs=('current_step', '_current_step', '_Entity__current_step', '_step'))

Saves a checkpoint of the current object at the given path.

Parameters

path (PathLike) – Full path to a directory to store the checkpoint
file_name (Optional[str]) – Name of the file to dump into. If not given, a unique name is created
info (Optional[dict[str, Any]]) – Information to save with the checkpoint (must be json serializable)
exist_ok (bool) – If true, override existing dump
single_checkpoint (bool) – If true, keep a single checkpoint for the last step
step_attribs (tuple[str, ...]) – Attributes to represent the time-step of the object. Any of the given attributes will be used in the file name generated if single_checkpoint is False. If single_checkpoint is True, the filename will not contain time-step information

Return type

Path

Returns

full path to the file used to save the checkpoint

classmethod checkpoint_info(file_name)

Returns the information associated with a dump of the object saved in the given file

Parameters: file_name (Path | str) – Name of the object

Returns:

Return type: dict[str, Any]

classmethod create(*args, **kwargs): Creates an object and returns a proxy to it.

difference(first, second)

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

Return type: float

difference_prob(first, second)

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

Return type: Distribution

eu(offer)

calculates the expected utility value of the input outcome

Return type: float

eval(offer)

Return type: ScipyDistribution

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

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.

Return type: Value

extreme_outcomes(outcome_space=None, issues=None, outcomes=None, max_cardinality=1000)

Return type: tuple[Outcome, Outcome]

classmethod from_checkpoint(file_name, return_info=False)

Creates an object from a saved checkpoint

Parameters

file_name (Path | str) –
return_info – If True, tbe information saved when the file was dumped are returned

Return type

NamedObject | tuple[NamedObject, dict[str, Any]]

Returns

Either the object or the object and dump-info as a dict (if return_info was true)

Remarks:

If info is returned, it is guaranteed to have the following members:

time: Dump time

type: Type of the dumped object

id: ID

name: name

classmethod from_dict(d)

classmethod from_genius(file_name, **kwargs)

Imports a utility function from a GENIUS XML file.

Parameters: file_name (str) – File name to import from
Return type: Tuple[‘BaseUtilityFunction’ | None, float | None]
Returns: A utility function object (depending on the input file)

Examples

>>> from negmas.preferences import UtilityFunction
>>> import pkg_resources
>>> from negmas.inout import load_genius_domain
>>> domain = load_genius_domain(pkg_resources.resource_filename('negmas'
...                             , resource_name='tests/data/Laptop/Laptop-C-domain.xml'))
>>> u, d = UtilityFunction.from_genius(file_name = pkg_resources.resource_filename('negmas'
...                                      , resource_name='tests/data/Laptop/Laptop-C-prof1.xml')
...                                      , issues=domain.issues)
>>> u.__class__.__name__
'LinearAdditiveUtilityFunction'
>>> u.reserved_value
0.0
>>> d
1.0

Remarks:: See from_xml_str for all the parameters

classmethod from_xml_str(xml_str, issues, safe_parsing=True, ignore_discount=False, ignore_reserved=False, name=None)

Imports a utility function from a GENIUS XML string.

Parameters

xml_str (str) – The string containing GENIUS style XML utility function definition
issues (List[Issue] | None) – Optional issue space to confirm that the utility function is valid
input (product of all issues in the) –
safe_parsing (bool) – Turn on extra checks

Return type

Tuple[‘BaseUtilityFunction’ | None, float | None]

Returns

A utility function object (depending on the input file)

Examples

>>> from negmas.preferences import UtilityFunction
>>> import pkg_resources
>>> from negmas.inout import load_genius_domain
>>> domain = load_genius_domain(pkg_resources.resource_filename('negmas'
...                             , resource_name='tests/data/Laptop/Laptop-C-domain.xml'))
>>> u, _ = UtilityFunction.from_xml_str(open(pkg_resources.resource_filename('negmas'
...                                      , resource_name='tests/data/Laptop/Laptop-C-prof1.xml')
...                                      , 'r').read(), issues=domain.issues)

>>> u, _ = UtilityFunction.from_xml_str(open(pkg_resources.resource_filename('negmas'
...                                      , resource_name='tests/data/Laptop/Laptop-C-prof1.xml')
...                                      , 'r').read(), issues=domain.issues)
>>> assert abs(u(("Dell", "60 Gb", "19'' LCD",)) - 21.987727736172488) < 0.000001
>>> assert abs(u(("HP", "80 Gb", "20'' LCD",)) - 22.68559475583014) < 0.000001

classmethod generate_bilateral(outcomes, conflict_level=0.5, conflict_delta=0.005, scale=0.5)

Generates a couple of utility functions

Parameters

n_outcomes (int) – number of outcomes to use
conflict_level (float) – How conflicting are the two ufuns to generate. 1.0 means maximum conflict.
conflict_delta – How variable is the conflict at different outcomes.

Examples

>>> from negmas.preferences import UtilityFunction
>>> from negmas.preferences import conflict_level
>>> u1, u2 = UtilityFunction.generate_bilateral(outcomes=10, conflict_level=0.0
...                                             , conflict_delta=0.0)
>>> print(conflict_level(u1, u2, outcomes=10))
0.0

>>> u1, u2 = UtilityFunction.generate_bilateral(outcomes=10, conflict_level=1.0
...                                             , conflict_delta=0.0)
>>> print(conflict_level(u1, u2, outcomes=10))
1.0

>>> u1, u2 = UtilityFunction.generate_bilateral(outcomes=10, conflict_level=0.5
...                                             , conflict_delta=0.0)
>>> 0.0 < conflict_level(u1, u2, outcomes=10) < 1.0
True

Return type: Tuple[‘ProbUtilityFunction’, ‘ProbUtilityFunction’]

classmethod generate_random(n, outcomes, normalized=True, scale=0.5)

Generates N mapping utility functions

Parameters

n (int) – number of utility functions to generate
outcomes (Union[int, List[Outcome]]) – number of outcomes to use
normalized (bool) – if true, the resulting ufuns will be normlized between zero and one.

Return type

List[‘ProbUtilityFunction’]

classmethod generate_random_bilateral(outcomes, scale=0.5)

Generates a couple of utility functions

Parameters

n_outcomes (int) – number of outcomes to use
conflict_level – How conflicting are the two ufuns to generate. 1.0 means maximum conflict.
conflict_delta – How variable is the conflict at different outcomes.
zero_summness – How zero-sum like are the two ufuns.

Return type

Tuple[ProbUtilityFunction, ProbUtilityFunction]

invert(inverter=None)

Inverts the ufun, initializes it and caches the result.

Return type: InverseUFun

is_better(first, second)

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

Parameters

first (Outcome | None) – First outcome to be compared
second (Outcome | None) – Second outcome to be compared

Remarks:

Should raise ValueError if the comparison cannot be done

Return type: bool

is_equivalent(first, second)

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

Parameters

first (Outcome | None) – First outcome to be compared
second (Outcome | None) – Second outcome to be compared

Remarks:

Should raise ValueError if the comparison cannot be done

Return type: bool

is_not_better(first, second)

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

Parameters

first (Outcome) – First outcome to be compared
second (Outcome | None) – Second outcome to be compared

Remarks:

Should raise ValueError if the comparison cannot be done

Return type: bool

is_not_worse(first, second)

Is first at least as good as second

Return type: bool

is_session_dependent()

Does the utiltiy of an outcome depend on the NegotiatorMechanismInterface?

Return type: bool

is_state_dependent()

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

Return type: bool

is_stationary()

Are the preferences stationary (i.e. repeated calls return the same value for any preferences comparion or evaluaton method)?

Return type: bool

is_volatile()

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

Return type: bool

is_worse(first, second)

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

Parameters

first (Outcome | None) – First outcome to be compared
second (Outcome | None) – Second outcome to be compared

Remarks:

Should raise ValueError if the comparison cannot be done

Return type: bool

max()

Return type: Union[Distribution, float]

min()

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[Outcome] | 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

normalize(to=(0.0, 1.0), minmax=None, **kwargs)

Return type: T

normalize_for(to=(0.0, 1.0), outcome_space=None, issues=None, outcomes=None, minmax=None, **kwargs)

Return type: T

rank(outcomes, descending=True)

Ranks the given list of outcomes with weights. None stands for the null outcome.

Return type: list[list[Outcome | None]]
Returns: A list of lists of integers giving the outcome index in the input. The list is sorted by utlity value

rank_with_weights(outcomes, descending=True)

Ranks the given list of outcomes with weights. None stands for the null outcome.

Returns

an list of integers giving the index in the input array (outcomes) of an outcome (at the given utility level)
- the weight of that outcome
The list is sorted by weights descendingly

Return type

A list of tuples each with two values

sample_outcome_with_utility(rng, outcome_space=None, issues=None, outcomes=None, n_trials=100)

Samples an outcome in the given utiltity range or return None if not possible

Parameters

rng (Tuple[float, float]) – rng
outcome_space (OutcomeSpace | None) – outcome_space
issues (List[Issue] | None) – issues
outcomes (List[Outcome] | None) – outcomes
n_trials (int) – n_trials

Return type

Optional[“Outcome”]

scale_by(scale, scale_reserved=True)

Return type: WeightedUtilityFunction | T

scale_max(to, rng=None)

Return type: T

scale_max_for(to, outcome_space=None, issues=None, outcomes=None, rng=None)

Return type: T

scale_min(to, rng=None)

Return type: T

scale_min_for(to, outcome_space=None, issues=None, outcomes=None, rng=None)

Return type: T

shift_by(offset, shift_reserved=True)

Return type: WeightedUtilityFunction | T

shift_max_for(to, outcome_space=None, issues=None, outcomes=None, rng=None)

Return type: T

shift_min_for(to, outcome_space=None, issues=None, outcomes=None, rng=None)

Return type: T

classmethod spawn(spawn_as='object', spawn_params=None, *args, **kwargs)

classmethod spawn_object(*args, **kwargs)

to_crisp()

Return type: UtilityFunction

to_dict()

Return type: dict[str, Any]

to_genius(file_name, issues=None, **kwargs)

Exports a utility function to a GENIUS XML file.

Parameters

file_name (str) – File name to export to
u – utility function
issues (Iterable[Issue]) – The issues being considered as defined in the domain

Returns

None

Examples

>>> from negmas.preferences import UtilityFunction
>>> from negmas.inout import load_genius_domain
>>> import pkg_resources
>>> domain = load_genius_domain(domain_file_name=pkg_resources.resource_filename('negmas'
...                                             , resource_name='tests/data/Laptop/Laptop-C-domain.xml'))
>>> u, d = UtilityFunction.from_genius(file_name=pkg_resources.resource_filename('negmas'
...                                             , resource_name='tests/data/Laptop/Laptop-C-prof1.xml')
...                                             , issues=domain.issues)
>>> u.to_genius(discount_factor=d
...     , file_name = pkg_resources.resource_filename('negmas'
...                   , resource_name='tests/data/LaptopConv/Laptop-C-prof1.xml')
...     , issues=domain.issues)

Remarks:: See to_xml_str for all the parameters

to_prob()

Return type: ProbUtilityFunction

to_stationary()

to_xml_str(issues=None, discount_factor=None)

Exports a utility function to a well formatted string

Return type: str

worst()

Return type: tuple