Mechanism

class negmas.mechanisms.Mechanism(issues: Optional[List[negmas.outcomes.Issue]] = None, outcomes: Optional[Union[int, List[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]]]] = None, n_steps: Optional[int] = None, time_limit: Optional[float] = None, step_time_limit: Optional[float] = None, negotiator_time_limit: Optional[float] = None, max_n_agents: Optional[int] = None, dynamic_entry=False, cache_outcomes=True, max_n_outcomes: int = 1000000, keep_issue_names=None, annotation: Optional[Dict[str, Any]] = None, state_factory=<class 'negmas.common.MechanismState'>, enable_callbacks=False, checkpoint_every: int = 1, checkpoint_folder: Optional[Union[str, pathlib.Path]] = None, checkpoint_filename: Optional[str] = None, extra_checkpoint_info: Optional[Dict[str, Any]] = None, single_checkpoint: bool = True, exist_ok: bool = True, name=None, outcome_type=<class 'tuple'>, genius_port: int = 25337, id: Optional[str] = None)[source]

Bases: negmas.common.NamedObject, negmas.events.EventSource, negmas.checkpoints.CheckpointMixin, abc.ABC

Base class for all negotiation Mechanisms.

Override the round function of this class to implement a round of your mechanism

Parameters
  • issues – List of issues to use (optional as you can pass outcomes)

  • outcomes – List of outcomes (optional as you can pass issues). If an int then it is the number of outcomes

  • n_steps – Number of rounds allowed (None means infinity)

  • time_limit – Number of real seconds allowed (None means infinity)

  • max_n_agents – Maximum allowed number of agents

  • dynamic_entry – Allow agents to enter/leave negotiations between rounds

  • cache_outcomes – If true, a list of all possible outcomes will be cached

  • max_n_outcomes – The maximum allowed number of outcomes in the cached set

  • keep_issue_names – DEPRICATED. Use outcome_type instead. If True, dicts with issue names will be used for outcomes otherwise tuples

  • annotation – Arbitrary annotation

  • state_factory – A callable that receives an arbitrary set of key-value pairs and return a MechanismState descendant object

  • checkpoint_every – The number of steps to checkpoint after. Set to <= 0 to disable

  • checkpoint_folder – The folder to save checkpoints into. Set to None to disable

  • checkpoint_filename – The base filename to use for checkpoints (multiple checkpoints will be prefixed with step number).

  • single_checkpoint – If true, only the most recent checkpoint will be saved.

  • extra_checkpoint_info – Any extra information to save with the checkpoint in the corresponding json file as a dictionary with string keys

  • exist_ok – IF true, checkpoints override existing checkpoints with the same filename.

  • name – Name of the mechanism session. Should be unique. If not given, it will be generated.

  • outcome_type – The type used for representing outcomes. Can be tuple, dict or any OutcomeType

  • genius_port – the port used to connect to Genius for all negotiators in this mechanism (0 means any).

  • id – An optional system-wide unique identifier. You should not change the default value except in special circumstances like during serialization and should always guarantee system-wide uniquness if you set this value explicitly

Attributes Summary

agent_ids

agent_names

agreement

completed

current_step

dynamic_entry

history

issues

max_n_agents

n_outcomes

n_steps

negotiator_ids

negotiator_names

negotiators

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 agent to join the mechanism.

running

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

Methods Summary

abort()

Aborts the negotiation

add(negotiator, *[, ufun, role])

Add an agent to the negotiation.

add_requirements(requirements)

Adds requirements.

can_accept_more_agents()

Whether the mechanism can currently accept more negotiators.

can_enter(agent)

Whether the agent can enter the negotiation now.

can_leave(agent)

Can the agent leave now?

can_participate(agent)

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

discrete_outcomes([n_max, astype])

A discrete set of outcomes that spans the outcome space

extra_state()

Returns any extra state information to be kept in the state and history properties

get_negotiator(nid)

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

is_satisfying(capabilities)

Checks if the given capabilities are satisfying mechanism requirements.

is_valid(outcome)

Checks whether the outcome is valid given the issues

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.

outcome_index(outcome)

Returns the index of the outcome if that was possible

pareto_frontier([n_max, sort_by_welfare])

plot(**kwargs)

A method for plotting a negotiation session

random_outcomes([n, astype])

Returns random offers.

remove(negotiator, **kwargs)

Remove the agent from the negotiation.

remove_requirements(requirements)

Adds requirements.

round()

Implements a single step of the mechanism.

run([timeout])

runall(mechanisms[, keep_order, method])

Runs all mechanisms

step()

Runs a single step of the mechanism.

stepall(mechanisms[, keep_order])

Step all mechanisms

Attributes Documentation

agent_ids
agent_names
agreement
completed
current_step
dynamic_entry
history
issues
max_n_agents
n_outcomes
n_steps
negotiator_ids
negotiator_names
negotiators
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. 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 agent to join the mechanism.

running
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

Methods Documentation

abort()negmas.common.MechanismState[source]

Aborts the negotiation

add(negotiator: negmas.negotiators.Negotiator, *, ufun: Optional[negmas.utilities.UtilityFunction] = None, role: Optional[str] = None, **kwargs)Optional[bool][source]

Add an agent to the negotiation.

Parameters
  • negotiator – The agent to be added.

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

  • role – The role the agent 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 agent was added.

  • False if the agent was already in the negotiation.

  • None if the agent cannot be added.

add_requirements(requirements: dict)None[source]

Adds requirements.

can_accept_more_agents()bool[source]

Whether the mechanism can currently accept more negotiators.

can_enter(agent: negmas.negotiators.Negotiator)bool[source]

Whether the agent can enter the negotiation now.

can_leave(agent: negmas.negotiators.Negotiator)bool[source]

Can the agent leave now?

can_participate(agent: negmas.negotiators.Negotiator)bool[source]

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

Parameters

agent

Returns

True if it can

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

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

is not in the values announced by the agent.

An agent 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 agent

discrete_outcomes(n_max: Optional[int] = None, astype: Optional[Type[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]]] = None)List[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]][source]

A discrete set of outcomes that spans the outcome space

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

  • 100 if any of the issues was continuous (and) –

  • astype – A type to cast the resulting outcomes to.

Returns

List of n or less outcomes

Return type

List[Outcome]

extra_state()Optional[Dict[str, Any]][source]

Returns any extra state information to be kept in the state and history properties

get_negotiator(nid: str)Optional[SAONegotiator][source]

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

is_satisfying(capabilities: dict)bool[source]

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: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]])[source]

Checks whether the outcome is valid given the issues

on_mechanism_error()None[source]

Called when there is a mechanism error

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

on_negotiation_end()None[source]

Called at the end of each negotiation.

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

on_negotiation_start()bool[source]

Called before starting the negotiation. If it returns False then negotiation will end immediately

outcome_index(outcome)Optional[int][source]

Returns the index of the outcome if that was possible

pareto_frontier(n_max=None, sort_by_welfare=True)Tuple[List[Tuple[float]], List[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]]][source]
plot(**kwargs)[source]

A method for plotting a negotiation session

random_outcomes(n: int = 1, astype: Optional[Type[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]]] = None)List[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]][source]

Returns random offers.

Parameters
  • n – Number of outcomes to generate

  • astype – The type to use for the generated outcomes

Returns

A list of outcomes (in the type specified using astype) 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).

remove(negotiator: negmas.negotiators.Negotiator, **kwargs)Optional[bool][source]

Remove the agent from the negotiation.

Parameters

agent

Returns

  • True if the agent was removed.

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

  • None if the agent cannot be removed.

remove_requirements(requirements: Iterable)None[source]

Adds requirements.

abstract round()negmas.mechanisms.MechanismRoundResult[source]

Implements a single step of the mechanism. Override this!

Returns

MechanismRoundResult giving whether the negotiation was broken or timedout and the agreement if any.

run(timeout=None)negmas.common.MechanismState[source]
classmethod runall(mechanisms: List[negmas.mechanisms.Mechanism], keep_order=True, method='serial')List[negmas.common.MechanismState][source]

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 serial

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

Returns

  • List of states of all mechanisms after completion

step()negmas.common.MechanismState[source]

Runs a single step of the mechanism.

Returns

The state of the negotiation after the round is conducted

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[negmas.mechanisms.Mechanism], keep_order=True)List[negmas.common.MechanismState][source]

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