scml.scml2020.world

Implements the world class for the SCML2020 world

Module Contents

Classes

AWI	The Agent SCML2020World Interface for SCML2020 world.
Failure	A production failure
SCML2020World	A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020.
SCML2021World	A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020.
SCML2022World	A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020.
SCML2023World	A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020.
SCML2024World	A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020.

class scml.scml2020.world.AWI(world: negmas.situated.world.World, agent: negmas.situated.agent.Agent)

Bases: negmas.AgentWorldInterface

The Agent SCML2020World Interface for SCML2020 world.

This class contains all the methods needed to access the simulation to extract information which are divided into 5 groups:

Static World Information:

Information about the world and the agent that does not change over time. These include:

1. Market Information:

• n_products: Number of products in the production chain.

• n_processes: Number of processes in the production chain.

• n_competitors: Number of other factories on the same production level.

• all_suppliers: A list of all suppliers by product.

• all_consumers: A list of all consumers by product.

• catalog_prices: A list of the catalog prices (by product).

• inputs: Inputs to every manufacturing process.

• outputs: Outputs to every manufacturing process.

• is_system: Is the given system ID corresponding to a system agent?

• is_bankrupt: Is the given agent bankrupt (None asks about self)?

• current_step: Current simulation step (inherited from negmas.situated.AgentWorldInterface ).

• n_steps: Number of simulation steps (inherited from negmas.situated.AgentWorldInterface ).

• relative_time: fraction of the simulation completed (inherited from negmas.situated.AgentWorldInterface).

• settings: The system settings (inherited from negmas.situated.AgentWorldInterface ).

2. Agent Information:

• profile: Gives the agent profile including its production cost, number of production lines, input product index, mean of its delivery penalties, mean of its disposal costs, standard deviation of its shortfall penalties and standard deviation of its disposal costs. See OneShotProfile for full description. This information is private information and no other agent knows it.

• n_lines: the number of production lines in the factory (private information).

• is_first_level: Is the agent in the first production level (i.e. it is an input agent that buys the raw material).

• is_last_level: Is the agent in the last production level (i.e. it is an output agent that sells the final product).

• is_middle_level: Is the agent neither a first level nor a last level agent

• my_input_product: The input product to the factory controlled by the agent.

• my_output_product: The output product from the factory controlled by the agent.

• my_input_products: All input products of a factory controlled by the agent. Currently, it is always a list of one item. For future compatibility.

• my_output_products: All output products of a factory controlled by the agent. Currently, it is always a list of one item. For future compatibility.

• available_for_production: Returns the line-step slots available for production.

• level: The production level which is numerically the same as the input product.

• my_suppliers: A list of IDs for all suppliers to the agent (i.e. agents that can sell the input product of the agent).

• my_consumers: A list of IDs for all consumers to the agent (i.e. agents that can buy the output product of the agent).

• penalties_scale: The scale at which to calculate disposal cost/delivery penalties. “trading” and “catalog” mean trading and catalog prices. “unit” means the contract’s unit price while “none” means that disposal cost/shortfall penalty are absolute.

• n_input_negotiations: Number of negotiations with suppliers.

• n_output_negotiations: Number of negotiations with consumers.

• state: The full state of the agent ( FactoryState ).

• current_balance: The current balance of the agent

• current_inventory: The current inventory of the agent (quantity per product)

Dynamic World Information:

Information about the world and the agent that changes over time.

1. Market Information:

• trading_prices: The trading prices of all products. This information is only available if publish_trading_prices is set in the world.

• exogenous_contract_summary: A list of n_products tuples each giving the total quantity and average price of exogenous contracts for a product. This information is only available if publish_exogenous_summary is set in the world.

2. Other Agents’ Information:

• reports_of_agent: Gives all past financial reports of a given agent. See FinancialReport for details.

• reports_at_step: Gives all reports of all agents at a given step. See FinancialReport for details.

3. Current Negotiations Information:

• current_input_issues: The current issues for all negotiations to buy the input product of the agent. If the agent is at level zero, this will be empty.

• current_output_issues: The current issues for all negotiations to buy the output product of the agent. If the agent is at level n_products - 1, this will be empty.

4. Agent Information:

• spot_market_quantity: The quantity the agent bought from the spot market at

  a given step

• spot_market_loss: The spot market loss for the agent.

Actions:

1. Negotiation Control:

• request_negotiations: Requests a set of negotiations controlled by a single controller.

• request_negotiation: Requests a negotiation controlled by a single negotiator.

2. Production Control:

• schedule_production: Schedules production using one of the predefined scheduling strategies.

• order_production: Orders production directly for the current step.

• set_commands: Sets production commands directly on the factory.

• cancel_production: Cancels a scheduled production command.

Services (All inherited from negmas.situated.AgentWorldInterface):

• logdebug/loginfo/logwarning/logerror: Logs to the world log at the given log level.

• logdebug_agent/loginf_agnet/…: Logs to the agent specific log at the given log level.

• bb_query: Queries the bulletin-board.

• bb_read: Read a section of the bulletin-board.

property trading_prices: numpy.ndarray

Returns the current trading prices of all products

property exogenous_contract_summary: List[Tuple[int, int]]

The exogenous contracts in the current step for all products

Returns:

A list of tuples giving the total quantity and total price of all revealed exogenous contracts of all products at the current step.

property allow_zero_quantity: bool

Does negotiations allow zero quantity?

property state: scml.scml2020.common.FactoryState

Receives the factory state

property current_balance

Current balance of the agent

property current_inventory

Current inventory of the agent

property profile: scml.scml2020.common.FactoryProfile

Gets the profile (static private information) associated with the agent

property all_suppliers: List[List[str]]

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

property all_consumers: List[List[str]]

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

property inputs: numpy.ndarray

Returns the number of inputs to every production process

property outputs: numpy.ndarray

Returns the number of outputs to every production process

property n_competitors: int

Returns the number of factories/agents in the same production level

property my_input_product: int

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

property my_output_product: int

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

property my_input_products: numpy.ndarray

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

property my_output_products: numpy.ndarray

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

property my_suppliers: List[str]

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

property my_consumers: List[str]

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

property n_lines: int

The number of lines in the corresponding factory. You can read state to get this among other information

property catalog_prices: numpy.ndarray

Returns the catalog prices of all products

property n_products: int

Number of products in the world

property n_processes: int

Returns the number of processes in the system

property is_first_level

Whether this agent is in the first production level

property is_last_level

Whether this agent is in the last production level

property level

The production level which is the index of the process for this factory (or the index of its input product)

property is_middle_level

Whether this agent is in neither in the first nor in the last level

request_negotiations(is_buy: bool, product: int, quantity: int | Tuple[int, int], unit_price: int | Tuple[int, int], time: int | Tuple[int, int], controller: negmas.SAOController | None = None, negotiators: List[negmas.Negotiator] = None, partners: List[str] = None, extra: Dict[str, Any] = None, copy_partner_id=True) → bool

Requests a negotiation

Parameters:

• is_buy – If True the negotiation is about buying otherwise selling.

• product – The product to negotiate about

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

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

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

• controller – The controller to manage the complete set of negotiations

• negotiators – An optional list of negotiators to use for negotiating with the given partners (in the same order).

• partners – ID of all the partners to negotiate with.

• extra – Extra information accessible through the negotiation annotation to the caller

• copy_partner_id – If true, the partner ID will be copied to the negotiator ID

Returns:

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

Remarks:

• You can either use controller or negotiators. One of them must be None.

• All negotiations will use the following issues in order: quantity, time, unit_price

• Negotiations with bankrupt agents or on invalid products (see next point) will be automatically rejected

• Valid products for a factory are the following (any other products are not valid):

  1. Buying an input product (i.e. product $in$ my_input_products ) and an output product if the world settings allows it (see allow_buying_output)

  1. Selling an output product (i.e. product $in$ my_output_products ) and an input product if the world settings allows it (see allow_selling_input)

request_negotiation(is_buy: bool, product: int, quantity: int | Tuple[int, int], unit_price: int | Tuple[int, int], time: int | Tuple[int, int], partner: str, negotiator: negmas.SAONegotiator, extra: Dict[str, Any] = None) → bool

Requests a negotiation

Parameters:

• is_buy – If True the negotiation is about buying otherwise selling.

• product – The product to negotiate about

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

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

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

• partner – ID of the partner to negotiate with.

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

• extra – Extra information accessible through the negotiation annotation to the caller

Returns:

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

Remarks:

• All negotiations will use the following issues in order: quantity, time, unit_price

• Negotiations with bankrupt agents or on invalid products (see next point) will be automatically rejected

• Valid products for a factory are the following (any other products are not valid):

  1. Buying an input product (i.e. product $in$ my_input_products ) and an output product if the world settings allows it (see allow_buying_output)

  1. Selling an output product (i.e. product $in$ my_output_products ) and an input product if the world settings allows it (see allow_selling_input)

schedule_production(process: int, repeats: int, step: int | Tuple[int, int] = ANY_STEP, line: int = ANY_LINE, override: bool = True, method: str = 'latest', partial_ok: bool = False) → Tuple[numpy.ndarray, numpy.ndarray]

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

Parameters:

• process – The process to run

• repeats – How many times to repeat the process

• step – The simulation step or a range of steps. The special value ANY_STEP gives the factory the freedom to schedule production at any step in the present or future.

• line – The production line. The special value ANY_LINE gives the factory the freedom to use any line

• override – Whether to override existing production commands or not

• method – When to schedule the command if step was set to a range. Options are latest, earliest

• partial_ok – If true, allows partial scheduling

Returns:

Tuple[int, int] giving the steps and lines at which production is scheduled.

Remarks:

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

• ordering production of process -1 is equivalent of cancel_production only if both step and line are given

order_production(process: int, steps: numpy.ndarray, lines: numpy.ndarray) → None

Orders production of the given process

Parameters:

• process – The process to run

• steps – The time steps to run the process at as an np.ndarray

• lines – The corresponding lines to run the process at

Remarks:

• len(steps) must equal len(lines)

• No checks are done in this function. It is expected to be used after calling available_for_production

available_for_production(repeats: int, step: int | Tuple[int, int] = ANY_STEP, line: int = ANY_LINE, override: bool = True, method: str = 'latest') → Tuple[numpy.ndarray, numpy.ndarray]

Finds available times and lines for scheduling production.

Parameters:

• repeats – How many times to repeat the process

• step – The simulation step or a range of steps. The special value ANY_STEP gives the factory the freedom to schedule production at any step in the present or future.

• line – The production line. The special value ANY_LINE gives the factory the freedom to use any line

• override – Whether to override any existing commands at that line at that time.

• method – When to schedule the command if step was set to a range. Options are latest, earliest, all

Returns:

Tuple[np.ndarray, np.ndarray] The steps and lines at which production is scheduled.

Remarks:

• You cannot order production in the past or in the current step

• Ordering production, will automatically update inventory and balance for all simulation steps assuming that this production will be carried out. At the indicated step if production was not possible (due to insufficient funds or insufficient inventory of the input product), the predictions for the future will be corrected.

set_commands(commands: numpy.ndarray, step: int = -1) → None

Sets the production commands for all lines in the given step

Parameters:

• commands – n_lines vector of commands. A command is either a process number to run or NO_COMMAND to keep the line idle

• step – The step to set the commands at. If < 0, it means current step

cancel_production(step: int, line: int) → bool

Cancels any production commands on that line at this step

Parameters:

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

• line – The production line

Returns:

success/failure

Remarks:

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

reports_of_agent(aid: str) → Dict[int, scml.scml2020.common.FinancialReport]

Returns a dictionary mapping time-steps to financial reports of the given agent

reports_at_step(step: int) → Dict[str, scml.scml2020.common.FinancialReport]

Returns a dictionary mapping agent ID to its financial report for the given time-step

is_system(aid: str) → bool

Checks whether an agent is a system agent or not

Parameters:

aid – Agent ID

is_bankrupt(aid: str | None = None) → bool

Checks whether the agent is bankrupt

Parameters:

aid – Agent ID (None means self)

spot_market_quantity(step: int | None) → int

The quantity bought by the agent from the spot market at the given step.

Parameters:

step – The simulation step (day)

Remarks:

If step is None, the current step will be used

spot_market_loss(step: int | None) → int

The spot market loss of the agent at the given step.

Parameters:

step – The simulation step (day)

Remarks:

If step is None, the current step will be used

class scml.scml2020.world.Failure

A production failure

__slots__ = ['is_inventory', 'line', 'step', 'process']

is_inventory: bool

True if the cause of failure was insufficient inventory. If False, the cause was insufficient funds. Note that if both conditions were true, only insufficient funds (is_inventory=False) will be reported.

line: int

The line at which the failure happened

step: int

The step at which the failure happened

process: int

The process that failed to execute

class scml.scml2020.world.SCML2020World(process_inputs: numpy.ndarray, process_outputs: numpy.ndarray, catalog_prices: numpy.ndarray, profiles: list[scml.scml2020.common.FactoryProfile], agent_types: list[type[scml.scml2020.agent.SCML2020Agent]], agent_params: list[dict[str, Any]] | None = None, exogenous_contracts: Collection[scml.scml2020.common.ExogenousContract] = (), initial_balance: numpy.ndarray | tuple[int, int] | int = 1000, allow_buying_output=False, allow_selling_input=False, catalog_quantities: int | numpy.ndarray = 50, buy_missing_products=True, borrow_on_breach=True, bankruptcy_limit=0.0, liquidation_rate=1.0, spot_market_global_loss=0.3, interest_rate=0.05, financial_report_period: int = 5, compensation_fraction: float = 1.0, compensate_immediately=False, compensate_before_past_debt=True, exogenous_horizon: int | None = None, exogenous_force_max: bool = False, production_confirm=False, production_buy_missing=False, production_no_borrow=True, production_no_bankruptcy=False, production_penalty=0.15, compact=False, no_logs=False, n_steps=1000, time_limit=60 * 90, neg_n_steps=20, neg_time_limit=2 * 60, neg_step_time_limit=60, negotiation_speed=21, negotiation_quota_per_step=None, negotiation_quota_per_simulation=float('inf'), n_concurrent_negs_between_partners=float('inf'), shuffle_negotiations=False, end_negotiation_on_refusal_to_propose=True, trading_price_discount=0.9, spot_discount=0.9, spot_multiplier=0.05, signing_delay=0, force_signing=False, batch_signing=True, name: str = None, publish_exogenous_summary=True, publish_trading_prices=True, agent_name_reveals_position: bool = True, agent_name_reveals_type: bool = True, inventory_valuation_trading: float = 0.5, inventory_valuation_catalog: float = 0.0, **kwargs)

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

A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020.

Parameters:

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

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

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

• profiles – An n_agents list of FactoryProfile objects specifying the private profile of the factory associated with each agent.

• agent_types – An n_agents list of strings/ SCML2020Agent classes specifying the type of each agent

• agent_params – An n_agents dictionaries giving the parameters of each agent

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

• allow_selling_input – Allows agents to sell their input product(s) through negotiation

• allow_buying_output – Allows agents to buy their output product(s) through negotiation

• catalog_quantities – The quantities in the past for which catalog_prices are the average unit prices. This is used when updating the trading prices. If set to zero then the trading price will follow the market price and will not use the catalog_price (except for products that are never sold in the market for which the trading price will take the default value of the catalog price). If set to a large value (e.g. 10000), the price at which a product is sold will not affect the trading price

• spot_market_global_loss – Buying from the spot market will cost trading-price * (1+`spot_market_global_loss) and selling to it will cost trading-price / (1+ spot_market_global_loss) for agents with unit spot-market-loss-multiplier

• financial_report_period – The number of steps between financial reports. If < 1, it is a fraction of n_steps

• borrow_on_breach – If true, agents will be forced to borrow money on breach as much as possible to honor the contract

• interest_rate – The interest at which loans grow over time (it only affect a factory when its balance is negative)

• bankruptcy_limit – The maximum amount that be be borrowed (including interest). The balance of any factory cannot go lower than - borrow_limit or the agent will go bankrupt immediately

• liquidation_rate – The rate at which future contracts get liquidated when an agent gets bankrupt. It should be between zero and one.

• compensation_fraction – Fraction of a contract to be compensated (at most) if a partner goes bankrupt. Notice that this fraction is not guaranteed because the bankrupt agent may not have enough assets to pay all of its standing contracts to this level of compensation. In such cases, a smaller fraction will be used.

• compensate_immediately – If true, compensation will happen immediately when an agent goes bankrupt and in in money. This means that agents with contracts involving the bankrupt agent will just have these contracts be nullified and receive monetary compensation immediately . If false, compensation will not happen immediately but at the contract execution time. In this case, agents with contracts involving the bankrupt agent will be informed of the compensation fraction (instead of the compensation money) at the time of bankruptcy and will receive the compensation in kind (money if they are sellers and products if they are buyers) at the normal execution time of the contract. In the special case of no-compensation (i.e. compensation_fraction is zero or the bankrupt agent has no assets), the two options will behave similarity.

• compensate_before_past_debt – If true, then compensations will be paid before past debt is considered, otherwise, the money from liquidating bankrupt agents will first be used to pay past debt then whatever remains will be used for compensation. Notice that in all cases, the trigger of bankruptcy will be paid before compensation and past debts.

• exogenous_horizon – The horizon for revealing external contracts

• exogenous_force_max – If true, exogenous contracts are forced to be signed independent of the setting of force_signing

• production_no_borrow – If true, agents will not borrow if they fail to satisfy its production need to execute a scheduled production command

• production_no_bankruptcy – If true, agents will not go bankrupt because of an production related transaction.

• production_penalty – The penalty paid when buying from spot-market to satisfy production needs

• production_confirm – If true, the factory will confirm running processes at every time-step just before running them by calling confirm_production on the agent controlling it.

• 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 – The name of the simulations

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

property productivity: float

Fraction of production lines occupied during the simulation

property relative_productivity: float | None

Productivity relative to the expected value. Will return None if self.info does not have the expected productivity

property bankruptcy_rate: float

The fraction of factories that went bankrupt

property num_bankrupt: float

The fraction of factories that went bankrupt

property winners

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

property trading_prices

property stats_df: pandas.DataFrame

Returns a pandas data frame with the stats

property contracts_df: pandas.DataFrame

Returns a pandas data frame with the contracts

property system_agents: list[scml.scml2020.agent.SCML2020Agent]

Returns the two system agents

property system_agent_names: list[str]

Returns the names two system agents

property non_system_agents: list[scml.scml2020.agent.SCML2020Agent]

Returns all agents except system agents

property non_system_agent_names: list[str]

Returns names of all agents except system agents

property agreement_fraction: float

Fraction of negotiations ending in agreement and leading to signed contracts

system_agent_ids

non_system_agent_ids

classmethod generate(agent_types: list[type[scml.scml2020.agent.SCML2020Agent] | str], agent_params: list[dict[str, Any]] | None = None, agent_processes: list[int] | None = None, n_steps: tuple[int, int] | int = (50, 200), n_processes: tuple[int, int] | int = (2, 4), n_lines: numpy.ndarray | tuple[int, int] | int = 10, n_agents_per_process: numpy.ndarray | tuple[int, int] | int = (2, 4), process_inputs: numpy.ndarray | tuple[int, int] | int = 1, process_outputs: numpy.ndarray | tuple[int, int] | int = 1, production_costs: numpy.ndarray | tuple[int, int] | int = (1, 4), profit_means: numpy.ndarray | tuple[float, float] | float = (0.15, 0.2), profit_stddevs: numpy.ndarray | tuple[float, float] | float = 0.001, max_productivity: numpy.ndarray | tuple[float, float] | float = 1.0, initial_balance: numpy.ndarray | tuple[int, int] | int | None = None, cost_increases_with_level=True, equal_exogenous_supply=False, equal_exogenous_sales=False, exogenous_supply_predictability: tuple[float, float] | float = (0.6, 0.9), exogenous_sales_predictability: tuple[float, float] | float = (0.6, 0.9), exogenous_control: tuple[float, float] | float = (0.2, 0.8), cash_availability: tuple[float, float] | float = (1.5, 2.5), force_signing=False, profit_basis=np.max, horizon: tuple[float, float] | float = (0.2, 0.5), inventory_valuation_trading: numpy.ndarray | tuple[float, float] | float = 0.5, inventory_valuation_catalog: numpy.ndarray | tuple[float, float] | float = 0.0, random_agent_types: bool = False, cost_relativity: float = 1.0, exogenous_generation_method='profitable', exogenous_supply_surplus: tuple[float, float] | float = 0.0, exogenous_sales_surplus: tuple[float, float] | float = 0.0, run_extra_checks: bool = True, **kwargs) → dict[str, Any]

Generates the configuration for a world

Parameters:

• agent_types – All agent types

• agent_params – Agent parameters used to initialize them

• n_steps – Number of simulation steps

• n_processes – Number of processes in the production chain

• n_lines – Number of lines per factory

• process_inputs – Number of input units per process

• process_outputs – Number of output units per process

• production_costs – Production cost per factory

• profit_means – Mean profitability per production level (i.e. process).

• profit_stddevs – Std. Dev. of the profitability of every level (i.e. process).

• inventory_valuation_catalog – The fraction of catalog price to value items at the end.

• inventory_valuation_trading – The fraction of trading price to value items at the end.

• max_productivity – Maximum possible productivity per level (i.e. process).

• initial_balance – The initial balance of all agents

• n_agents_per_process – Number of agents per process

• agent_processes – The process for each agent. If not None , it will override n_agents_per_process and must be a list/tuple of the same length as agent_types . Morevoer, random_agent_types must be False in this case

• cost_increases_with_level – If true, production cost will be higher for processes nearer to the final product.

• profit_basis – The statistic used when controlling catalog prices by profit arguments. It can be np.mean, np.median, np.min, np.max or any Callable[[list[float]], float] and is used to summarize production costs at every level.

• horizon – The horizon used for revealing external supply/sales as a fraction of n_steps

• equal_exogenous_supply – If true, external supply will be distributed equally among all agents in the first layer

• equal_exogenous_sales – If true, external sales will be distributed equally among all agents in the last layer

• exogenous_supply_predictability – How predictable are exogenous supplies of each agent over time. 1.0 means that every agent will have the same quantity for all of its contracts over time. 0.0 means quantities per agent are completely random

• exogenous_sales_predictability – How predictable are exogenous supplies of each agent over time. 1.0 means that every agent will have the same quantity for all of its contracts over time. 0.0 means quantities per agent are completely random

• cash_availability – The fraction of the total money needs of the agent to work at maximum capacity that is available as initial_balance . This is only effective if initial_balance is set to None .

• force_signing – Whether to force contract signatures (exogenous contracts are treated in the same way).

• exogenous_control – How much control does the agent have over exogenous contract signing. Only effective if force_signing is False and use_exogenous_contracts is True

• random_agent_types – If True, the final agent types used by the generato wil always be sampled from the given types. If False, this random sampling will only happin if len(agent_types) != n_agents.

• cost_relativity – The exponent of production cost used to distribute contracts during generation

• method – The method used for world generation. Available methods are “profitable” and “guaranteed_profit”

• exogenous_supply_surplus – The surpolus exogenous supply contract quantity to add to the system as a fraction of the a fraction of the contracts generated by the given method.

• exogenous_sales_surplus – The surpolus exogenous sales contract quantity to add to the system as a fraction of the a fraction of the contracts generated by the given method.

• run_extra_checks – If given, the world generation method will check whether the genrated world “makes sense” given its internal criteria. May slow down world generation

• **kwargs –

Returns:

world configuration as a dict[str, Any]. A world can be generated from this dict by calling SCML2020World(**d)

Remarks:

• There are two general ways to use this generator:

  1. Pass random_agent_types = True, and pass agent_types, agent_processes to control placement of each agent in each level of the production graph.

  2. Pass random_agent_types = False and pass agent_types, n_agents_per_process to make the system randomly place the specified number of agents in each production level

• Most parameters (i.e. process_inputs , process_outputs , n_agents_per_process , costs ) can take a single value, a tuple of two values, or a list of values. If it has a single value, it is repeated for all processes/factories as appropriate. If it is a tuple of two numbers $(i, j)$, each process will take a number sampled from a uniform distribution supported on $[i, j]$ inclusive. If it is a list of values, of the length n_processes , it is used as it is otherwise, it is used to sample values for each process.

classmethod generate_guaranteed_profit(n_steps: int, n_lines: int, n_agents_per_process: int, process_of_agent: list[int], first_agent: list[int], last_agent: list[int], production_costs: list[int], exogenous_control: float, cash_availability: float, force_signing: bool, horizon: int, exogenous_supplies: list[int], max_productivity_process: list[float], max_productivity_agent: list[float], equal_exogenous_sales: bool, process_inputs: list[int], process_outputs: list[int], exogenous_sales_predictability: float, costs: numpy.ndarray, profit_stddevs_agent=list[float], profit_means_agent=list[float], initial_balance: numpy.ndarray | tuple[int, int] | int | None = None, cost_relativity: float = 1.0, profit_basis=np.max, inventory_valuation_trading: float = 0.5, inventory_valuation_catalog: float = 0.0, run_extra_checks=True) → tuple[list[scml.scml2020.common.ExogenousContract], list[int], list[scml.scml2020.common.FactoryProfile], list[float], dict[str, Any]]

Generates prices, contracts and profiles ensuring that all agents can profit and returning a set of explict contracts that can achieve this profit

classmethod generate_profitable(n_steps: int, n_lines: int, n_agents_per_process: int, process_of_agent: list[int], first_agent: list[int], last_agent: list[int], production_costs: list[int], exogenous_control: float, cash_availability: float, force_signing: bool, horizon: int, exogenous_supplies: list[int], max_productivity_process: list[float], max_productivity_agent: list[float], equal_exogenous_sales: bool, process_inputs: list[int], process_outputs: list[int], exogenous_sales_predictability: float, costs: numpy.ndarray, profit_stddevs_agent=list[float], profit_means_agent=list[float], initial_balance: numpy.ndarray | tuple[int, int] | int | None = None, cost_relativity: float = 1.0, profit_basis=np.max, inventory_valuation_trading: float = 0.5, inventory_valuation_catalog: float = 0.0, run_extra_checks: bool = True) → tuple[list[scml.scml2020.common.ExogenousContract], list[int], list[scml.scml2020.common.FactoryProfile], list[float], dict[str, Any]]

Generates the prices, contracts and profiles ensuring there is some possibility of profit in the market

get_private_state(agent: scml.scml2020.agent.SCML2020Agent) → dict

Reads the private state of the given agent

add_financial_report(agent: scml.scml2020.agent.SCML2020Agent, factory: scml.scml2020.factory.Factory, reports_agent, reports_time) → None

Records a financial report for the given agent in the agent indexed reports and time indexed reports

Parameters:

• agent – The agent

• factory – Its factory

• reports_agent – A dictionary of financial reports indexed by agent id

• reports_time – A dictionary of financial reports indexed by time

Returns:

negs_between(a1, a2)

current_balance(agent_id: str)

can_negotiate(a1, a2)

simulation_step(stage)

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.

contract_size(contract: negmas.Contract) → float

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

Returns:

contract_record(contract: negmas.Contract) → dict[str, Any]

Converts a contract to a record suitable for permanent storage

breach_record(breach: negmas.Breach) → dict[str, Any]

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

execute_action(action: negmas.Action, agent: scml.scml2020.agent.SCML2020Agent, callback: Callable = None) → bool

Executes the given action by the given agent

post_step_stats()

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

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

welfare(include_bankrupt: bool = False) → float

Total welfare of all agents

relative_welfare(include_bankrupt: bool = False) → float | None

Total welfare relative to expected value. Returns None if no expectation is found in self.info

order_contracts_for_execution(contracts: Collection[negmas.Contract]) → Collection[negmas.Contract]

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

_execute(product: int, q: int, p: int, u: int, buyer_factory: scml.scml2020.factory.Factory, seller_factory: scml.scml2020.factory.Factory, has_breaches: bool)

Executes the contract

__register_contract(agent_id: str, level: float) → None

Registers execution of the contract in the agent’s stats

record_bankrupt(factory: scml.scml2020.factory.Factory) → None

Records agent bankruptcy

on_contract_concluded(contract: negmas.Contract, to_be_signed_at: int) → None

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.

is_valid_contact(contract: negmas.Contract) → bool

Checks whether a signed contract is valid

on_contract_signed(contract: negmas.Contract) → bool

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.

nullify_contract(contract: negmas.Contract, new_quantity: int)

__register_breach(agent_id: str, level: float, contract_total: float, factory: scml.scml2020.factory.Factory) → int

Registers a breach of the given level on the given agent. Assume that the contract is already added to the agent_contracts

Parameters:

• agent_id – The perpetrator of the breach

• level – The breach level

• contract_total – The total of the contract breached (quantity * unit_price)

• factory – The factory corresponding to the perpetrator

Returns:

If nonzero, the agent should go bankrupt and this amount taken from them

_spot_loss(aid: str) → float

start_contract_execution(contract: negmas.Contract) → set[negmas.Breach] | None

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

complete_contract_execution(contract: negmas.Contract, breaches: list[negmas.Breach], resolution: negmas.Contract) → None

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:

compensate(available: int, factory: scml.scml2020.factory.Factory) → dict[str, list[tuple[negmas.Contract, int, int]]]

Called by a factory when it is going bankrupt after liquidation

Parameters:

• available – The amount available from liquidation

• factory – The factory being bankrupted

Returns:

A mapping from agent ID to nullified contracts, the new quantity for them and compensation_money

scores(assets_multiplier_trading: float | None = None, assets_multiplier_catalog: float | None = None, assets_multiplier: float | None = None) → dict[str, float]

scores of all agents given the asset multiplier.

Parameters:

assets_multiplier – a multiplier to multiply the assets with.

trading_prices_for(discount: float = 1.0, condition='executed') → numpy.ndarray

Calculates the prices at which all products traded using an optional discount factor

Parameters:

• discount – A discount factor to treat older prices less importantly (exponential discounting).

• condition – The condition for contracts to consider. Possible values are executed, signed, concluded, nullified

Returns:

an n_products vector of trading prices

draw(steps: tuple[int, int] | int | None = None, what: Collection[str] = DEFAULT_EDGE_TYPES, who: Callable[[negmas.Agent], bool] = None, where: Callable[[negmas.Agent], int | tuple[float, float]] = None, together: bool = True, axs: Collection[matplotlib.axis.Axis] = None, ncols: int = 4, figsize: tuple[int, int] = (15, 15), **kwargs) → tuple[matplotlib.axis.Axis, networkx.Graph] | tuple[list[matplotlib.axis.Axis], list[networkx.Graph]]

class scml.scml2020.world.SCML2021World(*args, **kwargs)

Bases: SCML2020World

A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020.

Parameters:

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

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

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

• profiles – An n_agents list of FactoryProfile objects specifying the private profile of the factory associated with each agent.

• agent_types – An n_agents list of strings/ SCML2020Agent classes specifying the type of each agent

• agent_params – An n_agents dictionaries giving the parameters of each agent

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

• allow_selling_input – Allows agents to sell their input product(s) through negotiation

• allow_buying_output – Allows agents to buy their output product(s) through negotiation

• catalog_quantities – The quantities in the past for which catalog_prices are the average unit prices. This is used when updating the trading prices. If set to zero then the trading price will follow the market price and will not use the catalog_price (except for products that are never sold in the market for which the trading price will take the default value of the catalog price). If set to a large value (e.g. 10000), the price at which a product is sold will not affect the trading price

• spot_market_global_loss – Buying from the spot market will cost trading-price * (1+`spot_market_global_loss) and selling to it will cost trading-price / (1+ spot_market_global_loss) for agents with unit spot-market-loss-multiplier

• financial_report_period – The number of steps between financial reports. If < 1, it is a fraction of n_steps

• borrow_on_breach – If true, agents will be forced to borrow money on breach as much as possible to honor the contract

• interest_rate – The interest at which loans grow over time (it only affect a factory when its balance is negative)

• bankruptcy_limit – The maximum amount that be be borrowed (including interest). The balance of any factory cannot go lower than - borrow_limit or the agent will go bankrupt immediately

• liquidation_rate – The rate at which future contracts get liquidated when an agent gets bankrupt. It should be between zero and one.

• compensation_fraction – Fraction of a contract to be compensated (at most) if a partner goes bankrupt. Notice that this fraction is not guaranteed because the bankrupt agent may not have enough assets to pay all of its standing contracts to this level of compensation. In such cases, a smaller fraction will be used.

• compensate_immediately – If true, compensation will happen immediately when an agent goes bankrupt and in in money. This means that agents with contracts involving the bankrupt agent will just have these contracts be nullified and receive monetary compensation immediately . If false, compensation will not happen immediately but at the contract execution time. In this case, agents with contracts involving the bankrupt agent will be informed of the compensation fraction (instead of the compensation money) at the time of bankruptcy and will receive the compensation in kind (money if they are sellers and products if they are buyers) at the normal execution time of the contract. In the special case of no-compensation (i.e. compensation_fraction is zero or the bankrupt agent has no assets), the two options will behave similarity.

• compensate_before_past_debt – If true, then compensations will be paid before past debt is considered, otherwise, the money from liquidating bankrupt agents will first be used to pay past debt then whatever remains will be used for compensation. Notice that in all cases, the trigger of bankruptcy will be paid before compensation and past debts.

• exogenous_horizon – The horizon for revealing external contracts

• exogenous_force_max – If true, exogenous contracts are forced to be signed independent of the setting of force_signing

• production_no_borrow – If true, agents will not borrow if they fail to satisfy its production need to execute a scheduled production command

• production_no_bankruptcy – If true, agents will not go bankrupt because of an production related transaction.

• production_penalty – The penalty paid when buying from spot-market to satisfy production needs

• production_confirm – If true, the factory will confirm running processes at every time-step just before running them by calling confirm_production on the agent controlling it.

• 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 – The name of the simulations

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

classmethod generate(*args, inventory_valuation_trading: numpy.ndarray | tuple[float, float] | float = (0.0, 0.5), horizon: tuple[float, float] | float = (0.2, 0.5), **kwargs) → dict[str, Any]

Generates the configuration for a world

Parameters:

• agent_types – All agent types

• agent_params – Agent parameters used to initialize them

• n_steps – Number of simulation steps

• n_processes – Number of processes in the production chain

• n_lines – Number of lines per factory

• process_inputs – Number of input units per process

• process_outputs – Number of output units per process

• production_costs – Production cost per factory

• profit_means – Mean profitability per production level (i.e. process).

• profit_stddevs – Std. Dev. of the profitability of every level (i.e. process).

• inventory_valuation_catalog – The fraction of catalog price to value items at the end.

• inventory_valuation_trading – The fraction of trading price to value items at the end.

• max_productivity – Maximum possible productivity per level (i.e. process).

• initial_balance – The initial balance of all agents

• n_agents_per_process – Number of agents per process

• agent_processes – The process for each agent. If not None , it will override n_agents_per_process and must be a list/tuple of the same length as agent_types . Morevoer, random_agent_types must be False in this case

• cost_increases_with_level – If true, production cost will be higher for processes nearer to the final product.

• profit_basis – The statistic used when controlling catalog prices by profit arguments. It can be np.mean, np.median, np.min, np.max or any Callable[[list[float]], float] and is used to summarize production costs at every level.

• horizon – The horizon used for revealing external supply/sales as a fraction of n_steps

• equal_exogenous_supply – If true, external supply will be distributed equally among all agents in the first layer

• equal_exogenous_sales – If true, external sales will be distributed equally among all agents in the last layer

• exogenous_supply_predictability – How predictable are exogenous supplies of each agent over time. 1.0 means that every agent will have the same quantity for all of its contracts over time. 0.0 means quantities per agent are completely random

• exogenous_sales_predictability – How predictable are exogenous supplies of each agent over time. 1.0 means that every agent will have the same quantity for all of its contracts over time. 0.0 means quantities per agent are completely random

• cash_availability – The fraction of the total money needs of the agent to work at maximum capacity that is available as initial_balance . This is only effective if initial_balance is set to None .

• force_signing – Whether to force contract signatures (exogenous contracts are treated in the same way).

• exogenous_control – How much control does the agent have over exogenous contract signing. Only effective if force_signing is False and use_exogenous_contracts is True

• random_agent_types – If True, the final agent types used by the generato wil always be sampled from the given types. If False, this random sampling will only happin if len(agent_types) != n_agents.

• cost_relativity – The exponent of production cost used to distribute contracts during generation

• method – The method used for world generation. Available methods are “profitable” and “guaranteed_profit”

• exogenous_supply_surplus – The surpolus exogenous supply contract quantity to add to the system as a fraction of the a fraction of the contracts generated by the given method.

• exogenous_sales_surplus – The surpolus exogenous sales contract quantity to add to the system as a fraction of the a fraction of the contracts generated by the given method.

• run_extra_checks – If given, the world generation method will check whether the genrated world “makes sense” given its internal criteria. May slow down world generation

• **kwargs –

Returns:

world configuration as a dict[str, Any]. A world can be generated from this dict by calling SCML2020World(**d)

Remarks:

• There are two general ways to use this generator:

  1. Pass random_agent_types = True, and pass agent_types, agent_processes to control placement of each agent in each level of the production graph.

  2. Pass random_agent_types = False and pass agent_types, n_agents_per_process to make the system randomly place the specified number of agents in each production level

• Most parameters (i.e. process_inputs , process_outputs , n_agents_per_process , costs ) can take a single value, a tuple of two values, or a list of values. If it has a single value, it is repeated for all processes/factories as appropriate. If it is a tuple of two numbers $(i, j)$, each process will take a number sampled from a uniform distribution supported on $[i, j]$ inclusive. If it is a list of values, of the length n_processes , it is used as it is otherwise, it is used to sample values for each process.

class scml.scml2020.world.SCML2022World(*args, **kwargs)

Bases: SCML2021World

A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020.

Parameters:

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

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

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

• profiles – An n_agents list of FactoryProfile objects specifying the private profile of the factory associated with each agent.

• agent_types – An n_agents list of strings/ SCML2020Agent classes specifying the type of each agent

• agent_params – An n_agents dictionaries giving the parameters of each agent

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

• allow_selling_input – Allows agents to sell their input product(s) through negotiation

• allow_buying_output – Allows agents to buy their output product(s) through negotiation

• catalog_quantities – The quantities in the past for which catalog_prices are the average unit prices. This is used when updating the trading prices. If set to zero then the trading price will follow the market price and will not use the catalog_price (except for products that are never sold in the market for which the trading price will take the default value of the catalog price). If set to a large value (e.g. 10000), the price at which a product is sold will not affect the trading price

• spot_market_global_loss – Buying from the spot market will cost trading-price * (1+`spot_market_global_loss) and selling to it will cost trading-price / (1+ spot_market_global_loss) for agents with unit spot-market-loss-multiplier

• financial_report_period – The number of steps between financial reports. If < 1, it is a fraction of n_steps

• borrow_on_breach – If true, agents will be forced to borrow money on breach as much as possible to honor the contract

• interest_rate – The interest at which loans grow over time (it only affect a factory when its balance is negative)

• bankruptcy_limit – The maximum amount that be be borrowed (including interest). The balance of any factory cannot go lower than - borrow_limit or the agent will go bankrupt immediately

• liquidation_rate – The rate at which future contracts get liquidated when an agent gets bankrupt. It should be between zero and one.

• compensation_fraction – Fraction of a contract to be compensated (at most) if a partner goes bankrupt. Notice that this fraction is not guaranteed because the bankrupt agent may not have enough assets to pay all of its standing contracts to this level of compensation. In such cases, a smaller fraction will be used.

• compensate_immediately – If true, compensation will happen immediately when an agent goes bankrupt and in in money. This means that agents with contracts involving the bankrupt agent will just have these contracts be nullified and receive monetary compensation immediately . If false, compensation will not happen immediately but at the contract execution time. In this case, agents with contracts involving the bankrupt agent will be informed of the compensation fraction (instead of the compensation money) at the time of bankruptcy and will receive the compensation in kind (money if they are sellers and products if they are buyers) at the normal execution time of the contract. In the special case of no-compensation (i.e. compensation_fraction is zero or the bankrupt agent has no assets), the two options will behave similarity.

• compensate_before_past_debt – If true, then compensations will be paid before past debt is considered, otherwise, the money from liquidating bankrupt agents will first be used to pay past debt then whatever remains will be used for compensation. Notice that in all cases, the trigger of bankruptcy will be paid before compensation and past debts.

• exogenous_horizon – The horizon for revealing external contracts

• exogenous_force_max – If true, exogenous contracts are forced to be signed independent of the setting of force_signing

• production_no_borrow – If true, agents will not borrow if they fail to satisfy its production need to execute a scheduled production command

• production_no_bankruptcy – If true, agents will not go bankrupt because of an production related transaction.

• production_penalty – The penalty paid when buying from spot-market to satisfy production needs

• production_confirm – If true, the factory will confirm running processes at every time-step just before running them by calling confirm_production on the agent controlling it.

• 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 – The name of the simulations

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

class scml.scml2020.world.SCML2023World(*args, **kwargs)

Bases: SCML2022World

A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020.

Parameters:

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

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

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

• profiles – An n_agents list of FactoryProfile objects specifying the private profile of the factory associated with each agent.

• agent_types – An n_agents list of strings/ SCML2020Agent classes specifying the type of each agent

• agent_params – An n_agents dictionaries giving the parameters of each agent

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

• allow_selling_input – Allows agents to sell their input product(s) through negotiation

• allow_buying_output – Allows agents to buy their output product(s) through negotiation

• catalog_quantities – The quantities in the past for which catalog_prices are the average unit prices. This is used when updating the trading prices. If set to zero then the trading price will follow the market price and will not use the catalog_price (except for products that are never sold in the market for which the trading price will take the default value of the catalog price). If set to a large value (e.g. 10000), the price at which a product is sold will not affect the trading price

• spot_market_global_loss – Buying from the spot market will cost trading-price * (1+`spot_market_global_loss) and selling to it will cost trading-price / (1+ spot_market_global_loss) for agents with unit spot-market-loss-multiplier

• financial_report_period – The number of steps between financial reports. If < 1, it is a fraction of n_steps

• borrow_on_breach – If true, agents will be forced to borrow money on breach as much as possible to honor the contract

• interest_rate – The interest at which loans grow over time (it only affect a factory when its balance is negative)

• bankruptcy_limit – The maximum amount that be be borrowed (including interest). The balance of any factory cannot go lower than - borrow_limit or the agent will go bankrupt immediately

• liquidation_rate – The rate at which future contracts get liquidated when an agent gets bankrupt. It should be between zero and one.

• compensation_fraction – Fraction of a contract to be compensated (at most) if a partner goes bankrupt. Notice that this fraction is not guaranteed because the bankrupt agent may not have enough assets to pay all of its standing contracts to this level of compensation. In such cases, a smaller fraction will be used.

• compensate_immediately – If true, compensation will happen immediately when an agent goes bankrupt and in in money. This means that agents with contracts involving the bankrupt agent will just have these contracts be nullified and receive monetary compensation immediately . If false, compensation will not happen immediately but at the contract execution time. In this case, agents with contracts involving the bankrupt agent will be informed of the compensation fraction (instead of the compensation money) at the time of bankruptcy and will receive the compensation in kind (money if they are sellers and products if they are buyers) at the normal execution time of the contract. In the special case of no-compensation (i.e. compensation_fraction is zero or the bankrupt agent has no assets), the two options will behave similarity.

• compensate_before_past_debt – If true, then compensations will be paid before past debt is considered, otherwise, the money from liquidating bankrupt agents will first be used to pay past debt then whatever remains will be used for compensation. Notice that in all cases, the trigger of bankruptcy will be paid before compensation and past debts.

• exogenous_horizon – The horizon for revealing external contracts

• exogenous_force_max – If true, exogenous contracts are forced to be signed independent of the setting of force_signing

• production_no_borrow – If true, agents will not borrow if they fail to satisfy its production need to execute a scheduled production command

• production_no_bankruptcy – If true, agents will not go bankrupt because of an production related transaction.

• production_penalty – The penalty paid when buying from spot-market to satisfy production needs

• production_confirm – If true, the factory will confirm running processes at every time-step just before running them by calling confirm_production on the agent controlling it.

• 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 – The name of the simulations

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

class scml.scml2020.world.SCML2024World(*args, **kwargs)

Bases: SCML2022World

A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020.

Parameters:

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

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

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

• profiles – An n_agents list of FactoryProfile objects specifying the private profile of the factory associated with each agent.

• agent_types – An n_agents list of strings/ SCML2020Agent classes specifying the type of each agent

• agent_params – An n_agents dictionaries giving the parameters of each agent

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

• allow_selling_input – Allows agents to sell their input product(s) through negotiation

• allow_buying_output – Allows agents to buy their output product(s) through negotiation

• catalog_quantities – The quantities in the past for which catalog_prices are the average unit prices. This is used when updating the trading prices. If set to zero then the trading price will follow the market price and will not use the catalog_price (except for products that are never sold in the market for which the trading price will take the default value of the catalog price). If set to a large value (e.g. 10000), the price at which a product is sold will not affect the trading price

• spot_market_global_loss – Buying from the spot market will cost trading-price * (1+`spot_market_global_loss) and selling to it will cost trading-price / (1+ spot_market_global_loss) for agents with unit spot-market-loss-multiplier

• financial_report_period – The number of steps between financial reports. If < 1, it is a fraction of n_steps

• borrow_on_breach – If true, agents will be forced to borrow money on breach as much as possible to honor the contract

• interest_rate – The interest at which loans grow over time (it only affect a factory when its balance is negative)

• bankruptcy_limit – The maximum amount that be be borrowed (including interest). The balance of any factory cannot go lower than - borrow_limit or the agent will go bankrupt immediately

• liquidation_rate – The rate at which future contracts get liquidated when an agent gets bankrupt. It should be between zero and one.

• compensation_fraction – Fraction of a contract to be compensated (at most) if a partner goes bankrupt. Notice that this fraction is not guaranteed because the bankrupt agent may not have enough assets to pay all of its standing contracts to this level of compensation. In such cases, a smaller fraction will be used.

• compensate_immediately – If true, compensation will happen immediately when an agent goes bankrupt and in in money. This means that agents with contracts involving the bankrupt agent will just have these contracts be nullified and receive monetary compensation immediately . If false, compensation will not happen immediately but at the contract execution time. In this case, agents with contracts involving the bankrupt agent will be informed of the compensation fraction (instead of the compensation money) at the time of bankruptcy and will receive the compensation in kind (money if they are sellers and products if they are buyers) at the normal execution time of the contract. In the special case of no-compensation (i.e. compensation_fraction is zero or the bankrupt agent has no assets), the two options will behave similarity.

• compensate_before_past_debt – If true, then compensations will be paid before past debt is considered, otherwise, the money from liquidating bankrupt agents will first be used to pay past debt then whatever remains will be used for compensation. Notice that in all cases, the trigger of bankruptcy will be paid before compensation and past debts.

• exogenous_horizon – The horizon for revealing external contracts

• exogenous_force_max – If true, exogenous contracts are forced to be signed independent of the setting of force_signing

• production_no_borrow – If true, agents will not borrow if they fail to satisfy its production need to execute a scheduled production command

• production_no_bankruptcy – If true, agents will not go bankrupt because of an production related transaction.

• production_penalty – The penalty paid when buying from spot-market to satisfy production needs

• production_confirm – If true, the factory will confirm running processes at every time-step just before running them by calling confirm_production on the agent controlling it.

• 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 – The name of the simulations

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