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
Fraction of negotiations ending in agreement and leading to signed contracts
Fraction of negotiations ending in agreement and leading to signed contracts
Fraction of signed contracts that led to breaches
The average breach level per contract
Fraction of signed contracts that led to breaches
The total business size defined as the total money transferred within the system
Fraction of negotiations ending in agreement and leading to signed contracts
Fraction of negotiations ending in agreement and leading to signed contracts
- rtype
List
[Dict
[str
,Any
]]
Fraction of signed contracts that were never executed because they were signed to late to be executable
Fraction of signed contracts that caused exception during their execution
Fraction of signed contracts successfully executed with no breaches, or errors
Fraction of signed contracts were nullified by the system (e.g.
- rtype
List
[Dict
[str
,Any
]]
- rtype
List
[Dict
[str
,Any
]]
The unique ID of this entity
Average number of rounds in a successful negotiation
Average number of rounds in a successful negotiation
A convenient name of the entity (intended primarily for printing/logging/debugging).
- rtype
List
[Dict
[str
,Any
]]
Returns a number between
0
and1
indicating elapsed relative time or steps.Returns the remaining number of steps until the end of the mechanism run.
Returns remaining time in seconds.
- rtype
List
[Dict
[str
,Any
]]
- rtype
List
[Dict
[str
,Any
]]
- rtype
List
[Dict
[str
,Any
]]
- rtype
List
[Dict
[str
,Any
]]
- rtype
List
[Dict
[str
,Any
]]
- rtype
Dict
[str
,Any
]
Elapsed time since mechanism started in seconds.
- rtype
List
[Dict
[str
,Any
]]
The unique ID of this entity
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
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.
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
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.
- rtype
None
evaluate_insurance
(contract, agent[, t])Can be called to evaluate the premium for insuring the given contract against breachs committed by others
Called at every time-step to get the contracts that are
executable
at this point of the simulationexecute_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
- 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 listenerorder_contracts_for_execution
(contracts)Orders the contracts in a specific time-step that are about to be executed
Saves relevant 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)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)A step of SCML simulation
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
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
and1
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 orFactoryManager
types to assign toparams (
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/paramsIf a
FactoryManager
object is given instead of a type or a string in thefactory_managers
collection, and the number offactory_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 randomizedn_default_per_level (
int
) – The number ofGreedyFactoryManager
objects guaranteed at every leveldefault_factory_manager_type (
Type
[FactoryManager
]) – TheFactoryManager
type to use as the base for default_factory_managers. You can specify how many of this type exist at every level by specifyingn_default_per_level
. Ifn_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 tomanager_types
.consumer_type (
Union
[str
,Type
[Consumer
]]) – Consumer type to use for all consumersminer_type (
Union
[str
,Type
[Miner
]]) – Miner type to use for all minersconsumption (
Union
[int
,Tuple
[int
,int
]]) – Consumption schedulen_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 productn_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 usedprocess_time (
Union
[int
,Tuple
[int
,int
]]) – The range of process times. A uniform distribution will be usedlog_file_name (
Optional
[str
]) – File name to store the logsagent_names_reveal_type (
bool
) – If true, agent names will start with a snake_case version of their type namenegotiator_type (
str
) – The negotiation factory used to create all negotiatorsmax_storage (
int
) – maximum storage capacity for all factory managers If None then it is unlimiteddefault_manager_params (
Optional
[Dict
[str
,Any
]]) – keyword arguments to be used for constructing factory managersconsumer_kwargs (
Optional
[Dict
[str
,Any
]]) – keyword arguments to be used for constructing consumersminer_kwargs (
Optional
[Dict
[str
,Any
]]) – keyword arguments to be used for constructing minersnegotiation_speed (
Optional
[int
]) – The number of negotiation steps per simulation step. None means infiniteinterest_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 checkpointfile_name (
Optional
[str
]) – Name of the file to dump into. If not given, a unique name is createdinfo (
Optional
[Dict
[str
,Any
]]) – Information to save with the checkpoint (must be json serializable)exist_ok (
bool
) – If true, override existing dumpsingle_checkpoint (
bool
) – If true, keep a single checkpoint for the last stepstep_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 conceptevery (
int
) – Number of steps per checkpoint. If < 1 no checkpoints will be savedfolder (
Union
[str
,Path
,None
]) – The directory to store checkpoints underfilename (
Optional
[str
]) – Name of the file to save the checkpoint under. If None, a unique name will be choosen. Ifsingle_checkpoint
was False, then multiple files will be used prefixed with the step numberinfo (
Optional
[Dict
[str
,Any
]]) – Any extra information to save in the json file associated with each checkpointexist_ok (
bool
) – Override existing files if anysingle (
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 contractcontract (
Contract
) – hypothetical contractt (
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 dictionarysection (
Optional
[str
]) – A section in the file or a key in the dictionary to use for loading paramsignore_children (
bool
) – If true then children will be ignored and there will be a single returntry_parsing_children (
bool
) – If true the children will first be parsed asConfigReader
classes if they are nottypes (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
]
-
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 registeredsimulation_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
-
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 addto_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 eventsender (
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
-
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 orrange. (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 lastbelow 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 0quantity_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 1process_relative_cost (
Union
[float
,Tuple
[float
,float
]]) – Intrinsic relative cost of processes [Outputs will be produceda 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 arange. –
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 tocustomer. 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 everyCan be a value or a range. (miner.) –
factory_manager_types (
Union
[Type
[FactoryManager
],List
[Type
[FactoryManager
]]]) – A callable for creating factory managers for the factoriesconsumer_types (
Union
[Type
[Consumer
],List
[Type
[Consumer
]]]) – A callable for creatingConsumer
objectsminer_types (
Union
[Type
[Miner
],List
[Type
[Miner
]]]) – A callable for creatingMiner
objectsnegotiator_type – A string that can be `eval`uated to a negotiator.
initial_wallet_balance (
Union
[float
,Tuple
[float
,float
]]) – The initial balance of all walletsfactory_kwargs (
Optional
[Dict
[str
,Any
]]) – keyword arguments to be used for constructing factory managersconsumer_kwargs (
Optional
[Dict
[str
,Any
]]) – keyword arguments to be used for constructing consumersminer_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 dictionarysection (
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 registeredsimulation_priority (
int
) – The simulation periority. Entities with lower periorities will be stepped first during
Returns:
-
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 callercaller (
Agent
) – The agent requesting the negotiationpartners (
List
[Agent
]) – The list of partners that the agent wants to negotiate with. Roles will be determined by these agents.issues (
List
[Issue
]) – Negotiation issuesannotation (
Optional
[Dict
[str
,Any
]]) – Extra information to be passed to thepartners
when asking them to join the negotiationpartners – 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 Nonemechanism_name (
Optional
[str
]) – Name of the mechanism to use. It must be one of the mechanism_names that are supported by theor 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
oron_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 negotiationpartners (
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 issuesannotation (
Optional
[Dict
[str
,Any
]]) – Extra information to be passed to thepartners
when asking them to join the negotiationpartners – 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 Nonemechanism_name (
Optional
[str
]) – Name of the mechanism to use. It must be one of the mechanism_names that are supported by theor 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 negotiationpartners (
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 issuesnegotiators – 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 thepartners
when asking them to join the negotiationpartners – 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 Nonemechanism_names (
Union
[str
,List
[str
],None
]) – Name of the mechanism to use. It must be one of the mechanism_names that are supported by theor 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 objectall_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)¶
-
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_stats_monitor
(m)¶
-
unregister_world_monitor
(m)¶