SAOSingleAgreementAspirationController

class negmas.sao.SAOSingleAgreementAspirationController(*args, max_aspiration=1.0, aspiration_type='boulware', **kwargs)[source]

Bases: SAOSingleAgreementController

A SAOSingleAgreementController that uses aspiration level to decide what to accept and what to propose.

Parameters:

preferences – The utility function to use for ALL negotiations
max_aspiration (float) – The maximum aspiration level to start with
aspiration_type (Union[Literal['boulware', 'conceder', 'linear'], int, float]) – The aspiration type/ exponent

Remarks:

This controller will get at most one agreement. It uses a concession strategy controlled by max_aspiration and aspiration_type as in the AspirationNegotiator for all negotiations.

The partner who gives the best proposal will receive an offer that is guaranteed to have a utility value (for the controller) above the current aspiration level.

The controller uses a single ufun for all negotiations. This implies that all negotiations should have the same outcome space (i.e. the same issues).

Attributes Summary

`active_negotiators`	Returns the negotiators whose negotiations are running.
`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).
`negotiators`	Returns a dictionary mapping negotiator ID to the a tuple containing the negotiator and its context.
`preferences`	The utility function attached to that object
`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.
`reserved_value`	Reserved value is what the entity gets if no agreement is reached in the negotiation.
`short_type_name`
`states`	Gets the current states of all negotiations as a mapping from negotiator ID to mechanism.
`type_name`
`ufun`	Returns the preferences if it is a `BaseUtilityFunction` else None
`uuid`	The unique ID of this entity

Methods Summary

`add_negotiator`(negotiator[, cntxt])	Adds a negotiator to the controller.
`after_join`(negotiator_id, *args[, ufun, ...])	Called by children negotiators after joining a negotiation to inform the controller
`before_join`(negotiator_id, nmi, state, *[, ...])	Called by children negotiators to get permission to join negotiations
`best_offer`(offers)	Return the ID of the negotiator with the best offer
`best_outcome`(negotiator[, state])	The best outcome for the negotiation `negotiator` engages in given the `state` .
`call`(negotiator, method, args, *kwargs)	Calls the given method on the given negotiator safely without causing recursion.
`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
`counter_all`(offers, states)	Counters all responses
`create`(args, *kwargs)	Creates an object and returns a proxy to it.
`create_negotiator`([negotiator_type, name, cntxt])	Creates a negotiator passing it the context
`first_offer`(negotiator_id)	Finds the first offer for this given negotiator.
`first_proposals`()	Gets a set of proposals to use for initializing the negotiation.
`from_checkpoint`(file_name[, return_info])	Creates an object from a saved checkpoint
`is_acceptable`(offer, source, state)	Should decide if the given offer is acceptable
`is_better`(a, b, negotiator, state)	Compares two outcomes of the same negotiation
`is_clean`()	Checks that the agent has no negotiators and that all its intermediate data-structures are reset
`join`(negotiator_id, nmi, state, *[, ...])	Called by the mechanism when the agent is about to enter a negotiation.
`kill_negotiator`(negotiator_id[, force])	Kills the negotiator sending it an `before_death` message.
`make_negotiator`([negotiator_type, name])	Creates a negotiator but does not add it to the controller.
`make_offer`(negotiator, state, best_offer, ...)	Generate an offer for the given partner
`on_leave`(negotiator_id, state)	A call back called after leaving a negotiation.
`on_mechanism_error`(negotiator_id, state)	rtype: `None`
`on_negotiation_end`(negotiator_id, state)	A call back called at each negotiation end
`on_negotiation_start`(negotiator_id, state)	A call back called at each negotiation start
`on_notification`(negotiator_id, notification, ...)
`on_preferences_changed`(changes)	Called to inform the entity that its ufun has changed.
`on_round_end`(negotiator_id, state)	A call back called at each negotiation round end
`on_round_start`(negotiator_id, state)	A call back called at each negotiation round start
`partner_agent_ids`(negotiator_id)	Finds the agent ID negotiating with one of our negotiators.
`partner_agent_names`(negotiator_id)	Finds the negotiator names negotiating with one of our negotiators.
`partner_negotiator_ids`(negotiator_id)	Finds the negotiator ID negotiating with one of our negotiators.
`partner_negotiator_names`(negotiator_id)	Finds the negotiator names negotiating with one of our negotiators.
`propose`(negotiator_id, state)	rtype: `tuple` \| `None`
`reset`()	Resets the controller and kills any negotiators it may have
`respond`(negotiator_id, state[, source])	rtype: `ResponseType`
`response_to_best_offer`(negotiator, state, offer)	Return a response to the partner from which the best current offer was received
`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)
`utility_at`(x)

Attributes Documentation

active_negotiators

Returns the negotiators whose negotiations are running.

Returns a dictionary mapping negotiator ID to the a tuple containing the negotiator and its context

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).

negotiators: Returns a dictionary mapping negotiator ID to the a tuple containing the negotiator and its context.

preferences: The utility function attached to that object

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

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

states: Gets the current states of all negotiations as a mapping from negotiator ID to mechanism.

type_name

ufun: Returns the preferences if it is a BaseUtilityFunction else None

uuid: The unique ID of this entity

Methods Documentation

add_negotiator(negotiator, cntxt=None)

Adds a negotiator to the controller.

Parameters:

negotaitor – The negotaitor to add
name – negotiator name
cntxt (Any) – The context to be associated with this negotiator.
**kwargs – any key-value pairs to be passed to the negotiator constructor

Return type:

None

after_join(negotiator_id, *args, ufun=None, preferences=None, **kwargs)

Called by children negotiators after joining a negotiation to inform the controller

Parameters:

negotiator_id – The negotiator ID
nmi (SAONMI) – The negotiation.
state (SAOState) – The current state of the negotiation
ufun (UtilityFunction) – The ufun function to use before any discounting.
role (str) – role of the agent.

Return type:

None

before_join(negotiator_id, nmi, state, *, preferences=None, role='negotiator')

Called by children negotiators to get permission to join negotiations

Parameters:

negotiator_id (str) – The negotiator ID
nmi (SAONMI) – The negotiation.
state (SAOState) – The current state of the negotiation
ufun (UtilityFunction) – The ufun function to use before any discounting.
role (str) – role of the agent.

Return type:

bool

Returns:

True if the negotiator is allowed to join the negotiation otherwise False

best_offer(offers)[source]

Return the ID of the negotiator with the best offer

Parameters:: offers – A mapping from negotiator ID to the offer it received
Returns:: The ID of the negotiator with best offer. Ties should be broken. Return None only if there is no way to calculate the best offer.

best_outcome(negotiator, state=None)[source]

The best outcome for the negotiation negotiator engages in given the state .

Parameters:

negotiator – The negotiator for which the best outcome is to be found
state – If given, the state of the negotiation. If None, should return the absolute best outcome

Returns:

The outcome with maximum utility.

Remarks:

The default implementation, just returns the best outcome for this negotiation without considering the state or returns None if it is not possible to find this best outcome.

If the negotiator defines a ufun, it is used otherwise the ufun defined for the controller if used (if any)

call(negotiator, method, *args, **kwargs)

Calls the given method on the given negotiator safely without causing recursion. The controller MUST use this function to access any callable on the negotiator.

Parameters:

negotiator (ControlledNegotiator)
method (str)
*args
**kwargs

Returns:

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 (str | None) – Name of the file to dump into. If not given, a unique name is created
info (dict[str, Any] | None) – 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
Return type:: dict[str, Any]

Returns:

counter_all(offers, states)

Counters all responses

Parameters:

offers (dict[str, tuple | None]) – A dictionary mapping partner ID to offer
states (dict[str, SAOState]) – A dictionary mapping partner ID to mechanism state

Return type:

dict[str, SAOResponse]

Returns:

A dictionary mapping partner ID to a response

Remarks:

The agent will counter all offers by either ending all negotiations except one which is accepted or by rejecting all offers and countering them using the make_offer method.

classmethod create(*args, **kwargs): Creates an object and returns a proxy to it.

create_negotiator(negotiator_type=None, name=None, cntxt=None, **kwargs)

Creates a negotiator passing it the context

Parameters:

negotiator_type – Type of the negotiator to be created
name (str | None) – negotiator name
cntxt (Any) – The context to be associated with this negotiator.
**kwargs – any key-value pairs to be passed to the negotiator constructor

Returns:

The negotiator to be controlled. None for failure

first_offer(negotiator_id)

Finds the first offer for this given negotiator. By default it will be the best offer

Parameters:: negotiator_id (str) – The ID of the negotiator
Return type:: tuple | None
Returns:: The first offer to use.

Remarks:: Default behavior is to use the ufun defined for the controller if any then try the ufun defined for the negotiator. If neither exists, the first offer will be None.

first_proposals()

Gets a set of proposals to use for initializing the negotiation.

Return type:: dict[str, tuple | None]

classmethod from_checkpoint(file_name, return_info=False)

Creates an object from a saved checkpoint

Parameters:

file_name (Path | str)
return_info (bool) – 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

is_acceptable(offer, source, state)[source]

Should decide if the given offer is acceptable

Parameters:

offer (tuple) – The offer being tested
source (str) – The ID of the negotiator that received this offer
state (SAOState) – The state of the negotiation handled by that negotiator

Remarks:

If True is returned, this offer will be accepted and all other negotiations will be ended.

is_better(a, b, negotiator, state)[source]

Compares two outcomes of the same negotiation

Parameters:

a (tuple | None) – Outcome
b (tuple | None) – Outcome
negotiator (str) – The negotiator for which the comparison is to be made
state (SAOState) – Current state of the negotiation

Return type:

bool

Returns:

True if utility(a) > utility(b)

is_clean()

Checks that the agent has no negotiators and that all its intermediate data-structures are reset

Return type:: bool

join(negotiator_id, 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:

negotiator_id (str) – The negotiator ID
nmi (AgentMechanismInterface) – The negotiation.
state (TState) – The current state of the negotiation
preferences (Preferences) – The preferences.
ufun (BaseUtilityFunction) – The ufun function to use before any discounting (overrides preferences)
role (str) – role of the agent.

Return type:

bool

Returns:

bool indicating whether or not the agent accepts to enter.If False is returned it will not enter the negotiation.

kill_negotiator(negotiator_id, force=False)

Kills the negotiator sending it an before_death message.

Parameters:

negotiator_id (str) – The ID of the negotiator to kill.
force (bool) – Whether to kill the negotiator in case it refused to die.

Return type:

None

Remarks:

Killing a negotiator amounts to nothing more than removing it form the list of negotiators maintained by the controller.

make_negotiator(negotiator_type=None, name=None, **kwargs)

Creates a negotiator but does not add it to the controller. Call add_negotiator to add it.

Parameters:

negotiator_type (Union[str, TypeVar(TControlledNegotiator, bound= Negotiator), None]) – Type of the negotiator to be created. If None, A ControlledNegotiator negotiator will be controlled (which is fully controlled by the controller).
name (str | None) – negotiator name
**kwargs – any key-value pairs to be passed to the negotiator constructor

Return type:

TypeVar(TControlledNegotiator, bound= Negotiator)

Returns:

The negotiator to be controlled. None for failure

make_offer(negotiator, state, best_offer, best_from)

Generate an offer for the given partner

Parameters:

negotiator (str) – The ID of the negotiator for who an offer is to be made.
state (SAOState) – The mechanism state of this partner
best_offer (tuple | None) – The best offer received in this round. None means that no known best offers.
best_from (str | None) – The ID of the negotiator that received the best offer

Return type:

tuple | None

Returns:

The outcome to be offered to negotiator (None means no-offer)

Remarks:

Default behavior is to offer everyone best_offer if available otherwise, it returns no offers (None). The best_from negotiator will be sending the result of best_outcome.

on_leave(negotiator_id, state)

A call back called after leaving a negotiation.

Parameters:

negotiator_id (str) – The negotiator ID
state (TypeVar(TState, bound= MechanismState)) – TState giving current state of the negotiation.

Return type:

None

on_mechanism_error(negotiator_id, state)

Return type:: None

on_negotiation_end(negotiator_id, state)

A call back called at each negotiation end

Parameters:

negotiator_id (str) – The negotiator ID
state (SAOState) – TState or one of its descendants giving the state at which the negotiation ended.

Return type:

None

on_negotiation_start(negotiator_id, state)

A call back called at each negotiation start

Parameters:

negotiator_id (str) – The negotiator ID
state (TypeVar(TState, bound= MechanismState)) – TState giving current state of the negotiation.

Return type:

None

on_notification(negotiator_id, notification, notifier)

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(negotiator_id, state)

A call back called at each negotiation round end

Parameters:

negotiator_id (str) – The negotiator ID
state (TypeVar(TState, bound= MechanismState)) – TState giving current state of the negotiation.

Return type:

None

on_round_start(negotiator_id, state)

A call back called at each negotiation round start

Parameters:

negotiator_id (str) – The negotiator ID
state (TypeVar(TState, bound= MechanismState)) – TState giving current state of the negotiation.

Return type:

None

partner_agent_ids(negotiator_id)

Finds the agent ID negotiating with one of our negotiators.

Parameters:: negotiator_id (str) – Our negotiator ID
Return type:: list[str] | None

partner_agent_names(negotiator_id)

Finds the negotiator names negotiating with one of our negotiators.

Parameters:: negotiator_id (str) – Our negotiator ID
Return type:: list[str] | None

partner_negotiator_ids(negotiator_id)

Finds the negotiator ID negotiating with one of our negotiators.

Parameters:: negotiator_id (str) – Our negotiator ID
Return type:: list[str] | None

partner_negotiator_names(negotiator_id)

Finds the negotiator names negotiating with one of our negotiators.

Parameters:: negotiator_id (str) – Our negotiator ID
Return type:: list[str] | None

propose(negotiator_id, state)

Return type:: tuple | None

reset(): Resets the controller and kills any negotiators it may have

respond(negotiator_id, state, source=None)

Return type:: ResponseType

response_to_best_offer(negotiator, state, offer)

Return a response to the partner from which the best current offer was received

Parameters:

negotiator (str) – The negotiator from which the best offer was received
state (SAOState) – The state of the corresponding negotiation
offer (tuple) – The best offer received at this round.

Return type:

tuple | None

Returns:

The offer to be sent back to negotiator

set_id(id): Sets the unique ID of this entity

set_preferences(value, force=False, ignore_exceptions=False)

Sets the utility function/Preferences.

Parameters:

value (Preferences | None) – The value to set to
force – If true, on_preferecnes_changed() will always be called even if value == self.preferences

Return type:

Preferences | None

classmethod spawn(spawn_as='object', spawn_params=None, *args, **kwargs)

classmethod spawn_object(*args, **kwargs)

utility_at(x)[source]