FrequencyLinearUFunModel
- class negmas.sao.FrequencyLinearUFunModel(*, negotiator=None)[source]
Bases:
negmas.sao.components.models.ufun.UFunModel
A
PartnerUfunModel
that uses a simple frequency-based model of the opponent offers assuming the ufun isLinearAdditiveUtilityFunction
.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).
- rtype
- rtype
Returns the utility_function type.
- rtype
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
can_join
(nmi, state, *[, preferences, ufun, ...])A call back called before joining a negotiation to confirm that we can join it.
changes
()- rtype
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
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 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 utiltiy of an outcome depend on the
NegotiatorMechanismInterface
?Does the utiltiy of an outcome depend on the negotiation state?
Are the preferences stationary (i.e.
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 secondmax
()- rtype
min
()- rtype
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
to_dict
()to_genius
(file_name[, issues])Exports a utility function to a GENIUS XML file.
to_prob
()- rtype
- rtype
TypeVar
(T
, bound=BaseUtilityFunction
)
to_xml_str
([issues, discount_factor])Exports a utility function to a well formatted string
worst
()- rtype
Attributes Documentation
- base_type
Returns the utility_function base type ignoring discounting and similar wrappings.
- Return type
- id
The unique ID of this entity
- name
A convenient name of the entity (intended primarily for printing/logging/debugging).
- negotiator
- reserved_distribution
- Return type
- 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
- 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.
- 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
- 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()
- Return type
- 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 (
Optional
[str
]) – Name of the file to dump into. If not given, a unique name is createdinfo (
Optional
[dict
[str
,Any
]]) – 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
- Parameters
file_name (Path | str) – Name of the object
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
- eval_normalized(offer, above_reserve=True, expected_limits=True)
Evaluates the ufun normalizing the result between zero and one
- Parameters
- 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
- 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
- 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
- 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
- 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
- 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
- is_session_dependent()
Does the utiltiy of an outcome depend on the
NegotiatorMechanismInterface
?- Return type
- is_state_dependent()
Does the utiltiy 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 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
- 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
- max()
- Return type
- min()
- Return type
- 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
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
- 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 proposedoffer (
tuple
) – The proposal.
- Remarks:
Will only be called if
enable_callbacks
is set for the mechanism
- Return type
- 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
- 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.
- 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 (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
- 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
- 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
- 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
TypeVar
(T
, bound=BaseUtilityFunction
)
- to_xml_str(issues=None, discount_factor=None)
Exports a utility function to a well formatted string
- Return type