scml¶
-
class
scml.
DoNothingAgent
(**kwargs)[source]¶ An agent that does nothing for the whole length of the simulation
-
init
()[source]¶ Called to initialize the agent after the world is initialized. the AWI is accessible at this point.
-
on_agent_bankrupt
(agent, contracts, quantities, compensation_money)[source]¶ Called whenever a contract is nullified (because the partner is bankrupt)
- Parameters
agent (
str
) – The ID of the agent that went bankrupt.contracts (
List
[Contract
]) – All future contracts between this agent and the bankrupt agent.quantities (
List
[int
]) – The actual quantities that these contracts will be executed at.compensation_money (
int
) – 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
- Return type
None
-
on_contract_breached
(contract, breaches, resolution)[source]¶ Called after complete processing of a contract that involved a breach.
-
on_contract_cancelled
(contract, rejectors)[source]¶ Called whenever at least a partner did not sign the contract
- Return type
None
-
on_contract_executed
(contract)[source]¶ Called after successful contract execution for which the agent is one of the partners.
- Return type
None
-
on_contracts_finalized
(signed, cancelled, rejectors)[source]¶ 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 (
List
[Contract
]) – A list of signed contracts. These are bindingcancelled (
List
[Contract
]) – A list of cancelled contracts. These are not bindingrejectors (
List
[List
[str
]]) – 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 andon_contract_cancelled
for cancelled contracts- Return type
None
-
on_failures
(failures)[source]¶ Called whenever there are failures either in production or in execution of guaranteed transactions
-
on_negotiation_failure
(partners, annotation, mechanism, state)[source]¶ Called whenever a negotiation ends without agreement
- Return type
None
-
on_negotiation_success
(contract, mechanism)[source]¶ Called whenever a negotiation ends with agreement
- Return type
None
-
respond_to_negotiation_request
(initiator, issues, annotation, mechanism)[source]¶ Called whenever another agent requests a negotiation with this agent.
- Parameters
initiator (
str
) – The ID of the agent that requested this negotiationissues (
List
[Issue
]) – Negotiation issuesannotation (
Dict
[str
,Any
]) – Annotation attached with this negotiationmechanism (
AgentMechanismInterface
) – TheAgentMechanismInterface
interface to the mechanism to be used for this negotiation.
- Return type
Optional
[Negotiator
]- Returns
None to reject the negotiation, otherwise a negotiator
-
sign_all_contracts
(contracts)[source]¶ Called to sign all contracts concluded in a single step by this agent
- Remarks:
default implementation calls
sign_contract
for each contract returning the results
-
-
class
scml.
IndependentNegotiationsAgent
(*args, **kwargs)[source]¶ 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 sameindex 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.
BuyCheapSellExpensiveAgent
(*args, **kwargs)[source]¶ An agent that tries to buy cheap and sell expensive but does not care about production scheduling.
-
class
scml.
DecentralizingAgent
(*args, negotiator_type=<class 'negmas.sao.AspirationNegotiator'>, negotiator_params=None, **kwargs)[source]¶
-
class
scml.
IndDecentralizingAgent
(*args, negotiator_type=<class 'negmas.sao.AspirationNegotiator'>, negotiator_params=None, **kwargs)[source]¶
-
class
scml.
ReactiveAgent
(*args, negotiator_type=<class 'negmas.sao.AspirationNegotiator'>, negotiator_params=None, **kwargs)[source]¶ -
acceptable_unit_price
(step, sell)[source]¶ Returns the maximum/minimum acceptable unit price for buying/selling at the given time-step
-
-
class
scml.
MovingRangeAgent
(*args, price_weight=0.7, utility_threshold=0.9, time_threshold=0.9, time_horizon=0.1, **kwargs)[source]¶
-
class
scml.
FactoryState
(inventory, balance, commands, inventory_changes, balance_change, contracts)[source]¶ -
balance
= None¶ Current balance in the wallet
-
balance_change
= None¶ Change in the balance in the last step
-
commands
= None¶ n_steps * n_lines array giving the process scheduled on each line at every step for the whole simulation
-
contracts
= None¶ The An n_steps list of lists containing the contracts of this agent by time-step
-
inventory
= None¶ An n_products vector giving current quantity of every product in storage
-
inventory_changes
= None¶ Changes in the inventory in the last step
-
-
class
scml.
SCML2020Agent
(**kwargs)[source]¶ Base class for all SCML2020 agents (factory managers)
-
confirm_production
(commands, balance, inventory)[source]¶ Called just before production starts at every time-step allowing the agent to change what is to be produced in its factory
- Parameters
- Return 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.
-
init
()[source]¶ Called to initialize the agent after the world is initialized. the AWI is accessible at this point.
-
property
internal_state
¶ Returns the internal state of the agent for debugging purposes
-
on_agent_bankrupt
(agent, contracts, quantities, compensation_money)[source]¶ Called whenever a contract is nullified (because the partner is bankrupt)
- Parameters
agent (
str
) – The ID of the agent that went bankrupt.contracts (
List
[Contract
]) – All future contracts between this agent and the bankrupt agent.quantities (
List
[int
]) – The actual quantities that these contracts will be executed at.compensation_money (
int
) – 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
- Return type
None
-
on_contract_breached
(contract, breaches, resolution)[source]¶ Called after complete processing of a contract that involved a breach.
-
on_contract_executed
(contract)[source]¶ Called after successful contract execution for which the agent is one of the partners.
- Return type
None
-
on_failures
(failures)[source]¶ Called whenever there are failures either in production or in execution of guaranteed transactions
-
on_negotiation_failure
(partners, annotation, mechanism, state)[source]¶ Called whenever a negotiation ends without agreement
- Return type
None
-
on_negotiation_success
(contract, mechanism)[source]¶ Called whenever a negotiation ends with agreement
- Return type
None
-
respond_to_negotiation_request
(initiator, issues, annotation, mechanism)[source]¶ Called whenever another agent requests a negotiation with this agent.
- Parameters
initiator (
str
) – The ID of the agent that requested this negotiationissues (
List
[Issue
]) – Negotiation issuesannotation (
Dict
[str
,Any
]) – Annotation attached with this negotiationmechanism (
AgentMechanismInterface
) – TheAgentMechanismInterface
interface to the mechanism to be used for this negotiation.
- Return type
Optional
[Negotiator
]- Returns
None to reject the negotiation, otherwise a negotiator
-
respond_to_renegotiation_request
(contract, breaches, agenda)[source]¶ Called to respond to a renegotiation request
- Parameters
agenda (
RenegotiationRequest
) –contract (
Contract
) –breaches (
List
[Breach
]) –
Returns:
- Return type
Optional
[Negotiator
]
-
-
class
scml.
AWI
(world, agent)[source]¶ The Agent SCML2020World Interface for SCML2020 world allowing a single process per agent
-
property
all_consumers
¶ Returns a list of agent IDs for all consumers for every product
-
property
all_suppliers
¶ Returns a list of agent IDs for all suppliers for every product
-
available_for_production
(repeats, step=-1, line=-1, override=True, method='latest')[source]¶ Finds available times and lines for scheduling production.
- Parameters
repeats (
int
) – How many times to repeat the processstep (
Union
[int
,Tuple
[int
,int
]]) – 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 (
int
) – The production line. The special value ANY_LINE gives the factory the freedom to use any lineoverride (
bool
) – Whether to override any existing commands at that line at that time.method (
str
) – When to schedule the command if step was set to a range. Options are latest, earliest, all
- Return type
- 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, line)[source]¶ Cancels any production commands on that line at this step
- Parameters
- Return type
- Returns
success/failure
Remarks:
The step cannot be in the past or the current step. Cancellation can only be ordered for future steps
-
property
my_consumers
¶ Returns a list of IDs for all the agent’s consumers (agents that can consume at least one product it may produce).
Remarks:
If the agent have multiple output products, consumers of a specific product $p$ can be found using: self.all_consumers[p].
-
property
my_input_product
¶ Returns a list of products that are inputs to at least one process the agent can run
- Return type
-
property
my_input_products
¶ Returns a list of products that are inputs to at least one process the agent can run
- Return type
-
property
my_output_product
¶ Returns a list of products that are outputs to at least one process the agent can run
- Return type
-
property
my_output_products
¶ Returns a list of products that are outputs to at least one process the agent can run
- Return type
-
property
my_suppliers
¶ Returns a list of IDs for all of the agent’s suppliers (agents that can supply at least one product it may need).
Remarks:
If the agent have multiple input products, suppliers of a specific product $p$ can be found using: self.all_suppliers[p].
-
property
n_lines
¶ The number of lines in the corresponding factory. You can read
state
to get this among other information- Return type
-
order_production
(process, steps, lines)[source]¶ Orders production of the given process
- Parameters
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
- Return type
None
-
property
profile
¶ Gets the profile (static private information) associated with the agent
- Return type
-
reports_at_step
(step)[source]¶ Returns a dictionary mapping agent ID to its financial report for the given time-step
- Return type
-
reports_of_agent
(aid)[source]¶ Returns a dictionary mapping time-steps to financial reports of the given agent
- Return type
-
request_negotiation
(is_buy, product, quantity, unit_price, time, partner, negotiator, extra=None)[source]¶ Requests a negotiation
- Parameters
is_buy (
bool
) – If True the negotiation is about buying otherwise selling.product (
int
) – The product to negotiate aboutquantity (
Union
[int
,Tuple
[int
,int
]]) – The minimum and maximum quantities. Passing a single value q is equivalent to passing (q,q)unit_price (
Union
[int
,Tuple
[int
,int
]]) – The minimum and maximum unit prices. Passing a single value u is equivalent to passing (u,u)time (
Union
[int
,Tuple
[int
,int
]]) – The minimum and maximum delivery step. Passing a single value t is equivalent to passing (t,t)partner (
str
) – ID of the partner to negotiate with.negotiator (
SAONegotiator
) – The negotiator to use for this negotiation (if the partner accepted to negotiate)extra (
Optional
[Dict
[str
,Any
]]) – Extra information accessible through the negotiation annotation to the caller
- Return type
- 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):
Buying an input product (i.e. product $in$
my_input_products
) and an output product if the world settings allows it (seeallow_buying_output
)
Selling an output product (i.e. product $in$
my_output_products
) and an input product if the world settings allows it (seeallow_selling_input
)
-
request_negotiations
(is_buy, product, quantity, unit_price, time, controller, negotiators=None, partners=None, extra=None)[source]¶ Requests a negotiation
- Parameters
is_buy (
bool
) – If True the negotiation is about buying otherwise selling.product (
int
) – The product to negotiate aboutquantity (
Union
[int
,Tuple
[int
,int
]]) – The minimum and maximum quantities. Passing a single value q is equivalent to passing (q,q)unit_price (
Union
[int
,Tuple
[int
,int
]]) – The minimum and maximum unit prices. Passing a single value u is equivalent to passing (u,u)time (
Union
[int
,Tuple
[int
,int
]]) – The minimum and maximum delivery step. Passing a single value t is equivalent to passing (t,t)controller (
SAOController
) – The controller to manage the complete set of negotiationsnegotiators (
Optional
[List
[Negotiator
]]) – An optional list of negotiators to use for negotiating with the given partners (in the same order).partners (
Optional
[List
[str
]]) – ID of all the partners to negotiate with.extra (
Optional
[Dict
[str
,Any
]]) – Extra information accessible through the negotiation annotation to the caller
- Return type
- 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):
Buying an input product (i.e. product $in$
my_input_products
) and an output product if the world settings allows it (seeallow_buying_output
)
Selling an output product (i.e. product $in$
my_output_products
) and an input product if the world settings allows it (seeallow_selling_input
)
-
schedule_production
(process, repeats, step=-1, line=-1, override=True, method='latest', partial_ok=False)[source]¶ Orders the factory to run the given process at the given line at the given step
- Parameters
process (
int
) – The process to runrepeats (
int
) – How many times to repeat the processstep (
Union
[int
,Tuple
[int
,int
]]) – 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 (
int
) – The production line. The special value ANY_LINE gives the factory the freedom to use any lineoverride (
bool
) – Whether to override existing production commands or notmethod (
str
) – When to schedule the command if step was set to a range. Options are latest, earliestpartial_ok (
bool
) – If true, allows partial scheduling
- Return type
- 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
-
set_commands
(commands, step=-1)[source]¶ Sets the production commands for all lines in the given step
-
property
state
¶ Receives the factory state
- Return type
-
property
-
class
scml.
SCML2020World
(process_inputs, process_outputs, catalog_prices, profiles, agent_types, agent_params=None, exogenous_contracts=(), initial_balance=1000, allow_buying_output=False, allow_selling_input=False, catalog_quantities=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=5, compensation_fraction=1.0, compensate_immediately=False, compensate_before_past_debt=True, exogenous_horizon=None, exogenous_force_max=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=5400, neg_n_steps=20, neg_time_limit=120, neg_step_time_limit=60, negotiation_speed=21, negotiation_quota_per_step=inf, negotiation_quota_per_simulation=inf, trading_price_discount=0.9, spot_discount=0.9, spot_multiplier=0.05, signing_delay=0, force_signing=False, batch_signing=True, name=None, agent_name_reveals_position=True, agent_name_reveals_type=True, **kwargs)[source]¶ A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020.
- Parameters
process_inputs (
ndarray
) – An n_processes vector specifying the number of inputs from each product needed to execute each process.process_outputs (
ndarray
) – An n_processes vector specifying the number of inputs from each product generated by executing each process.catalog_prices (
ndarray
) – An n_products vector (i.e. n_processes+1 vector) giving the catalog price of all productsprofiles (
List
[FactoryProfile
]) – An n_agents list ofFactoryProfile
objects specifying the private profile of the factory associated with each agent.agent_types (
List
[Type
[SCML2020Agent
]]) – An n_agents list of strings/SCML2020Agent
classes specifying the type of each agentagent_params (
Optional
[List
[Dict
[str
,Any
]]]) – An n_agents dictionaries giving the parameters of each agentinitial_balance (
Union
[ndarray
,Tuple
[int
,int
],int
]) – 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 (
Union
[int
,ndarray
]) – 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 pricespot_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 (
Optional
[int
]) – The horizon for revealing external contractsexogenous_force_max (
bool
) – If true, exogenous contracts are forced to be signed independent of the setting offorce_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
**kwargs – Other parameters that are passed directly to
SCML2020World
constructor.
-
add_financial_report
(agent, factory, reports_agent, reports_time)[source]¶ Records a financial report for the given agent in the agent indexed reports and time indexed reports
- Parameters
agent (
SCML2020Agent
) – The agentfactory (
Factory
) – Its factoryreports_agent – A dictionary of financial reports indexed by agent id
reports_time – A dictionary of financial reports indexed by time
Returns:
- Return type
None
-
breach_record
(breach)[source]¶ Converts a breach to a record suitable for storage during the simulation
-
compensate
(available, factory)[source]¶ Called by a factory when it is going bankrupt after liquidation
-
complete_contract_execution
(contract, breaches, resolution)[source]¶ Called after breach resolution is completed for contracts for which some potential breaches occurred.
- Parameters
contract (
Contract
) – The contract considered.breaches (
List
[Breach
]) – The list of potential breaches that was generated by_execute_contract
.resolution (
Contract
) – The agreed upon resolution
Returns:
- Return type
None
-
contract_size
(contract)[source]¶ Returns an estimation of the activity level associated with this contract. Higher is better :type contract:
Contract
:param contract:Returns:
- Return type
-
property
contracts_df
¶ Returns a pandas data frame with the contracts
- Return type
DataFrame
-
draw
(steps=None, what=['negotiation-requests-rejected', 'negotiation-requests-accepted', 'negotiations-rejected', 'negotiations-started', 'negotiations-failed', 'contracts-concluded', 'contracts-cancelled', 'contracts-signed', 'contracts-breached', 'contracts-executed'], who=None, where=None, together=True, axs=None, ncols=4, figsize=(15, 15), **kwargs)[source]¶ Generates a graph showing some aspect of the simulation
- Parameters
steps (
Union
[Tuple
[int
,int
],int
,None
]) – The step/steps to generate the graphs for. If a tuple is given all edges within the given range (inclusive beginning, exclusive end) will be accomulatedwhat (
Collection
[str
]) – The edges to have on the graph. Options are: negotiations, concluded, signed, executedwho (
Optional
[Callable
[[Agent
],bool
]]) – Either a callable that receives an agent and returns True if it is to be shown or None for allwhere (
Optional
[Callable
[[Agent
],Union
[int
,Tuple
[float
,float
]]]]) – A callable that returns for each agent the position it showed by drawn at either as an integer specifying the column in which to draw the column or a tuple of two floats specifying the position within the drawing area of the agent. If None, the default Networkx layout will be used.together (
bool
) – IF specified all edge types are put in the same graph.axs (
Optional
[Collection
[Axis
]]) – The axes used for drawing. If together is true, it should be a singleAxis
object otherwise it should be a list ofAxis
objects with the same length as what.show_node_labels – show node labels!
show_edge_labels – show edge labels!
kwargs – passed to networx.draw_networkx
- Return type
- Returns
A networkx graph representing the world if together==True else a list of graphs one for each item in what
-
execute_action
(action, agent, callback=None)[source]¶ Executes the given action by the given agent
- Return type
-
classmethod
generate
(agent_types, agent_params=None, n_steps=(50, 200), n_processes=4, n_lines=10, n_agents_per_process=3, process_inputs=1, process_outputs=1, production_costs=(1, 10), profit_means=(0.1, 0.2), profit_stddevs=0.05, max_productivity=1.0, initial_balance=None, cost_increases_with_level=True, horizon=(0.2, 0.5), equal_exogenous_supply=False, equal_exogenous_sales=False, exogenous_control=(0.2, 0.8), cash_availability=(1.5, 2.5), force_signing=False, profit_basis=<function mean>, **kwargs)[source]¶ Generates the configuration for a world
- Parameters
agent_types (
List
[Type
[SCML2020Agent
]]) – All agent typesagent_params (
Optional
[List
[Dict
[str
,Any
]]]) – Agent parameters used to initialize themn_steps (
Union
[Tuple
[int
,int
],int
]) – Number of simulation stepsn_processes (
Union
[Tuple
[int
,int
],int
]) – Number of processes in the production chainn_lines (
Union
[ndarray
,Tuple
[int
,int
],int
]) – Number of lines per factoryprocess_inputs (
Union
[ndarray
,Tuple
[int
,int
],int
]) – Number of input units per processprocess_outputs (
Union
[ndarray
,Tuple
[int
,int
],int
]) – Number of output units per processproduction_costs (
Union
[ndarray
,Tuple
[int
,int
],int
]) – Production cost per factoryprofit_means (
Union
[ndarray
,Tuple
[float
,float
],float
]) – Mean profitability per production level (i.e. process).profit_stddevs (
Union
[ndarray
,Tuple
[float
,float
],float
]) – Std. Dev. of the profitability of every level (i.e. process).max_productivity (
Union
[ndarray
,Tuple
[float
,float
],float
]) – Maximum possible productivity per level (i.e. process).initial_balance (
Union
[ndarray
,Tuple
[int
,int
],int
,None
]) – The initial balance of all agentsn_agents_per_process (
Union
[ndarray
,Tuple
[int
,int
],int
]) – Number of agents per processcost_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 (
Union
[Tuple
[float
,float
],float
]) – The horizon used for revealing external supply/sales as a fraction of n_stepsequal_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
cash_availability (
Union
[Tuple
[float
,float
],float
]) – The fraction of the total money needs of the agent to work at maximum capacity that is available asinitial_balance
. This is only effective ifinitial_balance
is set toNone
.force_signing – Whether to force contract signatures (exogenous contracts are treated in the same way).
exogenous_control (
Union
[Tuple
[float
,float
],float
]) – How much control does the agent have over exogenous contract signing. Only effective if force_signing is False and use_exogenous_contracts is True**kwargs –
- Return type
- Returns
world configuration as a Dict[str, Any]. A world can be generated from this dict by calling SCML2020World(**d)
Remarks:
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 lengthn_processes
, it is used as it is otherwise, it is used to sample values for each process.
-
property
non_system_agent_ids
¶ Returns names of all agents except system agents
-
property
non_system_agent_names
¶ Returns names of all agents except system agents
-
property
non_system_agents
¶ Returns all agents except system agents
- Return type
-
on_contract_concluded
(contract, to_be_signed_at)[source]¶ Called to add a contract to the existing set of unsigned contract after it is concluded
- Parameters
contract (
Contract
) – The contract to addto_be_signed_at (
int
) – The timestep at which the contract is to be signed
Remarks:
By default this function just adds the contract to the set of contracts maintaned by the world.
You should ALWAYS call this function when overriding it.
- Return type
None
-
on_contract_signed
(contract)[source]¶ Called to add a contract to the existing set of contract after it is signed
- Parameters
contract (
Contract
) – The contract to add
Remarks:
By default this function just adds the contract to the set of contracts maintaned by the world.
You should ALWAYS call this function when overriding it.
-
order_contracts_for_execution
(contracts)[source]¶ Orders the contracts in a specific time-step that are about to be executed
- Return type
Collection
[Contract
]
-
post_step_stats
()[source]¶ Called at the end of the simulation step to update all stats
Kept for backward compatibility and will be dropped. Override
update_stats
ins
-
pre_step_stats
()[source]¶ 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
-
property
productivity
¶ Fraction of production lines occupied during the simulation
- Return type
-
property
relative_productivity
¶ Productivity relative to the expected value. Will return None if self.info does not have the expected productivity
-
relative_welfare
(include_bankrupt=False)[source]¶ Total welfare relative to expected value. Returns None if no expectation is found in self.info
-
simulation_step
(stage)[source]¶ 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.
-
start_contract_execution
(contract)[source]¶ Tries to execute the contract
- Parameters
contract (
Contract
) –- Returns
The set of breaches committed if any. If there are no breaches return an empty set
- Return type
Set[Breach]
Remarks:
You must call super() implementation of this method before doing anything
It is possible to return None which indicates that the contract was nullified (i.e. not executed due to a reason other than an execution exeception).
-
property
stats_df
¶ Returns a pandas data frame with the stats
- Return type
DataFrame
-
property
system_agents
¶ Returns the two system agents
- Return type
-
trading_prices_for
(discount=1.0, condition='executed')[source]¶ Calculates the prices at which all products traded using an optional discount factor
-
property
winners
¶ The winners of this world (factory managers with maximum wallet balance
-
class
scml.
FinancialReport
(agent_id, step, cash, assets, breach_prob, breach_level, is_bankrupt, agent_name)[source]¶ A report published periodically by the system showing the financial standing of an agent
-
agent_id
¶ Agent ID
-
agent_name
¶ Agent name for printing purposes
-
assets
¶ Value of the products in the agent’s inventory @ catalog prices.
-
breach_level
¶ Sum of the agent’s breach levels so far divided by the number of contracts it signed.
-
breach_prob
¶ Number of times the agent breached a contract over the total number of contracts it signed.
-
cash
¶ Cash in the agent’s wallet. Negative numbers indicate liabilities.
-
is_bankrupt
¶ Whether the agent is already bankrupt (i.e. incapable of doing any more transactions).
-
step
¶ Simulation step at the beginning of which the report was published.
-
-
class
scml.
FactoryProfile
(costs)[source]¶ Defines all private information of a factory
-
costs
¶ An n_lines * n_processes array giving the cost of executing any process (INVALID_COST indicates infinity)
-
-
class
scml.
Factory
(profile, initial_balance, inputs, outputs, catalog_prices, world, compensate_before_past_debt, buy_missing_products, production_buy_missing, production_penalty, production_no_bankruptcy, production_no_borrow, agent_id, agent_name=None, confirm_production=True, initial_inventory=None)[source]¶ A simulated factory
-
agent_id
= None¶ A unique ID for the agent owning the factory
-
agent_name
= None¶ SCML2020Agent names used for logging purposes
-
available_for_production
(repeats, step=-1, line=-1, override=True, method='latest')[source]¶ Finds available times and lines for scheduling production.
- Parameters
repeats (
int
) – How many times to repeat the processstep (
Union
[int
,Tuple
[int
,int
]]) – 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 (
int
) – The production line. The special value ANY_LINE gives the factory the freedom to use any lineoverride (
bool
) – Whether to override any existing commands at that line at that time.method (
str
) – When to schedule the command if step was set to a range. Options are latest, earliest, all
- Return type
- 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.
-
balance_change
= None¶ Change in the balance in the last step
-
buy
(product, quantity, unit_price, buy_missing, penalty, no_bankruptcy=False, no_borrowing=False)[source]¶ Executes a transaction to buy/sell involving adding quantity and paying price (both are signed)
- Parameters
product (
int
) – The product transacted onquantity (
int
) – The quantity (added)unit_price (
int
) – The unit price (paid)buy_missing (
bool
) – If true, attempt buying missing products from the spot marketpenalty (
float
) – The penalty as a fraction to be paid for breachesno_bankruptcy (
bool
) – If true, this transaction can never lead to bankruptcyno_borrowing (
bool
) – If true, this transaction can never lead to borrowing
- Return type
- Returns
Tuple[int, int] The actual quantities bought and the total cost
-
cancel_production
(step, line)[source]¶ Cancels pre-ordered production given that it did not start yet.
- Parameters
- Return type
- Returns
True if step >= self.current_step
Remarks:
Cannot cancel a process in the past or present.
-
commands
= None¶ An n_steps * n_lines array giving the process scheduled for each line at every step. -1 indicates an empty line.
-
contracts
= None¶ A list of lists of contracts per time-step (len == n_steps)
-
inputs
= None¶ An n_process array giving the number of inputs needed for each process (of the product with the same index)
-
inventory_changes
= None¶ Changes in the inventory in the last step
-
is_bankrupt
= None¶ Will be true when the factory is bankrupt
-
min_balance
= None¶ The minimum balance possible
-
order_production
(process, steps, lines)[source]¶ Orders production of the given process
- Parameters
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
- Return type
None
-
outputs
= None¶ An n_process array giving the number of outputs produced by each process (of the product with the next index)
-
pay
(money, no_bankruptcy=False, no_borrowing=False, unit=0)[source]¶ Pays money
- Parameters
- Return type
- Returns
The amount actually paid
-
profile
= None¶ The readonly factory profile (See
FactoryProfile
)
-
schedule_production
(process, repeats, step=-1, line=-1, override=True, method='latest', partial_ok=False)[source]¶ Orders production of the given process on the given step and line.
- Parameters
process (
int
) – The process indexrepeats (
int
) – How many times to repeat the processstep (
Union
[int
,Tuple
[int
,int
]]) – 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 (
int
) – The production line. The special value ANY_LINE gives the factory the freedom to use any lineoverride (
bool
) – Whether to override any existing commands at that line at that time.method (
str
) – When to schedule the command if step was set to a range. Options are latest, earliest, allpartial_ok (
bool
) – If true, it is OK to produce only a subset of repeats
- Return type
- 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.
-
spot_price
(product, spot_loss)[source]¶ Get the current spot price for buying the given product on the spot market
-
store
(product, quantity, buy_missing, spot_price, no_bankruptcy=False, no_borrowing=False)[source]¶ Stores the given amount of product (signed) to the factory.
- Parameters
product (
int
) – Productquantity (
int
) – quantity to store/take out (-ve means take out)buy_missing (
bool
) – 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 penaltyspot_price (
float
) – 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 inventoryno_bankruptcy (
bool
) – Never bankrupt the agent on this transactionno_borrowing (
bool
) – Never borrow for this transaction
- Return type
- Returns
The quantity actually stored or taken out (always positive)
-
-
class
scml.
Failure
(is_inventory, line, step, process)[source]¶ A production failure
-
is_inventory
¶ 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
¶ The line at which the failure happened
-
process
¶ The process that failed to execute
-
step
¶ The step at which the failure happened
-
-
class
scml.
Simulation
(*args, **kwargs)[source]¶ 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:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
ProductionStrategy
(*args, **kwargs)[source]¶ 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 contractcan_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:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
can_be_produced
(contract_id)[source]¶ 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
-
schedule_range
= None¶ Gives the range of steps at which the production needed for a given contract are scheduled
-
class
scml.
SupplyDrivenProductionStrategy
(*args, **kwargs)[source]¶ A production strategy that converts all inputs to outputs
- Hooks Into:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
DemandDrivenProductionStrategy
(*args, **kwargs)[source]¶ 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
TradeDrivenProductionStrategy
(*args, **kwargs)[source]¶ 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
TradePredictionStrategy
(*args, predicted_outputs=None, predicted_inputs=None, add_trade=True, **kwargs)[source]¶ A prediction strategy for expected inputs and outputs at every step
- Parameters
predicted_inputs (
Union
[int
,ndarray
,None
]) – None for default, a number of an n_steps numbers giving predicted inputspredicted_outputs (
Union
[int
,ndarray
,None
]) – None for default, a number of an n_steps numbers giving predicted outputsadd_trade – If true, actual contracts will be just added to the expectations
- Provides:
expected_inputs
: n_steps vector giving the predicted inputs at every time-stepexpected_outputs
: n_steps vector giving the predicted outputs at every time-stepinput_cost
: n_steps vector giving the predicted input cost at every time-stepoutput_price
: n_steps vector giving the predicted output price at every time-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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
expected_inputs
= None¶ Expected input quantity every step
-
expected_outputs
= None¶ Expected output quantity every step
-
input_cost
= None¶ Expected unit price of the input
-
output_price
= None¶ Expected unit price of the output
-
class
scml.
FixedTradePredictionStrategy
(*args, predicted_outputs=None, predicted_inputs=None, add_trade=True, **kwargs)[source]¶ Predicts a fixed amount of trade both for the input and output products.
- Hooks Into:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
ExecutionRatePredictionStrategy
[source]¶ 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:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
FixedERPStrategy
(*args, execution_fraction=0.5, **kwargs)[source]¶ 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:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
MeanERPStrategy
(*args, execution_fraction=0.5, **kwargs)[source]¶ 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:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
SignAll
[source]¶ Signs all contracts no matter what.
- Overrides:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
SignAllPossible
[source]¶ 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:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
TradingStrategy
(*args, **kwargs)[source]¶ Base class for all trading strategies.
- Provides:
inputs_needed
(np.ndarray): How many items of the input product do I need at every time step (n_steps vector)outputs_needed
(np.ndarray): How many items of the output product do I need at every time step (n_steps vector)inputs_secured
(np.ndarray): How many items of the output product do I need at every time step (n_steps vector)outputs_secured
(np.ndarray): How many units of the output product I have already secured per step(n_steps vector)
- Hooks Into:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
inputs_needed
= None¶ How many items of the input product do I need at every time step
-
inputs_secured
= None¶ How many units of the input product I have already secured per step
-
outputs_needed
= None¶ How many items of the output product do I need at every time step
-
outputs_secured
= None¶ How many units of the output product I have already secured per step
-
class
scml.
ReactiveTradingStrategy
(*args, **kwargs)[source]¶ The agent reactively responds to contracts for selling by buying and vice versa.
- Hooks Into:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
PredictionBasedTradingStrategy
(*args, predicted_outputs=None, predicted_inputs=None, add_trade=True, **kwargs)[source]¶ A trading strategy that uses prediction strategies to manage inputs/outputs needed
- Hooks Into:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
NegotiationManager
(*args, horizon=5, negotiate_on_signing=True, **kwargs)[source]¶ 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:
- Abstract:
- Hooks Into:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
abstract
acceptable_unit_price
(step, sell)[source]¶ Returns the maximum/minimum acceptable unit price for buying/selling at the given time-step
-
start_negotiations
(product, quantity, unit_price, step, partners=None)[source]¶ Starts a set of negotiations to by/sell the product with the given limits
- Parameters
product (
int
) – product type. If it is an input product, negotiations to buy it will be started otherweise to sell.quantity (
int
) – The maximum quantity to negotiate aboutunit_price (
int
) – The maximum/minimum unit price for buy/sellstep (
int
) – The maximum/minimum time for buy/sellpartners (
Optional
[List
[str
]]) – A list of partners to negotiate with
Remarks:
This method assumes that product is either my_input_product or my_output_product
- Return type
None
-
class
scml.
StepNegotiationManager
(*args, negotiator_type=<class 'negmas.sao.AspirationNegotiator'>, negotiator_params=None, **kwargs)[source]¶ A negotiation manager that controls a controller and another for selling for every timestep
- Parameters
- Provides:
- Requires:
- Hooks Into:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
all_negotiations_concluded
(controller_index, is_seller)[source]¶ Called by the
StepController
to affirm that it is done negotiating for some time-step- Return type
None
-
buyers
= None¶ Buyer controllers and seller controllers. Each of them is responsible of covering the needs for one step (either buying or selling).
-
class
scml.
IndependentNegotiationsManager
(*args, negotiator_type=<class 'negmas.sao.AspirationNegotiator'>, negotiator_params=None, **kwargs)[source]¶ A negotiation manager that manages independent negotiators that do not share any information once created
- Parameters
- Requires:
- Hooks Into:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.
-
class
scml.
MovingRangeNegotiationManager
(*args, price_weight=0.7, utility_threshold=0.9, time_threshold=0.9, time_horizon=0.1, **kwargs)[source]¶ 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:
- 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 theBases
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 componentAbstract
section describes abstract methods that MUST be implemented by any descendant of this component.Hooks Into
section describes the methods this component overrides callingsuper
() which allows other components to hook into the same method (by overriding it). Usually callbacks starting withon_
are hooked into this way.Overrides
section describes the methods this component overrides without callingsuper
effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting withon_
) are overridden this way.