ZeroSumModel
- class negmas.sao.ZeroSumModel(above_reserve=True, rank_only=False, *, negotiator=None)[source]
Bases:
StationaryMixin
,UFunModel
Assumes a zero-sum negotiation (i.e. $u_o$ = $-u_s$ )
Remarks:
Because some negotiators do not work well with negative ufun values, we return (max - u(w)) instead of (- u(w))
Attributes Summary
Returns the utility_function base type ignoring discounting and similar wrappings.
The unique ID of this entity
A convenient name of the entity (intended primarily for printing/logging/debugging).
Returns the utility_function type.
The unique ID of this entity
Methods Summary
__call__
(offer)Calculate the utility 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[, source])Called before offering
best
()- rtype:
can_join
(nmi, state, *[, preferences, ufun, ...])A call back called before joining a negotiation to confirm that we can join it.
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)eval_normalized
(offer[, above_reserve, ...])Evaluates the ufun normalizing the result between zero and one
extreme_outcomes
([outcome_space, issues, ...])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 secondis_equivalent
(first, second)Compares two offers using the
ufun
returning whether the first is strictly equivelent than the secondis_not_better
(first, second)Compares two offers using the
ufun
returning whether the first is worse or equivalent than the secondis_not_worse
(first, second)Is
first
at least as good assecond
Does the utility of an outcome depend on the
NegotiatorMechanismInterface
?Does the utility of an outcome depend on the negotiation state?
Are the preferences stationary (i.e. repeated calls return the same value for any preferences comparion or evaluaton method)?.
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 secondmax
()min
()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
]
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.
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:
Union
[WeightedUtilityFunction
,TypeVar
(T
, bound= BaseUtilityFunction)]
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
set_negotiator
(negotiator)Sets the negotiator of which this component is a part.
shift_by
(offset[, shift_reserved])- rtype:
Union
[WeightedUtilityFunction
,TypeVar
(T
, bound= BaseUtilityFunction)]
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:
to_dict
()to_genius
(file_name[, issues])Exports a utility function to a GENIUS XML file.
to_prob
()- rtype:
- rtype:
to_xml_str
([issues, discount_factor])Exports a utility function to a well formatted string
worst
()- rtype:
Attributes Documentation
- above_reserve: bool
- 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: Rational | None = None
- rank_only: bool
- reserved_distribution
- short_type_name
- 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:
- 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.
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
- after_join(nmi)
A call back called after joining a negotiation to confirm wwe joined.
- Return type:
- after_proposing(state, offer)
Called after proposing
- after_responding(state, offer, response, source=None)
Called before offering
- argrank(outcomes, descending=True)
Ranks the given list of outcomes with weights. None stands for the null outcome.
- 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, source=None)
Called before offering
- 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:
- changes()
Returns a list of changes to the preferences (if any) since last call.
- Return type:
- 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 checkpointfile_name (
str
|None
) – Name of the file to dump into. If not given, a unique name is createdinfo (
dict
[str
,Any
] |None
) – Information to save with the checkpoint (must be json serializable)exist_ok (
bool
) – If true, override existing dumpsingle_checkpoint (
bool
) – If true, keep a single checkpoint for the last stepstep_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:
- 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
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:
- difference_prob(first, second)
Returns a numeric difference between the utility of the two given outcomes
- Return type:
Distribution
- eval_normalized(offer, above_reserve=True, expected_limits=True)[source]
Evaluates the ufun normalizing the result between zero and one
- Parameters:
- Return type:
- 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.
- extreme_outcomes(outcome_space=None, issues=None, outcomes=None, max_cardinality=100000)
- classmethod from_checkpoint(file_name, return_info=False)
Creates an object from a saved checkpoint
- Parameters:
- Return type:
- 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_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:
- 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:
- 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:
- is_better(first, second)
Compares two offers using the
ufun
returning whether the first is strictly better than the second- Parameters:
- Return type:
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:
- Return type:
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:
- Return type:
Remarks:
Should raise
ValueError
if the comparison cannot be done
- is_session_dependent()
Does the utility of an outcome depend on the
NegotiatorMechanismInterface
?- Return type:
- is_state_dependent()
Does the utility of an outcome depend on the negotiation state?
- Return type:
- is_stationary()
Are the preferences stationary (i.e. repeated calls return the same value for any preferences comparion or evaluaton method)?
- Return type:
- is_volatile()
Does the utility of an outcome depend on factors outside the negotiation?
- Return type:
- 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:
- Return type:
Remarks:
Should raise
ValueError
if the comparison cannot be done
- 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 (
Optional
[Sequence
[Issue
]]) – List of issues (optional)outcomes (
Optional
[Sequence
[tuple
]]) – 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:
- 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
]
- 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:
- 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 (
GBState
) –MechanismState
giving the state of the negotiation when the offer was porposed.partner_id (
str
) – The ID of the agent who proposedoffer (
tuple
) – The proposal.
- Return type:
- Remarks:
Will only be called if
enable_callbacks
is set for the mechanism
- on_partner_refused_to_propose(state, partner_id)
A callback called by the mechanism when a partner refuses to propose
- Parameters:
state (
GBState
) –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
- Return type:
- Remarks:
Will only be called if
enable_callbacks
is set for the mechanism
- on_partner_response(state, partner_id, outcome, response)
A callback called by the mechanism when a partner responds to some offer
- Parameters:
state (
GBState
) –MechanismState
giving the state of the negotiation when the partner responded.partner_id (
str
) – The ID of the agent who respondedresponse (
ResponseType
) – The response
- Return type:
- Remarks:
Will only be called if
enable_callbacks
is set for the mechanism
- on_preferences_changed(changes)[source]
Called to inform the component that the ufun has changed and the kinds of change that happened.
- rank(outcomes, descending=True)
Ranks the given list of outcomes with weights. None stands for the null outcome.
- 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:
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)
- Return type:
Union
[WeightedUtilityFunction
,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_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
- set_negotiator(negotiator)
Sets the negotiator of which this component is a part.
- Return type:
- shift_by(offset, shift_reserved=True)
- Return type:
Union
[WeightedUtilityFunction
,TypeVar
(T
, bound= BaseUtilityFunction)]
- 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:
- to_genius(file_name, issues=None, **kwargs)
Exports a utility function to a GENIUS XML file.
- Parameters:
- 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:
- to_stationary()
- Return type:
- to_xml_str(issues=None, discount_factor=None)
Exports a utility function to a well formatted string
- Return type: