Beer Game Supply Chain Simulation

This project implements a simplified Beer Game supply chain simulator to study the bullwhip effect under two control modes:

• Mode A (baseline / reactive policy): agents order primarily from local inventory gaps and incoming demand.
• Mode B (stabilized policy): agents include smoothing and correction terms to reduce amplification.

The goal is to compare how local ordering policies affect system-wide inventory oscillations, order variance, and total operating cost.

Architecture

Core components are organized around the following concepts:

• Agent
  • Represents one echelon (e.g., retailer, wholesaler, distributor, factory).
  • Tracks on-hand inventory, backlog, pipeline orders, and order decisions.
• SupplyChain
  • Connects all agents and advances the simulation one period at a time.
  • Applies demand, shipment/order delays, and state transitions across echelons.
• Policies
  • Mode A policy: baseline ordering rule that tends to overreact to local signals.
  • Mode B policy: damped ordering rule that uses stabilization terms to mitigate oscillations.
• Runner / experiment script
  • Parses parameters, executes one or more simulation runs, and writes plots/CSV outputs.

Quickstart

Requirements

• Python 3.10+ (3.11 recommended)
• pip for dependency installation

Install

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run a single-mode simulation

python runner.py --mode A --periods 100 --seed 42
python runner.py --mode B --periods 100 --seed 42

Run comparison and generate plot

python runner.py --compare --periods 100 --seed 42 --save-plots

If your runner entry point is exposed as a module, equivalent commands are typically: python -m beergame.runner ...

Parameter Reference

Parameter	Meaning	Typical effect
initial_inventory	Starting on-hand inventory per agent	Higher values reduce early stockouts but can increase holding cost
initial_demand	Base customer demand level before any shock	Sets baseline flow through all echelons
shock_start	Period when demand shock begins	Determines when system stress starts
shock_magnitude	Size of demand increase/decrease	Larger shocks create stronger transients
shock_duration	Number of periods shock persists	Longer shocks shift average inventory/order levels
order_delay	Delay between placing and receiving orders	Larger delays increase risk of over-ordering
shipment_delay	Transit delay for physical goods	Increases pipeline inventory and response lag
alpha	Responsiveness to inventory/backlog gap	Higher alpha usually increases oscillation amplitude
beta	Smoothing / damping gain (Mode B)	Higher beta typically reduces variance (up to stability limits)
holding_cost	Cost per unit inventory per period	Penalizes excess stock
backlog_cost	Cost per unit unmet demand per period	Penalizes stockouts and delayed fulfillment
demand_noise_std	Random demand noise scale	More noise can trigger stronger bullwhip under reactive policies

Outputs

Generated plots

Depending on CLI flags, the simulation can produce:

• Time-series plots for inventory, backlog, and orders by echelon
• Comparison plots (Mode A vs Mode B) for:
  • order trajectories
  • cumulative/period costs
  • inventory oscillation profiles

CSV schema (when enabled)

When CSV export is enabled, each row is typically one period × agent observation with fields such as:

• run_id
• mode
• period
• agent
• demand
• shipment_received
• order_placed
• inventory_on_hand
• backlog
• pipeline
• holding_cost
• backlog_cost
• total_cost

Interpreting key metrics

• Order variance: measures amplification of ordering signals; higher variance implies stronger bullwhip.
• Total cost: aggregate of holding + backlog costs over all periods/agents.
• Oscillation amplitude: peak-to-trough swing in inventory/orders; larger amplitude indicates less stable control.

Expected Behavior

In a typical demand-shock experiment:

• Mode A should exhibit stronger bullwhip oscillations and higher total system cost.
• Mode B should show damped oscillations, faster settling, and lower overall cost.

Use identical seeds and demand scenarios across both modes to make fair comparisons.