sim Module

Overview

The sim module contains code for simulating multi-echelon inventory systems. The primary data object is the SupplyChainNetwork object and the SupplyChainNode and SupplyChainProduct objects that it contains. These objects contain all of the data for the simulation instance.

Note

The terms “node” and “stage” are used interchangeably in the documentation.

See also

For an overview of simulation in Stockpyl, see the tutorial page for simulation and the tutorial page for multi-product simulation.

API Reference

simulation(network, num_periods, rand_seed=None, progress_bar=True, consistency_checks='W')[source]

Perform the simulation for num_periods periods. Fills performance measures directly into network.

If initial_inventory_level is None for any node, its initial inventory level is set to its base-stock level (or similar for other inventory policy types).

Parameters

  • network (SupplyChainNetwork) – The multi-echelon inventory network.

  • num_periods (int) – Number of periods to simulate.

  • rand_seed (int, optional) – Random number generator seed.

  • progress_bar (bool, optional) – Display a progress bar?

  • consistency_checks (str, optional) –

    String indicating whether to run consistency checks (backorder calculations) and what to do if check fails. Currently supported strings are:

    • ’N’: No consistency checks

    • ’W’: Issue warning if check fails but do not dump instance and simulation data to file (default)

    • ’WF’: Issue warning if check fails and dump instance and simulation data to file

    • ’E’: Raise exception if check fails but do not dump instance and simulation data to file

    • ’EF’: Raise exception if check fails and dump instance and simulation data to file

Returns

Total cost over all nodes and periods.

Return type

float

Raises

ValueError – If network contains a directed cycle.

initialize(network, num_periods, rand_seed=None)[source]

Initialize the simulation:

  • Check validity of the network

  • Initialize state and decision variables at each node

  • Set the numpy PRNG seed

  • Set network.period to None (will be set to 0 in first call to stockpyl.sim.step())

Note

Calling initialize() function, then stockpyl.sim.step() function once per period, then close() function is equivalent to calling simulate() function (aside from progress bar, which simulate() displays but the individual functions do not).

Parameters

  • network (SupplyChainNetwork) – The multi-echelon inventory network.

  • num_periods (int) – Number of periods to simulate.

  • rand_seed (int, optional) – Random number generator seed.

Raises

ValueError – If network contains a directed cycle.

step(network, order_quantity_override=None, consistency_checks='W')[source]

Execute one time period of the simulation:

  • Increment network.period by 1

  • Update disruption states

  • Generate demands and orders

  • Generate shipments

  • Update costs, pipelines, etc.

Note

Calling initialize() function, then stockpyl.sim.step() function once per period, then close() function is equivalent to calling simulate() function (aside from progress bar, which simulate() displays but the individual functions do not).

Parameters

  • network (SupplyChainNetwork) – The multi-echelon inventory network.

  • consistency_checks (str, optional) – String indicating whether to run consistency checks (backorder calculations) and what to do if check fails. See docstring for simulation() for list of currently supported strings.

  • order_quantity_override (dict, optional) – Nested dictionary such that order_quantity_override[node][pred][rm] is an order quantity (or None) for each node in the network, each predecessor, and each raw material the node orders from that predecessor (each specified by its index, not the object). If provided, these order quantities will override the order quantities that would otherwise be calculated for the nodes/products. If the node has a single predecessor and raw material, pred and rm may be set to None and they will be determined automatically. If order_quantity_override is provided but its value is None for a given node, an order quantity will be calculated for that node as usual. (This option is mostly used when running the simulation from outside the package, e.g., in a reinforcement learning environment; it is analogous to setting the action for the current time period.)

close(network)[source]

Close down the simulation:

  • Calculate and return the total cost over all nodes and periods.

Note

Calling initialize() function, then stockpyl.sim.step() function once per period, then close() function is equivalent to calling simulate() function (aside from progress bar, which simulate() displays but the individual functions do not).

Parameters

network (SupplyChainNetwork) – The multi-echelon inventory network.

Returns

Total cost over all nodes and periods.

Return type

float

run_multiple_trials(network, num_trials, num_periods, rand_seed=None, progress_bar=True)[source]

Run num_trials trials of the simulation, each with num_periods periods. Return mean and SEM of average cost per period across all trials.

(To build \(\alpha\)-confidence interval, use mean_cost \(\pm z_{1-(1-\alpha)/2} \times\) sem_cost.)

Note: After trials, network will contain state variables for the most recent trial.

Parameters

  • network (SupplyChainNetwork) – The multi-echelon inventory network.

  • num_trials (int) – Number of trials to simulate.

  • num_periods (int) – Number of periods to simulate.

  • rand_seed (int, optional) – Random number generator seed.

  • progress_bar (bool, optional) – Display a progress bar?

Returns

  • mean_cost (float) – Mean of average cost per period across all trials.

  • sem_cost (float) – Standard error of average cost per period across all trials.