NLevelsComparatorNegotiator
- class negmas.negotiators.NLevelsComparatorNegotiator(*args, thresholds=None, **kwargs)[source]
Bases:
Negotiator
A negotiator that can be asked to compare two outcomes using compare_nlevels which returns the strength of the difference between two outcomes as an integer from [-n, n] in the C compare sense. By default is just consults the ufun.
To change that behavior, override
compare_nlevels
.It has the
compare-nlevels
capability.Attributes Summary
Returns the private information (annotation) not shared with other negotiators
Agent capabilities
Returns the preferences if it is a CrispUtilityFunction else None
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 internal thresholds and None if they do not exist
Returns the preferences if it is a
BaseUtilityFunction
else NoneThe unique ID of this entity
Methods Summary
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.
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
compare_nlevels
(first, second[, n])Compares two offers using the
ufun
returning an integer in [-n, n] (i.e. 2n+1 possible values) which defines which outcome is better and the strength of the difference (discretized using internal thresholds).create
(*args, **kwargs)Creates an object and returns a proxy to it.
equiprobable_thresholds
(n, preferences, issues)Generates thresholds for the n given levels where levels are equally likely approximately
from_checkpoint
(file_name[, return_info])Creates an object from a saved checkpoint
generate_thresholds
(n[, ufun_min, ufun_max, ...])Generates thresholds for the n given levels assuming the ufun ranges and scale function
handlers
(notification_type)Gets the list of handlers registered for some notification type.
is_acceptable_as_agreement
(outcome)Whether the given outcome is acceptable as a final agreement of a negotiation.
is_better
(first, second[, epsilon])Compares two offers using the
ufun
returning whether the first is better than the secondisin
(negotiation_id)Is that agent participating in the given negotiation? Tests if the agent is participating in the given negotiation.
join
(nmi, state, *[, preferences, ufun, role])Called by the mechanism when the agent is about to enter a negotiation.
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_notification
(notification, notifier)Called whenever the agent receives a notification
on_notification_
(notification, notifier)Called when a notification is received.
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
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.
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)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
- 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
- thresholds
Returns the internal thresholds and None if they do not exist
- type_name
- ufun
Returns the preferences if it is a
BaseUtilityFunction
else None
- uuid
The unique ID of this entity
Methods Documentation
- 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:
- 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:
- compare_nlevels(first, second, n=2)[source]
Compares two offers using the
ufun
returning an integer in [-n, n] (i.e. 2n+1 possible values) which defines which outcome is better and the strength of the difference (discretized using internal thresholds)- Parameters:
- Return type:
- Returns:
None if either there is no ufun defined or the number of thresholds required cannot be satisfied
0 iff |u(first) - u(second)| <= thresholds[0]
- -i if
thresholds[i-1] < u(first) - u(second) <= -thresholds[i]
- +i if
thresholds[i-1] > u(first) - u(second) >= thresholds[i]
Remarks:
thresholds is an internal array that can be set using
thresholds
propertythresholds[n] is assumed to equal infinity
n must be <= the length of the internal thresholds array. If n > that length, a ValueError will be raised. If n < the length of the internal thresholds array, the first n values of the array will be used
- classmethod create(*args, **kwargs)
Creates an object and returns a proxy to it.
- classmethod equiprobable_thresholds(n, preferences, issues, n_samples=1000)[source]
Generates thresholds for the n given levels where levels are equally likely approximately
- 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 generate_thresholds(n, ufun_min=0.0, ufun_max=1.0, scale=None)[source]
Generates thresholds for the n given levels assuming the ufun ranges and scale function
- Parameters:
- Return type:
- 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
]]
- 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:
- is_better(first, second, epsilon=1e-10)[source]
Compares two offers using the
ufun
returning whether the first is better than the second- Parameters:
- Return type:
- Returns:
True if utility(first) > utility(second) + epsilon None if |utility(first) - utility(second)| <= epsilon or the utun is not defined False if utility(first) < utility(second) - epsilon
- 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, ufun=None, role='negotiator')
Called by the mechanism when the agent is about to enter a negotiation. It can prevent the agent from entering
- Parameters:
nmi (
TypeVar
(TNMI
, bound=NegotiatorMechanismInterface
)) – The negotiation.state (
TypeVar
(TState
, bound=MechanismState
)) – The current state of the negotiationpreferences (
Preferences
|None
) – The preferences used by the negotiator (seeufun
)ufun (
BaseUtilityFunction
|None
) – The ufun function to use (overridespreferences
)role (
str
) – role of the negotiator.
- Return type:
- Returns:
bool indicating whether or not the agent accepts to enter. If False is returned it will not enter the negotiation
Remarks:
Joining a neogiation will fail in the following conditions:
The negotiator already has preferences and is asked to join with new ones
The negotiator is already in a negotiation
- 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)
A call back called at each negotiation start
- Parameters:
state (
TypeVar
(TState
, bound=MechanismState
)) –MechanismState
giving current state of the negotiation.- Return type:
Remarks:
You MUST call the super() version of this function either before or after your code when you are overriding it.
on_negotiation_start
andon_negotiation_end
will always be called once for every agent.
- on_notification(notification, notifier)
Called whenever the agent receives a notification
- Parameters:
notification (
Notification
) – The notification!!notifier (
str
) – The notifier!!
- Returns:
None
Remarks:
You MUST call the super() version of this function either before or after your code when you are overriding it.
- 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_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.
- 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).
- 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)