From c5d62e8fb5b4ad4cb4c3bd6055e66a467a23f3e6 Mon Sep 17 00:00:00 2001 From: "Erick C. Jones Jr." <44578073+yamierick@users.noreply.github.com> Date: Tue, 27 Oct 2026 08:56:59 -0500 Subject: [PATCH] 07: buy now, rent later, the two-stage server farm The server-farm two-stage program has been on this library's to-do list since the migration (StochasticLP, 14 copies); IE 5301 teaches it in 2026 as 03_Two_Stage_Server_Farm.ipynb. Buy CPUs, GPUs and TPUs now under a budget and floor space (integer, first stage); rent cloud compute per scenario to cover the shortfall (integer, recourse); minimise purchase plus mean cloud bill. The course generates demand with numpy at run time. Here it is a table, data/raw/server_farm_demand.csv: 50 scenarios from random.Random with the seed recorded in serverfarm.py, and a test that it regenerates exactly. The seed is deliberate: with it the optimal purchase is unique (test_the_optimal_plan_is_unique minimises and maximises each machine count over every optimal plan), so the agreement assertion compares whole plans. Seed 7 with 40 scenarios has ties, and the docstring says so. The notebook builds the model with addVars and asks before solving whether money or floor space runs out first: space binds (100 of 100), the budget does not (592 of 1000). Result: buy 51 CPU, 5 GPU, 8 TPU, expected cost 1000.54. The plan-for-the-average shortcut buys no GPUs, reports an objective of 1002.00, and costs 1039.12 against the real scenarios: VSS 38.58. The package holds the same model in matrix form (addMVar, the course's form), so the assertion also shows the two formulations agree, exactly. The recourse figure distinguishes owned from rented by hatch as well as colour, and prints one Figure line per panel. Gate: 207 passed; the server-farm tests pass on the size-limited licence too (153 integer variables); 20 notebooks and 14 seeds clean; ruff clean. Co-Authored-By: Claude Opus 5.5 --- CITATION.cff | 2 +- CLAUDE.md | 7 +- NEXT_SESSION_PROMPT.md | 4 +- README.md | 4 +- data/raw/server_farm_demand.csv | 51 ++ data/raw/server_farm_machines.csv | 4 + .../server_farm.ipynb | 623 ++++++++++++++++++ src/orteach/serverfarm.py | 130 ++++ tests/test_serverfarm.py | 92 +++ tools/seeds/seed_serverfarm.py | 309 +++++++++ 10 files changed, 1218 insertions(+), 8 deletions(-) create mode 100644 data/raw/server_farm_demand.csv create mode 100644 data/raw/server_farm_machines.csv create mode 100644 notebooks/07_stochastic_and_newsvendor/server_farm.ipynb create mode 100644 src/orteach/serverfarm.py create mode 100644 tests/test_serverfarm.py create mode 100644 tools/seeds/seed_serverfarm.py diff --git a/CITATION.cff b/CITATION.cff index 64fc457..d1bda7d 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -2,7 +2,7 @@ cff-version: 1.2.0 message: "If you use this teaching material, or the models in it, please cite it as below." title: "Teaching notebooks for IE 3315, IE 5301 and REE 4301" abstract: >- - Nineteen executed teaching notebooks and an accompanying Python package, + Twenty executed teaching notebooks and an accompanying Python package, organised by subject across three courses in industrial engineering and energy systems modelling. Each notebook builds its model by hand and then asserts agreement with the packaged implementation, so the two cannot drift apart diff --git a/CLAUDE.md b/CLAUDE.md index bbfe2f0..c291c30 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -136,7 +136,7 @@ They belong with the repository. Moved twice so far: to `C:\dev\` on 2026-09-05, ## Status, measured 2026-09-05 -Nineteen notebooks (seventeen as of 2026-09-05) across twelve subjects (`02` empty on purpose), sixteen package modules, thirty- +Twenty notebooks (seventeen as of 2026-09-05) across twelve subjects (`02` empty on purpose), sixteen package modules, thirty- odd tables in `data/raw/`, 170 tests, and `tools/check_notebooks.py`. README.md has the table. **What to run before believing anything:** `python -m pytest tests/ -q`, @@ -175,5 +175,6 @@ with a status line per finding, and the list of what must change before the firs **Not done:** the 174 files the migration queue could not classify by name were only partly read; the ones that were (Pooling, Portfolio Selection, Gandhi Cloth, StochasticLP, the Monte Carlo set, the REE modules beyond M0) are either migrated or named in a folder README. Fixed-charge / logical -constraints (`Gandhi_Cloth`, `Portfolio Selection`) would be a second `05` notebook; the two-stage -server farm (`StochasticLP`, 14 copies) and the bakery VSS/EVPI example a second `07`. +constraints (`Gandhi_Cloth`, `Portfolio Selection`) would be a second `05` notebook; the bakery +VSS/EVPI example another `07`. The two-stage server farm is `07/server_farm.ipynb` (2026-10-27), +from IE 5301's 2026 code, and `07/risk_measures.ipynb` adds VaR and CVaR. diff --git a/NEXT_SESSION_PROMPT.md b/NEXT_SESSION_PROMPT.md index 3a9a6c7..f9b1549 100644 --- a/NEXT_SESSION_PROMPT.md +++ b/NEXT_SESSION_PROMPT.md @@ -133,8 +133,8 @@ caught by a printed number rather than by review or by the suite. ## Still open in this repository, beyond the closed queue -- Second notebooks for `05` (Gandhi cloth fixed charge, Portfolio logic) and `07` (server-farm - two-stage LP, bakery VSS/EVPI). +- Second notebooks for `05` (Gandhi cloth fixed charge, Portfolio logic) and `07` (bakery + VSS/EVPI). The server farm and VaR/CVaR landed in `07` on 2026-10-27. - Roughly 140 files in the original migration queue were never classified or read. - ~~`README.md` and `notebooks/12_energy_systems_pypsa/README.md` point at REE 4301 by its OneDrive path.~~ **Done.** Both carry the GitHub URL, and since 2026-09-13 it resolves for diff --git a/README.md b/README.md index 67e784d..9d339ee 100644 --- a/README.md +++ b/README.md @@ -125,7 +125,7 @@ ahead of LP formulation, which is backwards. ## What is here, measured 2026-09-05 -Nineteen teaching notebooks in twelve subjects, each with its package module, its tables and its +Twenty teaching notebooks in twelve subjects, each with its package module, its tables and its tests. `02_simplex_and_bases` is empty on purpose. Every notebook ships executed, ends in the agreement assertion, and passes `tools/check_notebooks.py`. @@ -136,7 +136,7 @@ agreement assertion, and passes `tools/check_notebooks.py`. | 04 | `transportation`, `assignment` | `transportation`, `assignment` | | 05 | `facility_location` | `facility_location` | | 06 | `curve_fit_lifting`, `pooling` | `nonconvex` | -| 07 | `newsvendor`, `risk_measures` | `newsvendor`, `data` | +| 07 | `newsvendor`, `risk_measures`, `server_farm` | `newsvendor`, `data`, `serverfarm` | | 08 | `monte_carlo` | `montecarlo` | | 09 | `markov_and_queues` | `markov`, `queueing` | | 10 | `zero_sum_game`, `saddle_points` | `games` | diff --git a/data/raw/server_farm_demand.csv b/data/raw/server_farm_demand.csv new file mode 100644 index 0000000..fb105c7 --- /dev/null +++ b/data/raw/server_farm_demand.csv @@ -0,0 +1,51 @@ +scenario,cpu,gpu,tpu +1,63.47,7.96,17.05 +2,69.1,8.95,17.68 +3,78.1,11.05,18.93 +4,60.59,8.59,12.18 +5,65.48,7.02,17.44 +6,73.48,10.5,9.91 +7,65.71,10.41,15.16 +8,88.42,5.9,19.11 +9,75.6,10.69,18.44 +10,67.5,5.98,14.88 +11,54.51,8.08,12.74 +12,70.88,11.13,7.78 +13,74.38,9.26,15.09 +14,75.75,7.64,18.13 +15,65.31,8.16,12.31 +16,85.1,7.64,8.19 +17,64.73,8.64,17.79 +18,79.05,7.94,15.97 +19,67.73,10.96,16.62 +20,60.64,7.04,15.49 +21,44.57,5.41,14.41 +22,68.75,8.94,15.51 +23,79.78,6.03,11.76 +24,74.41,7.33,19.83 +25,89.93,8.39,15.8 +26,69.22,5.0,14.19 +27,62.52,7.85,14.6 +28,58.91,5.69,13.82 +29,75.01,10.37,17.29 +30,69.62,11.55,18.29 +31,69.2,8.05,13.5 +32,71.51,8.1,10.06 +33,65.2,9.1,9.45 +34,76.6,8.42,10.87 +35,79.14,7.73,14.36 +36,65.24,11.47,9.81 +37,72.68,10.21,12.03 +38,62.42,4.91,8.59 +39,82.28,7.69,15.7 +40,63.57,5.63,10.85 +41,75.95,8.41,20.12 +42,67.83,9.06,13.17 +43,51.77,10.97,12.42 +44,73.74,4.21,10.94 +45,57.81,13.44,13.96 +46,69.82,7.08,13.68 +47,69.82,7.85,11.94 +48,76.23,7.02,16.29 +49,57.58,4.47,21.9 +50,64.53,10.84,15.16 diff --git a/data/raw/server_farm_machines.csv b/data/raw/server_farm_machines.csv new file mode 100644 index 0000000..aa77155 --- /dev/null +++ b/data/raw/server_farm_machines.csv @@ -0,0 +1,4 @@ +machine,purchase_cost,space,cloud_cost +cpu,6,1,7 +gpu,14,5,18 +tpu,27,3,30 diff --git a/notebooks/07_stochastic_and_newsvendor/server_farm.ipynb b/notebooks/07_stochastic_and_newsvendor/server_farm.ipynb new file mode 100644 index 0000000..5d00bec --- /dev/null +++ b/notebooks/07_stochastic_and_newsvendor/server_farm.ipynb @@ -0,0 +1,623 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "4054e3bc", + "metadata": {}, + "source": [ + "# Buy now, rent later: a two-stage server farm\n", + "\n", + "The newsvendor in this folder orders papers before it knows demand and then sells or scraps. This\n", + "is the same structure with more moving parts. You buy CPUs, GPUs and TPUs now, under a budget and a\n", + "floor-space limit. Then demand for each kind of compute arrives, and whatever your own machines\n", + "cannot cover you rent from a cloud provider at a higher price.\n", + "\n", + "The purchase is the **first stage**: one decision, no scenario index. The rentals are the **second\n", + "stage**, or recourse: one decision per scenario, made after that scenario's demand is known." + ] + }, + { + "cell_type": "markdown", + "id": "b3322cfb", + "metadata": {}, + "source": [ + "## Setup: where the package lives\n", + "\n", + "This notebook builds its model by hand and then checks it against `orteach`, the package in `src/`.\n", + "Run from a clone of the repository, `../../src` is right there. On Colab there is no clone until\n", + "this cell makes one, and no `gurobipy` until it installs it. Nothing here needs a secret." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "8343f86e", + "metadata": { + "execution": { + "iopub.execute_input": "2026-10-27T13:55:49.361577Z", + "iopub.status.busy": "2026-10-27T13:55:49.361354Z", + "iopub.status.idle": "2026-10-27T13:55:49.377145Z", + "shell.execute_reply": "2026-10-27T13:55:49.376572Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "package: src\\orteach\n" + ] + } + ], + "source": [ + "import os, subprocess, sys\n", + "\n", + "REPO_URL = \"https://github.com/sear-labs/teaching-code\"\n", + "REF = \"v1.0.0\" # the release this notebook ships in: Colab clones THIS\n", + "\n", + "try:\n", + " import google.colab # noqa: F401 - succeeds only on Colab\n", + " ON_COLAB = True\n", + "except ImportError:\n", + " ON_COLAB = False\n", + "\n", + "if ON_COLAB:\n", + " if not os.path.isdir(\"/content/teaching-code\"):\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", + " os.chdir(\"/content/teaching-code/notebooks/07_stochastic_and_newsvendor\")\n", + " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", + "\n", + "sys.path.insert(0, os.path.abspath(os.path.join(\"..\", \"..\", \"src\")))\n", + "try:\n", + " import orteach # noqa: F401\n", + "except ImportError:\n", + " raise SystemExit(\"orteach not found: run this notebook from its own folder inside the repository, \"\n", + " \"so that ../../src exists.\")\n", + "root = os.path.abspath(os.path.join(\"..\", \"..\"))\n", + "print(\"package:\", os.path.relpath(os.path.dirname(orteach.__file__), root))" + ] + }, + { + "cell_type": "markdown", + "id": "963f1d95", + "metadata": {}, + "source": [ + "## Licence setup\n", + "\n", + "Nothing here needs a key: `pip install gurobipy` ships a size-limited licence, and this model (three\n", + "purchase variables and three rentals per scenario) sits well inside it. A machine with its own\n", + "licence file uses that instead, and on Colab three secrets read from the key icon in the left\n", + "sidebar are used when they are there. The environment starts silent, so no licence number lands in\n", + "an output cell." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "cd615e39", + "metadata": { + "execution": { + "iopub.execute_input": "2026-10-27T13:55:49.379349Z", + "iopub.status.busy": "2026-10-27T13:55:49.379152Z", + "iopub.status.idle": "2026-10-27T13:55:49.444692Z", + "shell.execute_reply": "2026-10-27T13:55:49.444156Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "licence: local gurobi.lic\n" + ] + } + ], + "source": [ + "import gurobipy as gp\n", + "from gurobipy import GRB\n", + "\n", + "env = gp.Env(empty=True)\n", + "env.setParam(\"OutputFlag\", 0) # start silent: the licence banner, and its licence number, stay out of the outputs\n", + "try:\n", + " from google.colab import userdata\n", + " try:\n", + " env.setParam(\"WLSACCESSID\", userdata.get(\"GRB_WLSACCESSID\"))\n", + " env.setParam(\"WLSSECRET\", userdata.get(\"GRB_WLSSECRET\"))\n", + " env.setParam(\"LICENSEID\", int(userdata.get(\"GRB_LICENSEID\")))\n", + " licence = \"Colab Secrets (WLS)\"\n", + " except (userdata.SecretNotFoundError, userdata.NotebookAccessError):\n", + " licence = \"the size-limited licence pip ships\" # no key needed; see the note above\n", + "except ImportError:\n", + " licence = \"local gurobi.lic\"\n", + "env.start()\n", + "print(\"licence:\", licence)" + ] + }, + { + "cell_type": "markdown", + "id": "002bebc5", + "metadata": {}, + "source": [ + "## The machines and the scenarios are tables\n", + "\n", + "Each machine type has a price, the floor space it takes, and the price of renting one unit of the\n", + "same compute from the cloud instead. Each of the 50 demand scenarios says how much of each kind of\n", + "compute is needed. Both are instance data, so they live in `data/raw/` and the package reads the\n", + "same files. The budget and the floor space are knobs: one number each, written out here." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "ceb1c291", + "metadata": { + "execution": { + "iopub.execute_input": "2026-10-27T13:55:49.446903Z", + "iopub.status.busy": "2026-10-27T13:55:49.446682Z", + "iopub.status.idle": "2026-10-27T13:55:49.691570Z", + "shell.execute_reply": "2026-10-27T13:55:49.690946Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "budget 1000, floor space 100, 50 scenarios\n", + "machine buy space cloud demand: mean min max\n", + "cpu 6 1 7 69.4 44.6 89.9\n", + "gpu 14 5 18 8.3 4.2 13.4\n", + "tpu 27 3 30 14.4 7.8 21.9\n" + ] + } + ], + "source": [ + "from statistics import mean\n", + "from orteach import tolerance\n", + "from orteach.serverfarm import load_machines, load_demand\n", + "\n", + "BUDGET = 1000\n", + "SPACE = 100\n", + "\n", + "machines = load_machines()\n", + "demand = load_demand()\n", + "T = machines.types\n", + "K = len(demand)\n", + "\n", + "print(f\"budget {BUDGET}, floor space {SPACE}, {K} scenarios\")\n", + "print(f\"{'machine':8} {'buy':>5} {'space':>6} {'cloud':>6} demand: mean min max\")\n", + "for t in T:\n", + " col = [d[t] for d in demand]\n", + " print(f\"{t:8} {machines.purchase[t]:5.0f} {machines.space[t]:6.0f} {machines.cloud[t]:6.0f}\"\n", + " f\" {mean(col):6.1f} {min(col):6.1f} {max(col):6.1f}\")" + ] + }, + { + "cell_type": "markdown", + "id": "5b77bb01", + "metadata": {}, + "source": [ + "## The first stage\n", + "\n", + "Three integer variables, one per machine type, and two limits on them. The limits are written out\n", + "term by term, because which one binds is the first thing to look at. Predict now, before anything\n", + "is solved: will the purchase run out of money first, or out of floor space?" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "b4283881", + "metadata": { + "execution": { + "iopub.execute_input": "2026-10-27T13:55:49.694069Z", + "iopub.status.busy": "2026-10-27T13:55:49.693711Z", + "iopub.status.idle": "2026-10-27T13:55:49.700846Z", + "shell.execute_reply": "2026-10-27T13:55:49.700266Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "6.0 buy[cpu] + 14.0 buy[gpu] + 27.0 buy[tpu] <= 1000\n", + "buy[cpu] + 5.0 buy[gpu] + 3.0 buy[tpu] <= 100\n" + ] + } + ], + "source": [ + "m = gp.Model(\"server farm\", env=env)\n", + "tolerance.apply(m)\n", + "buy = m.addVars(T, vtype=GRB.INTEGER, name=\"buy\")\n", + "\n", + "budget = m.addConstr(machines.purchase[\"cpu\"] * buy[\"cpu\"] + machines.purchase[\"gpu\"] * buy[\"gpu\"]\n", + " + machines.purchase[\"tpu\"] * buy[\"tpu\"] <= BUDGET, name=\"budget\")\n", + "space = m.addConstr(machines.space[\"cpu\"] * buy[\"cpu\"] + machines.space[\"gpu\"] * buy[\"gpu\"]\n", + " + machines.space[\"tpu\"] * buy[\"tpu\"] <= SPACE, name=\"space\")\n", + "m.update()\n", + "print(m.getRow(budget), \"<=\", BUDGET)\n", + "print(m.getRow(space), \"<=\", SPACE)" + ] + }, + { + "cell_type": "markdown", + "id": "d06a8c69", + "metadata": {}, + "source": [ + "## The second stage\n", + "\n", + "One rental variable per scenario and machine type, and one covering constraint for each: what you\n", + "own plus what you rent must meet that scenario's demand. The constraint is identical across\n", + "scenarios except for the demand number, which is what `addConstrs` over `k` is for. The three\n", + "machine types are written out, so you can see that each scenario has its own rentals but shares\n", + "the single `buy`." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "4f582645", + "metadata": { + "execution": { + "iopub.execute_input": "2026-10-27T13:55:49.702857Z", + "iopub.status.busy": "2026-10-27T13:55:49.702671Z", + "iopub.status.idle": "2026-10-27T13:55:49.714504Z", + "shell.execute_reply": "2026-10-27T13:55:49.714003Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "153 variables (all integer: 153 ), 152 constraints\n" + ] + } + ], + "source": [ + "rent = m.addVars(K, T, vtype=GRB.INTEGER, name=\"rent\")\n", + "m.addConstrs((buy[\"cpu\"] + rent[k, \"cpu\"] >= demand[k][\"cpu\"] for k in range(K)), name=\"cover_cpu\")\n", + "m.addConstrs((buy[\"gpu\"] + rent[k, \"gpu\"] >= demand[k][\"gpu\"] for k in range(K)), name=\"cover_gpu\")\n", + "m.addConstrs((buy[\"tpu\"] + rent[k, \"tpu\"] >= demand[k][\"tpu\"] for k in range(K)), name=\"cover_tpu\")\n", + "m.update()\n", + "print(m.NumVars, \"variables (all integer:\", m.NumIntVars, \"),\", m.NumConstrs, \"constraints\")" + ] + }, + { + "cell_type": "markdown", + "id": "1eb4da55", + "metadata": {}, + "source": [ + "The objective is what you pay for the machines, plus the cloud bill averaged over the scenarios,\n", + "each equally likely." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "73e6d001", + "metadata": { + "execution": { + "iopub.execute_input": "2026-10-27T13:55:49.716594Z", + "iopub.status.busy": "2026-10-27T13:55:49.716417Z", + "iopub.status.idle": "2026-10-27T13:55:49.720244Z", + "shell.execute_reply": "2026-10-27T13:55:49.719857Z" + } + }, + "outputs": [], + "source": [ + "purchase_cost = gp.quicksum(machines.purchase[t] * buy[t] for t in T)\n", + "cloud_bill = gp.quicksum(machines.cloud[t] * rent[k, t] for k in range(K) for t in T) / K\n", + "m.setObjective(purchase_cost + cloud_bill, GRB.MINIMIZE)" + ] + }, + { + "cell_type": "markdown", + "id": "f32cfcb9", + "metadata": {}, + "source": [ + "Predict before solving: will the farm buy any GPUs, given that renting one is only a little dearer\n", + "than owning one?" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "7ce305ec", + "metadata": { + "execution": { + "iopub.execute_input": "2026-10-27T13:55:49.723111Z", + "iopub.status.busy": "2026-10-27T13:55:49.722863Z", + "iopub.status.idle": "2026-10-27T13:55:49.731454Z", + "shell.execute_reply": "2026-10-27T13:55:49.730981Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "buy {'cpu': 51, 'gpu': 5, 'tpu': 8} expected cost 1000.5400 MIP gap 0.0e+00\n", + "money spent 592 of 1000 floor space used 100 of 100\n" + ] + } + ], + "source": [ + "m.optimize()\n", + "hand_buy = {t: round(buy[t].X) for t in T}\n", + "hand_cost = m.ObjVal\n", + "print(\"buy\", hand_buy, f\" expected cost {hand_cost:.4f} MIP gap {m.MIPGap:.1e}\")\n", + "print(f\"money spent {purchase_cost.getValue():.0f} of {BUDGET} floor space used \"\n", + " f\"{sum(machines.space[t] * hand_buy[t] for t in T):.0f} of {SPACE}\")" + ] + }, + { + "cell_type": "markdown", + "id": "191f34c0", + "metadata": {}, + "source": [ + "Was your prediction about the binding limit right? If one limit is slack, what is the other one\n", + "costing you, and how would you find out?\n", + "\n", + "## The recourse\n", + "\n", + "The purchase is the same in every scenario; the rentals are not. Look at both together." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "1fa9597c", + "metadata": { + "execution": { + "iopub.execute_input": "2026-10-27T13:55:49.733587Z", + "iopub.status.busy": "2026-10-27T13:55:49.733398Z", + "iopub.status.idle": "2026-10-27T13:55:51.306645Z", + "shell.execute_reply": "2026-10-27T13:55:51.306125Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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uro6JCYmora2FgkJCWo3R3XZ+XNRXlqM+vNnrIlCgwHxyWmoqzqldtNIAdn5c93evvfD10LcEurMpUuXUF5ejoyMDKcp4CSPu+OqVBzYsmULrrnmmg6333333W6vNg4YMAALFy7EwoULfX4Pd23lZyU4eFyJtCVcznG0MnbRSjuJKLyE6/nd3q+/QeulJkR3iUOU0brMeHjmAEVe29Mx9TUOcCahBrBmHRGR/6ZMmeJX7Q5PdQiJiIiIiIiU4pogFAmThBpgq1lHRERERKRVlUfK1G4CERGR6kRNEAJMEhIRERERURC0mprtq2Eio41oaapTu0lERESqEzVBCDBJSCScpovn1G4CERERkWyn9m2z19U2t5oQE8daeERERCKLULsBRNSu6eI5HN1RpHYziIiIiGRrunjeuvHeD8ytJhVbQ0RERJ3hTEJSXdeeKbhUX4OB436EuO69AOhv5ztf2BKEXeJ7qN0UIiIiItkio43tiUGDAXHdk9VtEBEREXnFJKEGmdta1W6CoprrqhEb3wPlpR+H7e7NjglCblJDREREWld5pAwtTXWIiUuAudUUtud4RETkn71ff+N299/hmQPUa1QYYZJQY8xtrSgvLVa7GYqKje+BplrrcpT682dwat82tZsUUq4JwsioaLWbRH54/cOtQXnde/OvDsrrKu3YsWPIzc3F+fPn1W6K8ML9swLw80IUTiq/242UwWOQMmiU2k0hIiIN2XXcVqO/0en2r747Lvu1tXLerOY5M2sSaogtQXipvkbtpijK1FjXXq9Gkqz1a8IEE4RERESkR0wQEhERaQ+ThBrhmCAcOO5HajdHUXHdkwGDwfpLmNWrYYKQ5CoqKsKYMWMwcuRIXH311fjmm29w++2345133gEA/PGPf4TRaERjo/VK3FVXXYXPPvsMx44dQ3JyMn79618jJycHgwYNwkcffWR/3dLSUlx77bXIzc3FmDFj8M9//tN+35///GcMGjQIV111Ff72t7+FtsMkCz8vRBQqTBASEZFWBfuc+dZZN+KWm25ASfFG+32inDMzSagBrglC2+YeepE+cjLik9MQGW1EfHJaWNWrYYKQ5KiqqsIdd9yBtWvXYt++fbj//vtx6623Ytq0aSgpKQEAfPrpp8jJycFnn32GhoYGHDhwAFdccQUA4MKFC8jJycGuXbvw8ssv49FHHwUA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9IMtW7ao3QQiIiIiIiJVcCYhERERERERERFRmGOSkIiIiIiIiIiIKMwxSUhERERERERERBTmmCQkIiIiIiIiIiIKc0wSEhERERERCWzJkiUwGAxOP6mpqWo3i4iIdMavJGFhYSHGjh2L+Ph49O7dGzfddBMOHTrk9BhJkrBkyRKkpaUhNjYWU6ZMwYEDBxRtNBERERERUTgZPnw4zp49a//Zv3+/2k0iIiKd8StJuHXrVsyfPx9ffvklSkpK0NbWhhkzZqCxsdH+mOeffx4vvPACXn75ZZSWliI1NRXTp09HfX294o0nIiIiIiIKB1FRUUhNTbX/9OrVS+0mERGRzkT58+CioiKn39944w307t0bu3btwuTJkyFJElauXImnn34as2bNAgCsXbsWKSkpWLduHR544AHlWk5ERERERBQmDh8+jLS0NBiNRowfPx7Lli3DwIED3T7WZDLBZDLZf6+rqwtVM4mISMNk1SSsra0FAPTs2RMAUF5ejoqKCsyYMcP+GKPRiKuvvhrbt293+xomkwl1dXVOP0RERERERGQ1fvx4/P3vf0dxcTFeffVVVFRUYOLEibhw4YLbxxcWFiIxMdH+07dv3xC3mIiItCjgJKEkSVi0aBGuvPJKZGVlAQAqKioAACkpKU6PTUlJsd/nigGMiIiIiIjIs7y8PPz0pz/FiBEjMG3aNHz44YcArKu23Fm8eDFqa2vtPydPngxlc4mISKMCThIuWLAA+/btwzvvvNPhPoPB4PS7JEkdbrNhACMiIiIiIvJd165dMWLECBw+fNjt/UajEQkJCU4/REREnQkoSfjQQw9hw4YN2Lx5M9LT0+23p6amAkCHWYNVVVUdZhfaMIARERERERH5zmQy4eDBg+jTp4/aTSEiIh3xK0koSRIWLFiA999/H5s2bUJGRobT/RkZGUhNTUVJSYn9tpaWFmzduhUTJ05UpsVERERERERh5Be/+AW2bt2K8vJyfPXVV7j55ptRV1eHu+++W+2mERGRjvi1u/H8+fOxbt06/Otf/0J8fLx9xmBiYiJiY2NhMBiwcOFCLFu2DJmZmcjMzMSyZcsQFxeH2bNnB6UDREREREREenbq1CncfvvtOH/+PHr16oUrrrgCX375Jfr3769204iISEf8ShKuWrUKADBlyhSn29944w0UFBQAAJ544gk0Nzdj3rx5qKmpwfjx4/Hxxx8jPj5ekQYTERERERGFk3fffVftJhARURjwK0koSVKnjzEYDFiyZAmWLFkSaJuIiIiIiIiIiIgohALe3ZiIiIiIiIiIiIj0gUlCIiIiIiIiIiKiMMckIRERERERERERUZhjkpCIiIiIiIiIiCjMMUlIREREREREREQU5pgkJCIiIiIiIiIiCnNMEhIREREREREREYU5JgmJiIiIiIiIiIjCHJOEREREREREREREYY5JQiIiCkuFhYUYO3Ys4uPj0bt3b9x00004dOiQ2s0iIiIiIiJSBZOEREQUlrZu3Yr58+fjyy+/RElJCdra2jBjxgw0Njaq3TQiIiIiIqKQi1K7AURERGooKipy+v2NN95A7969sWvXLkyePFmlVhEREREREamDSUIiIiIAtbW1AICePXt6fIzJZILJZLL/XldXF/R2ERERERERhQKXGxMRUdiTJAmLFi3ClVdeiaysLI+PKywsRGJiov2nb9++IWwlERERERFR8DBJSEREYW/BggXYt28f3nnnHa+PW7x4MWpra+0/J0+eDFELiYiIiIiIgovLjYmIKKw99NBD2LBhA7Zt24b09HSvjzUajTAajSFqGRERERERUegwSUhERGFJkiQ89NBD+OCDD7BlyxZkZGSo3SQiIiIiIiLVMElIRERhaf78+Vi3bh3+9a9/IT4+HhUVFQCAxMRExMbGqtw6IiIiIiKi0GJNQiIiCkurVq1CbW0tpkyZgj59+th/3nvvPbWbRkREREREFHKcSUhERGFJkiS1m0BERERERCQMziQkIiIiIiIiIiIKc0wSEhERERERERERhTkmCYmIiIiIiIiIiMIck4RERERERERERERhjklCIiIiIiIiIiKiMMckIRERERERERERUZhjkpCIiIiIiIiIiCjMMUlIREREREREREQU5pgkJCIiIiIiIiIiCnNMEhIREREREREREYU5JgmJiIiIiIiIiIjCHJOEREREREREREREYY5JQiIiIiIiIiIiojDHJCEREREREREREVGYY5KQiIiIiIiIiIgozDFJSEREREREREREFOaYJCQiIiIiIiIiIgpzTBISERERERERERGFOSYJiYiIiIiIiIiIwhyThERERERERERERGGOSUIiIiIiIiIiIqIwxyQhERERERERERFRmGOSkIiIiIiIiIiIKMwxSUhERERE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xytJYsxyh/HKM8Yr3zFeWakVrwySJEny5iISERERERERERGRlum2JiERERERERERERH5hklCIiIiIiIiIiKiMMckIRERERERERERUZhjkpCIiIiIiIiIiCjMMUlIREREREREREQU5pgkJCIiIiIiIiIiCnNMEhIREREREREREYU5JgmJiIiIiIiIiIjCHJOERDq2Zs0adO/eXe1mEBERecV4RUREWsB4RXpnkCRJUrsRRBQczc3NqK+vR+/evdVuChERkUeMV0REpAWMV6R3TBIS6VRrayuio6PVbgYREZFXjFdERKQFjFcUDrjcmMhH//d//4cRI0YgNjYWSUlJmDZtGhobGwEAr7/+OoYPHw6j0Yg+ffpgwYIF9ufV1tbi/vvvR+/evZGQkIBrr70We/futd+/ZMkSjBo1Cm+++SYGDBiAxMRE3Hbbbaivr7c/pqioCFdeeSW6d++OpKQk3HDDDfj+++/t9x87dgwGgwH/+Mc/MGXKFHTp0gVvvfWW2+nwq1atwmWXXYaYmBgMGTIEb775ZpCOGBERqYHxioiItIDxikg8TBIS+eDs2bO4/fbbce+99+LgwYPYsmULZs2aBUmSsGrVKsyfPx/3338/9u/fjw0bNmDQoEEAAEmSkJ+fj4qKCnz00UfYtWsXxowZg6lTp6K6utr++t9//z3Wr1+P//znP/jPf/6DrVu3Yvny5fb7GxsbsWjRIpSWluLTTz9FREQEfvKTn8BisTi188knn8TDDz+MgwcP4rrrruvQjw8++ACPPPIIHnvsMXz99dd44IEHcM8992Dz5s1BOnJERBRKjFdERKQFjFdEgpKIqFO7du2SAEjHjh3rcF9aWpr09NNPu33ep59+KiUkJEiXLl1yuv2yyy6T/vrXv0qSJEnPPvusFBcXJ9XV1dnvf/zxx6Xx48d7bE9VVZUEQNq/f78kSZJUXl4uAZBWrlzp9Lg33nhDSkxMtP8+ceJE6b777nN6zC233CJdf/31Ht+LiIi0g/GKiIi0gPGKSEycSUjkg+zsbEydOhUjRozALbfcgldffRU1NTWoqqrCmTNnMHXqVLfP27VrFxoaGpCUlIRu3brZf8rLy52msw8YMADx8fH23/v06YOqqir7799//z1mz56NgQMHIiEhARkZGQCAEydOOL1fbm6u134cPHgQkyZNcrpt0qRJOHjwoG8HgoiIhMZ4RUREWsB4RSSmKLUbQKQFkZGRKCkpwfbt2/Hxxx/jT3/6E55++ml8+umnXp9nsVjQp08fbNmypcN9jrUsXAvgGgwGp6nuM2fORN++ffHqq68iLS0NFosFWVlZaGlpcXpe165dO+2LwWBw+l2SpA63ERGRNjFeERGRFjBeEYmJMwmJfGQwGDBp0iQ899xz2LNnD2JiYlBSUoIBAwZ4DGZjxoxBRUUFoqKiMGjQIKef5ORkn973woULOHjwIJ555hlMnToVl19+OWpqagLqw+WXX47//ve/Trdt374dl19+eUCvR0RE4mG8IiIiLWC8IhIPZxIS+eCrr77Cp59+ihkzZqB379746quvcO7cOVx++eVYsmQJHnzwQfTu3Rt5eXmor6/H559/joceegjTpk3DhAkTcNNNN2HFihUYMmQIzpw5g48++gg33XRTp9PXAaBHjx5ISkrC6tWr0adPH5w4cQJPPfVUQP14/PHHceutt9qL+/773//G+++/j08++SSg1yMiIrEwXhERkRYwXhGJiUlCIh8kJCRg27ZtWLlyJerq6tC/f3/84Q9/QF5eHgDg0qVLePHFF/GLX/wCycnJuPnmmwFYr4599NFHePrpp3Hvvffi3LlzSE1NxeTJk5GSkuLTe0dERODdd9/Fww8/jKysLAwZMgR//OMfMWXKFL/7cdNNN+Gll17C73//ezz88MPIyMjAG2+8EdBrERGReBiviIhICxiviMRkkCRJUrsRREREREREREREpB7WJCQiIiIiIiIiIgpzTBISERERERERERGFOSYJiYiIiIiIiIiIwhyThERERERERERERGGOSUIiIiIiIiIiIqIwxyQhERERERERERFRmGOSkIiIiIiIiIiIKMwxSUhERERERERERBTmmCQkIiIiIiIiIiIKc0wSEhERERERERERhTkmCYmIiIiIiIiIiMIck4RERERERERERERh7v8HhpV/Cn2BVkAAAAAASUVORK5CYII=", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Figure: CPU panel, 51 owned in every scenario; rentals range from 0 to 39, with none needed in 1 of 50 scenarios.\n", + "Figure: GPU panel, 5 owned in every scenario; rentals range from 0 to 9, with none needed in 4 of 50 scenarios.\n", + "Figure: TPU panel, 8 owned in every scenario; rentals range from 0 to 14, with none needed in 1 of 50 scenarios.\n" + ] + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "fig, axes = plt.subplots(1, 3, figsize=(13, 3.6))\n", + "for ax, t in zip(axes, T):\n", + " rented = [rent[k, t].X for k in range(K)]\n", + " ax.bar(range(K), [hand_buy[t]] * K, color=\"#9DB4C0\", label=\"owned\")\n", + " ax.bar(range(K), rented, bottom=[hand_buy[t]] * K, color=\"#2E4A62\", hatch=\"//\", label=\"rented\")\n", + " ax.plot(range(K), [d[t] for d in demand], \"k.\", ms=5, label=\"demand\")\n", + " ax.set_title(t.upper())\n", + " ax.set_xlabel(\"scenario\")\n", + " ax.legend(fontsize=8)\n", + "plt.tight_layout()\n", + "plt.show()\n", + "for t in T:\n", + " rented = [round(rent[k, t].X) for k in range(K)]\n", + " print(f\"Figure: {t.upper()} panel, {hand_buy[t]} owned in every scenario; rentals range from {min(rented)} to \"\n", + " f\"{max(rented)}, with none needed in {rented.count(0)} of {K} scenarios.\")" + ] + }, + { + "cell_type": "markdown", + "id": "b978c739", + "metadata": {}, + "source": [ + "## Planning for the average\n", + "\n", + "The tempting shortcut: replace the 50 scenarios by their average and solve once. Build that model\n", + "(one scenario, the mean demand), then take its purchase and cost it honestly against all 50\n", + "scenarios. A scenario's rentals, once the purchase is fixed, are just the shortfall rounded up." + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "6b36d831", + "metadata": { + "execution": { + "iopub.execute_input": "2026-10-27T13:55:51.308839Z", + "iopub.status.busy": "2026-10-27T13:55:51.308620Z", + "iopub.status.idle": "2026-10-27T13:55:51.316686Z", + "shell.execute_reply": "2026-10-27T13:55:51.316220Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "planning for the average buys {'cpu': 55, 'gpu': 0, 'tpu': 15} objective it reports 1002.00\n", + "costed against the 50 scenarios: 1039.1200 versus the stochastic plan 1000.5400\n", + "value of the stochastic solution 38.5800\n" + ] + } + ], + "source": [ + "import math\n", + "avg = {t: mean(d[t] for d in demand) for t in T}\n", + "\n", + "ma = gp.Model(\"plan for the average\", env=env)\n", + "tolerance.apply(ma)\n", + "a_buy = ma.addVars(T, vtype=GRB.INTEGER, name=\"buy\")\n", + "a_rent = ma.addVars(T, vtype=GRB.INTEGER, name=\"rent\")\n", + "ma.addConstr(gp.quicksum(machines.purchase[t] * a_buy[t] for t in T) <= BUDGET, name=\"budget\")\n", + "ma.addConstr(gp.quicksum(machines.space[t] * a_buy[t] for t in T) <= SPACE, name=\"space\")\n", + "ma.addConstrs((a_buy[t] + a_rent[t] >= avg[t] for t in T), name=\"cover\")\n", + "ma.setObjective(gp.quicksum(machines.purchase[t] * a_buy[t] + machines.cloud[t] * a_rent[t] for t in T), GRB.MINIMIZE)\n", + "ma.optimize()\n", + "avg_buy = {t: round(a_buy[t].X) for t in T}\n", + "\n", + "avg_rent = [{t: max(0, math.ceil(d[t] - avg_buy[t] - tolerance.FEASIBILITY_ATOL)) for t in T} for d in demand]\n", + "avg_cost = (sum(machines.purchase[t] * avg_buy[t] for t in T)\n", + " + sum(machines.cloud[t] * r[t] for r in avg_rent for t in T) / K)\n", + "print(\"planning for the average buys\", avg_buy, f\" objective it reports {ma.ObjVal:.2f}\")\n", + "print(f\"costed against the {K} scenarios: {avg_cost:.4f} versus the stochastic plan {hand_cost:.4f}\")\n", + "print(f\"value of the stochastic solution {avg_cost - hand_cost:.4f}\")" + ] + }, + { + "cell_type": "markdown", + "id": "8e048bf3", + "metadata": {}, + "source": [ + "The average plan's own objective and its honest cost are different numbers. Why is the honest one\n", + "higher, and which machine type does the average plan get most wrong?\n", + "\n", + "---\n", + "\n", + "# Now the streamlined version\n", + "\n", + "The package holds the same model once, written in matrix form with `addMVar` (the form IE 5301's\n", + "code uses): `serverfarm.solve_two_stage`, `serverfarm.solve_mean_value` for the shortcut costed\n", + "honestly, and `serverfarm.score_plan` for any purchase decided some other way." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "b56d73e9", + "metadata": { + "execution": { + "iopub.execute_input": "2026-10-27T13:55:51.318632Z", + "iopub.status.busy": "2026-10-27T13:55:51.318460Z", + "iopub.status.idle": "2026-10-27T13:55:51.700762Z", + "shell.execute_reply": "2026-10-27T13:55:51.700251Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "stochastic {'cpu': 51, 'gpu': 5, 'tpu': 8} 1000.5400\n", + "average plan {'cpu': 55, 'gpu': 0, 'tpu': 15} 1039.1200\n" + ] + } + ], + "source": [ + "from orteach import serverfarm as sf\n", + "from orteach.tolerance import AGREEMENT_RTOL, rel_diff\n", + "\n", + "pkg = sf.solve_two_stage(machines, demand, BUDGET, SPACE, env=env)\n", + "pkg_avg = sf.solve_mean_value(machines, demand, BUDGET, SPACE, env=env)\n", + "print(\"stochastic \", pkg.buy, f\"{pkg.expected_cost:.4f}\")\n", + "print(\"average plan \", pkg_avg.buy, f\"{pkg_avg.expected_cost:.4f}\")" + ] + }, + { + "cell_type": "markdown", + "id": "5f2943c7", + "metadata": {}, + "source": [ + "## The agreement assertion\n", + "\n", + "Two ways of writing the model, one answer. The optimal purchase is unique (`tests/test_serverfarm.py`\n", + "checks it by minimising and maximising each machine count over every optimal plan), so the purchases\n", + "are compared whole, along with both costs and the value of the stochastic solution." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "ead69700", + "metadata": { + "execution": { + "iopub.execute_input": "2026-10-27T13:55:51.702999Z", + "iopub.status.busy": "2026-10-27T13:55:51.702769Z", + "iopub.status.idle": "2026-10-27T13:55:51.708554Z", + "shell.execute_reply": "2026-10-27T13:55:51.708185Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "9 comparisons\n", + " expected cost hand 1000.5400 package 1000.5400 rel 0.00e+00\n", + " average plan, costed hand 1039.1200 package 1039.1200 rel 0.00e+00\n", + " value of the stochastic solution hand 38.5800 package 38.5800 rel 0.00e+00\n", + " buy cpu hand 51.0000 package 51.0000 rel 0.00e+00\n", + " ...\n", + "\n", + "notebook and package agree to 0.0e+00\n" + ] + } + ], + "source": [ + "checks = [(\"expected cost\", hand_cost, pkg.expected_cost),\n", + " (\"average plan, costed\", avg_cost, pkg_avg.expected_cost),\n", + " (\"value of the stochastic solution\", avg_cost - hand_cost, pkg_avg.expected_cost - pkg.expected_cost)]\n", + "for t in T:\n", + " checks.append((f\"buy {t}\", hand_buy[t], pkg.buy[t]))\n", + " checks.append((f\"average plan buys {t}\", avg_buy[t], pkg_avg.buy[t]))\n", + "\n", + "worst = max(rel_diff(h, k) for _, h, k in checks)\n", + "print(f\"{len(checks)} comparisons\")\n", + "for name, hand, packaged in checks[:4]:\n", + " print(f\" {name:34} hand {hand:10.4f} package {packaged:10.4f} rel {rel_diff(hand, packaged):.2e}\")\n", + "print(\" ...\")\n", + "assert worst < AGREEMENT_RTOL, f\"notebook and package disagree by {worst:.2e}\"\n", + "print(f\"\\nnotebook and package agree to {worst:.1e}\")" + ] + }, + { + "cell_type": "markdown", + "id": "f2f359e0", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Where to take this next\n", + "\n", + "- Raise `SPACE` to 120. Predict what the farm buys with the extra room, then check.\n", + "- Make the rentals continuous instead of integer (drop `vtype` on `rent`). Does the purchase change,\n", + " and what does the space constraint's dual now say a square metre is worth?\n", + "- The demand table was generated from a recorded seed (`serverfarm.DEMAND_SEED`). Regenerate it with\n", + " seed 7 and 40 scenarios and re-solve. Is the optimal purchase still unique?" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.13.9" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/src/orteach/serverfarm.py b/src/orteach/serverfarm.py new file mode 100644 index 0000000..be7712e --- /dev/null +++ b/src/orteach/serverfarm.py @@ -0,0 +1,130 @@ +"""A two-stage stochastic program: size a server farm now, rent cloud compute later. + +The teaching notebook ``notebooks/07_stochastic_and_newsvendor/server_farm.ipynb`` builds the +model by hand with ``addVars``, one constraint per scenario and machine type. This module builds +it once in matrix form with ``addMVar``, the form IE 5301's 2026 code uses, so the agreement +assertion also shows the two ways of writing it agree. + + first stage buy[t] machines of each type, bought before demand is seen (integer) + second stage rent[k, t] cloud units rented in scenario k to cover the shortfall (integer) + subject to purchase cost <= budget, floor space <= space, buy + rent >= demand + minimise purchase cost + mean over scenarios of cloud cost + +Both tables live in ``data/raw/``: ``server_farm_machines.csv`` (cost, space, cloud price per +type) and ``server_farm_demand.csv`` (50 scenarios), the latter generated by +``generate_demand`` from the seed recorded below. +""" +from __future__ import annotations + +import csv +import math +import os +import random +from dataclasses import dataclass, field + +import gurobipy as gp +import numpy as np + +from . import paths, tolerance + +MACHINES_CSV = "server_farm_machines.csv" # resolved by paths.table() when read +DEMAND_CSV = "server_farm_demand.csv" + +# The generating parameters, recorded so the table can be rebuilt exactly. random.Random rather +# than numpy, so the table does not depend on a numpy version's generator. With this seed and 50 +# scenarios the optimal purchase is unique (checked 2026-10-27 by minimising and maximising each +# machine count over the optimal set); seed 7 with 40 scenarios is a counterexample, with ties. +DEMAND_SEED = 20261027 +DEMAND_N = 50 +DEMAND_MEAN_SD = {"cpu": (70.0, 10.0), "gpu": (8.0, 2.0), "tpu": (15.0, 4.0)} + + +@dataclass +class Machines: + types: list + purchase: dict # type -> cost to buy one + space: dict # type -> floor space one takes + cloud: dict # type -> cost to rent one unit for the period + + +@dataclass +class Plan: + buy: dict # type -> machines bought + expected_cost: float # purchase + mean cloud bill over the scenarios + rent: list = field(repr=False) # per scenario: type -> units rented + label: str = "" + + +def generate_demand(n=DEMAND_N, seed=DEMAND_SEED): + rng = random.Random(seed) + return [{t: round(max(rng.normalvariate(*DEMAND_MEAN_SD[t]), 0.0), 2) for t in DEMAND_MEAN_SD} + for _ in range(n)] + + +def write_demand(path=None): + path = path or os.path.join(paths.SOURCE_DIR, DEMAND_CSV) # writes the clone's own table + rows = generate_demand() + with open(path, "w", newline="", encoding="utf-8") as f: + w = csv.writer(f) + w.writerow(["scenario"] + list(DEMAND_MEAN_SD)) + for k, d in enumerate(rows): + w.writerow([k + 1] + [d[t] for t in DEMAND_MEAN_SD]) + return path + + +def load_demand(path=None) -> list: + path = path or paths.table(DEMAND_CSV) + with open(path, encoding="utf-8") as f: + recs = list(csv.DictReader(f)) + return [{t: float(r[t]) for t in r if t != "scenario"} for r in recs] + + +def load_machines(path=None) -> Machines: + path = path or paths.table(MACHINES_CSV) + with open(path, encoding="utf-8") as f: + recs = list(csv.DictReader(f)) + return Machines([r["machine"] for r in recs], {r["machine"]: float(r["purchase_cost"]) for r in recs}, + {r["machine"]: float(r["space"]) for r in recs}, {r["machine"]: float(r["cloud_cost"]) for r in recs}) + + +def rent_needed(demand_k: dict, buy: dict) -> dict: + """Whole cloud units to cover one scenario's shortfall: the recourse, once buy is fixed.""" + return {t: max(0, math.ceil(demand_k[t] - buy[t] - tolerance.FEASIBILITY_ATOL)) for t in buy} + + +def score_plan(machines: Machines, demand: list, buy: dict, label="scored") -> Plan: + """A purchase decided some other way, costed against every scenario: no solver needed.""" + rent = [rent_needed(d, buy) for d in demand] + cost = sum(machines.purchase[t] * buy[t] for t in machines.types) + \ + sum(machines.cloud[t] * r[t] for r in rent for t in machines.types) / len(demand) + return Plan(dict(buy), cost, rent, label) + + +def solve_two_stage(machines: Machines, demand: list, budget: float, space: float, env=None) -> Plan: + """The stochastic program in matrix form (addMVar).""" + T, K = machines.types, len(demand) + c_buy = np.array([machines.purchase[t] for t in T]) + c_space = np.array([machines.space[t] for t in T]) + c_cloud = np.array([machines.cloud[t] for t in T]) + D = np.array([[d[t] for d in demand] for t in T]) # types x scenarios + with gp.Model(env=env) as m: + tolerance.apply(m) + x = m.addMVar(len(T), vtype=gp.GRB.INTEGER, name="buy") + y = m.addMVar((len(T), K), vtype=gp.GRB.INTEGER, name="rent") + m.addConstr(c_buy @ x <= budget, name="budget") + m.addConstr(c_space @ x <= space, name="space") + m.addConstrs((x + y[:, k] >= D[:, k] for k in range(K)), name="demand") + m.setObjective(c_buy @ x + gp.quicksum(c_cloud @ y[:, k] for k in range(K)) / K, gp.GRB.MINIMIZE) + m.optimize() + if m.Status != gp.GRB.OPTIMAL: + raise RuntimeError("server farm model ended with status %d" % m.Status) + buy = {t: int(round(v)) for t, v in zip(T, x.X)} + return score_plan(machines, demand, buy, "stochastic") + + +def solve_mean_value(machines: Machines, demand: list, budget: float, space: float, env=None) -> Plan: + """Plan for average demand as if it were certain, then cost that purchase honestly against + every scenario. The gap to solve_two_stage is the value of the stochastic solution.""" + mean = {t: sum(d[t] for d in demand) / len(demand) for t in machines.types} + plan = solve_two_stage(machines, [mean], budget, space, env=env) + return score_plan(machines, demand, plan.buy, "mean value") diff --git a/tests/test_serverfarm.py b/tests/test_serverfarm.py new file mode 100644 index 0000000..649cf6d --- /dev/null +++ b/tests/test_serverfarm.py @@ -0,0 +1,92 @@ +"""The two-stage server farm (notebooks/07_stochastic_and_newsvendor/server_farm.ipynb), pinned. + +The invariants: the recourse covers every scenario, the stochastic plan is never worse than the +mean-value plan scored the same way (VSS >= 0), and the plan the notebook compares as a whole +vector is the ONLY optimal plan, checked here rather than trusted. 3 + 3 * 50 integer +variables, inside the size-limited licence, so this runs in CI. +""" +import os +import sys + +import gurobipy as gp +import pytest + +sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname( + os.path.abspath(__file__))), "src")) + +from orteach import serverfarm as sf # noqa: E402 +from orteach.tolerance import AGREEMENT_RTOL, FEASIBILITY_ATOL, rel_diff # noqa: E402 + +BUDGET, SPACE = 1000, 100 + + +@pytest.fixture(scope="module") +def machines(): + return sf.load_machines() + + +@pytest.fixture(scope="module") +def demand(): + return sf.load_demand() + + +@pytest.fixture(scope="module") +def plan(machines, demand): + return sf.solve_two_stage(machines, demand, BUDGET, SPACE) + + +def test_the_demand_table_regenerates_exactly(demand): + assert demand == sf.generate_demand() + assert len(demand) == sf.DEMAND_N + + +def test_the_recourse_covers_every_scenario(plan, demand): + for d, r in zip(demand, plan.rent): + assert all(plan.buy[t] + r[t] >= d[t] - FEASIBILITY_ATOL for t in d) + + +def test_floor_space_binds_and_the_budget_does_not(plan, machines): + used_space = sum(machines.space[t] * plan.buy[t] for t in machines.types) + spent = sum(machines.purchase[t] * plan.buy[t] for t in machines.types) + assert used_space == SPACE and spent < BUDGET + + +def test_modelling_the_uncertainty_is_worth_something(machines, demand, plan): + mv = sf.solve_mean_value(machines, demand, BUDGET, SPACE) + assert mv.expected_cost - plan.expected_cost >= -FEASIBILITY_ATOL + assert mv.buy == {"cpu": 55, "gpu": 0, "tpu": 15} + + +def _range_over_optima(machines, demand, cost): + """Min and max of each machine count over every plan within the optimal cost.""" + T, K = machines.types, len(demand) + out = {} + for t in T: + lo_hi = [] + for sense in (gp.GRB.MINIMIZE, gp.GRB.MAXIMIZE): + with gp.Model() as m: + m.Params.OutputFlag = 0 + m.Params.MIPGap = 0 + x = m.addVars(T, vtype=gp.GRB.INTEGER) + y = m.addVars(K, T, vtype=gp.GRB.INTEGER) + m.addConstr(gp.quicksum(machines.purchase[s] * x[s] for s in T) <= BUDGET) + m.addConstr(gp.quicksum(machines.space[s] * x[s] for s in T) <= SPACE) + m.addConstrs(x[s] + y[k, s] >= demand[k][s] for k in range(K) for s in T) + m.addConstr(gp.quicksum(machines.purchase[s] * x[s] for s in T) + + gp.quicksum(machines.cloud[s] * y[k, s] for k in range(K) for s in T) / K + <= cost + FEASIBILITY_ATOL) + m.setObjective(x[t], sense) + m.optimize() + lo_hi.append(round(m.ObjVal)) + out[t] = tuple(lo_hi) + return out + + +def test_the_optimal_plan_is_unique(machines, demand, plan): + ranges = _range_over_optima(machines, demand, plan.expected_cost) + assert all(lo == hi == plan.buy[t] for t, (lo, hi) in ranges.items()), ranges + + +def test_the_numbers_the_notebook_prints(plan): + assert plan.buy == {"cpu": 51, "gpu": 5, "tpu": 8} + assert rel_diff(plan.expected_cost, 1000.54) < AGREEMENT_RTOL diff --git a/tools/seeds/seed_serverfarm.py b/tools/seeds/seed_serverfarm.py new file mode 100644 index 0000000..b7ce5cf --- /dev/null +++ b/tools/seeds/seed_serverfarm.py @@ -0,0 +1,309 @@ +"""Seed for the two-stage server farm notebook (07). Writes the notebook without outputs; execute it afterwards (README.md here).""" +import json +import os + +REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) +OUT = os.path.join(REPO, "notebooks", "07_stochastic_and_newsvendor", "server_farm.ipynb") +cells = [] + + +def md(t): + cells.append({"cell_type": "markdown", "metadata": {}, "source": t.strip("\n").splitlines(keepends=True)}) + + +def code(t): + cells.append({"cell_type": "code", "execution_count": None, "metadata": {}, "outputs": [], + "source": t.strip("\n").splitlines(keepends=True)}) + + +md(r""" +# Buy now, rent later: a two-stage server farm + +The newsvendor in this folder orders papers before it knows demand and then sells or scraps. This +is the same structure with more moving parts. You buy CPUs, GPUs and TPUs now, under a budget and a +floor-space limit. Then demand for each kind of compute arrives, and whatever your own machines +cannot cover you rent from a cloud provider at a higher price. + +The purchase is the **first stage**: one decision, no scenario index. The rentals are the **second +stage**, or recourse: one decision per scenario, made after that scenario's demand is known. +""") + +md(r""" +## Setup: where the package lives + +This notebook builds its model by hand and then checks it against `orteach`, the package in `src/`. +Run from a clone of the repository, `../../src` is right there. On Colab there is no clone until +this cell makes one, and no `gurobipy` until it installs it. Nothing here needs a secret. +""") +code(r''' +import os, subprocess, sys + +REPO_URL = "https://github.com/sear-labs/teaching-code" +REF = "v1.0.0" # the release this notebook ships in: Colab clones THIS + +try: + import google.colab # noqa: F401 - succeeds only on Colab + ON_COLAB = True +except ImportError: + ON_COLAB = False + +if ON_COLAB: + if not os.path.isdir("/content/teaching-code"): + subprocess.run(["git", "clone", "--quiet", "--depth", "1", "--branch", REF, REPO_URL, "/content/teaching-code"], check=True) + os.chdir("/content/teaching-code/notebooks/07_stochastic_and_newsvendor") + subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "gurobipy>=11,<14"], check=True) + +sys.path.insert(0, os.path.abspath(os.path.join("..", "..", "src"))) +try: + import orteach # noqa: F401 +except ImportError: + raise SystemExit("orteach not found: run this notebook from its own folder inside the repository, " + "so that ../../src exists.") +root = os.path.abspath(os.path.join("..", "..")) +print("package:", os.path.relpath(os.path.dirname(orteach.__file__), root)) +''') + +md(r""" +## Licence setup + +Nothing here needs a key: `pip install gurobipy` ships a size-limited licence, and this model (three +purchase variables and three rentals per scenario) sits well inside it. A machine with its own +licence file uses that instead, and on Colab three secrets read from the key icon in the left +sidebar are used when they are there. The environment starts silent, so no licence number lands in +an output cell. +""") +code(r''' +import gurobipy as gp +from gurobipy import GRB + +env = gp.Env(empty=True) +env.setParam("OutputFlag", 0) # start silent: the licence banner, and its licence number, stay out of the outputs +try: + from google.colab import userdata + try: + env.setParam("WLSACCESSID", userdata.get("GRB_WLSACCESSID")) + env.setParam("WLSSECRET", userdata.get("GRB_WLSSECRET")) + env.setParam("LICENSEID", int(userdata.get("GRB_LICENSEID"))) + licence = "Colab Secrets (WLS)" + except (userdata.SecretNotFoundError, userdata.NotebookAccessError): + licence = "the size-limited licence pip ships" # no key needed; see the note above +except ImportError: + licence = "local gurobi.lic" +env.start() +print("licence:", licence) +''') + +md(r""" +## The machines and the scenarios are tables + +Each machine type has a price, the floor space it takes, and the price of renting one unit of the +same compute from the cloud instead. Each of the 50 demand scenarios says how much of each kind of +compute is needed. Both are instance data, so they live in `data/raw/` and the package reads the +same files. The budget and the floor space are knobs: one number each, written out here. +""") +code(r''' +from statistics import mean +from orteach import tolerance +from orteach.serverfarm import load_machines, load_demand + +BUDGET = 1000 +SPACE = 100 + +machines = load_machines() +demand = load_demand() +T = machines.types +K = len(demand) + +print(f"budget {BUDGET}, floor space {SPACE}, {K} scenarios") +print(f"{'machine':8} {'buy':>5} {'space':>6} {'cloud':>6} demand: mean min max") +for t in T: + col = [d[t] for d in demand] + print(f"{t:8} {machines.purchase[t]:5.0f} {machines.space[t]:6.0f} {machines.cloud[t]:6.0f}" + f" {mean(col):6.1f} {min(col):6.1f} {max(col):6.1f}") +''') + +md(r""" +## The first stage + +Three integer variables, one per machine type, and two limits on them. The limits are written out +term by term, because which one binds is the first thing to look at. Predict now, before anything +is solved: will the purchase run out of money first, or out of floor space? +""") +code(r''' +m = gp.Model("server farm", env=env) +tolerance.apply(m) +buy = m.addVars(T, vtype=GRB.INTEGER, name="buy") + +budget = m.addConstr(machines.purchase["cpu"] * buy["cpu"] + machines.purchase["gpu"] * buy["gpu"] + + machines.purchase["tpu"] * buy["tpu"] <= BUDGET, name="budget") +space = m.addConstr(machines.space["cpu"] * buy["cpu"] + machines.space["gpu"] * buy["gpu"] + + machines.space["tpu"] * buy["tpu"] <= SPACE, name="space") +m.update() +print(m.getRow(budget), "<=", BUDGET) +print(m.getRow(space), "<=", SPACE) +''') + +md(r""" +## The second stage + +One rental variable per scenario and machine type, and one covering constraint for each: what you +own plus what you rent must meet that scenario's demand. The constraint is identical across +scenarios except for the demand number, which is what `addConstrs` over `k` is for. The three +machine types are written out, so you can see that each scenario has its own rentals but shares +the single `buy`. +""") +code(r''' +rent = m.addVars(K, T, vtype=GRB.INTEGER, name="rent") +m.addConstrs((buy["cpu"] + rent[k, "cpu"] >= demand[k]["cpu"] for k in range(K)), name="cover_cpu") +m.addConstrs((buy["gpu"] + rent[k, "gpu"] >= demand[k]["gpu"] for k in range(K)), name="cover_gpu") +m.addConstrs((buy["tpu"] + rent[k, "tpu"] >= demand[k]["tpu"] for k in range(K)), name="cover_tpu") +m.update() +print(m.NumVars, "variables (all integer:", m.NumIntVars, "),", m.NumConstrs, "constraints") +''') + +md(r""" +The objective is what you pay for the machines, plus the cloud bill averaged over the scenarios, +each equally likely. +""") +code(r''' +purchase_cost = gp.quicksum(machines.purchase[t] * buy[t] for t in T) +cloud_bill = gp.quicksum(machines.cloud[t] * rent[k, t] for k in range(K) for t in T) / K +m.setObjective(purchase_cost + cloud_bill, GRB.MINIMIZE) +''') + +md(r""" +Predict before solving: will the farm buy any GPUs, given that renting one is only a little dearer +than owning one? +""") +code(r''' +m.optimize() +hand_buy = {t: round(buy[t].X) for t in T} +hand_cost = m.ObjVal +print("buy", hand_buy, f" expected cost {hand_cost:.4f} MIP gap {m.MIPGap:.1e}") +print(f"money spent {purchase_cost.getValue():.0f} of {BUDGET} floor space used " + f"{sum(machines.space[t] * hand_buy[t] for t in T):.0f} of {SPACE}") +''') + +md(r""" +Was your prediction about the binding limit right? If one limit is slack, what is the other one +costing you, and how would you find out? + +## The recourse + +The purchase is the same in every scenario; the rentals are not. Look at both together. +""") +code(r''' +import matplotlib.pyplot as plt + +fig, axes = plt.subplots(1, 3, figsize=(13, 3.6)) +for ax, t in zip(axes, T): + rented = [rent[k, t].X for k in range(K)] + ax.bar(range(K), [hand_buy[t]] * K, color="#9DB4C0", label="owned") + ax.bar(range(K), rented, bottom=[hand_buy[t]] * K, color="#2E4A62", hatch="//", label="rented") + ax.plot(range(K), [d[t] for d in demand], "k.", ms=5, label="demand") + ax.set_title(t.upper()) + ax.set_xlabel("scenario") + ax.legend(fontsize=8) +plt.tight_layout() +plt.show() +for t in T: + rented = [round(rent[k, t].X) for k in range(K)] + print(f"Figure: {t.upper()} panel, {hand_buy[t]} owned in every scenario; rentals range from {min(rented)} to " + f"{max(rented)}, with none needed in {rented.count(0)} of {K} scenarios.") +''') + +md(r""" +## Planning for the average + +The tempting shortcut: replace the 50 scenarios by their average and solve once. Build that model +(one scenario, the mean demand), then take its purchase and cost it honestly against all 50 +scenarios. A scenario's rentals, once the purchase is fixed, are just the shortfall rounded up. +""") +code(r''' +import math +avg = {t: mean(d[t] for d in demand) for t in T} + +ma = gp.Model("plan for the average", env=env) +tolerance.apply(ma) +a_buy = ma.addVars(T, vtype=GRB.INTEGER, name="buy") +a_rent = ma.addVars(T, vtype=GRB.INTEGER, name="rent") +ma.addConstr(gp.quicksum(machines.purchase[t] * a_buy[t] for t in T) <= BUDGET, name="budget") +ma.addConstr(gp.quicksum(machines.space[t] * a_buy[t] for t in T) <= SPACE, name="space") +ma.addConstrs((a_buy[t] + a_rent[t] >= avg[t] for t in T), name="cover") +ma.setObjective(gp.quicksum(machines.purchase[t] * a_buy[t] + machines.cloud[t] * a_rent[t] for t in T), GRB.MINIMIZE) +ma.optimize() +avg_buy = {t: round(a_buy[t].X) for t in T} + +avg_rent = [{t: max(0, math.ceil(d[t] - avg_buy[t] - tolerance.FEASIBILITY_ATOL)) for t in T} for d in demand] +avg_cost = (sum(machines.purchase[t] * avg_buy[t] for t in T) + + sum(machines.cloud[t] * r[t] for r in avg_rent for t in T) / K) +print("planning for the average buys", avg_buy, f" objective it reports {ma.ObjVal:.2f}") +print(f"costed against the {K} scenarios: {avg_cost:.4f} versus the stochastic plan {hand_cost:.4f}") +print(f"value of the stochastic solution {avg_cost - hand_cost:.4f}") +''') + +md(r""" +The average plan's own objective and its honest cost are different numbers. Why is the honest one +higher, and which machine type does the average plan get most wrong? + +--- + +# Now the streamlined version + +The package holds the same model once, written in matrix form with `addMVar` (the form IE 5301's +code uses): `serverfarm.solve_two_stage`, `serverfarm.solve_mean_value` for the shortcut costed +honestly, and `serverfarm.score_plan` for any purchase decided some other way. +""") +code(r''' +from orteach import serverfarm as sf +from orteach.tolerance import AGREEMENT_RTOL, rel_diff + +pkg = sf.solve_two_stage(machines, demand, BUDGET, SPACE, env=env) +pkg_avg = sf.solve_mean_value(machines, demand, BUDGET, SPACE, env=env) +print("stochastic ", pkg.buy, f"{pkg.expected_cost:.4f}") +print("average plan ", pkg_avg.buy, f"{pkg_avg.expected_cost:.4f}") +''') + +md(r""" +## The agreement assertion + +Two ways of writing the model, one answer. The optimal purchase is unique (`tests/test_serverfarm.py` +checks it by minimising and maximising each machine count over every optimal plan), so the purchases +are compared whole, along with both costs and the value of the stochastic solution. +""") +code(r''' +checks = [("expected cost", hand_cost, pkg.expected_cost), + ("average plan, costed", avg_cost, pkg_avg.expected_cost), + ("value of the stochastic solution", avg_cost - hand_cost, pkg_avg.expected_cost - pkg.expected_cost)] +for t in T: + checks.append((f"buy {t}", hand_buy[t], pkg.buy[t])) + checks.append((f"average plan buys {t}", avg_buy[t], pkg_avg.buy[t])) + +worst = max(rel_diff(h, k) for _, h, k in checks) +print(f"{len(checks)} comparisons") +for name, hand, packaged in checks[:4]: + print(f" {name:34} hand {hand:10.4f} package {packaged:10.4f} rel {rel_diff(hand, packaged):.2e}") +print(" ...") +assert worst < AGREEMENT_RTOL, f"notebook and package disagree by {worst:.2e}" +print(f"\nnotebook and package agree to {worst:.1e}") +''') + +md(r""" +--- + +## Where to take this next + +- Raise `SPACE` to 120. Predict what the farm buys with the extra room, then check. +- Make the rentals continuous instead of integer (drop `vtype` on `rent`). Does the purchase change, + and what does the space constraint's dual now say a square metre is worth? +- The demand table was generated from a recorded seed (`serverfarm.DEMAND_SEED`). Regenerate it with + seed 7 and 40 scenarios and re-solve. Is the optimal purchase still unique? +""") + +nb = {"cells": cells, "metadata": {"kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"}, + "language_info": {"name": "python", "version": "3.13"}}, "nbformat": 4, "nbformat_minor": 5} +os.makedirs(os.path.dirname(OUT), exist_ok=True) +with open(OUT, "w", encoding="utf-8") as f: + json.dump(nb, f, indent=1, ensure_ascii=False) + f.write("\n") +print("wrote %s (%d cells)" % (OUT, len(cells)))