SCMLWorld

class scml.scml2019.SCMLWorld(products, processes, factories, consumers, miners, factory_managers=None, n_steps=100, time_limit=5400, mechanisms=None, neg_n_steps=20, neg_time_limit=120, neg_step_time_limit=60, negotiation_speed=21, no_bank=False, minimum_balance=0, interest_rate=0.1, interest_max=0.3, installment_interest=0.2, interest_time_increment=0.02, balance_at_max_interest=None, loan_installments=1, no_insurance=False, premium=0.03, premium_time_increment=0.03, premium_breach_increment=0.001, max_allowed_breach_level=None, breach_processing=<BreachProcessing.VICTIM_THEN_PERPETRATOR: 1>, breach_penalty_society=0.1, breach_penalty_society_min=0.0, breach_penalty_victim=0.0, breach_move_max_product=True, initial_wallet_balances=None, money_resolution=0.5, default_signing_delay=0, transportation_delay=0, transfer_delay=0, start_negotiations_immediately=False, catalog_profit=0.15, avg_process_cost_is_public=True, catalog_prices_are_public=True, strip_annotations=True, financial_reports_period=10, ignore_negotiated_penalties=False, prevent_cfp_tampering=False, default_price_for_products_without_one=1, compensation_fraction=0.5, compact=False, log_folder=None, log_to_file=True, log_to_screen=False, log_file_level=10, log_screen_level=40, log_file_name='log.txt', log_ufuns=False, log_negotiations=False, save_mechanism_state_in_contract=False, save_signed_contracts=True, save_cancelled_contracts=True, save_negotiations=True, save_resolved_breaches=True, save_unresolved_breaches=True, ignore_agent_exceptions=False, ignore_contract_execution_exceptions=False, name=None, **kwargs)[source]

Bases: negmas.situated.TimeInAgreementMixin, negmas.situated.World

The SCML2020World class running a simulation of supply chain management.

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 negotiations ending in agreement and leading to signed contracts

cancellation_rate

Fraction of negotiations ending in agreement and leading to signed contracts

cancelled_contracts

rtype

List[Dict[str, Any]]

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_negotiation_rounds_failed

Average number of rounds in a successful negotiation

n_negotiation_rounds_successful

Average number of rounds in a successful negotiation

name

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

nullified_contracts

rtype

List[Dict[str, Any]]

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]]

signed_contracts

rtype

List[Dict[str, Any]]

stats

rtype

Dict[str, Any]

time

Elapsed time since mechanism started in seconds.

unresolved_breaches

rtype

List[Dict[str, Any]]

uuid

The unique ID of this entity

winners

The winners of this world (factory managers with maximum wallet balance

Methods Summary

announce(event)

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

append_stats()

assign_managers([factory_managers, params])

Assigns existing factories to new factory managers created from the given types and parameters or manager objects.

breach_record(breach)

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

buy_insurance(contract, agent)

Buys insurance for the contract by the premium calculated by the insurance company.

chain_world([n_intermediate_levels, …])

Creates a very small world in which only one raw material and one final product.

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

The resolution can either be None or a contract with the following items:

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()

rtype

None

evaluate_insurance(contract, agent[, t])

Can be called to evaluate the premium for insuring the given contract against breachs committed by others

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()

rtype

Collection[Contract]

get_private_state(agent)

Reads the private state of the given agent

ignore_contract(contract)

Ignores the contract as if it was never agreed upon

init([time_field])

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

make_bankrupt(agent, amount, beneficiary, …)

Marks the agent as bankrupt

n_saved_contracts([ignore_no_issue])

Number of saved contracts

nullify_contract(contract)

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)

on_event(event, sender)

Called whenever an event is raised for which the SCML2020World is registered asa listener

order_contracts_for_execution(contracts)

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

post_step_stats()

Saves relevant stats

pre_step_stats()

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

random([n_raw_materials, …])

Creates a random SCML scenario with adjustable parameters.

random_small([n_production_levels, …])

read_config(config[, section])

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

receive_financial_reports(agent, receive, agents)

Registers interest/disinterest in receiving financial reports

register(x[, simulation_priority])

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

register_interest(agent, products)

rtype

None

register_listener(event_type, listener)

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.

save_config(file_name)

Saves the config of the world as a yaml file

set_bulletin_board(bulletin_board)

set_consumers(consumers)

set_factory_managers(factory_managers)

set_miners(miners)

set_processes(processes)

set_products(products)

simulation_step_after_execution()

A step of SCML simulation

simulation_step_before_execution()

A single step of the simulation if any (before entity and contract execution)

start_contract_execution(contract)

Tries to execute the contract

step()

A single simulation step

unregister_interest(agent, products)

rtype

None

unregister_stats_monitor(m)

unregister_world_monitor(m)

Attributes Documentation

agreement_fraction

Fraction of negotiations ending in agreement and leading to signed contracts

Return type

float

agreement_rate

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 negotiations ending in agreement and leading to signed contracts

Return type

float

cancellation_rate

Fraction of negotiations ending in agreement and leading to signed contracts

Return type

float

cancelled_contracts
Return type

List[Dict[str, Any]]

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_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

name

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

nullified_contracts
Return type

List[Dict[str, Any]]

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]]

signed_contracts
Return type

List[Dict[str, Any]]

stats
Return type

Dict[str, Any]

time

Elapsed time since mechanism started in seconds. None if the mechanism did not start running

Return type

Optional[float]

unresolved_breaches
Return type

List[Dict[str, Any]]

uuid

The unique ID of this entity

winners

The winners of this world (factory managers with maximum wallet balance

Methods Documentation

announce(event)

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

append_stats()
assign_managers(factory_managers=typing.Iterable[typing.Union[str, typing.Type[scml.scml2019.factory_managers.builtins.FactoryManager], scml.scml2019.factory_managers.builtins.FactoryManager]], params=None)[source]

Assigns existing factories to new factory managers created from the given types and parameters or manager objects.

Parameters
  • factory_managers – An iterable of FactoryManager objects type names or FactoryManager types to assign to

  • params (Optional[Iterable[Dict[str, Any]]]) – parameters of the newly created managers

Remarks:

  • factories are assigned in the same order they exist in the local factories attribute cycling through the input managers or types/params

  • If a FactoryManager object is given instead of a type or a string in the factory_managers collection, and the number of factory_managers is less than the number of factories in the world causing this object to cycle for more than one factory, it is assigned to the first such factory but then deep copies of it with new ids and names are assigned to the rest of the factories. That ensures that each manager has exactly one factory and that all factories are assigned exactly one unique manager.

Return type

None

breach_record(breach)[source]

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

Return type

Dict[str, Any]

buy_insurance(contract, agent)[source]

Buys insurance for the contract by the premium calculated by the insurance company.

Remarks:

The agent can call evaluate_insurance to find the premium that will be used.

Return type

bool

classmethod chain_world(n_intermediate_levels=0, n_miners=5, n_factories_per_level=5, n_consumers=5, n_steps=100, n_lines_per_factory=10, n_max_assignable_factories=None, log_file_name=None, agent_names_reveal_type=False, negotiator_type='negmas.sao.AspirationNegotiator', miner_type=<class 'scml.scml2019.miners.ReactiveMiner'>, consumer_type=<class 'scml.scml2019.consumers.JustInTimeConsumer'>, max_storage=9223372036854775807, default_manager_params=None, miner_kwargs=None, consumption=(0, 5), consumer_kwargs=None, negotiation_speed=None, manager_types=(<class 'scml.scml2019.factory_managers.builtins.GreedyFactoryManager'>, ), manager_params=None, n_default_per_level=0, default_factory_manager_type=<class 'scml.scml2019.factory_managers.builtins.GreedyFactoryManager'>, randomize=True, initial_wallet_balances=1000, process_cost=(1.0, 5.0), process_time=1, interest_rate=inf, interest_max=inf, shared_profile_per_factory=False, **kwargs)[source]

Creates a very small world in which only one raw material and one final product. The production graph is a series with n_intermediate_levels intermediate levels between the single raw material and single final product

Parameters
  • n_max_assignable_factories – The maximum number of factories assigned to managers other than the default

  • randomize (bool) – If true, the factory assignment is randomized

  • n_default_per_level (int) – The number of GreedyFactoryManager objects guaranteed at every level

  • default_factory_manager_type (Type[FactoryManager]) – The FactoryManager type to use as the base for default_factory_managers. You can specify how many of this type exist at every level by specifying n_default_per_level. If n_default_per_level is zero, this parameter has no effect.

  • manager_types (Sequence[Type[FactoryManager]]) – A sequence of factory manager types to control the factories.

  • manager_params (Optional[Sequence[Dict[str, Any]]]) – An optional sequence of dictionaries giving the parameters to pass to manager_types.

  • consumer_type (Union[str, Type[Consumer]]) – Consumer type to use for all consumers

  • miner_type (Union[str, Type[Miner]]) – Miner type to use for all miners

  • consumption (Union[int, Tuple[int, int]]) – Consumption schedule

  • n_intermediate_levels – The number of intermediate products

  • n_miners – number of miners of the single raw material

  • n_factories_per_level – number of factories at every production level

  • n_consumers (Union[int, Tuple[int, int], List[int]]) – number of consumers of the final product

  • n_steps – number of simulation steps

  • n_lines_per_factory – number of lines in each factory

  • process_cost (Union[float, Tuple[float, float]]) – The range of process costs. A uniform distribution will be used

  • process_time (Union[int, Tuple[int, int]]) – The range of process times. A uniform distribution will be used

  • log_file_name (Optional[str]) – File name to store the logs

  • agent_names_reveal_type (bool) – If true, agent names will start with a snake_case version of their type name

  • negotiator_type (str) – The negotiation factory used to create all negotiators

  • max_storage (int) – maximum storage capacity for all factory managers If None then it is unlimited

  • default_manager_params (Optional[Dict[str, Any]]) – keyword arguments to be used for constructing factory managers

  • consumer_kwargs (Optional[Dict[str, Any]]) – keyword arguments to be used for constructing consumers

  • miner_kwargs (Optional[Dict[str, Any]]) – keyword arguments to be used for constructing miners

  • negotiation_speed (Optional[int]) – The number of negotiation steps per simulation step. None means infinite

  • interest_max – Maximum interest rate

  • interest_rate – Minimum interest rate

  • initial_wallet_balances – initial wallet balances for all factories

  • shared_profile_per_factory – If true, all lines in the same factory will have the same profile costs

  • kwargs – Any other parameters are just passed to the world constructor

Returns

SCMLWorld ready to run

Remarks:

  • Every production level n has one process only that takes n steps to complete

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 (Union[Path, str]) – 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 (Union[str, Path]) – 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 (Union[str, Path, None]) – 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 choosen. 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]

The resolution can either be None or a contract with the following items:

The issues can be any or all of the following:

immediate_quantity: int immediate_unit_price: float later_quantity: int later_unit_price: int later_penalty: float later_time: int

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()
Return type

None

evaluate_insurance(contract, agent, t=None)[source]

Can be called to evaluate the premium for insuring the given contract against breachs committed by others

Parameters
  • agent (SCMLAgent) – The agent buying the contract

  • contract (Contract) – hypothetical contract

  • t (Optional[int]) – time at which the policy is to be bought. If None, it means current step

Return type

Optional[float]

executable_contracts()

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 (Union[str, Path]) –

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

Return type

Union[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

  • types (e.g. int, str, float, Iterable[int|str|float] (simple) –

  • scope – The scope at which to evaluate any child classes. This MUST be passed as scope=globals() if you are

  • any children that are to be parsed. (having) –

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()
Return type

Collection[Contract]

get_private_state(agent)[source]

Reads the private state of the given agent

Return type

FactoryState

ignore_contract(contract)

Ignores the contract as if it was never agreed upon

Parameters

contract – The contract to add

init(time_field='time')
join(x, simulation_priority=0)[source]

Add an agent to the world.

Parameters
  • x (Agent) – The agent to be registered

  • simulation_priority (int) – The simulation priority. Entities with lower priorities will be stepped first during

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

make_bankrupt(agent, amount, beneficiary, contract)[source]

Marks the agent as bankrupt

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

nullify_contract(contract)[source]
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)
on_event(event, sender)[source]

Called whenever an event is raised for which the SCML2020World is registered asa listener

Parameters
  • event (Event) – The event

  • sender (EventSource) – The sender

Return type

None

Returns

None

order_contracts_for_execution(contracts)[source]

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

post_step_stats()[source]

Saves relevant stats

pre_step_stats()[source]

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

classmethod random(n_raw_materials=(5, 10), raw_material_price=(1.0, 30.0), n_final_products=(3, 5), n_production_levels=(3, 5), n_products_per_level=(3, 5), n_processes_per_level=(6, 10), n_inputs_per_process=(2, 5), bias_toward_last_level_products=0.0, quantity_per_input=(1, 10), input_step=0.0, quantity_per_output=(1, 1), output_step=1.0, process_relative_cost=(0.05, 0.4), n_outputs_per_process=(1, 1), n_lines=(3, 5), lines_are_similar=False, n_processes_per_line=None, cost_for_line=(5.0, 50.0), n_production_steps=(2, 10), max_storage=2000, n_factories=20, n_consumers=5, n_products_per_consumer=None, n_miners=5, n_products_per_miner=None, factory_manager_types=<class 'scml.scml2019.factory_managers.builtins.GreedyFactoryManager'>, consumer_types=<class 'scml.scml2019.consumers.JustInTimeConsumer'>, miner_types=<class 'scml.scml2019.miners.ReactiveMiner'>, negotiator_type='negmas.sao.AspirationNegotiator', initial_wallet_balance=1000, factory_kwargs=None, miner_kwargs=None, consumer_kwargs=None, **kwargs)[source]

Creates a random SCML scenario with adjustable parameters.

Parameters
  • n_raw_materials (Union[int, Tuple[int, int]]) – Number of raw materials. Can be a value or a range.

  • raw_material_price (Union[float, Tuple[float, float]]) – Catalog prices for raw materials. Can be a value or a range.

  • n_final_products (Union[int, Tuple[int, int]]) – Number of final products. Can be a value or a range.

  • n_production_levels (Union[int, Tuple[int, int]]) – How deep is the production graph (number of intermediate products). Can be a value or

  • range. (a) –

  • n_products_per_level (Union[int, Tuple[int, int]]) – How many intermediate products per intermediate level. Can be a value or a range.

  • n_processes_per_level (Union[int, Tuple[int, int]]) – Number of processes in intermediate levels. Can be a value or a range.

  • n_inputs_per_process (Union[int, Tuple[int, int]]) – Number of inputs per process. Can be a value or a range.

  • bias_toward_last_level_products (float) – How biased are production processes toward using products from the last

  • below them (level) –

  • quantity_per_input (Union[int, Tuple[int, int]]) – How many items are needed for each input to a process. Can be a value or a range.

  • input_step (Union[float, Tuple[float, float]]) – When are inputs consumed during the production process. Can be a value or a range. Default 0

  • quantity_per_output (Union[int, Tuple[int, int]]) – How many items are produced per output. Can be a value or a range.

  • output_step (Union[float, Tuple[float, float]]) – When are outputs created during the production process. Can be a value or a range. Default 1

  • process_relative_cost (Union[float, Tuple[float, float]]) – Intrinsic relative cost of processes [Outputs will be produced

  • a cost of sum (at) –

  • n_outputs_per_process (Union[int, Tuple[int, int]]) – Number of outputs per process. Can be a value or a range.

  • n_lines (Union[int, Tuple[int, int]]) – Number of lines per factory. Can be a value or a range.

  • lines_are_similar (bool) – If true then all lins of the same factory will have the same production processes.

  • n_processes_per_line (Union[int, Tuple[int, int], None]) – Number of processes that can be run on each line per factory. Can be a value or a

  • range.

  • cost_for_line (Union[float, Tuple[float, float]]) – Cost for running a process on a line. Can be a value or a range.

  • n_production_steps (Union[int, Tuple[int, int]]) – Number of production steps per line. Can be a value or a range.

  • max_storage (Union[int, Tuple[int, int]]) – Maximum storage per factory. Can be a value or a range.

  • n_factories (Union[int, Tuple[int, int]]) – Number of factories. Can be a value or a range.

  • n_consumers (Union[int, Tuple[int, int]]) – Number of consumers. Can be a value or a range.

  • n_products_per_consumer (Union[int, Tuple[int, int], None]) – Number of products per miner. If None then all final products will be assigned to

  • customer. Can be a value or a range. (every) –

  • n_miners (Union[int, Tuple[int, int]]) – Number of miners. Can be a value or a range.

  • n_products_per_miner (Union[int, Tuple[int, int], None]) – Number of products per miner. If None then all raw materials will be assigned to every

  • Can be a value or a range. (miner.) –

  • factory_manager_types (Union[Type[FactoryManager], List[Type[FactoryManager]]]) – A callable for creating factory managers for the factories

  • consumer_types (Union[Type[Consumer], List[Type[Consumer]]]) – A callable for creating Consumer objects

  • miner_types (Union[Type[Miner], List[Type[Miner]]]) – A callable for creating Miner objects

  • negotiator_type – A string that can be `eval`uated to a negotiator.

  • initial_wallet_balance (Union[float, Tuple[float, float]]) – The initial balance of all wallets

  • factory_kwargs (Optional[Dict[str, Any]]) – keyword arguments to be used for constructing factory managers

  • consumer_kwargs (Optional[Dict[str, Any]]) – keyword arguments to be used for constructing consumers

  • miner_kwargs (Optional[Dict[str, Any]]) – keyword arguments to be used for constructing miners

  • **kwargs

Returns

SCMLWorld The random world generated

Remarks:

  • Most parameters accept either a single value or a 2-valued tuple. In the later case, it will sample a value within the range specified by the tuple (low, high) inclusive. For example the number of lines (n_lines) follows this pattern

classmethod random_small(n_production_levels=1, n_factories=10, factory_kwargs=None, miner_kwargs=None, consumer_kwargs=None, **kwargs)[source]
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:

receive_financial_reports(agent, receive, agents)[source]

Registers interest/disinterest in receiving financial reports

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_interest(agent, products)[source]
Return type

None

register_listener(event_type, listener)
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)[source]

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[Agent]) – The list of partners that the agent wants to negotiate with. Roles will be determined by these agents.

  • 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

  • or None which means that the World should select the mechanism. If None, then roles and my_role (World) –

  • also be None (must) –

  • mechanism_params (Optional[Dict[str, Any]]) – A dict of parameters used to initialize the mechanism object

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, roles=None, annotation=None, mechanism_name=None, mechanism_params=None)[source]

Runs a negotiation until completion

Parameters
  • caller (Agent) – The agent requesting the negotiation

  • partners (Collection[Agent]) – The list of partners that the agent wants to negotiate with. Roles will be determined by these agents.

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

  • or None which means that the World should select the mechanism. If None, then roles and my_role (World) –

  • also be None (must) –

  • mechanism_params (Optional[Dict[str, Any]]) – A dict of parameters used to initialize the mechanism object

Return type

Optional[Tuple[Contract, AgentMechanismInterface]]

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, issues, partners, roles=None, annotations=None, mechanism_names=None, mechanism_params=None)[source]

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[Agent]]) – The list of partners that the agent wants to negotiate with. Roles will be determined by these agents.

  • issues (Union[List[Issue], List[List[Issue]]]) – 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 (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

  • or None which means that the World should select the mechanism. If None, then roles and my_role (World) –

  • also be None (must) –

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

Return type

A list of tuples each with two values

save_config(file_name)[source]

Saves the config of the world as a yaml file

Parameters

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

Returns:

Return type

None

set_bulletin_board(bulletin_board)
set_consumers(consumers)[source]
set_factory_managers(factory_managers)[source]
set_miners(miners)[source]
set_processes(processes)[source]
set_products(products)[source]
simulation_step_after_execution()[source]

A step of SCML simulation

simulation_step_before_execution()[source]

A single step of the simulation if any (before entity and contract execution)

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_interest(agent, products)[source]
Return type

None

unregister_stats_monitor(m)
unregister_world_monitor(m)