ExpDiscountedUFun

class negmas.preferences.ExpDiscountedUFun(ufun, discount=None, factor='step', name=None, reserved_value=-inf, dynamic_reservation=True, id=None, **kwargs)[source]

Bases: DiscountedUtilityFunction

A discounted utility function based on some factor of the negotiation

Parameters:

ufun (BaseUtilityFunction) – The utility function that is being discounted
discount (float | None) – discount factor
factor (callable -> must receive a mechanism info object and returns a float representing the) – str -> The name of the AgentMechanismInterface variable based on which discounting operate
factor

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`
`short_type_name`
`type`	Returns the utility_function type.
`type_name`
`uuid`	The unique ID of this entity

Methods Summary

`__call__`(offer)	Calculate the utility for a given outcome at the given negotiation state.
`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`()	Returns a list of changes to the preferences (if any) since last call.
`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: `Distribution`
`eval_normalized`(offer[, above_reserve, ...])	Evaluates the ufun normalizing the result between zero and one
`eval_on_state`(offer[, nmi, state])	Evaluates the offer given a session and state
`extreme_outcomes`([outcome_space, issues, ...])	rtype: `tuple`[`tuple`, `tuple`]
`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_geniusweb`(file_name, **kwargs)	Imports a utility function from a GeniusWeb json file.
`from_geniusweb_json_str`(json_str[, ...])	Imports a utility function from a GeniusWeb JSON string.
`from_xml_str`(xml_str, issues[, ...])	Imports a utility function from a GENIUS XML string.
`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. repeated calls return the same value for any preferences comparion or evaluaton method)?.
`is_volatile`()	Does the utility 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, normalize_weights])	rtype: `Union`[`TypeVar`(`T`, bound= BaseUtilityFunction), `ConstUtilityFunction`]
`normalize_for`([to, outcome_space])	rtype: `Union`[`TypeVar`(`T`, bound= BaseUtilityFunction), `ConstUtilityFunction`]
`random`(issues[, reserved_value, normalized, ...])	Generates a random ufun of the given type
`rank`(outcomes[, descending])	Ranks the given list of outcomes with weights.
`rank_with_weights`(outcomes[, descending])	Ranks the given list of outcomes with weights.
`reset_changes`()	Will be called whenever we need to reset changes.
`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: `ExpDiscountedUFun`
`scale_max`(to[, rng])	rtype: `TypeVar`(`T`, bound= BaseUtilityFunction)
`scale_max_for`(to[, outcome_space, issues, ...])	rtype: `TypeVar`(`T`, bound= BaseUtilityFunction)
`scale_min`(to[, rng])	rtype: `TypeVar`(`T`, bound= BaseUtilityFunction)
`scale_min_for`(to[, outcome_space, issues, ...])	rtype: `TypeVar`(`T`, bound= BaseUtilityFunction)
`set_id`(id)	Sets the unique ID of this entity
`shift_by`(offset[, shift_reserved])	rtype: `ExpDiscountedUFun`
`shift_max_for`(to[, outcome_space, issues, ...])	rtype: `TypeVar`(`T`, bound= BaseUtilityFunction)
`shift_min_for`(to[, outcome_space, issues, ...])	rtype: `TypeVar`(`T`, bound= BaseUtilityFunction)
`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`
`xml`(issues)	rtype: `str`

Attributes Documentation

base_type

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

short_type_name

type

type_name

uuid: The unique ID of this entity

Methods Documentation

__call__(offer)

Calculate the utility for a given outcome at the given negotiation state.

Parameters:: offer (tuple | 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:: Union[Distribution, float]
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[tuple | 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()

Returns a list of changes to the preferences (if any) since last call.

Return type:: list[PreferencesChange]

Remarks:

If the ufun is stationary, the return list will always be empty.
If the ufun is not stationary, the ufun itself is responsible for saving the changes in _changes whenever they happen.

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 (str | None) – Name of the file to dump into. If not given, a unique name is created
info (dict[str, Any] | None) – 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
Return type:: dict[str, Any]

Returns:

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:: Distribution

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.

eval_on_state(offer, nmi=None, state=None)[source]: Evaluates the offer given a session and state

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

Return type:: tuple[tuple, tuple]

classmethod from_checkpoint(file_name, return_info=False)

Creates an object from a saved checkpoint

Parameters:

file_name (Path | str)
return_info (bool) – 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)[source]

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_geniusweb(file_name, **kwargs)

Imports a utility function from a GeniusWeb json 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)

Remarks:: See from_geniusweb_json_str for all the parameters

classmethod from_geniusweb_json_str(json_str, safe_parsing=True, issues=None, ignore_discount=False, ignore_reserved=False, use_reserved_outcome=False, name=None)

Imports a utility function from a GeniusWeb JSON string.

Parameters:

json_str (str) – The string containing GENIUS style XML utility function definition
issues (Sequence[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)

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 (Sequence[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"
...     )
... )
>>> with open(
...     pkg_resources.resource_filename(
...         "negmas", resource_name="tests/data/Laptop/Laptop-C-prof1.xml"
...     ),
...     "r",
... ) as ff:
...     u, _ = UtilityFunction.from_xml_str(ff.read(), issues=domain.issues)
>>> with open(
...     pkg_resources.resource_filename(
...         "negmas", resource_name="tests/data/Laptop/Laptop-C-prof1.xml"
...     ),
...     "r",
... ) as ff:
...     u, _ = UtilityFunction.from_xml_str(ff.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

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 (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

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

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 | 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

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?

is_state_dependent(): Does the utiltiy of an outcome depend on the negotiation state?

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 utility 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

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()

Return type:: Union[Distribution, float]

min()

Return type:: Union[Distribution, float]

minmax(outcome_space=None, issues=None, outcomes=None, max_cardinality=10000, above_reserve=False)[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.

Return type:

tuple[float, float]

Returns:

(lowest, highest) utilities in that order

normalize(to=(0.0, 1.0), normalize_weights=False)

Return type:: Union[TypeVar(T, bound= BaseUtilityFunction), ConstUtilityFunction]

normalize_for(to=(0.0, 1.0), outcome_space=None)

Return type:: Union[TypeVar(T, bound= BaseUtilityFunction), ConstUtilityFunction]

classmethod random(issues, reserved_value=(0.0, 1.0), normalized=True, discount_range=(0.8, 1.0), base_preferences_type='negmas.LinearAdditiveUtilityFunction', **kwargs)[source]

Generates a random ufun of the given type

Return type:: ExpDiscountedUFun

rank(outcomes, descending=True)

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

Return type:: list[list[tuple | 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

reset_changes()

Will be called whenever we need to reset changes.

Return type:: None

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 (Sequence[Issue] | None) – issues
outcomes (Sequence[Outcome] | None) – outcomes
n_trials (int) – n_trials

Return type:

Optional[“Outcome”]

scale_by(scale, scale_reserved=True)[source]

Return type:: ExpDiscountedUFun

scale_max(to, rng=None)

Return type:: TypeVar(T, bound= BaseUtilityFunction)

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

Return type:: TypeVar(T, bound= BaseUtilityFunction)

scale_min(to, rng=None)

Return type:: TypeVar(T, bound= BaseUtilityFunction)

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

Return type:: TypeVar(T, bound= BaseUtilityFunction)

set_id(id): Sets the unique ID of this entity

shift_by(offset, shift_reserved=True)[source]

Return type:: ExpDiscountedUFun

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

Return type:: TypeVar(T, bound= BaseUtilityFunction)

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

Return type:: TypeVar(T, bound= BaseUtilityFunction)

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

classmethod spawn_object(*args, **kwargs)

to_crisp()

Return type:: UtilityFunction

to_dict()[source]

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 (Optional[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

xml(issues)[source]

Return type:: str