scml.scml2020.services.simulators ================================= .. py:module:: scml.scml2020.services.simulators .. autoapi-nested-parse:: Simulators module implementing factory simulation Classes ------- .. autoapisummary:: scml.scml2020.services.simulators.FactorySimulator Functions --------- .. autoapisummary:: scml.scml2020.services.simulators.transaction scml.scml2020.services.simulators.temporary_transaction Module Contents --------------- .. py:class:: 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). .. py:attribute:: _n_steps .. py:attribute:: _catalog_prices .. py:attribute:: _initial_balance .. py:attribute:: _initial_inventory .. py:attribute:: _profile .. py:attribute:: _n_products .. py:attribute:: _reserved_inventory .. py:attribute:: _bankrupt_at :value: 9223372036854775807 .. py:attribute:: bankruptcy_limit .. py:attribute:: spot_market_global_loss .. py:attribute:: _n_lines .. py:attribute:: _balance .. py:attribute:: _inventory :value: None .. py:attribute:: commands .. py:attribute:: _fixed_before :value: 0 .. py:attribute:: _bookmarks :type: List[_FullBookmark] :value: [] .. py:attribute:: _active_bookmark :type: Optional[_FullBookmark] :value: None .. py:property:: n_steps :type: int Number of steps to predict ahead. .. py:property:: initial_balance :type: int Initial cash in balance .. py:property:: initial_inventory :type: numpy.array Initial inventory .. py:property:: n_lines Number of lines .. py:property:: final_balance :type: int Returns the final balance of the agent at the end of the simulation .. py:method:: final_score(prices: Optional[numpy.ndarray]) -> int Returns the final balance of the agent at the end of the simulation .. py:method:: inventory_at(t: int) -> numpy.array Returns the inventory of all products *at* time t :param t: Time :returns: An array of size `n_products` giving the quantity of each product in inventory at time-step `t`. .. seealso:: `inventory_to` `balance_at` .. py:method:: line_schedules_at(t: int) -> numpy.array Returns the schedule of each line at a given timestep :param 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 .. py:method:: reserved_inventory_to(t: int) -> numpy.array Returns the *reserved* inventory of all products *up to* time t :param 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. .. seealso:: `total_inventory_at` `inventory_at` `reserved_inventory_at` .. py:method:: reserved_inventory_at(t: int) -> numpy.array Returns the *reserved* inventory of all products *at* time t :param 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. .. seealso:: `total_inventory_to` `inventory_to` `reserved_inventory_at` .. py:method:: available_inventory_to(t: int) -> numpy.array Returns the *available* inventory of all products *up to* time t. :param 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. .. seealso:: `total_inventory_to` `inventory_to` `reserved_inventory_to` .. py:method:: available_inventory_at(t: int) -> numpy.array Returns the *available* inventory of all products *at* time t :param 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. .. seealso:: `total_inventory_to` `inventory_to` `reserved_inventory_at` .. py:method:: is_bankrupt() -> bool Checks if the agent will go bankrupt given all the info so far .. py:method:: balance_to(t: int) -> numpy.array Returns the balance fo the factory until and including time t. :param t: time Remarks: - The balance is defined as the cash in balance .. py:method:: score(inventory_weight=0.5) -> float Estimates the final score of the agent :param 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 .. py:method:: balance_at(t: int) -> numpy.array Returns the balance of the factory at time t. :param t: time Remarks: - The balance is defined as the cash in balance .. py:method:: inventory_to(t: int) -> numpy.array Returns the balance fo the factory *up to* time t. :param t: time Remarks: - The balance is defined as the cash in balance .. py:method:: line_schedules_to(t: int) -> numpy.array .. py:method:: receive(payment: int, t: int) -> bool Simulates receiving payment at time t :param payment: Amount received :param t: time :returns: Success or failure .. py:method:: reserve(product: int, quantity: int, t: int) -> bool Simulates reserving the given quantity of the given product at times >= t. :param product: Index/ID of the product being reserved :param quantity: quantity being reserved :param 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. .. py:method:: pay(payment: int, t: int, ignore_money_shortage: bool = True) -> bool Simulate payment at time t :param payment: Amount payed :param t: time :param ignore_money_shortage: If True, shortage in money will be ignored and the balance can go negative :returns: Success or failure .. py:method:: transport_to(product: int, quantity: int, t: int, ignore_inventory_shortage: bool = True) -> bool Simulates transporting products to/from inventory at time t :param product: product ID (index) :param quantity: quantity to transport :param t: time :param ignore_inventory_shortage: Ignore shortage in the `product` which may lead to negative inventory[product] :returns: Success or failure .. py:method:: 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 :param product: Product to buy (ID/index) :param quantity: quantity to buy :param price: unit price :param t: time :param 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 .. seealso:: `sell` .. py:method:: 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 :param product: Index/ID of the product to be sold :param quantity: quantity to be sold :param price: unit price :param t: time :param 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 .. seealso:: `buy` .. py:method:: available_for_production(repeats: int, step: Union[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. :param repeats: How many times to repeat the process :param 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. :param line: The production line. The special value ANY_LINE gives the factory the freedom to use any line :param override: Whether to override any existing commands at that line at that time. :param 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. .. py:method:: order_production(process: int, steps: numpy.ndarray, lines: numpy.ndarray) -> None Orders production of the given process :param process: The process to run :param steps: The time steps to run the process at as an np.ndarray :param 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` .. py:method:: schedule(process: int, quantity: int, t: Union[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 :param process: The process to run :param quantity: The quantity to be produced :param t: The time-step step :param line: The line :param ignore_inventory_shortage: If true shortages in inputs will be ignored :param ignore_money_shortage: If true, shortage in money will be ignored :param override: Whether the job should override any already registered job at its time-step :param method: The method employed for scheduling. Supported methods are latest, earliest :returns: Success/failure .. py:method:: fix_before(t: int) -> bool Fix the history before this point :param 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`). .. seealso:: `set_state` `fixed_before` .. py:property:: fixed_before Gives the time before which the schedule is fixed. .. seealso:: `fix_before` .. py:method:: delete_bookmark(bookmark_id: int) -> bool Commits everything since the bookmark so it cannot be rolled back :param bookmark_id The bookmark ID returned from bookmark: :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). .. seealso:: `delete_bookmark` `rollback` `transaction` `temporary_transaction` .. py:method:: bookmark() -> int Sets a bookmark to the current location :returns: bookmark ID Remarks: - Bookmarks can be used to implement transactions. .. seealso:: `delete_bookmark` `rollback` `transaction` `temporary_transaction` .. py:method:: rollback(bookmark_id: int) -> bool Rolls back to the given bookmark ID :param bookmark_id The bookmark ID returned from bookmark: 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) .. seealso:: `delete_bookmark` `rollback` `transaction` `temporary_transaction` .. py:method:: 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) :param t: Time step to set the state at :param inventory: quantity of every product (array of integers of size `n_products`) :param balance: Cash in balance :param commands: Line schedules (array of process numbers/NO_PRODUCTION of size `n_lines`) .. py:function:: transaction(simulator) Runs the simulated actions then confirms them if they are not rolled back .. py:function:: temporary_transaction(simulator) Runs the simulated actions then rolls them back