scml.scml2020.services
Services are classes that provide functionality that can be used by agents or components. The do not hook into or override any methods of the SCML2020Agent class.
Submodules
Package Contents
Classes
A simulator that can be used to predict future state of a factory given some combination of operations (sell, buy, 

A controller for managing a set of negotiations about selling or buying (but not both) starting/ending at some 

Will try to get the best deal which is defined as being nearest to the agent needs and with lowest price 
Functions

Runs the simulated actions then confirms them if they are not rolled back 

Runs the simulated actions then rolls them back 
Attributes
 class scml.scml2020.services.FactorySimulator(profile: scml.scml2020.common.FactoryProfile, initial_balance: int, bankruptcy_limit: int, spot_market_global_loss: float, catalog_prices: numpy.ndarray, n_steps: int, initial_inventory: numpy.ndarray = None)[source]
A simulator that can be used to predict future state of a factory given some combination of operations (sell, buy, schedule).
 property initial_inventory: numpy.array
Initial inventory
 property n_lines
Number of lines
 property fixed_before
Gives the time before which the schedule is fixed.
See also
 final_score(prices: numpy.ndarray  None) int [source]
Returns the final balance of the agent at the end of the simulation
 inventory_at(t: int) numpy.array [source]
Returns the inventory of all products at time t
 Parameters:
t – Time
 Returns:
An array of size
n_products
giving the quantity of each product in inventory at timestept
.
See also
 line_schedules_at(t: int) numpy.array [source]
Returns the schedule of each line at a given timestep
 Parameters:
t – time
 Returns:
An array of
n_lines
values giving the schedule up att
.
Remarks:
A
NO_COMMAND
value means no production, otherwise the index of the process being run
 reserved_inventory_to(t: int) numpy.array [source]
Returns the reserved inventory of all products up to time t
 Parameters:
t – Time
 Returns:
An array of size
n_products
*t
giving the quantity of each product reserved at every step up tot
.
Remarks:
Reserved inventory is counted in calls to
inventory_at
,total_inventory_at
,inventory_to
,total_inventory_to
Reserving quantities of products is a tool that can be used to avoid double counting availability of given products in the inventory for multiple contracts.
See also
total_inventory_at
inventory_at
reserved_inventory_at
 reserved_inventory_at(t: int) numpy.array [source]
Returns the reserved inventory of all products at time t
 Parameters:
t – Time
 Returns:
An array of size
n_products
giving the quantity of each product reserved at timestept
.
Remarks:
Reserved inventory is counted in calls to
inventory_at
,total_inventory_at
,inventory_to
,total_inventory_to
Reserving quantities of products is a tool that can be used to avoid double counting availability of given products in the inventory for multiple contracts.
See also
total_inventory_to
inventory_to
reserved_inventory_at
 available_inventory_to(t: int) numpy.array [source]
Returns the available inventory of all products up to time t.
 Parameters:
t – Time
 Returns:
An array of size
n_products
*t
giving the quantity of each product available at every step up tot
.
Remarks:
Available inventory is defined as the difference between inventory and reserved inventory.
Reserved inventory is counted in calls to
inventory_at
,total_inventory_at
,inventory_to
,total_inventory_to
Reserving quantities of products is a tool that can be used to avoid double counting availability of given products in the inventory for multiple contracts.
See also
total_inventory_to
inventory_to
reserved_inventory_to
 available_inventory_at(t: int) numpy.array [source]
Returns the available inventory of all products at time t
 Parameters:
t – Time
 Returns:
An array of size
n_products
giving the quantity of each product available at timestept
.
Remarks:
Available inventory is defined as the difference between inventory and reserved inventory.
Reserved inventory is counted in calls to
inventory_at
,total_inventory_at
,inventory_to
,total_inventory_to
Reserving quantities of products is a tool that can be used to avoid double counting availability of given products in the inventory for multiple contracts.
See also
total_inventory_to
inventory_to
reserved_inventory_at
 balance_to(t: int) numpy.array [source]
Returns the balance fo the factory until and including time t.
 Parameters:
t – time
Remarks:
The balance is defined as the cash in balance
 score(inventory_weight=0.5) float [source]
Estimates the final score of the agent
 Parameters:
inventory_weight – The weight of the inventory that remains at the end of the simulation
 Remarks:
It uses the catalog prices for price estimation. This may be inaccurate. There is no way to know the actual trading prices of the market that are used to calculate the real score
 balance_at(t: int) numpy.array [source]
Returns the balance of the factory at time t.
 Parameters:
t – time
Remarks:
The balance is defined as the cash in balance
 inventory_to(t: int) numpy.array [source]
Returns the balance fo the factory up to time t.
 Parameters:
t – time
Remarks:
The balance is defined as the cash in balance
 receive(payment: int, t: int) bool [source]
Simulates receiving payment at time t
 Parameters:
payment – Amount received
t – time
 Returns:
Success or failure
 reserve(product: int, quantity: int, t: int) bool [source]
Simulates reserving the given quantity of the given product at times >= t.
 Parameters:
product – Index/ID of the product being reserved
quantity – quantity being reserved
t – time
 Returns:
Success/failure
Remarks:
Reserved products do not show in calls to
inventory_at
,inventory_to
etc.Reserving a product does nothing more than mark some quantity as reserved for calls to
reserved_inventory_at
andavailable_inventory_at
.This feature can be used to simulate inventory hiding commands in the real factory and to avoid double counting of inventory when calculating needs for future contracts.
 pay(payment: int, t: int, ignore_money_shortage: bool = True) bool [source]
Simulate payment at time t
 Parameters:
payment – Amount payed
t – time
ignore_money_shortage – If True, shortage in money will be ignored and the balance can go negative
 Returns:
Success or failure
 transport_to(product: int, quantity: int, t: int, ignore_inventory_shortage: bool = True) bool [source]
Simulates transporting products to/from inventory at time t
 Parameters:
product – product ID (index)
quantity – quantity to transport
t – time
ignore_inventory_shortage – Ignore shortage in the
product
which may lead to negative inventory[product]
 Returns:
Success or failure
 buy(product: int, quantity: int, price: int, t: int, ignore_money_shortage: bool = True) bool [source]
Buy a given quantity of a product for a given price at some time t
 Parameters:
product – Product to buy (ID/index)
quantity – quantity to buy
price – unit price
t – time
ignore_money_shortage – If True, shortage in money will be ignored and the balance can go negative
 Returns:
Success or failure
Remarks:
buy cannot ever have inventory shortage
See also
 sell(product: int, quantity: int, price: int, t: int, ignore_inventory_shortage: bool = True) bool [source]
sell a given quantity of a product for a given price at some time t
 Parameters:
product – Index/ID of the product to be sold
quantity – quantity to be sold
price – unit price
t – time
ignore_inventory_shortage – If True, shortage in inventory will be ignored and the inventory can go negative
 Returns:
Success or failure
Remarks:
sell cannot ever have space shortage
See also
 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] [source]
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.
 order_production(process: int, steps: numpy.ndarray, lines: numpy.ndarray) None [source]
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
 schedule(process: int, quantity: int, t: int  Tuple[int, int] = ANY_STEP, line: int = ANY_LINE, override=True, method: str = 'latest', ignore_inventory_shortage=True, ignore_money_shortage=True) bool [source]
Simulates scheduling the given job at its
time
andline
optionally overriding whatever was already scheduled Parameters:
process – The process to run
quantity – The quantity to be produced
t – The timestep step
line – The line
ignore_inventory_shortage – If true shortages in inputs will be ignored
ignore_money_shortage – If true, shortage in money will be ignored
override – Whether the job should override any already registered job at its timestep
method – The method employed for scheduling. Supported methods are latest, earliest
 Returns:
Success/failure
 fix_before(t: int) bool [source]
Fix the history before this point
 Parameters:
t – time
 Returns:
Success/failure
Remarks:
After this function is called at any timestep
t
, there is no way to change any component of the factory state at any timestep beforet
.This function is useful for fixing any difference between the simulator and the real state (in conjunction with
set_state
).
See also
 delete_bookmark(bookmark_id: int) bool [source]
Commits everything since the bookmark so it cannot be rolled back
 Parameters:
bookmark (bookmark_id The bookmark ID returned from) –
 Returns:
Success/failure
Remarks:
You can delete bookmarks in the reverse order of their creation only. If the bookmark ID given here is not the one at the top of the bookmarks stack, the deletion will fail (return False).
 bookmark() int [source]
Sets a bookmark to the current location
 Returns:
bookmark ID
Remarks:
Bookmarks can be used to implement transactions.
 rollback(bookmark_id: int) bool [source]
Rolls back to the given bookmark ID
 Parameters:
bookmark (bookmark_id The bookmark ID returned from) –
Remarks:
You can only rollback in the reverse order of bookmarks. If the bookmark ID given here is not the one at the top of the bookmarks stack, the rollback will fail (return False)
 set_state(t: int, inventory: numpy.array, balance: int, commands: numpy.array) None [source]
Sets the current state at the given timestep. It implicitly causes a fix_before(t + 1)
 Parameters:
t – Time step to set the state at
inventory – quantity of every product (array of integers of size
n_products
)balance – Cash in balance
commands – Line schedules (array of process numbers/NO_PRODUCTION of size
n_lines
)
 scml.scml2020.services.transaction(simulator)[source]
Runs the simulated actions then confirms them if they are not rolled back
 scml.scml2020.services.temporary_transaction(simulator)[source]
Runs the simulated actions then rolls them back
 class scml.scml2020.services.StepController(*args, target_quantity: int, is_seller: bool, step: int, urange: Tuple[int, int], product: int, partners: List[str], negotiator_type: negmas.sao.SAONegotiator, horizon: int, awi: negmas.AgentWorldInterface, parent_name: str, negotiations_concluded_callback: Callable[[int, bool], None], negotiator_params: Dict[str, Any] = None, max_retries: int = 2, **kwargs)[source]
Bases:
negmas.sao.SAOController
,negmas.events.Notifier
A controller for managing a set of negotiations about selling or buying (but not both) starting/ending at some specific timestep.
 Parameters:
target_quantity – The quantity to be secured
is_seller – Is this a seller or a buyer
parent_name – Name of the parent
horizon – How many steps in the future to allow negotiations for selling to go for.
step – The simulation step that this controller is responsible about
urange – The range of unit prices used for negotiation
product – The product that this controller negotiates about
partners – A list of partners to negotiate with
negotiator_type – The type of the single negotiator used for all negotiations.
negotiator_params – The parameters of the negotiator used for all negotiations
max_retries – How many times can the controller try negotiating with each partner.
negotiations_concluded_callback – A method to be called with the step of this controller and whether is it a seller when all negotiations are concluded
*args – Position arguments passed to the base Controller constructor
**kwargs – Keyword arguments passed to the base Controller constructor
Remarks:
It uses whatever negotiator type on all of its negotiations and it assumes that the ufun will never change
Once it accumulates the required quantity, it ends all remaining negotiations
It assumes that all ufuns are identical so there is no need to keep a separate negotiator for each one and it instantiates a single negotiator that dynamically changes the AMI but always uses the same ufun.
 join(negotiator_id: str, nmi: negmas.common.NegotiatorMechanismInterface, state: negmas.MechanismState, *, preferences: negmas.Preferences  None = None, ufun: negmas.UtilityFunction  None = None, role: str = 'agent') bool [source]
Called by the mechanism when the agent is about to enter a negotiation. It can prevent the agent from entering
 Parameters:
negotiator_id – The negotiator ID
nmi (AgentMechanismInterface) – The negotiation.
state (TState) – The current state of the negotiation
preferences (Preferences) – The preferences.
ufun (BaseUtilityFunction) – The ufun function to use before any discounting (overrides preferences)
role (str) – role of the agent.
 Returns:
bool indicating whether or not the agent accepts to enter.If False is returned it will not enter the negotiation.
 respond(negotiator_id: str, state: negmas.MechanismState, source: str = '') negmas.ResponseType [source]
 create_negotiator(negotiator_type: str  Type[negmas.ControlledNegotiator] = None, name: str = None, cntxt: Any = None, **kwargs) negmas.ControlledNegotiator [source]
Creates a negotiator passing it the context
 Parameters:
negotiator_type – Type of the negotiator to be created
name – negotiator name
cntxt – The context to be associated with this negotiator.
**kwargs – any keyvalue pairs to be passed to the negotiator constructor
 Returns:
The negotiator to be controlled. None for failure
 class scml.scml2020.services.SyncController(*args, is_seller: bool, parent: scml.scml2020.components.trading.PredictionBasedTradingStrategy, price_weight=0.7, utility_threshold=0.9, time_threshold=0.9, **kwargs)[source]
Bases:
negmas.sao.SAOSyncController
Will try to get the best deal which is defined as being nearest to the agent needs and with lowest price
 utility(offer: Tuple[int, int, int], max_price: int) float [source]
A simple utility function
 Remarks:
If the time is invalid or there is no need to get any more agreements at the given time, return 1000
Otherwise use the priceweight to calculate a linear combination of the price and the how much of the needs is satisfied by this contract
 counter_all(offers: Dict[str, negmas.Outcome], states: Dict[str, negmas.sao.SAOState]) Dict[str, negmas.sao.SAOResponse] [source]
Calculate a response to all offers from all negotiators (negotiator ID is the key).
 Parameters:
offers – Maps negotiator IDs to offers
states – Maps negotiator IDs to offers AT the time the offers were made.
 Remarks:
The response type CANNOT be WAIT.