UFunModel

class negmas.sao.UFunModel(*, negotiator=None)[source]

Bases: negmas.sao.components.base.SAOComponent, negmas.preferences.base_ufun.BaseUtilityFunction

A SAOComponent that can model the opponent’s utility function.

Classes implementing this ufun-model, must implement the abstract eval() method to return the utility value of an outcome. They can use any callbacks available to SAOComponent to update the model.

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).
`negotiator`
`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 at the given negotiation state.
`after_join`(nmi)	A call back called after joining a negotiation to confirm wwe joined.
`after_proposing`(state, offer)	Called after proposing
`after_responding`(state, offer, response)	Called before offering
`argrank`(outcomes[, descending])	Ranks the given list of outcomes with weights.
`argrank_with_weights`(outcomes[, descending])	Ranks the given list of outcomes with weights.
`before_proposing`(state)	Called before proposing
`before_responding`(state, offer)	Called before offering
`best`()	rtype `tuple`
`can_join`(nmi, state, *[, preferences, ufun, ...])	A call back called before joining a negotiation to confirm that we can join it.
`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 `Union`[`Distribution`, `float`]
`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.
`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
`on_leave`(state)	A call back called after leaving a negotiation.
`on_mechanism_error`(state)	A call back called whenever an error happens in the mechanism.
`on_negotiation_end`(state)	A call back called at each negotiation end
`on_negotiation_start`(state)	A call back called at each negotiation start
`on_partner_ended`(partner)	Called when a partner ends the negotiation.
`on_partner_joined`(partner)	Called when a partner joins the negotiation.
`on_partner_left`(partner)	Called when a partner leaves the negotiation.
`on_partner_proposal`(state, partner_id, offer)	A callback called by the mechanism when a partner proposes something
`on_partner_refused_to_propose`(state, partner_id)	A callback called by the mechanism when a partner refuses to propose
`on_partner_response`(state, partner_id, ...)	A callback called by the mechanism when a partner responds to some offer
`on_preferences_changed`(changes)	Called to inform the component that the ufun has changed and the kinds of change that happened.
`on_round_end`(state)	A call back called at each negotiation round end
`on_round_start`(state)	A call back called at each negotiation round start
`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
`set_negotiator`(negotiator)	Sets the negotiator of which this component is a part.
`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`()	rtype `TypeVar`(`T`, bound= `BaseUtilityFunction`)
`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).

negotiator

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 at the given negotiation state.

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: Value
Returns: The utility of the given outcome

after_join(nmi)

A call back called after joining a negotiation to confirm wwe joined.

Return type: None

after_proposing(state, offer): Called after proposing

after_responding(state, offer, response): Called before offering

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

before_proposing(state): Called before proposing

before_responding(state, offer): Called before offering

best()

Return type: tuple

can_join(nmi, state, *, preferences=None, ufun=None, role='negotiator')

A call back called before joining a negotiation to confirm that we can join it.

Return type: bool

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

abstract eval(offer)

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

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

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

on_leave(state)

A call back called after leaving a negotiation.

Return type: None

on_mechanism_error(state)

A call back called whenever an error happens in the mechanism. The error and its explanation are accessible in state

Return type: None

on_negotiation_end(state)

A call back called at each negotiation end

Return type: None

on_negotiation_start(state)

A call back called at each negotiation start

Return type: None

on_partner_ended(partner)

Called when a partner ends the negotiation.

Note that the negotiator owning this component may never receive this offer. This is only receivd if the mechanism is sending notifications on every offer.

on_partner_joined(partner)

Called when a partner joins the negotiation.

This is only receivd if the mechanism is sending notifications.

on_partner_left(partner)

Called when a partner leaves the negotiation.

This is only receivd if the mechanism is sending notifications.

on_partner_proposal(state, partner_id, offer)

A callback called by the mechanism when a partner proposes something

Parameters

state (SAOState) – MechanismState giving the state of the negotiation when the offer was porposed.
partner_id (str) – The ID of the agent who proposed
offer (tuple) – The proposal.

Remarks:

Will only be called if enable_callbacks is set for the mechanism

Return type: None

on_partner_refused_to_propose(state, partner_id)

A callback called by the mechanism when a partner refuses to propose

Parameters

state (SAOState) – MechanismState giving the state of the negotiation when the partner refused to offer.
partner_id (str) – The ID of the agent who refused to propose

Remarks:

Will only be called if enable_callbacks is set for the mechanism

Return type: None

on_partner_response(state, partner_id, outcome, response)

A callback called by the mechanism when a partner responds to some offer

Parameters

state (SAOState) – MechanismState giving the state of the negotiation when the partner responded.
partner_id (str) – The ID of the agent who responded
outcome (Outcome | None) – The proposal being responded to.
response (ResponseType) – The response

Remarks:

Will only be called if enable_callbacks is set for the mechanism

Return type: None

on_preferences_changed(changes): Called to inform the component that the ufun has changed and the kinds of change that happened.

on_round_end(state)

A call back called at each negotiation round end

Return type: None

on_round_start(state)

A call back called at each negotiation round start

Return type: None

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

set_negotiator(negotiator)

Sets the negotiator of which this component is a part.

Return type: None

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

Return type: TypeVar(T, bound= BaseUtilityFunction)

to_xml_str(issues=None, discount_factor=None)

Exports a utility function to a well formatted string

Return type: str

worst()

Return type: tuple