negmas.situated Package

This module defines the base classes for worlds within which multiple agents engage in situated negotiations

The Agent class encapsulates the managing entity that creates negotiators to engage in negotiations within a world Simulation in order to maximize its own total utility.

Remarks:

  • When immediate_negotiations is true, negotiations start in the same step they are registered in (they may also end in that step) and negotiation_speed_multiple steps of it are conducted. That entails that requesting a negotiation may result in new contracts in the same time-step only of immediate_negotiations is true.

Simulation steps:

It is possible to control the order of the simulation steps differently using the operations parameter to the world constructor. this is the default order

  1. prepare custom stats (call _pre_step_stats)

  2. step all existing negotiations negotiation_speed_multiple times handling any failed negotiations and creating contracts for any resulting agreements

  3. Allow custom simulation (call simulation_step ) with stage 0

  4. run all Entity objects registered (i.e. all agents) in the predefined simulation_order.

  5. sign contracts that are to be signed at this step calling on_contracts_finalized / on_contract_signed as needed

  6. execute contracts that are executable at this time-step handling any breaches

  7. allow custom simulation steps to run (call simulation_step ) with stage 1

  8. remove any negotiations that are completed!

  9. update basic stats

  10. update custom stats (call _post_step_stats)

Monitoring a simulation:

You can monitor a running simulation using a WorldMonitor or StatsMonitor object. The former monitors events in the world while the later monitors the statistics of the simulation. This is a list of some of the events that can be monitored by WorldMonitor . World designers can add new events either by announcing them using announce or as a side-effect of logging them using any of the log functions.

Event

Data

extra-step

none

mechanism-creation-exception

exception: Exception

zero-outcomes-negotiation

caller: Agent, partners: List[Agent] , annotation: Dict [ str, Any ]

entity-exception

exception: Exception

contract-exception

contract: Contract, exception: Exception

agent-exception

method: str , exception: Exception

agent-joined

agent: Agent

negotiation-request

caller: Agent , partners: List [ Agent ], issues: List [ Issue ] , mechanism_name: str , annotation: Dict [ str, Any ], req_id: str

negotiation-request-immediate

caller: Agent , partners: List [ Agent ], issues: List [ Issue ] , mechanism_name: str , annotation: Dict [ str, Any ]

negotiation-request-rejected

caller: Agent , partners: List [ Agent ] , req_id: str , rejectors: List [ Agent ] , annotation: Dict [ str, Any ]

negotiation-request-accepted

caller: Agent , partners: List [ Agent ] , req_id: str , mechanism: Mechanism , annotation: Dict [ str, Any ]

negotiation-success

mechanism: Mechanism , contract: Contract , partners: List [ Agent ]

negotiation-failure

mechanism: Mechanism , partners: List [ Agent ]

contract-executing

contract: Contract

contract-nullified

contract: Contract

contract-breached

contract: Contract, breach: Breach

breach-resolved

contract: Contract, breaches: List[Breach], resolution

contract-executed

contract: Contract

dropped-contract

contract: Contract

Functions

safe_min(a, b)

Returns min(a, b) assuming None is less than anything.

deflistdict()

show_edge_colors()

Plots the edge colors used with their meaning

save_stats(world, log_dir[, params, ...])

Saves the statistics of a world run.

Classes

RunningNegotiationInfo(negotiator, ...)

Keeps track of running negotiations for an agent

NegotiationRequestInfo(partners, issues, ...)

Keeps track to negotiation requests that an agent sent

RenegotiationRequest(publisher, issues[, ...])

A request for renegotiation.

NegotiationInfo(mechanism, partners, ...[, ...])

Saves information about a negotiation

Operations(value)

An enumeration.

Action(type, params)

An action that an Agent can execute in a World through the Simulator.

Adapter(obj[, include_adapter_type_name, ...])

Represents an adapter agent that makes some included object act as an agent in some world.

Agent([name, type_postfix, preferences, ufun])

Base class for all agents that can run within a World and engage in situated negotiations

Entity([type_postfix])

Defines an entity that is a part of the world but does not participate in the simulation

AgentWorldInterface(world, agent)

Agent World Interface class

BreachProcessing(value)

The way breaches are to be handled

Breach(contract, perpetrator, type[, ...])

BulletinBoard()

The bulletin-board which carries all public information.

Contract([agreement, partners, annotation, ...])

A agreement definition which encapsulates an agreement with partners and extra information

MechanismFactory(world, mechanism_name, ...)

A mechanism creation class.

TimeInAgreementMixin()

NoContractExecutionMixin()

A mixin to add when there is no contract execution

NoResponsesMixin()

A mixin that can be added to Agent to minimize the number of abstract methods

StatsMonitor([type_postfix])

A monitor object capable of receiving stats of a world

WorldMonitor([type_postfix])

A monitor object capable of monitoring a world.

World([bulletin_board, n_steps, time_limit, ...])

Base world class encapsulating a world that runs a simulation with several agents interacting within some dynamically changing environment.

SimpleWorld([bulletin_board, n_steps, ...])

Represents a simple world with no simulation and sane values for most callbacks and methods.

NegWorld(*args, scenario, types[, params, ...])

A world that runs a list of negotiators in a given scenario to evaluate them

NegAgent(*args, negotiator_type[, ...])

Wraps a negotiator for evaluaton

Condition(name, issues, ufuns, partner_types)

A representation of a negotiation scenario in which a negotiator can be evaluated

Class Inheritance Diagram

digraph inheritance73ea85be44 { bgcolor=transparent; fontsize=11; randkir=TB; rankdir=LR; size=""; "ABC" [URL="https://docs.python.org/3/library/abc.html#abc.ABC",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Helper class that provides a standard way to create an ABC using"]; "Action" [URL="../api/negmas.situated.Action.html#negmas.situated.Action",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="An action that an `Agent` can execute in a `World` through the `Simulator`."]; "Adapter" [URL="../api/negmas.situated.Adapter.html#negmas.situated.Adapter",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Represents an adapter agent that makes some included object act as an"]; "Agent" -> "Adapter" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Agent" [URL="../api/negmas.situated.Agent.html#negmas.situated.Agent",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Base class for all agents that can run within a `World` and engage in situated negotiations"]; "Entity" -> "Agent" [arrowsize=0.5,style="setlinewidth(0.5)"]; "EventSink" -> "Agent" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ConfigReader" -> "Agent" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Notifier" -> "Agent" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Rational" -> "Agent" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ABC" -> "Agent" [arrowsize=0.5,style="setlinewidth(0.5)"]; "AgentWorldInterface" [URL="../api/negmas.situated.AgentWorldInterface.html#negmas.situated.AgentWorldInterface",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Agent World Interface class"]; "Breach" [URL="../api/negmas.situated.Breach.html#negmas.situated.Breach",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top"]; "BreachProcessing" [URL="../api/negmas.situated.BreachProcessing.html#negmas.situated.BreachProcessing",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="The way breaches are to be handled"]; "Enum" -> "BreachProcessing" [arrowsize=0.5,style="setlinewidth(0.5)"]; "BulletinBoard" [URL="../api/negmas.situated.BulletinBoard.html#negmas.situated.BulletinBoard",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="The bulletin-board which carries all public information. It consists of sections each with a dictionary of records."]; "EventSource" -> "BulletinBoard" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ConfigReader" -> "BulletinBoard" [arrowsize=0.5,style="setlinewidth(0.5)"]; "CheckpointMixin" [URL="../api/negmas.checkpoints.CheckpointMixin.html#negmas.checkpoints.CheckpointMixin",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Adds the ability to save checkpoints to a `NamedObject`"]; "Condition" [URL="../api/negmas.situated.Condition.html#negmas.situated.Condition",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A representation of a negotiation scenario in which a negotiator can be evaluated"]; "ConfigReader" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled"]; "Contract" [URL="../api/negmas.situated.Contract.html#negmas.situated.Contract",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A agreement definition which encapsulates an agreement with partners and extra information"]; "Entity" [URL="../api/negmas.situated.Entity.html#negmas.situated.Entity",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Defines an entity that is a part of the world but does not participate in the simulation"]; "Enum" [URL="https://docs.python.org/3/library/enum.html#enum.Enum",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Generic enumeration."]; "EventSink" [URL="../api/negmas.events.EventSink.html#negmas.events.EventSink",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="An object capable of receiving events"]; "EventSource" [URL="../api/negmas.events.EventSource.html#negmas.events.EventSource",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="An object capable of raising events"]; "MechanismFactory" [URL="../api/negmas.situated.MechanismFactory.html#negmas.situated.MechanismFactory",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A mechanism creation class. It can invite agents to join a mechanism and then run it."]; "NamedObject" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="The base class of all named entities."]; "NegAgent" [URL="../api/negmas.situated.NegAgent.html#negmas.situated.NegAgent",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Wraps a negotiator for evaluaton"]; "Agent" -> "NegAgent" [arrowsize=0.5,style="setlinewidth(0.5)"]; "NegWorld" [URL="../api/negmas.situated.NegWorld.html#negmas.situated.NegWorld",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A world that runs a list of negotiators in a given scenario to evaluate them"]; "NoContractExecutionMixin" -> "NegWorld" [arrowsize=0.5,style="setlinewidth(0.5)"]; "World" -> "NegWorld" [arrowsize=0.5,style="setlinewidth(0.5)"]; "NegotiationInfo" [URL="../api/negmas.situated.NegotiationInfo.html#negmas.situated.NegotiationInfo",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Saves information about a negotiation"]; "NegotiationRequestInfo" [URL="../api/negmas.situated.NegotiationRequestInfo.html#negmas.situated.NegotiationRequestInfo",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="NegotiationRequestInfo(partners, issues, annotation, uuid, negotiator, requested, extra)"]; "NoContractExecutionMixin" [URL="../api/negmas.situated.NoContractExecutionMixin.html#negmas.situated.NoContractExecutionMixin",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A mixin to add when there is no contract execution"]; "NoResponsesMixin" [URL="../api/negmas.situated.NoResponsesMixin.html#negmas.situated.NoResponsesMixin",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A mixin that can be added to Agent to minimize the number of abstract methods"]; "Notifier" [URL="../api/negmas.events.Notifier.html#negmas.events.Notifier",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="An object that can notify other objects"]; "NamedObject" -> "Notifier" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Operations" [URL="../api/negmas.situated.Operations.html#negmas.situated.Operations",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="An enumeration."]; "Enum" -> "Operations" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Rational" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="A rational object is an object that can have preferences."]; "NamedObject" -> "Rational" [arrowsize=0.5,style="setlinewidth(0.5)"]; "RenegotiationRequest" [URL="../api/negmas.situated.RenegotiationRequest.html#negmas.situated.RenegotiationRequest",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A request for renegotiation."]; "RunningNegotiationInfo" [URL="../api/negmas.situated.RunningNegotiationInfo.html#negmas.situated.RunningNegotiationInfo",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="RunningNegotiationInfo(negotiator, annotation, uuid, extra, my_request)"]; "SimpleWorld" [URL="../api/negmas.situated.SimpleWorld.html#negmas.situated.SimpleWorld",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Represents a simple world with no simulation and sane values for most callbacks and methods."]; "World" -> "SimpleWorld" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ABC" -> "SimpleWorld" [arrowsize=0.5,style="setlinewidth(0.5)"]; "StatsMonitor" [URL="../api/negmas.situated.StatsMonitor.html#negmas.situated.StatsMonitor",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A monitor object capable of receiving stats of a world"]; "Entity" -> "StatsMonitor" [arrowsize=0.5,style="setlinewidth(0.5)"]; "TimeInAgreementMixin" [URL="../api/negmas.situated.TimeInAgreementMixin.html#negmas.situated.TimeInAgreementMixin",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top"]; "World" [URL="../api/negmas.situated.World.html#negmas.situated.World",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Base world class encapsulating a world that runs a simulation with several agents interacting within some"]; "EventSink" -> "World" [arrowsize=0.5,style="setlinewidth(0.5)"]; "EventSource" -> "World" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ConfigReader" -> "World" [arrowsize=0.5,style="setlinewidth(0.5)"]; "NamedObject" -> "World" [arrowsize=0.5,style="setlinewidth(0.5)"]; "CheckpointMixin" -> "World" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ABC" -> "World" [arrowsize=0.5,style="setlinewidth(0.5)"]; "WorldMonitor" [URL="../api/negmas.situated.WorldMonitor.html#negmas.situated.WorldMonitor",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A monitor object capable of monitoring a world. It has read/write access to the world"]; "Entity" -> "WorldMonitor" [arrowsize=0.5,style="setlinewidth(0.5)"]; }