scml.scml2020.services.simulators

Simulators module implementing factory simulation

Module Contents

Classes

FactorySimulator

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

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
class scml.scml2020.services.simulators.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 n_steps: int[source]

Number of steps to predict ahead.

property initial_balance: int[source]

Initial cash in balance

property initial_inventory: numpy.array[source]

Initial inventory

property n_lines[source]

Number of lines

property final_balance: int[source]

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

property fixed_before[source]

Gives the time before which the schedule is fixed.

See also

fix_before

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

See also

inventory_to balance_at

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 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[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 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[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 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[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 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[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 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[source]

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

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

line_schedules_to(t: int) → numpy.array[source]
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 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[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

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

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][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 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[source]

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

See also

delete_bookmark rollback transaction temporary_transaction

bookmark() → int[source]

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

See also

delete_bookmark rollback transaction temporary_transaction

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

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.simulators.transaction(simulator)[source]

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

scml.scml2020.services.simulators.temporary_transaction(simulator)[source]

Runs the simulated actions then rolls them back