scml.scml2020

Implements the SCML 2020 world design.

The detailed description of this world simulation can be found here .

Subpackages

• scml.scml2020.agents
  • scml.scml2020.agents.bcse
  • scml.scml2020.agents.decentralizing
  • scml.scml2020.agents.do_nothing
  • scml.scml2020.agents.indneg
  • scml.scml2020.agents.moving
  • scml.scml2020.agents.random
  • scml.scml2020.agents.reactive
  • scml.scml2020.agents.satisficer
• scml.scml2020.components
  • scml.scml2020.components.negotiation
  • scml.scml2020.components.prediction
  • scml.scml2020.components.production
  • scml.scml2020.components.signing
  • scml.scml2020.components.simulation
  • scml.scml2020.components.trading
• scml.scml2020.services
  • scml.scml2020.services.controllers
  • scml.scml2020.services.simulators

Submodules

• scml.scml2020.agent
• scml.scml2020.awi
• scml.scml2020.common
• scml.scml2020.factory
• scml.scml2020.world

Package Contents

Classes

SCML2020Agent	Base class for all SCML2020 agents (factory managers)
OneShotAdapter	An adapter allowing agents developed for SCML-OneShot to run in
RandomAgent	An agent that negotiates randomly.
DoNothingAgent	An agent that does nothing for the whole length of the simulation
IndependentNegotiationsAgent	Implements the base class for agents that negotiate independently with different partners.
MarketAwareIndependentNegotiationsAgent	Implements the base class for agents that negotiate independently with different partners using trading/catalog
BuyCheapSellExpensiveAgent	An agent that tries to buy cheap and sell expensive but does not care about production scheduling.
MarketAwareBuyCheapSellExpensiveAgent	An agent that tries to buy cheap and sell expensive but does not care about production scheduling.
DecentralizingAgent	A negotiation manager that controls a controller and another for selling for every timestep
IndDecentralizingAgent	A negotiation manager that manages independent negotiators that do not share any information once created
DecentralizingAgentWithLogging	A negotiation manager that controls a controller and another for selling for every timestep
MarketAwareDecentralizingAgent	Predicts an amount based on publicly available market information. Falls
MarketAwareIndDecentralizingAgent	Signs all contracts that have good prices
ReactiveAgent	A negotiation manager that controls a controller and another for selling for every timestep
MarketAwareReactiveAgent	Signs all contracts that have good prices
MovingRangeAgent	My negotiation strategy
MarketAwareMovingRangeAgent	Predicts an amount based on publicly available market information. Falls
SatisficerAgent	A simple monolithic agent that tries to carefully make small profit
AWI	The Agent SCML2020World Interface for SCML2020 world.
FactoryState
FinancialReport	A report published periodically by the system showing the financial standing of an agent
FactoryProfile	Defines all private information of a factory
Failure	A production failure
ExogenousContract	Represents a contract to be revealed at revelation_time to buyer and seller between them that is not agreed upon
ProductionStrategy	Represents a strategy for controlling production.
SupplyDrivenProductionStrategy	A production strategy that converts all inputs to outputs
DemandDrivenProductionStrategy	A production strategy that produces ONLY when a contract is secured
TradeDrivenProductionStrategy	A production strategy that produces ONLY for contracts that the agent did not initiate.
TradePredictionStrategy	A prediction strategy for expected inputs and outputs at every step
FixedTradePredictionStrategy	Predicts a fixed amount of trade both for the input and output products.
ExecutionRatePredictionStrategy	A prediction strategy for expected inputs and outputs at every step
FixedERPStrategy	Predicts that the there is a fixed execution rate that does not change for all partners
MeanERPStrategy	Predicts the mean execution fraction for each partner
MarketAwareTradePredictionStrategy	Predicts an amount based on publicly available market information. Falls
SignAll	Signs all contracts no matter what.
SignAllPossible	Signs all contracts that can in principle be honored.
KeepOnlyGoodPrices	Signs all contracts that have good prices
NegotiationManager	A negotiation manager is a component that provides negotiation control functionality to an agent
StepNegotiationManager	A negotiation manager that controls a controller and another for selling for every timestep
IndependentNegotiationsManager	A negotiation manager that manages independent negotiators that do not share any information once created
MovingRangeNegotiationManager	My negotiation strategy
Simulation	Provides a simulator to the agent.
Factory	A simulated factory
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.
Failure	A production failure
AWI	The Agent SCML2020World Interface for SCML2020 world.

Functions

is_system_agent(→ bool)	Checks whether an agent is a system agent or not
builtin_agent_types([as_str])	Returns all built-in agents.

Attributes

__all__
SYSTEM_BUYER_ID	ID of the system buyer agent
SYSTEM_SELLER_ID	ID of the system seller agent
COMPENSATION_ID	ID of the takeover agent
ANY_STEP	Used to indicate any time-step
NO_COMMAND	A constant indicating no command is scheduled on a factory line
ANY_LINE	Used to indicate any line
INFINITE_COST	A constant indicating an invalid cost for lines incapable of running some process
QUANTITY	Index of quantity in negotiation issues
TIME	Index of time in negotiation issues
UNIT_PRICE	Index of unit price in negotiation issues
__all__
__all__

class scml.scml2020.SCML2020Agent(name: str | None = None, type_postfix: str = '', preferences: negmas.preferences.Preferences | None = None, ufun: negmas.preferences.UtilityFunction | None = None)

Bases: negmas.Agent

Base class for all SCML2020 agents (factory managers)

property internal_state: Dict[str, Any]

Returns the internal state of the agent for debugging purposes

reset()

is_clean() → bool

init()

Called to initialize the agent after the world is initialized. the AWI is accessible at this point.

before_step()

step_()

Called at every time-step. This function is called directly by the world.

step()

Called by the simulator at every simulation step

to_dict()

_respond_to_negotiation_request(initiator: str, partners: List[str], issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface, role: str | None, req_id: str | None) → negmas.Negotiator | None

Called by the mechanism to ask for joining a negotiation. The agent can refuse by returning a None

Parameters:

• initiator – The ID of the agent that initiated the negotiation request

• partners – The partner list (will include this agent)

• issues – The list of issues

• annotation – Any annotation specific to this negotiation.

• mechanism – The mechanism that started the negotiation

• role – The role of this agent in the negotiation

• req_id – The req_id passed to the AWI when starting the negotiation (only to the initiator).

Returns:

None to refuse the negotiation or a Negotiator object appropriate to the given mechanism to accept it.

Remarks:

• It is expected that world designers will introduce a better way to respond and override this function to call it

on_contract_breached(contract: negmas.Contract, breaches: List[negmas.Breach], resolution: negmas.Contract | None) → None

Called after complete processing of a contract that involved a breach.

Parameters:

• contract – The contract

• breaches – All breaches committed (even if they were resolved)

• resolution – The resolution contract if re-negotiation was successful. None if not.

on_contract_executed(contract: negmas.Contract) → None

Called after successful contract execution for which the agent is one of the partners.

set_renegotiation_agenda(contract: negmas.Contract, breaches: List[negmas.Breach]) → negmas.RenegotiationRequest | None

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

Parameters:

• contract – The contract being breached

• breaches – All breaches on contract

Returns:

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

respond_to_renegotiation_request(contract: negmas.Contract, breaches: List[negmas.Breach], agenda: negmas.RenegotiationRequest) → negmas.Negotiator | None

Called to respond to a renegotiation request

Parameters:

• agenda –

• contract –

• breaches –

Returns:

on_neg_request_rejected(req_id: str, by: List[str] | None)

Called when a requested negotiation is rejected

Parameters:

• req_id – The request ID passed to _request_negotiation

• by – A list of agents that refused to participate or None if the failure was for another reason

on_neg_request_accepted(req_id: str, mechanism: negmas.NegotiatorMechanismInterface)

Called when a requested negotiation is accepted

on_negotiation_failure(partners: List[str], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface, state: negmas.MechanismState) → None

Called whenever a negotiation ends without agreement

on_negotiation_success(contract: negmas.Contract, mechanism: negmas.NegotiatorMechanismInterface) → None

Called whenever a negotiation ends with agreement

on_agent_bankrupt(agent: str, contracts: List[negmas.Contract], quantities: List[int], compensation_money: int) → None

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

Parameters:

• agent – The ID of the agent that went bankrupt.

• contracts – All future contracts between this agent and the bankrupt agent.

• quantities – The actual quantities that these contracts will be executed at.

• compensation_money – The compensation money that is already added to the agent’s wallet (if ANY).

Remarks:

• compensation_money will be nonzero iff immediate_compensation is enabled for this world

on_failures(failures: List[scml.scml2020.common.Failure]) → None

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

Parameters:

failures – A list of Failure s.

respond_to_negotiation_request(initiator: str, issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) → negmas.Negotiator | None

Called whenever another agent requests a negotiation with this agent.

Parameters:

• initiator – The ID of the agent that requested this negotiation

• issues – Negotiation issues

• annotation – Annotation attached with this negotiation

• mechanism – The NegotiatorMechanismInterface interface to the mechanism to be used for this negotiation.

Returns:

None to reject the negotiation, otherwise a negotiator

confirm_production(commands: numpy.ndarray, balance: int, inventory) → numpy.ndarray

Called just before production starts at every time-step allowing the agent to change what is to be produced in its factory

Parameters:

• commands – an n_lines vector giving the process to be run at every line (NO_COMMAND indicates nothing to be processed

• balance – The current balance of the factory

• inventory – an n_products vector giving the number of items available in the inventory of every product type.

Returns:

an n_lines vector giving the process to be run at every line (NO_COMMAND indicates nothing to be processed

Remarks:

• Not called in SCML2020 competition.

• The inventory will contain zero items of all products that the factory does not buy or sell

• The default behavior is to just retrun commands confirming production of everything.

sign_all_contracts(contracts: List[negmas.Contract]) → List[str | None]

Signs all contracts

class scml.scml2020.OneShotAdapter(oneshot_type: str | scml.oneshot.agent.OneShotAgent, oneshot_params: Dict[str, Any], obj: scml.oneshot.agent.OneShotAgent | None = None, name=None, type_postfix='', ufun=None)

Bases: scml.scml2020.components.signing.SignAll, scml.scml2020.components.production.DemandDrivenProductionStrategy, scml.scml2020.components.trading.MarketAwareTradePredictionStrategy, SCML2020Agent, negmas.situated.Adapter, scml.oneshot.mixins.OneShotUFunCreatorMixin

An adapter allowing agents developed for SCML-OneShot to run in SCML2020World simulations.

property price_multiplier

property is_perishable: bool

Are all products perishable (original design of OneShot)

property current_disposal_cost: float

Cost of storing one unit (penalizes buying too much/ selling too little)

property current_storage_cost: float

Cost of storing one unit (penalizes buying too much/ selling too little)

property current_shortfall_penalty: float

Cost of failure to deliver one unit (penalizes buying too little / selling too much)

property allow_zero_quantity: bool

Does negotiations allow zero quantity?

init()

Called to initialize the agent after the world is initialized. the AWI is accessible at this point.

_make_issues(product)

before_step()

step()

Called by the simulator at every simulation step

make_ufun(add_exogenous: bool)

to_dict()

respond_to_negotiation_request(initiator, issues, annotation, mechanism)

Called whenever another agent requests a negotiation with this agent.

Parameters:

• initiator – The ID of the agent that requested this negotiation

• issues – Negotiation issues

• annotation – Annotation attached with this negotiation

• mechanism – The NegotiatorMechanismInterface interface to the mechanism to be used for this negotiation.

Returns:

None to reject the negotiation, otherwise a negotiator

get_disposal_cost() → float

get_shortfall_penalty_mean()

get_disposal_cost_mean()

get_shortfall_penalty_dev()

get_disposal_cost_dev()

get_storage_cost_mean()

get_storage_cost_dev()

get_profile()

get_shortfall_penalty()

get_current_balance()

get_exogenous_output() → Tuple[int, int]

get_exogenous_input() → Tuple[int, int]

scml.scml2020.__all__

class scml.scml2020.RandomAgent(*args, **kwargs)

Bases: scml.scml2020.agents.indneg.IndependentNegotiationsAgent

An agent that negotiates randomly.

create_ufun(is_seller: bool, issues=None, outcomes=None)

Creates a utility function

class scml.scml2020.DoNothingAgent(name: str | None = None, type_postfix: str = '', preferences: negmas.preferences.Preferences | None = None, ufun: negmas.preferences.UtilityFunction | None = None)

Bases: scml.scml2020.agent.SCML2020Agent

An agent that does nothing for the whole length of the simulation

respond_to_negotiation_request(initiator: str, issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) → negmas.Negotiator | None

Called whenever another agent requests a negotiation with this agent.

Parameters:

• initiator – The ID of the agent that requested this negotiation

• issues – Negotiation issues

• annotation – Annotation attached with this negotiation

• mechanism – The NegotiatorMechanismInterface interface to the mechanism to be used for this negotiation.

Returns:

None to reject the negotiation, otherwise a negotiator

sign_all_contracts(contracts: List[negmas.Contract]) → List[str | None]

Signs all contracts

on_contracts_finalized(signed: List[negmas.Contract], cancelled: List[negmas.Contract], rejectors: List[List[str]]) → None

Called for all contracts in a single step to inform the agent about which were finally signed and which were rejected by any agents (including itself)

Parameters:

• signed – A list of signed contracts. These are binding

• cancelled – A list of cancelled contracts. These are not binding

• rejectors – A list of lists where each of the internal lists gives the rejectors of one of the cancelled contracts. Notice that it is possible that this list is empty which means that the contract other than being rejected by any agents (if that was possible in the specific world).

Remarks:

The default implementation is to call on_contract_signed for singed contracts and on_contract_cancelled for cancelled contracts

step()

Called by the simulator at every simulation step

init()

Called to initialize the agent after the world is initialized. the AWI is accessible at this point.

on_agent_bankrupt(agent: str, contracts: List[negmas.Contract], quantities: List[int], compensation_money: int) → None

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

Parameters:

• agent – The ID of the agent that went bankrupt.

• contracts – All future contracts between this agent and the bankrupt agent.

• quantities – The actual quantities that these contracts will be executed at.

• compensation_money – The compensation money that is already added to the agent’s wallet (if ANY).

Remarks:

• compensation_money will be nonzero iff immediate_compensation is enabled for this world

on_failures(failures: List[scml.scml2020.common.Failure]) → None

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

Parameters:

failures – A list of Failure s.

on_negotiation_failure(partners: List[str], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface, state: negmas.MechanismState) → None

Called whenever a negotiation ends without agreement

on_negotiation_success(contract: negmas.Contract, mechanism: negmas.NegotiatorMechanismInterface) → None

Called whenever a negotiation ends with agreement

on_contract_cancelled(contract: negmas.Contract, rejectors: List[str]) → None

Called whenever at least a partner did not sign the contract

on_contract_executed(contract: negmas.Contract) → None

Called after successful contract execution for which the agent is one of the partners.

on_contract_breached(contract: negmas.Contract, breaches: List[negmas.Breach], resolution: negmas.Contract | None) → None

Called after complete processing of a contract that involved a breach.

Parameters:

• contract – The contract

• breaches – All breaches committed (even if they were resolved)

• resolution – The resolution contract if re-negotiation was successful. None if not.

class scml.scml2020.IndependentNegotiationsAgent(*args, **kwargs)

Bases: scml.scml2020.components.negotiation.IndependentNegotiationsManager, scml.scml2020.components.prediction.FixedTradePredictionStrategy, scml.scml2020.components.trading.ReactiveTradingStrategy, scml.scml2020.world.SCML2020Agent

Implements the base class for agents that negotiate independently with different partners.

These agents do not take production capacity, availability of materials or any other aspects of the simulation into account. They are to serve only as baselines.

Remarks:

• IndependentNegotiationsAgent agents assume that each production process has one input type with the same

  index as itself and one output type with one added to the index (i.e. process $i$ takes product $i$ as input and creates product $i+1$ as output.

• It does not assume that all lines have the same production cost (it uses the average cost though).

• It does not assume that the agent has a single production process.

acceptable_unit_price(step: int, sell: bool) → int

Returns the maximum/minimum acceptable unit price for buying/selling at the given time-step

Parameters:

• step – Simulation step

• sell – Sell or buy

target_quantity(step: int, sell: bool) → int

Returns the target quantity to sell/buy at a given time-step

Parameters:

• step – Simulation step

• sell – Sell or buy

class scml.scml2020.MarketAwareIndependentNegotiationsAgent(*args, buying_margin=None, selling_margin=None, min_price_margin=0.5, max_price_margin=0.5, **kwargs)

Bases: scml.scml2020.components.signing.KeepOnlyGoodPrices, IndependentNegotiationsAgent

Implements the base class for agents that negotiate independently with different partners using trading/catalog prices to control signing

These agents do not take production capacity, availability of materials or any other aspects of the simulation into account. They are to serve only as baselines.

Remarks:

• IndependentNegotiationsAgent agents assume that each production process has one input type with the same

  index as itself and one output type with one added to the index (i.e. process $i$ takes product $i$ as input and creates product $i+1$ as output.

• It does not assume that all lines have the same production cost (it uses the average cost though).

• It does not assume that the agent has a single production process.

class scml.scml2020.BuyCheapSellExpensiveAgent(*args, **kwargs)

Bases: scml.scml2020.agents.indneg.IndependentNegotiationsAgent

An agent that tries to buy cheap and sell expensive but does not care about production scheduling.

create_ufun(is_seller: bool, issues=None, outcomes=None)

Creates a utility function

class scml.scml2020.MarketAwareBuyCheapSellExpensiveAgent(*args, buying_margin=None, selling_margin=None, min_price_margin=0.5, max_price_margin=0.5, **kwargs)

Bases: scml.scml2020.agents.indneg.MarketAwareIndependentNegotiationsAgent, BuyCheapSellExpensiveAgent

An agent that tries to buy cheap and sell expensive but does not care about production scheduling.

class scml.scml2020.DecentralizingAgent(*args, negotiator_type: negmas.SAONegotiator | str = AspirationNegotiator, negotiator_params: Dict[str, Any] | None = None, **kwargs)

Bases: _NegotiationCallbacks, scml.scml2020.components.StepNegotiationManager, scml.scml2020.components.trading.PredictionBasedTradingStrategy, scml.scml2020.components.SupplyDrivenProductionStrategy, scml.scml2020.world.SCML2020Agent

A negotiation manager that controls a controller and another for selling for every timestep

Parameters:

• negotiator_type – The negotiator type to use to manage all negotiations

• negotiator_params – Paramters of the negotiator

Provides:

• all_negotiations_concluded

Requires:

• acceptable_unit_price

• target_quantity

• OPTIONALLY target_quantities

Hooks Into:

• init

• respond_to_negotiation_request

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

class scml.scml2020.IndDecentralizingAgent(*args, negotiator_type: negmas.SAONegotiator | str = AspirationNegotiator, negotiator_params: Dict[str, Any] | None = None, **kwargs)

Bases: _NegotiationCallbacks, scml.scml2020.components.IndependentNegotiationsManager, scml.scml2020.components.trading.PredictionBasedTradingStrategy, scml.scml2020.components.SupplyDrivenProductionStrategy, scml.scml2020.world.SCML2020Agent

A negotiation manager that manages independent negotiators that do not share any information once created

Parameters:

• negotiator_type – The negotiator type to use to manage all negotiations

• negotiator_params – Parameters of the negotiator

Requires:

• create_ufun

• acceptable_unit_price

• target_quantity

• OPTIONALLY target_quantities

Hooks Into:

• respond_to_negotiation_request

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

create_ufun(is_seller: bool, issues=None, outcomes=None)

Creates a utility function

class scml.scml2020.DecentralizingAgentWithLogging(*args, **kwargs)

Bases: _NegotiationCallbacks, scml.scml2020.components.StepNegotiationManager, scml.scml2020.components.trading.PredictionBasedTradingStrategy, scml.scml2020.components.SupplyDrivenProductionStrategy, scml.scml2020.world.SCML2020Agent

A negotiation manager that controls a controller and another for selling for every timestep

Parameters:

• negotiator_type – The negotiator type to use to manage all negotiations

• negotiator_params – Paramters of the negotiator

Provides:

• all_negotiations_concluded

Requires:

• acceptable_unit_price

• target_quantity

• OPTIONALLY target_quantities

Hooks Into:

• init

• respond_to_negotiation_request

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

class scml.scml2020.MarketAwareDecentralizingAgent(*args, buying_margin=None, selling_margin=None, min_price_margin=0.5, max_price_margin=0.5, **kwargs)

Bases: scml.scml2020.components.prediction.MarketAwareTradePredictionStrategy, _NegotiationCallbacks, scml.scml2020.components.MovingRangeNegotiationManager, scml.scml2020.components.trading.PredictionBasedTradingStrategy, scml.scml2020.components.signing.KeepOnlyGoodPrices, scml.scml2020.components.SupplyDrivenProductionStrategy, scml.scml2020.world.SCML2020Agent

Predicts an amount based on publicly available market information. Falls back to fixed prediction if no information is available

Hooks Into:

• internal_state

• on_contracts_finalized

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

class scml.scml2020.MarketAwareIndDecentralizingAgent(*args, buying_margin=None, selling_margin=None, min_price_margin=0.5, max_price_margin=0.5, **kwargs)

Bases: scml.scml2020.components.signing.KeepOnlyGoodPrices, scml.scml2020.components.prediction.MarketAwareTradePredictionStrategy, IndDecentralizingAgent

Signs all contracts that have good prices

Overrides:

• sign_all_contracts

- buying_margin

The margin from the catalog price to allow for buying. The agent will never buy at a price higher than the catalog price by more than this margin (relative to catalog price).

- selling_margin

The margin from the catalog price to allow for selling. The agent will never sell at a price lower than the catalog price by more than this margin (relative to catalog price).

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

class scml.scml2020.ReactiveAgent(*args, negotiator_type: negmas.SAONegotiator | str = AspirationNegotiator, negotiator_params: Dict[str, Any] | None = None, **kwargs)

Bases: scml.scml2020.components.StepNegotiationManager, scml.scml2020.components.trading.ReactiveTradingStrategy, scml.scml2020.components.production.TradeDrivenProductionStrategy, scml.scml2020.components.FixedTradePredictionStrategy, scml.scml2020.world.SCML2020Agent

A negotiation manager that controls a controller and another for selling for every timestep

Parameters:

• negotiator_type – The negotiator type to use to manage all negotiations

• negotiator_params – Paramters of the negotiator

Provides:

• all_negotiations_concluded

Requires:

• acceptable_unit_price

• target_quantity

• OPTIONALLY target_quantities

Hooks Into:

• init

• respond_to_negotiation_request

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

acceptable_unit_price(step: int, sell: bool) → int

Returns the maximum/minimum acceptable unit price for buying/selling at the given time-step

Parameters:

• step – Simulation step

• sell – Sell or buy

target_quantity(step: int, sell: bool) → int

Returns the target quantity to sell/buy at a given time-step

Parameters:

• step – Simulation step

• sell – Sell or buy

target_quantities(steps: Tuple[int, int], sell: bool) → numpy.ndarray

Implemented for speed but not really required

class scml.scml2020.MarketAwareReactiveAgent(*args, buying_margin=None, selling_margin=None, min_price_margin=0.5, max_price_margin=0.5, **kwargs)

Bases: scml.scml2020.components.signing.KeepOnlyGoodPrices, ReactiveAgent

Signs all contracts that have good prices

Overrides:

• sign_all_contracts

- buying_margin

The margin from the catalog price to allow for buying. The agent will never buy at a price higher than the catalog price by more than this margin (relative to catalog price).

- selling_margin

The margin from the catalog price to allow for selling. The agent will never sell at a price lower than the catalog price by more than this margin (relative to catalog price).

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

class scml.scml2020.MovingRangeAgent(*args, price_weight=0.7, utility_threshold=0.9, time_threshold=0.9, time_horizon=0.1, min_price_margin=0.5, max_price_margin=0.5, **kwargs)

Bases: scml.scml2020.components.MovingRangeNegotiationManager, scml.scml2020.components.trading.PredictionBasedTradingStrategy, scml.scml2020.components.SupplyDrivenProductionStrategy, scml.scml2020.world.SCML2020Agent

My negotiation strategy

Parameters:

• price_weight – The relative importance of price in the utility calculation.

• utility_threshold – The fraction of maximum utility above which all offers will be accepted.

• time_threshold – The fraction of the negotiation time after which any valid offers will be accepted.

• time_range – The time-range for each controller as a fraction of the number of simulation steps

Hooks Into:

• init

• step

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

class scml.scml2020.MarketAwareMovingRangeAgent(*args, min_price_margin=0.5, max_price_margin=0.5, **kwargs)

Bases: scml.scml2020.components.prediction.MarketAwareTradePredictionStrategy, MovingRangeAgent

Predicts an amount based on publicly available market information. Falls back to fixed prediction if no information is available

Hooks Into:

• internal_state

• on_contracts_finalized

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

class scml.scml2020.SatisficerAgent(*args, target_productivity=1.0, satisfying_profit=0.15, acceptable_loss=0.02, price_range=0.4, concession_rate_price=1.0, concession_rate_quantity=1.0, concession_rate_time=1.0, market_share=1, horizon=5, **kwargs)

Bases: scml.scml2020.agent.SCML2020Agent

A simple monolithic agent that tries to carefully make small profit every step.

Parameters:

• target_productivity – The productivity level targeted by the agent defined as the fraction of its lines to be active per step.

• satisfying_profit – A profit amount considered satisfactory. Used when deciding negotiation agenda and signing to decide if a price is a good price (see _good_price()). A fraction of the trading price.

• acceptable_loss – A fraction of trading price that the seller/buyer is willing to go under/over the current trading price during negotiation.

• price_range – The total range around the trading price for negotiation agendas.

• concession_rate_price – The exponent of the consession curve for price.

• concession_rate_quantity – The exponent of the consession curve for quantity.

• concession_rate_time – The exponent of the consession curve for time.

• market_share – An integer specifying the expected share of the agent in the market. The agent will assume that it can get up to (market_share / (n_competitors + market_share -1)) of all sales and supplies where n_competitors is the number of agents at the same production level. Setting it to 1 means that the agent assumes it will get the same amount of trade as all other agents. Setting it to infinity means that the agent will assume it will take all the trade in the market

• horizon – Time horizon for negotiations. If None, the exogenous_contracts_revelation horizon will be used

init()

Called once

before_step()

Called at at the BEGINNING of every production step (day)

step()

Called at the end of the day. Will request all negotiations

respond_to_negotiation_request(initiator, issues, annotation, mechanism)

Called whenever another agent requests a negotiation with this agent.

Parameters:

• initiator – The ID of the agent that requested this negotiation

• issues – Negotiation issues

• annotation – Annotation attached with this negotiation

• mechanism – The NegotiatorMechanismInterface interface to the mechanism to be used for this negotiation.

Returns:

None to reject the negotiation, otherwise a negotiator

sign_all_contracts(contracts)

Signs all contracts

on_contracts_finalized(signed, cancelled, rejectors)

Called for all contracts in a single step to inform the agent about which were finally signed and which were rejected by any agents (including itself)

Parameters:

• signed – A list of signed contracts. These are binding

• cancelled – A list of cancelled contracts. These are not binding

• rejectors – A list of lists where each of the internal lists gives the rejectors of one of the cancelled contracts. Notice that it is possible that this list is empty which means that the contract other than being rejected by any agents (if that was possible in the specific world).

Remarks:

The default implementation is to call on_contract_signed for singed contracts and on_contract_cancelled for cancelled contracts

do_production() → int

propose(state: negmas.sao.SAOState, ami: negmas.sao.SAONMI, is_selling: bool, is_requested: bool)

Used to propose to the opponent

Parameters:

• state – mechanism state including current round

• ami – Agent-mechanism-interface for accessing the negotiation mechanism

• offer – The offer proposed by the partner

• is_selling – Whether the agent is selling to this partner

• is_requested – Whether the agent requested this negotiation

respond(state, ami, is_selling, is_requested)

Responds to an offer from one partner.

Parameters:

• state – mechanism state including current round

• ami – Agent-mechanism-interface for accessing the negotiation mechanism

• offer – The offer proposed by the partner

• is_selling – Whether the agent is selling to this partner

• is_requested – Whether the agent requested this negotiation

Remarks:

• The main idea is to accept offers that are within the quantity limits for the delivery day if its price is good enough for the current stage of the negotiation.

• During negotiation, the agent starts accepting highest/lowest prices for selling/buying and gradually conceeds to the minimally acceptable price (good_price) defined as being acceptable_loss above/below the trading price for buying/selling.

on_negotiation_failure(partners, annotation, mechanism, state)

Called when a negotiation fails

on_negotiation_success(contract, mechanism)

Called when a negotiation fails

_remove_tentative_offer(selling, partner)

Removes my last offer from the tentative offers

_is_good_price(is_selling: bool, u: float, slack: float = 0.0)

Checks whether a price is good relative to current trading prices, and satisfying profit (with possible slack).

class scml.scml2020.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

scml.scml2020.SYSTEM_BUYER_ID = 'BUYER'

ID of the system buyer agent

scml.scml2020.SYSTEM_SELLER_ID = 'SELLER'

ID of the system seller agent

scml.scml2020.COMPENSATION_ID = 'COMPENSATOR'

ID of the takeover agent

scml.scml2020.ANY_STEP

Used to indicate any time-step

scml.scml2020.NO_COMMAND

A constant indicating no command is scheduled on a factory line

scml.scml2020.ANY_LINE

Used to indicate any line

scml.scml2020.INFINITE_COST

A constant indicating an invalid cost for lines incapable of running some process

scml.scml2020.QUANTITY = 0

Index of quantity in negotiation issues

scml.scml2020.TIME = 1

Index of time in negotiation issues

scml.scml2020.UNIT_PRICE = 2

Index of unit price in negotiation issues

scml.scml2020.is_system_agent(aid: str) → bool

Checks whether an agent is a system agent or not

Parameters:

aid – Agent ID

Returns:

True if the ID is for a system agent.

class scml.scml2020.FactoryState

property n_lines: int

property n_steps: int

property n_products: int

property n_processes: int

inventory: numpy.ndarray

An n_products vector giving current quantity of every product in storage

balance: int

Current balance in the wallet

commands: numpy.ndarray

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

inventory_changes: numpy.ndarray

Changes in the inventory in the last step

balance_change: int

Change in the balance in the last step

contracts: list[list[ContractInfo]]

The An n_steps list of lists containing the contracts of this agent by time-step

class scml.scml2020.FinancialReport

A report published periodically by the system showing the financial standing of an agent

__slots__ = ['agent_id', 'step', 'cash', 'assets', 'breach_prob', 'breach_level', 'is_bankrupt', 'agent_name']

agent_id: str

Agent ID

step: int

Simulation step at the beginning of which the report was published.

cash: int

Cash in the agent’s wallet. Negative numbers indicate liabilities.

assets: int

Value of the products in the agent’s inventory @ catalog prices.

breach_prob: float

Number of times the agent breached a contract over the total number of contracts it signed.

breach_level: float

Sum of the agent’s breach levels so far divided by the number of contracts it signed.

is_bankrupt: bool

Whether the agent is already bankrupt (i.e. incapable of doing any more transactions).

agent_name: str

Agent name for printing purposes

__str__()

Return str(self).

class scml.scml2020.FactoryProfile

Defines all private information of a factory

property n_lines

property n_products

property n_processes

property processes: numpy.ndarray

The processes that have valid costs

property input_products: numpy.ndarray

The input products to all processes runnable (See processes )

property output_products: numpy.ndarray

The output products to all processes runnable (See processes )

__slots__ = ['costs']

costs: numpy.ndarray

An n_lines * n_processes array giving the cost of executing any process (INVALID_COST indicates infinity)

class scml.scml2020.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.ExogenousContract

Represents a contract to be revealed at revelation_time to buyer and seller between them that is not agreed upon through negotiation but is endogenously given

product: int

Product

quantity: int

Quantity

unit_price: int

Unit price

time: int

Delivery time

revelation_time: int

Time at which to reveal the contract to both buyer and seller

seller: int

Seller index in the agents array (-1 means “system”)

buyer: int

Buyer index in the agents array (-1 means “system”)

scml.scml2020.__all__

class scml.scml2020.ProductionStrategy(*args, **kwargs)

Represents a strategy for controlling production.

Provides:

• schedule_range : A mapping from contract ID to a tuple of the first and last steps at which some lines are occupied to produce the quantity specified by the contract and whether it is a sell contract

• can_be_produced : Given a contract, it returns whether or not it is possible to produce the quantity entailed by it (which means that there is enough vacant production line slots before/after the contracts delivery time for sell/buy contracts).

Hooks Into:

• on_contract_breached

• on_contract_executed

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

schedule_range: dict[str, tuple[int, int, bool]]

Gives the range of steps at which the production needed for a given contract are scheduled

can_be_produced(contract_id: str)

Returns True if the SELL contract given can be honored in principle given the production capacity of the agent (n. lines). It does not check for the availability of inputs or enough money to run the production process.

Remarks:

• Cannot be called before calling on_contracts_finalized

on_contract_executed(contract: negmas.Contract) → None

on_contract_breached(contract: negmas.Contract, breaches, resolution) → None

class scml.scml2020.SupplyDrivenProductionStrategy(*args, **kwargs)

Bases: ProductionStrategy

A production strategy that converts all inputs to outputs

Hooks Into:

• step

• on_contracts_finalized

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

step()

on_contracts_finalized(signed: list[negmas.Contract], cancelled: list[negmas.Contract], rejectors: list[list[str]]) → None

class scml.scml2020.DemandDrivenProductionStrategy(*args, **kwargs)

Bases: ProductionStrategy

A production strategy that produces ONLY when a contract is secured

Hooks Into:

• on_contract_finalized

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

on_contracts_finalized(signed: list[negmas.Contract], cancelled: list[negmas.Contract], rejectors: list[list[str]]) → None

class scml.scml2020.TradeDrivenProductionStrategy(*args, **kwargs)

Bases: ProductionStrategy

A production strategy that produces ONLY for contracts that the agent did not initiate.

Hooks Into:

• on_contract_finalized

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

on_contracts_finalized(signed: list[negmas.Contract], cancelled: list[negmas.Contract], rejectors: list[list[str]]) → None

class scml.scml2020.TradePredictionStrategy(*args, predicted_outputs: int | numpy.ndarray = None, predicted_inputs: int | numpy.ndarray = None, add_trade=False, **kwargs)

A prediction strategy for expected inputs and outputs at every step

Parameters:

• predicted_inputs (-) – None for default, a number of an n_steps numbers giving predicted inputs

• predicted_outputs (-) – None for default, a number of an n_steps numbers giving predicted outputs

Provides:

• expected_inputs : n_steps vector giving the predicted inputs at every time-step. It defaults to the number of lines.

• expected_outputs : n_steps vector giving the predicted outputs at every time-step. It defaults to the number of lines.

• input_cost : n_steps vector giving the predicted input cost at every time-step. It defaults to catalog price.

• output_price : n_steps vector giving the predicted output price at every time-step. It defaults to catalog price.

Hooks Into:

• init

• before_step

• step

Abstract:

• trade_prediction_init: Called during init() to initialize the trade prediction.

• trade_prediction_step: Called during step() to update the trade prediction.

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

expected_outputs

Expected output quantity every step

expected_inputs

Expected input quantity every step

input_cost: numpy.ndarray

Expected unit price of the input

output_price: numpy.ndarray

Expected unit price of the output

abstract trade_prediction_init() → None

Will be called to update expected_outputs, expected_inputs, input_cost, output_cost during init()

trade_prediction_before_step() → None

Will be called at the beginning of every step to update the prediction

trade_prediction_step() → None

Will be called at the end of every step to update the prediction

init()

before_step()

step()

class scml.scml2020.FixedTradePredictionStrategy(*args, add_trade=True, **kwargs)

Bases: TradePredictionStrategy

Predicts a fixed amount of trade both for the input and output products.

Hooks Into:

• internal_state

• on_contracts_finalized

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

property internal_state

trade_prediction_init()

Will be called to update expected_outputs, expected_inputs, input_cost, output_cost during init()

on_contracts_finalized(signed: List[negmas.Contract], cancelled: List[negmas.Contract], rejectors: List[List[str]]) → None

class scml.scml2020.ExecutionRatePredictionStrategy

A prediction strategy for expected inputs and outputs at every step

Provides:

• predict_quantity : A method for predicting the quantity that will actually be executed from a contract

Abstract:

• predict_quantity : A method for predicting the quantity that will actually be executed from a contract

Hooks Into:

• internal_state

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

abstract predict_quantity(contract: negmas.Contract)

class scml.scml2020.FixedERPStrategy(*args, execution_fraction=0.95, **kwargs)

Bases: ExecutionRatePredictionStrategy

Predicts that the there is a fixed execution rate that does not change for all partners

Parameters:

execution_fraction – The expected fraction of any contract’s quantity to be executed

Provides:

• predict_quantity : A method for predicting the quantity that will actually be executed from a contract

Hooks Into:

• internal_state

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

predict_quantity(contract: negmas.Contract)

class scml.scml2020.MeanERPStrategy(*args, execution_fraction=0.95, **kwargs)

Bases: ExecutionRatePredictionStrategy

Predicts the mean execution fraction for each partner

Parameters:

execution_fraction – The expected fraction of any contract’s quantity to be executed

Provides:

• predict_quantity : A method for predicting the quantity that will actually be executed from a contract

Hooks Into:

• internal_state

• init

• on_contract_executed

• on_contract_breached

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

property internal_state

predict_quantity(contract: negmas.Contract)

init()

on_contract_executed(contract: negmas.Contract) → None

on_contract_breached(contract: negmas.Contract, breaches: List[negmas.Breach], resolution: negmas.Contract | None) → None

class scml.scml2020.MarketAwareTradePredictionStrategy(*args, predicted_outputs: int | numpy.ndarray = None, predicted_inputs: int | numpy.ndarray = None, add_trade=False, **kwargs)

Bases: TradePredictionStrategy

Predicts an amount based on publicly available market information. Falls back to fixed prediction if no information is available

Hooks Into:

• internal_state

• on_contracts_finalized

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

property internal_state

init()

trade_prediction_init()

Will be called to update expected_outputs, expected_inputs, input_cost, output_cost during init()

__update()

trade_prediction_step()

Will be called at the end of every step to update the prediction

trade_prediction_before_step()

Will be called at the beginning of every step to update the prediction

class scml.scml2020.SignAll

Signs all contracts no matter what.

Overrides:

• sign_all_contracts

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

sign_all_contracts(contracts: List[negmas.Contract]) → List[str | None]

class scml.scml2020.SignAllPossible

Signs all contracts that can in principle be honored. The only check made by this strategy is that for sell contracts there is enough production capacity

Overrides:

• sign_all_contracts

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

sign_all_contracts(contracts: List[negmas.Contract]) → List[str | None]

class scml.scml2020.KeepOnlyGoodPrices(*args, buying_margin=0.5, selling_margin=0.5, **kwargs)

Signs all contracts that have good prices

Overrides:

• sign_all_contracts

- buying_margin

The margin from the catalog price to allow for buying. The agent will never buy at a price higher than the catalog price by more than this margin (relative to catalog price).

- selling_margin

The margin from the catalog price to allow for selling. The agent will never sell at a price lower than the catalog price by more than this margin (relative to catalog price).

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

sign_all_contracts(contracts: List[negmas.Contract]) → List[str | None]

class scml.scml2020.NegotiationManager(*args, horizon=5, negotiate_on_signing=True, logdebug=False, use_trading_prices=True, min_price_margin=0.5, max_price_margin=0.5, **kwargs)

A negotiation manager is a component that provides negotiation control functionality to an agent

Parameters:

horizon – The number of steps in the future to consider for selling outputs.

Provides:

• start_negotiations An easy to use method to start a set of buy/sell negotiations

Requires:

• acceptable_unit_price

• target_quantity

• OPTIONALLY target_quantities

Abstract:

• respond_to_negotiation_request

Hooks Into:

• init

• step

• on_contracts_finalized

• respond_to_negotiation_request

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

property use_trading

init()

start_negotiations(product: int, quantity: int, unit_price: int, step: int, partners: List[str] = None) → None

Starts a set of negotiations to buy/sell the product with the given limits

Parameters:

• product – product type. If it is an input product, negotiations to buy it will be started otherweise to sell.

• quantity – The maximum quantity to negotiate about

• unit_price – The maximum/minimum unit price for buy/sell

• step – The maximum/minimum time for buy/sell

• partners – A list of partners to negotiate with

Remarks:

• This method assumes that product is either my_input_product or my_output_product

step()

Generates buy and sell negotiations as needed

on_contracts_finalized(signed: List[negmas.Contract], cancelled: List[negmas.Contract], rejectors: List[List[str]]) → None

_generate_negotiations(step: int, sell: bool) → None

Generates all the required negotiations for selling/buying for the given step

_urange(step, is_seller, time_range)

_trange(step, is_seller)

target_quantities(steps: Tuple[int, int], sell: bool) → numpy.ndarray

Returns the target quantity to negotiate about for each step in the range given (beginning included and ending excluded) for buying/selling

Parameters:

• steps – Simulation step

• sell – Sell or buy

abstract _start_negotiations(product: int, sell: bool, step: int, qvalues: Tuple[int, int], uvalues: Tuple[int, int], tvalues: Tuple[int, int], partners: List[str]) → None

Actually start negotiations with the given agenda

Parameters:

• product – The product to negotiate about.

• sell – If true, this is a sell negotiation

• step – The step

• qvalues – the range of quantities

• uvalues – the range of unit prices

• tvalues – the range of times

• partners – partners

abstract target_quantity(step: int, sell: bool) → int

Returns the target quantity to sell/buy at a given time-step

Parameters:

• step – Simulation step

• sell – Sell or buy

abstract acceptable_unit_price(step: int, sell: bool) → int

Returns the maximum/minimum acceptable unit price for buying/selling at the given time-step

Parameters:

• step – Simulation step

• sell – Sell or buy

abstract respond_to_negotiation_request(initiator: str, issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) → negmas.Negotiator | None

class scml.scml2020.StepNegotiationManager(*args, negotiator_type: negmas.SAONegotiator | str = AspirationNegotiator, negotiator_params: Dict[str, Any] | None = None, **kwargs)

Bases: scml.scml2020.components.prediction.MeanERPStrategy, NegotiationManager

A negotiation manager that controls a controller and another for selling for every timestep

Parameters:

• negotiator_type – The negotiator type to use to manage all negotiations

• negotiator_params – Paramters of the negotiator

Provides:

• all_negotiations_concluded

Requires:

• acceptable_unit_price

• target_quantity

• OPTIONALLY target_quantities

Hooks Into:

• init

• respond_to_negotiation_request

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

init()

_start_negotiations(product: int, sell: bool, step: int, qvalues: Tuple[int, int], uvalues: Tuple[int, int], tvalues: Tuple[int, int], partners: List[str]) → None

Actually start negotiations with the given agenda

Parameters:

• product – The product to negotiate about.

• sell – If true, this is a sell negotiation

• step – The step

• qvalues – the range of quantities

• uvalues – the range of unit prices

• tvalues – the range of times

• partners – partners

respond_to_negotiation_request(initiator: str, issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) → negmas.Negotiator | None

all_negotiations_concluded(controller_index: int, is_seller: bool) → None

Called by the StepController to affirm that it is done negotiating for some time-step

add_controller(is_seller: bool, target, urange: Tuple[int, int], expected_quantity: int, step: int) → scml.scml2020.services.controllers.StepController

insert_controller(controller: scml.scml2020.services.controllers.StepController, is_seller: bool, target, urange: Tuple[int, int], expected_quantity: int, step: int = None) → scml.scml2020.services.controllers.StepController

create_controller(is_seller: bool, target, urange: Tuple[int, int], expected_quantity: int, step: int) → scml.scml2020.services.controllers.StepController

_get_controller(mechanism) → scml.scml2020.services.controllers.StepController

class scml.scml2020.IndependentNegotiationsManager(*args, negotiator_type: negmas.SAONegotiator | str = AspirationNegotiator, negotiator_params: Dict[str, Any] | None = None, **kwargs)

Bases: NegotiationManager

A negotiation manager that manages independent negotiators that do not share any information once created

Parameters:

• negotiator_type – The negotiator type to use to manage all negotiations

• negotiator_params – Parameters of the negotiator

Requires:

• create_ufun

• acceptable_unit_price

• target_quantity

• OPTIONALLY target_quantities

Hooks Into:

• respond_to_negotiation_request

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

_start_negotiations(product: int, sell: bool, step: int, qvalues: Tuple[int, int], uvalues: Tuple[int, int], tvalues: Tuple[int, int], partners: List[str]) → None

Actually start negotiations with the given agenda

Parameters:

• product – The product to negotiate about.

• sell – If true, this is a sell negotiation

• step – The step

• qvalues – the range of quantities

• uvalues – the range of unit prices

• tvalues – the range of times

• partners – partners

respond_to_negotiation_request(initiator: str, issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) → negmas.Negotiator | None

create_ufun(is_seller: bool, issues=None, outcomes=None) → negmas.UtilityFunction

Creates a utility function

negotiator(is_seller: bool, issues=None, outcomes=None, partner=None) → negmas.SAONegotiator

Creates a negotiator

class scml.scml2020.MovingRangeNegotiationManager(*args, price_weight=0.7, utility_threshold=0.9, time_threshold=0.9, time_horizon=0.1, min_price_margin=0.5, max_price_margin=0.5, **kwargs)

My negotiation strategy

Parameters:

• price_weight – The relative importance of price in the utility calculation.

• utility_threshold – The fraction of maximum utility above which all offers will be accepted.

• time_threshold – The fraction of the negotiation time after which any valid offers will be accepted.

• time_range – The time-range for each controller as a fraction of the number of simulation steps

Hooks Into:

• init

• step

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

step()

respond_to_negotiation_request(initiator: str, issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) → negmas.Negotiator | None

class scml.scml2020.Simulation(*args, **kwargs)

Provides a simulator to the agent.

Provides:

• simulator (FactorySimulator): A simulator that can be used to simulate the effect of contracts on the future of the factory

Hooks Into:

• init

• step

Remarks:

• Attributes section describes the attributes that can be used to construct the component (passed to its __init__ method).

• Provides section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the Bases section above for all the bases of this component).

• Requires section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component

• Abstract section describes abstract methods that MUST be implemented by any descendant of this component.

• Hooks Into section describes the methods this component overrides calling super () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with on_ are hooked into this way.

• Overrides section describes the methods this component overrides without calling super effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with on_) are overridden this way.

init()

step()

class scml.scml2020.Factory(profile: scml.scml2020.common.FactoryProfile, initial_balance: int, inputs: numpy.ndarray, outputs: numpy.ndarray, catalog_prices: numpy.ndarray, world: scml.scml2020.world.SCML2020World, compensate_before_past_debt: bool, buy_missing_products: bool, production_buy_missing: bool, production_penalty: float, production_no_bankruptcy: bool, production_no_borrow: bool, agent_id: str, agent_name: str | None = None, confirm_production: bool = True, initial_inventory: numpy.ndarray | None = None, disallow_concurrent_negs_with_same_partners=False)

A simulated factory

property state: scml.scml2020.common.FactoryState

property current_inventory: numpy.ndarray

Current inventory contents

property current_balance: int

Current wallet balance

_disallow_concurrent_negs_with_same_partners

The readonly factory profile (See FactoryProfile )

commands

An n_steps * n_lines array giving the process scheduled for each line at every step. -1 indicates an empty line.

_balance

Current balance

_inventory

Current inventory

agent_id

A unique ID for the agent owning the factory

inputs

An n_process array giving the number of inputs needed for each process (of the product with the same index)

outputs

An n_process array giving the number of outputs produced by each process (of the product with the next index)

inventory_changes

Changes in the inventory in the last step

balance_change = 0

Change in the balance in the last step

min_balance

The minimum balance possible

is_bankrupt = False

Will be true when the factory is bankrupt

agent_name

SCML2020Agent names used for logging purposes

contracts: List[List[scml.scml2020.common.ContractInfo]]

A list of lists of contracts per time-step (len == n_steps)

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 production of the given process on the given step and line.

Parameters:

• process – The process index

• 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

• partial_ok – If true, it is OK to produce only a subset of repeats

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.

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.

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

Cancels pre-ordered production given that it did not start yet.

Parameters:

• step – Step to cancel at

• line – Line to cancel at

Returns:

True if step >= self.current_step

Remarks:

• Cannot cancel a process in the past or present.

step() → List[scml.scml2020.common.Failure]

Override this method to modify stepping logic.

spot_price(product: int, spot_loss: float) → int

Get the current spot price for buying the given product on the spot market

Parameters:

• product – Product

• spot_loss – Spot loss specific to that agent

Returns:

The unit price

store(product: int, quantity: int, buy_missing: bool, spot_price: float, no_bankruptcy: bool = False, no_borrowing: bool = False) → int

Stores the given amount of product (signed) to the factory.

Parameters:

• product – Product

• quantity – quantity to store/take out (-ve means take out)

• buy_missing – If the quantity is negative and not enough product exists in the market, it buys the product from the spot-market at an increased price of penalty

• spot_price – The fraction of unit_price added because we are buying from the spot market. Only effective if quantity is negative and not enough of the product exists in the inventory

• no_bankruptcy – Never bankrupt the agent on this transaction

• no_borrowing – Never borrow for this transaction

Returns:

The quantity actually stored or taken out (always positive)

buy(product: int, quantity: int, unit_price: int, buy_missing: bool, penalty: float, no_bankruptcy: bool = False, no_borrowing: bool = False) → Tuple[int, int]

Executes a transaction to buy/sell involving adding quantity and paying price (both are signed)

Parameters:

• product – The product transacted on

• quantity – The quantity (added)

• unit_price – The unit price (paid)

• buy_missing – If true, attempt buying missing products from the spot market

• penalty – The penalty as a fraction to be paid for breaches

• no_bankruptcy – If true, this transaction can never lead to bankruptcy

• no_borrowing – If true, this transaction can never lead to borrowing

Returns:

Tuple[int, int] The actual quantities bought and the total cost

pay(money: int, no_bankruptcy: bool = False, no_borrowing: bool = False, unit: int = 0) → int

Pays money

Parameters:

• money – amount to pay

• no_bankruptcy – If true, this transaction can never lead to bankruptcy

• no_borrowing – If true, this transaction can never lead to borrowing

• unit – If nonzero then an integer multiple of unit will be paid

Returns:

The amount actually paid

bankrupt(required: int) → int

Bankruptcy processing for the given agent

Parameters:

required – The money required after the bankruptcy is processed

Returns:

The amount of money to pay back to the entity that should have been paid money

class scml.scml2020.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.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.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.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.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.

class scml.scml2020.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.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

scml.scml2020.builtin_agent_types(as_str=False)

Returns all built-in agents.

Parameters:

as_str – If true, the full type name will be returned otherwise the type object itself.

scml.scml2020.__all__