scml

class scml.FactoryState(inventory, balance, commands)[source]
balance = None

Current balance in the wallet

commands = None

n_steps * n_lines array giving the process scheduled on each line at every step for the whole simulation

inventory = None

An n_products vector giving current quantity of every product in storage

class scml.SCML2020Agent(**kwargs)[source]
abstract confirm_guaranteed_sales(quantities, unit_prices)[source]

Called to confirm the amount of guaranteed sales the agent is willing to accept

Parameters
  • quantities (ndarray) – An n_products vector giving the maximum quantity that can sold (without negotiation)

  • unit_prices (ndarray) – An n_products vector giving the guaranteed unit prices

Return type

ndarray

Returns

An n_products vector specifying the quantities to be sold (up to the given quantities limit).

abstract confirm_guaranteed_supplies(quantities, unit_prices)[source]

Called to confirm the amount of guaranteed supplies the agent is willing to accept

Parameters
  • quantities (ndarray) – An n_products vector giving the maximum quantity that can bought (without negotiation)

  • unit_prices (ndarray) – An n_products vector giving the guaranteed unit prices

Return type

ndarray

Returns

An n_products vector specifying the quantities to be bought (up to the given quantities limit).

abstract on_contract_nullified(contract, compensation)[source]

Called whenever a contract is nullified (because the partner is bankrupt)

Parameters
  • contract (Contract) – The contract being nullified

  • compensation (int) – The compensation money that is already added to the agent’s wallet

Return type

None

abstract on_failures(failures)[source]

Called whenever there are failures either in production or in execution of guaranteed transactions

Parameters

failures (List[Failure]) – A list of Failure s.

Return type

None

on_neg_request_accepted(req_id, mechanism)[source]

Called when a requested negotiation is accepted

on_neg_request_rejected(req_id, by)[source]

Called when a requested negotiation is rejected

Parameters
  • req_id (str) – The request ID passed to _request_negotiation

  • by (Optional[List[str]]) – A list of agents that refused to participate or None if the failure was for another reason

abstract respond_to_negotiation_request(initiator, issues, annotation, mechanism)[source]

Called whenever another agent requests a negotiation with this agent.

Parameters
  • initiator (str) – The ID of the agent that requested this negotiation

  • issues (List[Issue]) – Negotiation issues

  • annotation (Dict[str, Any]) – Annotation attached with this negotiation

  • mechanism (AgentMechanismInterface) – The AgentMechanismInterface interface to the mechanism to be used for this negotiation.

Return type

Optional[Negotiator]

Returns

None to reject the negotiation, otherwise a negotiator

respond_to_renegotiation_request(contract, breaches, agenda)[source]

Called to respond to a renegotiation request

Parameters
  • agenda (RenegotiationRequest) –

  • contract (Contract) –

  • breaches (List[Breach]) –

Returns:

Return type

Optional[Negotiator]

set_renegotiation_agenda(contract, breaches)[source]

Received by partners in ascending order of their total breach levels in order to set the renegotiation agenda when contract execution fails

Parameters
  • contract (Contract) – The contract being breached

  • breaches (List[Breach]) – All breaches on contract

Return type

Optional[RenegotiationRequest]

Returns

Renegotiation agenda (issues to negotiate about to avoid reporting the breaches).

sign_contract(contract)[source]

Called after the signing delay from contract conclusion to sign the contract. Contracts become binding only after they are signed.

Return type

Optional[str]

class scml.AWI(world, agent)[source]
property all_consumers

Returns a list of agent IDs for all consumers for every product

Return type

List[List[str]]

property all_suppliers

Returns a list of agent IDs for all suppliers for every product

Return type

List[List[str]]

cancel_production(step, line)[source]

Cancels any production commands on that line at this step

Parameters
  • step (int) – The step to cancel production at (must be in the future).

  • line (int) – The production line

Return type

bool

Returns

success/failure

Remarks:

  • The step cannot be in the past or the current step. Production can only be ordered for future steps

property my_consumers

Returns a list of IDs for all the agent’s consumers (agents that can consume at least one product it may produce).

Remarks:

  • If the agent have multiple output products, consumers of a specific product $p$ can be found using: self.all_consumers[p].

Return type

List[str]

property my_input_products

Returns a list of products that are inputs to at least one process the agent can run

Return type

List[int]

property my_output_products

Returns a list of products that are outputs to at least one process the agent can run

Return type

List[int]

property my_suppliers

Returns a list of IDs for all of the agent’s suppliers (agents that can supply at least one product it may need).

Remarks:

  • If the agent have multiple input products, suppliers of a specific product $p$ can be found using: self.all_suppliers[p].

Return type

List[str]

request_negotiation(is_buy, product, quantity, unit_price, time, partner, negotiator)[source]

Requests a negotiation

Parameters
  • is_buy (bool) – If True the negotiation is about buying otherwise selling.

  • product (int) – The product to negotiate about

  • quantity (Union[int, Tuple[int, int]]) – The minimum and maximum quantities. Passing a single value q is equivalent to passing (q,q)

  • unit_price (Union[int, Tuple[int, int]]) – The minimum and maximum unit prices. Passing a single value u is equivalent to passing (u,u)

  • time (Union[int, Tuple[int, int]]) – The minimum and maximum delivery step. Passing a single value t is equivalent to passing (t,t)

  • partner (str) – ID of the partner to negotiate with.

  • negotiator (SAONegotiator) – The negotiator to use for this negotiation (if the partner accepted to negotiate)

Return type

bool

Returns

True if the partner accepted and the negotiation is ready to start

schedule_production(process, step, line, override=True)[source]

Orders the factory to run the given process at the given line at the given step

Parameters
  • process (int) – The process to run

  • step (int) – The simulation step. Must be in the future

  • line (int) – The production line

  • override (bool) – Whether to override existing production commands or not

Return type

bool

Returns

success/failure

Remarks:

  • The step cannot be in the past or the current step. Production can only be ordered for future steps

  • ordering production of process -1 is equivalent of cancel_production

state()[source]

Receives the factory state

Return type

FactoryState

class scml.World(process_inputs, process_outputs, catalog_prices, profiles, agent_types, agent_params=None, initial_balance=1000, breach_penalty=0.15, compact=False, n_steps=1000, time_limit=5400, neg_n_steps=100, neg_time_limit=120, neg_step_time_limit=60, negotiation_speed=101, signing_delay=1, name=None, **kwargs)[source]

A Supply Chain World Simulation as described for the SCML league of ANAC 2020 @ IJCAI.

Parameters
  • process_inputs (ndarray) – An n_processes vector specifying the number of inputs from each product needed to execute each process.

  • process_outputs (ndarray) – An n_processes vector specifying the number of inputs from each product generated by executing each process.

  • catalog_prices (ndarray) – An n_products vector (i.e. n_processes+1 vector) giving the catalog price of all products

  • profiles (List[FactoryProfile]) – An n_agents list of FactoryProfile objects specifying the private profile of the factory associated with each agent.

  • agent_types (List[Type[SCML2020Agent]]) – An n_agents list of strings/ SCM2020Agent classes specifying the type of each agent

  • agent_params (Optional[List[Dict[str, Any]]]) – An n_agents dictionaries giving the parameters of each agent

  • initial_balance (int) – The initial balance in each agent’s wallet. All agents will start with this same value.

  • breach_penalty – The total penalty paid upon a breach will be calculated as (breach_level * breach_penalty * contract_quantity * contract_unit_price).

  • compact – If True, no logs will be kept and the whole simulation will use a smaller memory footprint

  • n_steps – Number of simulation steps (can be considered as days).

  • time_limit – Total time allowed for the complete simulation in seconds.

  • neg_n_steps – Number of negotiation steps allowed for all negotiations.

  • neg_time_limit – Total time allowed for a complete negotiation in seconds.

  • neg_step_time_limit – Total time allowed for a single step of a negotiation. in seconds.

  • negotiation_speed – The number of negotiation steps that pass in every simulation step. If 0, negotiations will be guaranteed to finish within a single simulation step

  • signing_delay – The number of simulation steps to pass between a contract is concluded and signed

  • name (Optional[str]) – The name of the simulations

  • **kwargs – Other parameters that are passed directly to World constructor.

breach_record(breach)[source]

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

Return type

Dict[str, Any]

complete_contract_execution(contract, breaches, resolution)[source]

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

Parameters
  • contract (Contract) – The contract considered.

  • breaches (List[Breach]) – The list of potential breaches that was generated by _execute_contract.

  • resolution (Contract) – The agreed upon resolution

Returns:

Return type

None

contract_record(contract)[source]

Converts a contract to a record suitable for permanent storage

Return type

Dict[str, Any]

contract_size(contract)[source]

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

Returns:

Return type

float

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

Executes the given action by the given agent

Return type

bool

get_private_state(agent)[source]

Reads the private state of the given agent

Return type

dict

order_contracts_for_execution(contracts)[source]

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

Return type

Collection[Contract]

post_step_stats()[source]

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

pre_step_stats()[source]

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

simulation_step()[source]

A single step of the simulation if any

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