MeanElicitor
- class negmas.elicitation.MeanElicitor(strategy, user, **kwargs)[source]
Bases:
OptimalIncrementalElicitor
Same as
OptimalIncrementalElicitor
usingMeanExpector
for estimating utilitiesAttributes Summary
Returns the private information (annotation) not shared with other negotiators
Agent capabilities
Returns the preferences if it is a CrispUtilityFunction else None
The total elicitation cost.
The total elicitation time in seconds.
Does the entity has an associated ufun?
Does the entity has an associated ufun?
Does the entity has an associated ufun?
The unique ID of this entity
A convenient name of the entity (intended primarily for printing/logging/debugging).
Returns the owner agent of the negotiator
Returns the parent controller
The utility function attached to that object
Returns the private information (annotation) not shared with other negotiators
Returns the preferences if it is a ProbUtilityFunction else None
Reserved outcome is the outcome that will be realized by default for this agent.
Reserved value is what the entity gets if no agreement is reached in the negotiation.
Returns the preferences if it is a
BaseUtilityFunction
else NoneThe unique ID of this entity
Methods Summary
__call__
(state)Called by
Negotiator.__call__
(which is called by the mechanism) to counter the offer.accuracy_limit
(cost)The accuracy limit given the cost and
epsilon
.add_capabilities
(capabilities)Adds named capabilities to the negotiator.
add_handler
(notification_type, callback)Adds a notification handler to the list of handlers of the given type.
before_death
(cntxt)Called whenever the parent is about to kill this negotiator.
Called before starting elicitation at every negotiation round.
best_offer
(state)The outcome with maximum expected utility given the expector and its utility
Checks whether there are any unknowns in the unknowns list.
cancel
([reason])A method that may be called by a mechanism to make the negotiator cancel whatever it is currently processing.
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.
do_elicit
(outcome, state)Does a real elicitation step.
elicit
(state)Called to do utility elicitation whenever needed.
elicit_single
(state)Does a single elicitation act
from_checkpoint
(file_name[, return_info])Creates an object from a saved checkpoint
handlers
(notification_type)Gets the list of handlers registered for some notification type.
init_elicitation
(preferences, **kwargs)Initializes the elicitation process (called only once).
Initializes the unknowns list which is a list of Tuples [-u(o), o] for o in outcomes.
is_acceptable_as_agreement
(outcome)Whether the given outcome is acceptable as a final agreement of a negotiation.
isin
(negotiation_id)Is that agent participating in the given negotiation? Tests if the agent is participating in the given negotiation.
join
(nmi, state, *[, preferences, role])Called to join a negotiation.
Maximum utility that could even in principle be attained which simply means the utility value of the outcome with maximum utility.
Minimum utility that could even in principle be attained which simply means the utility value of the outcome with minimum utility.
Returns the maximum estimaged utility and the corresponding outocme
offering_utilities
(state)Calculates the offering utility for all outcomes
offering_utility
(outcome, state)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)Called when the negotiation starts.
on_notification
(notification, notifier)Called whenever a notification is received
on_notification_
(notification, notifier)Called when a notification is received.
on_opponent_model_updated
(outcomes, old, new)Called when the opponent model is updated.
on_partner_ended
(partner)Called when a partner ends the negotiation.
on_partner_proposal
(state, partner_id, offer)Called when one of the partners propose (only if enable_callbacks is set in the
SAOMechanism
).on_partner_response
(state, partner_id, ...)Called when one of the partners respond (only if enable_callbacks is set in the
SAOMechanism
).on_preferences_changed
(changes)Called to inform the entity that its ufun has changed.
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
propose
(state)Called to propose an outcome
propose_
(state)The method directly called by the mechanism (through
counter
) to ask for a proposalRemoves the best offer from the unkonwn list and returns it.
remove_capability
(name)Removes named capability from the negotiator
remove_handler
(notification_type, callback)Removes a notification handler from the list of handlers of the given type.
respond
(state[, source])Called to respond to an offer.
respond_
(state, offer)Called by the mechanism directly (through
counter
) to respond to offers.set_id
(id)Sets the unique ID of this entity
set_preferences
(value[, force])Sets the utility function/Preferences.
spawn
([spawn_as, spawn_params])spawn_object
(*args, **kwargs)update_best_offer_utility
(outcome, u)We need not do anything here as we will remove the outcome anyway to the known list
Updates the cutoff utility under which no elicitation is done.
user_preferences
(outcome)Finds the total utility obtained by the user for this outcome after discounting elicitation cost.
utilities_on_rejection
(state)Finds the utility of rejection for all outputs.
utility_at
(x)Returns a
Distribution
for every outcomeutility_on_acceptance
(outcome)The utility of acceptance which is simply the utility function applied to
outcome
.utility_on_rejection
(outcome, state)Uses the aspiration level as the utility of rejection.
z_index
([updated_outcomes])Update the internal z-index or create it if needed.
Attributes Documentation
- ami
- annotation
Returns the private information (annotation) not shared with other negotiators
- capabilities
Agent capabilities
- crisp_ufun
Returns the preferences if it is a CrispUtilityFunction else None
- elicitation_cost
The total elicitation cost.
- elicitation_time
The total elicitation time in seconds.
- has_cardinal_preferences
Does the entity has an associated ufun?
- has_preferences
Does the entity has an associated ufun?
- has_ufun
Does the entity has an associated ufun?
- id
The unique ID of this entity
- name
A convenient name of the entity (intended primarily for printing/logging/debugging).
- nmi
- opponent_ufun
- owner
Returns the owner agent of the negotiator
- parent
Returns the parent controller
- preferences
The utility function attached to that object
- private_info
Returns the private information (annotation) not shared with other negotiators
- prob_ufun
Returns the preferences if it is a ProbUtilityFunction else None
- reserved_outcome
Reserved outcome is the outcome that will be realized by default for this agent.
Remarks:
Reserved outcomes are defined for
OrdinalPreferences
.
See also
- reserved_value
Reserved value is what the entity gets if no agreement is reached in the negotiation.
The reserved value can either be explicity defined for the ufun or it can be the output of the ufun for
None
outcome.
- short_type_name
- type_name
- ufun
Returns the preferences if it is a
BaseUtilityFunction
else None
- uuid
The unique ID of this entity
Methods Documentation
- __call__(state)
Called by
Negotiator.__call__
(which is called by the mechanism) to counter the offer. It just callsrespond_
andpropose_
as needed.- Parameters:
state (
SAOState
) –SAOState
giving current state of the negotiation.- Returns:
The response to the given offer with a counter offer if the response is REJECT
- Return type:
Tuple[ResponseType, Outcome]
- Remarks:
The current offer is accessible through state.current_offer
- add_capabilities(capabilities)
Adds named capabilities to the negotiator.
- Parameters:
capabilities (
dict
) – The capabilities to be added as a dict- Return type:
- Returns:
None
- Remarks:
It is the responsibility of the caller to be really capable of added capabilities.
- add_handler(notification_type, callback)
Adds a notification handler to the list of handlers of the given type. These handlers will be called in the order in which they are received
- Parameters:
notification_type (
str
) – Notification type as specificed in the type member of the Notification classcallback (
Callable
[[Notification
,str
],bool
]) – The callback which must receive a Notification object and a string and returns a boolean. If True is returned from one callback, the remaining callbacks will not be called
Returns:
- before_death(cntxt)
Called whenever the parent is about to kill this negotiator.
It should return False if the negotiator does not want to be killed but the controller can still force-kill it
- Return type:
- before_eliciting()
Called before starting elicitation at every negotiation round.
- Remarks:
It just updates cutoff utility
- best_offer(state)
The outcome with maximum expected utility given the expector and its utility
- Parameters:
state (
MechanismState
) – The mechanism state- Return type:
- Returns:
A tuple containing the best outcome (or None) and its expected utility using the expector (or reserved value)
- Remarks:
if there are no offerable outcomes, elicitation is done and if still there are no offerable outcomes, the reserved value is returned (with None as outcome)
Only offerable outcomes are checked.
The best outcome is defined as the one with maximum
expect
applied tooffering_utility
.
- cancel(reason=None)
A method that may be called by a mechanism to make the negotiator cancel whatever it is currently processing.
Negotiators can just ignore this message (default behavior) but if there is a way to actually cancel work, it should be implemented here to improve the responsiveness of the negotiator.
- 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 (
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.
- do_elicit(outcome, state)
Does a real elicitation step.
- Parameters:
outcome (
tuple
) – The outcome to elicitstate (
MechanismState
) – The state at which elicitation is happening
- Remarks:
If
deep_elicitation
is set, the strategy is applied until the uncertainty in the utility value foroutcome
is less than the accuracty limit otherwise, apply it once.
- elicit(state)
Called to do utility elicitation whenever needed.
- Parameters:
state (
MechanismState
) – mechanism state- Return type:
- Remarks:
Keeps track of elicitation time and asking time.
If the maximum attainable utility minus elicitation cost is less than the reserved value, no elicitation will take place because we will end this negotiation anyway. Note that the maximum attainable utility can never go up.
Calls
before_eliciting
once to initialize the process then callselicit_single
which does the actual elicitation. This is done only once ifsingle_elicitation
is set, otherwise it is repeated until one of the following conditiosn is met:elicit_single
returns FalseThe maximum attainable utility (minus elicitation cost) is less than the reserved value.
- elicit_single(state)
Does a single elicitation act
- Parameters:
state (
MechanismState
) – mechanism state
- Remarks:
The process goes as follows:
Find the offer to elicit using
offer_to_elicit
.If the utility of that offer is less than the cutoff utility, or the best offer to elicit is
None
, stop eliciting and return.call
do_elicit
once.update the distribution of the elicited outcome
add the elicited outcome to the offerable outcomes
If the utility of the best outcome is a number, remove it from the unknown outcomes list otherwise jsut update it
Update the cutoff utility and elicitation history.
- 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
- handlers(notification_type)
Gets the list of handlers registered for some notification type. This list can be modified in place to change the order of handlers for example. It is NOT a copy.
- Return type:
list
[Callable
[[Notification
,str
],bool
]]
- init_elicitation(preferences, **kwargs)
Initializes the elicitation process (called only once).
Remarks:
After calling the parent’s
init_elicitation
, this method callsinit_unknowns
to initialize the unknown list.
- init_unknowns()
Initializes the unknowns list which is a list of Tuples [-u(o), o] for o in outcomes.
- is_acceptable_as_agreement(outcome)
Whether the given outcome is acceptable as a final agreement of a negotiation.
The default behavior is to reject only if a reserved value is defined for the agent and is known to be higher than the utility of the outcome.
- Return type:
- isin(negotiation_id)
Is that agent participating in the given negotiation? Tests if the agent is participating in the given negotiation.
- join(nmi, state, *, preferences=None, role='negotiator', **kwargs)
Called to join a negotiation.
- Return type:
- Remarks:
uses the base_negotiator to join the negotiation.
creates a
MappingUtilityFunction
that maps every outcome to the result of the expector applied to the corresponding utility value.The reserved value of the created ufun is set to -inf
- maximum_attainable_utility()
Maximum utility that could even in principle be attained which simply means the utility value of the outcome with maximum utility.
- Return type:
- minimum_guaranteed_utility()
Minimum utility that could even in principle be attained which simply means the utility value of the outcome with minimum utility.
- offer_to_elicit()
Returns the maximum estimaged utility and the corresponding outocme
- Remarks:
This method assumes that each element of the unkown list is a
tuple
of negative the utility value and the outcome.It also assumest that the first item in the unknown list contains the outocme with maximum estimated utility and the negative of the corresponding estimated utility.
- offering_utilities(state)
Calculates the offering utility for all outcomes
- Parameters:
state – Calculates the state at which the offering utilities are to be calculated
- Return type:
- Returns:
An ndarray with the offering utility of every outcome (in order)
- Remarks:
This is just a faster version of calling
offering_utility
in a loop.
- offering_utility(outcome, state)
returns expected utlity of offering
outcome
instate
- Parameters:
outcome – The outcome
state – The state
- Return type:
- Returns:
A utility value
- Remarks:
returns $u(o) p(o) + ru(o) (1-p(o))$ where $p$ is the opponent model, $u$ is the utility function, and $r$ is the utility in case of rejections.
state
is needed when calculating $r(o)$ by callingutility_on_rejection
.Note that if $u$ or $r$ return a
Distribution
, this method will return aDistribution
not a real number.
- on_leave(state)
A call back called after leaving a negotiation.
- Parameters:
state (
TypeVar
(TState
, bound=MechanismState
)) –MechanismState
giving current state of the negotiation.- Return type:
- on_mechanism_error(state)
A call back called whenever an error happens in the mechanism. The error and its explanation are accessible in
state
- Parameters:
state (
TypeVar
(TState
, bound=MechanismState
)) –MechanismState
giving current state of the negotiation.- Return type:
- Remarks:
The default behavior is to do nothing.
Override this to hook some action
- on_negotiation_end(state)
A call back called at each negotiation end
- Parameters:
state (
TypeVar
(TState
, bound=MechanismState
)) –MechanismState
or one of its descendants giving the state at which the negotiation ended.- Return type:
- Remarks:
The default behavior is to do nothing.
Override this to hook some action
on_negotiation_start
andon_negotiation_end
will always be called once for every agent.
- on_negotiation_start(state)
Called when the negotiation starts. Just passes the call to base_negotiator.
- on_notification(notification, notifier)
Called whenever a notification is received
- Parameters:
notification (
Notification
) – The notificationnotifier (
str
) – The notifier entity
- Remarks:
The default implementation only responds to end_negotiation by ending the negotiation
- on_notification_(notification, notifier)
Called when a notification is received. Do NOT directly override this method
- Parameters:
notification (
Notification
)notifier (
str
)
- Return type:
Returns:
- on_opponent_model_updated(outcomes, old, new)
Called when the opponent model is updated.
- Parameters:
- Return type:
- Remarks:
Updates the unknown list only if precalculated_index was not set.
- 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_proposal(state, partner_id, offer)
Called when one of the partners propose (only if enable_callbacks is set in the
SAOMechanism
).- Parameters:
state (
MechanismState
) – mechanism statepartner_id (
str
) – the partner who proposedoffer (
tuple
) – The offer from the partner
- Remarks:
Used to update the opponent model by calling
update_offered
thenon_opponent_model_updated
.
- on_partner_response(state, partner_id, outcome, response)
Called when one of the partners respond (only if enable_callbacks is set in the
SAOMechanism
).- Parameters:
state (
MechanismState
) – mechanism statepartner_id (
str
) – the partner who offeredoutcome (
tuple
) – The outcome responded toresponse (
ResponseType
) – The partner response including both the response and outcome
- Remarks:
Used to update the opponent model by calling
update_rejected
orupdate_accepted1 then `on_opponent_model_updated
.
- on_preferences_changed(changes)
Called to inform the entity that its ufun has changed.
- Parameters:
changes (
list
[PreferencesChange
]) – An ordered list of changes that happened.
Remarks:
You MUST call the super() version of this function either before or after your code when you are overriding it.
The most general form of change is
PreferencesChange.General
which indicates that you cannot trust anything you knew about the ufun anymore
- on_round_end(state)
A call back called at each negotiation round end
- Parameters:
state (
TypeVar
(TState
, bound=MechanismState
)) –MechanismState
giving current state of the negotiation.- Return type:
- Remarks:
The default behavior is to do nothing.
Override this to hook some action
- on_round_start(state)
A call back called at each negotiation round start
- Parameters:
state (
TypeVar
(TState
, bound=MechanismState
)) –MechanismState
giving current state of the negotiation.- Return type:
- Remarks:
The default behavior is to do nothing.
Override this to hook some action.
- propose(state)
Called to propose an outcome
- Parameters:
state (
MechanismState
) – mechanism state- Return type:
Remarks:
if the negotiator
can_elicit
, it willelicit
.always then calls the base negotiator to propose.
- propose_(state)
The method directly called by the mechanism (through
counter
) to ask for a proposal- Parameters:
state (
SAOState
) – The mechanism state- Return type:
- Returns:
An outcome to offer or None to refuse to offer
- Remarks:
Depending on the
SAOMechanism
settings, refusing to offer may be interpreted as ending the negotiationThe negotiator will only receive this call if it has the ‘propose’ capability.
- remove_best_offer_from_unknown_list()
Removes the best offer from the unkonwn list and returns it.
- remove_capability(name)
Removes named capability from the negotiator
- Parameters:
capabilities – The capabilities to be added as a dict
- Return type:
- Returns:
None
- Remarks:
It is the responsibility of the caller to be really capable of added capabilities.
- remove_handler(notification_type, callback)
Removes a notification handler from the list of handlers of the given type.
- Parameters:
notification_type (
str
) – Notification type as specificed in the type member of the Notification classcallback (
Callable
[[Notification
,str
],bool
]) – The callback which must receive a Notification object and a string and returns a boolean. If True is returned from one callback, the remaining callbacks will not be called
- Return type:
- Returns:
Whether or not the handler was in the list of handlers for this type. In all cases, the handler will not be called after this call (either it was not there or it will be removed).
- respond(state, source=None)
Called to respond to an offer. This is the method that should be overriden to provide an acceptance strategy.
- Parameters:
- Returns:
The response to the offer
- Return type:
- Remarks:
The default implementation never ends the negotiation
The default implementation asks the negotiator to
propose`() and accepts the `offer
if its utility was at least as good as the offer that it would have proposed (and above the reserved value).The current offer to respond to can be accessed through
state.current_offer
- respond_(state, offer)
Called by the mechanism directly (through
counter
) to respond to offers.- Parameters:
state (
MechanismState
) – mechanism stateoffer (
tuple
) – the offer to respond to
- Return type:
- Remarks:
Does the following steps:
Finds the the best offer using
best_offer
and uses the base negotiator to respond if that offer wasNone
Looks at
offerable_outcomes
and applies the elicitation strategy (one step) to the outcome if it was not offerable (or if there are no offerable outcomes defined).Finds the utility of the offer using
utility_function
not taking into accout elicitation cost and uses the base negotiator if that fails (i.e.utility_function
returnsNone
).Finds the expected utility of the offer using the
expect
() method which calls the expector passed during construction.If the maximum attainable utility now (judging from the current estimation of the utility value of each outcome taking elicitation cost into account) is less than the reserved value, end the negotiation
If the utility of my best offer (returned from
best_offer
) is less than the offered utility, accept the offerOtherwise, call bhe base negotiator to respond.
- set_id(id)
Sets the unique ID of this entity
- set_preferences(value, force=False)
Sets the utility function/Preferences.
- Parameters:
value (
Preferences
|None
) – The value to set toforce – If true,
on_preferecnes_changed()
will always be called even ifvalue
==self.preferences
- Return type:
- classmethod spawn(spawn_as='object', spawn_params=None, *args, **kwargs)
- classmethod spawn_object(*args, **kwargs)
- update_best_offer_utility(outcome, u)
We need not do anything here as we will remove the outcome anyway to the known list
- update_cutoff_utility()
Updates the cutoff utility under which no elicitation is done.
- Return type:
- Remarks:
By default it uses \(max_{o \in \Omega \cup \phi}{u(o)}\) for all outcomes \(o \in \Omega\) and the None outcome representing reserved value
- user_preferences(outcome)
Finds the total utility obtained by the user for this outcome after discounting elicitation cost.
- Parameters:
outcome (
tuple
|None
) – The outcome to find the user utility for. If None, it returns the reserved value.- Return type:
- Remarks:
The total elicitation cost is not discounted from the reserved value when the input is None
- utilities_on_rejection(state)
Finds the utility of rejection for all outputs.
- Remarks:
By default it calls
utility_on_rejection
repeatedly for all outcomes. Override this method if a faster versin can be implemented
- utility_at(x)
- utility_distributions()
Returns a
Distribution
for every outcome- Return type:
list
[ScipyDistribution
]
- utility_on_acceptance(outcome)
The utility of acceptance which is simply the utility function applied to
outcome
.
- utility_on_rejection(outcome, state)
Uses the aspiration level as the utility of rejection.
- Remarks:
This does not depend on using
AspirationNegotiator
as the base_negotiator.