SAOElicitingMechanism

class negmas.elicitation.SAOElicitingMechanism(priors, true_utilities, elicitor_reserved_value, cost, opp_utility, opponent, n_steps, time_limit, base_agent, opponent_model, elicitation_strategy='pingpong', toughness=0.95, elicitor_type='balanced', history_file_name: str = None, screen_log: bool = False, dynamic_queries=True, each_outcome_once=False, rational_answer_probs=True, update_related_queries=True, resolution=0.1, cost_assuming_titration=False, name: str | None = None)

Bases: SAOMechanism

Attributes Summary

agent_ids
agent_names
agreement
atomic_steps	Is every step corresponding to a single action by a single negotiator
completed	Ended without timing out (either with agreement or broken by a negotiator)
current_step
dynamic_entry
ended	Ended in any way
expected_relative_time	Returns a positive number indicating elapsed relative time or steps.
expected_remaining_steps	Returns the expected remaining number of steps until the end of the mechanism run.
expected_remaining_time	Returns remaining time in seconds (expectation).
extended_trace	Returns the negotiation history as a list of step/negotiator/offer tuples
full_trace	Returns the negotiation history as a list of relative_time/step/negotiator/offer tuples
genius_negotiator_ids
history
id	The unique ID of this entity
issues	Returns the issues of the outcome space (if defined).
max_n_negotiators
n_outcomes
n_steps
name	A convenient name of the entity (intended primarily for printing/logging/debugging).
negotiator_ids
negotiator_names
negotiator_times	The total time consumed by every negotiator.
negotiators
offers	Returns the negotiation history as a list of offers
outcome_space
outcomes
participants	Returns a list of all participant names.
relative_time	Returns a number between 0 and 1 indicating elapsed relative time or steps.
remaining_steps	Returns the remaining number of steps until the end of the mechanism run.
remaining_time	Returns remaining time in seconds.
requirements	A dictionary specifying the requirements that must be in the capabilities of any negotiator to join the mechanism.
running
short_type_name
state	Returns the current state.
state4history	Returns the state as it should be stored in the history.
stats
time	Elapsed time since mechanism started in seconds.
time_limit
trace	Returns the negotiation history as a list of negotiator/offer tuples
type_name
uuid	The unique ID of this entity
verbosity	Verbosity level.

Methods Summary

__call__(state[, action])	implements a round or a single step of the Stacked Alternating Offers Protocol.
abort()	Aborts the negotiation.
add(negotiator, *[, preferences, role])	Add an negotiator to the negotiation.
add_requirements(requirements)	Adds requirements.
announce(event)	Raises an event and informs all event sinks that are registered for notifications on this event type
can_accept_more_negotiators()	Whether the mechanism can currently accept more negotiators.
can_enter(negotiator)	Whether the negotiator can enter the negotiation now.
can_leave(negotiator)	Can the negotiator leave now?
can_participate(negotiator)	Checks if the negotiator can participate in this type of negotiation in general.
checkpoint(path[, file_name, info, ...])	Saves a checkpoint of the current object at the given path.
checkpoint_final_step()	Should be called at the end of the simulation to save the final state
checkpoint_info(file_name)	Returns the information associated with a dump of the object saved in the given file
checkpoint_init([step_attrib, every, ...])	Initializes the object to automatically save a checkpoint
checkpoint_on_step_started()	Should be called on every step to save checkpoints as needed.
create(*args, **kwargs)	Creates an object and returns a proxy to it.
discrete_outcome_space([levels, max_cardinality])	Returns a stable discrete version of the given outcome-space.
discrete_outcomes([levels, max_cardinality])	A discrete set of outcomes that spans the outcome space.
following_negotiators()	Returns a list of ids for all negotiators in the order they are to be run in the next calls to step()
from_checkpoint(file_name[, return_info])	Creates an object from a saved checkpoint
generate_config(cost[, n_outcomes, ...])
genius_id(id)	Gets the Genius ID corresponding to the given negotiator if known otherwise its normal ID
get_negotiator(source)	Returns the negotiator with the given ID if present in the negotiation.
get_negotiator_raise(source)	Returns the negotiator with the given ID if present in the negotiation otherwise it raises an exception.
is_satisfying(capabilities)	Checks if the given capabilities are satisfying mechanism requirements.
is_valid(outcome)	Checks whether the outcome is valid given the issues.
kalai_points([max_cardinality, frontier, ...])
log(nid, data, level)	Saves a log for a negotiator
log_critical(nid, data)	Logs at critical level
log_debug(nid, data)	Logs at debug level
log_error(nid, data)	Logs at error level
log_info(nid, data)	Logs at info level
log_warning(nid, data)	Logs at warning level
logdebug(s)	logs debug-level information
logerror(s)	logs error-level information
loginfo(s)	logs nmi-level information
logwarning(s)	logs warning-level information
max_relative_welfare_points([...])
max_welfare_points([max_cardinality, ...])
modified_kalai_points([max_cardinality, ...])
nash_points([max_cardinality, frontier, ...])
negotiator_full_trace(negotiator_id)	Returns the (time/relative-time/step/outcome/response) given by a negotiator (in order)
negotiator_index(source)	Gets the negotiator index.
negotiator_offers(negotiator_id)	Returns the offers given by a negotiator (in order)
next_negotitor_ids()	Returns a list of negotiator IDs in the order they are to be run in the next call to step()
on_mechanism_error()	Called when there is a mechanism error.
on_negotiation_end()	Called at the end of each negotiation.
on_negotiation_start()	Called before starting the negotiation.
pareto_frontier([max_cardinality, ...])
pareto_frontier_bf([max_cardinality, ...])
plot([visible_negotiators, consider_costs])	A method for plotting a negotiation session.
random_outcome()	Returns a single random offer
random_outcomes([n, with_replacement])	Returns random outcomes.
register_listener(event_type, listener)	Registers a listener for the given event_type.
remove(negotiator)	Remove the negotiator from the negotiation.
remove_requirements(requirements)	Adds requirements.
run([timeout])
run_with_progress([timeout])
runall(mechanisms[, keep_order, method, ...])	Runs all mechanisms.
set_id(id)	Sets the unique ID of this entity
set_sync_call(v)
spawn([spawn_as, spawn_params])
spawn_object(*args, **kwargs)
step()	Runs a single step of the mechanism.
stepall(mechanisms[, keep_order])	Step all mechanisms.

Attributes Documentation

agent_ids

agent_names

agreement

atomic_steps

Is every step corresponding to a single action by a single negotiator

completed

Ended without timing out (either with agreement or broken by a negotiator)

current_step

dynamic_entry

ended

Ended in any way

expected_relative_time

Returns a positive number indicating elapsed relative time or steps.

Remarks:

• This is relative to the expected time/step at which the negotiation ends given all timing conditions (time_limit, n_step, pend, pend_per_second).

expected_remaining_steps

Returns the expected remaining number of steps until the end of the mechanism run.

None if unlimited

expected_remaining_time

Returns remaining time in seconds (expectation).

None if no time limit or pend_per_second is given.

extended_trace

Returns the negotiation history as a list of step/negotiator/offer tuples

full_trace

Returns the negotiation history as a list of relative_time/step/negotiator/offer tuples

genius_negotiator_ids

history

id

The unique ID of this entity

issues

Returns the issues of the outcome space (if defined).

Will raise an exception if the outcome space has no defined issues

max_n_negotiators

n_outcomes

n_steps

name

A convenient name of the entity (intended primarily for printing/logging/debugging).

negotiator_ids

negotiator_names

negotiator_times

The total time consumed by every negotiator.

Each mechanism class is responsible of updating this for any activities of the negotiator it controls.

negotiators

offers

Returns the negotiation history as a list of offers

outcome_space

outcomes

participants

Returns a list of all participant names.

relative_time

Returns a number between 0 and 1 indicating elapsed relative time or steps.

Remarks:

• If pend or pend_per_second are defined in the NegotiatorMechanismInterface, and time_limit/n_steps are not given, this becomes an expectation that is limited above by one.

remaining_steps

Returns the remaining number of steps until the end of the mechanism run.

None if unlimited

remaining_time

Returns remaining time in seconds.

None if no time limit is given.

requirements

A dictionary specifying the requirements that must be in the capabilities of any negotiator to join the mechanism.

running

short_type_name

state

Returns the current state.

Override extra_state if you want to keep extra state

state4history

Returns the state as it should be stored in the history.

stats

time

Elapsed time since mechanism started in seconds.

0.0 if the mechanism did not start running

time_limit

trace

Returns the negotiation history as a list of negotiator/offer tuples

type_name

uuid

The unique ID of this entity

verbosity

Verbosity level.

• Children of this class should only print if verbosity > 1

Methods Documentation

__call__(state, action=None) → MechanismStepResult

implements a round or a single step of the Stacked Alternating Offers Protocol.

Parameters:

• state – Current state of the mechanism

• action – The action to use as a mapping from negotiator ID (key) to its response (value). If not given, the negotiator(s) is called to generate its response.

abort() → TState

Aborts the negotiation.

add(negotiator: SAONegotiator | GBNegotiator, *, preferences: Preferences | None = None, role: str | None = None, **kwargs) → bool | None

Add an negotiator to the negotiation.

Parameters:

• negotiator – The negotiator to be added.

• preferences – The utility function to use. If None, then the negotiator must already have a stored utility function otherwise it will fail to enter the negotiation.

• ufun – [depricated] same as preferences but must be a UFun object.

• role – The role the negotiator plays in the negotiation mechanism. It is expected that mechanisms inheriting from this class will check this parameter to ensure that the role is a valid role and is still possible for negotiators to join on that role. Roles may include things like moderator, representative etc based on the mechanism

Returns:

• True if the negotiator was added.

• False if the negotiator was already in the negotiation.

• None if the negotiator cannot be added. This can happen in the following cases:

  1. The capabilities of the negotiator do not match the requirements of the negotiation

  2. The outcome-space of the negotiator’s preferences do not contain the outcome-space of the negotiation

  3. The negotiator refuses to join (by returning False from its join method) see Negotiator.join for possible reasons of that

add_requirements(requirements: dict) → None

Adds requirements.

announce(event: Event)

Raises an event and informs all event sinks that are registered for notifications on this event type

can_accept_more_negotiators() → bool

Whether the mechanism can currently accept more negotiators.

can_enter(negotiator: TNegotiator) → bool

Whether the negotiator can enter the negotiation now.

can_leave(negotiator: Negotiator) → bool

Can the negotiator leave now?

can_participate(negotiator: TNegotiator) → bool

Checks if the negotiator can participate in this type of negotiation in general.

Returns:

True if the negotiator can participate

Return type:

bool

Remarks:

The only reason this may return False is if the mechanism requires some requirements that are not within the capabilities of the negotiator.

When evaluating compatibility, the negotiator is considered incapable of participation if any of the following conditions hold: * A mechanism requirement is not in the capabilities of the negotiator * A mechanism requirement is in the capabilities of the negotiator by the values required for it

is not in the values announced by the negotiator.

An negotiator that lists a None value for a capability is announcing that it can work with all its values. On the other hand, a mechanism that lists a requirement as None announces that it accepts any value for this requirement as long as it exist in the negotiator

checkpoint(path: PathLike, file_name: str | None = None, info: dict[str, Any] | None = None, exist_ok: bool = False, single_checkpoint: bool = True, step_attribs: tuple[str, ...] = ('current_step', '_current_step', '_Entity__current_step', '_step')) → Path

Saves a checkpoint of the current object at the given path.

Parameters:

• path – Full path to a directory to store the checkpoint

• file_name – Name of the file to dump into. If not given, a unique name is created

• info – Information to save with the checkpoint (must be json serializable)

• exist_ok – If true, override existing dump

• single_checkpoint – If true, keep a single checkpoint for the last step

• step_attribs – 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

Returns:

full path to the file used to save the checkpoint

checkpoint_final_step() → Path | None

Should be called at the end of the simulation to save the final state

Remarks:

• Should be called after all processing of the final step is conducted.

classmethod checkpoint_info(file_name: Path | str) → dict[str, Any]

Returns the information associated with a dump of the object saved in the given file

Parameters:

file_name – Name of the object

Returns:

checkpoint_init(step_attrib: str = 'current_step', every: int = 1, folder: PathLike | Path | str | None = None, filename: str | None = None, info: dict[str, Any] | None = None, exist_ok: bool = True, single: bool = True)

Initializes the object to automatically save a checkpoint

Parameters:

• step_attrib – The attribute that defines the current step. If None, there is no step concept

• every – Number of steps per checkpoint. If < 1 no checkpoints will be saved

• folder – The directory to store checkpoints under

• filename – Name of the file to save the checkpoint under. If None, a unique name will be chosen. If single_checkpoint was False, then multiple files will be used prefixed with the step number

• info – Any extra information to save in the json file associated with each checkpoint

• exist_ok – Override existing files if any

• single – If True, only the most recent checkpoint will be kept

Remarks:

• single_checkpoint implies exist_ok

checkpoint_on_step_started() → Path | None

Should be called on every step to save checkpoints as needed.

Returns:

The path on which the checkpoint is stored if one is stored. None otherwise.

Remarks:

• Should be called at the BEGINNING of every step before any processing takes place

classmethod create(*args, **kwargs)

Creates an object and returns a proxy to it.

discrete_outcome_space(levels: int = 5, max_cardinality: int = 10000000000) → DiscreteOutcomeSpace

Returns a stable discrete version of the given outcome-space.

discrete_outcomes(levels: int = 5, max_cardinality: int | float = inf) → list[tuple]

A discrete set of outcomes that spans the outcome space.

Parameters:

• max_cardinality – The maximum number of outcomes to return. If None, all outcomes will be returned for discrete issues

• continuous (and 10_000 if any of the issues was)

Returns:

list of n or less outcomes

Return type:

list[Outcome]

following_negotiators() → list[str]

Returns a list of ids for all negotiators in the order they are to be run in the next calls to step()

classmethod from_checkpoint(file_name: Path | str, return_info: bool = False) → NamedObject | tuple[NamedObject, dict[str, Any]]

Creates an object from a saved checkpoint

Parameters:

• file_name

• return_info – If True, tbe information saved when the file was dumped are returned

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_config(cost, n_outcomes: int = None, rand_preferencess=True, conflict: float = None, conflict_delta: float = None, winwin=None, genius_folder: str = None, n_steps=None, time_limit=None, own_utility_uncertainty=0.5, own_uncertainty_variablility=0.0, own_reserved_value=0.0, own_base_agent='aspiration', opponent_model_uncertainty=0.5, opponent_model_adaptive=False, opponent_proposes=True, opponent_type='best_only', opponent_toughness=0.9, opponent_reserved_value=0.0) → dict[str, Any]

genius_id(id: str | None) → str | None

Gets the Genius ID corresponding to the given negotiator if known otherwise its normal ID

get_negotiator(source: str) → Negotiator | None

Returns the negotiator with the given ID if present in the negotiation.

get_negotiator_raise(source: str) → Negotiator

Returns the negotiator with the given ID if present in the negotiation otherwise it raises an exception.

is_satisfying(capabilities: dict) → bool

Checks if the given capabilities are satisfying mechanism requirements.

Parameters:

capabilities – capabilities to check

Returns:

bool are the requirements satisfied by the capabilities.

Remarks:

• Requirements are also a dict with the following meanings:

  • tuple: Min and max acceptable values

  • list/set: Any value in the iterable is acceptable

  • Single value: The capability must match this value

• Capabilities can also have the same three possibilities.

is_valid(outcome: tuple)

Checks whether the outcome is valid given the issues.

kalai_points(max_cardinality: float = inf, frontier: tuple[tuple[float, ...], ...] | None = None, frontier_outcomes: list[tuple] | None = None) → tuple[tuple[tuple[float, ...], tuple], ...]

log(nid: str, data: dict[str, Any], level: str) → None

Saves a log for a negotiator

log_critical(nid: str, data: dict[str, Any]) → None

Logs at critical level

log_debug(nid: str, data: dict[str, Any]) → None

Logs at debug level

log_error(nid: str, data: dict[str, Any]) → None

Logs at error level

log_info(nid: str, data: dict[str, Any]) → None

Logs at info level

log_warning(nid: str, data: dict[str, Any]) → None

Logs at warning level

logdebug(s) → None

logs debug-level information

Parameters:

s (str) – The string to log

logerror(s) → None

logs error-level information

Parameters:

s (str) – The string to log

loginfo(s: str) → None

logs nmi-level information

Parameters:

s (str) – The string to log

logwarning(s) → None

logs warning-level information

Parameters:

s (str) – The string to log

max_relative_welfare_points(max_cardinality: float = inf, frontier: tuple[tuple[float, ...], ...] | None = None, frontier_outcomes: list[tuple] | None = None) → tuple[tuple[tuple[float, ...], tuple], ...]

max_welfare_points(max_cardinality: float = inf, frontier: tuple[tuple[float, ...], ...] | None = None, frontier_outcomes: list[tuple] | None = None) → tuple[tuple[tuple[float, ...], tuple], ...]

modified_kalai_points(max_cardinality: float = inf, frontier: tuple[tuple[float, ...], ...] | None = None, frontier_outcomes: list[tuple] | None = None) → tuple[tuple[tuple[float, ...], tuple], ...]

nash_points(max_cardinality: float = inf, frontier: tuple[tuple[float, ...], ...] | None = None, frontier_outcomes: list[tuple] | None = None) → tuple[tuple[tuple[float, ...], tuple], ...]

negotiator_full_trace(negotiator_id: str) → list[tuple[float, float, int, tuple, str]]

Returns the (time/relative-time/step/outcome/response) given by a negotiator (in order)

negotiator_index(source: str) → int | None

Gets the negotiator index.

Parameters:

source (str) – source

Return type:

int | None

negotiator_offers(negotiator_id: str) → list[tuple]

Returns the offers given by a negotiator (in order)

next_negotitor_ids() → list[str]

Returns a list of negotiator IDs in the order they are to be run in the next call to step()

on_mechanism_error() → None

Called when there is a mechanism error.

Remarks:

• When overriding this function you MUST call the base class version

on_negotiation_end()

Called at the end of each negotiation.

Remarks:

• When overriding this function you MUST call the base class version

on_negotiation_start()

Called before starting the negotiation.

If it returns False then negotiation will end immediately

pareto_frontier(max_cardinality: float = inf, sort_by_welfare=True) → tuple[tuple[tuple[float, ...], ...], list[tuple]]

pareto_frontier_bf(max_cardinality: float = inf, sort_by_welfare=True) → tuple[list[tuple[float, ...]], list[tuple]]

plot(visible_negotiators=(0, 1), consider_costs=False)

A method for plotting a negotiation session.

random_outcome() → tuple

Returns a single random offer

random_outcomes(n: int = 1, with_replacement: bool = False) → list[tuple]

Returns random outcomes.

Parameters:

• n – Number of outcomes to generate

• with_replacement – If true, outcomes may be repeated

Returns:

A list of outcomes of at most n outcomes.

Remarks:

• If the number of outcomes n cannot be satisfied, a smaller number will be returned

• Sampling is done without replacement (i.e. returned outcomes are unique).

register_listener(event_type: str | None, listener: EventSink)

Registers a listener for the given event_type.

Parameters:

• event_type – The type to register. If None, the listener will be registered for all types

• listener – The listening agent (must have an on_event method that receives an event: Event and a sender: EventSource)

remove(negotiator: TNegotiator) → bool | None

Remove the negotiator from the negotiation.

Returns:

• True if the negotiator was removed.

• False if the negotiator was not in the negotiation already.

• None if the negotiator cannot be removed.

remove_requirements(requirements: Iterable) → None

Adds requirements.

run(timeout=None) → TState

run_with_progress(timeout=None) → TState

classmethod runall(mechanisms: list[Mechanism] | tuple[Mechanism, ...], keep_order=True, method: str = 'ordered', ordering: tuple[int, ...] | None = None, ordering_fun: Callable[[int, list[TState | None]], int] | None = None, completion_callback: Callable[[int, Mechanism], None] | None = None, ignore_mechanism_exceptions: bool = False) → list[TState | None]

Runs all mechanisms.

Parameters:

• mechanisms – list of mechanisms

• keep_order – if True, the mechanisms will be run in order every step otherwise the order will be randomized at every step. This is only allowed if the method is ordered

• method – the method to use for running all the sessions. Acceptable options are: sequential, ordered, threads, processes

• ordering – Controls the order of advancing the negotiations with the “ordered” method.

• ordering_fun – A function to implement dynamic ordering for the “ordered” method. This function receives a list of states and returns the index of the next mechanism to step. Note that a state may be None if the corresponding mechanism was None and it should never be stepped

• completion_callback – A callback to be called at the moment each mechanism is ended

• ignore_mechanism_exceptions – If given, mechanisms with exceptions will be treated as ending and running will continue

Returns:

• list of states of all mechanisms after completion

• None for any such states indicates disagreements

Remarks:

• sequential means running each mechanism until completion before going to the next

• ordered means stepping mechanisms in some order which can be controlled by ordering. If no ordering is given, the ordering is just round-robin

set_id(id: str)

Sets the unique ID of this entity

set_sync_call(v: bool)

classmethod spawn(spawn_as='object', spawn_params: dict[str, Any] | None = None, *args, **kwargs)

classmethod spawn_object(*args, **kwargs)

step() → SAOState

Runs a single step of the mechanism.

Returns:

The state of the negotiation after the round is conducted action: An optional action (value) for the next negotiator (key). If given, the call

should just execute the action without calling the next negotiator.

Return type:

MechanismState

Remarks:

• Every call yields the results of one round (see round())

• If the mechanism was yet to start, it will start it and runs one round

• There is another function (run()) that runs the whole mechanism in blocking mode

classmethod stepall(mechanisms: list[Mechanism] | tuple[Mechanism, ...], keep_order=True) → list[TState]

Step all mechanisms.

Parameters:

• mechanisms – list of mechanisms

• keep_order – if True, the mechanisms will be run in order every step otherwise the order will be randomized at every step

Returns:

• list of states of all mechanisms after completion