sim Module

Overview

The sim module contains code for simulating multi-echelon inventory systems. The primary data object is the SupplyChainNetwork and the SupplyChainNode objects that it contains, which contains 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.

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) – Dictionary indicating an order quantity (or None) for each node in network (specified as SupplyChainNode objects). If provided, these order quantity will override the order quantities that would otherwise be calculated for the nodes. 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.