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

• scml.scml2020.services.controllers
• scml.scml2020.services.simulators

Package Contents

Classes

FactorySimulator	A simulator that can be used to predict future state of a factory given some combination of operations (sell, buy,
StepController	A controller for managing a set of negotiations about selling or buying (but not both) starting/ending at some
SyncController	Will try to get the best deal which is defined as being nearest to the agent needs and with lowest price

Functions

transaction(simulator)	Runs the simulated actions then confirms them if they are not rolled back
temporary_transaction(simulator)	Runs the simulated actions then rolls them back

Attributes

__all__

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)

A simulator that can be used to predict future state of a factory given some combination of operations (sell, buy, schedule).

property n_steps: int

Number of steps to predict ahead.

property initial_balance: int

Initial cash in balance

property initial_inventory: numpy.array

Initial inventory

property n_lines

Number of lines

property final_balance: int

Returns the final balance of the agent at the end of the simulation

property fixed_before

Gives the time before which the schedule is fixed.

See also

fix_before

final_score(prices: numpy.ndarray | None) → int

Returns the final balance of the agent at the end of the simulation

inventory_at(t: int) → numpy.array

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 time-step t.

See also

inventory_to balance_at

line_schedules_at(t: int) → numpy.array

Returns the schedule of each line at a given timestep

Parameters:

t – time

Returns:

An array of n_lines values giving the schedule up at t.

Remarks:

• A NO_COMMAND value means no production, otherwise the index of the process being run

reserved_inventory_to(t: int) → numpy.array

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 to t.

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

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 time-step t.

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

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 to t.

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

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 time-step t.

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

is_bankrupt() → bool

Checks if the agent will go bankrupt given all the info so far

balance_to(t: int) → numpy.array

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

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

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

Returns the balance fo the factory up to time t.

Parameters:

t – time

Remarks:

• The balance is defined as the cash in balance

line_schedules_to(t: int) → numpy.array

receive(payment: int, t: int) → bool

Simulates receiving payment at time t

Parameters:

• payment – Amount received

• t – time

Returns:

Success or failure

reserve(product: int, quantity: int, t: int) → bool

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 and available_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

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

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

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

sell(product: int, quantity: int, price: int, t: int, ignore_inventory_shortage: bool = True) → bool

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

buy

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.

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

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

Simulates scheduling the given job at its time and line optionally overriding whatever was already scheduled

Parameters:

• process – The process to run

• quantity – The quantity to be produced

• t – The time-step 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 time-step

• method – The method employed for scheduling. Supported methods are latest, earliest

Returns:

Success/failure

fix_before(t: int) → bool

Fix the history before this point

Parameters:

t – time

Returns:

Success/failure

Remarks:

• After this function is called at any time-step t, there is no way to change any component of the factory state at any timestep before t.

• This function is useful for fixing any difference between the simulator and the real state (in conjunction with set_state).

See also

set_state fixed_before

delete_bookmark(bookmark_id: int) → bool

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

See also

delete_bookmark rollback transaction temporary_transaction

bookmark() → int

Sets a bookmark to the current location

Returns:

bookmark ID

Remarks:

• Bookmarks can be used to implement transactions.

See also

delete_bookmark rollback transaction temporary_transaction

rollback(bookmark_id: int) → bool

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)

See also

delete_bookmark rollback transaction temporary_transaction

set_state(t: int, inventory: numpy.array, balance: int, commands: numpy.array) → None

Sets the current state at the given time-step. 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)

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

scml.scml2020.services.temporary_transaction(simulator)

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)

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 time-step.

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

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.

propose(negotiator_id: str, state: negmas.MechanismState) → negmas.Outcome | None

respond(negotiator_id: str, state: negmas.MechanismState, source: str = '') → negmas.ResponseType

__str__()

Return str(self).

create_negotiator(negotiator_type: str | Type[negmas.ControlledNegotiator] = None, name: str = None, cntxt: Any = None, **kwargs) → negmas.ControlledNegotiator

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 key-value pairs to be passed to the negotiator constructor

Returns:

The negotiator to be controlled. None for failure

time_range(step, is_seller)

on_negotiation_end(negotiator_id: str, state: negmas.MechanismState) → None

A call back called at each negotiation end

Parameters:

• negotiator_id – The negotiator ID

• state – TState or one of its descendants giving the state at which the negotiation ended.

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)

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

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 price-weight to calculate a linear combination of the price and the how much of the needs is satisfied by this contract

is_valid(negotiator_id: str, offer: negmas.Outcome) → bool

counter_all(offers: Dict[str, negmas.Outcome], states: Dict[str, negmas.sao.SAOState]) → Dict[str, negmas.sao.SAOResponse]

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.

best_proposal(nid: str) → Tuple[negmas.Outcome | None, float]

Finds the best proposal for the given negotiation

Parameters:

nid – Negotiator ID

Returns:

The outcome with highest utility and the corresponding utility

first_proposals() → Dict[str, negmas.Outcome]

Gets a set of proposals to use for initializing the negotiation.

scml.scml2020.services.__all__