World

class negmas.situated.World(bulletin_board: Optional[negmas.situated.situated.BulletinBoard] = None, n_steps=10000, time_limit=3600, negotiation_speed=None, neg_n_steps=100, neg_time_limit=180, neg_step_time_limit=60, shuffle_negotiations=True, negotiation_quota_per_step=inf, negotiation_quota_per_simulation=inf, default_signing_delay=1, force_signing=False, batch_signing=True, breach_processing=<BreachProcessing.NONE: 0>, mechanisms: Optional[Dict[str, Dict[str, Any]]] = None, awi_type: str = 'negmas.situated.AgentWorldInterface', start_negotiations_immediately: bool = False, log_folder=None, log_to_file=True, log_ufuns=False, log_negotiations: bool = False, log_to_screen: bool = False, log_stats_every: int = 0, log_file_level=10, log_screen_level=40, no_logs=False, event_file_name='events.json', event_types=None, log_file_name='log.txt', save_signed_contracts: bool = True, save_cancelled_contracts: bool = True, save_negotiations: bool = True, save_resolved_breaches: bool = True, save_unresolved_breaches: bool = True, ignore_agent_exceptions: bool = False, ignore_negotiation_exceptions: bool = False, ignore_contract_execution_exceptions: bool = False, ignore_simulation_exceptions: bool = False, safe_stats_monitoring: bool = False, construct_graphs: bool = 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, operations: Collection[negmas.situated.situated.Operations] = (<Operations.StatsUpdate: 6>, <Operations.Negotiations: 1>, <Operations.ContractSigning: 2>, <Operations.AgentSteps: 3>, <Operations.ContractExecution: 4>, <Operations.SimulationStep: 5>, <Operations.ContractSigning: 2>, <Operations.StatsUpdate: 6>), info: Optional[Dict[str, Any]] = None, genius_port: int = 25337, disable_agent_printing: bool = False, name: Optional[str] = None, id: Optional[str] = None)[source]

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

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

A world maintains its own session.

Parameters
  • General * (*) –

  • name – World Name

  • bulletin_board – A bulletin board object to use. If not given one will be created

  • awi_type – The type used for agent world interfaces (must descend from or behave like AgentWorldInterface )

  • info – A dictionary of key-value pairs that is kept within the world but never used. It is useful for storing contextual information. For example, when running tournaments.

  • Simulation parameters * (*) –

  • n_steps – Total simulation time in steps

  • time_limit – Real-time limit on the simulation

  • operations – A list of Operations to run in order during every simulation step

  • Negotiation Parameters * (*) –

  • negotiation_speed – The number of negotiation steps per simulation step. None means infinite

  • neg_n_steps – Maximum number of steps allowed for a negotiation.

  • neg_step_time_limit – Time limit for single step of the negotiation protocol.

  • neg_time_limit – Real-time limit on each single negotiation.

  • shuffle_negotiations – Whether negotiations are shuffled everytime when stepped.

  • negotiation_quota_per_step – Number of negotiations an agent is allowed to start per step

  • negotiation_quota_per_simulation – Number of negotiations an agent is allowed to start in the simulation

  • start_negotiations_immediately – If true negotiations start immediately when registered rather than waiting for the next step

  • mechanisms – The mechanism types allowed in this world associated with each keyward arguments to be passed to it.

  • Signing parameters * (*) –

  • default_signing_delay – The default number of steps between contract conclusion and signing it. Only takes effect if force_signing is False

  • force_signing – If true, agents are not asked to sign contracts. They are forced to do so. In this case, default_singing_delay is not effective and signature is immediate

  • batch_signing – If true, contracts are signed in batches not individually

  • Breach Processing * (*) –

  • breach_processing – How to handle breaches. Can be any of BreachProcessing values

  • Logging * (*) –

  • log_folder – Folder to save all logs

  • log_to_file – If true, will log to a file

  • log_file_name – Name of the log file

  • log_file_level – The log-level to save to file (WARNING, ERROR, INFO, DEBUG, CRITICAL, …)

  • log_ufuns – Log utility functions

  • log_negotiations – Log all negotiation events

  • log_to_screen – Whether to log to screen

  • log_screen_level – The log-level to show on screen (WARNING, ERROR, INFO, DEBUG, CRITICAL, …)

  • no_logs – If True, All logging will be disabled no matter what other options are given.

  • log_stats_every – If nonzero and positive, the period of saving stats

  • construct_graphs – If true, information needed to draw graphs using draw method are kept.

  • event_file_name – If not None, the file-name to store events into.

  • event_types – Types of events to log

  • What to save * (*) –

  • save_signed_contracts – Save all signed contracts

  • save_cancelled_contracts – Save all cancelled contracts

  • save_negotiations – Save all negotiation records

  • save_resolved_breaches – Save all resolved breaches

  • save_unresolved_breaches – Save all unresolved breaches

  • Exception Handling * (*) –

  • ignore_agent_exceptions – Ignore agent exceptions and keep running

  • ignore_negotiation_exceptions – If true, all mechanism exceptions are ignored and the mechanism is aborted

  • ignore_simulation_exceptions – Ignore simulation exceptions and keep running

  • ignore_contract_execution_exceptions – Ignore contract execution exceptions and keep running

  • safe_stats_monitoring – Never throw an exception for a failure to save stats or because of a Stats Monitor object

  • Checkpoints * (*) –

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

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

Attributes Summary

agreement_fraction

Fraction of negotiations ending in agreement and leading to signed contracts

agreement_rate

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

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

executed_contracts

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.

nullified_contracts

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

saved_breaches

saved_contracts

saved_negotiations

signed_contracts

stats

time

Elapsed time since world started in seconds.

total_time

Returns total simulation time (till now) in mx

unresolved_breaches

Methods Summary

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

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.

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

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

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

register(x[, simulation_priority])

Registers an entity in the world so it can be looked up by name.

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, …])

set_bulletin_board(bulletin_board)

simulation_step([stage])

A single step of the simulation.

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

agreement_rate

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
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. due to bankruptcy)

current_step
erred_contracts
executed_contracts
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.

Remarks:
nullified_contracts
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.

resolved_breaches
saved_breaches
saved_contracts
saved_negotiations
signed_contracts
stats
time

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

total_time

Returns total simulation time (till now) in mx

unresolved_breaches

Methods Documentation

append_stats()[source]
abstract breach_record(breach: negmas.situated.Breach)Dict[str, Any][source]

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

call(agent: negmas.situated.Agent, method: Callable, *args, **kwargs)Any[source]

Calls a method on an agent updating exeption count

Parameters
  • agent – The agent on which the method is to be called

  • method – The bound method (bound to the agent)

  • *args – position arguments

  • **kwargs – keyword arguments

Returns

whatever method returns

abstract complete_contract_execution(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach], resolution: negmas.situated.Contract)None[source]

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

Parameters
  • contract – The contract considered.

  • breaches – The list of potential breaches that was generated by _execute_contract.

  • resolution – The agreed upon resolution

Returns:

abstract contract_record(contract: negmas.situated.Contract)Dict[str, Any][source]

Converts a contract to a record suitable for permanent storage

abstract contract_size(contract: negmas.situated.Contract)float[source]

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

Returns:

abstract delete_executed_contracts()None[source]

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

draw(steps: Optional[Union[Tuple[int, int], int]] = None, what: Collection[str] = ['negotiation-requests-rejected', 'negotiation-requests-accepted', 'negotiations-rejected', 'negotiations-started', 'negotiations-failed', 'contracts-concluded', 'contracts-cancelled', 'contracts-signed', 'contracts-breached', 'contracts-executed'], who: Optional[Callable[[negmas.situated.Agent], bool]] = None, where: Optional[Callable[[negmas.situated.Agent], Union[int, Tuple[float, float]]]] = None, together: bool = True, axs: Optional[Collection[matplotlib.axis.Axis]] = None, ncols: int = 4, figsize: Tuple[int, int] = (15, 15), show_node_labels=True, show_edge_labels=True, **kwargs)Union[Tuple[matplotlib.axis.Axis, networkx.classes.graph.Graph], Tuple[matplotlib.axis.Axis, List[networkx.classes.graph.Graph]]][source]

Generates a graph showing some aspect of the simulation

Parameters
  • steps – 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 – The edges to have on the graph. Options are: negotiations, concluded, signed, executed

  • who – Either a callable that receives an agent and returns True if it is to be shown or None for all

  • where – 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 – IF specified all edge types are put in the same graph.

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

Returns

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

abstract executable_contracts()Collection[negmas.situated.Contract][source]

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

abstract execute_action(action: negmas.situated.Action, agent: negmas.situated.Agent, callback: Optional[Callable] = None)bool[source]

Executes the given action by the given agent

get_dropped_contracts()Collection[negmas.situated.Contract][source]

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

abstract get_private_state(agent: negmas.situated.Agent)dict[source]

Reads the private state of the given agent

graph(steps: Optional[Union[Tuple[int, int], int]] = None, what: Collection[str] = ['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: Optional[Callable[[negmas.situated.Agent], bool]] = None, together: bool = True)Union[networkx.classes.graph.Graph, List[networkx.classes.graph.Graph]][source]

Generates a graph showing some aspect of the simulation

Parameters
  • steps – 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 – The edges to have on the graph. Options are: negotiations, concluded, signed, executed

  • who – Either a callable that receives an agent and returns True if it is to be shown or None for all

  • together – IF specified all edge types are put in the same 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)[source]

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: str)bool[source]

Checks whether a given statistic is agent specific.

is_valid_agreement(negotiation: negmas.situated.NegotiationInfo, agreement: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]], mechanism: negmas.mechanisms.Mechanism)bool[source]

Confirms that the agreement is valid given the world rules.

Parameters
  • negotiation – The NegotiationInfo that led to the agreement

  • agreement – The agreement

  • mechanism – The mechanism that led to the agreement

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: negmas.situated.Contract)bool[source]

Confirms that the agreement is valid given the world rules.

Parameters

contract – The contract being tested

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: negmas.situated.Agent, simulation_priority: int = 0, **kwargs)[source]

Add an agent to the world.

Parameters
  • x – The agent to be registered

  • simulation_priority – 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: str, event: Optional[negmas.events.Event] = None)None[source]

logs debug-level information

Parameters
  • s (str) – The string to log

  • event (Event) – The event to announce after logging

logdebug_agent(aid: str, s: str, event: Optional[negmas.events.Event] = None)None[source]

logs debug to the agent individual log

Parameters
  • s (str) – The string to log

  • event (Event) – The event to announce after logging

logerror(s: str, event: Optional[negmas.events.Event] = None)None[source]

logs error-level information

Parameters
  • s (str) – The string to log

  • event (Event) – The event to announce after logging

logerror_agent(aid: str, s: str, event: Optional[negmas.events.Event] = None)None[source]

logs information to the agent individual log

Parameters
  • s (str) – The string to log

  • event (Event) – The event to announce after logging

loginfo(s: str, event: Optional[negmas.events.Event] = None)None[source]

logs info-level information

Parameters
  • s (str) – The string to log

  • event (Event) – The event to announce after logging

loginfo_agent(aid: str, s: str, event: Optional[negmas.events.Event] = None)None[source]

logs information to the agent individual log

Parameters
  • s (str) – The string to log

  • event (Event) – The event to announce after logging

logwarning(s: str, event: Optional[negmas.events.Event] = None)None[source]

logs warning-level information

Parameters
  • s (str) – The string to log

  • event (Event) – The event to announce after logging

logwarning_agent(aid: str, s: str, event: Optional[negmas.events.Event] = None)None[source]

logs warning to the agent individual log

Parameters
  • s (str) – The string to log

  • event (Event) – The event to announce after logging

n_saved_contracts(ignore_no_issue: bool = True)int[source]

Number of saved contracts

Parameters

ignore_no_issue – If true, only contracts resulting from negotiation (has some issues) will be counted

on_contract_cancelled(contract)[source]

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: negmas.situated.Contract, to_be_signed_at: int)None[source]

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

Parameters
  • contract – The contract to add

  • to_be_signed_at – 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.

on_contract_processed(contract)[source]

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: negmas.situated.Contract)bool[source]

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

Parameters

contract – The contract to add

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: negmas.events.Event, sender: negmas.events.EventSource)[source]

Received when an event is raised

on_exception(entity: negmas.situated.Entity, e: Exception)None[source]

Called when an exception happens.

Parameters
  • entity – The entity that caused the exception

  • e – The exception

abstract order_contracts_for_execution(contracts: Collection[negmas.situated.Contract])Collection[negmas.situated.Contract][source]

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

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

register(x: negmas.situated.Entity, simulation_priority: int = 0)[source]

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

Parameters
  • x – The entity to be registered

  • simulation_priority – The simulation periority. Entities with lower periorities will be stepped first during

Returns:

register_stats_monitor(m: negmas.situated.StatsMonitor)[source]
register_world_monitor(m: negmas.situated.WorldMonitor)[source]
request_negotiation_about(req_id: str, caller: negmas.situated.Agent, issues: List[negmas.outcomes.Issue], partners: List[Union[str, negmas.situated.Agent]], roles: Optional[List[str]] = None, annotation: Optional[Dict[str, Any]] = None, mechanism_name: Optional[str] = None, mechanism_params: Optional[Dict[str, Any]] = None, group: Optional[str] = None)bool[source]

Requests to start a negotiation with some other agents

Parameters
  • req_id – An ID For the request that is unique to the caller

  • caller – The agent requesting the negotiation

  • partners – 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 – Negotiation issues

  • annotation – 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 – The roles of different partners. If None then each role for each partner will be None

  • mechanism_name – Name of the mechanism to use. It must be one of the mechanism_names that are supported by the

  • or None which means that the World should select the mechanism. If None (World) –

  • roles and my_role (then) –

  • also be None (must) –

  • mechanism_params – A dict of parameters used to initialize the mechanism object

  • group – An identifier for the group to which the negotiation belongs. This is not not used by the system.

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()[source]

Runs the simulation until it ends

run_negotiation(caller: negmas.situated.Agent, issues: Collection[negmas.outcomes.Issue], partners: Collection[Union[str, negmas.situated.Agent]], negotiator: negmas.negotiators.Negotiator, ufun: Optional[negmas.utilities.UtilityFunction] = None, caller_role: Optional[str] = None, roles: Optional[Collection[str]] = None, annotation: Optional[Dict[str, Any]] = None, mechanism_name: Optional[str] = None, mechanism_params: Optional[Dict[str, Any]] = None)Tuple[Optional[negmas.situated.Contract], Optional[negmas.common.AgentMechanismInterface]][source]

Runs a negotiation until completion

Parameters
  • caller – The agent requesting the negotiation

  • partners – 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 – The negotiator to be used in the negotiation

  • ufun – The utility function. Only needed if the negotiator does not already know it

  • caller_role – The role of the caller in the negotiation

  • issues – Negotiation issues

  • annotation – 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 – The roles of different partners. If None then each role for each partner will be None

  • mechanism_name – Name of the mechanism to use. It must be one of the mechanism_names that are supported by the

  • or None which means that the World should select the mechanism. If None (World) –

  • roles and my_role (then) –

  • also be None (must) –

  • mechanism_params – A dict of parameters used to initialize the mechanism object

Returns

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

run_negotiations(caller: negmas.situated.Agent, issues: Union[List[negmas.outcomes.Issue], List[List[negmas.outcomes.Issue]]], partners: List[List[Union[str, negmas.situated.Agent]]], negotiators: List[negmas.negotiators.Negotiator], ufuns: Optional[List[negmas.utilities.UtilityFunction]] = None, caller_roles: Optional[List[str]] = None, roles: Optional[List[Optional[List[str]]]] = None, annotations: Optional[List[Optional[Dict[str, Any]]]] = None, mechanism_names: Optional[Union[str, List[str]]] = None, mechanism_params: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = None, all_or_none: bool = False)List[Tuple[negmas.situated.Contract, negmas.common.AgentMechanismInterface]][source]

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

Parameters
  • caller – The agent requesting the negotiation

  • partners – 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 – Negotiation issues

  • negotiators – The negotiator to be used in the negotiation

  • ufuns – The utility function. Only needed if the negotiator does not already know it

  • caller_roles – The role of the caller in the negotiation

  • annotations – 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 – The roles of different partners. If None then each role for each partner will be None

  • mechanism_names – Name of the mechanism to use. It must be one of the mechanism_names that are supported by the

  • or None which means that the World should select the mechanism. If None (World) –

  • roles and my_role (then) –

  • also be None (must) –

  • mechanism_params – 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 ami (The mechanism info [None if the partner refused the negotiation])

Return type

A list of tuples each with two values

run_with_progress(callback: Optional[Callable[[int], None]] = None)None[source]

Runs the simulation showing progress, with optional callback

save_config(file_name: str)[source]

Saves the config of the world as a yaml file

Parameters

file_name – Name of file to save the config to

Returns:

save_gif(path: Optional[Union[str, pathlib.Path]] = None, what: Collection[str] = ['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: Optional[Callable[[negmas.situated.Agent], bool]] = None, together: bool = True, draw_every: int = 1, fps: int = 5)None[source]
set_bulletin_board(bulletin_board)[source]
abstract simulation_step(stage: int = 0)[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.

abstract start_contract_execution(contract: negmas.situated.Contract)Optional[Set[negmas.situated.Breach]][source]

Tries to execute the contract

Parameters

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()bool[source]

A single simulation step

unregister_stats_monitor(m: negmas.situated.StatsMonitor)[source]
unregister_world_monitor(m: negmas.situated.WorldMonitor)[source]
update_stats(stage: int)[source]

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

Parameters

stage – 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.