NegWorld

class negmas.situated.NegWorld(*args, domain, types, params=None, agent_names_reveal_type=True, compact=False, no_logs=False, normalize_scores=False, **kwargs)[source]

Bases: negmas.situated.situated.NoContractExecutionMixin, negmas.situated.situated.World

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

Parameters

domain (NegDomain) – The NegDomain specifying all information about the situation in which negotiators are to be evaluated including the partners.
types (List[Union[Negotiator, NegAgent]]) – The negotiator types to be evaluated
params (Optional[List[Optional[Dict[str, Any]]]]) – Any parameters needed to create negotiators
agent_names_reveal_type (bool) – if given the agent name for each negotiator will simply be the negotiator’s type
compact (bool) – If given the system will strive to save memory and minimize logging
no_logs (bool) – disables all logging
kwargs – Any extra arguments to be passed to the World constructor

Attributes Summary

`agreement_fraction`	Fraction of negotiations ending in agreement and leading to signed contracts
`breach_fraction`	Fraction of signed contracts that led to breaches
`breach_level`	The average breach level per contract
`breach_rate`	Fraction of signed contracts that led to breaches
`business_size`	The total business size defined as the total money transferred within the system
`cancellation_fraction`	Fraction of contracts concluded (through negotiation or otherwise) that were cancelled.
`cancellation_rate`	Fraction of contracts concluded (through negotiation or otherwise) that were cancelled.
`cancelled_contracts`	rtype `List`[`Dict`[`str`, `Any`]]
`competitors`
`contract_dropping_fraction`	Fraction of signed contracts that were never executed because they were signed to late to be executable
`contract_err_fraction`	Fraction of signed contracts that caused exception during their execution
`contract_execution_fraction`	Fraction of signed contracts successfully executed with no breaches, or errors
`contract_nullification_fraction`	Fraction of signed contracts were nullified by the system (e.g.
`current_step`
`erred_contracts`	rtype `List`[`Dict`[`str`, `Any`]]
`executed_contracts`	rtype `List`[`Dict`[`str`, `Any`]]
`id`	The unique ID of this entity
`log_folder`
`n_agent_exceptions`	Returns a mapping from agent ID to the total number of exceptions it and its negotiators have raised
`n_contract_exceptions`	Returns a mapping from agent ID to the total number of exceptions it and its negotiators have raised
`n_mechanism_exceptions`	Returns a mapping from agent ID to the total number of exceptions it and its negotiators have raised
`n_negotiation_rounds_failed`	Average number of rounds in a successful negotiation
`n_negotiation_rounds_successful`	Average number of rounds in a successful negotiation
`n_negotiator_exceptions`	Returns a mapping from agent ID to the total number of exceptions its negotiators have raised
`n_simulation_exceptions`	Returns a mapping from agent ID to the total number of exceptions it and its negotiators have raised
`n_total_agent_exceptions`	Returns a mapping from agent ID to the total number of exceptions it and its negotiators have raised
`n_total_simulation_exceptions`	Returns the total number of exceptions per step that are not directly raised by agents or their negotiators.
`name`	A convenient name of the entity (intended primarily for printing/logging/debugging).
`nullified_contracts`	rtype `List`[`Dict`[`str`, `Any`]]
`partners`
`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.
`resolved_breaches`	rtype `List`[`Dict`[`str`, `Any`]]
`saved_breaches`	rtype `List`[`Dict`[`str`, `Any`]]
`saved_contracts`	rtype `List`[`Dict`[`str`, `Any`]]
`saved_negotiations`	rtype `List`[`Dict`[`str`, `Any`]]
`short_type_name`	rtype `str`
`signed_contracts`	rtype `List`[`Dict`[`str`, `Any`]]
`stats`	rtype `Dict`[`str`, `Any`]
`time`	Elapsed time since world started in seconds.
`total_time`	Returns total simulation time (till now) in mx
`type_name`	rtype `str`
`unresolved_breaches`	rtype `List`[`Dict`[`str`, `Any`]]
`uuid`	The unique ID of this entity

Methods Summary

`agreement_rate`(aid)	Fraction of negotiations ending in agreement and leading to signed contracts
`announce`(event)	Raises an event and informs all event sinks that are registered for notifications on this event type
`append_stats`()
`breach_record`(breach)	Converts a breach to a record suitable for storage during the simulation
`call`(agent, method, args, *kwargs)	Calls a method on an agent updating exeption count
`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.
`complete_contract_execution`(contract, ...)	Called after breach resolution is completed for contracts for which some potential breaches occurred.
`contract_record`(contract)	Converts a contract to a record suitable for permanent storage
`contract_size`(contract)	Returns an estimation of the activity level associated with this contract.
`create`(args, *kwargs)	Creates an object and returns a proxy to it.
`delete_executed_contracts`()	Called after processing executable contracts at every simulation step to delete processed contracts
`draw`([steps, what, who, where, together, ...])	Generates a graph showing some aspect of the simulation
`executable_contracts`()	Called at every time-step to get the contracts that are `executable` at this point of the simulation
`execute_action`(action, agent[, callback])	Executes the given action by the given agent
`from_checkpoint`(file_name[, return_info])	Creates an object from a saved checkpoint
`from_config`(config[, section, ...])	Creates an object of this class given the configuration info
`get_dropped_contracts`()	Called at the end of every time-step to get a list of the contracts that are signed but will never be executed
`get_private_state`(agent)	Reads the private state of the given agent
`graph`([steps, what, who, together])	Generates a graph showing some aspect of the simulation
`ignore_contract`(contract[, as_dropped])	Ignores the contract as if it was never agreed upon or as if was dropped
`is_basic_stat`(s)	Checks whether a given statistic is agent specific.
`is_valid_agreement`(negotiation, agreement, ...)	Confirms that the agreement is valid given the world rules.
`is_valid_contract`(contract)	Confirms that the agreement is valid given the world rules.
`join`(x[, simulation_priority])	Add an agent to the world.
`logdebug`(s[, event])	logs debug-level information
`logdebug_agent`(aid, s[, event])	logs debug to the agent individual log
`logerror`(s[, event])	logs error-level information
`logerror_agent`(aid, s[, event])	logs information to the agent individual log
`loginfo`(s[, event])	logs info-level information
`loginfo_agent`(aid, s[, event])	logs information to the agent individual log
`logwarning`(s[, event])	logs warning-level information
`logwarning_agent`(aid, s[, event])	logs warning to the agent individual log
`n_saved_contracts`([ignore_no_issue])	Number of saved contracts
`on_contract_cancelled`(contract)	Called whenever a concluded contract is not signed (cancelled)
`on_contract_concluded`(contract, to_be_signed_at)	Called to add a contract to the existing set of unsigned contract after it is concluded
`on_contract_processed`(contract)	Called whenever a contract finished processing to be removed from unsigned contracts
`on_contract_signed`(contract)	Called to add a contract to the existing set of contract after it is signed
`on_event`(event, sender)	Received when an event is raised
`on_exception`(entity, e)	Called when an exception happens.
`order_contracts_for_execution`(contracts)	Orders the contracts in a specific time-step that are about to be executed
`partner_advantage`(aid)
`partner_utility`(aid)
`post_step_stats`()	Called at the end of the simulation step to update all stats
`pre_step_stats`()	Called at the beginning of the simulation step to prepare stats or update them
`read_config`(config[, section])	Reads the configuration from a file or a dict and prepares it for parsing
`received_advantage`(aid)
`received_utility`(aid)
`register`(x[, simulation_priority])	Registers an entity in the world so it can be looked up by name.
`register_listener`(event_type, listener)	Registers a listener for the given event_type.
`register_stats_monitor`(m)
`register_world_monitor`(m)
`request_negotiation_about`(req_id, caller, ...)	Requests to start a negotiation with some other agents
`run`()	Runs the simulation until it ends
`run_negotiation`(caller, issues, partners, ...)	Runs a negotiation until completion
`run_negotiations`(caller, issues, partners, ...)	Requests to run a set of negotiations simultaneously.
`run_with_progress`([callback])	Runs the simulation showing progress, with optional callback
`save_config`(file_name)	Saves the config of the world as a yaml file
`save_gif`([path, what, who, together, ...])	rtype `None`
`set_bulletin_board`(bulletin_board)
`simulation_step`(stage)	A single step of the simulation.
`spawn`([spawn_as, spawn_params])
`spawn_object`(args, *kwargs)
`start_contract_execution`(contract)	Tries to execute the contract
`step`()	A single simulation step
`unregister_stats_monitor`(m)
`unregister_world_monitor`(m)
`update_stats`(stage)	Called to update any custom stats that the world designer wants to keep

Attributes Documentation

agreement_fraction

Fraction of negotiations ending in agreement and leading to signed contracts

Return type: float

breach_fraction

Fraction of signed contracts that led to breaches

Return type: float

breach_level

The average breach level per contract

Return type: float

breach_rate

Fraction of signed contracts that led to breaches

Return type: float

business_size

The total business size defined as the total money transferred within the system

Return type: float

cancellation_fraction

Fraction of contracts concluded (through negotiation or otherwise) that were cancelled.

Return type: float

cancellation_rate

Fraction of contracts concluded (through negotiation or otherwise) that were cancelled.

Return type: float

cancelled_contracts

Return type: List[Dict[str, Any]]

competitors

contract_dropping_fraction

Fraction of signed contracts that were never executed because they were signed to late to be executable

Return type: float

contract_err_fraction

Fraction of signed contracts that caused exception during their execution

Return type: float

contract_execution_fraction

Fraction of signed contracts successfully executed with no breaches, or errors

Return type: float

contract_nullification_fraction

Fraction of signed contracts were nullified by the system (e.g. due to bankruptcy)

Return type: float

current_step

erred_contracts

Return type: List[Dict[str, Any]]

executed_contracts

Return type: List[Dict[str, Any]]

id: The unique ID of this entity

log_folder

n_agent_exceptions

Returns a mapping from agent ID to the total number of exceptions it and its negotiators have raised

Return type: Dict[str, int]

n_contract_exceptions

Returns a mapping from agent ID to the total number of exceptions it and its negotiators have raised

Return type: Dict[int, int]

n_mechanism_exceptions

Returns a mapping from agent ID to the total number of exceptions it and its negotiators have raised

Return type: Dict[int, int]

n_negotiation_rounds_failed

Average number of rounds in a successful negotiation

Return type: float

n_negotiation_rounds_successful

Average number of rounds in a successful negotiation

Return type: float

n_negotiator_exceptions

Returns a mapping from agent ID to the total number of exceptions its negotiators have raised

Return type: Dict[str, int]

n_simulation_exceptions

Returns a mapping from agent ID to the total number of exceptions it and its negotiators have raised

Return type: Dict[int, int]

n_total_agent_exceptions

Returns a mapping from agent ID to the total number of exceptions it and its negotiators have raised

Return type: Dict[str, int]

n_total_simulation_exceptions

Returns the total number of exceptions per step that are not directly raised by agents or their negotiators.

Remarks:

This property sums the totals of n_simulation_exceptions, n_contract_exceptions, and n_mechanism_exceptions

Return type: Dict[int, int]

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

nullified_contracts

Return type: List[Dict[str, Any]]

partners

relative_time

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

Return type: float

remaining_steps

Returns the remaining number of steps until the end of the mechanism run. None if unlimited

Return type: Optional[int]

remaining_time

Returns remaining time in seconds. None if no time limit is given.

Return type: Optional[float]

resolved_breaches

Return type: List[Dict[str, Any]]

saved_breaches

Return type: List[Dict[str, Any]]

saved_contracts

Return type: List[Dict[str, Any]]

saved_negotiations

Return type: List[Dict[str, Any]]

short_type_name

Return type: str

signed_contracts

Return type: List[Dict[str, Any]]

stats

Return type: Dict[str, Any]

time

Elapsed time since world started in seconds. 0.0 if the world did not start running

Return type: Optional[float]

total_time: Returns total simulation time (till now) in mx

type_name

Return type: str

unresolved_breaches

Return type: List[Dict[str, Any]]

uuid: The unique ID of this entity

Methods Documentation

agreement_rate(aid)[source]: Fraction of negotiations ending in agreement and leading to signed contracts

announce(event): Raises an event and informs all event sinks that are registered for notifications on this event type

append_stats()

breach_record(breach)[source]

Converts a breach to a record suitable for storage during the simulation

Return type: Dict[str, Any]

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

Calls a method on an agent updating exeption count

Parameters

agent (Agent) – The agent on which the method is to be called
method (Callable) – The bound method (bound to the agent)
*args – position arguments
**kwargs – keyword arguments

Return type

Any

Returns

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

checkpoint_final_step()

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.

Return type: Optional[Path]

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

Returns:

Return type: dict[str, Any]

checkpoint_init(step_attrib='current_step', every=1, folder=None, filename=None, info=None, exist_ok=True, single=True)

Initializes the object to automatically save a checkpoint

Parameters

step_attrib (str) – The attribute that defines the current step. If None, there is no step concept
every (int) – Number of steps per checkpoint. If < 1 no checkpoints will be saved
folder (Optional[PathLike]) – The directory to store checkpoints under
filename (Optional[str]) – 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 (Optional[Dict[str, Any]]) – Any extra information to save in the json file associated with each checkpoint
exist_ok (bool) – Override existing files if any
single (bool) – If True, only the most recent checkpoint will be kept

Remarks:

single_checkpoint implies exist_ok

checkpoint_on_step_started()

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

Return type: Optional[Path]
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

complete_contract_execution(contract, breaches, resolution)[source]

Called after breach resolution is completed for contracts for which some potential breaches occurred.

Parameters

contract (Contract) – The contract considered.
breaches (List[Breach]) – The list of potential breaches that was generated by _execute_contract.
resolution (Contract) – The agreed upon resolution

Returns:

Return type: None

contract_record(contract)[source]

Converts a contract to a record suitable for permanent storage

Return type: Dict[str, Any]

contract_size(contract)[source]

Returns an estimation of the activity level associated with this contract. Higher is better :type contract: Contract :param contract:

Returns:

Return type: float

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

delete_executed_contracts()[source]

Called after processing executable contracts at every simulation step to delete processed contracts

Return type: None

draw(steps=None, what=['negotiation-requests-rejected', 'negotiation-requests-accepted', 'negotiations-rejected', 'negotiations-started', 'negotiations-failed', 'contracts-concluded', 'contracts-cancelled', 'contracts-signed', 'contracts-breached', 'contracts-executed'], who=None, where=None, together=True, axs=None, ncols=4, figsize=(15, 15), show_node_labels=True, show_edge_labels=True, **kwargs)

Generates a graph showing some aspect of the simulation

Parameters

steps (Union[Tuple[int, int], int, None]) – The step/steps to generate the graphs for. If a tuple is given all edges within the given range (inclusive beginning, exclusive end) will be accomulated
what (Collection[str]) – The edges to have on the graph. Options are: negotiations, concluded, signed, executed
who (Optional[Callable[[Agent], bool]]) – Either a callable that receives an agent and returns True if it is to be shown or None for all
where (Optional[Callable[[Agent], Union[int, Tuple[float, float]]]]) – A callable that returns for each agent the position it showed by drawn at either as an integer specifying the column in which to draw the column or a tuple of two floats specifying the position within the drawing area of the agent. If None, the default Networkx layout will be used.
together (bool) – IF specified all edge types are put in the same graph.
axs (Optional[Collection[Axis]]) – The axes used for drawing. If together is true, it should be a single Axis object otherwise it should be a list of Axis objects with the same length as what.
show_node_labels – show node labels!
show_edge_labels – show edge labels!
kwargs – passed to networx.draw_networkx

Return type

Union[Tuple[Axis, Graph], Tuple[Axis, List[Graph]]]

Returns

A networkx graph representing the world if together==True else a list of graphs one for each item in what

executable_contracts()[source]

Called at every time-step to get the contracts that are executable at this point of the simulation

Return type: Collection[Contract]

execute_action(action, agent, callback=None)[source]

Executes the given action by the given agent

Return type: bool

classmethod from_checkpoint(file_name, return_info=False)

Creates an object from a saved checkpoint

Parameters

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

classmethod from_config(config, section=None, ignore_children=True, try_parsing_children=True, scope=None)

Creates an object of this class given the configuration info

Parameters

config (Union[str, dict]) – Either a file name or a dictionary
section (Optional[str]) – A section in the file or a key in the dictionary to use for loading params
ignore_children (bool) – If true then children will be ignored and there will be a single return
try_parsing_children (bool) – If true the children will first be parsed as ConfigReader classes if they are not
int (simple types (e.g.) –
str –
float –
Iterable[int|str|float] –
scope – The scope at which to evaluate any child classes. This MUST be passed as scope=globals() if you are
parsed. (having any children that are to be) –

Returns

An object of cls if ignore_children is True or a tuple with an object of cls and a dictionary with children that were not parsed.

Remarks:

This function will return an object of its class after passing the key-value pairs found in the config to the init function.

Requiring passing scope=globals() to this function is to get around the fact that in python eval() will be called with a globals dictionary based on the module in which the function is defined not called. This means that in general when eval() is called to create the children, it will not have access to the class definitions of these children (except if they happen to be imported in this file). To avoid this problem causing an undefined_name exception, the caller must pass her globals() as the scope.

get_dropped_contracts()

Called at the end of every time-step to get a list of the contracts that are signed but will never be executed

Return type: Collection[Contract]

get_private_state(agent)[source]

Reads the private state of the given agent

Return type: dict

graph(steps=None, what=['negotiation-requests-rejected', 'negotiation-requests-accepted', 'negotiations-rejected', 'negotiations-started', 'negotiations-failed', 'negotiations-succeeded', 'contracts-concluded', 'contracts-cancelled', 'contracts-signed', 'contracts-nullified', 'contracts-erred', 'contracts-breached', 'contracts-executed'], who=None, together=True)

Generates a graph showing some aspect of the simulation

Parameters

steps (Union[Tuple[int, int], int, None]) – The step/steps to generate the graphs for. If a tuple is given all edges within the given range (inclusive beginning, exclusive end) will be accumulated
what (Collection[str]) – The edges to have on the graph. Options are: negotiations, concluded, signed, executed
who (Optional[Callable[[Agent], bool]]) – Either a callable that receives an agent and returns True if it is to be shown or None for all
together (bool) – IF specified all edge types are put in the same graph.

Return type

Union[Graph, List[Graph]]

Returns

A networkx graph representing the world if together==True else a list of graphs one for each item in what

ignore_contract(contract, as_dropped=False)

Ignores the contract as if it was never agreed upon or as if was dropped

Parameters

contract – The contract to ignore
as_dropped – If true, the contract is treated as a dropped invalid contract, otherwise it is treated as if it never happened.

classmethod is_basic_stat(s)

Checks whether a given statistic is agent specific.

Return type: bool

is_valid_agreement(negotiation, agreement, mechanism)

Confirms that the agreement is valid given the world rules.

Parameters

negotiation (NegotiationInfo) – The NegotiationInfo that led to the agreement
agreement (tuple) – The agreement
mechanism (Mechanism) – The mechanism that led to the agreement

Return type

bool

Returns

Returns True for valid agreements and False for invalid agreements

Remarks:

This test is conducted before the agents are asked to sign the corresponding contract

Invalid agreements will be treated as never happened and agents will not be asked to sign it

is_valid_contract(contract)

Confirms that the agreement is valid given the world rules.

Parameters: contract (Contract) – The contract being tested
Return type: bool
Returns: Returns True for valid contracts and False for invalid contracts

Remarks:

This test will be conducted after agents are asked to sign the contract and only for signed contracts.

If False is returned, the contract will considered unsigned and will be recorded as a concluded but not signed contract with no rejectors

join(x, simulation_priority=0, **kwargs)

Add an agent to the world.

Parameters

x (Agent) – The agent to be registered
simulation_priority (int) – The simulation priority. Entities with lower pprioritieswill be stepped first during
kwargs – Any key-value pairs specifying attributes of the agent. NegMAS internally uses the attribute ‘color’ when drawing the agent in draw

Returns:

logdebug(s, event=None)

logs debug-level information

Parameters

s (str) – The string to log
event (Event) – The event to announce after logging

Return type

None

logdebug_agent(aid, s, event=None)

logs debug to the agent individual log

Parameters

s (str) – The string to log
event (Event) – The event to announce after logging

Return type

None

logerror(s, event=None)

logs error-level information

Parameters

s (str) – The string to log
event (Event) – The event to announce after logging

Return type

None

logerror_agent(aid, s, event=None)

logs information to the agent individual log

Parameters

s (str) – The string to log
event (Event) – The event to announce after logging

Return type

None

loginfo(s, event=None)

logs info-level information

Parameters

s (str) – The string to log
event (Event) – The event to announce after logging

Return type

None

loginfo_agent(aid, s, event=None)

logs information to the agent individual log

Parameters

s (str) – The string to log
event (Event) – The event to announce after logging

Return type

None

logwarning(s, event=None)

logs warning-level information

Parameters

s (str) – The string to log
event (Event) – The event to announce after logging

Return type

None

logwarning_agent(aid, s, event=None)

logs warning to the agent individual log

Parameters

s (str) – The string to log
event (Event) – The event to announce after logging

Return type

None

n_saved_contracts(ignore_no_issue=True)

Number of saved contracts

Parameters: ignore_no_issue (bool) – If true, only contracts resulting from negotiation (has some issues) will be counted
Return type: int

on_contract_cancelled(contract)

Called whenever a concluded contract is not signed (cancelled)

Parameters: contract – The contract to add

Remarks:

By default this function just adds the contract to the set of contracts maintaned by the world.

You should ALWAYS call this function when overriding it.

on_contract_concluded(contract, to_be_signed_at)

Called to add a contract to the existing set of unsigned contract after it is concluded

Parameters

contract (Contract) – The contract to add
to_be_signed_at (int) – The timestep at which the contract is to be signed

Remarks:

By default this function just adds the contract to the set of contracts maintaned by the world.

You should ALWAYS call this function when overriding it.

Return type: None

on_contract_processed(contract)

Called whenever a contract finished processing to be removed from unsigned contracts

Parameters: contract – Contract

Remarks:

called by on_contract_cancelled and on_contract_signed

on_contract_signed(contract)

Called to add a contract to the existing set of contract after it is signed

Parameters: contract (Contract) – The contract to add
Return type: bool
Returns: True if everything went OK and False otherwise

Remarks:

By default this function just adds the contract to the set of contracts maintaned by the world.

You should ALWAYS call this function when overriding it.

on_event(event, sender): Received when an event is raised

on_exception(entity, e)

Called when an exception happens.

Parameters

entity (Entity) – The entity that caused the exception
e (Exception) – The exception

Return type

None

order_contracts_for_execution(contracts)[source]

Orders the contracts in a specific time-step that are about to be executed

Return type: Collection[Contract]

partner_advantage(aid)[source]

partner_utility(aid)[source]

post_step_stats()[source]

Called at the end of the simulation step to update all stats

Kept for backward compatibility and will be dropped. Override update_stats ins

pre_step_stats()[source]

Called at the beginning of the simulation step to prepare stats or update them

Kept for backward compatibility and will be dropped. Override update_stats instead

classmethod read_config(config, section=None)

Reads the configuration from a file or a dict and prepares it for parsing

Parameters

config (Union[str, dict]) – Either a file name or a dictionary
section (Optional[str]) – A section in the file or a key in the dictionary to use for loading params

Return type

dict[str, Any]

Returns

A dict ready to be parsed by from_config

Remarks:

received_advantage(aid)[source]

received_utility(aid)[source]

register(x, simulation_priority=0)

Registers an entity in the world so it can be looked up by name. Should not be called directly

Parameters

x (Entity) – The entity to be registered
simulation_priority (int) – The simulation periority. Entities with lower periorities will be stepped first during

Returns:

register_listener(event_type, listener)

Registers a listener for the given event_type.

Parameters

event_type (Optional[str]) – The type to register. If None, the listener will be registered for all types
listener (EventSink) – The listening agent (must have an on_event method that receives an event: Event and a sender: EventSource)

register_stats_monitor(m)

register_world_monitor(m)

request_negotiation_about(req_id, caller, issues, partners, roles=None, annotation=None, mechanism_name=None, mechanism_params=None, group=None)

Requests to start a negotiation with some other agents

Parameters

req_id (str) – An ID For the request that is unique to the caller
caller (Agent) – The agent requesting the negotiation
partners (List[Union[str, Agent]]) – A list of partners to participate in the negotiation. Note that the caller itself may not be in this list which makes it possible for an agent to request a negotaition that it does not participate in. If that is not to be allowed in some world, override this method and explicitly check for these kinds of negotiations and return False. If partners is passed as a single string/Agent or as a list containing a single string/Agent, then he caller will be added at the beginning of the list. This will only be done if roles was passed as None.
issues (List[Issue]) – Negotiation issues
annotation (Optional[Dict[str, Any]]) – Extra information to be passed to the partners when asking them to join the negotiation
partners – A list of partners to participate in the negotiation
roles (Optional[List[str]]) – The roles of different partners. If None then each role for each partner will be None
mechanism_name (Optional[str]) – Name of the mechanism to use. It must be one of the mechanism_names that are supported by the
None (must also be) –
my_role (then roles and) –
None –
mechanism_params (Optional[Dict[str, Any]]) – A dict of parameters used to initialize the mechanism object
group (Optional[str]) – An identifier for the group to which the negotiation belongs. This is not not used by the system.

Return type

bool

Returns

None. The caller will be informed by a callback function on_neg_request_accepted or on_neg_request_rejected about the status of the negotiation.

run(): Runs the simulation until it ends

run_negotiation(caller, issues, partners, negotiator, preferences=None, caller_role=None, roles=None, annotation=None, mechanism_name=None, mechanism_params=None)

Runs a negotiation until completion

Parameters

caller (Agent) – The agent requesting the negotiation
partners (Collection[Union[str, Agent]]) – A list of partners to participate in the negotiation. Note that the caller itself may not be in this list which makes it possible for an agent to request a negotaition that it does not participate in. If that is not to be allowed in some world, override this method and explicitly check for these kinds of negotiations and return False. If partners is passed as a single string/Agent or as a list containing a single string/Agent, then he caller will be added at the beginning of the list. This will only be done if roles was passed as None.
negotiator (Negotiator) – The negotiator to be used in the negotiation
preferences (Optional[Preferences]) – The utility function. Only needed if the negotiator does not already know it
caller_role (Optional[str]) – The role of the caller in the negotiation
issues (Collection[Issue]) – Negotiation issues
annotation (Optional[Dict[str, Any]]) – Extra information to be passed to the partners when asking them to join the negotiation
partners – A list of partners to participate in the negotiation
roles (Optional[Collection[str]]) – The roles of different partners. If None then each role for each partner will be None
mechanism_name (Optional[str]) – Name of the mechanism to use. It must be one of the mechanism_names that are supported by the
None (must also be) –
my_role (then roles and) –
None –
mechanism_params (Optional[Dict[str, Any]]) – A dict of parameters used to initialize the mechanism object

Return type

Tuple[Optional[Contract], Optional[NegotiatorMechanismInterface]]

Returns

A Tuple of a contract and the nmi of the mechanism used to get it in case of success. None otherwise

run_negotiations(caller, issues, partners, negotiators, preferences=None, caller_roles=None, roles=None, annotations=None, mechanism_names=None, mechanism_params=None, all_or_none=False)

Requests to run a set of negotiations simultaneously. Returns after all negotiations are run to completion

Parameters

caller (Agent) – The agent requesting the negotiation
partners (List[List[Union[str, Agent]]]) – A list of list of partners to participate in the negotiation. Note that the caller itself may not be in this list which makes it possible for an agent to request a negotaition that it does not participate in. If that is not to be allowed in some world, override this method and explicitly check for these kinds of negotiations and return False. If partners[i] is passed as a single string/Agent or as a list containing a single string/Agent, then he caller will be added at the beginning of the list. This will only be done if roles was passed as None.
issues (Union[List[Issue], List[List[Issue]]]) – Negotiation issues
negotiators (List[Negotiator]) – The negotiator to be used in the negotiation
ufuns – The utility function. Only needed if the negotiator does not already know it
caller_roles (Optional[List[str]]) – The role of the caller in the negotiation
annotations (Optional[List[Optional[Dict[str, Any]]]]) – Extra information to be passed to the partners when asking them to join the negotiation
partners – A list of partners to participate in the negotiation
roles (Optional[List[Optional[List[str]]]]) – The roles of different partners. If None then each role for each partner will be None
mechanism_names (Union[str, List[str], None]) – Name of the mechanism to use. It must be one of the mechanism_names that are supported by the
None (must also be) –
my_role (then roles and) –
None –
mechanism_params (Union[Dict[str, Any], List[Dict[str, Any]], None]) – A dict of parameters used to initialize the mechanism object
all_of_none – If True, ALL partners must agree to negotiate to go through.

Returns

contract (None for failure) and nmi (The mechanism info [None if the partner refused the negotiation])

Return type

A list of tuples each with two values

run_with_progress(callback=None)

Runs the simulation showing progress, with optional callback

Return type: None

save_config(file_name)

Saves the config of the world as a yaml file

Parameters: file_name (str) – Name of file to save the config to

Returns:

save_gif(path=None, what=['negotiation-requests-rejected', 'negotiation-requests-accepted', 'negotiations-rejected', 'negotiations-started', 'negotiations-failed', 'negotiations-succeeded', 'contracts-concluded', 'contracts-cancelled', 'contracts-signed', 'contracts-nullified', 'contracts-erred', 'contracts-breached', 'contracts-executed'], who=None, together=True, draw_every=1, fps=5)

Return type: None

set_bulletin_board(bulletin_board)

simulation_step(stage)[source]

A single step of the simulation.

Parameters: stage – How many times so far was this method called within the current simulation step

Remarks:

Using the stage parameter, it is possible to have Operations . SimulationStep several times with the list of operations while differentiating between these calls.

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

classmethod spawn_object(*args, **kwargs)

start_contract_execution(contract)[source]

Tries to execute the contract

Parameters: contract (Contract) –
Returns: The set of breaches committed if any. If there are no breaches return an empty set
Return type: Set[Breach]

Remarks:

You must call super() implementation of this method before doing anything

It is possible to return None which indicates that the contract was nullified (i.e. not executed due to a reason other than an execution exeception).

step()

A single simulation step

Return type: bool

unregister_stats_monitor(m)

unregister_world_monitor(m)

update_stats(stage)

Called to update any custom stats that the world designer wants to keep

Parameters: stage (int) – How many times was this method called during this stage

Remarks:

Default behavior is: - If Operations . StatsUpdate appears once in operations, it calls post_step_stats once - Otherwise: it calls pre_step_stats for stage 0, and post_step_stats for any other stage.