scml.scml2019.simulators

Simulators module implementing factory simulation

Module Contents

Classes

FactorySimulator

Simulates a factory allowing for prediction of storage/balance in the future.

SlowFactorySimulator

A slow factory simulator that runs an internal factory to find-out what will happen in the future

FastFactorySimulator

A faster implementation of the FactorySimulator interface (compared with SlowFactorySimulator.

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.scml2019.simulators.FactorySimulator(initial_wallet: float, initial_storage: Dict[int, int], n_steps: int, n_products: int, profiles: List[scml.scml2019.common.ManufacturingProfile], max_storage: int | None = None)[source]

Bases: abc.ABC

Simulates a factory allowing for prediction of storage/balance in the future.

Parameters:

  • initial_wallet – The initial amount of cash in the wallet

  • initial_storage – initial inventory

  • n_steps – number of simulation steps

  • n_products – number of products in the world

  • profiles – all profiles that the factory being simulated can run

  • max_storage – maximum available storage space.

property max_storage: int | None[source]

Maximum storage available

property n_steps: int[source]

Number of steps to predict ahead.

property initial_wallet: float[source]

Initial cash in wallet

property initial_storage: numpy.array[source]

Initial inventory

abstract property n_lines[source]

Number of lines

abstract property final_balance: float[source]

Final balance given everything scheduled so-far

abstract property fixed_before[source]

Gives the time before which the schedule is fixed.

See also

fix_before

_as_array(storage: Dict[int, int])[source]
abstract wallet_to(t: int) → numpy.array[source]

Returns the cash in wallet up to and including time t.

Parameters:

t – Time

Returns:

wallet_at(t: int) → float[source]

Returns the cash in wallet at a given timestep (given all simulated actions)

Parameters:

t –

Returns:

abstract storage_to(t: int) → numpy.array[source]

Returns the storage of all products up to time t

Parameters:

t – Time

Returns:

An array of size n_products * t giving the quantity of each product in storage at every step up to t.

storage_at(t: int) → numpy.array[source]

Returns the storage of all products at time t

Parameters:

t – Time

Returns:

An array of size n_products giving the quantity of each product in storage at time-step t.

See also

storage_to wallet_at

abstract line_schedules_to(t: int) → numpy.array[source]

Returns the schedule of each line up to a given timestep

Parameters:

t – time

Returns:

An array of n_lines * t values giving the schedule up to t.

Remarks:

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

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_PRODUCTION value means no production, otherwise the index of the process being run

total_storage_to(t: int) → numpy.array[source]

The total storage up to a given time

Parameters:

t – time

Returns:

an array of size t giving the total quantity of stored products in the inventory up to timestep t

See also

total_storage_at storage_to

total_storage_at(t: int) → int[source]

The total storage at a given time

Parameters:

t – time

Returns:

an integer giving the total quantity of stored products in the inventory at timestep t

See also

total_storage_to storage_at

reserved_storage_to(t: int) → numpy.array[source]

Returns the reserved storage 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 storage is counted in calls to storage_at , total_storage_at , storage_to , total_storage_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_storage_at storage_at reserved_storage_at

reserved_storage_at(t: int) → numpy.array[source]

Returns the reserved storage 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 storage is counted in calls to storage_at , total_storage_at , storage_to , total_storage_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_storage_to storage_to reserved_storage_at

available_storage_to(t: int) → numpy.array[source]

Returns the available storage 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 storage is defined as the difference between storage and reserved storage.

  • Reserved storage is counted in calls to storage_at , total_storage_at , storage_to , total_storage_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_storage_to storage_to reserved_storage_to

available_storage_at(t: int) → numpy.array[source]

Returns the available storage 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 storage is defined as the difference between storage and reserved storage.

  • Reserved storage is counted in calls to storage_at , total_storage_at , storage_to , total_storage_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_storage_to storage_to reserved_storage_at

abstract loans_to(t: int) → numpy.array[source]

Returns loans up to time t

Parameters:

t – time

Returns:

An array of t real numbers giving the loans registered at time-steps up to t

loans_at(t: int) → float[source]

Returns loans at time t

Parameters:

t – time

balance_at(t: int) → float[source]

Returns the balance fo the factory at time t.

Parameters:

t – time

Remarks:

  • The balance is defined as the cash in wallet minus loans

See also

loans_at wallet_at

balance_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 wallet minus loans

See also

loans_to wallet_to

abstract set_state(t: int, storage: numpy.array, wallet: float, loans: float, line_schedules: 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

  • storage – quantity of every product (array of integers of size n_products)

  • wallet – Cash in wallet

  • loans – Loans

  • line_schedules – Line schedules (array of process numbers/NO_PRODUCTION of size n_lines)

abstract add_loan(total: float, t: int) → bool[source]

Adds a loan at the given time

Parameters:

  • total – Total amount of the loan

  • t – time step to take the loan

Returns:

Success or failure

Remarks:

  • Taking a loan is simulated as reception of money. Payment back of the loan is not simulated in this call. To simulate paying back the loan, use pay at the times of installment payments.

receive(payment: float, t: int) → bool[source]

Simulates receiving payment at time t

Parameters:

  • payment – Amount received

  • t – time

Returns:

Success or failure

abstract pay(payment: float, 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 wallet can go negative

Returns:

Success or failure

abstract transport_to(product: int, quantity: int, t: int, ignore_inventory_shortage: bool = True, ignore_space_shortage: bool = True) → bool[source]

Simulates transporting products to/from storage 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 storage[product]

  • ignore_space_shortage – Ignore the limit on total storage which may lead to total_storage > max_storage

Returns:

Success or failure

abstract buy(product: int, quantity: int, price: int, t: int, ignore_money_shortage: bool = True, ignore_space_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 wallet can go negative

  • ignore_space_shortage – Ignore the limit on total storage which may lead to total_storage > max_storage

Returns:

Success or failure

Remarks:

  • buy cannot ever have inventory shortage

See also

sell

abstract sell(product: int, quantity: int, price: int, t: int, ignore_money_shortage: bool = True, 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_money_shortage – If True, shortage in money will be ignored and the wallet can go negative

  • ignore_inventory_shortage – Ignore shortage in the product which may lead to negative storage[product]

Returns:

Success or failure

Remarks:

  • sell cannot ever have space shortage

See also

buy

abstract schedule(job: scml.scml2019.common.Job, ignore_inventory_shortage=True, ignore_money_shortage=True, ignore_space_shortage=True, override=True) → bool[source]

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

Parameters:

  • job – Production job

  • ignore_inventory_shortage – If true shortages in inputs will be ignored

  • ignore_money_shortage – If true, shortage in money will be ignored

  • ignore_space_shortage – If true, shortage in space will be ignored

  • override – Whether the job should override any already registered job at its time-step

Returns:

Success/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 show in calls to storage_at , total_storage_at etc.

  • Reserving a product does nothing more than mark some quantity as reserved for calls to reserved_storage_at and available_storage_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.

abstract 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

abstract 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

abstract 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

abstract 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

class scml.scml2019.simulators.SlowFactorySimulator(initial_wallet: float, initial_storage: Dict[int, int], n_steps: int, n_products: int, profiles: List[scml.scml2019.common.ManufacturingProfile], max_storage: int | None)[source]

Bases: FactorySimulator

A slow factory simulator that runs an internal factory to find-out what will happen in the future

Remarks:

  • It is much faster to always access the properties/methods of this class in ascending time. If that is not the case, each time reversal will cause a complete reset.

  • It is recommended to call fix_before () to fix the past once a production step is completed. That will speed up operations

property final_balance: float[source]

Final balance given everything scheduled so-far

property n_lines[source]

Number of lines

property fixed_before[source]

Gives the time before which the schedule is fixed.

See also

fix_before

set_state(t: int, storage: numpy.array, wallet: float, loans: float, line_schedules: 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

  • storage – quantity of every product (array of integers of size n_products)

  • wallet – Cash in wallet

  • loans – Loans

  • line_schedules – Line schedules (array of process numbers/NO_PRODUCTION of size n_lines)

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

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

_update_state() → None[source]
reset_to(t: int) → None[source]
goto(t: int) → None[source]

Steps the factory to the end of step t :param t: time

Returns:

wallet_to(t: int) → numpy.array[source]

Returns the cash in wallet up to and including time t.

Parameters:

t – Time

Returns:

line_schedules_to(t: int) → numpy.array[source]

Returns the schedule of each line up to a given timestep

Parameters:

t – time

Returns:

An array of n_lines * t values giving the schedule up to t.

Remarks:

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

storage_to(t: int) → numpy.array[source]

Returns the storage of all products up to time t

Parameters:

t – Time

Returns:

An array of size n_products * t giving the quantity of each product in storage at every step up to t.

loans_to(t: int) → float[source]

Returns loans up to time t

Parameters:

t – time

Returns:

An array of t real numbers giving the loans registered at time-steps up to t

add_loan(total: float, t: int) → bool[source]

Adds a loan at the given time

Parameters:

  • total – Total amount of the loan

  • t – time step to take the loan

Returns:

Success or failure

Remarks:

  • Taking a loan is simulated as reception of money. Payment back of the loan is not simulated in this call. To simulate paying back the loan, use pay at the times of installment payments.

pay(payment: float, 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 wallet can go negative

Returns:

Success or failure

transport_to(product: int, quantity: int, t: int, ignore_inventory_shortage: bool = True, ignore_space_shortage: bool = True) → bool[source]

Simulates transporting products to/from storage 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 storage[product]

  • ignore_space_shortage – Ignore the limit on total storage which may lead to total_storage > max_storage

Returns:

Success or failure

schedule(job: scml.scml2019.common.Job, ignore_inventory_shortage=True, ignore_money_shortage=True, ignore_space_shortage=True, override=True) → bool[source]

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

Parameters:

  • job – Production job

  • ignore_inventory_shortage – If true shortages in inputs will be ignored

  • ignore_money_shortage – If true, shortage in money will be ignored

  • ignore_space_shortage – If true, shortage in space will be ignored

  • override – Whether the job should override any already registered job at its time-step

Returns:

Success/failure

buy(product: int, quantity: int, price: int, t: int, ignore_money_shortage: bool = True, ignore_space_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 wallet can go negative

  • ignore_space_shortage – Ignore the limit on total storage which may lead to total_storage > max_storage

Returns:

Success or failure

Remarks:

  • buy cannot ever have inventory shortage

See also

sell

sell(product: int, quantity: int, price: int, t: int, ignore_money_shortage: bool = True, 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_money_shortage – If True, shortage in money will be ignored and the wallet can go negative

  • ignore_inventory_shortage – Ignore shortage in the product which may lead to negative storage[product]

Returns:

Success or failure

Remarks:

  • sell cannot ever have space shortage

See also

buy

class scml.scml2019.simulators.FastFactorySimulator(initial_wallet: float, initial_storage: Dict[int, int], n_steps: int, n_products: int, profiles: List[scml.scml2019.common.ManufacturingProfile], max_storage: int | None)[source]

Bases: FactorySimulator

A faster implementation of the FactorySimulator interface (compared with SlowFactorySimulator.

property fixed_before[source]

Gives the time before which the schedule is fixed.

See also

fix_before

property n_lines[source]

Number of lines

property final_balance: float[source]

Final balance given everything scheduled so-far

_as_array(storage: Dict[int, int]) → numpy.array[source]
init(*args, **kwargs)[source]
wallet_to(t: int) → numpy.array[source]

Returns the cash in wallet up to and including time t.

Parameters:

t – Time

Returns:

storage_to(t: int) → numpy.array[source]

Returns the storage of all products up to time t

Parameters:

t – Time

Returns:

An array of size n_products * t giving the quantity of each product in storage at every step up to t.

line_schedules_to(t: int) → numpy.array[source]

Returns the schedule of each line up to a given timestep

Parameters:

t – time

Returns:

An array of n_lines * t values giving the schedule up to t.

Remarks:

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

loans_to(t: int) → numpy.array[source]

Returns loans up to time t

Parameters:

t – time

Returns:

An array of t real numbers giving the loans registered at time-steps up to t

add_loan(total: float, t: int) → bool[source]

Adds a loan at the given time

Parameters:

  • total – Total amount of the loan

  • t – time step to take the loan

Returns:

Success or failure

Remarks:

  • Taking a loan is simulated as reception of money. Payment back of the loan is not simulated in this call. To simulate paying back the loan, use pay at the times of installment payments.

pay(payment: float, 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 wallet can go negative

Returns:

Success or failure

transport_to(product: int, quantity: int, t: int, ignore_inventory_shortage: bool = True, ignore_space_shortage: bool = True) → bool[source]

Simulates transporting products to/from storage 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 storage[product]

  • ignore_space_shortage – Ignore the limit on total storage which may lead to total_storage > max_storage

Returns:

Success or failure

buy(product: int, quantity: int, price: int, t: int, ignore_money_shortage: bool = True, ignore_space_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 wallet can go negative

  • ignore_space_shortage – Ignore the limit on total storage which may lead to total_storage > max_storage

Returns:

Success or failure

Remarks:

  • buy cannot ever have inventory shortage

See also

sell

sell(product: int, quantity: int, price: int, t: int, ignore_money_shortage: bool = True, 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_money_shortage – If True, shortage in money will be ignored and the wallet can go negative

  • ignore_inventory_shortage – Ignore shortage in the product which may lead to negative storage[product]

Returns:

Success or failure

Remarks:

  • sell cannot ever have space shortage

See also

buy

schedule(job: scml.scml2019.common.Job, ignore_inventory_shortage=True, ignore_money_shortage=True, ignore_space_shortage=True, override=True) → bool[source]

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

Parameters:

  • job – Production job

  • ignore_inventory_shortage – If true shortages in inputs will be ignored

  • ignore_money_shortage – If true, shortage in money will be ignored

  • ignore_space_shortage – If true, shortage in space will be ignored

  • override – Whether the job should override any already registered job at its time-step

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, storage: numpy.array, wallet: float, loans: float, line_schedules: 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

  • storage – quantity of every product (array of integers of size n_products)

  • wallet – Cash in wallet

  • loans – Loans

  • line_schedules – Line schedules (array of process numbers/NO_PRODUCTION of size n_lines)

scml.scml2019.simulators.transaction(simulator)[source]

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

scml.scml2019.simulators.temporary_transaction(simulator)[source]

Runs the simulated actions then rolls them back