From b11f6336c698da69c8d8d490018a228a4a0090c1 Mon Sep 17 00:00:00 2001 From: "Erick C. Jones Jr." <44578073+yamierick@users.noreply.github.com> Date: Tue, 27 Oct 2026 08:43:00 -0500 Subject: [PATCH] Close the standard's remaining gaps: tables, imports, alt text, the release pin Four things the code standard asks for that this library did not do, each now enforced by something that fails rather than by a README line. 1. Tables reachable from anywhere (Part 4). All 14 modules found data/raw by walking up from __file__: right in a clone, wrong after `pip install git+...`, which ships no data/. Several did it inside a default argument, frozen at import time. orteach.paths.table() is now the one resolver, local first: an explicit data_dir=, then $ORTEACH_DATA (both refused if the file is missing, never skipped), then data/raw beside the code, then under the cwd, then the raw URL at the release TAG, fetched once and cached. Loaders take path=None and resolve at call time; writers write into the clone's own data/raw. tests/test_paths.py pins each rule by name. Watched to fail: a named location falling through failed two tests; the URL ahead of the local copy failed one. 2. Every import declared (Part 6). tests/test_dependencies.py parses (never imports) every import in src/, notebooks/ and tests/ and compares with pyproject.toml, which it reads rather than restates. Unknown distributions fail instead of being guessed at. tomli is declared for 3.10 instead of skipped. Watched to fail on an injected `import yaml` in a module and, separately, in a notebook. 3. A text alternative for every figure (Part 3, accessibility; WCAG 2.1 AA from 2027-04-26). The six committed figures (08 x3, 14 x3) had none. Each cell now prints a "Figure:" line saying what the image shows, computed from the same data; the dart scatter separates inside from outside by marker as well as colour. check_notebooks.py refuses any image cell without one. Watched to fail: it flagged exactly those six cells before the fix. 4. Notebooks clone the release, not main (Part 4, Part 5 "tag what you hand out"). Every setup cell gains REF and clones --branch REF. REF must equal orteach.paths.TAG, the tag the package fetches tables from; check_notebooks.py reads TAG from source and refuses a mismatch. Watched to fail on the 11 seeded notebooks before they were regenerated. README "Cutting a release" has the steps. TAG is v1.0.0, which this PR's merge commit is meant to become. All 17 notebooks re-executed. Their outputs match HEAD except the new Figure lines, a branch-and-bound node count in 06's time-limited run (the same bound; node counts under a time limit vary), and -0.0 printed as 0.0 in pooling. No prose number moved; the checker confirms. Gate: 191 passed (base); 21 in the energy venv with ORTEACH_REQUIRE_PYPSA=1; 17 notebooks and 11 seeds clean; ruff clean. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 10 +- README.md | 26 +- notebooks/01_lp_formulation/diet.ipynb | 225 +-- .../01_lp_formulation/goal_programming.ipynb | 211 +-- .../primal_and_dual.ipynb | 223 +-- .../assignment.ipynb | 99 +- .../transportation.ipynb | 155 +- .../facility_location.ipynb | 139 +- .../curve_fit_lifting.ipynb | 165 +-- .../06_nonlinear_and_convex/pooling.ipynb | 165 +-- .../newsvendor.ipynb | 179 +-- .../monte_carlo.ipynb | 167 ++- .../markov_and_queues.ipynb | 175 +-- notebooks/10_game_theory/zero_sum_game.ipynb | 139 +- .../capital_budgeting.ipynb | 115 +- .../dispatch_to_pypsa.ipynb | 1253 +++++++++-------- .../sourcing_and_resilience.ipynb | 187 +-- .../distributions_and_clt.ipynb | 245 ++-- .../inference_and_regression.ipynb | 175 +-- pyproject.toml | 3 + src/orteach/assignment.py | 7 +- src/orteach/capital_budgeting.py | 9 +- src/orteach/data.py | 11 +- src/orteach/diet.py | 8 +- src/orteach/duality.py | 6 +- src/orteach/energy.py | 16 +- src/orteach/facility_location.py | 10 +- src/orteach/games.py | 6 +- src/orteach/goal_programming.py | 6 +- src/orteach/inference.py | 13 +- src/orteach/markov.py | 6 +- src/orteach/nonconvex.py | 10 +- src/orteach/paths.py | 69 + src/orteach/sourcing.py | 6 +- src/orteach/transportation.py | 8 +- tests/test_dependencies.py | 99 ++ tests/test_paths.py | 73 + tools/check_notebooks.py | 23 + tools/seeds/seed_curvefit.py | 3 +- tools/seeds/seed_diet.py | 3 +- tools/seeds/seed_distributions.py | 10 +- tools/seeds/seed_duality.py | 3 +- tools/seeds/seed_energy.py | 3 +- tools/seeds/seed_games.py | 3 +- tools/seeds/seed_goal.py | 3 +- tools/seeds/seed_inference.py | 3 +- tools/seeds/seed_markov.py | 3 +- tools/seeds/seed_pooling.py | 3 +- tools/seeds/seed_sourcing.py | 3 +- 49 files changed, 2421 insertions(+), 2061 deletions(-) create mode 100644 src/orteach/paths.py create mode 100644 tests/test_dependencies.py create mode 100644 tests/test_paths.py diff --git a/CLAUDE.md b/CLAUDE.md index 473a2ce..040b23a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -154,9 +154,15 @@ with a status line per finding, and the list of what must change before the firs **Conventions this library settled, beyond the standard:** -- Every notebook opens with the same setup cell (`REPO_URL`, clone-or-`../../src`) and, when it +- Every notebook opens with the same setup cell (`REPO_URL`, `REF`, clone-or-`../../src`) and, when it solves, the same licence cell (silent `gp.Env`, Colab Secrets, `NotebookAccessError` caught). - Patch them everywhere or nowhere. + Patch them everywhere or nowhere. `REF` is the release tag Colab clones and must equal + `orteach.paths.TAG`, the tag the package fetches tables from; the checker enforces it, and + README "Cutting a release" has the steps. +- Instance tables are found only through `orteach.paths.table()`. Never build a path to + `data/raw` from `__file__` in a module: it is right in a clone and wrong after `pip install`. +- A cell that draws a figure also prints a `Figure:` line saying what it shows, computed from the + same data. The checker enforces it. - Tolerances are named in `orteach.tolerance` and nowhere else; every hand-built Gurobi model calls `tolerance.apply(m)`. - When an optimum is not unique, the agreement assertion compares what every optimum shares and the diff --git a/README.md b/README.md index 18bc9bd..e1c5560 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,11 @@ to be public. - **`data/raw/`** — instance *tables*: many entries, indexed by the model's own sets, named nowhere in the prose. Both the notebook and the package read them from here. A scalar carrying a concept — a rate, a count, a breakpoint — is a **knob** and stays written out inline in the cell. + The package finds them through one function, `orteach.paths.table()`, local copy first: an + explicit `data_dir=`, then `$ORTEACH_DATA`, then `data/raw` beside the code (a clone), then + `data/raw` under the working directory, and only then the release's raw URL, fetched once and + cached. The first two are refused if the file is missing, never skipped, so a reader who points + at an edited copy can never silently get the published numbers instead. - **`tests/`** — at minimum a smoke test asserting the domain invariants: totals that must balance, quantities that cannot go negative. @@ -174,7 +179,12 @@ The checker refuses: an unexecuted notebook or an error output, an orphan code c named lambda before the "Now the streamlined version" heading, no predict-before-you-run prompt, no agreement assertion, a tolerance literal used as a threshold, a seed set but not printed, a cell too long to read without scrolling, a number in the prose that no output produced, a licence banner in -an output, and a notebook without the Colab setup cell. +an output, a notebook without the Colab setup cell, a setup cell that does not clone the release +`orteach.paths.TAG` names, and a figure whose cell prints no `Figure:` line saying what it shows +(its text alternative, written in the same cell as the plot). + +`tests/test_dependencies.py` parses every import in `src/`, `notebooks/` and `tests/` and fails on +anything `pyproject.toml` does not declare. `tests/test_paths.py` pins the table resolver's order. Eleven of the notebooks are written by a script in `tools/seeds/`, which is where to edit them: change the seed, run it, then execute the notebook in place so it ships with outputs. `tools/check_seeds.py` @@ -184,6 +194,20 @@ whatever was fixed since. To re-execute a notebook: `jupyter nbconvert --to notebook --execute --inplace ` (for `12`, add `--ExecutePreprocessor.kernel_name=orteach-energy`). +### Cutting a release + +A notebook handed to students must not change under them, so on Colab each one clones a release +tag, not `main`, and the package fetches tables from the same tag. To cut the next one: + +1. Set `TAG` in `src/orteach/paths.py` and `REF` in every setup cell (the eleven seeds and the six + notebooks edited in place) to the new tag. `check_notebooks.py` refuses any setup cell that + disagrees with `TAG`. +2. Re-execute, merge through a pull request with CI green. +3. Tag the merge commit, annotated, and check it peels to that commit: + `git tag -a vX.Y.Z -m "..."`, `git push origin vX.Y.Z`, + `git ls-remote origin "refs/tags/vX.Y.Z^{}"`. No GitHub Release unless a Zenodo deposit is + wanted, which is Jones's decision. + Every notebook has been read by a fresh-context reviewer against Parts 3, 4 and 10. The first nine reviews are folded into commit `9054550`, the probability pair into `3084cf3`, and `09`/`10`/`12` into `33d47b6`. **`REVIEW_QUEUE.md` holds the two most recent reviews verbatim with a status line per diff --git a/notebooks/01_lp_formulation/diet.ipynb b/notebooks/01_lp_formulation/diet.ipynb index 1c564a9..d3b4932 100644 --- a/notebooks/01_lp_formulation/diet.ipynb +++ b/notebooks/01_lp_formulation/diet.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "33e629c0", + "id": "5f6a02e1", "metadata": {}, "source": [ "# The diet problem: the first LP, and the direction of an inequality\n", @@ -19,7 +19,7 @@ }, { "cell_type": "markdown", - "id": "56c43dd7", + "id": "389be82d", "metadata": {}, "source": [ "## Setup: where the package lives\n", @@ -32,13 +32,13 @@ { "cell_type": "code", "execution_count": 1, - "id": "5dc78e07", + "id": "af06e808", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.419704Z", - "iopub.status.busy": "2026-09-06T03:26:38.419527Z", - "iopub.status.idle": "2026-09-06T03:26:38.433170Z", - "shell.execute_reply": "2026-09-06T03:26:38.432649Z" + "iopub.execute_input": "2026-10-27T13:37:22.952042Z", + "iopub.status.busy": "2026-10-27T13:37:22.951771Z", + "iopub.status.idle": "2026-10-27T13:37:22.969415Z", + "shell.execute_reply": "2026-10-27T13:37:22.968796Z" } }, "outputs": [ @@ -54,6 +54,7 @@ "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", @@ -63,7 +64,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/01_lp_formulation\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -79,7 +80,7 @@ }, { "cell_type": "markdown", - "id": "d932eb96", + "id": "df14144d", "metadata": {}, "source": [ "## Licence setup\n", @@ -93,13 +94,13 @@ { "cell_type": "code", "execution_count": 2, - "id": "e98c5344", + "id": "45ad70ab", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.435304Z", - "iopub.status.busy": "2026-09-06T03:26:38.435129Z", - "iopub.status.idle": "2026-09-06T03:26:38.492802Z", - "shell.execute_reply": "2026-09-06T03:26:38.492247Z" + "iopub.execute_input": "2026-10-27T13:37:22.972130Z", + "iopub.status.busy": "2026-10-27T13:37:22.971869Z", + "iopub.status.idle": "2026-10-27T13:37:23.061542Z", + "shell.execute_reply": "2026-10-27T13:37:23.060950Z" } }, "outputs": [ @@ -134,7 +135,7 @@ }, { "cell_type": "markdown", - "id": "908ed395", + "id": "f0c5abac", "metadata": {}, "source": [ "## The instance is a table\n", @@ -150,13 +151,13 @@ { "cell_type": "code", "execution_count": 3, - "id": "45a19115", + "id": "ce5aced3", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.495841Z", - "iopub.status.busy": "2026-09-06T03:26:38.495148Z", - "iopub.status.idle": "2026-09-06T03:26:38.523465Z", - "shell.execute_reply": "2026-09-06T03:26:38.522866Z" + "iopub.execute_input": "2026-10-27T13:37:23.064226Z", + "iopub.status.busy": "2026-10-27T13:37:23.063967Z", + "iopub.status.idle": "2026-10-27T13:37:23.084389Z", + "shell.execute_reply": "2026-10-27T13:37:23.083756Z" } }, "outputs": [ @@ -201,7 +202,7 @@ }, { "cell_type": "markdown", - "id": "9242f2c3", + "id": "977c91e0", "metadata": {}, "source": [ "## Predict before building anything\n", @@ -212,7 +213,7 @@ }, { "cell_type": "markdown", - "id": "574303e1", + "id": "40fbe18d", "metadata": {}, "source": [ "## The model, and one variable per food\n", @@ -223,13 +224,13 @@ { "cell_type": "code", "execution_count": 4, - "id": "348cedb6", + "id": "4378cac8", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.526065Z", - "iopub.status.busy": "2026-09-06T03:26:38.525756Z", - "iopub.status.idle": "2026-09-06T03:26:38.532163Z", - "shell.execute_reply": "2026-09-06T03:26:38.531274Z" + "iopub.execute_input": "2026-10-27T13:37:23.087381Z", + "iopub.status.busy": "2026-10-27T13:37:23.087052Z", + "iopub.status.idle": "2026-10-27T13:37:23.099663Z", + "shell.execute_reply": "2026-10-27T13:37:23.098976Z" } }, "outputs": [ @@ -251,7 +252,7 @@ }, { "cell_type": "markdown", - "id": "a3679a58", + "id": "2e62de33", "metadata": {}, "source": [ "## The objective is the grocery bill\n", @@ -262,13 +263,13 @@ { "cell_type": "code", "execution_count": 5, - "id": "6c3f1563", + "id": "7431c183", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.534639Z", - "iopub.status.busy": "2026-09-06T03:26:38.534454Z", - "iopub.status.idle": "2026-09-06T03:26:38.540540Z", - "shell.execute_reply": "2026-09-06T03:26:38.539793Z" + "iopub.execute_input": "2026-10-27T13:37:23.102401Z", + "iopub.status.busy": "2026-10-27T13:37:23.102170Z", + "iopub.status.idle": "2026-10-27T13:37:23.113546Z", + "shell.execute_reply": "2026-10-27T13:37:23.112759Z" } }, "outputs": [ @@ -288,7 +289,7 @@ }, { "cell_type": "markdown", - "id": "e5386da2", + "id": "43c21190", "metadata": {}, "source": [ "## One constraint per nutrient — written out once\n", @@ -301,13 +302,13 @@ { "cell_type": "code", "execution_count": 6, - "id": "f1aee587", + "id": "5cdb85d8", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.543339Z", - "iopub.status.busy": "2026-09-06T03:26:38.543159Z", - "iopub.status.idle": "2026-09-06T03:26:38.547714Z", - "shell.execute_reply": "2026-09-06T03:26:38.547236Z" + "iopub.execute_input": "2026-10-27T13:37:23.116080Z", + "iopub.status.busy": "2026-10-27T13:37:23.115859Z", + "iopub.status.idle": "2026-10-27T13:37:23.123755Z", + "shell.execute_reply": "2026-10-27T13:37:23.123132Z" } }, "outputs": [ @@ -329,7 +330,7 @@ }, { "cell_type": "markdown", - "id": "eb7d25b7", + "id": "de1015da", "metadata": {}, "source": [ "The other three rows have identical shape, so a loop is honest here — it repeats a step you have\n", @@ -339,13 +340,13 @@ { "cell_type": "code", "execution_count": 7, - "id": "aee8b866", + "id": "e9a46916", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.549722Z", - "iopub.status.busy": "2026-09-06T03:26:38.549516Z", - "iopub.status.idle": "2026-09-06T03:26:38.553973Z", - "shell.execute_reply": "2026-09-06T03:26:38.553546Z" + "iopub.execute_input": "2026-10-27T13:37:23.126269Z", + "iopub.status.busy": "2026-10-27T13:37:23.126010Z", + "iopub.status.idle": "2026-10-27T13:37:23.132075Z", + "shell.execute_reply": "2026-10-27T13:37:23.131558Z" } }, "outputs": [ @@ -369,7 +370,7 @@ }, { "cell_type": "markdown", - "id": "a6176b63", + "id": "19751f54", "metadata": {}, "source": [ "## Read back what you built\n", @@ -381,13 +382,13 @@ { "cell_type": "code", "execution_count": 8, - "id": "9e37c557", + "id": "6d8e509c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.555954Z", - "iopub.status.busy": "2026-09-06T03:26:38.555785Z", - "iopub.status.idle": "2026-09-06T03:26:38.561487Z", - "shell.execute_reply": "2026-09-06T03:26:38.560886Z" + "iopub.execute_input": "2026-10-27T13:37:23.134684Z", + "iopub.status.busy": "2026-10-27T13:37:23.134419Z", + "iopub.status.idle": "2026-10-27T13:37:23.139212Z", + "shell.execute_reply": "2026-10-27T13:37:23.138617Z" } }, "outputs": [ @@ -409,7 +410,7 @@ }, { "cell_type": "markdown", - "id": "bc984836", + "id": "42e108f4", "metadata": {}, "source": [ "## Two side conditions, as bounds rather than rows\n", @@ -422,13 +423,13 @@ { "cell_type": "code", "execution_count": 9, - "id": "030ad19a", + "id": "b33532f0", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.564269Z", - "iopub.status.busy": "2026-09-06T03:26:38.564072Z", - "iopub.status.idle": "2026-09-06T03:26:38.568370Z", - "shell.execute_reply": "2026-09-06T03:26:38.567807Z" + "iopub.execute_input": "2026-10-27T13:37:23.141981Z", + "iopub.status.busy": "2026-10-27T13:37:23.141624Z", + "iopub.status.idle": "2026-10-27T13:37:23.146538Z", + "shell.execute_reply": "2026-10-27T13:37:23.145981Z" } }, "outputs": [ @@ -452,7 +453,7 @@ }, { "cell_type": "markdown", - "id": "e9363272", + "id": "09201ed8", "metadata": {}, "source": [ "## Solve\n", @@ -464,13 +465,13 @@ { "cell_type": "code", "execution_count": 10, - "id": "3e88e237", + "id": "53344183", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.570715Z", - "iopub.status.busy": "2026-09-06T03:26:38.570473Z", - "iopub.status.idle": "2026-09-06T03:26:38.575779Z", - "shell.execute_reply": "2026-09-06T03:26:38.575295Z" + "iopub.execute_input": "2026-10-27T13:37:23.149129Z", + "iopub.status.busy": "2026-10-27T13:37:23.148907Z", + "iopub.status.idle": "2026-10-27T13:37:23.169451Z", + "shell.execute_reply": "2026-10-27T13:37:23.168688Z" } }, "outputs": [ @@ -490,7 +491,7 @@ }, { "cell_type": "markdown", - "id": "eefe04af", + "id": "ca5e107c", "metadata": {}, "source": [ "## The basket, and which minimums bind\n", @@ -502,13 +503,13 @@ { "cell_type": "code", "execution_count": 11, - "id": "6f19e102", + "id": "5b8e41f0", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.577848Z", - "iopub.status.busy": "2026-09-06T03:26:38.577678Z", - "iopub.status.idle": "2026-09-06T03:26:38.582939Z", - "shell.execute_reply": "2026-09-06T03:26:38.582327Z" + "iopub.execute_input": "2026-10-27T13:37:23.172061Z", + "iopub.status.busy": "2026-10-27T13:37:23.171830Z", + "iopub.status.idle": "2026-10-27T13:37:23.178259Z", + "shell.execute_reply": "2026-10-27T13:37:23.177705Z" } }, "outputs": [ @@ -544,7 +545,7 @@ }, { "cell_type": "markdown", - "id": "60c24b9b", + "id": "e218bc3c", "metadata": {}, "source": [ "Compare with what you wrote down. Which foods surprised you, and does the binding column explain them?\n", @@ -561,13 +562,13 @@ { "cell_type": "code", "execution_count": 12, - "id": "08f29cc6", + "id": "882b1d09", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.585018Z", - "iopub.status.busy": "2026-09-06T03:26:38.584846Z", - "iopub.status.idle": "2026-09-06T03:26:38.590719Z", - "shell.execute_reply": "2026-09-06T03:26:38.590256Z" + "iopub.execute_input": "2026-10-27T13:37:23.180896Z", + "iopub.status.busy": "2026-10-27T13:37:23.180551Z", + "iopub.status.idle": "2026-10-27T13:37:23.188229Z", + "shell.execute_reply": "2026-10-27T13:37:23.187710Z" } }, "outputs": [ @@ -601,7 +602,7 @@ }, { "cell_type": "markdown", - "id": "6b14937d", + "id": "52047fab", "metadata": {}, "source": [ "Before you run it: will this bill be higher or lower than the one above, and why? The feasible\n", @@ -611,13 +612,13 @@ { "cell_type": "code", "execution_count": 13, - "id": "f70e3f71", + "id": "9244192d", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.592671Z", - "iopub.status.busy": "2026-09-06T03:26:38.592505Z", - "iopub.status.idle": "2026-09-06T03:26:38.597805Z", - "shell.execute_reply": "2026-09-06T03:26:38.597262Z" + "iopub.execute_input": "2026-10-27T13:37:23.191043Z", + "iopub.status.busy": "2026-10-27T13:37:23.190794Z", + "iopub.status.idle": "2026-10-27T13:37:23.197764Z", + "shell.execute_reply": "2026-10-27T13:37:23.197261Z" } }, "outputs": [ @@ -659,7 +660,7 @@ }, { "cell_type": "markdown", - "id": "6daaf909", + "id": "f38d3b7d", "metadata": {}, "source": [ "Look at the protein line. The model is sitting exactly on 10 — from which side? What question did the\n", @@ -674,13 +675,13 @@ { "cell_type": "code", "execution_count": 14, - "id": "835b831d", + "id": "1ff9cdf5", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.599884Z", - "iopub.status.busy": "2026-09-06T03:26:38.599708Z", - "iopub.status.idle": "2026-09-06T03:26:38.603783Z", - "shell.execute_reply": "2026-09-06T03:26:38.603297Z" + "iopub.execute_input": "2026-10-27T13:37:23.200303Z", + "iopub.status.busy": "2026-10-27T13:37:23.200082Z", + "iopub.status.idle": "2026-10-27T13:37:23.204872Z", + "shell.execute_reply": "2026-10-27T13:37:23.204066Z" } }, "outputs": [ @@ -702,7 +703,7 @@ }, { "cell_type": "markdown", - "id": "88fc67ef", + "id": "09c19dcd", "metadata": {}, "source": [ "---\n", @@ -717,13 +718,13 @@ { "cell_type": "code", "execution_count": 15, - "id": "675a6f74", + "id": "b05c3367", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.605746Z", - "iopub.status.busy": "2026-09-06T03:26:38.605538Z", - "iopub.status.idle": "2026-09-06T03:26:38.625346Z", - "shell.execute_reply": "2026-09-06T03:26:38.624827Z" + "iopub.execute_input": "2026-10-27T13:37:23.207367Z", + "iopub.status.busy": "2026-10-27T13:37:23.207134Z", + "iopub.status.idle": "2026-10-27T13:37:23.215453Z", + "shell.execute_reply": "2026-10-27T13:37:23.214789Z" } }, "outputs": [ @@ -751,7 +752,7 @@ }, { "cell_type": "markdown", - "id": "1145bec5", + "id": "5c64fc54", "metadata": {}, "source": [ "Same three steps — variables, objective, one `>=` row per nutrient — with no side bounds this time.\n", @@ -761,13 +762,13 @@ { "cell_type": "code", "execution_count": 16, - "id": "dcb45444", + "id": "9b520242", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.627471Z", - "iopub.status.busy": "2026-09-06T03:26:38.627271Z", - "iopub.status.idle": "2026-09-06T03:26:38.633143Z", - "shell.execute_reply": "2026-09-06T03:26:38.632712Z" + "iopub.execute_input": "2026-10-27T13:37:23.217986Z", + "iopub.status.busy": "2026-10-27T13:37:23.217758Z", + "iopub.status.idle": "2026-10-27T13:37:23.225292Z", + "shell.execute_reply": "2026-10-27T13:37:23.224779Z" } }, "outputs": [ @@ -799,7 +800,7 @@ }, { "cell_type": "markdown", - "id": "6178518c", + "id": "2c9a5ba6", "metadata": {}, "source": [ "---\n", @@ -814,13 +815,13 @@ { "cell_type": "code", "execution_count": 17, - "id": "a61eaade", + "id": "4ee518aa", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.635404Z", - "iopub.status.busy": "2026-09-06T03:26:38.635219Z", - "iopub.status.idle": "2026-09-06T03:26:38.641385Z", - "shell.execute_reply": "2026-09-06T03:26:38.640899Z" + "iopub.execute_input": "2026-10-27T13:37:23.227942Z", + "iopub.status.busy": "2026-10-27T13:37:23.227700Z", + "iopub.status.idle": "2026-10-27T13:37:23.235585Z", + "shell.execute_reply": "2026-10-27T13:37:23.235061Z" } }, "outputs": [ @@ -848,7 +849,7 @@ }, { "cell_type": "markdown", - "id": "d025b915", + "id": "14bef5c0", "metadata": {}, "source": [ "## The agreement assertion\n", @@ -861,13 +862,13 @@ { "cell_type": "code", "execution_count": 18, - "id": "6bb595ae", + "id": "5a470eab", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:38.643330Z", - "iopub.status.busy": "2026-09-06T03:26:38.643160Z", - "iopub.status.idle": "2026-09-06T03:26:38.648309Z", - "shell.execute_reply": "2026-09-06T03:26:38.647829Z" + "iopub.execute_input": "2026-10-27T13:37:23.238174Z", + "iopub.status.busy": "2026-10-27T13:37:23.237932Z", + "iopub.status.idle": "2026-10-27T13:37:23.245545Z", + "shell.execute_reply": "2026-10-27T13:37:23.244945Z" } }, "outputs": [ @@ -906,7 +907,7 @@ }, { "cell_type": "markdown", - "id": "1797769e", + "id": "88c819cb", "metadata": {}, "source": [ "---\n", diff --git a/notebooks/01_lp_formulation/goal_programming.ipynb b/notebooks/01_lp_formulation/goal_programming.ipynb index 3e88fd8..70ab33f 100644 --- a/notebooks/01_lp_formulation/goal_programming.ipynb +++ b/notebooks/01_lp_formulation/goal_programming.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "ca6c11b3", + "id": "fda94fce", "metadata": {}, "source": [ "# Goal programming: when the targets cannot all be met\n", @@ -22,7 +22,7 @@ }, { "cell_type": "markdown", - "id": "ff79b0ca", + "id": "756062c5", "metadata": {}, "source": [ "## Setup: where the package lives\n", @@ -35,13 +35,13 @@ { "cell_type": "code", "execution_count": 1, - "id": "eb1b1412", + "id": "c086c535", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.617124Z", - "iopub.status.busy": "2026-09-06T03:26:41.616936Z", - "iopub.status.idle": "2026-09-06T03:26:41.632161Z", - "shell.execute_reply": "2026-09-06T03:26:41.631633Z" + "iopub.execute_input": "2026-10-27T13:37:34.791033Z", + "iopub.status.busy": "2026-10-27T13:37:34.790826Z", + "iopub.status.idle": "2026-10-27T13:37:34.804099Z", + "shell.execute_reply": "2026-10-27T13:37:34.803605Z" } }, "outputs": [ @@ -57,6 +57,7 @@ "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", @@ -66,7 +67,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/01_lp_formulation\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -82,7 +83,7 @@ }, { "cell_type": "markdown", - "id": "ce136d2c", + "id": "9b91b2aa", "metadata": {}, "source": [ "## Licence setup\n", @@ -96,13 +97,13 @@ { "cell_type": "code", "execution_count": 2, - "id": "06755898", + "id": "a1462c0b", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.634514Z", - "iopub.status.busy": "2026-09-06T03:26:41.634311Z", - "iopub.status.idle": "2026-09-06T03:26:41.694735Z", - "shell.execute_reply": "2026-09-06T03:26:41.694224Z" + "iopub.execute_input": "2026-10-27T13:37:34.806295Z", + "iopub.status.busy": "2026-10-27T13:37:34.806092Z", + "iopub.status.idle": "2026-10-27T13:37:34.858004Z", + "shell.execute_reply": "2026-10-27T13:37:34.857469Z" } }, "outputs": [ @@ -137,7 +138,7 @@ }, { "cell_type": "markdown", - "id": "7dbee656", + "id": "8f54e2cd", "metadata": {}, "source": [ "## The table, and the knobs\n", @@ -153,13 +154,13 @@ { "cell_type": "code", "execution_count": 3, - "id": "f5a93f28", + "id": "4a5ffccf", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.696941Z", - "iopub.status.busy": "2026-09-06T03:26:41.696719Z", - "iopub.status.idle": "2026-09-06T03:26:41.718149Z", - "shell.execute_reply": "2026-09-06T03:26:41.717669Z" + "iopub.execute_input": "2026-10-27T13:37:34.860489Z", + "iopub.status.busy": "2026-10-27T13:37:34.860286Z", + "iopub.status.idle": "2026-10-27T13:37:34.875720Z", + "shell.execute_reply": "2026-10-27T13:37:34.875197Z" } }, "outputs": [ @@ -200,7 +201,7 @@ }, { "cell_type": "markdown", - "id": "ce51d281", + "id": "a21979b2", "metadata": {}, "source": [ "## First, the plain LP\n", @@ -212,13 +213,13 @@ { "cell_type": "code", "execution_count": 4, - "id": "810fe3d7", + "id": "e83d7a8c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.721017Z", - "iopub.status.busy": "2026-09-06T03:26:41.720770Z", - "iopub.status.idle": "2026-09-06T03:26:41.727146Z", - "shell.execute_reply": "2026-09-06T03:26:41.726623Z" + "iopub.execute_input": "2026-10-27T13:37:34.877746Z", + "iopub.status.busy": "2026-10-27T13:37:34.877571Z", + "iopub.status.idle": "2026-10-27T13:37:34.883147Z", + "shell.execute_reply": "2026-10-27T13:37:34.882686Z" } }, "outputs": [ @@ -245,7 +246,7 @@ }, { "cell_type": "markdown", - "id": "0ced215d", + "id": "72398612", "metadata": {}, "source": [ "Predict before you run it: can 45 million be reached within ten person-minutes? Look at the labor\n", @@ -255,13 +256,13 @@ { "cell_type": "code", "execution_count": 5, - "id": "2a7669bc", + "id": "90373ba2", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.729289Z", - "iopub.status.busy": "2026-09-06T03:26:41.729102Z", - "iopub.status.idle": "2026-09-06T03:26:41.734442Z", - "shell.execute_reply": "2026-09-06T03:26:41.733880Z" + "iopub.execute_input": "2026-10-27T13:37:34.885113Z", + "iopub.status.busy": "2026-10-27T13:37:34.884946Z", + "iopub.status.idle": "2026-10-27T13:37:34.889784Z", + "shell.execute_reply": "2026-10-27T13:37:34.889320Z" } }, "outputs": [ @@ -286,7 +287,7 @@ }, { "cell_type": "markdown", - "id": "23eca828", + "id": "48f1e83b", "metadata": {}, "source": [ "## What happens if you insist\n", @@ -297,13 +298,13 @@ { "cell_type": "code", "execution_count": 6, - "id": "309384f7", + "id": "3edf7880", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.737127Z", - "iopub.status.busy": "2026-09-06T03:26:41.736746Z", - "iopub.status.idle": "2026-09-06T03:26:41.742302Z", - "shell.execute_reply": "2026-09-06T03:26:41.741706Z" + "iopub.execute_input": "2026-10-27T13:37:34.891696Z", + "iopub.status.busy": "2026-10-27T13:37:34.891528Z", + "iopub.status.idle": "2026-10-27T13:37:34.895822Z", + "shell.execute_reply": "2026-10-27T13:37:34.895363Z" } }, "outputs": [ @@ -326,7 +327,7 @@ }, { "cell_type": "markdown", - "id": "2c830df3", + "id": "38255b8f", "metadata": {}, "source": [ "No plan exists. The LP has nothing more to say. That is the situation goal programming is for.\n", @@ -347,13 +348,13 @@ { "cell_type": "code", "execution_count": 7, - "id": "239c6e5c", + "id": "e2bd5a6e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.744971Z", - "iopub.status.busy": "2026-09-06T03:26:41.744751Z", - "iopub.status.idle": "2026-09-06T03:26:41.749960Z", - "shell.execute_reply": "2026-09-06T03:26:41.749332Z" + "iopub.execute_input": "2026-10-27T13:37:34.897841Z", + "iopub.status.busy": "2026-10-27T13:37:34.897671Z", + "iopub.status.idle": "2026-10-27T13:37:34.902519Z", + "shell.execute_reply": "2026-10-27T13:37:34.902106Z" } }, "outputs": [ @@ -378,7 +379,7 @@ }, { "cell_type": "markdown", - "id": "99f47f67", + "id": "7e76ce59", "metadata": {}, "source": [ "The hard constraints are unchanged: staff time and the radio contract are physical limits, not\n", @@ -388,13 +389,13 @@ { "cell_type": "code", "execution_count": 8, - "id": "18770ef9", + "id": "bd35b3f2", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.753726Z", - "iopub.status.busy": "2026-09-06T03:26:41.753454Z", - "iopub.status.idle": "2026-09-06T03:26:41.758965Z", - "shell.execute_reply": "2026-09-06T03:26:41.758254Z" + "iopub.execute_input": "2026-10-27T13:37:34.904502Z", + "iopub.status.busy": "2026-10-27T13:37:34.904334Z", + "iopub.status.idle": "2026-10-27T13:37:34.908104Z", + "shell.execute_reply": "2026-10-27T13:37:34.907633Z" } }, "outputs": [ @@ -415,7 +416,7 @@ }, { "cell_type": "markdown", - "id": "f3343c17", + "id": "ffe37314", "metadata": {}, "source": [ "The two goal rows. Note they are equalities — the deviations do the flexing — and note that the\n", @@ -426,13 +427,13 @@ { "cell_type": "code", "execution_count": 9, - "id": "7d92c399", + "id": "61fb9895", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.762066Z", - "iopub.status.busy": "2026-09-06T03:26:41.761491Z", - "iopub.status.idle": "2026-09-06T03:26:41.768074Z", - "shell.execute_reply": "2026-09-06T03:26:41.767015Z" + "iopub.execute_input": "2026-10-27T13:37:34.909994Z", + "iopub.status.busy": "2026-10-27T13:37:34.909824Z", + "iopub.status.idle": "2026-10-27T13:37:34.915596Z", + "shell.execute_reply": "2026-10-27T13:37:34.914937Z" } }, "outputs": [ @@ -459,7 +460,7 @@ }, { "cell_type": "markdown", - "id": "e0869dff", + "id": "1a4d15cb", "metadata": {}, "source": [ "## Priority 1: miss the exposure target by as little as possible\n", @@ -471,13 +472,13 @@ { "cell_type": "code", "execution_count": 10, - "id": "f26fe6fe", + "id": "b6b8bc33", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.770474Z", - "iopub.status.busy": "2026-09-06T03:26:41.770243Z", - "iopub.status.idle": "2026-09-06T03:26:41.775933Z", - "shell.execute_reply": "2026-09-06T03:26:41.775426Z" + "iopub.execute_input": "2026-10-27T13:37:34.917909Z", + "iopub.status.busy": "2026-10-27T13:37:34.917730Z", + "iopub.status.idle": "2026-10-27T13:37:34.925199Z", + "shell.execute_reply": "2026-10-27T13:37:34.924718Z" } }, "outputs": [ @@ -505,7 +506,7 @@ }, { "cell_type": "markdown", - "id": "ed2c6851", + "id": "b4eedf7a", "metadata": {}, "source": [ "## The pin\n", @@ -518,13 +519,13 @@ { "cell_type": "code", "execution_count": 11, - "id": "f686cbfd", + "id": "7c01e592", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.778180Z", - "iopub.status.busy": "2026-09-06T03:26:41.777996Z", - "iopub.status.idle": "2026-09-06T03:26:41.782342Z", - "shell.execute_reply": "2026-09-06T03:26:41.781698Z" + "iopub.execute_input": "2026-10-27T13:37:34.927296Z", + "iopub.status.busy": "2026-10-27T13:37:34.927124Z", + "iopub.status.idle": "2026-10-27T13:37:34.932284Z", + "shell.execute_reply": "2026-10-27T13:37:34.931628Z" } }, "outputs": [ @@ -544,7 +545,7 @@ }, { "cell_type": "markdown", - "id": "653987b2", + "id": "6ff32fae", "metadata": {}, "source": [ "## Priority 2: overspend by as little as possible, without losing stage 1\n", @@ -555,13 +556,13 @@ { "cell_type": "code", "execution_count": 12, - "id": "8f46b155", + "id": "d9f55f01", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.785344Z", - "iopub.status.busy": "2026-09-06T03:26:41.785121Z", - "iopub.status.idle": "2026-09-06T03:26:41.791337Z", - "shell.execute_reply": "2026-09-06T03:26:41.790723Z" + "iopub.execute_input": "2026-10-27T13:37:34.934368Z", + "iopub.status.busy": "2026-10-27T13:37:34.934152Z", + "iopub.status.idle": "2026-10-27T13:37:34.939717Z", + "shell.execute_reply": "2026-10-27T13:37:34.939084Z" } }, "outputs": [ @@ -590,7 +591,7 @@ }, { "cell_type": "markdown", - "id": "54c1f4f2", + "id": "a69b1a68", "metadata": {}, "source": [ "## The other deviation\n", @@ -603,13 +604,13 @@ { "cell_type": "code", "execution_count": 13, - "id": "a70b34ba", + "id": "6148827c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.793882Z", - "iopub.status.busy": "2026-09-06T03:26:41.793672Z", - "iopub.status.idle": "2026-09-06T03:26:41.799182Z", - "shell.execute_reply": "2026-09-06T03:26:41.798618Z" + "iopub.execute_input": "2026-10-27T13:37:34.942161Z", + "iopub.status.busy": "2026-10-27T13:37:34.941928Z", + "iopub.status.idle": "2026-10-27T13:37:34.948161Z", + "shell.execute_reply": "2026-10-27T13:37:34.947491Z" } }, "outputs": [ @@ -638,7 +639,7 @@ }, { "cell_type": "markdown", - "id": "a105aacd", + "id": "46451a66", "metadata": {}, "source": [ "The objective came back zero: the model got exactly what it asked for. Now read the cost line and\n", @@ -656,13 +657,13 @@ { "cell_type": "code", "execution_count": 14, - "id": "735d214e", + "id": "263828e7", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.801826Z", - "iopub.status.busy": "2026-09-06T03:26:41.801609Z", - "iopub.status.idle": "2026-09-06T03:26:41.807894Z", - "shell.execute_reply": "2026-09-06T03:26:41.807380Z" + "iopub.execute_input": "2026-10-27T13:37:34.950616Z", + "iopub.status.busy": "2026-10-27T13:37:34.950381Z", + "iopub.status.idle": "2026-10-27T13:37:34.956039Z", + "shell.execute_reply": "2026-10-27T13:37:34.955260Z" } }, "outputs": [ @@ -692,7 +693,7 @@ }, { "cell_type": "markdown", - "id": "221f74ee", + "id": "7dd33cec", "metadata": {}, "source": [ "## How many plans meet both goals equally?\n", @@ -705,13 +706,13 @@ { "cell_type": "code", "execution_count": 15, - "id": "0a45cf81", + "id": "4d20bffd", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.810371Z", - "iopub.status.busy": "2026-09-06T03:26:41.810143Z", - "iopub.status.idle": "2026-09-06T03:26:41.816395Z", - "shell.execute_reply": "2026-09-06T03:26:41.815804Z" + "iopub.execute_input": "2026-10-27T13:37:34.958389Z", + "iopub.status.busy": "2026-10-27T13:37:34.958160Z", + "iopub.status.idle": "2026-10-27T13:37:34.963781Z", + "shell.execute_reply": "2026-10-27T13:37:34.963189Z" } }, "outputs": [ @@ -740,7 +741,7 @@ }, { "cell_type": "markdown", - "id": "380ebb2a", + "id": "5240a651", "metadata": {}, "source": [ "---\n", @@ -756,13 +757,13 @@ { "cell_type": "code", "execution_count": 16, - "id": "045e18eb", + "id": "8de14744", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.819635Z", - "iopub.status.busy": "2026-09-06T03:26:41.819392Z", - "iopub.status.idle": "2026-09-06T03:26:41.828276Z", - "shell.execute_reply": "2026-09-06T03:26:41.827614Z" + "iopub.execute_input": "2026-10-27T13:37:34.965757Z", + "iopub.status.busy": "2026-10-27T13:37:34.965576Z", + "iopub.status.idle": "2026-10-27T13:37:34.979312Z", + "shell.execute_reply": "2026-10-27T13:37:34.978925Z" } }, "outputs": [ @@ -794,7 +795,7 @@ }, { "cell_type": "markdown", - "id": "eed69d9c", + "id": "17b71ae5", "metadata": {}, "source": [ "Whatever minutes the two preemptive rows show, both plans lie on the segment between the cheapest and\n", @@ -814,13 +815,13 @@ { "cell_type": "code", "execution_count": 17, - "id": "50a659eb", + "id": "7956450f", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:41.831077Z", - "iopub.status.busy": "2026-09-06T03:26:41.830839Z", - "iopub.status.idle": "2026-09-06T03:26:41.837759Z", - "shell.execute_reply": "2026-09-06T03:26:41.837214Z" + "iopub.execute_input": "2026-10-27T13:37:34.981266Z", + "iopub.status.busy": "2026-10-27T13:37:34.981083Z", + "iopub.status.idle": "2026-10-27T13:37:34.986881Z", + "shell.execute_reply": "2026-10-27T13:37:34.986487Z" } }, "outputs": [ @@ -862,7 +863,7 @@ }, { "cell_type": "markdown", - "id": "8fbcd0a2", + "id": "a74e1dc1", "metadata": {}, "source": [ "---\n", diff --git a/notebooks/03_duality_and_sensitivity/primal_and_dual.ipynb b/notebooks/03_duality_and_sensitivity/primal_and_dual.ipynb index 1538e7a..b6745f9 100644 --- a/notebooks/03_duality_and_sensitivity/primal_and_dual.ipynb +++ b/notebooks/03_duality_and_sensitivity/primal_and_dual.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "6993ac21", + "id": "a90cd293", "metadata": {}, "source": [ "# Primal and dual: the same answer from the other side\n", @@ -20,7 +20,7 @@ }, { "cell_type": "markdown", - "id": "98af2d39", + "id": "d8c29aac", "metadata": {}, "source": [ "## Setup: where the package lives\n", @@ -33,13 +33,13 @@ { "cell_type": "code", "execution_count": 1, - "id": "15585cd1", + "id": "361d2fa6", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.756564Z", - "iopub.status.busy": "2026-09-06T03:26:45.756334Z", - "iopub.status.idle": "2026-09-06T03:26:45.772090Z", - "shell.execute_reply": "2026-09-06T03:26:45.771494Z" + "iopub.execute_input": "2026-10-27T13:37:45.842526Z", + "iopub.status.busy": "2026-10-27T13:37:45.842350Z", + "iopub.status.idle": "2026-10-27T13:37:45.855098Z", + "shell.execute_reply": "2026-10-27T13:37:45.854501Z" } }, "outputs": [ @@ -55,6 +55,7 @@ "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", @@ -64,7 +65,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/03_duality_and_sensitivity\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -80,7 +81,7 @@ }, { "cell_type": "markdown", - "id": "12028a50", + "id": "a7ae3838", "metadata": {}, "source": [ "## Licence setup\n", @@ -94,13 +95,13 @@ { "cell_type": "code", "execution_count": 2, - "id": "9adb0666", + "id": "caa3ff05", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.774774Z", - "iopub.status.busy": "2026-09-06T03:26:45.774527Z", - "iopub.status.idle": "2026-09-06T03:26:45.841616Z", - "shell.execute_reply": "2026-09-06T03:26:45.841008Z" + "iopub.execute_input": "2026-10-27T13:37:45.857357Z", + "iopub.status.busy": "2026-10-27T13:37:45.857176Z", + "iopub.status.idle": "2026-10-27T13:37:45.908902Z", + "shell.execute_reply": "2026-10-27T13:37:45.908411Z" } }, "outputs": [ @@ -135,7 +136,7 @@ }, { "cell_type": "markdown", - "id": "01645aad", + "id": "6261dd28", "metadata": {}, "source": [ "## The LP is a table\n", @@ -149,13 +150,13 @@ { "cell_type": "code", "execution_count": 3, - "id": "aa46c960", + "id": "29c85b98", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.844672Z", - "iopub.status.busy": "2026-09-06T03:26:45.844309Z", - "iopub.status.idle": "2026-09-06T03:26:45.869013Z", - "shell.execute_reply": "2026-09-06T03:26:45.868332Z" + "iopub.execute_input": "2026-10-27T13:37:45.911087Z", + "iopub.status.busy": "2026-10-27T13:37:45.910886Z", + "iopub.status.idle": "2026-10-27T13:37:45.926124Z", + "shell.execute_reply": "2026-10-27T13:37:45.925642Z" } }, "outputs": [ @@ -193,7 +194,7 @@ }, { "cell_type": "markdown", - "id": "c4f66336", + "id": "5cee12fe", "metadata": {}, "source": [ "## The primal, longhand\n", @@ -208,13 +209,13 @@ { "cell_type": "code", "execution_count": 4, - "id": "b185852f", + "id": "c81d9c5d", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.871769Z", - "iopub.status.busy": "2026-09-06T03:26:45.871503Z", - "iopub.status.idle": "2026-09-06T03:26:45.879736Z", - "shell.execute_reply": "2026-09-06T03:26:45.879155Z" + "iopub.execute_input": "2026-10-27T13:37:45.928171Z", + "iopub.status.busy": "2026-10-27T13:37:45.927992Z", + "iopub.status.idle": "2026-10-27T13:37:45.933837Z", + "shell.execute_reply": "2026-10-27T13:37:45.933231Z" } }, "outputs": [ @@ -244,7 +245,7 @@ }, { "cell_type": "markdown", - "id": "64a52178", + "id": "cd507c3b", "metadata": {}, "source": [ "Predict before you run: which of the two rows is worth more per unit of right-hand side? And the\n", @@ -254,13 +255,13 @@ { "cell_type": "code", "execution_count": 5, - "id": "37943243", + "id": "c84cbe3f", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.882301Z", - "iopub.status.busy": "2026-09-06T03:26:45.882079Z", - "iopub.status.idle": "2026-09-06T03:26:45.887594Z", - "shell.execute_reply": "2026-09-06T03:26:45.887109Z" + "iopub.execute_input": "2026-10-27T13:37:45.935895Z", + "iopub.status.busy": "2026-10-27T13:37:45.935724Z", + "iopub.status.idle": "2026-10-27T13:37:45.940100Z", + "shell.execute_reply": "2026-10-27T13:37:45.939381Z" } }, "outputs": [ @@ -284,7 +285,7 @@ }, { "cell_type": "markdown", - "id": "eba87a3c", + "id": "30d2f952", "metadata": {}, "source": [ "One price is negative. Hold that thought until the dual has been built by hand and it can be seen\n", @@ -311,13 +312,13 @@ { "cell_type": "code", "execution_count": 6, - "id": "e26acd30", + "id": "09bbfd6c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.890096Z", - "iopub.status.busy": "2026-09-06T03:26:45.889850Z", - "iopub.status.idle": "2026-09-06T03:26:45.897801Z", - "shell.execute_reply": "2026-09-06T03:26:45.897135Z" + "iopub.execute_input": "2026-10-27T13:37:45.942700Z", + "iopub.status.busy": "2026-10-27T13:37:45.942486Z", + "iopub.status.idle": "2026-10-27T13:37:45.948269Z", + "shell.execute_reply": "2026-10-27T13:37:45.947775Z" } }, "outputs": [ @@ -345,7 +346,7 @@ }, { "cell_type": "markdown", - "id": "57c4ef55", + "id": "90952ad7", "metadata": {}, "source": [ "Predict the dual's objective value before running it. You have already seen the number." @@ -354,13 +355,13 @@ { "cell_type": "code", "execution_count": 7, - "id": "61d555ef", + "id": "0e04bec1", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.900388Z", - "iopub.status.busy": "2026-09-06T03:26:45.900148Z", - "iopub.status.idle": "2026-09-06T03:26:45.906143Z", - "shell.execute_reply": "2026-09-06T03:26:45.905480Z" + "iopub.execute_input": "2026-10-27T13:37:45.950371Z", + "iopub.status.busy": "2026-10-27T13:37:45.950189Z", + "iopub.status.idle": "2026-10-27T13:37:45.955175Z", + "shell.execute_reply": "2026-10-27T13:37:45.954692Z" } }, "outputs": [ @@ -382,7 +383,7 @@ }, { "cell_type": "markdown", - "id": "d4604c6c", + "id": "c155e3f1", "metadata": {}, "source": [ "Equal objectives is strong duality. The dual's variables are the primal's `Pi`. The rules table\n", @@ -401,13 +402,13 @@ { "cell_type": "code", "execution_count": 8, - "id": "203298fd", + "id": "ee54dc7d", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.908756Z", - "iopub.status.busy": "2026-09-06T03:26:45.908508Z", - "iopub.status.idle": "2026-09-06T03:26:45.914150Z", - "shell.execute_reply": "2026-09-06T03:26:45.913513Z" + "iopub.execute_input": "2026-10-27T13:37:45.957182Z", + "iopub.status.busy": "2026-10-27T13:37:45.957009Z", + "iopub.status.idle": "2026-10-27T13:37:45.961992Z", + "shell.execute_reply": "2026-10-27T13:37:45.961503Z" } }, "outputs": [ @@ -431,7 +432,7 @@ }, { "cell_type": "markdown", - "id": "466b777e", + "id": "bc4be49c", "metadata": {}, "source": [ "## Test a price by paying it\n", @@ -444,13 +445,13 @@ { "cell_type": "code", "execution_count": 9, - "id": "dc3820d2", + "id": "2d0fbde6", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.916706Z", - "iopub.status.busy": "2026-09-06T03:26:45.916466Z", - "iopub.status.idle": "2026-09-06T03:26:45.922643Z", - "shell.execute_reply": "2026-09-06T03:26:45.922149Z" + "iopub.execute_input": "2026-10-27T13:37:45.963846Z", + "iopub.status.busy": "2026-10-27T13:37:45.963674Z", + "iopub.status.idle": "2026-10-27T13:37:45.968401Z", + "shell.execute_reply": "2026-10-27T13:37:45.967968Z" } }, "outputs": [ @@ -477,7 +478,7 @@ }, { "cell_type": "markdown", - "id": "87926f26", + "id": "37539210", "metadata": {}, "source": [ "How far could you keep adding units before the price stopped being right? Nothing above answers that.\n", @@ -496,13 +497,13 @@ { "cell_type": "code", "execution_count": 10, - "id": "525d80a9", + "id": "5347398f", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.925039Z", - "iopub.status.busy": "2026-09-06T03:26:45.924816Z", - "iopub.status.idle": "2026-09-06T03:26:45.941054Z", - "shell.execute_reply": "2026-09-06T03:26:45.940501Z" + "iopub.execute_input": "2026-10-27T13:37:45.970424Z", + "iopub.status.busy": "2026-10-27T13:37:45.970252Z", + "iopub.status.idle": "2026-10-27T13:37:45.976026Z", + "shell.execute_reply": "2026-10-27T13:37:45.975667Z" } }, "outputs": [ @@ -529,7 +530,7 @@ }, { "cell_type": "markdown", - "id": "8c43eda4", + "id": "f8c90186", "metadata": {}, "source": [ "The same three steps as before, over the table's sets this time. The loop over resources repeats one\n", @@ -539,13 +540,13 @@ { "cell_type": "code", "execution_count": 11, - "id": "b507c66e", + "id": "ae0d2e5e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.943804Z", - "iopub.status.busy": "2026-09-06T03:26:45.943555Z", - "iopub.status.idle": "2026-09-06T03:26:45.951400Z", - "shell.execute_reply": "2026-09-06T03:26:45.950747Z" + "iopub.execute_input": "2026-10-27T13:37:45.977923Z", + "iopub.status.busy": "2026-10-27T13:37:45.977750Z", + "iopub.status.idle": "2026-10-27T13:37:45.983703Z", + "shell.execute_reply": "2026-10-27T13:37:45.983345Z" } }, "outputs": [ @@ -579,7 +580,7 @@ }, { "cell_type": "markdown", - "id": "5ff1552d", + "id": "9ea32add", "metadata": {}, "source": [ "Buy one more unit of each resource in turn and watch the profit. Which one was not worth buying, and\n", @@ -589,13 +590,13 @@ { "cell_type": "code", "execution_count": 12, - "id": "26ab7eb9", + "id": "23f4f543", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.954410Z", - "iopub.status.busy": "2026-09-06T03:26:45.954177Z", - "iopub.status.idle": "2026-09-06T03:26:45.959986Z", - "shell.execute_reply": "2026-09-06T03:26:45.959260Z" + "iopub.execute_input": "2026-10-27T13:37:45.985589Z", + "iopub.status.busy": "2026-10-27T13:37:45.985418Z", + "iopub.status.idle": "2026-10-27T13:37:45.989815Z", + "shell.execute_reply": "2026-10-27T13:37:45.989333Z" } }, "outputs": [ @@ -622,7 +623,7 @@ }, { "cell_type": "markdown", - "id": "5c8f19b4", + "id": "d8a9d832", "metadata": {}, "source": [ "---\n", @@ -637,13 +638,13 @@ { "cell_type": "code", "execution_count": 13, - "id": "396850bf", + "id": "cf468cbd", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.963051Z", - "iopub.status.busy": "2026-09-06T03:26:45.962779Z", - "iopub.status.idle": "2026-09-06T03:26:45.992377Z", - "shell.execute_reply": "2026-09-06T03:26:45.991582Z" + "iopub.execute_input": "2026-10-27T13:37:45.991710Z", + "iopub.status.busy": "2026-10-27T13:37:45.991540Z", + "iopub.status.idle": "2026-10-27T13:37:46.002543Z", + "shell.execute_reply": "2026-10-27T13:37:46.002077Z" } }, "outputs": [ @@ -675,7 +676,7 @@ }, { "cell_type": "markdown", - "id": "7742f1a5", + "id": "f2463671", "metadata": {}, "source": [ "Flows integer, supplies as ceilings, demands as floors. Predict the cost: it is small enough to do by\n", @@ -685,13 +686,13 @@ { "cell_type": "code", "execution_count": 14, - "id": "bfc2d3b8", + "id": "c7268e19", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:45.995530Z", - "iopub.status.busy": "2026-09-06T03:26:45.995267Z", - "iopub.status.idle": "2026-09-06T03:26:46.003820Z", - "shell.execute_reply": "2026-09-06T03:26:46.003027Z" + "iopub.execute_input": "2026-10-27T13:37:46.004505Z", + "iopub.status.busy": "2026-10-27T13:37:46.004328Z", + "iopub.status.idle": "2026-10-27T13:37:46.019528Z", + "shell.execute_reply": "2026-10-27T13:37:46.019023Z" } }, "outputs": [ @@ -724,7 +725,7 @@ }, { "cell_type": "markdown", - "id": "d4bfa5f2", + "id": "d745b74b", "metadata": {}, "source": [ "Now ask it what one more unit of demand at each wholesaler would cost. This is the cell the original\n", @@ -734,13 +735,13 @@ { "cell_type": "code", "execution_count": 15, - "id": "1ea698f0", + "id": "d22bd681", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:46.006624Z", - "iopub.status.busy": "2026-09-06T03:26:46.006374Z", - "iopub.status.idle": "2026-09-06T03:26:46.011547Z", - "shell.execute_reply": "2026-09-06T03:26:46.010965Z" + "iopub.execute_input": "2026-10-27T13:37:46.021474Z", + "iopub.status.busy": "2026-10-27T13:37:46.021298Z", + "iopub.status.idle": "2026-10-27T13:37:46.024914Z", + "shell.execute_reply": "2026-10-27T13:37:46.024479Z" } }, "outputs": [ @@ -761,7 +762,7 @@ }, { "cell_type": "markdown", - "id": "a9718463", + "id": "7635c910", "metadata": {}, "source": [ "An integer program has no dual in the LP sense: its feasible set is a scatter of points, not a\n", @@ -773,13 +774,13 @@ { "cell_type": "code", "execution_count": 16, - "id": "7cf8cad0", + "id": "53899aa2", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:46.014002Z", - "iopub.status.busy": "2026-09-06T03:26:46.013747Z", - "iopub.status.idle": "2026-09-06T03:26:46.020813Z", - "shell.execute_reply": "2026-09-06T03:26:46.020182Z" + "iopub.execute_input": "2026-10-27T13:37:46.026740Z", + "iopub.status.busy": "2026-10-27T13:37:46.026567Z", + "iopub.status.idle": "2026-10-27T13:37:46.031299Z", + "shell.execute_reply": "2026-10-27T13:37:46.030860Z" } }, "outputs": [ @@ -807,7 +808,7 @@ }, { "cell_type": "markdown", - "id": "777c374e", + "id": "23fd33f3", "metadata": {}, "source": [ "The flows did not change, so the integrality bought nothing: transportation problems with whole\n", @@ -833,13 +834,13 @@ { "cell_type": "code", "execution_count": 17, - "id": "5b343781", + "id": "018cb83c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:46.023640Z", - "iopub.status.busy": "2026-09-06T03:26:46.023392Z", - "iopub.status.idle": "2026-09-06T03:26:46.031773Z", - "shell.execute_reply": "2026-09-06T03:26:46.031195Z" + "iopub.execute_input": "2026-10-27T13:37:46.033164Z", + "iopub.status.busy": "2026-10-27T13:37:46.032994Z", + "iopub.status.idle": "2026-10-27T13:37:46.039746Z", + "shell.execute_reply": "2026-10-27T13:37:46.039278Z" } }, "outputs": [ @@ -873,7 +874,7 @@ }, { "cell_type": "markdown", - "id": "6f41015e", + "id": "850da9c9", "metadata": {}, "source": [ "## The agreement assertion\n", @@ -887,13 +888,13 @@ { "cell_type": "code", "execution_count": 18, - "id": "2097e814", + "id": "9d7350a9", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:46.034561Z", - "iopub.status.busy": "2026-09-06T03:26:46.034268Z", - "iopub.status.idle": "2026-09-06T03:26:46.044529Z", - "shell.execute_reply": "2026-09-06T03:26:46.043925Z" + "iopub.execute_input": "2026-10-27T13:37:46.041626Z", + "iopub.status.busy": "2026-10-27T13:37:46.041453Z", + "iopub.status.idle": "2026-10-27T13:37:46.048642Z", + "shell.execute_reply": "2026-10-27T13:37:46.048152Z" } }, "outputs": [ @@ -947,7 +948,7 @@ }, { "cell_type": "markdown", - "id": "d77b0fed", + "id": "82c85888", "metadata": {}, "source": [ "---\n", diff --git a/notebooks/04_networks_and_transport/assignment.ipynb b/notebooks/04_networks_and_transport/assignment.ipynb index 24f1358..e574c75 100644 --- a/notebooks/04_networks_and_transport/assignment.ipynb +++ b/notebooks/04_networks_and_transport/assignment.ipynb @@ -36,10 +36,10 @@ "id": "773f63d9", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:49.855024Z", - "iopub.status.busy": "2026-09-06T03:26:49.854802Z", - "iopub.status.idle": "2026-09-06T03:26:49.870027Z", - "shell.execute_reply": "2026-09-06T03:26:49.869397Z" + "iopub.execute_input": "2026-10-27T13:37:57.223730Z", + "iopub.status.busy": "2026-10-27T13:37:57.223553Z", + "iopub.status.idle": "2026-10-27T13:37:57.236585Z", + "shell.execute_reply": "2026-10-27T13:37:57.235886Z" } }, "outputs": [ @@ -55,6 +55,7 @@ "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", @@ -64,7 +65,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/04_networks_and_transport\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -97,10 +98,10 @@ "id": "bd12ea65", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:49.872851Z", - "iopub.status.busy": "2026-09-06T03:26:49.872594Z", - "iopub.status.idle": "2026-09-06T03:26:49.934649Z", - "shell.execute_reply": "2026-09-06T03:26:49.934026Z" + "iopub.execute_input": "2026-10-27T13:37:57.238893Z", + "iopub.status.busy": "2026-10-27T13:37:57.238684Z", + "iopub.status.idle": "2026-10-27T13:37:57.296225Z", + "shell.execute_reply": "2026-10-27T13:37:57.295618Z" } }, "outputs": [ @@ -149,10 +150,10 @@ "id": "eac9f97e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:49.937378Z", - "iopub.status.busy": "2026-09-06T03:26:49.937116Z", - "iopub.status.idle": "2026-09-06T03:26:49.961180Z", - "shell.execute_reply": "2026-09-06T03:26:49.960577Z" + "iopub.execute_input": "2026-10-27T13:37:57.298481Z", + "iopub.status.busy": "2026-10-27T13:37:57.298279Z", + "iopub.status.idle": "2026-10-27T13:37:57.316131Z", + "shell.execute_reply": "2026-10-27T13:37:57.315414Z" } }, "outputs": [ @@ -202,10 +203,10 @@ "id": "7613c6e4", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:49.964088Z", - "iopub.status.busy": "2026-09-06T03:26:49.963801Z", - "iopub.status.idle": "2026-09-06T03:26:49.968772Z", - "shell.execute_reply": "2026-09-06T03:26:49.968256Z" + "iopub.execute_input": "2026-10-27T13:37:57.318516Z", + "iopub.status.busy": "2026-10-27T13:37:57.318304Z", + "iopub.status.idle": "2026-10-27T13:37:57.323393Z", + "shell.execute_reply": "2026-10-27T13:37:57.322809Z" } }, "outputs": [ @@ -247,10 +248,10 @@ "id": "972ba710", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:49.971405Z", - "iopub.status.busy": "2026-09-06T03:26:49.971156Z", - "iopub.status.idle": "2026-09-06T03:26:49.976763Z", - "shell.execute_reply": "2026-09-06T03:26:49.976133Z" + "iopub.execute_input": "2026-10-27T13:37:57.325553Z", + "iopub.status.busy": "2026-10-27T13:37:57.325368Z", + "iopub.status.idle": "2026-10-27T13:37:57.330534Z", + "shell.execute_reply": "2026-10-27T13:37:57.330003Z" } }, "outputs": [ @@ -286,10 +287,10 @@ "id": "2d7ae515", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:49.979373Z", - "iopub.status.busy": "2026-09-06T03:26:49.979133Z", - "iopub.status.idle": "2026-09-06T03:26:49.985881Z", - "shell.execute_reply": "2026-09-06T03:26:49.985145Z" + "iopub.execute_input": "2026-10-27T13:37:57.332796Z", + "iopub.status.busy": "2026-10-27T13:37:57.332624Z", + "iopub.status.idle": "2026-10-27T13:37:57.337129Z", + "shell.execute_reply": "2026-10-27T13:37:57.336782Z" } }, "outputs": [ @@ -323,10 +324,10 @@ "id": "0e6fd78e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:49.988570Z", - "iopub.status.busy": "2026-09-06T03:26:49.988344Z", - "iopub.status.idle": "2026-09-06T03:26:49.995152Z", - "shell.execute_reply": "2026-09-06T03:26:49.994613Z" + "iopub.execute_input": "2026-10-27T13:37:57.339037Z", + "iopub.status.busy": "2026-10-27T13:37:57.338871Z", + "iopub.status.idle": "2026-10-27T13:37:57.343706Z", + "shell.execute_reply": "2026-10-27T13:37:57.343236Z" } }, "outputs": [ @@ -368,10 +369,10 @@ "id": "cad41b32", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:49.997968Z", - "iopub.status.busy": "2026-09-06T03:26:49.997719Z", - "iopub.status.idle": "2026-09-06T03:26:50.003269Z", - "shell.execute_reply": "2026-09-06T03:26:50.002641Z" + "iopub.execute_input": "2026-10-27T13:37:57.345759Z", + "iopub.status.busy": "2026-10-27T13:37:57.345594Z", + "iopub.status.idle": "2026-10-27T13:37:57.350283Z", + "shell.execute_reply": "2026-10-27T13:37:57.349812Z" } }, "outputs": [ @@ -421,10 +422,10 @@ "id": "dd2d0195", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:50.006013Z", - "iopub.status.busy": "2026-09-06T03:26:50.005770Z", - "iopub.status.idle": "2026-09-06T03:26:50.016681Z", - "shell.execute_reply": "2026-09-06T03:26:50.015961Z" + "iopub.execute_input": "2026-10-27T13:37:57.352255Z", + "iopub.status.busy": "2026-10-27T13:37:57.352084Z", + "iopub.status.idle": "2026-10-27T13:37:57.373042Z", + "shell.execute_reply": "2026-10-27T13:37:57.372521Z" } }, "outputs": [ @@ -470,10 +471,10 @@ "id": "ba40e607", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:50.020107Z", - "iopub.status.busy": "2026-09-06T03:26:50.019781Z", - "iopub.status.idle": "2026-09-06T03:26:50.026569Z", - "shell.execute_reply": "2026-09-06T03:26:50.025623Z" + "iopub.execute_input": "2026-10-27T13:37:57.374966Z", + "iopub.status.busy": "2026-10-27T13:37:57.374786Z", + "iopub.status.idle": "2026-10-27T13:37:57.379895Z", + "shell.execute_reply": "2026-10-27T13:37:57.379498Z" } }, "outputs": [ @@ -519,10 +520,10 @@ "id": "42d73292", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:50.029566Z", - "iopub.status.busy": "2026-09-06T03:26:50.029272Z", - "iopub.status.idle": "2026-09-06T03:26:50.040857Z", - "shell.execute_reply": "2026-09-06T03:26:50.040161Z" + "iopub.execute_input": "2026-10-27T13:37:57.381832Z", + "iopub.status.busy": "2026-10-27T13:37:57.381621Z", + "iopub.status.idle": "2026-10-27T13:37:57.389730Z", + "shell.execute_reply": "2026-10-27T13:37:57.389261Z" } }, "outputs": [ @@ -566,10 +567,10 @@ "id": "4359c6f2", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:50.043591Z", - "iopub.status.busy": "2026-09-06T03:26:50.043349Z", - "iopub.status.idle": "2026-09-06T03:26:50.049327Z", - "shell.execute_reply": "2026-09-06T03:26:50.048585Z" + "iopub.execute_input": "2026-10-27T13:37:57.391766Z", + "iopub.status.busy": "2026-10-27T13:37:57.391594Z", + "iopub.status.idle": "2026-10-27T13:37:57.396443Z", + "shell.execute_reply": "2026-10-27T13:37:57.396003Z" } }, "outputs": [ diff --git a/notebooks/04_networks_and_transport/transportation.ipynb b/notebooks/04_networks_and_transport/transportation.ipynb index 72ca183..dbcb6d0 100644 --- a/notebooks/04_networks_and_transport/transportation.ipynb +++ b/notebooks/04_networks_and_transport/transportation.ipynb @@ -41,10 +41,10 @@ "id": "021cc86b", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:53.853802Z", - "iopub.status.busy": "2026-09-06T03:26:53.853500Z", - "iopub.status.idle": "2026-09-06T03:26:53.870693Z", - "shell.execute_reply": "2026-09-06T03:26:53.869991Z" + "iopub.execute_input": "2026-10-27T13:38:09.018077Z", + "iopub.status.busy": "2026-10-27T13:38:09.017811Z", + "iopub.status.idle": "2026-10-27T13:38:09.036450Z", + "shell.execute_reply": "2026-10-27T13:38:09.035687Z" } }, "outputs": [ @@ -60,6 +60,7 @@ "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", @@ -69,7 +70,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/04_networks_and_transport\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -102,10 +103,10 @@ "id": "2eac243a", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:53.873596Z", - "iopub.status.busy": "2026-09-06T03:26:53.873282Z", - "iopub.status.idle": "2026-09-06T03:26:53.946369Z", - "shell.execute_reply": "2026-09-06T03:26:53.945766Z" + "iopub.execute_input": "2026-10-27T13:38:09.039645Z", + "iopub.status.busy": "2026-10-27T13:38:09.039349Z", + "iopub.status.idle": "2026-10-27T13:38:09.117420Z", + "shell.execute_reply": "2026-10-27T13:38:09.116673Z" } }, "outputs": [ @@ -157,10 +158,10 @@ "id": "328be594", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:53.949476Z", - "iopub.status.busy": "2026-09-06T03:26:53.949132Z", - "iopub.status.idle": "2026-09-06T03:26:53.982067Z", - "shell.execute_reply": "2026-09-06T03:26:53.981468Z" + "iopub.execute_input": "2026-10-27T13:38:09.120243Z", + "iopub.status.busy": "2026-10-27T13:38:09.119881Z", + "iopub.status.idle": "2026-10-27T13:38:09.140373Z", + "shell.execute_reply": "2026-10-27T13:38:09.139652Z" } }, "outputs": [ @@ -211,10 +212,10 @@ "id": "8beba541", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:53.985133Z", - "iopub.status.busy": "2026-09-06T03:26:53.984844Z", - "iopub.status.idle": "2026-09-06T03:26:53.990514Z", - "shell.execute_reply": "2026-09-06T03:26:53.989719Z" + "iopub.execute_input": "2026-10-27T13:38:09.143492Z", + "iopub.status.busy": "2026-10-27T13:38:09.143193Z", + "iopub.status.idle": "2026-10-27T13:38:09.148351Z", + "shell.execute_reply": "2026-10-27T13:38:09.147608Z" } }, "outputs": [ @@ -265,10 +266,10 @@ "id": "6f1db61d", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:53.994621Z", - "iopub.status.busy": "2026-09-06T03:26:53.994316Z", - "iopub.status.idle": "2026-09-06T03:26:54.001543Z", - "shell.execute_reply": "2026-09-06T03:26:54.000385Z" + "iopub.execute_input": "2026-10-27T13:38:09.151077Z", + "iopub.status.busy": "2026-10-27T13:38:09.150790Z", + "iopub.status.idle": "2026-10-27T13:38:09.156324Z", + "shell.execute_reply": "2026-10-27T13:38:09.155740Z" } }, "outputs": [ @@ -305,10 +306,10 @@ "id": "c44f9baa", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.005565Z", - "iopub.status.busy": "2026-09-06T03:26:54.005281Z", - "iopub.status.idle": "2026-09-06T03:26:54.012133Z", - "shell.execute_reply": "2026-09-06T03:26:54.011071Z" + "iopub.execute_input": "2026-10-27T13:38:09.158911Z", + "iopub.status.busy": "2026-10-27T13:38:09.158565Z", + "iopub.status.idle": "2026-10-27T13:38:09.163859Z", + "shell.execute_reply": "2026-10-27T13:38:09.163056Z" } }, "outputs": [ @@ -342,10 +343,10 @@ "id": "f8f04c6d", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.015722Z", - "iopub.status.busy": "2026-09-06T03:26:54.015403Z", - "iopub.status.idle": "2026-09-06T03:26:54.023458Z", - "shell.execute_reply": "2026-09-06T03:26:54.022665Z" + "iopub.execute_input": "2026-10-27T13:38:09.166426Z", + "iopub.status.busy": "2026-10-27T13:38:09.166204Z", + "iopub.status.idle": "2026-10-27T13:38:09.172199Z", + "shell.execute_reply": "2026-10-27T13:38:09.171654Z" } }, "outputs": [ @@ -387,10 +388,10 @@ "id": "27a6a887", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.026744Z", - "iopub.status.busy": "2026-09-06T03:26:54.026453Z", - "iopub.status.idle": "2026-09-06T03:26:54.035318Z", - "shell.execute_reply": "2026-09-06T03:26:54.034612Z" + "iopub.execute_input": "2026-10-27T13:38:09.174494Z", + "iopub.status.busy": "2026-10-27T13:38:09.174279Z", + "iopub.status.idle": "2026-10-27T13:38:09.180905Z", + "shell.execute_reply": "2026-10-27T13:38:09.180308Z" } }, "outputs": [ @@ -446,10 +447,10 @@ "id": "33787f87", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.038387Z", - "iopub.status.busy": "2026-09-06T03:26:54.038124Z", - "iopub.status.idle": "2026-09-06T03:26:54.045112Z", - "shell.execute_reply": "2026-09-06T03:26:54.044446Z" + "iopub.execute_input": "2026-10-27T13:38:09.183112Z", + "iopub.status.busy": "2026-10-27T13:38:09.182891Z", + "iopub.status.idle": "2026-10-27T13:38:09.188355Z", + "shell.execute_reply": "2026-10-27T13:38:09.187832Z" } }, "outputs": [ @@ -500,10 +501,10 @@ "id": "d504fe39", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.048349Z", - "iopub.status.busy": "2026-09-06T03:26:54.047612Z", - "iopub.status.idle": "2026-09-06T03:26:54.058089Z", - "shell.execute_reply": "2026-09-06T03:26:54.057353Z" + "iopub.execute_input": "2026-10-27T13:38:09.190536Z", + "iopub.status.busy": "2026-10-27T13:38:09.190318Z", + "iopub.status.idle": "2026-10-27T13:38:09.197470Z", + "shell.execute_reply": "2026-10-27T13:38:09.196908Z" } }, "outputs": [ @@ -567,10 +568,10 @@ "id": "15093ef3", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.061182Z", - "iopub.status.busy": "2026-09-06T03:26:54.060908Z", - "iopub.status.idle": "2026-09-06T03:26:54.067891Z", - "shell.execute_reply": "2026-09-06T03:26:54.067093Z" + "iopub.execute_input": "2026-10-27T13:38:09.199583Z", + "iopub.status.busy": "2026-10-27T13:38:09.199383Z", + "iopub.status.idle": "2026-10-27T13:38:09.205400Z", + "shell.execute_reply": "2026-10-27T13:38:09.204809Z" } }, "outputs": [ @@ -611,10 +612,10 @@ "id": "54fb4711", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.071104Z", - "iopub.status.busy": "2026-09-06T03:26:54.070835Z", - "iopub.status.idle": "2026-09-06T03:26:54.081022Z", - "shell.execute_reply": "2026-09-06T03:26:54.080308Z" + "iopub.execute_input": "2026-10-27T13:38:09.207510Z", + "iopub.status.busy": "2026-10-27T13:38:09.207316Z", + "iopub.status.idle": "2026-10-27T13:38:09.215445Z", + "shell.execute_reply": "2026-10-27T13:38:09.214926Z" } }, "outputs": [ @@ -665,10 +666,10 @@ "id": "a9cba3be", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.083983Z", - "iopub.status.busy": "2026-09-06T03:26:54.083717Z", - "iopub.status.idle": "2026-09-06T03:26:54.093102Z", - "shell.execute_reply": "2026-09-06T03:26:54.092386Z" + "iopub.execute_input": "2026-10-27T13:38:09.217513Z", + "iopub.status.busy": "2026-10-27T13:38:09.217326Z", + "iopub.status.idle": "2026-10-27T13:38:09.224634Z", + "shell.execute_reply": "2026-10-27T13:38:09.224091Z" } }, "outputs": [ @@ -735,10 +736,10 @@ "id": "285bec16", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.096072Z", - "iopub.status.busy": "2026-09-06T03:26:54.095754Z", - "iopub.status.idle": "2026-09-06T03:26:54.105545Z", - "shell.execute_reply": "2026-09-06T03:26:54.104889Z" + "iopub.execute_input": "2026-10-27T13:38:09.226748Z", + "iopub.status.busy": "2026-10-27T13:38:09.226558Z", + "iopub.status.idle": "2026-10-27T13:38:09.234320Z", + "shell.execute_reply": "2026-10-27T13:38:09.233790Z" } }, "outputs": [ @@ -798,10 +799,10 @@ "id": "4b6ba199", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.108460Z", - "iopub.status.busy": "2026-09-06T03:26:54.108197Z", - "iopub.status.idle": "2026-09-06T03:26:54.113578Z", - "shell.execute_reply": "2026-09-06T03:26:54.112969Z" + "iopub.execute_input": "2026-10-27T13:38:09.236561Z", + "iopub.status.busy": "2026-10-27T13:38:09.236360Z", + "iopub.status.idle": "2026-10-27T13:38:09.240734Z", + "shell.execute_reply": "2026-10-27T13:38:09.240191Z" } }, "outputs": [ @@ -843,10 +844,10 @@ "id": "7ebb789e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.116190Z", - "iopub.status.busy": "2026-09-06T03:26:54.115947Z", - "iopub.status.idle": "2026-09-06T03:26:54.141455Z", - "shell.execute_reply": "2026-09-06T03:26:54.140850Z" + "iopub.execute_input": "2026-10-27T13:38:09.242900Z", + "iopub.status.busy": "2026-10-27T13:38:09.242710Z", + "iopub.status.idle": "2026-10-27T13:38:09.249971Z", + "shell.execute_reply": "2026-10-27T13:38:09.249404Z" } }, "outputs": [ @@ -886,10 +887,10 @@ "id": "ca99ba31", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.144274Z", - "iopub.status.busy": "2026-09-06T03:26:54.143989Z", - "iopub.status.idle": "2026-09-06T03:26:54.153182Z", - "shell.execute_reply": "2026-09-06T03:26:54.152620Z" + "iopub.execute_input": "2026-10-27T13:38:09.252112Z", + "iopub.status.busy": "2026-10-27T13:38:09.251915Z", + "iopub.status.idle": "2026-10-27T13:38:09.259503Z", + "shell.execute_reply": "2026-10-27T13:38:09.258955Z" } }, "outputs": [ @@ -971,10 +972,10 @@ "id": "85d1c5cd", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.156136Z", - "iopub.status.busy": "2026-09-06T03:26:54.155773Z", - "iopub.status.idle": "2026-09-06T03:26:54.165242Z", - "shell.execute_reply": "2026-09-06T03:26:54.164435Z" + "iopub.execute_input": "2026-10-27T13:38:09.261852Z", + "iopub.status.busy": "2026-10-27T13:38:09.261655Z", + "iopub.status.idle": "2026-10-27T13:38:09.269035Z", + "shell.execute_reply": "2026-10-27T13:38:09.268588Z" } }, "outputs": [ @@ -1023,10 +1024,10 @@ "id": "fe5a585e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:54.168186Z", - "iopub.status.busy": "2026-09-06T03:26:54.167918Z", - "iopub.status.idle": "2026-09-06T03:26:54.176887Z", - "shell.execute_reply": "2026-09-06T03:26:54.176234Z" + "iopub.execute_input": "2026-10-27T13:38:09.271208Z", + "iopub.status.busy": "2026-10-27T13:38:09.271003Z", + "iopub.status.idle": "2026-10-27T13:38:09.278114Z", + "shell.execute_reply": "2026-10-27T13:38:09.277605Z" } }, "outputs": [ diff --git a/notebooks/05_integer_and_branch_bound/facility_location.ipynb b/notebooks/05_integer_and_branch_bound/facility_location.ipynb index 0f0b3a0..87c0246 100644 --- a/notebooks/05_integer_and_branch_bound/facility_location.ipynb +++ b/notebooks/05_integer_and_branch_bound/facility_location.ipynb @@ -37,10 +37,10 @@ "id": "3cf99d04", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.315127Z", - "iopub.status.busy": "2026-09-06T03:26:58.314823Z", - "iopub.status.idle": "2026-09-06T03:26:58.330437Z", - "shell.execute_reply": "2026-09-06T03:26:58.329969Z" + "iopub.execute_input": "2026-10-27T13:38:20.679185Z", + "iopub.status.busy": "2026-10-27T13:38:20.679004Z", + "iopub.status.idle": "2026-10-27T13:38:20.693989Z", + "shell.execute_reply": "2026-10-27T13:38:20.693461Z" } }, "outputs": [ @@ -56,6 +56,7 @@ "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", @@ -65,7 +66,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/05_integer_and_branch_bound\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -98,10 +99,10 @@ "id": "509c4481", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.332804Z", - "iopub.status.busy": "2026-09-06T03:26:58.332592Z", - "iopub.status.idle": "2026-09-06T03:26:58.390492Z", - "shell.execute_reply": "2026-09-06T03:26:58.389979Z" + "iopub.execute_input": "2026-10-27T13:38:20.696848Z", + "iopub.status.busy": "2026-10-27T13:38:20.696648Z", + "iopub.status.idle": "2026-10-27T13:38:20.793295Z", + "shell.execute_reply": "2026-10-27T13:38:20.792784Z" } }, "outputs": [ @@ -151,10 +152,10 @@ "id": "a97d0968", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.392961Z", - "iopub.status.busy": "2026-09-06T03:26:58.392703Z", - "iopub.status.idle": "2026-09-06T03:26:58.433646Z", - "shell.execute_reply": "2026-09-06T03:26:58.433022Z" + "iopub.execute_input": "2026-10-27T13:38:20.795490Z", + "iopub.status.busy": "2026-10-27T13:38:20.795280Z", + "iopub.status.idle": "2026-10-27T13:38:20.815507Z", + "shell.execute_reply": "2026-10-27T13:38:20.814968Z" } }, "outputs": [ @@ -234,10 +235,10 @@ "id": "3b7ca758", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.436624Z", - "iopub.status.busy": "2026-09-06T03:26:58.436331Z", - "iopub.status.idle": "2026-09-06T03:26:58.443150Z", - "shell.execute_reply": "2026-09-06T03:26:58.442509Z" + "iopub.execute_input": "2026-10-27T13:38:20.817775Z", + "iopub.status.busy": "2026-10-27T13:38:20.817576Z", + "iopub.status.idle": "2026-10-27T13:38:20.830571Z", + "shell.execute_reply": "2026-10-27T13:38:20.829936Z" } }, "outputs": [ @@ -276,10 +277,10 @@ "id": "9c6716c2", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.445897Z", - "iopub.status.busy": "2026-09-06T03:26:58.445621Z", - "iopub.status.idle": "2026-09-06T03:26:58.452778Z", - "shell.execute_reply": "2026-09-06T03:26:58.452246Z" + "iopub.execute_input": "2026-10-27T13:38:20.832757Z", + "iopub.status.busy": "2026-10-27T13:38:20.832570Z", + "iopub.status.idle": "2026-10-27T13:38:20.838866Z", + "shell.execute_reply": "2026-10-27T13:38:20.838363Z" } }, "outputs": [ @@ -313,10 +314,10 @@ "id": "f42e4f68", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.455860Z", - "iopub.status.busy": "2026-09-06T03:26:58.455551Z", - "iopub.status.idle": "2026-09-06T03:26:58.460747Z", - "shell.execute_reply": "2026-09-06T03:26:58.460204Z" + "iopub.execute_input": "2026-10-27T13:38:20.840962Z", + "iopub.status.busy": "2026-10-27T13:38:20.840777Z", + "iopub.status.idle": "2026-10-27T13:38:20.846592Z", + "shell.execute_reply": "2026-10-27T13:38:20.846110Z" } }, "outputs": [ @@ -351,10 +352,10 @@ "id": "b5e48cca", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.463047Z", - "iopub.status.busy": "2026-09-06T03:26:58.462824Z", - "iopub.status.idle": "2026-09-06T03:26:58.468660Z", - "shell.execute_reply": "2026-09-06T03:26:58.468116Z" + "iopub.execute_input": "2026-10-27T13:38:20.848675Z", + "iopub.status.busy": "2026-10-27T13:38:20.848487Z", + "iopub.status.idle": "2026-10-27T13:38:20.855435Z", + "shell.execute_reply": "2026-10-27T13:38:20.854593Z" } }, "outputs": [ @@ -389,10 +390,10 @@ "id": "bace6c11", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.470918Z", - "iopub.status.busy": "2026-09-06T03:26:58.470717Z", - "iopub.status.idle": "2026-09-06T03:26:58.483022Z", - "shell.execute_reply": "2026-09-06T03:26:58.482427Z" + "iopub.execute_input": "2026-10-27T13:38:20.857543Z", + "iopub.status.busy": "2026-10-27T13:38:20.857344Z", + "iopub.status.idle": "2026-10-27T13:38:20.894301Z", + "shell.execute_reply": "2026-10-27T13:38:20.893906Z" } }, "outputs": [ @@ -440,10 +441,10 @@ "id": "cc9568d3", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.485872Z", - "iopub.status.busy": "2026-09-06T03:26:58.485428Z", - "iopub.status.idle": "2026-09-06T03:26:58.491408Z", - "shell.execute_reply": "2026-09-06T03:26:58.490579Z" + "iopub.execute_input": "2026-10-27T13:38:20.896306Z", + "iopub.status.busy": "2026-10-27T13:38:20.896107Z", + "iopub.status.idle": "2026-10-27T13:38:20.901555Z", + "shell.execute_reply": "2026-10-27T13:38:20.901054Z" } }, "outputs": [ @@ -483,10 +484,10 @@ "id": "48156adb", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.494062Z", - "iopub.status.busy": "2026-09-06T03:26:58.493793Z", - "iopub.status.idle": "2026-09-06T03:26:58.499028Z", - "shell.execute_reply": "2026-09-06T03:26:58.498528Z" + "iopub.execute_input": "2026-10-27T13:38:20.903745Z", + "iopub.status.busy": "2026-10-27T13:38:20.903562Z", + "iopub.status.idle": "2026-10-27T13:38:20.907578Z", + "shell.execute_reply": "2026-10-27T13:38:20.907181Z" } }, "outputs": [ @@ -528,10 +529,10 @@ "id": "24262441", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.501686Z", - "iopub.status.busy": "2026-09-06T03:26:58.501455Z", - "iopub.status.idle": "2026-09-06T03:26:58.510937Z", - "shell.execute_reply": "2026-09-06T03:26:58.510357Z" + "iopub.execute_input": "2026-10-27T13:38:20.909579Z", + "iopub.status.busy": "2026-10-27T13:38:20.909395Z", + "iopub.status.idle": "2026-10-27T13:38:20.919200Z", + "shell.execute_reply": "2026-10-27T13:38:20.918707Z" } }, "outputs": [ @@ -589,10 +590,10 @@ "id": "87466577", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.513719Z", - "iopub.status.busy": "2026-09-06T03:26:58.513409Z", - "iopub.status.idle": "2026-09-06T03:26:58.518985Z", - "shell.execute_reply": "2026-09-06T03:26:58.518375Z" + "iopub.execute_input": "2026-10-27T13:38:20.921432Z", + "iopub.status.busy": "2026-10-27T13:38:20.921241Z", + "iopub.status.idle": "2026-10-27T13:38:20.925384Z", + "shell.execute_reply": "2026-10-27T13:38:20.924897Z" } }, "outputs": [ @@ -638,10 +639,10 @@ "id": "bfdab43f", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.521411Z", - "iopub.status.busy": "2026-09-06T03:26:58.521168Z", - "iopub.status.idle": "2026-09-06T03:26:58.532925Z", - "shell.execute_reply": "2026-09-06T03:26:58.532368Z" + "iopub.execute_input": "2026-10-27T13:38:20.927669Z", + "iopub.status.busy": "2026-10-27T13:38:20.927481Z", + "iopub.status.idle": "2026-10-27T13:38:20.937085Z", + "shell.execute_reply": "2026-10-27T13:38:20.936728Z" } }, "outputs": [ @@ -649,13 +650,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "fractional sites: ['1', '2', '3', '4'] branching on warehouse 2 (open = 0.500)\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ + "fractional sites: ['1', '2', '3', '4'] branching on warehouse 2 (open = 0.500)\n", "\n", " open[2] = 0: cost 9,098.75 integral: False\n", " 1:1.00 2:0.00 3:0.94 4:0.50 5:0.00\n", @@ -709,10 +704,10 @@ "id": "d4a560bd", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.535336Z", - "iopub.status.busy": "2026-09-06T03:26:58.535116Z", - "iopub.status.idle": "2026-09-06T03:26:58.540116Z", - "shell.execute_reply": "2026-09-06T03:26:58.539710Z" + "iopub.execute_input": "2026-10-27T13:38:20.939291Z", + "iopub.status.busy": "2026-10-27T13:38:20.939106Z", + "iopub.status.idle": "2026-10-27T13:38:20.944371Z", + "shell.execute_reply": "2026-10-27T13:38:20.943748Z" } }, "outputs": [ @@ -764,10 +759,10 @@ "id": "27cfba75", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.542443Z", - "iopub.status.busy": "2026-09-06T03:26:58.542242Z", - "iopub.status.idle": "2026-09-06T03:26:58.557456Z", - "shell.execute_reply": "2026-09-06T03:26:58.556829Z" + "iopub.execute_input": "2026-10-27T13:38:20.946547Z", + "iopub.status.busy": "2026-10-27T13:38:20.946361Z", + "iopub.status.idle": "2026-10-27T13:38:20.960167Z", + "shell.execute_reply": "2026-10-27T13:38:20.959635Z" } }, "outputs": [ @@ -818,10 +813,10 @@ "id": "5f2f2da9", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:26:58.559894Z", - "iopub.status.busy": "2026-09-06T03:26:58.559673Z", - "iopub.status.idle": "2026-09-06T03:26:58.566744Z", - "shell.execute_reply": "2026-09-06T03:26:58.566181Z" + "iopub.execute_input": "2026-10-27T13:38:20.962403Z", + "iopub.status.busy": "2026-10-27T13:38:20.962210Z", + "iopub.status.idle": "2026-10-27T13:38:20.969059Z", + "shell.execute_reply": "2026-10-27T13:38:20.968628Z" } }, "outputs": [ diff --git a/notebooks/06_nonlinear_and_convex/curve_fit_lifting.ipynb b/notebooks/06_nonlinear_and_convex/curve_fit_lifting.ipynb index faee612..ed23430 100644 --- a/notebooks/06_nonlinear_and_convex/curve_fit_lifting.ipynb +++ b/notebooks/06_nonlinear_and_convex/curve_fit_lifting.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "20fa8a62", + "id": "fe3f1293", "metadata": {}, "source": [ "# Fitting a curve with a division in it: lifting a model a solver can take\n", @@ -25,7 +25,7 @@ }, { "cell_type": "markdown", - "id": "55d71791", + "id": "49c1a98e", "metadata": {}, "source": [ "## Setup: where the package lives\n", @@ -38,13 +38,13 @@ { "cell_type": "code", "execution_count": 1, - "id": "3d18fb35", + "id": "1adc5c17", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:05.614955Z", - "iopub.status.busy": "2026-09-06T10:46:05.614780Z", - "iopub.status.idle": "2026-09-06T10:46:05.625995Z", - "shell.execute_reply": "2026-09-06T10:46:05.625531Z" + "iopub.execute_input": "2026-10-27T13:38:33.163534Z", + "iopub.status.busy": "2026-10-27T13:38:33.163323Z", + "iopub.status.idle": "2026-10-27T13:38:33.178355Z", + "shell.execute_reply": "2026-10-27T13:38:33.177517Z" } }, "outputs": [ @@ -60,6 +60,7 @@ "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", @@ -69,7 +70,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/06_nonlinear_and_convex\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -85,7 +86,7 @@ }, { "cell_type": "markdown", - "id": "695c561b", + "id": "496ab515", "metadata": {}, "source": [ "## Licence setup\n", @@ -99,13 +100,13 @@ { "cell_type": "code", "execution_count": 2, - "id": "b388a703", + "id": "2c337b04", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:05.628213Z", - "iopub.status.busy": "2026-09-06T10:46:05.628040Z", - "iopub.status.idle": "2026-09-06T10:46:05.674559Z", - "shell.execute_reply": "2026-09-06T10:46:05.673994Z" + "iopub.execute_input": "2026-10-27T13:38:33.180646Z", + "iopub.status.busy": "2026-10-27T13:38:33.180468Z", + "iopub.status.idle": "2026-10-27T13:38:33.280754Z", + "shell.execute_reply": "2026-10-27T13:38:33.280246Z" } }, "outputs": [ @@ -140,7 +141,7 @@ }, { "cell_type": "markdown", - "id": "940dc328", + "id": "6fc87893", "metadata": {}, "source": [ "## The observations are a table\n", @@ -152,13 +153,13 @@ { "cell_type": "code", "execution_count": 3, - "id": "e8b4c422", + "id": "b765c8c1", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:05.676578Z", - "iopub.status.busy": "2026-09-06T10:46:05.676384Z", - "iopub.status.idle": "2026-09-06T10:46:05.859382Z", - "shell.execute_reply": "2026-09-06T10:46:05.858884Z" + "iopub.execute_input": "2026-10-27T13:38:33.283121Z", + "iopub.status.busy": "2026-10-27T13:38:33.282913Z", + "iopub.status.idle": "2026-10-27T13:38:33.612603Z", + "shell.execute_reply": "2026-10-27T13:38:33.612047Z" } }, "outputs": [ @@ -197,7 +198,7 @@ }, { "cell_type": "markdown", - "id": "796b62b9", + "id": "13184d92", "metadata": {}, "source": [ "## Predict before building anything\n", @@ -222,13 +223,13 @@ { "cell_type": "code", "execution_count": 4, - "id": "d4148f75", + "id": "f67a34f9", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:05.861361Z", - "iopub.status.busy": "2026-09-06T10:46:05.861161Z", - "iopub.status.idle": "2026-09-06T10:46:05.867346Z", - "shell.execute_reply": "2026-09-06T10:46:05.866683Z" + "iopub.execute_input": "2026-10-27T13:38:33.614755Z", + "iopub.status.busy": "2026-10-27T13:38:33.614548Z", + "iopub.status.idle": "2026-10-27T13:38:33.629099Z", + "shell.execute_reply": "2026-10-27T13:38:33.628582Z" } }, "outputs": [ @@ -262,7 +263,7 @@ }, { "cell_type": "markdown", - "id": "2fb93318", + "id": "9048cae9", "metadata": {}, "source": [ "## Trick 2: give each residual its own variable\n", @@ -279,13 +280,13 @@ { "cell_type": "code", "execution_count": 5, - "id": "dc53b869", + "id": "739f7b14", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:05.869286Z", - "iopub.status.busy": "2026-09-06T10:46:05.869116Z", - "iopub.status.idle": "2026-09-06T10:46:05.873583Z", - "shell.execute_reply": "2026-09-06T10:46:05.873092Z" + "iopub.execute_input": "2026-10-27T13:38:33.631160Z", + "iopub.status.busy": "2026-10-27T13:38:33.630983Z", + "iopub.status.idle": "2026-10-27T13:38:33.637267Z", + "shell.execute_reply": "2026-10-27T13:38:33.636849Z" } }, "outputs": [ @@ -308,7 +309,7 @@ }, { "cell_type": "markdown", - "id": "e74dbf9a", + "id": "a0484ece", "metadata": {}, "source": [ "## The slide's side condition\n", @@ -320,13 +321,13 @@ { "cell_type": "code", "execution_count": 6, - "id": "6545a359", + "id": "68c27d2b", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:05.875453Z", - "iopub.status.busy": "2026-09-06T10:46:05.875286Z", - "iopub.status.idle": "2026-09-06T10:46:05.878745Z", - "shell.execute_reply": "2026-09-06T10:46:05.878255Z" + "iopub.execute_input": "2026-10-27T13:38:33.639299Z", + "iopub.status.busy": "2026-10-27T13:38:33.639124Z", + "iopub.status.idle": "2026-10-27T13:38:33.644440Z", + "shell.execute_reply": "2026-10-27T13:38:33.643948Z" } }, "outputs": [ @@ -347,7 +348,7 @@ }, { "cell_type": "markdown", - "id": "8f9586fa", + "id": "343081e9", "metadata": {}, "source": [ "## Solve, and read the proof\n", @@ -360,13 +361,13 @@ { "cell_type": "code", "execution_count": 7, - "id": "711395e3", + "id": "2ddf280c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:05.880809Z", - "iopub.status.busy": "2026-09-06T10:46:05.880641Z", - "iopub.status.idle": "2026-09-06T10:46:05.979280Z", - "shell.execute_reply": "2026-09-06T10:46:05.978752Z" + "iopub.execute_input": "2026-10-27T13:38:33.646363Z", + "iopub.status.busy": "2026-10-27T13:38:33.646191Z", + "iopub.status.idle": "2026-10-27T13:38:33.810869Z", + "shell.execute_reply": "2026-10-27T13:38:33.810290Z" } }, "outputs": [ @@ -388,7 +389,7 @@ }, { "cell_type": "markdown", - "id": "77660fac", + "id": "8af2e553", "metadata": {}, "source": [ "## The residuals, with their signs\n", @@ -400,13 +401,13 @@ { "cell_type": "code", "execution_count": 8, - "id": "3ed7563a", + "id": "e0f8621c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:05.981314Z", - "iopub.status.busy": "2026-09-06T10:46:05.981134Z", - "iopub.status.idle": "2026-09-06T10:46:05.985818Z", - "shell.execute_reply": "2026-09-06T10:46:05.985209Z" + "iopub.execute_input": "2026-10-27T13:38:33.812850Z", + "iopub.status.busy": "2026-10-27T13:38:33.812662Z", + "iopub.status.idle": "2026-10-27T13:38:33.816689Z", + "shell.execute_reply": "2026-10-27T13:38:33.816199Z" } }, "outputs": [ @@ -433,7 +434,7 @@ }, { "cell_type": "markdown", - "id": "4d917a73", + "id": "9d7f48ce", "metadata": {}, "source": [ "---\n", @@ -448,13 +449,13 @@ { "cell_type": "code", "execution_count": 9, - "id": "6043c41d", + "id": "f102dc2e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:05.988034Z", - "iopub.status.busy": "2026-09-06T10:46:05.987849Z", - "iopub.status.idle": "2026-09-06T10:46:06.073512Z", - "shell.execute_reply": "2026-09-06T10:46:06.073045Z" + "iopub.execute_input": "2026-10-27T13:38:33.818600Z", + "iopub.status.busy": "2026-10-27T13:38:33.818421Z", + "iopub.status.idle": "2026-10-27T13:38:33.902508Z", + "shell.execute_reply": "2026-10-27T13:38:33.901922Z" } }, "outputs": [ @@ -493,7 +494,7 @@ }, { "cell_type": "markdown", - "id": "b4cbad3e", + "id": "e6be7378", "metadata": {}, "source": [ "Every residual is now zero or positive. What has that bound told the solver the curve must do, and is\n", @@ -510,13 +511,13 @@ { "cell_type": "code", "execution_count": 10, - "id": "e442a19a", + "id": "dfc795e1", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:06.075551Z", - "iopub.status.busy": "2026-09-06T10:46:06.075364Z", - "iopub.status.idle": "2026-09-06T10:46:11.524250Z", - "shell.execute_reply": "2026-09-06T10:46:11.523665Z" + "iopub.execute_input": "2026-10-27T13:38:33.904794Z", + "iopub.status.busy": "2026-10-27T13:38:33.904611Z", + "iopub.status.idle": "2026-10-27T13:38:39.361927Z", + "shell.execute_reply": "2026-10-27T13:38:39.361320Z" } }, "outputs": [ @@ -553,7 +554,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "every bound removed time limit 96664 4.8076 100.0%\n" + "every bound removed time limit 77380 4.8076 100.0%\n" ] } ], @@ -591,7 +592,7 @@ }, { "cell_type": "markdown", - "id": "7dcf0aec", + "id": "d4a0cf41", "metadata": {}, "source": [ "Removing any *single* bound leaves the proof intact — and dropping the upper bound on $\\beta_1$ makes\n", @@ -617,13 +618,13 @@ { "cell_type": "code", "execution_count": 11, - "id": "8ce658cb", + "id": "0823d208", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:11.526221Z", - "iopub.status.busy": "2026-09-06T10:46:11.526032Z", - "iopub.status.idle": "2026-09-06T10:46:12.313399Z", - "shell.execute_reply": "2026-09-06T10:46:12.312945Z" + "iopub.execute_input": "2026-10-27T13:38:39.364324Z", + "iopub.status.busy": "2026-10-27T13:38:39.364110Z", + "iopub.status.idle": "2026-10-27T13:38:40.555406Z", + "shell.execute_reply": "2026-10-27T13:38:40.554829Z" } }, "outputs": [ @@ -656,7 +657,7 @@ }, { "cell_type": "markdown", - "id": "d87443cb", + "id": "cb9cea58", "metadata": {}, "source": [ "Same sum of squares to six decimals; $\\beta_1$ differs in the second decimal place. Two correct methods,\n", @@ -677,13 +678,13 @@ { "cell_type": "code", "execution_count": 12, - "id": "192c8f91", + "id": "6a7b599e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:12.315575Z", - "iopub.status.busy": "2026-09-06T10:46:12.315314Z", - "iopub.status.idle": "2026-09-06T10:46:12.430045Z", - "shell.execute_reply": "2026-09-06T10:46:12.429522Z" + "iopub.execute_input": "2026-10-27T13:38:40.557618Z", + "iopub.status.busy": "2026-10-27T13:38:40.557374Z", + "iopub.status.idle": "2026-10-27T13:38:40.681632Z", + "shell.execute_reply": "2026-10-27T13:38:40.680985Z" } }, "outputs": [ @@ -708,7 +709,7 @@ }, { "cell_type": "markdown", - "id": "5f364ebe", + "id": "02f05a4b", "metadata": {}, "source": [ "## The agreement assertion\n", @@ -726,13 +727,13 @@ { "cell_type": "code", "execution_count": 13, - "id": "4fdcf7c8", + "id": "34e8dfb8", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:46:12.432243Z", - "iopub.status.busy": "2026-09-06T10:46:12.432050Z", - "iopub.status.idle": "2026-09-06T10:46:12.438117Z", - "shell.execute_reply": "2026-09-06T10:46:12.437563Z" + "iopub.execute_input": "2026-10-27T13:38:40.684222Z", + "iopub.status.busy": "2026-10-27T13:38:40.683971Z", + "iopub.status.idle": "2026-10-27T13:38:40.691472Z", + "shell.execute_reply": "2026-10-27T13:38:40.690791Z" } }, "outputs": [ @@ -774,7 +775,7 @@ }, { "cell_type": "markdown", - "id": "490f524d", + "id": "4cf1976f", "metadata": {}, "source": [ "---\n", diff --git a/notebooks/06_nonlinear_and_convex/pooling.ipynb b/notebooks/06_nonlinear_and_convex/pooling.ipynb index 2b4d320..0cff546 100644 --- a/notebooks/06_nonlinear_and_convex/pooling.ipynb +++ b/notebooks/06_nonlinear_and_convex/pooling.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "97933cb2", + "id": "1e5b5329", "metadata": {}, "source": [ "# The pooling problem: when a quality is an unknown times an unknown\n", @@ -20,7 +20,7 @@ }, { "cell_type": "markdown", - "id": "6d490a66", + "id": "ae9215e2", "metadata": {}, "source": [ "## Setup: where the package lives\n", @@ -33,13 +33,13 @@ { "cell_type": "code", "execution_count": 1, - "id": "5aa9bdaf", + "id": "5ca0cfc8", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.160949Z", - "iopub.status.busy": "2026-09-06T10:43:40.160725Z", - "iopub.status.idle": "2026-09-06T10:43:40.173314Z", - "shell.execute_reply": "2026-09-06T10:43:40.172712Z" + "iopub.execute_input": "2026-10-27T13:38:52.574157Z", + "iopub.status.busy": "2026-10-27T13:38:52.573923Z", + "iopub.status.idle": "2026-10-27T13:38:52.590206Z", + "shell.execute_reply": "2026-10-27T13:38:52.589718Z" } }, "outputs": [ @@ -55,6 +55,7 @@ "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", @@ -64,7 +65,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/06_nonlinear_and_convex\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -80,7 +81,7 @@ }, { "cell_type": "markdown", - "id": "b07cfccf", + "id": "9bbd0a01", "metadata": {}, "source": [ "## Licence setup\n", @@ -94,13 +95,13 @@ { "cell_type": "code", "execution_count": 2, - "id": "a95502b0", + "id": "859b6a79", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.175688Z", - "iopub.status.busy": "2026-09-06T10:43:40.175502Z", - "iopub.status.idle": "2026-09-06T10:43:40.226683Z", - "shell.execute_reply": "2026-09-06T10:43:40.226167Z" + "iopub.execute_input": "2026-10-27T13:38:52.592210Z", + "iopub.status.busy": "2026-10-27T13:38:52.592032Z", + "iopub.status.idle": "2026-10-27T13:38:52.652736Z", + "shell.execute_reply": "2026-10-27T13:38:52.652194Z" } }, "outputs": [ @@ -135,7 +136,7 @@ }, { "cell_type": "markdown", - "id": "e1c926ca", + "id": "e7e6e07c", "metadata": {}, "source": [ "## Two tables\n", @@ -148,13 +149,13 @@ { "cell_type": "code", "execution_count": 3, - "id": "ded9aba4", + "id": "d32d45c6", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.228798Z", - "iopub.status.busy": "2026-09-06T10:43:40.228595Z", - "iopub.status.idle": "2026-09-06T10:43:40.420418Z", - "shell.execute_reply": "2026-09-06T10:43:40.419900Z" + "iopub.execute_input": "2026-10-27T13:38:52.654865Z", + "iopub.status.busy": "2026-10-27T13:38:52.654653Z", + "iopub.status.idle": "2026-10-27T13:38:52.886634Z", + "shell.execute_reply": "2026-10-27T13:38:52.886137Z" } }, "outputs": [ @@ -196,7 +197,7 @@ }, { "cell_type": "markdown", - "id": "f036c245", + "id": "1b9b93b1", "metadata": {}, "source": [ "## Predict before building anything\n", @@ -218,13 +219,13 @@ { "cell_type": "code", "execution_count": 4, - "id": "228c4328", + "id": "a1042b1f", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.422545Z", - "iopub.status.busy": "2026-09-06T10:43:40.422336Z", - "iopub.status.idle": "2026-09-06T10:43:40.428993Z", - "shell.execute_reply": "2026-09-06T10:43:40.428489Z" + "iopub.execute_input": "2026-10-27T13:38:52.889113Z", + "iopub.status.busy": "2026-10-27T13:38:52.888883Z", + "iopub.status.idle": "2026-10-27T13:38:52.894686Z", + "shell.execute_reply": "2026-10-27T13:38:52.894109Z" } }, "outputs": [ @@ -254,7 +255,7 @@ }, { "cell_type": "markdown", - "id": "4d54a2de", + "id": "a1ce6482", "metadata": {}, "source": [ "## The quality variables — where the model stops being linear\n", @@ -270,13 +271,13 @@ { "cell_type": "code", "execution_count": 5, - "id": "25a4268b", + "id": "888816a0", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.430972Z", - "iopub.status.busy": "2026-09-06T10:43:40.430795Z", - "iopub.status.idle": "2026-09-06T10:43:40.442685Z", - "shell.execute_reply": "2026-09-06T10:43:40.442086Z" + "iopub.execute_input": "2026-10-27T13:38:52.896699Z", + "iopub.status.busy": "2026-10-27T13:38:52.896518Z", + "iopub.status.idle": "2026-10-27T13:38:52.902001Z", + "shell.execute_reply": "2026-10-27T13:38:52.901504Z" } }, "outputs": [ @@ -303,7 +304,7 @@ }, { "cell_type": "markdown", - "id": "ce5edc98", + "id": "5e314ff0", "metadata": {}, "source": [ "The same balance at each product: what it receives from the pool carries the pool's fraction, what it\n", @@ -314,13 +315,13 @@ { "cell_type": "code", "execution_count": 6, - "id": "e680df50", + "id": "234b4c8b", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.444785Z", - "iopub.status.busy": "2026-09-06T10:43:40.444614Z", - "iopub.status.idle": "2026-09-06T10:43:40.449228Z", - "shell.execute_reply": "2026-09-06T10:43:40.448711Z" + "iopub.execute_input": "2026-10-27T13:38:52.904718Z", + "iopub.status.busy": "2026-10-27T13:38:52.904515Z", + "iopub.status.idle": "2026-10-27T13:38:52.910177Z", + "shell.execute_reply": "2026-10-27T13:38:52.909733Z" } }, "outputs": [ @@ -345,7 +346,7 @@ }, { "cell_type": "markdown", - "id": "da55fe0d", + "id": "560151e9", "metadata": {}, "source": [ "## The objective: revenue minus purchases" @@ -354,13 +355,13 @@ { "cell_type": "code", "execution_count": 7, - "id": "1340eb09", + "id": "e06be692", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.451100Z", - "iopub.status.busy": "2026-09-06T10:43:40.450929Z", - "iopub.status.idle": "2026-09-06T10:43:40.455712Z", - "shell.execute_reply": "2026-09-06T10:43:40.455218Z" + "iopub.execute_input": "2026-10-27T13:38:52.912556Z", + "iopub.status.busy": "2026-10-27T13:38:52.912360Z", + "iopub.status.idle": "2026-10-27T13:38:52.917395Z", + "shell.execute_reply": "2026-10-27T13:38:52.916628Z" } }, "outputs": [ @@ -383,7 +384,7 @@ }, { "cell_type": "markdown", - "id": "1baaeffd", + "id": "bcafe658", "metadata": {}, "source": [ "## Ask the solver as if the model were convex\n", @@ -395,13 +396,13 @@ { "cell_type": "code", "execution_count": 8, - "id": "33abcc3c", + "id": "4a4d9844", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.457665Z", - "iopub.status.busy": "2026-09-06T10:43:40.457496Z", - "iopub.status.idle": "2026-09-06T10:43:40.462001Z", - "shell.execute_reply": "2026-09-06T10:43:40.461506Z" + "iopub.execute_input": "2026-10-27T13:38:52.919947Z", + "iopub.status.busy": "2026-10-27T13:38:52.919735Z", + "iopub.status.idle": "2026-10-27T13:38:52.924387Z", + "shell.execute_reply": "2026-10-27T13:38:52.923967Z" } }, "outputs": [ @@ -424,7 +425,7 @@ }, { "cell_type": "markdown", - "id": "e07b0edc", + "id": "0a0d1d51", "metadata": {}, "source": [ "## Now let it branch\n", @@ -437,13 +438,13 @@ { "cell_type": "code", "execution_count": 9, - "id": "80bb813a", + "id": "7e0adb8d", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.463966Z", - "iopub.status.busy": "2026-09-06T10:43:40.463798Z", - "iopub.status.idle": "2026-09-06T10:43:40.490018Z", - "shell.execute_reply": "2026-09-06T10:43:40.489542Z" + "iopub.execute_input": "2026-10-27T13:38:52.926722Z", + "iopub.status.busy": "2026-10-27T13:38:52.926533Z", + "iopub.status.idle": "2026-10-27T13:38:52.960802Z", + "shell.execute_reply": "2026-10-27T13:38:52.960284Z" } }, "outputs": [ @@ -484,7 +485,7 @@ }, { "cell_type": "markdown", - "id": "5708fb58", + "id": "d7f9f662", "metadata": {}, "source": [ "A product that is not made has no delivered fraction: its quality row reads $q_j \\times 0 = 0$, so\n", @@ -500,13 +501,13 @@ { "cell_type": "code", "execution_count": 10, - "id": "896caef9", + "id": "c2d1f8e9", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.492037Z", - "iopub.status.busy": "2026-09-06T10:43:40.491861Z", - "iopub.status.idle": "2026-09-06T10:43:40.497709Z", - "shell.execute_reply": "2026-09-06T10:43:40.497115Z" + "iopub.execute_input": "2026-10-27T13:38:52.963527Z", + "iopub.status.busy": "2026-10-27T13:38:52.963240Z", + "iopub.status.idle": "2026-10-27T13:38:52.969033Z", + "shell.execute_reply": "2026-10-27T13:38:52.968349Z" } }, "outputs": [ @@ -536,7 +537,7 @@ }, { "cell_type": "markdown", - "id": "e4710a0b", + "id": "f7b14e50", "metadata": {}, "source": [ "---\n", @@ -551,13 +552,13 @@ { "cell_type": "code", "execution_count": 11, - "id": "87a30b08", + "id": "ec3a2560", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.500004Z", - "iopub.status.busy": "2026-09-06T10:43:40.499825Z", - "iopub.status.idle": "2026-09-06T10:43:40.535848Z", - "shell.execute_reply": "2026-09-06T10:43:40.535320Z" + "iopub.execute_input": "2026-10-27T13:38:52.971088Z", + "iopub.status.busy": "2026-10-27T13:38:52.970905Z", + "iopub.status.idle": "2026-10-27T13:38:53.009782Z", + "shell.execute_reply": "2026-10-27T13:38:53.009165Z" } }, "outputs": [ @@ -592,7 +593,7 @@ }, { "cell_type": "markdown", - "id": "3d1d8496", + "id": "f2c128ae", "metadata": {}, "source": [ "Two profitable regions with a valley between them, and the run above ends back at the free optimum.\n", @@ -612,13 +613,13 @@ { "cell_type": "code", "execution_count": 12, - "id": "23c7c71a", + "id": "55c99351", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.537901Z", - "iopub.status.busy": "2026-09-06T10:43:40.537722Z", - "iopub.status.idle": "2026-09-06T10:43:40.575452Z", - "shell.execute_reply": "2026-09-06T10:43:40.574937Z" + "iopub.execute_input": "2026-10-27T13:38:53.011905Z", + "iopub.status.busy": "2026-10-27T13:38:53.011713Z", + "iopub.status.idle": "2026-10-27T13:38:53.051671Z", + "shell.execute_reply": "2026-10-27T13:38:53.051151Z" } }, "outputs": [ @@ -629,7 +630,7 @@ "Gurobi, P-formulation: profit 400.00 bound 400.00 pool sulfur 0.0100\n", "profit from flows: 400.0\n", "delivered sulfur : {'Y': 0.015}\n", - "landscape : {0.01: 400.0, 0.015: 300.0, 0.02: -0.0, 0.025: 50.0, 0.03: 100.0}\n" + "landscape : {0.01: 400.0, 0.015: 300.0, 0.02: 0.0, 0.025: 50.0, 0.03: 100.0}\n" ] } ], @@ -649,7 +650,7 @@ }, { "cell_type": "markdown", - "id": "41fd7b2c", + "id": "8f5c5d50", "metadata": {}, "source": [ "## The agreement assertion\n", @@ -666,13 +667,13 @@ { "cell_type": "code", "execution_count": 13, - "id": "8ca6d553", + "id": "c14dd722", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:43:40.577501Z", - "iopub.status.busy": "2026-09-06T10:43:40.577314Z", - "iopub.status.idle": "2026-09-06T10:43:40.583142Z", - "shell.execute_reply": "2026-09-06T10:43:40.582644Z" + "iopub.execute_input": "2026-10-27T13:38:53.053661Z", + "iopub.status.busy": "2026-10-27T13:38:53.053481Z", + "iopub.status.idle": "2026-10-27T13:38:53.060298Z", + "shell.execute_reply": "2026-10-27T13:38:53.059845Z" } }, "outputs": [ @@ -717,7 +718,7 @@ }, { "cell_type": "markdown", - "id": "e1709166", + "id": "68cc7a06", "metadata": {}, "source": [ "---\n", diff --git a/notebooks/07_stochastic_and_newsvendor/newsvendor.ipynb b/notebooks/07_stochastic_and_newsvendor/newsvendor.ipynb index e34c9ab..9ae6af6 100644 --- a/notebooks/07_stochastic_and_newsvendor/newsvendor.ipynb +++ b/notebooks/07_stochastic_and_newsvendor/newsvendor.ipynb @@ -45,10 +45,10 @@ "id": "1eb953bc", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.259650Z", - "iopub.status.busy": "2026-09-06T03:27:10.259473Z", - "iopub.status.idle": "2026-09-06T03:27:10.271788Z", - "shell.execute_reply": "2026-09-06T03:27:10.271208Z" + "iopub.execute_input": "2026-10-27T13:39:04.255592Z", + "iopub.status.busy": "2026-10-27T13:39:04.255240Z", + "iopub.status.idle": "2026-10-27T13:39:04.277456Z", + "shell.execute_reply": "2026-10-27T13:39:04.276725Z" } }, "outputs": [ @@ -64,6 +64,7 @@ "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", @@ -73,7 +74,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\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", @@ -113,10 +114,10 @@ "id": "0370b26a", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.274083Z", - "iopub.status.busy": "2026-09-06T03:27:10.273898Z", - "iopub.status.idle": "2026-09-06T03:27:10.322724Z", - "shell.execute_reply": "2026-09-06T03:27:10.322209Z" + "iopub.execute_input": "2026-10-27T13:39:04.280261Z", + "iopub.status.busy": "2026-10-27T13:39:04.279970Z", + "iopub.status.idle": "2026-10-27T13:39:04.339064Z", + "shell.execute_reply": "2026-10-27T13:39:04.338480Z" } }, "outputs": [ @@ -171,10 +172,10 @@ "id": "596513ee", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.324876Z", - "iopub.status.busy": "2026-09-06T03:27:10.324675Z", - "iopub.status.idle": "2026-09-06T03:27:10.328421Z", - "shell.execute_reply": "2026-09-06T03:27:10.327974Z" + "iopub.execute_input": "2026-10-27T13:39:04.341287Z", + "iopub.status.busy": "2026-10-27T13:39:04.341075Z", + "iopub.status.idle": "2026-10-27T13:39:04.345164Z", + "shell.execute_reply": "2026-10-27T13:39:04.344671Z" } }, "outputs": [ @@ -228,10 +229,10 @@ "id": "54627f23", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.330418Z", - "iopub.status.busy": "2026-09-06T03:27:10.330254Z", - "iopub.status.idle": "2026-09-06T03:27:10.353157Z", - "shell.execute_reply": "2026-09-06T03:27:10.352562Z" + "iopub.execute_input": "2026-10-27T13:39:04.347324Z", + "iopub.status.busy": "2026-10-27T13:39:04.347150Z", + "iopub.status.idle": "2026-10-27T13:39:04.361047Z", + "shell.execute_reply": "2026-10-27T13:39:04.360568Z" } }, "outputs": [ @@ -274,10 +275,10 @@ "id": "b506ef81", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.356152Z", - "iopub.status.busy": "2026-09-06T03:27:10.355852Z", - "iopub.status.idle": "2026-09-06T03:27:10.360576Z", - "shell.execute_reply": "2026-09-06T03:27:10.359982Z" + "iopub.execute_input": "2026-10-27T13:39:04.363023Z", + "iopub.status.busy": "2026-10-27T13:39:04.362842Z", + "iopub.status.idle": "2026-10-27T13:39:04.366357Z", + "shell.execute_reply": "2026-10-27T13:39:04.365878Z" } }, "outputs": [ @@ -331,10 +332,10 @@ "id": "8ef303e6", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.363299Z", - "iopub.status.busy": "2026-09-06T03:27:10.363044Z", - "iopub.status.idle": "2026-09-06T03:27:10.368471Z", - "shell.execute_reply": "2026-09-06T03:27:10.367867Z" + "iopub.execute_input": "2026-10-27T13:39:04.368400Z", + "iopub.status.busy": "2026-10-27T13:39:04.368227Z", + "iopub.status.idle": "2026-10-27T13:39:04.372106Z", + "shell.execute_reply": "2026-10-27T13:39:04.371642Z" } }, "outputs": [ @@ -379,10 +380,10 @@ "id": "f8a51e0b", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.371519Z", - "iopub.status.busy": "2026-09-06T03:27:10.371226Z", - "iopub.status.idle": "2026-09-06T03:27:10.377717Z", - "shell.execute_reply": "2026-09-06T03:27:10.377114Z" + "iopub.execute_input": "2026-10-27T13:39:04.374011Z", + "iopub.status.busy": "2026-10-27T13:39:04.373835Z", + "iopub.status.idle": "2026-10-27T13:39:04.378729Z", + "shell.execute_reply": "2026-10-27T13:39:04.378239Z" } }, "outputs": [ @@ -428,10 +429,10 @@ "id": "36a7dead", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.380497Z", - "iopub.status.busy": "2026-09-06T03:27:10.380247Z", - "iopub.status.idle": "2026-09-06T03:27:10.385753Z", - "shell.execute_reply": "2026-09-06T03:27:10.385045Z" + "iopub.execute_input": "2026-10-27T13:39:04.380661Z", + "iopub.status.busy": "2026-10-27T13:39:04.380485Z", + "iopub.status.idle": "2026-10-27T13:39:04.384663Z", + "shell.execute_reply": "2026-10-27T13:39:04.384188Z" } }, "outputs": [ @@ -469,10 +470,10 @@ "id": "5f4c9a41", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.388635Z", - "iopub.status.busy": "2026-09-06T03:27:10.388252Z", - "iopub.status.idle": "2026-09-06T03:27:10.392818Z", - "shell.execute_reply": "2026-09-06T03:27:10.392303Z" + "iopub.execute_input": "2026-10-27T13:39:04.386586Z", + "iopub.status.busy": "2026-10-27T13:39:04.386397Z", + "iopub.status.idle": "2026-10-27T13:39:04.390539Z", + "shell.execute_reply": "2026-10-27T13:39:04.389932Z" } }, "outputs": [ @@ -508,10 +509,10 @@ "id": "4fd90c95", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.395584Z", - "iopub.status.busy": "2026-09-06T03:27:10.395322Z", - "iopub.status.idle": "2026-09-06T03:27:10.409768Z", - "shell.execute_reply": "2026-09-06T03:27:10.409254Z" + "iopub.execute_input": "2026-10-27T13:39:04.392576Z", + "iopub.status.busy": "2026-10-27T13:39:04.392392Z", + "iopub.status.idle": "2026-10-27T13:39:04.404759Z", + "shell.execute_reply": "2026-10-27T13:39:04.404233Z" } }, "outputs": [ @@ -551,10 +552,10 @@ "id": "b8b8874f", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.411877Z", - "iopub.status.busy": "2026-09-06T03:27:10.411696Z", - "iopub.status.idle": "2026-09-06T03:27:10.460851Z", - "shell.execute_reply": "2026-09-06T03:27:10.460342Z" + "iopub.execute_input": "2026-10-27T13:39:04.406866Z", + "iopub.status.busy": "2026-10-27T13:39:04.406687Z", + "iopub.status.idle": "2026-10-27T13:39:04.456283Z", + "shell.execute_reply": "2026-10-27T13:39:04.455749Z" } }, "outputs": [ @@ -592,10 +593,10 @@ "id": "d40029a6", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.463311Z", - "iopub.status.busy": "2026-09-06T03:27:10.463121Z", - "iopub.status.idle": "2026-09-06T03:27:10.476783Z", - "shell.execute_reply": "2026-09-06T03:27:10.476244Z" + "iopub.execute_input": "2026-10-27T13:39:04.458365Z", + "iopub.status.busy": "2026-10-27T13:39:04.458185Z", + "iopub.status.idle": "2026-10-27T13:39:04.471640Z", + "shell.execute_reply": "2026-10-27T13:39:04.471098Z" } }, "outputs": [ @@ -637,10 +638,10 @@ "id": "ef9c21e1", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.478897Z", - "iopub.status.busy": "2026-09-06T03:27:10.478709Z", - "iopub.status.idle": "2026-09-06T03:27:10.483883Z", - "shell.execute_reply": "2026-09-06T03:27:10.483320Z" + "iopub.execute_input": "2026-10-27T13:39:04.473767Z", + "iopub.status.busy": "2026-10-27T13:39:04.473589Z", + "iopub.status.idle": "2026-10-27T13:39:04.479135Z", + "shell.execute_reply": "2026-10-27T13:39:04.478650Z" } }, "outputs": [ @@ -685,10 +686,10 @@ "id": "07860c83", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.485871Z", - "iopub.status.busy": "2026-09-06T03:27:10.485696Z", - "iopub.status.idle": "2026-09-06T03:27:10.490009Z", - "shell.execute_reply": "2026-09-06T03:27:10.489600Z" + "iopub.execute_input": "2026-10-27T13:39:04.481134Z", + "iopub.status.busy": "2026-10-27T13:39:04.480959Z", + "iopub.status.idle": "2026-10-27T13:39:04.485414Z", + "shell.execute_reply": "2026-10-27T13:39:04.484906Z" } }, "outputs": [ @@ -729,10 +730,10 @@ "id": "7029af4d", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.491941Z", - "iopub.status.busy": "2026-09-06T03:27:10.491773Z", - "iopub.status.idle": "2026-09-06T03:27:10.495753Z", - "shell.execute_reply": "2026-09-06T03:27:10.495342Z" + "iopub.execute_input": "2026-10-27T13:39:04.487465Z", + "iopub.status.busy": "2026-10-27T13:39:04.487294Z", + "iopub.status.idle": "2026-10-27T13:39:04.491245Z", + "shell.execute_reply": "2026-10-27T13:39:04.490733Z" } }, "outputs": [ @@ -777,10 +778,10 @@ "id": "55b2d668", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.497728Z", - "iopub.status.busy": "2026-09-06T03:27:10.497556Z", - "iopub.status.idle": "2026-09-06T03:27:10.501141Z", - "shell.execute_reply": "2026-09-06T03:27:10.500755Z" + "iopub.execute_input": "2026-10-27T13:39:04.493254Z", + "iopub.status.busy": "2026-10-27T13:39:04.493079Z", + "iopub.status.idle": "2026-10-27T13:39:04.496944Z", + "shell.execute_reply": "2026-10-27T13:39:04.496479Z" } }, "outputs": [ @@ -819,10 +820,10 @@ "id": "fc426561", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.503124Z", - "iopub.status.busy": "2026-09-06T03:27:10.502911Z", - "iopub.status.idle": "2026-09-06T03:27:10.506639Z", - "shell.execute_reply": "2026-09-06T03:27:10.506218Z" + "iopub.execute_input": "2026-10-27T13:39:04.498875Z", + "iopub.status.busy": "2026-10-27T13:39:04.498696Z", + "iopub.status.idle": "2026-10-27T13:39:04.502516Z", + "shell.execute_reply": "2026-10-27T13:39:04.502054Z" } }, "outputs": [ @@ -870,10 +871,10 @@ "id": "b2c8a364", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.508607Z", - "iopub.status.busy": "2026-09-06T03:27:10.508438Z", - "iopub.status.idle": "2026-09-06T03:27:10.596352Z", - "shell.execute_reply": "2026-09-06T03:27:10.595905Z" + "iopub.execute_input": "2026-10-27T13:39:04.504516Z", + "iopub.status.busy": "2026-10-27T13:39:04.504330Z", + "iopub.status.idle": "2026-10-27T13:39:04.594045Z", + "shell.execute_reply": "2026-10-27T13:39:04.593318Z" } }, "outputs": [ @@ -932,10 +933,10 @@ "id": "76aa1a36", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.598424Z", - "iopub.status.busy": "2026-09-06T03:27:10.598243Z", - "iopub.status.idle": "2026-09-06T03:27:10.603008Z", - "shell.execute_reply": "2026-09-06T03:27:10.602572Z" + "iopub.execute_input": "2026-10-27T13:39:04.596615Z", + "iopub.status.busy": "2026-10-27T13:39:04.596401Z", + "iopub.status.idle": "2026-10-27T13:39:04.601831Z", + "shell.execute_reply": "2026-10-27T13:39:04.601245Z" } }, "outputs": [ @@ -984,10 +985,10 @@ "id": "e8ae2e98", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.605168Z", - "iopub.status.busy": "2026-09-06T03:27:10.604936Z", - "iopub.status.idle": "2026-09-06T03:27:10.609608Z", - "shell.execute_reply": "2026-09-06T03:27:10.609127Z" + "iopub.execute_input": "2026-10-27T13:39:04.604186Z", + "iopub.status.busy": "2026-10-27T13:39:04.604013Z", + "iopub.status.idle": "2026-10-27T13:39:04.609120Z", + "shell.execute_reply": "2026-10-27T13:39:04.608685Z" } }, "outputs": [ @@ -1048,10 +1049,10 @@ "id": "ccebd76b", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.611598Z", - "iopub.status.busy": "2026-09-06T03:27:10.611428Z", - "iopub.status.idle": "2026-09-06T03:27:10.769358Z", - "shell.execute_reply": "2026-09-06T03:27:10.768854Z" + "iopub.execute_input": "2026-10-27T13:39:04.611407Z", + "iopub.status.busy": "2026-10-27T13:39:04.611206Z", + "iopub.status.idle": "2026-10-27T13:39:04.768134Z", + "shell.execute_reply": "2026-10-27T13:39:04.767626Z" } }, "outputs": [ @@ -1111,10 +1112,10 @@ "id": "b1ff993b", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:10.771480Z", - "iopub.status.busy": "2026-09-06T03:27:10.771302Z", - "iopub.status.idle": "2026-09-06T03:27:10.777982Z", - "shell.execute_reply": "2026-09-06T03:27:10.777517Z" + "iopub.execute_input": "2026-10-27T13:39:04.770337Z", + "iopub.status.busy": "2026-10-27T13:39:04.770152Z", + "iopub.status.idle": "2026-10-27T13:39:04.776780Z", + "shell.execute_reply": "2026-10-27T13:39:04.776267Z" } }, "outputs": [ diff --git a/notebooks/08_monte_carlo_and_simulation/monte_carlo.ipynb b/notebooks/08_monte_carlo_and_simulation/monte_carlo.ipynb index 86a9d57..f0b25ca 100644 --- a/notebooks/08_monte_carlo_and_simulation/monte_carlo.ipynb +++ b/notebooks/08_monte_carlo_and_simulation/monte_carlo.ipynb @@ -39,10 +39,10 @@ "id": "5fe09c3f", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:13.675762Z", - "iopub.status.busy": "2026-09-06T03:27:13.675591Z", - "iopub.status.idle": "2026-09-06T03:27:13.688659Z", - "shell.execute_reply": "2026-09-06T03:27:13.687781Z" + "iopub.execute_input": "2026-10-27T13:39:16.080826Z", + "iopub.status.busy": "2026-10-27T13:39:16.080606Z", + "iopub.status.idle": "2026-10-27T13:39:16.094414Z", + "shell.execute_reply": "2026-10-27T13:39:16.093875Z" } }, "outputs": [ @@ -58,6 +58,7 @@ "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", @@ -67,7 +68,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/08_monte_carlo_and_simulation\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -101,10 +102,10 @@ "id": "ad74361b", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:13.690844Z", - "iopub.status.busy": "2026-09-06T03:27:13.690622Z", - "iopub.status.idle": "2026-09-06T03:27:14.891881Z", - "shell.execute_reply": "2026-09-06T03:27:14.891246Z" + "iopub.execute_input": "2026-10-27T13:39:16.096529Z", + "iopub.status.busy": "2026-10-27T13:39:16.096328Z", + "iopub.status.idle": "2026-10-27T13:39:17.131083Z", + "shell.execute_reply": "2026-10-27T13:39:17.130420Z" } }, "outputs": [ @@ -149,10 +150,10 @@ "id": "19230315", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:14.894138Z", - "iopub.status.busy": "2026-09-06T03:27:14.893922Z", - "iopub.status.idle": "2026-09-06T03:27:14.922589Z", - "shell.execute_reply": "2026-09-06T03:27:14.922017Z" + "iopub.execute_input": "2026-10-27T13:39:17.133217Z", + "iopub.status.busy": "2026-10-27T13:39:17.132998Z", + "iopub.status.idle": "2026-10-27T13:39:17.165668Z", + "shell.execute_reply": "2026-10-27T13:39:17.165139Z" } }, "outputs": [ @@ -190,10 +191,10 @@ "id": "d5169944", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:14.924699Z", - "iopub.status.busy": "2026-09-06T03:27:14.924481Z", - "iopub.status.idle": "2026-09-06T03:27:14.930519Z", - "shell.execute_reply": "2026-09-06T03:27:14.930020Z" + "iopub.execute_input": "2026-10-27T13:39:17.167741Z", + "iopub.status.busy": "2026-10-27T13:39:17.167511Z", + "iopub.status.idle": "2026-10-27T13:39:17.173933Z", + "shell.execute_reply": "2026-10-27T13:39:17.173482Z" } }, "outputs": [ @@ -228,10 +229,10 @@ "id": "0ac5d465", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:14.932496Z", - "iopub.status.busy": "2026-09-06T03:27:14.932322Z", - "iopub.status.idle": "2026-09-06T03:27:14.936139Z", - "shell.execute_reply": "2026-09-06T03:27:14.935642Z" + "iopub.execute_input": "2026-10-27T13:39:17.175925Z", + "iopub.status.busy": "2026-10-27T13:39:17.175741Z", + "iopub.status.idle": "2026-10-27T13:39:17.179815Z", + "shell.execute_reply": "2026-10-27T13:39:17.179333Z" } }, "outputs": [ @@ -269,16 +270,16 @@ "id": "359291e8", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:14.938309Z", - "iopub.status.busy": "2026-09-06T03:27:14.938137Z", - "iopub.status.idle": "2026-09-06T03:27:15.176868Z", - "shell.execute_reply": "2026-09-06T03:27:15.176249Z" + "iopub.execute_input": "2026-10-27T13:39:17.181816Z", + "iopub.status.busy": "2026-10-27T13:39:17.181633Z", + "iopub.status.idle": "2026-10-27T13:39:17.400219Z", + "shell.execute_reply": "2026-10-27T13:39:17.399640Z" } }, "outputs": [ { "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAAAckAAAHBCAYAAAACbEAcAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjYsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvq6yFwwAAAAlwSFlzAAAPYQAAD2EBqD+naQABAABJREFUeJzsfXl4VcX9/nuX7CEXQkgggUCUTSQsoiymgAsqaivFBbpZxA0UviqorVptXdpStSIqILiidQNFxAVREFdA68JakUXCL0oCIQQSErgk9+b8/jiZkzlzZ86Zs93E9r7P4yM5d85sZ2Y+89l9iqIoSCCBBBJIIIEEYuBv7Q4kkEACCSSQQFtFgkgmkEACCSSQgAAJIplAAgkkkEACAiSIZAIJJJBAAgkIkCCSCSSQQAIJJCBAgkgmkEACCSSQgAAJIplAAgkkkEACAiSIZAIJJJBAAgkIkCCSCSSQQAIJJCBAgkhKYuPGjbjwwgtRWFiItLQ0ZGdnY8SIEXjhhRek66irq8NNN92E/Px8pKamYtCgQXjllVe4Zb/55huMGTMGmZmZaN++PS6++GLs3r2bW/axxx5D3759kZKSgqKiItxzzz1obGy0NU4RNmzYgNGjRyMUCsHn82HOnDncchUVFbjzzjsxYsQI5OTkICsrC0OGDMETTzyBaDQaU96rOXH6vuycVlZW4oorrkBOTg7S09MxYsQIfPDBB9J94uGMM87AGWec4agOFkePHsXdd9+Njz76yNV6WwN///vf8cYbb8Q8/+ijj+Dz+VpljD+V+X300UcxfPhw5OTkICUlBYWFhfjVr36F//znP1Lvv/322/j973+P4uJiJCUlwefzccv98MMPGD9+PE444QRkZGQgFAph8ODBmDt3LiKRSEz5pUuXoqSkBNnZ2Wjfvj2GDh2Kf/3rXzHlamtr8ac//Qm9e/dGeno6CgoKcNlll0n33xaUBKTw4YcfKlOmTFH+9a9/KWvWrFHeeust5Ve/+pUCQLnvvvuk6jjnnHOU9u3bKwsWLFDWrFmjXH311QoA5cUXX9SV27Ztm9KuXTtl5MiRyjvvvKMsXbpUOfnkk5X8/HylsrJSV/avf/2r4vP5lNtvv1358MMPlQceeEBJTk5WrrnmGtfGriiKMmjQIKVXr17KihUrlPXr1ysVFRXccm+99ZbSrVs35U9/+pPyzjvvKO+//74yY8YMxe/3K5MnT44p78Wc8ODFnIbDYaV///5K165dlRdeeEF5//33lXHjxinBYFD56KOPTPskwujRo5XRo0fbfp+HAwcOKACUv/zlL67W2xrIyMhQJk2aFPO8pqZGWb9+vVJTUxP3Pv1U5vfPf/6zcvfddyvLli1TPvroI+WZZ55RevfurWRkZCjfffed6ftXXnml0qtXL2XChAnKkCFDFBEJ2bZtm/L73/9eeeaZZ5TVq1crK1asUKZPn64AUK666ipd2aeffloBoFxyySXKihUrlHfffVc7W2fPnq0rO2rUKCU9PV154IEHlDVr1ijPP/+80rNnT6Vdu3bKnj177E+MARJE0iGGDRumdOvWzbTcO++8owBQXnrpJd3zc845R8nPz1cikYj27LLLLlNycnJ0m33Pnj1KUlKS8oc//EF7VlVVpaSmpirXXnutrs6//e1vis/nU/7zn//YHVYMgsGgct1115mWq66uVhoaGmKeT5s2TQGglJWVac+8mBMRvJjTefPmKQCUdevWac8aGxuVfv36KUOHDjXtkwhuEsmmpibl6NGjP5lDXAYiItma+CnP77fffqsAUO666y7TstFoVPs32dNWMGHCBCUYDCrhcFh7VlJSonTv3l1Xd1NTk9K3b19lwIAB2rOdO3cqAJQ777xTV+e6deu4BNUtJMStDpGTk4NgMGhabtmyZcjMzMRll12mez558mSUl5fjiy++AABEIhG8/fbbuOSSS5CVlaWV6969O84880wsW7ZMe7Zy5UqEw2FMnjw5pk5FUbgiKRZbt27FuHHj0KFDB03c+dxzz2m/L1q0CD6fD5FIBI8//jh8Pp9QxAIAHTp0QFJSUszzoUOHAgB+/PFHT+eEB6/mdNmyZejTpw9GjBihPQsGg/jd736Hf//739i7d69hvxRFwQMPPIDu3bsjNTUVp5xyCt59992YcuFwGDfffDMGDRqEUCikifqXL18eU9bn82H69OlYsGABTjrpJKSkpOC5555Dp06dAAD33HOP9g2vuOIKAMCBAwdw7bXXolu3bkhJSUGnTp1QUlKC1atXG/bfChRFwfz58zFo0CCkpaWhQ4cOuPTSS2PE3Rs2bMDPf/5z5ObmIiUlBfn5+bjwwgu1dePz+VBfX4/nnntOGwcRTfPErVdccQUyMzPx3Xff4bzzzkNGRga6dOmCf/zjHwCAzz//HD/72c+QkZGB3r1769Y+mZvrr78e/fr1Q2ZmJnJzc3HWWWfh008/1crs2bPHcH4BYOfOnfjNb36jjeukk07CvHnz3JpeRyB9lznH/H5nJKNTp07w+/0IBALas6SkJGRmZurq9vl8yMrKQmpqqq4cAIRCIV2d7du3BwBdWVfhCen9L0Y0GlUaGxuVyspKZd68eUowGFQWLFhg+t7w4cOV0047Leb51q1bFQDKwoULFUVRlO+++04BoMybNy+m7C233KL4fD7l2LFjiqIoym233aYAUOrq6mLK5uTkKL/+9a8N+/Tdd98p7dq1U0488UTl+eefV9555x3l17/+tQJAuf/++xVFUZTKykpl/fr1CgDl0ksvVdavX6+sX7/edLwsJk2apASDQaWqqkp75sWciMbpxZx27txZueyyy2LKvf322woA5b333hP2SVEU5S9/+Ysmfnr33XeVJ554QikoKFA6d+6s4yQPHz6sXHHFFZqof+XKlcott9yi+P1+5bnnntPVCUApKChQBgwYoLz00kvKmjVrlI0bNyorV67U2iLfcNeuXYqiKMp5552ndOrUSXniiSeUjz76SHnjjTeUP//5z8orr7xi2H8ruOaaa5SkpCTl5ptvVlauXKm89NJLSt++fZW8vDxl3759iqIoSl1dndKxY0fl1FNPVZYsWaJ8/PHHyuLFi5WpU6cq3377raIoirJ+/XolLS1NueCCC7RxEO7+ww8/VAAoH374odbupEmTlOTkZOWkk05SHnnkEWXVqlXK5MmTFQDK7bffrvTu3Vt5+umnlffee0/5+c9/rgBQvvrqK+397777TrnuuuuUV155Rfnoo4+Ut99+W7nqqqsUv9+vtRMOhw3n9z//+Y8SCoWU4uJi5fnnn1fef/995eabb1b8fr9y9913m85dJBJRGhsbTf+jOTGZOsPhsLJt2zZl3LhxSm5urk7KIwMZTrKpqUlpbGxUqqurlVdeeUXJyMhQbr/9dl2ZpUuXKn6/X/nrX/+qVFZWKgcOHFAefPBBJRAIKEuWLNGVHTdunJKfn6+sWbNGOXLkiLJt2zZlzJgxSmFhoVJdXW2p/7JIEEmLmDJligJAAaAkJycr8+fPl3qvV69eynnnnRfzvLy8XAGg/P3vf1cURVHWrl2rAFBefvnlmLJ///vfFQBKeXm5oijqwZOSksJtr3fv3sq5555r2Kdf/epXSkpKSszmOP/885X09HTl8OHD2jMAyrRp04wHKcB7772n+P1+ZcaMGbrnXswJD17NaVJSkjJlypSYckT8w4qRaRw6dEhJTU1Vxo8fz+2rkbiVHJpXXXWVMnjwYN1vAJRQKBRzYBiJAzMzM5WbbrpJ2J5TkEvWQw89pHv+ww8/KGlpaZq4+6uvvlIAKG+88YZhfSJxq4hIAlCWLl2qPWtsbFQ6deqkAFC++eYb7fnBgweVQCCgzJw5U9g2mfuzzz5b9+2M5ve8885TunbtGqMrnT59upKammp6uI8ePVo7c4z+syKCTklJ0d7r3bu3dgmxAhkiOWvWLK0dn8+n/OlPf+KWe+ONN5RQKKSVTUtLU1544YWYcg0NDco111yjG/eAAQOU0tJSy/2XhTl/nYAOd9xxB66++mpUVlbirbfewvTp01FfX49bbrnF9F0jMSX7m2xZK3WyWLNmDc4++2x069ZN9/yKK67Au+++i/Xr12Ps2LGGdZjhm2++wYQJEzB8+HDMmjXLUh/tzomdMnbn1G6f1q9fj3A4jN/+9re656effjq6d+8eU/7VV1/FnDlzsGnTJtTX12vPeSKms846Cx06dBC2zWLo0KFYtGgROnbsiDFjxmDIkCFckbldvP322/D5fPjd736ns2zs3LkzBg4cqIlHe/bsiQ4dOuCPf/wjKioqMGrUKPTr189x+z6fDxdccIH2dzAYRM+ePREMBjF48GDteXZ2NnJzc/H//t//072/YMECPPHEE/j2229x/Phx7Xnfvn1N2w6Hw/jggw9w3XXXIT09XTf+Cy64AHPnzsXnn3+O888/X1jHwoULceTIEdO2cnJyTMsQrFu3Dg0NDfj+++/x8MMP48wzz8QHH3yAk08+WboOGVxxxRUYM2YMqqursWbNGjz44IOoqanBY489ppVZuXIlfve73+Gyyy7DhAkTEAwG8eabb+KKK65AQ0ODTvVx3XXXYdmyZXj44YdxyimnYN++fXjwwQdx1lln4cMPP+TuHadIEEmLKCwsRGFhIQBoG+/222/HpEmTNNk+Dx07dsTBgwdjnldXVwNQNygpB0BY1ufzaTL4jh07IhwO4+jRo0hPT48pO2TIEMOxHDx4EF26dIl5np+fL+yDFWzYsAHnnHMOevXqhRUrViAlJUX3uxdzwoNXcyrbfx7Ie507d475jX32+uuvY8KECbjssstw6623onPnzggGg3j88cfxzDPPxLzP+6ZGWLx4Mf7617/iqaeewl133YXMzEyMHz8eDzzwALd/VrF//34oioK8vDzu7yeccAIAVdf08ccf429/+xvuuOMOHDp0CF26dME111yDO++80zbhTk9Pj7lMJCcnc79PcnIywuGw9vfs2bNx8803Y+rUqbjvvvuQk5ODQCCAu+66C9u2bTNt++DBg4hEInjsscd0hIFGVVWVYR09e/aEoiimbVnRF55yyikAgOHDh+Oiiy5Cz549cccdd3D13E7QuXNnbQ2de+656NChA2677TZceeWVGDx4MBRFwZVXXolRo0bp1vKYMWNQU1OD//u//8OECROQkZGBlStX4umnn8arr76KSy+9VCt77rnnokePHrj77rvx7LPPutp/IEEkHWPo0KFYsGABdu/ebUgki4uL8fLLLyMSiegU5Fu2bAEA9O/fHwBw4oknIi0tTXtOY8uWLejZs6e24YuLi7Xnw4YN08rt27cPVVVVWp0idOzYERUVFTHPy8vLAVi7mbLYsGEDxowZg+7du+P999+PUbaT/rs9Jzx4NafFxcXCOun+80AI9759+2J+27dvH3r06KH9/cILL6CoqAiLFy/Wcac0V0NDhqumkZOTgzlz5mDOnDkoKyvDm2++idtuuw2VlZVYuXKlpbpE9ft8Pnz66acxFyUAumfFxcV45ZVXoCgKNm/ejEWLFuHee+9FWloabrvtNsd9sYoXXngBZ5xxBh5//HHdcxnODlAN2QKBAC6//HJMmzaNW6aoqMiwjrPPPhsff/yxaVuTJk3CokWLpPpFo127dujbty927Nhh+V2rIAZ8O3bswODBg7F//35UVFRgypQpMWVPO+00PP/889izZw9OPvlkbNy4UXtOo3379ujZsye2bt3qSZ8T1q0O8eGHH8Lv92u3YRHGjx+Puro6LF26VPf8ueeeQ35+vnYgB4NB/OIXv8Drr7+u24hlZWX48MMPcfHFF2vPxo4di9TU1JiNQSxSf/nLXxr26eyzz8aaNWs0okjw/PPPIz09HcOHDzd8X4SNGzdizJgx6Nq1K1atWiUU/XkxJzx4Nafjx4/Hd999p1nhAqol7QsvvIBhw4ZpHDkPw4cPR2pqKl588UXd83Xr1sWI+3w+H5KTk3XEb9++fZZu/YQQHTt2zLBcYWEhpk+fjnPOOQfffPONdP1G+PnPfw5FUbB3716ceuqpMf+RiwkNn8+HgQMH4uGHH0b79u11fUlJSTEdh1vw+XwxhH3z5s1Yv3697ploftPT03HmmWdiw4YNGDBgAHf85MIkwsKFC/Hll1+a/nf33XfbGmNVVZV2WfQaH374IQBobRGr+s8//zym7Pr16+H3+zXJCNlPbNmDBw9ix44d6Nq1qzed9kzb+V+Ga665Rrn55puVxYsXKx999JHy2muvKRMnTlQAKLfeequu7LPPPqsAUJ599lnd83POOUfp0KGD8sQTTyhr1qzRFNCsgnrbtm1KZmamMmrUKGXFihXK66+/rvTv39/Q8f2OO+5QPvroI+XBBx9UUlJSpIIJEOvW3r17Ky+88IKyYsUK5be//a0CQHnggQd0ZSFpuPPdd98pHTt2VLKzs5W33npLs/Qj/7H992JOiKGD13MaDoeVk08+WenWrZvy4osvKqtWrVLGjx8vHUzgzjvv1CwiV65cqTz55JNc69ZnnnlGAaBcd911ygcffKAsWrRIOfHEE5VevXrFjNPoO3Xv3l3p06eP8t577ylffvmlUlpaqhw+fFgZPHiw8uCDDypvvfWWNt7U1FTlN7/5jekYZHHttdcq6enpyq233qq89dZbypo1a5QXX3xRue666zTjt7feeks5//zzlYULFyqrVq1S3n//fWXq1KkKAOWJJ57Q6ho9erSSm5urvPnmm8qXX36pOcGLDHcyMjJi+jN69Gjl5JNP5s7RhRdeqP395z//WfH5fMqf//xn5YMPPlDmz5+vdO7cWTnxxBOV7t27x7zLzq+iqNatHTp0UIYOHao8++yzyocffqi8+eabyuzZs5UzzzzT7pRaxuHDh5XTTjtNefjhh5W3335b+eCDD5THH39c6du3r5Kenq58+eWXuvKBQEA566yzdM/27NmjvPrqq8qrr76qjB07VgGg/U2//+c//1mZMmWK8uKLL2oW01OnTlUCgUCMRfjMmTMVAMrll1+uvP3228q7776rGUjSgQeOHDmidO/eXenQoYPyz3/+U1tDgwYNUgKBgO67u4kEkZTEM888o4wcOVLJyclRgsGg0r59e2X06NHKv/71r5iyjz32mAJAWblype75kSNHlBtuuEHp3LmzkpycrAwYMIBrcakoqqXf2Wef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sRG9e/dGXl6e6/OQ4s1ffvnlMSGUfiy191hqKxC2N2gcS+09ltoKfDPbaxgGDh48iJqaGuTny3cdv5GeZH5+Pvr37+/b+UpLS4+JwUVwLLX3WGorELY3aBxL7T2W2gp889rr5EEShMSdECFChAgRQoDQSIYIESJEiBAChEbSA4qKinDnnXeiqKgo201RwrHU3mOprUDY3qBxLLX3WGorELbXCd9I4k6IECFChAihgtCTDBEiRIgQIQQIjWSIECFChAghQGgkQ4QIESJECAFCIxkiRIgQIUIIEBpJCX71q1/hjDPOQI8ePXDccccp/cYwDCxYsAA1NTUoKSnBWWedhY8//th2TGdnJ37yk5+gvLwcPXv2xIUXXohdu3Z5bm9raytmzJiBWCyGWCyGGTNm4MCBA9Lf5OXlcf/79a9/bR1z1llnpf39iiuuyHhbf/SjH6W1Y/z48bZjcqVvu7u78bOf/Qy1tbXo2bMnampq8K//+q9obGy0HedX3z722GMYMmQIiouLMXbsWLz77rvS49955x2MHTsWxcXFOOGEE/D444+nHfPSSy/hpJNOQlFREU466SQsW7ZMu11+tPfll1/Geeedh+OPPx6lpaWYMGEC/vrXv9qOefrpp7njuKOjI+Ptffvtt7lt+fTTT23H5Ur/8t6rvLw8nHzyydYxQfXv3/72N/zzP/8zampqkJeXhz/96U+Ov8n42DVCCPHzn//cWLhwoTFv3jwjFosp/ebee+81evfubbz00kvGpk2bjMsvv9yorq422tvbrWPmzJlj9OvXz1i5cqXxwQcfGGeffbZxyimnGPF43FN7p06daowaNcpYvXq1sXr1amPUqFHGtGnTpL9pamqy/ffUU08ZeXl5xmeffWYdM2nSJGPWrFm24w4cOJDxts6cOdOYOnWqrR379++3HZMrfXvgwAFj8uTJxtKlS41PP/3UWLNmjTFu3Dhj7NixtuP86Nvnn3/eKCgoMJ544gljy5Ytxk033WT07NnT+OKLL7jH79y50+jRo4dx0003GVu2bDGeeOIJo6CgwPjjH/9oHbN69WojEokYd999t/HJJ58Yd999txGNRo21a9dqtc2P9t50003GfffdZ7z33nvGtm3bjNtvv90oKCgwPvjgA+uYxYsXG6WlpWnj2Q/otvett94yABhbt261tYUeg7nUvwcOHLC188svvzTKysqMO++80zomqP79y1/+Yvznf/6n8dJLLxkAjGXLlkmPz8bYDY2kAhYvXqxkJJPJpFFVVWXce++91ncdHR1GLBYzHn/8ccMwzAFZUFBgPP/889YxX331lZGfn2+sWLHCdRu3bNliALANhDVr1hgAjE8//VT5PBdddJFxzjnn2L6bNGmScdNNN7luGwu3bZ05c6Zx0UUXCf+e63373nvvGQBsk5UffXv66acbc+bMsX03cuRI47bbbuMe/9Of/tQYOXKk7bvZs2cb48ePtz7X1dUZU6dOtR1z/vnnG1dccYWntrppLw8nnXSScdddd1mfVd9RN9BtLzGSra2twnPmcv8uW7bMyMvLMz7//HPruyD7l0DFSGZj7IbhVh9RX1+P3bt3Y8qUKdZ3RUVFmDRpElavXg0AWL9+Pbq7u23H1NTUYNSoUdYxbrBmzRrEYjGMGzfO+m78+PGIxWLK592zZw+WL1+Oa665Ju1vzz77LMrLy3HyySfj1ltvtSqpZLqtb7/9NioqKjB8+HDMmjULzc3N1t9yuW8BoK2tDXl5eWmhey9929XVhfXr19vuGQCmTJkibNuaNWvSjj///PPxj3/8A93d3dJjvPSj2/aySCaTOHjwIMrKymzfHzp0CIMGDUL//v0xbdo0bNiwwVNbvbZ3zJgxqK6uxrnnnou33nrL9rdc7t8nn3wSkydPxqBBg2zfB9G/usjG2P1GCpwHhd27dwMAKisrbd9XVlbiiy++sI4pLCxEnz590o4hv3d77YqKirTvKyoqlM+7ZMkS9O7dG5dccont+6uuugpDhgxBVVUVNm/ejNtvvx0ffvghVq5cmdG2XnDBBbjsssswaNAg1NfX44477sA555yD9evXo6ioKKf7tqOjA7fddhuuvPJKmyiz177dt28fEokEd8yJ2rZ7927u8fF4HPv27UN1dbXwGC/96La9LB544AF8/fXXqKurs74bOXIknn76adTW1qK9vR0PPfQQJk6ciA8//BDDhg3LaHurq6vx29/+FmPHjkVnZyd+//vf49xzz8Xbb7+NM888E4D4GWS7f5uamvDaa6/hueees30fVP/qIhtj9xtnJBcsWIC77rpLesz777+P0047zfU12PJbhmE4luQSHaPaXt51Va9N8NRTT+Gqq65CcXGx7ftZs2ZZ/z9q1CgMGzYMp512Gj744AOceuqpGWvr5ZdfbmvHaaedhkGDBmH58uVphl3lvJnq2+7ublxxxRVIJpN47LHHbH9T7Vsn6I453vHs927GsSrcnvsPf/gDFixYgFdeecW2cBk/fryNxDVx4kSceuqpePjhh/Gb3/wmo+0dMWIERowYYX2eMGECvvzyS/zXf/2XZSR1zxlke2k8/fTTOO6443DxxRfbvg+6f3WQ6bH7jTOSc+fOdWQPDh482NW5q6qqAJirnerqauv75uZma2VTVVWFrq4utLa22jye5uZmnHHGGa7b+9FHH2HPnj1pf9u7d2/aqoqHd999F1u3bsXSpUsdjz311FNRUFCA7du32ybyTLWVoLq6GoMGDcL27dsB5Gbfdnd3o66uDvX19XjzzTcdS/uI+laE8vJyRCKRtFUyPeZYVFVVcY+PRqPo27ev9Bid5+NXewmWLl2Ka665Bi+++CImT54sPTY/Px/f+c53rLGRjfbSGD9+PJ555hnrcy72r2EYeOqppzBjxgwUFhZKj/Wrf3WRlbHraifzGwZd4s59991nfdfZ2ckl7ixdutQ6prGx0Tdyybp166zv1q5dq0wumTlzZhrzUoRNmzYZAIx33nknK20l2Ldvn1FUVGQsWbLEMIzc69uuri7j4osvNk4++WSjublZ6Vpu+vb00083rr/+ett3J554opS4c+KJJ9q+mzNnThr54YILLrAdM3XqVN+IJTrtNQzDeO6554zi4mJHYgdBMpk0TjvtNOPqq6/20lTDMNy1l8Wll15qnH322dbnXOtfw0gRjjZt2uR4DT/7lwCKxJ1Mj93QSErwxRdfGBs2bDDuuusuo1evXsaGDRuMDRs2GAcPHrSOGTFihPHyyy9bn++9914jFosZL7/8srFp0ybjhz/8ITcFpH///sbrr79ufPDBB8Y555zjW5rCt7/9bWPNmjXGmjVrjNra2rQ0Bba9hmEYbW1tRo8ePYz//u//Tjvnjh07jLvuust4//33jfr6emP58uXGyJEjjTFjxnhqr25bDx48aMyfP99YvXq1UV9fb7z11lvGhAkTjH79+uVk33Z3dxsXXnih0b9/f2Pjxo022nxnZ6dhGP71LaH8P/nkk8aWLVuMm2++2ejZs6fFTrztttuMGTNmWMcTGv0tt9xibNmyxXjyySfTaPSrVq0yIpGIce+99xqffPKJce+99/qeoqDa3ueee86IRqPGo48+KkyVWbBggbFixQrjs88+MzZs2GBcffXVRjQatS1sMtXeBx980Fi2bJmxbds2Y/PmzcZtt91mADBeeukl65hc6l+Cf/mXfzHGjRvHPWdQ/Xvw4EFrXgVgLFy40NiwYYPFAM+FsRsaSQlmzpxpAEj776233rKOAWAsXrzY+pxMJo0777zTqKqqMoqKiowzzzwzbWV25MgRY+7cuUZZWZlRUlJiTJs2zWhoaPDc3v379xtXXXWV0bt3b6N3797GVVddlUZDZ9trGIaxaNEio6SkhJuf19DQYJx55plGWVmZUVhYaHzrW98ybrzxxrT8xKDbevjwYWPKlCnG8ccfbxQUFBgDBw40Zs6cmdZvudK39fX13LFDjx8/+/bRRx81Bg0aZBQWFhqnnnqqzROdOXOmMWnSJNvxb7/9tjFmzBijsLDQGDx4MHeB9OKLLxojRowwCgoKjJEjR9omea/Qae+kSZO4/Thz5kzrmJtvvtkYOHCgUVhYaBx//PHGlClTjNWrV2elvffdd5/xrW99yyguLjb69OljfPe73zWWL1+eds5c6V/DMKMwJSUlxm9/+1vu+YLqX+K9ip5tLozdsFRWiBAhQoQIIUCYJxkiRIgQIUIIEBrJECFChAgRQoDQSIYIESJEiBAChEYyRIgQIUKEECA0kiFChAgRIoQAoZEMESJEiBAhBAiNZIgQIUKECCFAaCRDhAgRIkQIAUIjGSJEiBAhQggQGskQIUKECBFCgNBIhggRIkSIEAKERjJEiBAhQoQQ4P8HMpk3SsivuTYAAAAASUVORK5CYII=", + "image/png": "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v/xy3HXXXejRoweioqLw7LPPYunSpSHXi96pGVasWIGHH34YL774Iu6//3507NgRU6dOxZ///Gdh/+yisrIShBCkpqYK/37yyScD0HxNH3/8MR555BH84Q9/wM8//4yePXti1qxZuO+++xwL7oSEhJDNRExMjPD9xMTEoKGhQf/9r3/9K+bOnYubb74ZDz30ELp164bIyEjcf//9KC4utrx3dXU1Tpw4gaeeesogGFgcOHDAtI2BAweCEGJ5Lzv+whEjRgAAxo4di1/+8pcYOHAg/vCHPwj93G7Qo0cPfQ5NnjwZXbp0wd13342ZM2di+PDhIIRg5syZOOusswxzOScnBzU1NfjNb36DadOmoUOHDvjoo4/w0ksv4a233sJll12mnzt58mT069cP8+bNw8svv+xp/4GwkHSNMWPG4LnnnsO///1vUyE5ZMgQvPHGGzhx4oTBQb5jxw4AwKmnngoAGDBgAOLj4/XjLHbs2IGBAwfqH/yQIUP046effrp+XkVFBQ4cOKC3KUNycjLKy8tDju/btw+AvZ0pj6+//ho5OTno27cv1q1bF+Jsp/33ekxE8GtMhwwZIm2T7b8IVHBXVFSE/K2iogL9+vXTf1++fDn69++PFStWGLRTVqthoaJVs+jWrRsWLVqERYsWoaysDKtWrcLdd9+NqqoqfPTRR7bakrUfCASwefPmkI0SAMOxIUOG4M033wQhBN988w2WLVuG+fPnIz4+HnfffbfrvtjF8uXLMXHiRDz77LOG4yqaHaAFskVGRuLqq6/G7Nmzhef079/ftI1Jkybh448/trzXjBkzsGzZMqV+sejUqRMyMjLw3Xff2b7WLmgA33fffYfhw4ejsrIS5eXluOmmm0LOHT16NF599VXs3r0bgwcPxrZt2/TjLDp37oyBAwfi22+/9aXP4ehWl8jPz0dERIS+G5Zh6tSpOHz4MFauXGk4/sorr6BXr176ghwVFYULL7wQ77zzjuFDLCsrQ35+Pi655BL92DnnnIO4uLiQD4NGpF588cWmfZo0aRI2btyoC0WKV199FQkJCRg7dqzp9TJs27YNOTk56N27N/Ly8qSmPz/GRAS/xnTq1KkoKSnRo3ABLZJ2+fLlOP3003WNXISxY8ciLi4Or732muH4li1bQsx9gUAAMTExBuFXUVFha9dPBVF9fb3peWlpabjtttuQ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", "text/plain": [ "
" ] @@ -290,20 +291,24 @@ "name": "stdout", "output_type": "stream", "text": [ - "drawn: the first 3,000 of 200,000 darts\n" + "drawn: the first 3,000 of 200,000 darts\n", + "Figure: 3,000 darts in the unit square, 2,369 inside the quarter circle (dots) and 631 outside it (crosses); the boundary between them is the arc x^2 + y^2 = 1.\n" ] } ], "source": [ "show = 3000\n", "fig, ax = plt.subplots(figsize=(5, 5))\n", - "ax.scatter(xs[:show][inside[:show]], ys[:show][inside[:show]], s=2, label=\"inside\")\n", - "ax.scatter(xs[:show][~inside[:show]], ys[:show][~inside[:show]], s=2, label=\"outside\")\n", + "ax.scatter(xs[:show][inside[:show]], ys[:show][inside[:show]], s=4, marker=\"o\", label=\"inside\")\n", + "ax.scatter(xs[:show][~inside[:show]], ys[:show][~inside[:show]], s=10, marker=\"x\", lw=0.6, label=\"outside\")\n", "ax.set_aspect(\"equal\")\n", "ax.set_title(f\"{show:,} of {n:,} darts estimate = {pi_hat:.4f}\")\n", "ax.legend(loc=\"upper right\", markerscale=4)\n", "plt.show()\n", - "print(f\"drawn: the first {show:,} of {n:,} darts\")\n" + "print(f\"drawn: the first {show:,} of {n:,} darts\")\n", + "print(f\"Figure: {show:,} darts in the unit square, {int(inside[:show].sum()):,} inside the quarter circle \"\n", + " f\"(dots) and {show - int(inside[:show].sum()):,} outside it (crosses); the boundary between them \"\n", + " f\"is the arc x^2 + y^2 = 1.\")\n" ] }, { @@ -328,10 +333,10 @@ "id": "d1e1ec75", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:15.179353Z", - "iopub.status.busy": "2026-09-06T03:27:15.179108Z", - "iopub.status.idle": "2026-09-06T03:27:15.183913Z", - "shell.execute_reply": "2026-09-06T03:27:15.183433Z" + "iopub.execute_input": "2026-10-27T13:39:17.402189Z", + "iopub.status.busy": "2026-10-27T13:39:17.401999Z", + "iopub.status.idle": "2026-10-27T13:39:17.406387Z", + "shell.execute_reply": "2026-10-27T13:39:17.405921Z" } }, "outputs": [ @@ -390,10 +395,10 @@ "id": "25e55a1c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:15.186344Z", - "iopub.status.busy": "2026-09-06T03:27:15.186145Z", - "iopub.status.idle": "2026-09-06T03:27:15.193745Z", - "shell.execute_reply": "2026-09-06T03:27:15.193184Z" + "iopub.execute_input": "2026-10-27T13:39:17.408459Z", + "iopub.status.busy": "2026-10-27T13:39:17.408276Z", + "iopub.status.idle": "2026-10-27T13:39:17.415368Z", + "shell.execute_reply": "2026-10-27T13:39:17.414976Z" } }, "outputs": [ @@ -432,10 +437,10 @@ "id": "45ed4d06", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:15.195863Z", - "iopub.status.busy": "2026-09-06T03:27:15.195683Z", - "iopub.status.idle": "2026-09-06T03:27:15.200565Z", - "shell.execute_reply": "2026-09-06T03:27:15.200103Z" + "iopub.execute_input": "2026-10-27T13:39:17.417384Z", + "iopub.status.busy": "2026-10-27T13:39:17.417205Z", + "iopub.status.idle": "2026-10-27T13:39:17.423127Z", + "shell.execute_reply": "2026-10-27T13:39:17.422610Z" } }, "outputs": [ @@ -475,10 +480,10 @@ "id": "2ae52645", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:15.202404Z", - "iopub.status.busy": "2026-09-06T03:27:15.202237Z", - "iopub.status.idle": "2026-09-06T03:27:15.438942Z", - "shell.execute_reply": "2026-09-06T03:27:15.438408Z" + "iopub.execute_input": "2026-10-27T13:39:17.425252Z", + "iopub.status.busy": "2026-10-27T13:39:17.425073Z", + "iopub.status.idle": "2026-10-27T13:39:17.668850Z", + "shell.execute_reply": "2026-10-27T13:39:17.668300Z" } }, "outputs": [ @@ -491,6 +496,13 @@ }, "metadata": {}, "output_type": "display_data" + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Figure: a histogram of 200,000 draws following the bell-shaped true density, centred at 1, with the area between 3 and 6 shaded; that area is 0.1133 of the draws.\n" + ] } ], "source": [ @@ -503,7 +515,9 @@ "ax.fill_between(grid[band], dens[band], alpha=0.6, label=\"[3, 6]\")\n", "ax.set_title(f\"P(3 <= X <= 6) = {p_hat:.4f}\")\n", "ax.legend()\n", - "plt.show()" + "plt.show()\n", + "print(f\"Figure: a histogram of {len(sims):,} draws following the bell-shaped true density, \"\n", + " f\"centred at 1, with the area between 3 and 6 shaded; that area is {p_hat:.4f} of the draws.\")" ] }, { @@ -528,10 +542,10 @@ "id": "0a6d134f", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:15.441247Z", - "iopub.status.busy": "2026-09-06T03:27:15.441070Z", - "iopub.status.idle": "2026-09-06T03:27:15.462611Z", - "shell.execute_reply": "2026-09-06T03:27:15.462031Z" + "iopub.execute_input": "2026-10-27T13:39:17.670840Z", + "iopub.status.busy": "2026-10-27T13:39:17.670655Z", + "iopub.status.idle": "2026-10-27T13:39:17.692698Z", + "shell.execute_reply": "2026-10-27T13:39:17.692252Z" } }, "outputs": [ @@ -582,10 +596,10 @@ "id": "70779f1d", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:15.464583Z", - "iopub.status.busy": "2026-09-06T03:27:15.464412Z", - "iopub.status.idle": "2026-09-06T03:27:15.469247Z", - "shell.execute_reply": "2026-09-06T03:27:15.468779Z" + "iopub.execute_input": "2026-10-27T13:39:17.694875Z", + "iopub.status.busy": "2026-10-27T13:39:17.694692Z", + "iopub.status.idle": "2026-10-27T13:39:17.700238Z", + "shell.execute_reply": "2026-10-27T13:39:17.699721Z" } }, "outputs": [ @@ -630,10 +644,10 @@ "id": "9da9ca3d", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:15.471353Z", - "iopub.status.busy": "2026-09-06T03:27:15.471187Z", - "iopub.status.idle": "2026-09-06T03:27:16.029512Z", - "shell.execute_reply": "2026-09-06T03:27:16.028975Z" + "iopub.execute_input": "2026-10-27T13:39:17.702319Z", + "iopub.status.busy": "2026-10-27T13:39:17.702142Z", + "iopub.status.idle": "2026-10-27T13:39:18.180892Z", + "shell.execute_reply": "2026-10-27T13:39:18.180358Z" } }, "outputs": [ @@ -646,6 +660,13 @@ }, "metadata": {}, "output_type": "display_data" + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Figure: the running estimate of P(lose) over 200,000 games (log scale) wobbles at first and settles near the exact value 0.01312 (dashed line), ending at 0.01302.\n" + ] } ], "source": [ @@ -659,7 +680,9 @@ "ax.set_xlabel(\"games played\")\n", "ax.set_ylabel(\"P(lose)\")\n", "ax.legend()\n", - "plt.show()" + "plt.show()\n", + "print(f\"Figure: the running estimate of P(lose) over {games:,} games (log scale) wobbles at first and \"\n", + " f\"settles near the exact value {exact_lose:.5f} (dashed line), ending at {running[-1]:.5f}.\")" ] }, { @@ -677,10 +700,10 @@ "id": "031d714b", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:16.032088Z", - "iopub.status.busy": "2026-09-06T03:27:16.031898Z", - "iopub.status.idle": "2026-09-06T03:27:16.037229Z", - "shell.execute_reply": "2026-09-06T03:27:16.036732Z" + "iopub.execute_input": "2026-10-27T13:39:18.183084Z", + "iopub.status.busy": "2026-10-27T13:39:18.182901Z", + "iopub.status.idle": "2026-10-27T13:39:18.187901Z", + "shell.execute_reply": "2026-10-27T13:39:18.187387Z" } }, "outputs": [ @@ -730,10 +753,10 @@ "id": "bbcb008c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:16.039280Z", - "iopub.status.busy": "2026-09-06T03:27:16.039097Z", - "iopub.status.idle": "2026-09-06T03:27:16.071372Z", - "shell.execute_reply": "2026-09-06T03:27:16.070860Z" + "iopub.execute_input": "2026-10-27T13:39:18.189984Z", + "iopub.status.busy": "2026-10-27T13:39:18.189782Z", + "iopub.status.idle": "2026-10-27T13:39:18.221070Z", + "shell.execute_reply": "2026-10-27T13:39:18.220587Z" } }, "outputs": [ @@ -785,10 +808,10 @@ "id": "e510c0e0", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:16.073522Z", - "iopub.status.busy": "2026-09-06T03:27:16.073344Z", - "iopub.status.idle": "2026-09-06T03:27:16.078374Z", - "shell.execute_reply": "2026-09-06T03:27:16.077841Z" + "iopub.execute_input": "2026-10-27T13:39:18.223068Z", + "iopub.status.busy": "2026-10-27T13:39:18.222882Z", + "iopub.status.idle": "2026-10-27T13:39:18.228827Z", + "shell.execute_reply": "2026-10-27T13:39:18.227943Z" } }, "outputs": [ diff --git a/notebooks/09_queueing_and_markov/markov_and_queues.ipynb b/notebooks/09_queueing_and_markov/markov_and_queues.ipynb index c986ffa..1e0ca40 100644 --- a/notebooks/09_queueing_and_markov/markov_and_queues.ipynb +++ b/notebooks/09_queueing_and_markov/markov_and_queues.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "fd5c1ad8", + "id": "b73b2751", "metadata": {}, "source": [ "# Markov chains and queues: where things end up, and how long they wait\n", @@ -21,7 +21,7 @@ }, { "cell_type": "markdown", - "id": "d15ab7ad", + "id": "fc915b34", "metadata": {}, "source": [ "## Setup: where the package lives\n", @@ -34,13 +34,13 @@ { "cell_type": "code", "execution_count": 1, - "id": "de826090", + "id": "4abaeff0", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.117263Z", - "iopub.status.busy": "2026-09-06T03:27:19.116924Z", - "iopub.status.idle": "2026-09-06T03:27:19.131266Z", - "shell.execute_reply": "2026-09-06T03:27:19.130541Z" + "iopub.execute_input": "2026-10-27T13:39:29.498861Z", + "iopub.status.busy": "2026-10-27T13:39:29.498680Z", + "iopub.status.idle": "2026-10-27T13:39:29.511368Z", + "shell.execute_reply": "2026-10-27T13:39:29.510874Z" } }, "outputs": [ @@ -56,6 +56,7 @@ "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", @@ -65,7 +66,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/09_queueing_and_markov\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -81,7 +82,7 @@ }, { "cell_type": "markdown", - "id": "a067a47e", + "id": "3f7e88e0", "metadata": {}, "source": [ "## A chain is a table\n", @@ -94,13 +95,13 @@ { "cell_type": "code", "execution_count": 2, - "id": "a6e48672", + "id": "2f3e4483", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.133870Z", - "iopub.status.busy": "2026-09-06T03:27:19.133636Z", - "iopub.status.idle": "2026-09-06T03:27:19.348055Z", - "shell.execute_reply": "2026-09-06T03:27:19.347525Z" + "iopub.execute_input": "2026-10-27T13:39:29.513460Z", + "iopub.status.busy": "2026-10-27T13:39:29.513279Z", + "iopub.status.idle": "2026-10-27T13:39:29.736752Z", + "shell.execute_reply": "2026-10-27T13:39:29.736177Z" } }, "outputs": [ @@ -140,7 +141,7 @@ }, { "cell_type": "markdown", - "id": "8dafa57b", + "id": "8f436c12", "metadata": {}, "source": [ "## One step, two steps, three\n", @@ -153,13 +154,13 @@ { "cell_type": "code", "execution_count": 3, - "id": "96f1accd", + "id": "e4b0b841", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.350231Z", - "iopub.status.busy": "2026-09-06T03:27:19.350019Z", - "iopub.status.idle": "2026-09-06T03:27:19.354451Z", - "shell.execute_reply": "2026-09-06T03:27:19.353944Z" + "iopub.execute_input": "2026-10-27T13:39:29.738996Z", + "iopub.status.busy": "2026-10-27T13:39:29.738779Z", + "iopub.status.idle": "2026-10-27T13:39:29.743057Z", + "shell.execute_reply": "2026-10-27T13:39:29.742573Z" } }, "outputs": [ @@ -184,7 +185,7 @@ }, { "cell_type": "markdown", - "id": "2b916ffc", + "id": "b86dbb09", "metadata": {}, "source": [ "Twenty steps, from each starting zone. The rows of $P^{20}$ are the distributions after twenty fares\n", @@ -194,13 +195,13 @@ { "cell_type": "code", "execution_count": 4, - "id": "8ca3a91d", + "id": "0fe8e845", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.356563Z", - "iopub.status.busy": "2026-09-06T03:27:19.356381Z", - "iopub.status.idle": "2026-09-06T03:27:19.360814Z", - "shell.execute_reply": "2026-09-06T03:27:19.360217Z" + "iopub.execute_input": "2026-10-27T13:39:29.745109Z", + "iopub.status.busy": "2026-10-27T13:39:29.744935Z", + "iopub.status.idle": "2026-10-27T13:39:29.749162Z", + "shell.execute_reply": "2026-10-27T13:39:29.748357Z" } }, "outputs": [ @@ -222,7 +223,7 @@ }, { "cell_type": "markdown", - "id": "7f3e303e", + "id": "5d5c0b3f", "metadata": {}, "source": [ "## The steady state, solved rather than iterated\n", @@ -236,13 +237,13 @@ { "cell_type": "code", "execution_count": 5, - "id": "715f4adf", + "id": "1f16fdf1", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.362997Z", - "iopub.status.busy": "2026-09-06T03:27:19.362685Z", - "iopub.status.idle": "2026-09-06T03:27:19.371504Z", - "shell.execute_reply": "2026-09-06T03:27:19.371067Z" + "iopub.execute_input": "2026-10-27T13:39:29.751873Z", + "iopub.status.busy": "2026-10-27T13:39:29.751617Z", + "iopub.status.idle": "2026-10-27T13:39:29.758698Z", + "shell.execute_reply": "2026-10-27T13:39:29.758096Z" } }, "outputs": [ @@ -270,7 +271,7 @@ }, { "cell_type": "markdown", - "id": "add727fa", + "id": "1a46c621", "metadata": {}, "source": [ "## A two-state check by hand\n", @@ -283,13 +284,13 @@ { "cell_type": "code", "execution_count": 6, - "id": "e9aa9621", + "id": "fe8a44d0", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.374427Z", - "iopub.status.busy": "2026-09-06T03:27:19.374069Z", - "iopub.status.idle": "2026-09-06T03:27:19.380160Z", - "shell.execute_reply": "2026-09-06T03:27:19.379280Z" + "iopub.execute_input": "2026-10-27T13:39:29.760965Z", + "iopub.status.busy": "2026-10-27T13:39:29.760790Z", + "iopub.status.idle": "2026-10-27T13:39:29.765563Z", + "shell.execute_reply": "2026-10-27T13:39:29.764813Z" } }, "outputs": [ @@ -311,7 +312,7 @@ }, { "cell_type": "markdown", - "id": "b5122689", + "id": "054ad6ec", "metadata": {}, "source": [ "---\n", @@ -326,13 +327,13 @@ { "cell_type": "code", "execution_count": 7, - "id": "09525cfa", + "id": "66f1617f", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.382772Z", - "iopub.status.busy": "2026-09-06T03:27:19.382574Z", - "iopub.status.idle": "2026-09-06T03:27:19.395982Z", - "shell.execute_reply": "2026-09-06T03:27:19.395445Z" + "iopub.execute_input": "2026-10-27T13:39:29.767894Z", + "iopub.status.busy": "2026-10-27T13:39:29.767716Z", + "iopub.status.idle": "2026-10-27T13:39:29.774008Z", + "shell.execute_reply": "2026-10-27T13:39:29.773567Z" } }, "outputs": [ @@ -363,7 +364,7 @@ }, { "cell_type": "markdown", - "id": "52a0c636", + "id": "40dc9399", "metadata": {}, "source": [ "## The fundamental matrix\n", @@ -377,13 +378,13 @@ { "cell_type": "code", "execution_count": 8, - "id": "ccf6bdb2", + "id": "dfbcdc4e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.398195Z", - "iopub.status.busy": "2026-09-06T03:27:19.398006Z", - "iopub.status.idle": "2026-09-06T03:27:19.404252Z", - "shell.execute_reply": "2026-09-06T03:27:19.403613Z" + "iopub.execute_input": "2026-10-27T13:39:29.776296Z", + "iopub.status.busy": "2026-10-27T13:39:29.776117Z", + "iopub.status.idle": "2026-10-27T13:39:29.782356Z", + "shell.execute_reply": "2026-10-27T13:39:29.781622Z" } }, "outputs": [ @@ -411,7 +412,7 @@ }, { "cell_type": "markdown", - "id": "8dbe38df", + "id": "ade2dee4", "metadata": {}, "source": [ "D is the fastest start, and half of the time D's first step is to A, the slowest. Trace the paths\n", @@ -432,13 +433,13 @@ { "cell_type": "code", "execution_count": 9, - "id": "b2a02c38", + "id": "a078e010", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.406866Z", - "iopub.status.busy": "2026-09-06T03:27:19.406680Z", - "iopub.status.idle": "2026-09-06T03:27:19.411361Z", - "shell.execute_reply": "2026-09-06T03:27:19.410886Z" + "iopub.execute_input": "2026-10-27T13:39:29.784733Z", + "iopub.status.busy": "2026-10-27T13:39:29.784553Z", + "iopub.status.idle": "2026-10-27T13:39:29.788755Z", + "shell.execute_reply": "2026-10-27T13:39:29.788304Z" } }, "outputs": [ @@ -465,7 +466,7 @@ }, { "cell_type": "markdown", - "id": "8180ada9", + "id": "6cdb3fcb", "metadata": {}, "source": [ "Four measures, two relationships. $L = \\lambda W$ and $L_q = \\lambda W_q$ — **Little's law** — hold\n", @@ -477,13 +478,13 @@ { "cell_type": "code", "execution_count": 10, - "id": "61bc918b", + "id": "c56e0027", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.413862Z", - "iopub.status.busy": "2026-09-06T03:27:19.413673Z", - "iopub.status.idle": "2026-09-06T03:27:19.418473Z", - "shell.execute_reply": "2026-09-06T03:27:19.418004Z" + "iopub.execute_input": "2026-10-27T13:39:29.790875Z", + "iopub.status.busy": "2026-10-27T13:39:29.790706Z", + "iopub.status.idle": "2026-10-27T13:39:29.795039Z", + "shell.execute_reply": "2026-10-27T13:39:29.794681Z" } }, "outputs": [ @@ -507,7 +508,7 @@ }, { "cell_type": "markdown", - "id": "71b5f557", + "id": "61322425", "metadata": {}, "source": [ "## Two servers: M/M/2\n", @@ -520,13 +521,13 @@ { "cell_type": "code", "execution_count": 11, - "id": "4c32049d", + "id": "7f4bef45", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.420442Z", - "iopub.status.busy": "2026-09-06T03:27:19.420263Z", - "iopub.status.idle": "2026-09-06T03:27:19.425866Z", - "shell.execute_reply": "2026-09-06T03:27:19.425027Z" + "iopub.execute_input": "2026-10-27T13:39:29.797394Z", + "iopub.status.busy": "2026-10-27T13:39:29.797223Z", + "iopub.status.idle": "2026-10-27T13:39:29.802386Z", + "shell.execute_reply": "2026-10-27T13:39:29.801907Z" } }, "outputs": [ @@ -557,7 +558,7 @@ }, { "cell_type": "markdown", - "id": "d96a1564", + "id": "1bc06f6c", "metadata": {}, "source": [ "---\n", @@ -576,13 +577,13 @@ { "cell_type": "code", "execution_count": 12, - "id": "8fa00fb7", + "id": "e75ffa24", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.428170Z", - "iopub.status.busy": "2026-09-06T03:27:19.427990Z", - "iopub.status.idle": "2026-09-06T03:27:19.588527Z", - "shell.execute_reply": "2026-09-06T03:27:19.587881Z" + "iopub.execute_input": "2026-10-27T13:39:29.804711Z", + "iopub.status.busy": "2026-10-27T13:39:29.804534Z", + "iopub.status.idle": "2026-10-27T13:39:29.963329Z", + "shell.execute_reply": "2026-10-27T13:39:29.962761Z" } }, "outputs": [ @@ -624,7 +625,7 @@ }, { "cell_type": "markdown", - "id": "ad2191c2", + "id": "c1ab9e6e", "metadata": {}, "source": [ "Close, not equal. Change the seed and run again; then make `N_CUSTOMERS` a hundred times smaller, and\n", @@ -644,13 +645,13 @@ { "cell_type": "code", "execution_count": 13, - "id": "03139e05", + "id": "3c1fdea4", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.591411Z", - "iopub.status.busy": "2026-09-06T03:27:19.591073Z", - "iopub.status.idle": "2026-09-06T03:27:19.707875Z", - "shell.execute_reply": "2026-09-06T03:27:19.707167Z" + "iopub.execute_input": "2026-10-27T13:39:29.965580Z", + "iopub.status.busy": "2026-10-27T13:39:29.965371Z", + "iopub.status.idle": "2026-10-27T13:39:30.067588Z", + "shell.execute_reply": "2026-10-27T13:39:30.067033Z" } }, "outputs": [ @@ -684,7 +685,7 @@ }, { "cell_type": "markdown", - "id": "432f3ce9", + "id": "a7ed58c7", "metadata": {}, "source": [ "## The agreement assertion\n", @@ -698,13 +699,13 @@ { "cell_type": "code", "execution_count": 14, - "id": "8b343d84", + "id": "2335ac2b", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:19.710339Z", - "iopub.status.busy": "2026-09-06T03:27:19.710095Z", - "iopub.status.idle": "2026-09-06T03:27:19.723332Z", - "shell.execute_reply": "2026-09-06T03:27:19.722036Z" + "iopub.execute_input": "2026-10-27T13:39:30.069955Z", + "iopub.status.busy": "2026-10-27T13:39:30.069756Z", + "iopub.status.idle": "2026-10-27T13:39:30.076239Z", + "shell.execute_reply": "2026-10-27T13:39:30.075705Z" } }, "outputs": [ @@ -747,7 +748,7 @@ }, { "cell_type": "markdown", - "id": "f9223627", + "id": "992315bd", "metadata": {}, "source": [ "---\n", diff --git a/notebooks/10_game_theory/zero_sum_game.ipynb b/notebooks/10_game_theory/zero_sum_game.ipynb index 22259e9..dec79d2 100644 --- a/notebooks/10_game_theory/zero_sum_game.ipynb +++ b/notebooks/10_game_theory/zero_sum_game.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "c52a955e", + "id": "e43670b9", "metadata": {}, "source": [ "# A zero-sum game, solved as two linear programs\n", @@ -20,7 +20,7 @@ }, { "cell_type": "markdown", - "id": "43281565", + "id": "130a1e66", "metadata": {}, "source": [ "## Setup: where the package lives\n", @@ -33,13 +33,13 @@ { "cell_type": "code", "execution_count": 1, - "id": "6e665c1e", + "id": "aa6bdcaa", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:22.885472Z", - "iopub.status.busy": "2026-09-06T03:27:22.885297Z", - "iopub.status.idle": "2026-09-06T03:27:22.897592Z", - "shell.execute_reply": "2026-09-06T03:27:22.897114Z" + "iopub.execute_input": "2026-10-27T13:39:41.217951Z", + "iopub.status.busy": "2026-10-27T13:39:41.217690Z", + "iopub.status.idle": "2026-10-27T13:39:41.235439Z", + "shell.execute_reply": "2026-10-27T13:39:41.234649Z" } }, "outputs": [ @@ -55,6 +55,7 @@ "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", @@ -64,7 +65,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/10_game_theory\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -80,7 +81,7 @@ }, { "cell_type": "markdown", - "id": "1d0131d5", + "id": "e6a76bee", "metadata": {}, "source": [ "## Licence setup\n", @@ -94,13 +95,13 @@ { "cell_type": "code", "execution_count": 2, - "id": "f0d015a8", + "id": "70145cce", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:22.900414Z", - "iopub.status.busy": "2026-09-06T03:27:22.900237Z", - "iopub.status.idle": "2026-09-06T03:27:22.952083Z", - "shell.execute_reply": "2026-09-06T03:27:22.951591Z" + "iopub.execute_input": "2026-10-27T13:39:41.238488Z", + "iopub.status.busy": "2026-10-27T13:39:41.238239Z", + "iopub.status.idle": "2026-10-27T13:39:41.315440Z", + "shell.execute_reply": "2026-10-27T13:39:41.314699Z" } }, "outputs": [ @@ -135,7 +136,7 @@ }, { "cell_type": "markdown", - "id": "2476ac96", + "id": "f2fbc32e", "metadata": {}, "source": [ "## The payoff matrix is a table\n", @@ -148,13 +149,13 @@ { "cell_type": "code", "execution_count": 3, - "id": "b70f2133", + "id": "0483ffcf", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:22.954380Z", - "iopub.status.busy": "2026-09-06T03:27:22.954181Z", - "iopub.status.idle": "2026-09-06T03:27:22.973084Z", - "shell.execute_reply": "2026-09-06T03:27:22.972582Z" + "iopub.execute_input": "2026-10-27T13:39:41.318164Z", + "iopub.status.busy": "2026-10-27T13:39:41.317886Z", + "iopub.status.idle": "2026-10-27T13:39:41.334358Z", + "shell.execute_reply": "2026-10-27T13:39:41.333701Z" } }, "outputs": [ @@ -190,7 +191,7 @@ }, { "cell_type": "markdown", - "id": "ca33fd41", + "id": "a1ae97b5", "metadata": {}, "source": [ "## Pure strategies first\n", @@ -203,13 +204,13 @@ { "cell_type": "code", "execution_count": 4, - "id": "32a8aee6", + "id": "3eb9ad9d", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:22.975201Z", - "iopub.status.busy": "2026-09-06T03:27:22.975026Z", - "iopub.status.idle": "2026-09-06T03:27:22.979982Z", - "shell.execute_reply": "2026-09-06T03:27:22.979373Z" + "iopub.execute_input": "2026-10-27T13:39:41.336717Z", + "iopub.status.busy": "2026-10-27T13:39:41.336492Z", + "iopub.status.idle": "2026-10-27T13:39:41.341983Z", + "shell.execute_reply": "2026-10-27T13:39:41.341425Z" } }, "outputs": [ @@ -236,7 +237,7 @@ }, { "cell_type": "markdown", - "id": "4b11d669", + "id": "91090d03", "metadata": {}, "source": [ "The row player can guarantee 2 by playing pure; the column player can hold the loss to 3 by playing\n", @@ -253,13 +254,13 @@ { "cell_type": "code", "execution_count": 5, - "id": "a4d06d91", + "id": "1729db8c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:22.982670Z", - "iopub.status.busy": "2026-09-06T03:27:22.982441Z", - "iopub.status.idle": "2026-09-06T03:27:22.992102Z", - "shell.execute_reply": "2026-09-06T03:27:22.991400Z" + "iopub.execute_input": "2026-10-27T13:39:41.344287Z", + "iopub.status.busy": "2026-10-27T13:39:41.344068Z", + "iopub.status.idle": "2026-10-27T13:39:41.351455Z", + "shell.execute_reply": "2026-10-27T13:39:41.350946Z" } }, "outputs": [ @@ -298,7 +299,7 @@ }, { "cell_type": "markdown", - "id": "890dd444", + "id": "5ec59881", "metadata": {}, "source": [ "That printed table is the check to make before solving. These rows are easy to build with a `prod`\n", @@ -312,13 +313,13 @@ { "cell_type": "code", "execution_count": 6, - "id": "3033dc20", + "id": "7651d0a3", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:22.994666Z", - "iopub.status.busy": "2026-09-06T03:27:22.994458Z", - "iopub.status.idle": "2026-09-06T03:27:23.000357Z", - "shell.execute_reply": "2026-09-06T03:27:22.999782Z" + "iopub.execute_input": "2026-10-27T13:39:41.353997Z", + "iopub.status.busy": "2026-10-27T13:39:41.353770Z", + "iopub.status.idle": "2026-10-27T13:39:41.359196Z", + "shell.execute_reply": "2026-10-27T13:39:41.358550Z" } }, "outputs": [ @@ -342,7 +343,7 @@ }, { "cell_type": "markdown", - "id": "72b0d5e0", + "id": "7299f3dc", "metadata": {}, "source": [ "## Which columns bind, and what the duals say\n", @@ -355,13 +356,13 @@ { "cell_type": "code", "execution_count": 7, - "id": "25ba6d4a", + "id": "def044da", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:23.003038Z", - "iopub.status.busy": "2026-09-06T03:27:23.002738Z", - "iopub.status.idle": "2026-09-06T03:27:23.008503Z", - "shell.execute_reply": "2026-09-06T03:27:23.007682Z" + "iopub.execute_input": "2026-10-27T13:39:41.361767Z", + "iopub.status.busy": "2026-10-27T13:39:41.361535Z", + "iopub.status.idle": "2026-10-27T13:39:41.366550Z", + "shell.execute_reply": "2026-10-27T13:39:41.365941Z" } }, "outputs": [ @@ -388,7 +389,7 @@ }, { "cell_type": "markdown", - "id": "c77724f2", + "id": "904bcf9a", "metadata": {}, "source": [ "Hold those duals: minus each one is a probability, and the probability-row dual is the value of the\n", @@ -404,13 +405,13 @@ { "cell_type": "code", "execution_count": 8, - "id": "e12a7e54", + "id": "85f02c2f", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:23.012066Z", - "iopub.status.busy": "2026-09-06T03:27:23.011735Z", - "iopub.status.idle": "2026-09-06T03:27:23.019280Z", - "shell.execute_reply": "2026-09-06T03:27:23.018700Z" + "iopub.execute_input": "2026-10-27T13:39:41.369039Z", + "iopub.status.busy": "2026-10-27T13:39:41.368818Z", + "iopub.status.idle": "2026-10-27T13:39:41.375928Z", + "shell.execute_reply": "2026-10-27T13:39:41.375333Z" } }, "outputs": [ @@ -446,7 +447,7 @@ }, { "cell_type": "markdown", - "id": "a6a64d0f", + "id": "fe23a7c3", "metadata": {}, "source": [ "Same value from both sides: the minimax theorem, which is strong duality with the players' names on\n", @@ -457,13 +458,13 @@ { "cell_type": "code", "execution_count": 9, - "id": "a3fd2e28", + "id": "1c819335", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:23.021395Z", - "iopub.status.busy": "2026-09-06T03:27:23.021214Z", - "iopub.status.idle": "2026-09-06T03:27:23.026047Z", - "shell.execute_reply": "2026-09-06T03:27:23.025416Z" + "iopub.execute_input": "2026-10-27T13:39:41.378240Z", + "iopub.status.busy": "2026-10-27T13:39:41.378024Z", + "iopub.status.idle": "2026-10-27T13:39:41.382862Z", + "shell.execute_reply": "2026-10-27T13:39:41.382237Z" } }, "outputs": [ @@ -484,7 +485,7 @@ }, { "cell_type": "markdown", - "id": "05846db7", + "id": "5078ac87", "metadata": {}, "source": [ "Both hold the row player to exactly the value. If they differ, how many optimal column strategies\n", @@ -503,13 +504,13 @@ { "cell_type": "code", "execution_count": 10, - "id": "3d9ba6a3", + "id": "f5442155", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:23.028412Z", - "iopub.status.busy": "2026-09-06T03:27:23.028202Z", - "iopub.status.idle": "2026-09-06T03:27:23.033743Z", - "shell.execute_reply": "2026-09-06T03:27:23.033284Z" + "iopub.execute_input": "2026-10-27T13:39:41.385279Z", + "iopub.status.busy": "2026-10-27T13:39:41.385061Z", + "iopub.status.idle": "2026-10-27T13:39:41.391343Z", + "shell.execute_reply": "2026-10-27T13:39:41.390900Z" } }, "outputs": [ @@ -536,7 +537,7 @@ }, { "cell_type": "markdown", - "id": "284177da", + "id": "b5d2bcac", "metadata": {}, "source": [ "## The agreement assertion\n", @@ -552,13 +553,13 @@ { "cell_type": "code", "execution_count": 11, - "id": "133a5959", + "id": "9abd5495", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:23.035752Z", - "iopub.status.busy": "2026-09-06T03:27:23.035573Z", - "iopub.status.idle": "2026-09-06T03:27:23.041450Z", - "shell.execute_reply": "2026-09-06T03:27:23.040970Z" + "iopub.execute_input": "2026-10-27T13:39:41.393674Z", + "iopub.status.busy": "2026-10-27T13:39:41.393463Z", + "iopub.status.idle": "2026-10-27T13:39:41.400451Z", + "shell.execute_reply": "2026-10-27T13:39:41.399868Z" } }, "outputs": [ @@ -599,7 +600,7 @@ }, { "cell_type": "markdown", - "id": "166126f6", + "id": "75eca1c2", "metadata": {}, "source": [ "---\n", diff --git a/notebooks/11_decision_analysis/capital_budgeting.ipynb b/notebooks/11_decision_analysis/capital_budgeting.ipynb index f115d19..1820210 100644 --- a/notebooks/11_decision_analysis/capital_budgeting.ipynb +++ b/notebooks/11_decision_analysis/capital_budgeting.ipynb @@ -38,10 +38,10 @@ "id": "6729c724", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.193852Z", - "iopub.status.busy": "2026-09-06T03:27:26.193536Z", - "iopub.status.idle": "2026-09-06T03:27:26.210483Z", - "shell.execute_reply": "2026-09-06T03:27:26.209873Z" + "iopub.execute_input": "2026-10-27T13:39:52.593707Z", + "iopub.status.busy": "2026-10-27T13:39:52.593530Z", + "iopub.status.idle": "2026-10-27T13:39:52.606647Z", + "shell.execute_reply": "2026-10-27T13:39:52.605773Z" } }, "outputs": [ @@ -57,6 +57,7 @@ "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", @@ -66,7 +67,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/11_decision_analysis\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -99,10 +100,10 @@ "id": "ab4b9d8e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.213034Z", - "iopub.status.busy": "2026-09-06T03:27:26.212612Z", - "iopub.status.idle": "2026-09-06T03:27:26.272190Z", - "shell.execute_reply": "2026-09-06T03:27:26.271060Z" + "iopub.execute_input": "2026-10-27T13:39:52.609355Z", + "iopub.status.busy": "2026-10-27T13:39:52.609125Z", + "iopub.status.idle": "2026-10-27T13:39:52.663776Z", + "shell.execute_reply": "2026-10-27T13:39:52.663265Z" } }, "outputs": [ @@ -156,10 +157,10 @@ "id": "35de65cd", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.274473Z", - "iopub.status.busy": "2026-09-06T03:27:26.274246Z", - "iopub.status.idle": "2026-09-06T03:27:26.292296Z", - "shell.execute_reply": "2026-09-06T03:27:26.291713Z" + "iopub.execute_input": "2026-10-27T13:39:52.665905Z", + "iopub.status.busy": "2026-10-27T13:39:52.665697Z", + "iopub.status.idle": "2026-10-27T13:39:52.681174Z", + "shell.execute_reply": "2026-10-27T13:39:52.680652Z" } }, "outputs": [ @@ -204,10 +205,10 @@ "id": "0e7bc6f8", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.294383Z", - "iopub.status.busy": "2026-09-06T03:27:26.294206Z", - "iopub.status.idle": "2026-09-06T03:27:26.297953Z", - "shell.execute_reply": "2026-09-06T03:27:26.297584Z" + "iopub.execute_input": "2026-10-27T13:39:52.683558Z", + "iopub.status.busy": "2026-10-27T13:39:52.683314Z", + "iopub.status.idle": "2026-10-27T13:39:52.688865Z", + "shell.execute_reply": "2026-10-27T13:39:52.688218Z" } }, "outputs": [ @@ -250,10 +251,10 @@ "id": "b4bdfa2a", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.299930Z", - "iopub.status.busy": "2026-09-06T03:27:26.299760Z", - "iopub.status.idle": "2026-09-06T03:27:26.304170Z", - "shell.execute_reply": "2026-09-06T03:27:26.303754Z" + "iopub.execute_input": "2026-10-27T13:39:52.691180Z", + "iopub.status.busy": "2026-10-27T13:39:52.690986Z", + "iopub.status.idle": "2026-10-27T13:39:52.695368Z", + "shell.execute_reply": "2026-10-27T13:39:52.694881Z" } }, "outputs": [ @@ -298,10 +299,10 @@ "id": "cf1a214c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.306311Z", - "iopub.status.busy": "2026-09-06T03:27:26.306127Z", - "iopub.status.idle": "2026-09-06T03:27:26.311262Z", - "shell.execute_reply": "2026-09-06T03:27:26.310868Z" + "iopub.execute_input": "2026-10-27T13:39:52.697295Z", + "iopub.status.busy": "2026-10-27T13:39:52.697116Z", + "iopub.status.idle": "2026-10-27T13:39:52.702289Z", + "shell.execute_reply": "2026-10-27T13:39:52.701732Z" } }, "outputs": [ @@ -342,10 +343,10 @@ "id": "f30c3de4", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.313350Z", - "iopub.status.busy": "2026-09-06T03:27:26.313176Z", - "iopub.status.idle": "2026-09-06T03:27:26.318390Z", - "shell.execute_reply": "2026-09-06T03:27:26.317936Z" + "iopub.execute_input": "2026-10-27T13:39:52.704307Z", + "iopub.status.busy": "2026-10-27T13:39:52.704131Z", + "iopub.status.idle": "2026-10-27T13:39:52.709329Z", + "shell.execute_reply": "2026-10-27T13:39:52.708834Z" } }, "outputs": [ @@ -387,10 +388,10 @@ "id": "683a90df", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.320368Z", - "iopub.status.busy": "2026-09-06T03:27:26.320197Z", - "iopub.status.idle": "2026-09-06T03:27:26.324886Z", - "shell.execute_reply": "2026-09-06T03:27:26.324427Z" + "iopub.execute_input": "2026-10-27T13:39:52.711400Z", + "iopub.status.busy": "2026-10-27T13:39:52.711202Z", + "iopub.status.idle": "2026-10-27T13:39:52.716658Z", + "shell.execute_reply": "2026-10-27T13:39:52.716198Z" } }, "outputs": [ @@ -435,10 +436,10 @@ "id": "704f5e90", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.326842Z", - "iopub.status.busy": "2026-09-06T03:27:26.326673Z", - "iopub.status.idle": "2026-09-06T03:27:26.330568Z", - "shell.execute_reply": "2026-09-06T03:27:26.330144Z" + "iopub.execute_input": "2026-10-27T13:39:52.719072Z", + "iopub.status.busy": "2026-10-27T13:39:52.718892Z", + "iopub.status.idle": "2026-10-27T13:39:52.723076Z", + "shell.execute_reply": "2026-10-27T13:39:52.722578Z" } }, "outputs": [ @@ -492,10 +493,10 @@ "id": "2ba1bbf2", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.332572Z", - "iopub.status.busy": "2026-09-06T03:27:26.332397Z", - "iopub.status.idle": "2026-09-06T03:27:26.338764Z", - "shell.execute_reply": "2026-09-06T03:27:26.338291Z" + "iopub.execute_input": "2026-10-27T13:39:52.725487Z", + "iopub.status.busy": "2026-10-27T13:39:52.725270Z", + "iopub.status.idle": "2026-10-27T13:39:52.732061Z", + "shell.execute_reply": "2026-10-27T13:39:52.731481Z" } }, "outputs": [ @@ -552,10 +553,10 @@ "id": "eeb7684c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.340757Z", - "iopub.status.busy": "2026-09-06T03:27:26.340589Z", - "iopub.status.idle": "2026-09-06T03:27:26.345883Z", - "shell.execute_reply": "2026-09-06T03:27:26.345410Z" + "iopub.execute_input": "2026-10-27T13:39:52.734787Z", + "iopub.status.busy": "2026-10-27T13:39:52.734554Z", + "iopub.status.idle": "2026-10-27T13:39:52.740616Z", + "shell.execute_reply": "2026-10-27T13:39:52.740083Z" } }, "outputs": [ @@ -604,10 +605,10 @@ "id": "a3323773", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.347817Z", - "iopub.status.busy": "2026-09-06T03:27:26.347640Z", - "iopub.status.idle": "2026-09-06T03:27:26.351403Z", - "shell.execute_reply": "2026-09-06T03:27:26.350963Z" + "iopub.execute_input": "2026-10-27T13:39:52.742684Z", + "iopub.status.busy": "2026-10-27T13:39:52.742500Z", + "iopub.status.idle": "2026-10-27T13:39:52.746592Z", + "shell.execute_reply": "2026-10-27T13:39:52.746073Z" } }, "outputs": [ @@ -665,10 +666,10 @@ "id": "42d2525e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.353460Z", - "iopub.status.busy": "2026-09-06T03:27:26.353288Z", - "iopub.status.idle": "2026-09-06T03:27:26.358491Z", - "shell.execute_reply": "2026-09-06T03:27:26.357997Z" + "iopub.execute_input": "2026-10-27T13:39:52.748752Z", + "iopub.status.busy": "2026-10-27T13:39:52.748571Z", + "iopub.status.idle": "2026-10-27T13:39:52.753851Z", + "shell.execute_reply": "2026-10-27T13:39:52.753336Z" } }, "outputs": [ @@ -719,10 +720,10 @@ "id": "1fa41df8", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:26.360502Z", - "iopub.status.busy": "2026-09-06T03:27:26.360329Z", - "iopub.status.idle": "2026-09-06T03:27:26.365147Z", - "shell.execute_reply": "2026-09-06T03:27:26.364640Z" + "iopub.execute_input": "2026-10-27T13:39:52.755958Z", + "iopub.status.busy": "2026-10-27T13:39:52.755772Z", + "iopub.status.idle": "2026-10-27T13:39:52.760803Z", + "shell.execute_reply": "2026-10-27T13:39:52.760324Z" } }, "outputs": [ diff --git a/notebooks/12_energy_systems_pypsa/dispatch_to_pypsa.ipynb b/notebooks/12_energy_systems_pypsa/dispatch_to_pypsa.ipynb index 57db12b..6bd0281 100644 --- a/notebooks/12_energy_systems_pypsa/dispatch_to_pypsa.ipynb +++ b/notebooks/12_energy_systems_pypsa/dispatch_to_pypsa.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "371e4b11", + "id": "5169c9e6", "metadata": {}, "source": [ "# From a linear program to PyPSA: the same problem three times, then one you cannot check by hand\n", @@ -21,7 +21,7 @@ }, { "cell_type": "markdown", - "id": "d596b6cb", + "id": "b426f851", "metadata": {}, "source": [ "## Setup: where the package lives, and PyPSA\n", @@ -34,13 +34,13 @@ { "cell_type": "code", "execution_count": 1, - "id": "a3f03e61", + "id": "fc7b0062", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:58:40.011477Z", - "iopub.status.busy": "2026-10-22T17:58:40.010849Z", - "iopub.status.idle": "2026-10-22T17:59:18.191166Z", - "shell.execute_reply": "2026-10-22T17:59:18.189226Z" + "iopub.execute_input": "2026-10-27T13:39:59.490878Z", + "iopub.status.busy": "2026-10-27T13:39:59.490604Z", + "iopub.status.idle": "2026-10-27T13:40:16.785233Z", + "shell.execute_reply": "2026-10-27T13:40:16.784273Z" } }, "outputs": [ @@ -56,6 +56,7 @@ "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", @@ -65,7 +66,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/12_energy_systems_pypsa\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\", \"pypsa\", \"highspy\"], check=True)\n", "\n", @@ -85,7 +86,7 @@ }, { "cell_type": "markdown", - "id": "1c493214", + "id": "6debce55", "metadata": {}, "source": [ "## Licence setup, and a quiet solver\n", @@ -103,13 +104,13 @@ { "cell_type": "code", "execution_count": 2, - "id": "924e7d9f", + "id": "b64ddfab", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:18.195665Z", - "iopub.status.busy": "2026-10-22T17:59:18.195051Z", - "iopub.status.idle": "2026-10-22T17:59:18.284433Z", - "shell.execute_reply": "2026-10-22T17:59:18.282546Z" + "iopub.execute_input": "2026-10-27T13:40:16.787704Z", + "iopub.status.busy": "2026-10-27T13:40:16.787478Z", + "iopub.status.idle": "2026-10-27T13:40:17.095255Z", + "shell.execute_reply": "2026-10-27T13:40:17.094424Z" } }, "outputs": [ @@ -154,7 +155,7 @@ }, { "cell_type": "markdown", - "id": "986f5879", + "id": "934f4968", "metadata": {}, "source": [ "## Part A — one hour, on paper\n", @@ -180,13 +181,13 @@ { "cell_type": "code", "execution_count": 3, - "id": "3d620dc8", + "id": "e9814135", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:18.289204Z", - "iopub.status.busy": "2026-10-22T17:59:18.288297Z", - "iopub.status.idle": "2026-10-22T17:59:18.304551Z", - "shell.execute_reply": "2026-10-22T17:59:18.302733Z" + "iopub.execute_input": "2026-10-27T13:40:17.098141Z", + "iopub.status.busy": "2026-10-27T13:40:17.097638Z", + "iopub.status.idle": "2026-10-27T13:40:17.113496Z", + "shell.execute_reply": "2026-10-27T13:40:17.112578Z" } }, "outputs": [ @@ -215,7 +216,7 @@ }, { "cell_type": "markdown", - "id": "1270e5e8", + "id": "12f22895", "metadata": {}, "source": [ "Predict before you run: the cost of the hour, and the shadow price on the balance row — the cost of\n", @@ -225,13 +226,13 @@ { "cell_type": "code", "execution_count": 4, - "id": "f66524d8", + "id": "4ff9c0e8", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:18.309083Z", - "iopub.status.busy": "2026-10-22T17:59:18.308504Z", - "iopub.status.idle": "2026-10-22T17:59:18.320524Z", - "shell.execute_reply": "2026-10-22T17:59:18.318679Z" + "iopub.execute_input": "2026-10-27T13:40:17.115708Z", + "iopub.status.busy": "2026-10-27T13:40:17.115429Z", + "iopub.status.idle": "2026-10-27T13:40:17.130916Z", + "shell.execute_reply": "2026-10-27T13:40:17.130054Z" } }, "outputs": [ @@ -258,7 +259,7 @@ }, { "cell_type": "markdown", - "id": "f0c8fcc2", + "id": "fc1d1f9f", "metadata": {}, "source": [ "The price is gas's cost, not an average of what ran. Nothing was added to the model to get that;\n", @@ -274,13 +275,13 @@ { "cell_type": "code", "execution_count": 5, - "id": "6150fd14", + "id": "bebaac41", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:18.324960Z", - "iopub.status.busy": "2026-10-22T17:59:18.324361Z", - "iopub.status.idle": "2026-10-22T17:59:18.657547Z", - "shell.execute_reply": "2026-10-22T17:59:18.655714Z" + "iopub.execute_input": "2026-10-27T13:40:17.133818Z", + "iopub.status.busy": "2026-10-27T13:40:17.133471Z", + "iopub.status.idle": "2026-10-27T13:40:17.271208Z", + "shell.execute_reply": "2026-10-27T13:40:17.270369Z" } }, "outputs": [ @@ -301,7 +302,7 @@ }, { "cell_type": "markdown", - "id": "748ab0ee", + "id": "7d419757", "metadata": {}, "source": [ "A generator per technology. `p_nom` is the capacity row's right-hand side; `marginal_cost` is the\n", @@ -311,13 +312,13 @@ { "cell_type": "code", "execution_count": 6, - "id": "463abbb3", + "id": "9c0c144f", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:18.662037Z", - "iopub.status.busy": "2026-10-22T17:59:18.661461Z", - "iopub.status.idle": "2026-10-22T17:59:18.776357Z", - "shell.execute_reply": "2026-10-22T17:59:18.774460Z" + "iopub.execute_input": "2026-10-27T13:40:17.273706Z", + "iopub.status.busy": "2026-10-27T13:40:17.273502Z", + "iopub.status.idle": "2026-10-27T13:40:17.323409Z", + "shell.execute_reply": "2026-10-27T13:40:17.322537Z" } }, "outputs": [ @@ -340,7 +341,7 @@ }, { "cell_type": "markdown", - "id": "fe563880", + "id": "651c0436", "metadata": {}, "source": [ "The load is the balance row's right-hand side." @@ -349,13 +350,13 @@ { "cell_type": "code", "execution_count": 7, - "id": "f2f1b26b", + "id": "72ca80e8", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:18.780905Z", - "iopub.status.busy": "2026-10-22T17:59:18.780325Z", - "iopub.status.idle": "2026-10-22T17:59:18.812296Z", - "shell.execute_reply": "2026-10-22T17:59:18.810434Z" + "iopub.execute_input": "2026-10-27T13:40:17.326650Z", + "iopub.status.busy": "2026-10-27T13:40:17.326166Z", + "iopub.status.idle": "2026-10-27T13:40:17.342838Z", + "shell.execute_reply": "2026-10-27T13:40:17.341408Z" } }, "outputs": [ @@ -376,7 +377,7 @@ }, { "cell_type": "markdown", - "id": "e9f986b0", + "id": "9cfbf7d2", "metadata": {}, "source": [ "Solve. Predict, before running, whether the objective and the bus's marginal price will match Part B\n", @@ -386,13 +387,13 @@ { "cell_type": "code", "execution_count": 8, - "id": "53c401e8", + "id": "49b3c293", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:18.816793Z", - "iopub.status.busy": "2026-10-22T17:59:18.816212Z", - "iopub.status.idle": "2026-10-22T17:59:20.942508Z", - "shell.execute_reply": "2026-10-22T17:59:20.940632Z" + "iopub.execute_input": "2026-10-27T13:40:17.344944Z", + "iopub.status.busy": "2026-10-27T13:40:17.344742Z", + "iopub.status.idle": "2026-10-27T13:40:18.328118Z", + "shell.execute_reply": "2026-10-27T13:40:18.326773Z" } }, "outputs": [ @@ -420,7 +421,7 @@ }, { "cell_type": "markdown", - "id": "2b40fdda", + "id": "d32242b5", "metadata": {}, "source": [ "## Part D — what PyPSA actually wrote\n", @@ -432,13 +433,13 @@ { "cell_type": "code", "execution_count": 9, - "id": "84c51769", + "id": "b4f2d336", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:20.946976Z", - "iopub.status.busy": "2026-10-22T17:59:20.946386Z", - "iopub.status.idle": "2026-10-22T17:59:21.878576Z", - "shell.execute_reply": "2026-10-22T17:59:21.876766Z" + "iopub.execute_input": "2026-10-27T13:40:18.330548Z", + "iopub.status.busy": "2026-10-27T13:40:18.330339Z", + "iopub.status.idle": "2026-10-27T13:40:18.725203Z", + "shell.execute_reply": "2026-10-27T13:40:18.724445Z" } }, "outputs": [ @@ -468,7 +469,7 @@ }, { "cell_type": "markdown", - "id": "39751cfe", + "id": "f0799f24", "metadata": {}, "source": [ "| you wrote | PyPSA wrote |\n", @@ -498,13 +499,13 @@ { "cell_type": "code", "execution_count": 10, - "id": "ca4636d9", + "id": "0ef3cc15", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:21.883013Z", - "iopub.status.busy": "2026-10-22T17:59:21.882440Z", - "iopub.status.idle": "2026-10-22T17:59:21.923147Z", - "shell.execute_reply": "2026-10-22T17:59:21.921334Z" + "iopub.execute_input": "2026-10-27T13:40:18.727866Z", + "iopub.status.busy": "2026-10-27T13:40:18.727659Z", + "iopub.status.idle": "2026-10-27T13:40:18.747414Z", + "shell.execute_reply": "2026-10-27T13:40:18.746565Z" } }, "outputs": [ @@ -544,7 +545,7 @@ }, { "cell_type": "markdown", - "id": "2d9a9fce", + "id": "646c5d60", "metadata": {}, "source": [ "Look at the two profiles together before building anything. Solar peaks at midday; demand peaks at\n", @@ -562,13 +563,13 @@ { "cell_type": "code", "execution_count": 11, - "id": "223dddbb", + "id": "783fa9f2", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:21.927718Z", - "iopub.status.busy": "2026-10-22T17:59:21.927165Z", - "iopub.status.idle": "2026-10-22T17:59:22.410911Z", - "shell.execute_reply": "2026-10-22T17:59:22.409285Z" + "iopub.execute_input": "2026-10-27T13:40:18.749952Z", + "iopub.status.busy": "2026-10-27T13:40:18.749751Z", + "iopub.status.idle": "2026-10-27T13:40:18.940060Z", + "shell.execute_reply": "2026-10-27T13:40:18.939519Z" } }, "outputs": [ @@ -615,7 +616,7 @@ }, { "cell_type": "markdown", - "id": "9d615aaf", + "id": "02fdb027", "metadata": {}, "source": [ "What did PyPSA write this time? Look for the row that ties hour $t$ to hour $t-1$." @@ -624,13 +625,13 @@ { "cell_type": "code", "execution_count": 12, - "id": "52268010", + "id": "5898c8a1", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:22.415165Z", - "iopub.status.busy": "2026-10-22T17:59:22.414605Z", - "iopub.status.idle": "2026-10-22T17:59:24.135844Z", - "shell.execute_reply": "2026-10-22T17:59:24.133926Z" + "iopub.execute_input": "2026-10-27T13:40:18.942749Z", + "iopub.status.busy": "2026-10-27T13:40:18.942548Z", + "iopub.status.idle": "2026-10-27T13:40:19.626553Z", + "shell.execute_reply": "2026-10-27T13:40:19.625282Z" } }, "outputs": [ @@ -659,7 +660,7 @@ }, { "cell_type": "markdown", - "id": "384dddc6", + "id": "238787f4", "metadata": {}, "source": [ "`StorageUnit-energy_balance` is the one you could not have solved on paper — twenty-four rows, each\n", @@ -674,13 +675,13 @@ { "cell_type": "code", "execution_count": 13, - "id": "6c88e66e", + "id": "060ef3e7", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:24.140160Z", - "iopub.status.busy": "2026-10-22T17:59:24.139597Z", - "iopub.status.idle": "2026-10-22T17:59:26.501333Z", - "shell.execute_reply": "2026-10-22T17:59:26.499478Z" + "iopub.execute_input": "2026-10-27T13:40:19.628887Z", + "iopub.status.busy": "2026-10-27T13:40:19.628598Z", + "iopub.status.idle": "2026-10-27T13:40:20.440374Z", + "shell.execute_reply": "2026-10-27T13:40:20.439592Z" } }, "outputs": [ @@ -734,7 +735,7 @@ }, { "cell_type": "markdown", - "id": "013f0edd", + "id": "c8f9dd6f", "metadata": {}, "source": [ "Read the table before moving on. The battery column is negative when it charges. Find the hours it\n", @@ -747,13 +748,13 @@ { "cell_type": "code", "execution_count": 14, - "id": "b93ead8b", + "id": "f257aa13", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:26.506002Z", - "iopub.status.busy": "2026-10-22T17:59:26.505393Z", - "iopub.status.idle": "2026-10-22T17:59:26.521702Z", - "shell.execute_reply": "2026-10-22T17:59:26.519826Z" + "iopub.execute_input": "2026-10-27T13:40:20.442898Z", + "iopub.status.busy": "2026-10-27T13:40:20.442694Z", + "iopub.status.idle": "2026-10-27T13:40:20.449779Z", + "shell.execute_reply": "2026-10-27T13:40:20.449068Z" } }, "outputs": [ @@ -778,7 +779,7 @@ }, { "cell_type": "markdown", - "id": "bb01705b", + "id": "5661cded", "metadata": {}, "source": [ "## Which hours it charges in is not the model's answer\n", @@ -795,13 +796,13 @@ { "cell_type": "code", "execution_count": 15, - "id": "15966e48", + "id": "01837d9f", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:26.526126Z", - "iopub.status.busy": "2026-10-22T17:59:26.525553Z", - "iopub.status.idle": "2026-10-22T17:59:31.104596Z", - "shell.execute_reply": "2026-10-22T17:59:31.102645Z" + "iopub.execute_input": "2026-10-27T13:40:20.452136Z", + "iopub.status.busy": "2026-10-27T13:40:20.451929Z", + "iopub.status.idle": "2026-10-27T13:40:22.113875Z", + "shell.execute_reply": "2026-10-27T13:40:22.112963Z" } }, "outputs": [ @@ -840,7 +841,7 @@ }, { "cell_type": "markdown", - "id": "d830520a", + "id": "f574d9fd", "metadata": {}, "source": [ "The same cost to the cent, from a different set of charging hours. So those hours are not a property\n", @@ -857,13 +858,13 @@ { "cell_type": "code", "execution_count": 16, - "id": "bc04eded", + "id": "6ddad4d7", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:31.109156Z", - "iopub.status.busy": "2026-10-22T17:59:31.108541Z", - "iopub.status.idle": "2026-10-22T17:59:36.098906Z", - "shell.execute_reply": "2026-10-22T17:59:36.097258Z" + "iopub.execute_input": "2026-10-27T13:40:22.116022Z", + "iopub.status.busy": "2026-10-27T13:40:22.115821Z", + "iopub.status.idle": "2026-10-27T13:40:23.842467Z", + "shell.execute_reply": "2026-10-27T13:40:23.841184Z" } }, "outputs": [ @@ -899,7 +900,7 @@ }, { "cell_type": "markdown", - "id": "df516c3e", + "id": "cad6ca1c", "metadata": {}, "source": [ "The cost moved, so the standing loss is not a tie-breaker at all — it is a real cost, and a sizeable\n", @@ -927,13 +928,13 @@ { "cell_type": "code", "execution_count": 17, - "id": "a2bfd9cb", + "id": "6fcfc8c4", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:36.103612Z", - "iopub.status.busy": "2026-10-22T17:59:36.103084Z", - "iopub.status.idle": "2026-10-22T17:59:38.625954Z", - "shell.execute_reply": "2026-10-22T17:59:38.624128Z" + "iopub.execute_input": "2026-10-27T13:40:23.845367Z", + "iopub.status.busy": "2026-10-27T13:40:23.844981Z", + "iopub.status.idle": "2026-10-27T13:40:24.734814Z", + "shell.execute_reply": "2026-10-27T13:40:24.733952Z" } }, "outputs": [ @@ -970,7 +971,7 @@ }, { "cell_type": "markdown", - "id": "b3b66c18", + "id": "cc380df4", "metadata": {}, "source": [ "`Generator-p_nom` is now a variable. In Part E it was a number in a table. Predict before running:\n", @@ -980,13 +981,13 @@ { "cell_type": "code", "execution_count": 18, - "id": "4398fb9b", + "id": "42b90e6a", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:38.630282Z", - "iopub.status.busy": "2026-10-22T17:59:38.629790Z", - "iopub.status.idle": "2026-10-22T17:59:41.267438Z", - "shell.execute_reply": "2026-10-22T17:59:41.265523Z" + "iopub.execute_input": "2026-10-27T13:40:24.737484Z", + "iopub.status.busy": "2026-10-27T13:40:24.737243Z", + "iopub.status.idle": "2026-10-27T13:40:25.701825Z", + "shell.execute_reply": "2026-10-27T13:40:25.701078Z" } }, "outputs": [ @@ -1012,7 +1013,7 @@ }, { "cell_type": "markdown", - "id": "64b02f21", + "id": "92a87873", "metadata": {}, "source": [ "## The envelope calculation, and where it goes wrong\n", @@ -1025,13 +1026,13 @@ { "cell_type": "code", "execution_count": 19, - "id": "052efecb", + "id": "abb40694", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:41.272056Z", - "iopub.status.busy": "2026-10-22T17:59:41.271440Z", - "iopub.status.idle": "2026-10-22T17:59:41.283944Z", - "shell.execute_reply": "2026-10-22T17:59:41.282102Z" + "iopub.execute_input": "2026-10-27T13:40:25.704398Z", + "iopub.status.busy": "2026-10-27T13:40:25.704095Z", + "iopub.status.idle": "2026-10-27T13:40:25.709925Z", + "shell.execute_reply": "2026-10-27T13:40:25.708960Z" } }, "outputs": [ @@ -1063,7 +1064,7 @@ }, { "cell_type": "markdown", - "id": "c44f3ae7", + "id": "ffdd119e", "metadata": {}, "source": [ "The envelope says no solar at the table's price, and the model agreed. Now find the price at which\n", @@ -1074,13 +1075,13 @@ { "cell_type": "code", "execution_count": 20, - "id": "8caf8eca", + "id": "c2536c5b", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:41.288466Z", - "iopub.status.busy": "2026-10-22T17:59:41.287878Z", - "iopub.status.idle": "2026-10-22T17:59:58.032130Z", - "shell.execute_reply": "2026-10-22T17:59:58.030328Z" + "iopub.execute_input": "2026-10-27T13:40:25.712272Z", + "iopub.status.busy": "2026-10-27T13:40:25.712003Z", + "iopub.status.idle": "2026-10-27T13:40:31.306618Z", + "shell.execute_reply": "2026-10-27T13:40:31.305772Z" } }, "outputs": [ @@ -1154,7 +1155,7 @@ }, { "cell_type": "markdown", - "id": "f9e4fe1e", + "id": "56b5beb5", "metadata": {}, "source": [ "The model builds solar well above the price the envelope allowed. The envelope valued solar at the\n", @@ -1174,13 +1175,13 @@ { "cell_type": "code", "execution_count": 21, - "id": "fbf97302", + "id": "ec6d3317", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T17:59:58.036574Z", - "iopub.status.busy": "2026-10-22T17:59:58.036008Z", - "iopub.status.idle": "2026-10-22T18:00:21.370944Z", - "shell.execute_reply": "2026-10-22T18:00:21.369116Z" + "iopub.execute_input": "2026-10-27T13:40:31.308787Z", + "iopub.status.busy": "2026-10-27T13:40:31.308584Z", + "iopub.status.idle": "2026-10-27T13:40:39.704424Z", + "shell.execute_reply": "2026-10-27T13:40:39.703547Z" } }, "outputs": [ @@ -1221,7 +1222,7 @@ }, { "cell_type": "markdown", - "id": "e605b94d", + "id": "0c83919b", "metadata": {}, "source": [ "## The agreement assertion\n", @@ -1239,13 +1240,13 @@ { "cell_type": "code", "execution_count": 22, - "id": "ee7a5167", + "id": "92bc1d6b", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T18:00:21.375525Z", - "iopub.status.busy": "2026-10-22T18:00:21.374938Z", - "iopub.status.idle": "2026-10-22T18:00:21.391991Z", - "shell.execute_reply": "2026-10-22T18:00:21.390116Z" + "iopub.execute_input": "2026-10-27T13:40:39.706846Z", + "iopub.status.busy": "2026-10-27T13:40:39.706631Z", + "iopub.status.idle": "2026-10-27T13:40:39.714215Z", + "shell.execute_reply": "2026-10-27T13:40:39.713160Z" } }, "outputs": [ @@ -1295,7 +1296,7 @@ }, { "cell_type": "markdown", - "id": "2c5c4ca7", + "id": "bf7ef61a", "metadata": {}, "source": [ "---\n", @@ -1315,13 +1316,13 @@ { "cell_type": "code", "execution_count": 23, - "id": "9d76fcf7", + "id": "fbaca2c7", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T18:00:21.396413Z", - "iopub.status.busy": "2026-10-22T18:00:21.395841Z", - "iopub.status.idle": "2026-10-22T18:00:24.373702Z", - "shell.execute_reply": "2026-10-22T18:00:24.371921Z" + "iopub.execute_input": "2026-10-27T13:40:39.716481Z", + "iopub.status.busy": "2026-10-27T13:40:39.716204Z", + "iopub.status.idle": "2026-10-27T13:40:40.731113Z", + "shell.execute_reply": "2026-10-27T13:40:40.730292Z" } }, "outputs": [ @@ -1362,7 +1363,7 @@ }, { "cell_type": "markdown", - "id": "29780c8e", + "id": "673325c4", "metadata": {}, "source": [ "### Slide it: one day, with a battery\n", @@ -1374,13 +1375,13 @@ { "cell_type": "code", "execution_count": 24, - "id": "26460902", + "id": "3af6189b", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T18:00:24.378160Z", - "iopub.status.busy": "2026-10-22T18:00:24.377590Z", - "iopub.status.idle": "2026-10-22T18:00:24.392113Z", - "shell.execute_reply": "2026-10-22T18:00:24.390320Z" + "iopub.execute_input": "2026-10-27T13:40:40.733474Z", + "iopub.status.busy": "2026-10-27T13:40:40.733192Z", + "iopub.status.idle": "2026-10-27T13:40:40.739547Z", + "shell.execute_reply": "2026-10-27T13:40:40.738629Z" } }, "outputs": [], @@ -1412,7 +1413,7 @@ }, { "cell_type": "markdown", - "id": "71ad217f", + "id": "25c4f0dc", "metadata": {}, "source": [ "Move the sliders, then press **Run Interact**.\n", @@ -1431,20 +1432,20 @@ { "cell_type": "code", "execution_count": 25, - "id": "dc2c6052", + "id": "99974dd7", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T18:00:24.396582Z", - "iopub.status.busy": "2026-10-22T18:00:24.395991Z", - "iopub.status.idle": "2026-10-22T18:00:24.554260Z", - "shell.execute_reply": "2026-10-22T18:00:24.552477Z" + "iopub.execute_input": "2026-10-27T13:40:40.742118Z", + "iopub.status.busy": "2026-10-27T13:40:40.741910Z", + "iopub.status.idle": "2026-10-27T13:40:40.771828Z", + "shell.execute_reply": "2026-10-27T13:40:40.770953Z" } }, "outputs": [ { "data": { "application/vnd.jupyter.widget-view+json": { - "model_id": "e2217bb1d776498ab571242173c11268", + "model_id": "d5678e8e1c044f33adbe9ace7b11df00", "version_major": 2, "version_minor": 0 }, @@ -1468,7 +1469,7 @@ }, { "cell_type": "markdown", - "id": "f69a989e", + "id": "2c205abc", "metadata": {}, "source": [ "### Slide it: what gets built\n", @@ -1480,13 +1481,13 @@ { "cell_type": "code", "execution_count": 26, - "id": "89d5a72f", + "id": "79276064", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T18:00:24.558551Z", - "iopub.status.busy": "2026-10-22T18:00:24.557999Z", - "iopub.status.idle": "2026-10-22T18:00:28.000659Z", - "shell.execute_reply": "2026-10-22T18:00:27.994864Z" + "iopub.execute_input": "2026-10-27T13:40:40.774717Z", + "iopub.status.busy": "2026-10-27T13:40:40.774381Z", + "iopub.status.idle": "2026-10-27T13:40:41.868635Z", + "shell.execute_reply": "2026-10-27T13:40:41.867660Z" } }, "outputs": [ @@ -1500,7 +1501,7 @@ { "data": { "application/vnd.jupyter.widget-view+json": { - "model_id": "ca32b79ce94d4906ab9d74a11abdb4ea", + "model_id": "3069b9ccc9f34f879adeaa1590d4c271", "version_major": 2, "version_minor": 0 }, @@ -1540,7 +1541,7 @@ }, { "cell_type": "markdown", - "id": "6f2020c8", + "id": "8fc9c553", "metadata": {}, "source": [ "> **4.** Find the solar capital cost at which the model starts to build solar. Then double the\n", @@ -1557,13 +1558,13 @@ { "cell_type": "code", "execution_count": 27, - "id": "8cb794fa", + "id": "20463945", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T18:00:28.005283Z", - "iopub.status.busy": "2026-10-22T18:00:28.004710Z", - "iopub.status.idle": "2026-10-22T18:00:28.017171Z", - "shell.execute_reply": "2026-10-22T18:00:28.015321Z" + "iopub.execute_input": "2026-10-27T13:40:41.871700Z", + "iopub.status.busy": "2026-10-27T13:40:41.871434Z", + "iopub.status.idle": "2026-10-27T13:40:41.878362Z", + "shell.execute_reply": "2026-10-27T13:40:41.877602Z" } }, "outputs": [ @@ -1596,7 +1597,7 @@ }, { "cell_type": "markdown", - "id": "74bc837b", + "id": "60b5f607", "metadata": {}, "source": [ "> **5.** Before you run: what happens to solar's output, and to the price? After: which technology is\n", @@ -1611,13 +1612,13 @@ { "cell_type": "code", "execution_count": 28, - "id": "ce62958a", + "id": "fc95defc", "metadata": { "execution": { - "iopub.execute_input": "2026-10-22T18:00:28.021612Z", - "iopub.status.busy": "2026-10-22T18:00:28.021025Z", - "iopub.status.idle": "2026-10-22T18:00:31.434836Z", - "shell.execute_reply": "2026-10-22T18:00:31.432968Z" + "iopub.execute_input": "2026-10-27T13:40:41.880957Z", + "iopub.status.busy": "2026-10-27T13:40:41.880684Z", + "iopub.status.idle": "2026-10-27T13:40:43.025969Z", + "shell.execute_reply": "2026-10-27T13:40:43.025317Z" } }, "outputs": [ @@ -1647,7 +1648,7 @@ }, { "cell_type": "markdown", - "id": "a25a6213", + "id": "a406a9ff", "metadata": {}, "source": [ "> **6.** Predict what the battery does when the peak moves to 13:00, then run it. Which result in\n", @@ -1656,7 +1657,7 @@ }, { "cell_type": "markdown", - "id": "0118d298", + "id": "de597b4f", "metadata": {}, "source": [ "---\n", @@ -1695,7 +1696,7 @@ "widgets": { "application/vnd.jupyter.widget-state+json": { "state": { - "0148289762154f2cb8b783ac7b12def6": { + "09aa90e1a106445dad8597b8c2341df4": { "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", @@ -1748,27 +1749,38 @@ "width": null } }, - "066352e54eda4f19b5e64b918da26f7a": { - "model_module": "@jupyter-widgets/output", - "model_module_version": "1.0.0", - "model_name": "OutputModel", + "0a974152adda43919cfea490a12d1de0": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "FloatSliderModel", "state": { "_dom_classes": [], - "_model_module": "@jupyter-widgets/output", - "_model_module_version": "1.0.0", - "_model_name": "OutputModel", + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "FloatSliderModel", "_view_count": null, - "_view_module": "@jupyter-widgets/output", - "_view_module_version": "1.0.0", - "_view_name": "OutputView", - "layout": "IPY_MODEL_100fec923dc841afb2aa24f4fa899f1d", - "msg_id": "", - "outputs": [], + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "FloatSliderView", + "behavior": "drag-tap", + "continuous_update": true, + "description": "peaker $/MWh", + "description_allow_html": false, + "disabled": false, + "layout": "IPY_MODEL_c7045bc3fe3b47249ecf2e7180fbff6c", + "max": 400.0, + "min": 40.0, + "orientation": "horizontal", + "readout": true, + "readout_format": ".2f", + "step": 10.0, + "style": "IPY_MODEL_21f0747574c2436cbe8c478d02ea31e3", "tabbable": null, - "tooltip": null + "tooltip": null, + "value": 80.0 } }, - "0d3cf40aa6594decb398675a195b225b": { + "0ccbc9735e7e4568843569459f4c268f": { "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "SliderStyleModel", @@ -1784,7 +1796,38 @@ "handle_color": null } }, - "100fec923dc841afb2aa24f4fa899f1d": { + "0d1bac9e44e04d58bf3d84dfb1725450": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "IntSliderModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "IntSliderModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "IntSliderView", + "behavior": "drag-tap", + "continuous_update": true, + "description": "peak hour", + "description_allow_html": false, + "disabled": false, + "layout": "IPY_MODEL_f71f453302114889b2d414da7ce140a4", + "max": 23, + "min": 0, + "orientation": "horizontal", + "readout": true, + "readout_format": "d", + "step": 1, + "style": "IPY_MODEL_2d6c1f7e0a544284bdf1b1d4d7258d54", + "tabbable": null, + "tooltip": null, + "value": 19 + } + }, + "15aaa8f87a554af294fd699712914329": { "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", @@ -1837,133 +1880,82 @@ "width": null } }, - "198ddfd4f9ff4285b2984882b034ab68": { - "model_module": "@jupyter-widgets/base", + "1fc6053b60c0473282ba08b1b80b4287": { + "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", - "model_name": "LayoutModel", + "model_name": "SliderStyleModel", "state": { - "_model_module": "@jupyter-widgets/base", + "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", - "_model_name": "LayoutModel", + "_model_name": "SliderStyleModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", - "_view_name": "LayoutView", - "align_content": null, - "align_items": null, - "align_self": null, - "border_bottom": null, - "border_left": null, - "border_right": null, - "border_top": null, - "bottom": null, - "display": null, - "flex": null, - "flex_flow": null, - "grid_area": null, - "grid_auto_columns": null, - "grid_auto_flow": null, - "grid_auto_rows": null, - "grid_column": null, - "grid_gap": null, - "grid_row": null, - "grid_template_areas": null, - "grid_template_columns": null, - "grid_template_rows": null, - "height": null, - "justify_content": null, - "justify_items": null, - "left": null, - "margin": null, - "max_height": null, - "max_width": null, - "min_height": null, - "min_width": null, - "object_fit": null, - "object_position": null, - "order": null, - "overflow": null, - "padding": null, - "right": null, - "top": null, - "visibility": null, - "width": null + "_view_name": "StyleView", + "description_width": "", + "handle_color": null } }, - "2474bf65f7e0457493bdb4893f495f07": { - "model_module": "@jupyter-widgets/output", - "model_module_version": "1.0.0", - "model_name": "OutputModel", + "21f0747574c2436cbe8c478d02ea31e3": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "SliderStyleModel", "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/output", - "_model_module_version": "1.0.0", - "_model_name": "OutputModel", + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "SliderStyleModel", "_view_count": null, - "_view_module": "@jupyter-widgets/output", - "_view_module_version": "1.0.0", - "_view_name": "OutputView", - "layout": "IPY_MODEL_9872dcbf232d4ed0ae11fb47da686996", - "msg_id": "", - "outputs": [], - "tabbable": null, - "tooltip": null + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "StyleView", + "description_width": "", + "handle_color": null } }, - "46ce47f318cc49078a870dbed616c3df": { - "model_module": "@jupyter-widgets/base", + "2d6c1f7e0a544284bdf1b1d4d7258d54": { + "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", - "model_name": "LayoutModel", + "model_name": "SliderStyleModel", "state": { - "_model_module": "@jupyter-widgets/base", + "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", - "_model_name": "LayoutModel", + "_model_name": "SliderStyleModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", - "_view_name": "LayoutView", - "align_content": null, - "align_items": null, - "align_self": null, - "border_bottom": null, - "border_left": null, - "border_right": null, - "border_top": null, - "bottom": null, - "display": null, - "flex": null, - "flex_flow": null, - "grid_area": null, - "grid_auto_columns": null, - "grid_auto_flow": null, - "grid_auto_rows": null, - "grid_column": null, - "grid_gap": null, - "grid_row": null, - "grid_template_areas": null, - "grid_template_columns": null, - "grid_template_rows": null, - "height": null, - "justify_content": null, - "justify_items": null, - "left": null, - "margin": null, - "max_height": null, - "max_width": null, - "min_height": null, - "min_width": null, - "object_fit": null, - "object_position": null, - "order": null, - "overflow": null, - "padding": null, - "right": null, - "top": null, - "visibility": null, - "width": null + "_view_name": "StyleView", + "description_width": "", + "handle_color": null + } + }, + "3069b9ccc9f34f879adeaa1590d4c271": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "VBoxModel", + "state": { + "_dom_classes": [ + "widget-interact" + ], + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "VBoxModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "VBoxView", + "box_style": "", + "children": [ + "IPY_MODEL_fcd7c215d0cf4e75af88ba34253d4fae", + "IPY_MODEL_41a72f9fdeb34f808299991d031c0d94", + "IPY_MODEL_66bc789994004757ac3b5db6f63c5abe", + "IPY_MODEL_b3aa5fad5eda435e96ff7e3d360801bf" + ], + "layout": "IPY_MODEL_8663cd6056b44dd19bfe467d1b00df1d", + "tabbable": null, + "tooltip": null } }, - "4879a8d08e9d462c81d036c2ccb8a086": { + "368ebadf782b45b18ecf84c7cbee5ce8": { "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", @@ -2016,76 +2008,85 @@ "width": null } }, - "4aeb836b5b87446baa0d475ecea0e864": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "2.0.0", - "model_name": "ButtonStyleModel", - "state": { - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "2.0.0", - "_model_name": "ButtonStyleModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "2.0.0", - "_view_name": "StyleView", - "button_color": null, - "font_family": null, - "font_size": null, - "font_style": null, - "font_variant": null, - "font_weight": null, - "text_color": null, - "text_decoration": null - } - }, - "5a8dee68e2ae4f08a42aaa2a5bc7e63f": { + "419e5ca8b2bf48f586aecd5bc9c03a18": { "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", - "model_name": "SliderStyleModel", + "model_name": "FloatSliderModel", "state": { + "_dom_classes": [], "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", - "_model_name": "SliderStyleModel", + "_model_name": "FloatSliderModel", "_view_count": null, - "_view_module": "@jupyter-widgets/base", + "_view_module": "@jupyter-widgets/controls", "_view_module_version": "2.0.0", - "_view_name": "StyleView", - "description_width": "", - "handle_color": null + "_view_name": "FloatSliderView", + "behavior": "drag-tap", + "continuous_update": true, + "description": "battery h", + "description_allow_html": false, + "disabled": false, + "layout": "IPY_MODEL_ec2b6c8bd2e8459b866cb407cbb21c89", + "max": 8.0, + "min": 1.0, + "orientation": "horizontal", + "readout": true, + "readout_format": ".2f", + "step": 1.0, + "style": "IPY_MODEL_1fc6053b60c0473282ba08b1b80b4287", + "tabbable": null, + "tooltip": null, + "value": 4.0 } }, - "5c750366d6a643e99fb4cddab4658367": { + "41a72f9fdeb34f808299991d031c0d94": { "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", - "model_name": "IntSliderModel", + "model_name": "FloatSliderModel", "state": { "_dom_classes": [], "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", - "_model_name": "IntSliderModel", + "_model_name": "FloatSliderModel", "_view_count": null, "_view_module": "@jupyter-widgets/controls", "_view_module_version": "2.0.0", - "_view_name": "IntSliderView", + "_view_name": "FloatSliderView", "behavior": "drag-tap", "continuous_update": true, - "description": "peak hour", + "description": "battery MW", "description_allow_html": false, "disabled": false, - "layout": "IPY_MODEL_198ddfd4f9ff4285b2984882b034ab68", - "max": 23, - "min": 0, + "layout": "IPY_MODEL_606c526b7b2344a28e5d7ef74905d4d5", + "max": 150.0, + "min": 0.0, "orientation": "horizontal", "readout": true, - "readout_format": "d", - "step": 1, - "style": "IPY_MODEL_ebe9ccc728344be4b8d3873264b42ca3", + "readout_format": ".2f", + "step": 10.0, + "style": "IPY_MODEL_672350490d7e4885a16e7722d39e7187", "tabbable": null, "tooltip": null, - "value": 19 + "value": 40.0 + } + }, + "560a80682b7c4408b9e936e83cb37fa5": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "SliderStyleModel", + "state": { + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "SliderStyleModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "StyleView", + "description_width": "", + "handle_color": null } }, - "5e566fa8bd9449349e68908ea34ca3af": { + "606c526b7b2344a28e5d7ef74905d4d5": { "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", @@ -2138,7 +2139,7 @@ "width": null } }, - "5e99ebe89e6048849cb1e2af287faf47": { + "66bc789994004757ac3b5db6f63c5abe": { "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "ButtonModel", @@ -2155,13 +2156,13 @@ "description": "Run Interact", "disabled": false, "icon": "", - "layout": "IPY_MODEL_46ce47f318cc49078a870dbed616c3df", - "style": "IPY_MODEL_d5b1dbb92a8a41669295690db50cfaf7", + "layout": "IPY_MODEL_e1b557db9de244e9b59c37d7b4a09e0d", + "style": "IPY_MODEL_8e37dc0ce1534a49a9cbb9beffdeca6b", "tabbable": null, "tooltip": null } }, - "614f637c13f04599809c0403f4d642e9": { + "672350490d7e4885a16e7722d39e7187": { "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "SliderStyleModel", @@ -2177,38 +2178,7 @@ "handle_color": null } }, - "7b154bad123c4abeb826a89ee52113c1": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "2.0.0", - "model_name": "FloatSliderModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "2.0.0", - "_model_name": "FloatSliderModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "2.0.0", - "_view_name": "FloatSliderView", - "behavior": "drag-tap", - "continuous_update": true, - "description": "battery MW", - "description_allow_html": false, - "disabled": false, - "layout": "IPY_MODEL_0148289762154f2cb8b783ac7b12def6", - "max": 150.0, - "min": 0.0, - "orientation": "horizontal", - "readout": true, - "readout_format": ".2f", - "step": 10.0, - "style": "IPY_MODEL_0d3cf40aa6594decb398675a195b225b", - "tabbable": null, - "tooltip": null, - "value": 40.0 - } - }, - "8708869465f14e4b84e0329d90ff71ea": { + "68ce9cb222a94b9992ccb821f82a1ea9": { "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", @@ -2261,38 +2231,7 @@ "width": null } }, - "91ad767011e4462582d67985d8c70ce5": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "2.0.0", - "model_name": "FloatSliderModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "2.0.0", - "_model_name": "FloatSliderModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "2.0.0", - "_view_name": "FloatSliderView", - "behavior": "drag-tap", - "continuous_update": true, - "description": "battery h", - "description_allow_html": false, - "disabled": false, - "layout": "IPY_MODEL_fa7bdea9cac241eea060618f850d1da4", - "max": 8.0, - "min": 1.0, - "orientation": "horizontal", - "readout": true, - "readout_format": ".2f", - "step": 1.0, - "style": "IPY_MODEL_5a8dee68e2ae4f08a42aaa2a5bc7e63f", - "tabbable": null, - "tooltip": null, - "value": 4.0 - } - }, - "9872dcbf232d4ed0ae11fb47da686996": { + "8663cd6056b44dd19bfe467d1b00df1d": { "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", @@ -2345,159 +2284,135 @@ "width": null } }, - "a94490e2a3e14ec9be4a54a3498aeaa2": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "2.0.0", - "model_name": "FloatSliderModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "2.0.0", - "_model_name": "FloatSliderModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "2.0.0", - "_view_name": "FloatSliderView", - "behavior": "drag-tap", - "continuous_update": true, - "description": "solar $/MW-yr", - "description_allow_html": false, - "disabled": false, - "layout": "IPY_MODEL_f19f6155c8a24c3481a3532d91e8a22f", - "max": 120000.0, - "min": 40000.0, - "orientation": "horizontal", - "readout": true, - "readout_format": ".2f", - "step": 1000.0, - "style": "IPY_MODEL_bf37c35e17dd43578383ca51edbd9366", - "tabbable": null, - "tooltip": null, - "value": 90000.0 - } - }, - "a94926e32c0c465bba533b16f4bdbe31": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "2.0.0", - "model_name": "FloatSliderModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "2.0.0", - "_model_name": "FloatSliderModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "2.0.0", - "_view_name": "FloatSliderView", - "behavior": "drag-tap", - "continuous_update": true, - "description": "solar MW", - "description_allow_html": false, - "disabled": false, - "layout": "IPY_MODEL_8708869465f14e4b84e0329d90ff71ea", - "max": 400.0, - "min": 0.0, - "orientation": "horizontal", - "readout": true, - "readout_format": ".2f", - "step": 20.0, - "style": "IPY_MODEL_cb617f46517c4720b26195f63d1b43c0", - "tabbable": null, - "tooltip": null, - "value": 140.0 - } - }, - "bd46bec417cd4fc4be954d43ad35dcc7": { + "8e37dc0ce1534a49a9cbb9beffdeca6b": { "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", - "model_name": "FloatSliderModel", + "model_name": "ButtonStyleModel", "state": { - "_dom_classes": [], "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", - "_model_name": "FloatSliderModel", + "_model_name": "ButtonStyleModel", "_view_count": null, - "_view_module": "@jupyter-widgets/controls", + "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", - "_view_name": "FloatSliderView", - "behavior": "drag-tap", - "continuous_update": true, - "description": "peaker $/MWh", - "description_allow_html": false, - "disabled": false, - "layout": "IPY_MODEL_4879a8d08e9d462c81d036c2ccb8a086", - "max": 400.0, - "min": 40.0, - "orientation": "horizontal", - "readout": true, - "readout_format": ".2f", - "step": 10.0, - "style": "IPY_MODEL_614f637c13f04599809c0403f4d642e9", - "tabbable": null, - "tooltip": null, - "value": 80.0 + "_view_name": "StyleView", + "button_color": null, + "font_family": null, + "font_size": null, + "font_style": null, + "font_variant": null, + "font_weight": null, + "text_color": null, + "text_decoration": null } }, - "bf37c35e17dd43578383ca51edbd9366": { + "99b221152e864a29a33cc918c0df7504": { "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", - "model_name": "SliderStyleModel", + "model_name": "ButtonStyleModel", "state": { "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", - "_model_name": "SliderStyleModel", + "_model_name": "ButtonStyleModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", "_view_name": "StyleView", - "description_width": "", - "handle_color": null + "button_color": null, + "font_family": null, + "font_size": null, + "font_style": null, + "font_variant": null, + "font_weight": null, + "text_color": null, + "text_decoration": null } }, - "ca32b79ce94d4906ab9d74a11abdb4ea": { - "model_module": "@jupyter-widgets/controls", + "9eb7e5352e184807a6144a4b54905a68": { + "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", - "model_name": "VBoxModel", + "model_name": "LayoutModel", "state": { - "_dom_classes": [ - "widget-interact" - ], - "_model_module": "@jupyter-widgets/controls", + "_model_module": "@jupyter-widgets/base", "_model_module_version": "2.0.0", - "_model_name": "VBoxModel", + "_model_name": "LayoutModel", "_view_count": null, - "_view_module": "@jupyter-widgets/controls", + "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", - "_view_name": "VBoxView", - "box_style": "", - "children": [ - "IPY_MODEL_a94490e2a3e14ec9be4a54a3498aeaa2", - "IPY_MODEL_7b154bad123c4abeb826a89ee52113c1", - "IPY_MODEL_5e99ebe89e6048849cb1e2af287faf47", - "IPY_MODEL_2474bf65f7e0457493bdb4893f495f07" - ], - "layout": "IPY_MODEL_f146fed8e50f4636b415bc8bb12fabc9", - "tabbable": null, - "tooltip": null + "_view_name": "LayoutView", + "align_content": null, + "align_items": null, + "align_self": null, + "border_bottom": null, + "border_left": null, + "border_right": null, + "border_top": null, + "bottom": null, + "display": null, + "flex": null, + "flex_flow": null, + "grid_area": null, + "grid_auto_columns": null, + "grid_auto_flow": null, + "grid_auto_rows": null, + "grid_column": null, + "grid_gap": null, + "grid_row": null, + "grid_template_areas": null, + "grid_template_columns": null, + "grid_template_rows": null, + "height": null, + "justify_content": null, + "justify_items": null, + "left": null, + "margin": null, + "max_height": null, + "max_width": null, + "min_height": null, + "min_width": null, + "object_fit": null, + "object_position": null, + "order": null, + "overflow": null, + "padding": null, + "right": null, + "top": null, + "visibility": null, + "width": null } }, - "cb617f46517c4720b26195f63d1b43c0": { + "a29f560b26994caf84cc9bc6b6793cc6": { "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", - "model_name": "SliderStyleModel", + "model_name": "FloatSliderModel", "state": { + "_dom_classes": [], "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", - "_model_name": "SliderStyleModel", + "_model_name": "FloatSliderModel", "_view_count": null, - "_view_module": "@jupyter-widgets/base", + "_view_module": "@jupyter-widgets/controls", "_view_module_version": "2.0.0", - "_view_name": "StyleView", - "description_width": "", - "handle_color": null + "_view_name": "FloatSliderView", + "behavior": "drag-tap", + "continuous_update": true, + "description": "battery MW", + "description_allow_html": false, + "disabled": false, + "layout": "IPY_MODEL_15aaa8f87a554af294fd699712914329", + "max": 150.0, + "min": 0.0, + "orientation": "horizontal", + "readout": true, + "readout_format": ".2f", + "step": 10.0, + "style": "IPY_MODEL_f60f52cfed6444a98426941fea670e7f", + "tabbable": null, + "tooltip": null, + "value": 40.0 } }, - "cc4bf1378ca9466785759656d4ed6095": { + "ac12f8ae7c254bfdafd7cb8ad560c728": { "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", @@ -2550,7 +2465,47 @@ "width": null } }, - "ccf2f0abde1a423cb121c1491d39a900": { + "ae59cf1000a044fc8223e209fe26adc6": { + "model_module": "@jupyter-widgets/output", + "model_module_version": "1.0.0", + "model_name": "OutputModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/output", + "_model_module_version": "1.0.0", + "_model_name": "OutputModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/output", + "_view_module_version": "1.0.0", + "_view_name": "OutputView", + "layout": "IPY_MODEL_9eb7e5352e184807a6144a4b54905a68", + "msg_id": "", + "outputs": [], + "tabbable": null, + "tooltip": null + } + }, + "b3aa5fad5eda435e96ff7e3d360801bf": { + "model_module": "@jupyter-widgets/output", + "model_module_version": "1.0.0", + "model_name": "OutputModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/output", + "_model_module_version": "1.0.0", + "_model_name": "OutputModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/output", + "_view_module_version": "1.0.0", + "_view_name": "OutputView", + "layout": "IPY_MODEL_dc409baad0534d399c4ee8c800d450c5", + "msg_id": "", + "outputs": [], + "tabbable": null, + "tooltip": null + } + }, + "c7045bc3fe3b47249ecf2e7180fbff6c": { "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", @@ -2603,82 +2558,7 @@ "width": null } }, - "d5b1dbb92a8a41669295690db50cfaf7": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "2.0.0", - "model_name": "ButtonStyleModel", - "state": { - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "2.0.0", - "_model_name": "ButtonStyleModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "2.0.0", - "_view_name": "StyleView", - "button_color": null, - "font_family": null, - "font_size": null, - "font_style": null, - "font_variant": null, - "font_weight": null, - "text_color": null, - "text_decoration": null - } - }, - "e2217bb1d776498ab571242173c11268": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "2.0.0", - "model_name": "VBoxModel", - "state": { - "_dom_classes": [ - "widget-interact" - ], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "2.0.0", - "_model_name": "VBoxModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "2.0.0", - "_view_name": "VBoxView", - "box_style": "", - "children": [ - "IPY_MODEL_e877baf67d5d4ceaa4e02d4a33633da5", - "IPY_MODEL_91ad767011e4462582d67985d8c70ce5", - "IPY_MODEL_a94926e32c0c465bba533b16f4bdbe31", - "IPY_MODEL_bd46bec417cd4fc4be954d43ad35dcc7", - "IPY_MODEL_5c750366d6a643e99fb4cddab4658367", - "IPY_MODEL_e84c129762a346eebbbaf21f11e870de", - "IPY_MODEL_066352e54eda4f19b5e64b918da26f7a" - ], - "layout": "IPY_MODEL_cc4bf1378ca9466785759656d4ed6095", - "tabbable": null, - "tooltip": null - } - }, - "e84c129762a346eebbbaf21f11e870de": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "2.0.0", - "model_name": "ButtonModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "2.0.0", - "_model_name": "ButtonModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "2.0.0", - "_view_name": "ButtonView", - "button_style": "", - "description": "Run Interact", - "disabled": false, - "icon": "", - "layout": "IPY_MODEL_ccf2f0abde1a423cb121c1491d39a900", - "style": "IPY_MODEL_4aeb836b5b87446baa0d475ecea0e864", - "tabbable": null, - "tooltip": null - } - }, - "e877baf67d5d4ceaa4e02d4a33633da5": { + "d48d13108c874c07a94ec8a21072d016": { "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "FloatSliderModel", @@ -2693,39 +2573,53 @@ "_view_name": "FloatSliderView", "behavior": "drag-tap", "continuous_update": true, - "description": "battery MW", + "description": "solar MW", "description_allow_html": false, "disabled": false, - "layout": "IPY_MODEL_5e566fa8bd9449349e68908ea34ca3af", - "max": 150.0, + "layout": "IPY_MODEL_68ce9cb222a94b9992ccb821f82a1ea9", + "max": 400.0, "min": 0.0, "orientation": "horizontal", "readout": true, "readout_format": ".2f", - "step": 10.0, - "style": "IPY_MODEL_f14e6f5131894f519e8e32ace6ca1ec3", + "step": 20.0, + "style": "IPY_MODEL_560a80682b7c4408b9e936e83cb37fa5", "tabbable": null, "tooltip": null, - "value": 40.0 + "value": 140.0 } }, - "ebe9ccc728344be4b8d3873264b42ca3": { + "d5678e8e1c044f33adbe9ace7b11df00": { "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", - "model_name": "SliderStyleModel", + "model_name": "VBoxModel", "state": { + "_dom_classes": [ + "widget-interact" + ], "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", - "_model_name": "SliderStyleModel", + "_model_name": "VBoxModel", "_view_count": null, - "_view_module": "@jupyter-widgets/base", + "_view_module": "@jupyter-widgets/controls", "_view_module_version": "2.0.0", - "_view_name": "StyleView", - "description_width": "", - "handle_color": null + "_view_name": "VBoxView", + "box_style": "", + "children": [ + "IPY_MODEL_a29f560b26994caf84cc9bc6b6793cc6", + "IPY_MODEL_419e5ca8b2bf48f586aecd5bc9c03a18", + "IPY_MODEL_d48d13108c874c07a94ec8a21072d016", + "IPY_MODEL_0a974152adda43919cfea490a12d1de0", + "IPY_MODEL_0d1bac9e44e04d58bf3d84dfb1725450", + "IPY_MODEL_f2b363df4884427a920451ecea0c6efc", + "IPY_MODEL_ae59cf1000a044fc8223e209fe26adc6" + ], + "layout": "IPY_MODEL_368ebadf782b45b18ecf84c7cbee5ce8", + "tabbable": null, + "tooltip": null } }, - "f146fed8e50f4636b415bc8bb12fabc9": { + "dc409baad0534d399c4ee8c800d450c5": { "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", @@ -2778,23 +2672,60 @@ "width": null } }, - "f14e6f5131894f519e8e32ace6ca1ec3": { - "model_module": "@jupyter-widgets/controls", + "e1b557db9de244e9b59c37d7b4a09e0d": { + "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", - "model_name": "SliderStyleModel", + "model_name": "LayoutModel", "state": { - "_model_module": "@jupyter-widgets/controls", + "_model_module": "@jupyter-widgets/base", "_model_module_version": "2.0.0", - "_model_name": "SliderStyleModel", + "_model_name": "LayoutModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", - "_view_name": "StyleView", - "description_width": "", - "handle_color": null + "_view_name": "LayoutView", + "align_content": null, + "align_items": null, + "align_self": null, + "border_bottom": null, + "border_left": null, + "border_right": null, + "border_top": null, + "bottom": null, + "display": null, + "flex": null, + "flex_flow": null, + "grid_area": null, + "grid_auto_columns": null, + "grid_auto_flow": null, + "grid_auto_rows": null, + "grid_column": null, + "grid_gap": null, + "grid_row": null, + "grid_template_areas": null, + "grid_template_columns": null, + "grid_template_rows": null, + "height": null, + "justify_content": null, + "justify_items": null, + "left": null, + "margin": null, + "max_height": null, + "max_width": null, + "min_height": null, + "min_width": null, + "object_fit": null, + "object_position": null, + "order": null, + "overflow": null, + "padding": null, + "right": null, + "top": null, + "visibility": null, + "width": null } }, - "f19f6155c8a24c3481a3532d91e8a22f": { + "ec2b6c8bd2e8459b866cb407cbb21c89": { "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", @@ -2847,7 +2778,46 @@ "width": null } }, - "fa7bdea9cac241eea060618f850d1da4": { + "f2b363df4884427a920451ecea0c6efc": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "ButtonModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "ButtonModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "ButtonView", + "button_style": "", + "description": "Run Interact", + "disabled": false, + "icon": "", + "layout": "IPY_MODEL_ac12f8ae7c254bfdafd7cb8ad560c728", + "style": "IPY_MODEL_99b221152e864a29a33cc918c0df7504", + "tabbable": null, + "tooltip": null + } + }, + "f60f52cfed6444a98426941fea670e7f": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "SliderStyleModel", + "state": { + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "SliderStyleModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "StyleView", + "description_width": "", + "handle_color": null + } + }, + "f71f453302114889b2d414da7ce140a4": { "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", @@ -2899,6 +2869,37 @@ "visibility": null, "width": null } + }, + "fcd7c215d0cf4e75af88ba34253d4fae": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "FloatSliderModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "FloatSliderModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "FloatSliderView", + "behavior": "drag-tap", + "continuous_update": true, + "description": "solar $/MW-yr", + "description_allow_html": false, + "disabled": false, + "layout": "IPY_MODEL_09aa90e1a106445dad8597b8c2341df4", + "max": 120000.0, + "min": 40000.0, + "orientation": "horizontal", + "readout": true, + "readout_format": ".2f", + "step": 1000.0, + "style": "IPY_MODEL_0ccbc9735e7e4568843569459f4c268f", + "tabbable": null, + "tooltip": null, + "value": 90000.0 + } } }, "version_major": 2, diff --git a/notebooks/13_supply_chain/sourcing_and_resilience.ipynb b/notebooks/13_supply_chain/sourcing_and_resilience.ipynb index fd28cc9..2ba5ab0 100644 --- a/notebooks/13_supply_chain/sourcing_and_resilience.ipynb +++ b/notebooks/13_supply_chain/sourcing_and_resilience.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "ee652382", + "id": "c61a52e6", "metadata": {}, "source": [ "# Sourcing through a middle layer, and the price of not depending on one supplier\n", @@ -20,7 +20,7 @@ }, { "cell_type": "markdown", - "id": "06106231", + "id": "4dbe9c88", "metadata": {}, "source": [ "## Setup: where the package lives\n", @@ -33,13 +33,13 @@ { "cell_type": "code", "execution_count": 1, - "id": "2c5b084d", + "id": "ed29d3db", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.467349Z", - "iopub.status.busy": "2026-09-06T10:42:08.467180Z", - "iopub.status.idle": "2026-09-06T10:42:08.479104Z", - "shell.execute_reply": "2026-09-06T10:42:08.478628Z" + "iopub.execute_input": "2026-10-27T13:40:54.547197Z", + "iopub.status.busy": "2026-10-27T13:40:54.547022Z", + "iopub.status.idle": "2026-10-27T13:40:54.559810Z", + "shell.execute_reply": "2026-10-27T13:40:54.559319Z" } }, "outputs": [ @@ -55,6 +55,7 @@ "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", @@ -64,7 +65,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/13_supply_chain\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -80,7 +81,7 @@ }, { "cell_type": "markdown", - "id": "293cb864", + "id": "43221151", "metadata": {}, "source": [ "## Licence setup\n", @@ -94,13 +95,13 @@ { "cell_type": "code", "execution_count": 2, - "id": "06e988f1", + "id": "db7b04b3", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.481231Z", - "iopub.status.busy": "2026-09-06T10:42:08.481060Z", - "iopub.status.idle": "2026-09-06T10:42:08.528004Z", - "shell.execute_reply": "2026-09-06T10:42:08.527468Z" + "iopub.execute_input": "2026-10-27T13:40:54.561968Z", + "iopub.status.busy": "2026-10-27T13:40:54.561790Z", + "iopub.status.idle": "2026-10-27T13:40:54.622317Z", + "shell.execute_reply": "2026-10-27T13:40:54.621769Z" } }, "outputs": [ @@ -135,7 +136,7 @@ }, { "cell_type": "markdown", - "id": "4659f955", + "id": "f26ff420", "metadata": {}, "source": [ "## Four tables\n", @@ -149,13 +150,13 @@ { "cell_type": "code", "execution_count": 3, - "id": "9cfdafe5", + "id": "08f2cfb6", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.530085Z", - "iopub.status.busy": "2026-09-06T10:42:08.529873Z", - "iopub.status.idle": "2026-09-06T10:42:08.542578Z", - "shell.execute_reply": "2026-09-06T10:42:08.542092Z" + "iopub.execute_input": "2026-10-27T13:40:54.625387Z", + "iopub.status.busy": "2026-10-27T13:40:54.625065Z", + "iopub.status.idle": "2026-10-27T13:40:54.646811Z", + "shell.execute_reply": "2026-10-27T13:40:54.646160Z" } }, "outputs": [ @@ -202,7 +203,7 @@ }, { "cell_type": "markdown", - "id": "0b7ce48d", + "id": "9fdc5da9", "metadata": {}, "source": [ "## Predict before building anything\n", @@ -220,13 +221,13 @@ { "cell_type": "code", "execution_count": 4, - "id": "918c0f37", + "id": "6f960bd1", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.544611Z", - "iopub.status.busy": "2026-09-06T10:42:08.544438Z", - "iopub.status.idle": "2026-09-06T10:42:08.549361Z", - "shell.execute_reply": "2026-09-06T10:42:08.548816Z" + "iopub.execute_input": "2026-10-27T13:40:54.649618Z", + "iopub.status.busy": "2026-10-27T13:40:54.649336Z", + "iopub.status.idle": "2026-10-27T13:40:54.655204Z", + "shell.execute_reply": "2026-10-27T13:40:54.654570Z" } }, "outputs": [ @@ -250,7 +251,7 @@ }, { "cell_type": "markdown", - "id": "b592ce09", + "id": "28212335", "metadata": {}, "source": [ "## Objective: every leg's cost times its flow" @@ -259,13 +260,13 @@ { "cell_type": "code", "execution_count": 5, - "id": "a7a1196c", + "id": "12e67ebb", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.551286Z", - "iopub.status.busy": "2026-09-06T10:42:08.551115Z", - "iopub.status.idle": "2026-09-06T10:42:08.555790Z", - "shell.execute_reply": "2026-09-06T10:42:08.555325Z" + "iopub.execute_input": "2026-10-27T13:40:54.657810Z", + "iopub.status.busy": "2026-10-27T13:40:54.657627Z", + "iopub.status.idle": "2026-10-27T13:40:54.661927Z", + "shell.execute_reply": "2026-10-27T13:40:54.661377Z" } }, "outputs": [ @@ -285,7 +286,7 @@ }, { "cell_type": "markdown", - "id": "1460649c", + "id": "e7784009", "metadata": {}, "source": [ "## Capacities at both ends, requirements at the plants\n", @@ -298,13 +299,13 @@ { "cell_type": "code", "execution_count": 6, - "id": "548e67c5", + "id": "5f54af1e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.557649Z", - "iopub.status.busy": "2026-09-06T10:42:08.557483Z", - "iopub.status.idle": "2026-09-06T10:42:08.562210Z", - "shell.execute_reply": "2026-09-06T10:42:08.561747Z" + "iopub.execute_input": "2026-10-27T13:40:54.664136Z", + "iopub.status.busy": "2026-10-27T13:40:54.663913Z", + "iopub.status.idle": "2026-10-27T13:40:54.669329Z", + "shell.execute_reply": "2026-10-27T13:40:54.668792Z" } }, "outputs": [ @@ -326,7 +327,7 @@ }, { "cell_type": "markdown", - "id": "ca424c80", + "id": "b9b72fa0", "metadata": {}, "source": [ "## And conservation in the middle\n", @@ -338,13 +339,13 @@ { "cell_type": "code", "execution_count": 7, - "id": "d2798b70", + "id": "9ce69252", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.564107Z", - "iopub.status.busy": "2026-09-06T10:42:08.563938Z", - "iopub.status.idle": "2026-09-06T10:42:08.568046Z", - "shell.execute_reply": "2026-09-06T10:42:08.567553Z" + "iopub.execute_input": "2026-10-27T13:40:54.671720Z", + "iopub.status.busy": "2026-10-27T13:40:54.671537Z", + "iopub.status.idle": "2026-10-27T13:40:54.676566Z", + "shell.execute_reply": "2026-10-27T13:40:54.675814Z" } }, "outputs": [ @@ -373,7 +374,7 @@ }, { "cell_type": "markdown", - "id": "10377444", + "id": "d2d0495d", "metadata": {}, "source": [ "## Solve, and read the plan by mine and by processor" @@ -382,13 +383,13 @@ { "cell_type": "code", "execution_count": 8, - "id": "fbfc4978", + "id": "50885bdd", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.569965Z", - "iopub.status.busy": "2026-09-06T10:42:08.569799Z", - "iopub.status.idle": "2026-09-06T10:42:08.575841Z", - "shell.execute_reply": "2026-09-06T10:42:08.575324Z" + "iopub.execute_input": "2026-10-27T13:40:54.679033Z", + "iopub.status.busy": "2026-10-27T13:40:54.678767Z", + "iopub.status.idle": "2026-10-27T13:40:54.686819Z", + "shell.execute_reply": "2026-10-27T13:40:54.685824Z" } }, "outputs": [ @@ -425,7 +426,7 @@ }, { "cell_type": "markdown", - "id": "b49596a3", + "id": "e9fff98a", "metadata": {}, "source": [ "Everything from one mine, through one processor. The processor is full, and the price printed beside\n", @@ -440,13 +441,13 @@ { "cell_type": "code", "execution_count": 9, - "id": "db1f2a6b", + "id": "e9a2e80c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.577719Z", - "iopub.status.busy": "2026-09-06T10:42:08.577553Z", - "iopub.status.idle": "2026-09-06T10:42:08.582102Z", - "shell.execute_reply": "2026-09-06T10:42:08.581655Z" + "iopub.execute_input": "2026-10-27T13:40:54.689566Z", + "iopub.status.busy": "2026-10-27T13:40:54.689374Z", + "iopub.status.idle": "2026-10-27T13:40:54.695282Z", + "shell.execute_reply": "2026-10-27T13:40:54.694733Z" } }, "outputs": [ @@ -478,7 +479,7 @@ }, { "cell_type": "markdown", - "id": "05fcc5bb", + "id": "cc47f5ae", "metadata": {}, "source": [ "The zero describes one side only. A shadow price is a derivative, and here the cost has a **kink**:\n", @@ -500,13 +501,13 @@ { "cell_type": "code", "execution_count": 10, - "id": "2564129f", + "id": "673542f2", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.583971Z", - "iopub.status.busy": "2026-09-06T10:42:08.583804Z", - "iopub.status.idle": "2026-09-06T10:42:08.588735Z", - "shell.execute_reply": "2026-09-06T10:42:08.588328Z" + "iopub.execute_input": "2026-10-27T13:40:54.697477Z", + "iopub.status.busy": "2026-10-27T13:40:54.697297Z", + "iopub.status.idle": "2026-10-27T13:40:54.702656Z", + "shell.execute_reply": "2026-10-27T13:40:54.701739Z" } }, "outputs": [ @@ -533,7 +534,7 @@ }, { "cell_type": "markdown", - "id": "26bd4e86", + "id": "eb750887", "metadata": {}, "source": [ "## The price curve\n", @@ -546,13 +547,13 @@ { "cell_type": "code", "execution_count": 11, - "id": "c4707c8a", + "id": "b781bb37", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.590644Z", - "iopub.status.busy": "2026-09-06T10:42:08.590481Z", - "iopub.status.idle": "2026-09-06T10:42:08.596906Z", - "shell.execute_reply": "2026-09-06T10:42:08.596449Z" + "iopub.execute_input": "2026-10-27T13:40:54.705200Z", + "iopub.status.busy": "2026-10-27T13:40:54.705018Z", + "iopub.status.idle": "2026-10-27T13:40:54.710953Z", + "shell.execute_reply": "2026-10-27T13:40:54.710529Z" } }, "outputs": [ @@ -589,7 +590,7 @@ }, { "cell_type": "markdown", - "id": "310a6949", + "id": "7d59b3f0", "metadata": {}, "source": [ "Three mines, each capped at the same share of the total: below one third, the three caps add to less\n", @@ -606,13 +607,13 @@ { "cell_type": "code", "execution_count": 12, - "id": "8f845567", + "id": "a89de08f", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.599151Z", - "iopub.status.busy": "2026-09-06T10:42:08.598979Z", - "iopub.status.idle": "2026-09-06T10:42:08.603119Z", - "shell.execute_reply": "2026-09-06T10:42:08.602664Z" + "iopub.execute_input": "2026-10-27T13:40:54.712939Z", + "iopub.status.busy": "2026-10-27T13:40:54.712763Z", + "iopub.status.idle": "2026-10-27T13:40:54.717768Z", + "shell.execute_reply": "2026-10-27T13:40:54.716946Z" } }, "outputs": [ @@ -635,7 +636,7 @@ }, { "cell_type": "markdown", - "id": "7e169a0d", + "id": "3ef17a2e", "metadata": {}, "source": [ "Same number. Now raise the requirement at one plant by a single kilotonne and solve both versions." @@ -644,13 +645,13 @@ { "cell_type": "code", "execution_count": 13, - "id": "77374a72", + "id": "1cdd097e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.604987Z", - "iopub.status.busy": "2026-09-06T10:42:08.604822Z", - "iopub.status.idle": "2026-09-06T10:42:08.610254Z", - "shell.execute_reply": "2026-09-06T10:42:08.609777Z" + "iopub.execute_input": "2026-10-27T13:40:54.720148Z", + "iopub.status.busy": "2026-10-27T13:40:54.719973Z", + "iopub.status.idle": "2026-10-27T13:40:54.726830Z", + "shell.execute_reply": "2026-10-27T13:40:54.726353Z" } }, "outputs": [ @@ -686,7 +687,7 @@ }, { "cell_type": "markdown", - "id": "025d4a03", + "id": "0569bf21", "metadata": {}, "source": [ "One kilotonne later they disagree, and the one without the rows refines more than the refinery can\n", @@ -706,13 +707,13 @@ { "cell_type": "code", "execution_count": 14, - "id": "0ab35984", + "id": "3f408c08", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.612146Z", - "iopub.status.busy": "2026-09-06T10:42:08.611980Z", - "iopub.status.idle": "2026-09-06T10:42:08.623832Z", - "shell.execute_reply": "2026-09-06T10:42:08.623353Z" + "iopub.execute_input": "2026-10-27T13:40:54.728879Z", + "iopub.status.busy": "2026-10-27T13:40:54.728705Z", + "iopub.status.idle": "2026-10-27T13:40:54.741372Z", + "shell.execute_reply": "2026-10-27T13:40:54.740871Z" } }, "outputs": [ @@ -756,7 +757,7 @@ }, { "cell_type": "markdown", - "id": "8363cfc8", + "id": "7d3f2df8", "metadata": {}, "source": [ "## The agreement assertion\n", @@ -774,13 +775,13 @@ { "cell_type": "code", "execution_count": 15, - "id": "8f4f98ff", + "id": "98184102", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T10:42:08.625813Z", - "iopub.status.busy": "2026-09-06T10:42:08.625649Z", - "iopub.status.idle": "2026-09-06T10:42:08.630947Z", - "shell.execute_reply": "2026-09-06T10:42:08.630478Z" + "iopub.execute_input": "2026-10-27T13:40:54.743598Z", + "iopub.status.busy": "2026-10-27T13:40:54.743413Z", + "iopub.status.idle": "2026-10-27T13:40:54.749628Z", + "shell.execute_reply": "2026-10-27T13:40:54.749106Z" } }, "outputs": [ @@ -823,7 +824,7 @@ }, { "cell_type": "markdown", - "id": "8a7c0e34", + "id": "60a7c756", "metadata": {}, "source": [ "---\n", diff --git a/notebooks/14_probability_and_stats/distributions_and_clt.ipynb b/notebooks/14_probability_and_stats/distributions_and_clt.ipynb index 3ca25ef..de03ddc 100644 --- a/notebooks/14_probability_and_stats/distributions_and_clt.ipynb +++ b/notebooks/14_probability_and_stats/distributions_and_clt.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "00f6b8f4", + "id": "fbb57cd6", "metadata": {}, "source": [ "# Distributions as formulas, and the theorem that makes the mean trustworthy\n", @@ -19,7 +19,7 @@ }, { "cell_type": "markdown", - "id": "77591149", + "id": "b439e4aa", "metadata": {}, "source": [ "## Setup: where the package lives\n", @@ -32,13 +32,13 @@ { "cell_type": "code", "execution_count": 1, - "id": "44b8ae7d", + "id": "6321b099", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:32.633734Z", - "iopub.status.busy": "2026-09-06T03:27:32.633532Z", - "iopub.status.idle": "2026-09-06T03:27:32.647940Z", - "shell.execute_reply": "2026-09-06T03:27:32.647112Z" + "iopub.execute_input": "2026-10-27T13:41:06.052951Z", + "iopub.status.busy": "2026-10-27T13:41:06.052491Z", + "iopub.status.idle": "2026-10-27T13:41:06.069451Z", + "shell.execute_reply": "2026-10-27T13:41:06.068838Z" } }, "outputs": [ @@ -54,6 +54,7 @@ "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", @@ -63,7 +64,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/14_probability_and_stats\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -79,7 +80,7 @@ }, { "cell_type": "markdown", - "id": "6c1505f6", + "id": "c2b92f09", "metadata": {}, "source": [ "## Set the seed, and print it\n", @@ -91,13 +92,13 @@ { "cell_type": "code", "execution_count": 2, - "id": "1f280b1e", + "id": "a9a48498", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:32.650901Z", - "iopub.status.busy": "2026-09-06T03:27:32.650687Z", - "iopub.status.idle": "2026-09-06T03:27:34.810237Z", - "shell.execute_reply": "2026-09-06T03:27:34.809734Z" + "iopub.execute_input": "2026-10-27T13:41:06.072444Z", + "iopub.status.busy": "2026-10-27T13:41:06.072162Z", + "iopub.status.idle": "2026-10-27T13:41:08.386438Z", + "shell.execute_reply": "2026-10-27T13:41:08.385948Z" } }, "outputs": [ @@ -124,7 +125,7 @@ }, { "cell_type": "markdown", - "id": "8d72bdf7", + "id": "04961d5b", "metadata": {}, "source": [ "## Binomial: successes in a fixed number of trials\n", @@ -139,13 +140,13 @@ { "cell_type": "code", "execution_count": 3, - "id": "18fe2b12", + "id": "b7801fcc", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:34.812406Z", - "iopub.status.busy": "2026-09-06T03:27:34.812173Z", - "iopub.status.idle": "2026-09-06T03:27:34.981802Z", - "shell.execute_reply": "2026-09-06T03:27:34.981264Z" + "iopub.execute_input": "2026-10-27T13:41:08.388956Z", + "iopub.status.busy": "2026-10-27T13:41:08.388716Z", + "iopub.status.idle": "2026-10-27T13:41:08.556218Z", + "shell.execute_reply": "2026-10-27T13:41:08.555733Z" } }, "outputs": [ @@ -167,6 +168,13 @@ }, "metadata": {}, "output_type": "display_data" + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Figure: a histogram of the 10,000 binomial draws, mound-shaped from 10 to 44, peaking near 25.0, with a vertical line at the sample mean.\n" + ] } ], "source": [ @@ -180,12 +188,14 @@ "print(f\"sample mean {sample.mean():.3f} n p = {N_BINOM * P_BINOM} sample sd {sample.std(ddof=1):.3f} \"\n", " f\"sqrt(n p (1-p)) = {math.sqrt(N_BINOM * P_BINOM * (1 - P_BINOM)):.3f}\")\n", "plt.hist(sample, bins=range(sample.min(), sample.max() + 2), color=\"lightblue\", edgecolor=\"white\")\n", - "plt.axvline(sample.mean(), color=\"red\"); plt.title(\"Binomial(100, 0.25): 10,000 draws\"); plt.show()" + "plt.axvline(sample.mean(), color=\"red\"); plt.title(\"Binomial(100, 0.25): 10,000 draws\"); plt.show()\n", + "print(f\"Figure: a histogram of the {N_SAMPLE:,} binomial draws, mound-shaped from {sample.min()} to \"\n", + " f\"{sample.max()}, peaking near {sample.mean():.1f}, with a vertical line at the sample mean.\")" ] }, { "cell_type": "markdown", - "id": "5cd4cce0", + "id": "5899a9ae", "metadata": {}, "source": [ "## Negative binomial: failures before the $r$-th success\n", @@ -202,13 +212,13 @@ { "cell_type": "code", "execution_count": 4, - "id": "070686bf", + "id": "ecca25af", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:34.983888Z", - "iopub.status.busy": "2026-09-06T03:27:34.983701Z", - "iopub.status.idle": "2026-09-06T03:27:34.988716Z", - "shell.execute_reply": "2026-09-06T03:27:34.988126Z" + "iopub.execute_input": "2026-10-27T13:41:08.558302Z", + "iopub.status.busy": "2026-10-27T13:41:08.558126Z", + "iopub.status.idle": "2026-10-27T13:41:08.563028Z", + "shell.execute_reply": "2026-10-27T13:41:08.562561Z" } }, "outputs": [ @@ -240,7 +250,7 @@ }, { "cell_type": "markdown", - "id": "bb308888", + "id": "93b65722", "metadata": {}, "source": [ "The pieces fail in both directions. The binomial coefficient is an exact integer with more digits\n", @@ -255,13 +265,13 @@ { "cell_type": "code", "execution_count": 5, - "id": "0a36308c", + "id": "f467f296", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:34.991150Z", - "iopub.status.busy": "2026-09-06T03:27:34.990961Z", - "iopub.status.idle": "2026-09-06T03:27:35.000103Z", - "shell.execute_reply": "2026-09-06T03:27:34.999314Z" + "iopub.execute_input": "2026-10-27T13:41:08.565091Z", + "iopub.status.busy": "2026-10-27T13:41:08.564921Z", + "iopub.status.idle": "2026-10-27T13:41:08.572580Z", + "shell.execute_reply": "2026-10-27T13:41:08.572105Z" } }, "outputs": [ @@ -289,7 +299,7 @@ }, { "cell_type": "markdown", - "id": "9c34889e", + "id": "63a95cdb", "metadata": {}, "source": [ "## Geometric: failures before the first success\n", @@ -304,13 +314,13 @@ { "cell_type": "code", "execution_count": 6, - "id": "b68b8e69", + "id": "571f2c3e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:35.002256Z", - "iopub.status.busy": "2026-09-06T03:27:35.002080Z", - "iopub.status.idle": "2026-09-06T03:27:35.007899Z", - "shell.execute_reply": "2026-09-06T03:27:35.007433Z" + "iopub.execute_input": "2026-10-27T13:41:08.575196Z", + "iopub.status.busy": "2026-10-27T13:41:08.575018Z", + "iopub.status.idle": "2026-10-27T13:41:08.580890Z", + "shell.execute_reply": "2026-10-27T13:41:08.580253Z" } }, "outputs": [ @@ -337,7 +347,7 @@ }, { "cell_type": "markdown", - "id": "f10823a0", + "id": "a123ef43", "metadata": {}, "source": [ "## Poisson: events in a fixed interval\n", @@ -352,13 +362,13 @@ { "cell_type": "code", "execution_count": 7, - "id": "10fb3c37", + "id": "efddb2b6", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:35.010089Z", - "iopub.status.busy": "2026-09-06T03:27:35.009873Z", - "iopub.status.idle": "2026-09-06T03:27:35.016599Z", - "shell.execute_reply": "2026-09-06T03:27:35.015820Z" + "iopub.execute_input": "2026-10-27T13:41:08.583668Z", + "iopub.status.busy": "2026-10-27T13:41:08.583489Z", + "iopub.status.idle": "2026-10-27T13:41:08.590846Z", + "shell.execute_reply": "2026-10-27T13:41:08.590159Z" } }, "outputs": [ @@ -385,7 +395,7 @@ }, { "cell_type": "markdown", - "id": "0daefbaa", + "id": "4c7af6b7", "metadata": {}, "source": [ "## Exponential: the wait for the next event\n", @@ -398,13 +408,13 @@ { "cell_type": "code", "execution_count": 8, - "id": "3cbe8305", + "id": "ed132e2c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:35.019036Z", - "iopub.status.busy": "2026-09-06T03:27:35.018773Z", - "iopub.status.idle": "2026-09-06T03:27:35.025739Z", - "shell.execute_reply": "2026-09-06T03:27:35.025011Z" + "iopub.execute_input": "2026-10-27T13:41:08.593176Z", + "iopub.status.busy": "2026-10-27T13:41:08.592998Z", + "iopub.status.idle": "2026-10-27T13:41:08.598480Z", + "shell.execute_reply": "2026-10-27T13:41:08.598006Z" } }, "outputs": [ @@ -413,7 +423,13 @@ "output_type": "stream", "text": [ "P(X <= 0.2) 0.981684 scipy 0.981684 (R printed 0.982)\n", - "95th percentile 0.149787 scipy 0.149787\n", + "95th percentile 0.149787 scipy 0.149787\n" + ] + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ "sample mean 0.0499 1/lambda = 0.05\n" ] } @@ -431,7 +447,7 @@ }, { "cell_type": "markdown", - "id": "19f00f7c", + "id": "9b3e8059", "metadata": {}, "source": [ "## Gamma with an integer shape: the wait for the $k$-th event\n", @@ -446,13 +462,13 @@ { "cell_type": "code", "execution_count": 9, - "id": "5e52eeb7", + "id": "ebdd4a52", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:35.028160Z", - "iopub.status.busy": "2026-09-06T03:27:35.027911Z", - "iopub.status.idle": "2026-09-06T03:27:35.033272Z", - "shell.execute_reply": "2026-09-06T03:27:35.032680Z" + "iopub.execute_input": "2026-10-27T13:41:08.600889Z", + "iopub.status.busy": "2026-10-27T13:41:08.600602Z", + "iopub.status.idle": "2026-10-27T13:41:08.606160Z", + "shell.execute_reply": "2026-10-27T13:41:08.605681Z" } }, "outputs": [ @@ -477,7 +493,7 @@ }, { "cell_type": "markdown", - "id": "9cacd144", + "id": "9a99ddeb", "metadata": {}, "source": [ "## Normal\n", @@ -491,13 +507,13 @@ { "cell_type": "code", "execution_count": 10, - "id": "8083aa39", + "id": "048ad684", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:35.035629Z", - "iopub.status.busy": "2026-09-06T03:27:35.035456Z", - "iopub.status.idle": "2026-09-06T03:27:35.040977Z", - "shell.execute_reply": "2026-09-06T03:27:35.040396Z" + "iopub.execute_input": "2026-10-27T13:41:08.608566Z", + "iopub.status.busy": "2026-10-27T13:41:08.608289Z", + "iopub.status.idle": "2026-10-27T13:41:08.614651Z", + "shell.execute_reply": "2026-10-27T13:41:08.614046Z" } }, "outputs": [ @@ -521,7 +537,7 @@ }, { "cell_type": "markdown", - "id": "c0eb1486", + "id": "9a1eaf4a", "metadata": {}, "source": [ "## Log-normal\n", @@ -533,13 +549,13 @@ { "cell_type": "code", "execution_count": 11, - "id": "a5771e0b", + "id": "687a23b7", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:35.043290Z", - "iopub.status.busy": "2026-09-06T03:27:35.043081Z", - "iopub.status.idle": "2026-09-06T03:27:35.049400Z", - "shell.execute_reply": "2026-09-06T03:27:35.048876Z" + "iopub.execute_input": "2026-10-27T13:41:08.617070Z", + "iopub.status.busy": "2026-10-27T13:41:08.616847Z", + "iopub.status.idle": "2026-10-27T13:41:08.622330Z", + "shell.execute_reply": "2026-10-27T13:41:08.621805Z" } }, "outputs": [ @@ -563,7 +579,7 @@ }, { "cell_type": "markdown", - "id": "7cbeb1f5", + "id": "641308b4", "metadata": {}, "source": [ "## Three the formulas do not cover\n", @@ -578,13 +594,13 @@ { "cell_type": "code", "execution_count": 12, - "id": "c88406fe", + "id": "68d7bc73", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:35.052234Z", - "iopub.status.busy": "2026-09-06T03:27:35.051962Z", - "iopub.status.idle": "2026-09-06T03:27:35.059730Z", - "shell.execute_reply": "2026-09-06T03:27:35.059062Z" + "iopub.execute_input": "2026-10-27T13:41:08.625088Z", + "iopub.status.busy": "2026-10-27T13:41:08.624835Z", + "iopub.status.idle": "2026-10-27T13:41:08.633920Z", + "shell.execute_reply": "2026-10-27T13:41:08.633424Z" } }, "outputs": [ @@ -609,7 +625,7 @@ }, { "cell_type": "markdown", - "id": "4bb043b5", + "id": "63888a39", "metadata": {}, "source": [ "## The empirical CDF against the formula\n", @@ -621,13 +637,13 @@ { "cell_type": "code", "execution_count": 13, - "id": "afb33459", + "id": "92da516d", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:35.061947Z", - "iopub.status.busy": "2026-09-06T03:27:35.061776Z", - "iopub.status.idle": "2026-09-06T03:27:35.172425Z", - "shell.execute_reply": "2026-09-06T03:27:35.171916Z" + "iopub.execute_input": "2026-10-27T13:41:08.636288Z", + "iopub.status.busy": "2026-10-27T13:41:08.636059Z", + "iopub.status.idle": "2026-10-27T13:41:08.749315Z", + "shell.execute_reply": "2026-10-27T13:41:08.748742Z" } }, "outputs": [ @@ -645,6 +661,7 @@ "name": "stdout", "output_type": "stream", "text": [ + "Figure: the empirical CDF of the 10,000 draws (dots) lies on the formula's S-shaped curve (solid line), rising from 0 near 20 to 1 near 80 and passing 0.5 at 50.\n", "largest gap between the two: 0.0057\n" ] } @@ -656,12 +673,14 @@ "plt.plot(sample, ecdf, \".\", ms=2, label=\"empirical\")\n", "plt.plot(grid, [0.5 * (1 + math.erf((g - 50) / (10 * math.sqrt(2)))) for g in grid], \"k-\", lw=1, label=\"formula\")\n", "plt.legend(); plt.title(\"Normal(50, 10): empirical CDF of 10,000 draws\"); plt.show()\n", + "print(f\"Figure: the empirical CDF of the {N_SAMPLE:,} draws (dots) lies on the formula's S-shaped \"\n", + " f\"curve (solid line), rising from 0 near 20 to 1 near 80 and passing 0.5 at 50.\")\n", "print(f\"largest gap between the two: {np.max(np.abs(ecdf - stats.norm.cdf(sample, 50, 10))):.4f}\")" ] }, { "cell_type": "markdown", - "id": "12114615", + "id": "e92b2f33", "metadata": {}, "source": [ "---\n", @@ -681,13 +700,13 @@ { "cell_type": "code", "execution_count": 14, - "id": "b696ff21", + "id": "abbbea5c", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:35.174613Z", - "iopub.status.busy": "2026-09-06T03:27:35.174429Z", - "iopub.status.idle": "2026-09-06T03:27:35.191111Z", - "shell.execute_reply": "2026-09-06T03:27:35.190567Z" + "iopub.execute_input": "2026-10-27T13:41:08.751326Z", + "iopub.status.busy": "2026-10-27T13:41:08.751150Z", + "iopub.status.idle": "2026-10-27T13:41:08.765452Z", + "shell.execute_reply": "2026-10-27T13:41:08.764876Z" } }, "outputs": [ @@ -727,7 +746,7 @@ }, { "cell_type": "markdown", - "id": "ef234567", + "id": "21ec9d02", "metadata": {}, "source": [ "Ten times the sample bought how much of the spread — and why $\\sqrt{n}$ rather than $n$? Now look at\n", @@ -737,13 +756,13 @@ { "cell_type": "code", "execution_count": 15, - "id": "a311c72b", + "id": "3eb0b770", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:35.193742Z", - "iopub.status.busy": "2026-09-06T03:27:35.193535Z", - "iopub.status.idle": "2026-09-06T03:27:35.674214Z", - "shell.execute_reply": "2026-09-06T03:27:35.673601Z" + "iopub.execute_input": "2026-10-27T13:41:08.767707Z", + "iopub.status.busy": "2026-10-27T13:41:08.767531Z", + "iopub.status.idle": "2026-10-27T13:41:09.186087Z", + "shell.execute_reply": "2026-10-27T13:41:09.185398Z" } }, "outputs": [ @@ -756,6 +775,13 @@ }, "metadata": {}, "output_type": "display_data" + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Figure: four histograms. The exponential population is skewed hard to the right; the means of samples of 30, 100 and 1000 are mound-shaped around 4, with spreads (standard deviation) 0.788, 0.417 and 0.133.\n" + ] } ], "source": [ @@ -763,12 +789,15 @@ "axes[0].hist(population, bins=40, color=\"lightblue\"); axes[0].set_title(\"population: exponential\")\n", "for ax, size in zip(axes[1:], SIZES):\n", " ax.hist(means[size], bins=30, color=\"lightgreen\"); ax.set_title(f\"means of samples of {size}\")\n", - "plt.tight_layout(); plt.show()" + "plt.tight_layout(); plt.show()\n", + "print(f\"Figure: four histograms. The exponential population is skewed hard to the right; the \"\n", + " f\"means of samples of {SIZES[0]}, {SIZES[1]} and {SIZES[2]} are mound-shaped around 4, with spreads \"\n", + " f\"(standard deviation) {means[SIZES[0]].std():.3f}, {means[SIZES[1]].std():.3f} and {means[SIZES[2]].std():.3f}.\")" ] }, { "cell_type": "markdown", - "id": "dc31f8bf", + "id": "f86fdac8", "metadata": {}, "source": [ "The population is skewed; the averages of thirty are already nearly symmetric; the averages of a\n", @@ -787,13 +816,13 @@ { "cell_type": "code", "execution_count": 16, - "id": "ba934a37", + "id": "dad4041b", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:35.678162Z", - "iopub.status.busy": "2026-09-06T03:27:35.677666Z", - "iopub.status.idle": "2026-09-06T03:27:35.690057Z", - "shell.execute_reply": "2026-09-06T03:27:35.689545Z" + "iopub.execute_input": "2026-10-27T13:41:09.188754Z", + "iopub.status.busy": "2026-10-27T13:41:09.188545Z", + "iopub.status.idle": "2026-10-27T13:41:09.196652Z", + "shell.execute_reply": "2026-10-27T13:41:09.196160Z" } }, "outputs": [ @@ -817,7 +846,7 @@ }, { "cell_type": "markdown", - "id": "7fccbd90", + "id": "b21409db", "metadata": {}, "source": [ "## The agreement assertion\n", @@ -832,13 +861,13 @@ { "cell_type": "code", "execution_count": 17, - "id": "11a4e304", + "id": "43c394e5", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:35.692793Z", - "iopub.status.busy": "2026-09-06T03:27:35.692318Z", - "iopub.status.idle": "2026-09-06T03:27:35.723471Z", - "shell.execute_reply": "2026-09-06T03:27:35.722848Z" + "iopub.execute_input": "2026-10-27T13:41:09.198916Z", + "iopub.status.busy": "2026-10-27T13:41:09.198753Z", + "iopub.status.idle": "2026-10-27T13:41:09.215444Z", + "shell.execute_reply": "2026-10-27T13:41:09.214864Z" } }, "outputs": [ @@ -891,7 +920,7 @@ }, { "cell_type": "markdown", - "id": "408f6410", + "id": "0752b53e", "metadata": {}, "source": [ "---\n", diff --git a/notebooks/14_probability_and_stats/inference_and_regression.ipynb b/notebooks/14_probability_and_stats/inference_and_regression.ipynb index fcb8467..c6f1599 100644 --- a/notebooks/14_probability_and_stats/inference_and_regression.ipynb +++ b/notebooks/14_probability_and_stats/inference_and_regression.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "7bc08769", + "id": "305564aa", "metadata": {}, "source": [ "# Tests and regressions, line by line\n", @@ -19,7 +19,7 @@ }, { "cell_type": "markdown", - "id": "44a6db7a", + "id": "5ae2fd28", "metadata": {}, "source": [ "## Setup: where the package lives\n", @@ -32,13 +32,13 @@ { "cell_type": "code", "execution_count": 1, - "id": "734a89a3", + "id": "c5a97dbb", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:39.762313Z", - "iopub.status.busy": "2026-09-06T03:27:39.761999Z", - "iopub.status.idle": "2026-09-06T03:27:39.783420Z", - "shell.execute_reply": "2026-09-06T03:27:39.782559Z" + "iopub.execute_input": "2026-10-27T13:41:19.930408Z", + "iopub.status.busy": "2026-10-27T13:41:19.930239Z", + "iopub.status.idle": "2026-10-27T13:41:19.942968Z", + "shell.execute_reply": "2026-10-27T13:41:19.942499Z" } }, "outputs": [ @@ -54,6 +54,7 @@ "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", @@ -63,7 +64,7 @@ "\n", "if ON_COLAB:\n", " if not os.path.isdir(\"/content/teaching-code\"):\n", - " subprocess.run([\"git\", \"clone\", \"--quiet\", REPO_URL, \"/content/teaching-code\"], check=True)\n", + " subprocess.run([\"git\", \"clone\", \"--quiet\", \"--depth\", \"1\", \"--branch\", REF, REPO_URL, \"/content/teaching-code\"], check=True)\n", " os.chdir(\"/content/teaching-code/notebooks/14_probability_and_stats\")\n", " subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"--quiet\", \"gurobipy>=11,<14\"], check=True)\n", "\n", @@ -79,7 +80,7 @@ }, { "cell_type": "markdown", - "id": "417883ca", + "id": "94ce9426", "metadata": {}, "source": [ "## The scores are a table\n", @@ -93,13 +94,13 @@ { "cell_type": "code", "execution_count": 2, - "id": "c5e73761", + "id": "cff68bd5", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:39.787204Z", - "iopub.status.busy": "2026-09-06T03:27:39.786771Z", - "iopub.status.idle": "2026-09-06T03:27:42.244362Z", - "shell.execute_reply": "2026-09-06T03:27:42.243477Z" + "iopub.execute_input": "2026-10-27T13:41:19.944974Z", + "iopub.status.busy": "2026-10-27T13:41:19.944805Z", + "iopub.status.idle": "2026-10-27T13:41:21.536465Z", + "shell.execute_reply": "2026-10-27T13:41:21.535988Z" } }, "outputs": [ @@ -137,7 +138,7 @@ }, { "cell_type": "markdown", - "id": "815634d6", + "id": "51dc46dd", "metadata": {}, "source": [ "## One mean against a claimed value\n", @@ -154,13 +155,13 @@ { "cell_type": "code", "execution_count": 3, - "id": "50b4d087", + "id": "5deaba49", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:42.248559Z", - "iopub.status.busy": "2026-09-06T03:27:42.248026Z", - "iopub.status.idle": "2026-09-06T03:27:42.258643Z", - "shell.execute_reply": "2026-09-06T03:27:42.257929Z" + "iopub.execute_input": "2026-10-27T13:41:21.538754Z", + "iopub.status.busy": "2026-10-27T13:41:21.538537Z", + "iopub.status.idle": "2026-10-27T13:41:21.545088Z", + "shell.execute_reply": "2026-10-27T13:41:21.544126Z" } }, "outputs": [ @@ -191,7 +192,7 @@ }, { "cell_type": "markdown", - "id": "b4db2978", + "id": "d1a6e610", "metadata": {}, "source": [ "The same statistic, one-sided. Same claim — the average is 70 — but now the alternative is that it\n", @@ -202,13 +203,13 @@ { "cell_type": "code", "execution_count": 4, - "id": "da5e36d6", + "id": "29c14e6f", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:42.262777Z", - "iopub.status.busy": "2026-09-06T03:27:42.262176Z", - "iopub.status.idle": "2026-09-06T03:27:42.274380Z", - "shell.execute_reply": "2026-09-06T03:27:42.273150Z" + "iopub.execute_input": "2026-10-27T13:41:21.547131Z", + "iopub.status.busy": "2026-10-27T13:41:21.546925Z", + "iopub.status.idle": "2026-10-27T13:41:21.552250Z", + "shell.execute_reply": "2026-10-27T13:41:21.551794Z" } }, "outputs": [ @@ -232,7 +233,7 @@ }, { "cell_type": "markdown", - "id": "5d3e37da", + "id": "f40eb4c9", "metadata": {}, "source": [ "## Two means\n", @@ -246,13 +247,13 @@ { "cell_type": "code", "execution_count": 5, - "id": "63b38087", + "id": "8414d548", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:42.278273Z", - "iopub.status.busy": "2026-09-06T03:27:42.277944Z", - "iopub.status.idle": "2026-09-06T03:27:42.295487Z", - "shell.execute_reply": "2026-09-06T03:27:42.294155Z" + "iopub.execute_input": "2026-10-27T13:41:21.554284Z", + "iopub.status.busy": "2026-10-27T13:41:21.554082Z", + "iopub.status.idle": "2026-10-27T13:41:21.564655Z", + "shell.execute_reply": "2026-10-27T13:41:21.564198Z" } }, "outputs": [ @@ -291,7 +292,7 @@ }, { "cell_type": "markdown", - "id": "29ab8ca3", + "id": "04885cce", "metadata": {}, "source": [ "## One variance\n", @@ -304,13 +305,13 @@ { "cell_type": "code", "execution_count": 6, - "id": "8a68ed2d", + "id": "0c949e0e", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:42.299524Z", - "iopub.status.busy": "2026-09-06T03:27:42.298995Z", - "iopub.status.idle": "2026-09-06T03:27:42.311467Z", - "shell.execute_reply": "2026-09-06T03:27:42.310411Z" + "iopub.execute_input": "2026-10-27T13:41:21.566708Z", + "iopub.status.busy": "2026-10-27T13:41:21.566539Z", + "iopub.status.idle": "2026-10-27T13:41:21.571892Z", + "shell.execute_reply": "2026-10-27T13:41:21.571111Z" } }, "outputs": [ @@ -334,7 +335,7 @@ }, { "cell_type": "markdown", - "id": "ca6e1a1a", + "id": "65a0a20d", "metadata": {}, "source": [ "## Two variances\n", @@ -347,13 +348,13 @@ { "cell_type": "code", "execution_count": 7, - "id": "63dce70b", + "id": "a17e58cf", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:42.315850Z", - "iopub.status.busy": "2026-09-06T03:27:42.315430Z", - "iopub.status.idle": "2026-09-06T03:27:42.324324Z", - "shell.execute_reply": "2026-09-06T03:27:42.323094Z" + "iopub.execute_input": "2026-10-27T13:41:21.574054Z", + "iopub.status.busy": "2026-10-27T13:41:21.573859Z", + "iopub.status.idle": "2026-10-27T13:41:21.578915Z", + "shell.execute_reply": "2026-10-27T13:41:21.578401Z" } }, "outputs": [ @@ -373,7 +374,7 @@ }, { "cell_type": "markdown", - "id": "6e539f5d", + "id": "bc1fb1c6", "metadata": {}, "source": [ "## Chi-squared: does a distribution fit?\n", @@ -394,13 +395,13 @@ { "cell_type": "code", "execution_count": 8, - "id": "3a47449a", + "id": "8aea00ce", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:42.328294Z", - "iopub.status.busy": "2026-09-06T03:27:42.327959Z", - "iopub.status.idle": "2026-09-06T03:27:42.342822Z", - "shell.execute_reply": "2026-09-06T03:27:42.341746Z" + "iopub.execute_input": "2026-10-27T13:41:21.581168Z", + "iopub.status.busy": "2026-10-27T13:41:21.580987Z", + "iopub.status.idle": "2026-10-27T13:41:21.586891Z", + "shell.execute_reply": "2026-10-27T13:41:21.586435Z" } }, "outputs": [ @@ -432,7 +433,7 @@ }, { "cell_type": "markdown", - "id": "67c3afb8", + "id": "f7ceee0f", "metadata": {}, "source": [ "## Chi-squared: are two factors independent?\n", @@ -444,13 +445,13 @@ { "cell_type": "code", "execution_count": 9, - "id": "01d50cc1", + "id": "848b64ec", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:42.347440Z", - "iopub.status.busy": "2026-09-06T03:27:42.347013Z", - "iopub.status.idle": "2026-09-06T03:27:42.358087Z", - "shell.execute_reply": "2026-09-06T03:27:42.357000Z" + "iopub.execute_input": "2026-10-27T13:41:21.588957Z", + "iopub.status.busy": "2026-10-27T13:41:21.588710Z", + "iopub.status.idle": "2026-10-27T13:41:21.594163Z", + "shell.execute_reply": "2026-10-27T13:41:21.593680Z" } }, "outputs": [ @@ -474,7 +475,7 @@ }, { "cell_type": "markdown", - "id": "53959aa9", + "id": "7d451be5", "metadata": {}, "source": [ "---\n", @@ -491,13 +492,13 @@ { "cell_type": "code", "execution_count": 10, - "id": "47fb11df", + "id": "918cb4f5", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:42.362156Z", - "iopub.status.busy": "2026-09-06T03:27:42.361746Z", - "iopub.status.idle": "2026-09-06T03:27:42.395712Z", - "shell.execute_reply": "2026-09-06T03:27:42.394653Z" + "iopub.execute_input": "2026-10-27T13:41:21.596269Z", + "iopub.status.busy": "2026-10-27T13:41:21.596075Z", + "iopub.status.idle": "2026-10-27T13:41:21.612492Z", + "shell.execute_reply": "2026-10-27T13:41:21.611920Z" } }, "outputs": [ @@ -541,7 +542,7 @@ }, { "cell_type": "markdown", - "id": "0eff1c64", + "id": "a1a6e0a9", "metadata": {}, "source": [ "R printed, for this same regression: intercept 29.599855 with standard error 1.229720, slope\n", @@ -558,13 +559,13 @@ { "cell_type": "code", "execution_count": 11, - "id": "6db1dce3", + "id": "a2698552", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:42.401350Z", - "iopub.status.busy": "2026-09-06T03:27:42.400867Z", - "iopub.status.idle": "2026-09-06T03:27:42.415060Z", - "shell.execute_reply": "2026-09-06T03:27:42.413796Z" + "iopub.execute_input": "2026-10-27T13:41:21.614641Z", + "iopub.status.busy": "2026-10-27T13:41:21.614470Z", + "iopub.status.idle": "2026-10-27T13:41:21.620709Z", + "shell.execute_reply": "2026-10-27T13:41:21.620258Z" } }, "outputs": [ @@ -605,7 +606,7 @@ }, { "cell_type": "markdown", - "id": "c78bcdaf", + "id": "731c9096", "metadata": {}, "source": [ "Displacement's coefficient collapsed toward zero and lost its significance the moment weight and\n", @@ -625,13 +626,13 @@ { "cell_type": "code", "execution_count": 12, - "id": "782831a3", + "id": "e86e9506", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:42.420320Z", - "iopub.status.busy": "2026-09-06T03:27:42.419837Z", - "iopub.status.idle": "2026-09-06T03:27:42.451001Z", - "shell.execute_reply": "2026-09-06T03:27:42.450039Z" + "iopub.execute_input": "2026-10-27T13:41:21.622713Z", + "iopub.status.busy": "2026-10-27T13:41:21.622543Z", + "iopub.status.idle": "2026-10-27T13:41:21.629772Z", + "shell.execute_reply": "2026-10-27T13:41:21.629297Z" } }, "outputs": [ @@ -668,7 +669,7 @@ }, { "cell_type": "markdown", - "id": "ae830de5", + "id": "71c758b8", "metadata": {}, "source": [ "---\n", @@ -684,13 +685,13 @@ { "cell_type": "code", "execution_count": 13, - "id": "3d84f6c8", + "id": "8226a85d", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:42.454955Z", - "iopub.status.busy": "2026-09-06T03:27:42.454571Z", - "iopub.status.idle": "2026-09-06T03:27:42.473023Z", - "shell.execute_reply": "2026-09-06T03:27:42.471905Z" + "iopub.execute_input": "2026-10-27T13:41:21.631677Z", + "iopub.status.busy": "2026-10-27T13:41:21.631517Z", + "iopub.status.idle": "2026-10-27T13:41:21.639466Z", + "shell.execute_reply": "2026-10-27T13:41:21.639028Z" } }, "outputs": [ @@ -732,7 +733,7 @@ }, { "cell_type": "markdown", - "id": "8a2dffc2", + "id": "b8571a8f", "metadata": {}, "source": [ "## The agreement assertion\n", @@ -745,13 +746,13 @@ { "cell_type": "code", "execution_count": 14, - "id": "aa67c58e", + "id": "814f41da", "metadata": { "execution": { - "iopub.execute_input": "2026-09-06T03:27:42.477940Z", - "iopub.status.busy": "2026-09-06T03:27:42.477479Z", - "iopub.status.idle": "2026-09-06T03:27:42.495572Z", - "shell.execute_reply": "2026-09-06T03:27:42.494631Z" + "iopub.execute_input": "2026-10-27T13:41:21.641733Z", + "iopub.status.busy": "2026-10-27T13:41:21.641563Z", + "iopub.status.idle": "2026-10-27T13:41:21.648888Z", + "shell.execute_reply": "2026-10-27T13:41:21.648401Z" } }, "outputs": [ @@ -806,7 +807,7 @@ }, { "cell_type": "markdown", - "id": "be6fdad8", + "id": "cb89ca86", "metadata": {}, "source": [ "---\n", diff --git a/pyproject.toml b/pyproject.toml index ee4a258..46c48f7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -34,6 +34,9 @@ dev = [ # because ruff adds rules between minors, and a lint that goes red on an # unrelated push gets switched off. "ruff>=0.15,<0.16", + # tests/test_dependencies.py reads this file. tomllib is standard library from 3.11; on + # 3.10 the backport is declared rather than skipped, so the guard always runs. + "tomli>=2,<3; python_version < '3.11'", ] # Only `12_energy_systems_pypsa` and the PyPSA half of tests/test_energy.py need # this. It is an extra rather than a dependency because PyPSA 1.3 requires diff --git a/src/orteach/assignment.py b/src/orteach/assignment.py index d567226..712d374 100644 --- a/src/orteach/assignment.py +++ b/src/orteach/assignment.py @@ -17,7 +17,6 @@ from __future__ import annotations import csv -import os from dataclasses import dataclass import gurobipy as gp @@ -25,12 +24,12 @@ from . import tolerance from .transportation import Instance -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") +from . import paths -def load_costs(path=os.path.join(DATA_DIR, "assignment_4x4.csv")) -> dict: +def load_costs(path=None) -> dict: """(machine, job) -> cost, keys as strings so they match the CSV verbatim.""" + path = path or paths.table("assignment_4x4.csv") with open(path, encoding="utf-8") as f: return {(r["machine"], r["job"]): float(r["cost"]) for r in csv.DictReader(f)} diff --git a/src/orteach/capital_budgeting.py b/src/orteach/capital_budgeting.py index a466ce4..c77202a 100644 --- a/src/orteach/capital_budgeting.py +++ b/src/orteach/capital_budgeting.py @@ -25,25 +25,24 @@ from __future__ import annotations import csv -import os from dataclasses import dataclass, field import gurobipy as gp from . import tolerance -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") -INVESTMENTS_CSV = os.path.join(DATA_DIR, "staroil_investments.csv") +from . import paths +INVESTMENTS_CSV = "staroil_investments.csv" # resolved by paths.table() when read -def load_investments(path=INVESTMENTS_CSV): +def load_investments(path=None): """Read the investment table as a list of dicts, in file order. Returned to the caller, who passes it into the solvers — the solvers never read the file themselves, so a reader who edits a value in the notebook sees it reach both the hand-built model and the check. """ + path = path or paths.table(INVESTMENTS_CSV) with open(path, encoding="utf-8") as f: return [{"investment": r["investment"], "npv": float(r["npv"]), diff --git a/src/orteach/data.py b/src/orteach/data.py index 61f5e86..f629e5e 100644 --- a/src/orteach/data.py +++ b/src/orteach/data.py @@ -17,9 +17,8 @@ import csv import os -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") -DEMAND_CSV = os.path.join(DATA_DIR, "newsvendor_demand.csv") +from . import paths +DEMAND_CSV = "newsvendor_demand.csv" # resolved by paths.table() when read # The generating parameters, recorded so the table can be rebuilt exactly. # Truncated at zero: demand cannot be negative. @@ -40,9 +39,10 @@ def generate_demand(n=DEMAND_N, mu=DEMAND_MU, sigma=DEMAND_SIGMA, seed=DEMAND_SE return [round(max(rng.normalvariate(mu, sigma), 0.0), 6) for _ in range(n)] -def write_demand(path=DEMAND_CSV): +def write_demand(path=None): """Write the table. The script is the source of truth; the CSV is a build output, and ``tests/test_newsvendor.py::test_the_demand_table_regenerates_exactly`` checks that regenerating reproduces it.""" + path = path or os.path.join(paths.SOURCE_DIR, DEMAND_CSV) # writes the clone's own table rows = generate_demand() os.makedirs(os.path.dirname(path), exist_ok=True) with open(path, "w", newline="", encoding="utf-8") as f: @@ -53,9 +53,10 @@ def write_demand(path=DEMAND_CSV): return path -def load_demand(path=DEMAND_CSV): +def load_demand(path=None): """Read the demand table. Both the notebook and the package call this, and then pass the RESULT into the solvers — the solvers never read the file.""" + path = path or paths.table(DEMAND_CSV) with open(path, encoding="utf-8") as f: return [float(r["demand"]) for r in csv.DictReader(f)] diff --git a/src/orteach/diet.py b/src/orteach/diet.py index 41d08bb..3c9a085 100644 --- a/src/orteach/diet.py +++ b/src/orteach/diet.py @@ -19,15 +19,13 @@ from __future__ import annotations import csv -import os from dataclasses import dataclass import gurobipy as gp from . import tolerance -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") +from . import paths @dataclass @@ -42,9 +40,9 @@ class Instance: def load_diet(stem: str) -> Instance: """``stem`` is ``"macros"`` or ``"vitamins"``: the prefix of the CSV pair.""" - with open(os.path.join(DATA_DIR, "diet_%s_foods.csv" % stem), encoding="utf-8") as f: + with open(paths.table("diet_%s_foods.csv" % stem), encoding="utf-8") as f: frows = list(csv.DictReader(f)) - with open(os.path.join(DATA_DIR, "diet_%s_targets.csv" % stem), encoding="utf-8") as f: + with open(paths.table("diet_%s_targets.csv" % stem), encoding="utf-8") as f: trows = list(csv.DictReader(f)) nutrients = [r["nutrient"] for r in trows] return Instance( diff --git a/src/orteach/duality.py b/src/orteach/duality.py index d740da3..1e0bef4 100644 --- a/src/orteach/duality.py +++ b/src/orteach/duality.py @@ -29,15 +29,13 @@ from __future__ import annotations import csv -import os from dataclasses import dataclass import gurobipy as gp from . import tolerance -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") +from . import paths SENSES = ("<=", ">=", "=") @@ -62,7 +60,7 @@ def row_expr(self, r, x): def load_lp(filename: str, name: str = "") -> LP: - with open(os.path.join(DATA_DIR, filename), encoding="utf-8") as f: + with open(paths.table(filename), encoding="utf-8") as f: rows = list(csv.DictReader(f)) cols = list(rows[0].keys()) variables = cols[1:cols.index("sense")] diff --git a/src/orteach/energy.py b/src/orteach/energy.py index dedbc2f..e81e9a7 100644 --- a/src/orteach/energy.py +++ b/src/orteach/energy.py @@ -31,10 +31,9 @@ from . import tolerance -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") -PROFILES_CSV = os.path.join(DATA_DIR, "energy_day_profiles.csv") -GENERATORS_CSV = os.path.join(DATA_DIR, "energy_generators.csv") +from . import paths +PROFILES_CSV = "energy_day_profiles.csv" # resolved by paths.table() when read +GENERATORS_CSV = "energy_generators.csv" # resolved by paths.table() when read HOURS = np.arange(24) DAYS_PER_YEAR = 365.0 @@ -55,7 +54,8 @@ def day_profiles(peak_hour: int = 19) -> dict: "solar_pu": [round(float(s), 4) for s in solar]} -def write_day_profiles(path: str = PROFILES_CSV) -> None: +def write_day_profiles(path: str | None = None) -> None: + path = path or os.path.join(paths.SOURCE_DIR, PROFILES_CSV) # writes the clone's own table p = day_profiles() with open(path, "w", newline="", encoding="utf-8") as f: w = csv.writer(f) @@ -64,7 +64,8 @@ def write_day_profiles(path: str = PROFILES_CSV) -> None: w.writerow([h, d, s]) -def load_day_profiles(path: str = PROFILES_CSV) -> dict: +def load_day_profiles(path: str | None = None) -> dict: + path = path or paths.table(PROFILES_CSV) with open(path, encoding="utf-8") as f: rows = list(csv.DictReader(f)) return {"hour": [int(r["hour"]) for r in rows], @@ -82,7 +83,8 @@ class Technology: varies: bool # follows the solar profile -def load_generators(path: str = GENERATORS_CSV) -> list: +def load_generators(path: str | None = None) -> list: + path = path or paths.table(GENERATORS_CSV) with open(path, encoding="utf-8") as f: rows = list(csv.DictReader(f)) return [Technology(r["technology"], float(r["p_nom_mw"]), float(r["marginal_cost"]), diff --git a/src/orteach/facility_location.py b/src/orteach/facility_location.py index 9563737..b0622d1 100644 --- a/src/orteach/facility_location.py +++ b/src/orteach/facility_location.py @@ -31,15 +31,13 @@ from __future__ import annotations import csv -import os from dataclasses import dataclass, field import gurobipy as gp from . import tolerance -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") +from . import paths @dataclass @@ -55,11 +53,11 @@ class Instance: def load_ufl() -> Instance: - with open(os.path.join(DATA_DIR, "ufl_warehouses.csv"), encoding="utf-8") as f: + with open(paths.table("ufl_warehouses.csv"), encoding="utf-8") as f: wrows = list(csv.DictReader(f)) - with open(os.path.join(DATA_DIR, "ufl_demand.csv"), encoding="utf-8") as f: + with open(paths.table("ufl_demand.csv"), encoding="utf-8") as f: drows = list(csv.DictReader(f)) - with open(os.path.join(DATA_DIR, "ufl_shipping_cost.csv"), encoding="utf-8") as f: + with open(paths.table("ufl_shipping_cost.csv"), encoding="utf-8") as f: srows = list(csv.DictReader(f)) return Instance( warehouses=[r["Warehouse"] for r in wrows], diff --git a/src/orteach/games.py b/src/orteach/games.py index 97a6758..9e659b3 100644 --- a/src/orteach/games.py +++ b/src/orteach/games.py @@ -16,15 +16,13 @@ from __future__ import annotations import csv -import os from dataclasses import dataclass import gurobipy as gp from . import tolerance -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") +from . import paths @dataclass @@ -37,7 +35,7 @@ class Game: def load_game(filename: str) -> Game: """Matrix layout: first column names the row, header names the columns.""" - with open(os.path.join(DATA_DIR, filename), encoding="utf-8") as f: + with open(paths.table(filename), encoding="utf-8") as f: recs = list(csv.DictReader(f)) cols = [k for k in recs[0].keys() if k != "row"] rows = [r["row"] for r in recs] diff --git a/src/orteach/goal_programming.py b/src/orteach/goal_programming.py index 28e4989..febe50c 100644 --- a/src/orteach/goal_programming.py +++ b/src/orteach/goal_programming.py @@ -27,15 +27,13 @@ from __future__ import annotations import csv -import os from dataclasses import dataclass, field import gurobipy as gp from . import tolerance -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") +from . import paths @dataclass @@ -54,7 +52,7 @@ class Instance: def load_topad(labor_cap=10.0, radio_cap=6.0, exposure_goal=45.0, budget=100.0) -> Instance: """The table comes from the file; the four scalars are knobs the caller names, so the notebook can hand them over explicitly.""" - with open(os.path.join(DATA_DIR, "topad_media.csv"), encoding="utf-8") as f: + with open(paths.table("topad_media.csv"), encoding="utf-8") as f: rows = list(csv.DictReader(f)) return Instance( media=[r["medium"] for r in rows], diff --git a/src/orteach/inference.py b/src/orteach/inference.py index 7efa573..972fbfa 100644 --- a/src/orteach/inference.py +++ b/src/orteach/inference.py @@ -29,10 +29,9 @@ class score vectors; those are not published. import numpy as np from scipy import stats -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") +from . import paths -SCORES_CSV = os.path.join(DATA_DIR, "exam_scores.csv") +SCORES_CSV = "exam_scores.csv" # resolved by paths.table() when read SCORES_SEED = 20260905 SCORES_N = 22 SCORES_SHAPE = {"exam1": (75.0, 22.0, 100.0), "exam2": (70.0, 27.0, 105.0)} # mean, sd, cap @@ -51,7 +50,8 @@ def generate_scores(seed: int = SCORES_SEED, n: int = SCORES_N) -> dict: return out -def write_scores(path: str = SCORES_CSV) -> None: +def write_scores(path: str | None = None) -> None: + path = path or os.path.join(paths.SOURCE_DIR, SCORES_CSV) # writes the clone's own table scores = generate_scores() with open(path, "w", newline="", encoding="utf-8") as f: w = csv.writer(f) @@ -60,7 +60,8 @@ def write_scores(path: str = SCORES_CSV) -> None: w.writerow([i + 1, scores["exam1"][i], scores["exam2"][i]]) -def load_scores(path: str = SCORES_CSV) -> dict: +def load_scores(path: str | None = None) -> dict: + path = path or paths.table(SCORES_CSV) with open(path, encoding="utf-8") as f: rows = list(csv.DictReader(f)) return {"exam1": [float(r["exam1"]) for r in rows], "exam2": [float(r["exam2"]) for r in rows]} @@ -68,7 +69,7 @@ def load_scores(path: str = SCORES_CSV) -> dict: def load_table(filename: str) -> dict: """A CSV as {column: list}, numeric where every entry parses.""" - with open(os.path.join(DATA_DIR, filename), encoding="utf-8") as f: + with open(paths.table(filename), encoding="utf-8") as f: rows = list(csv.DictReader(f)) out = {} for col in rows[0].keys(): diff --git a/src/orteach/markov.py b/src/orteach/markov.py index 6fe67d2..25e0edb 100644 --- a/src/orteach/markov.py +++ b/src/orteach/markov.py @@ -14,15 +14,13 @@ from __future__ import annotations import csv -import os from dataclasses import dataclass import numpy as np from . import tolerance -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") +from . import paths ROW_SUM_ATOL = tolerance.LINALG_ATOL @@ -49,7 +47,7 @@ def index(self, state): def load_chain(filename: str) -> Chain: - with open(os.path.join(DATA_DIR, filename), encoding="utf-8") as f: + with open(paths.table(filename), encoding="utf-8") as f: recs = list(csv.DictReader(f)) states = [k for k in recs[0].keys() if k != "state"] P = np.array([[float(r[s]) for s in states] for r in recs]) diff --git a/src/orteach/nonconvex.py b/src/orteach/nonconvex.py index 12fd379..d75b616 100644 --- a/src/orteach/nonconvex.py +++ b/src/orteach/nonconvex.py @@ -24,7 +24,6 @@ from __future__ import annotations import csv -import os from dataclasses import dataclass import gurobipy as gp @@ -32,8 +31,7 @@ from . import tolerance -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") +from . import paths # ----------------------------------------------------------------------------- traffic fit @@ -46,7 +44,7 @@ class Traffic: def load_traffic() -> Traffic: - with open(os.path.join(DATA_DIR, "traffic_counts.csv"), encoding="utf-8") as f: + with open(paths.table("traffic_counts.csv"), encoding="utf-8") as f: rows = list(csv.DictReader(f)) return Traffic([float(r["volume"]) for r in rows], [float(r["travel_time"]) for r in rows]) @@ -148,9 +146,9 @@ def direct(self): def load_pooling() -> Pooling: - with open(os.path.join(DATA_DIR, "pooling_sources.csv"), encoding="utf-8") as f: + with open(paths.table("pooling_sources.csv"), encoding="utf-8") as f: srows = list(csv.DictReader(f)) - with open(os.path.join(DATA_DIR, "pooling_products.csv"), encoding="utf-8") as f: + with open(paths.table("pooling_products.csv"), encoding="utf-8") as f: prows = list(csv.DictReader(f)) return Pooling( sources=[r["source"] for r in srows], products=[r["product"] for r in prows], diff --git a/src/orteach/paths.py b/src/orteach/paths.py new file mode 100644 index 0000000..e72b2f8 --- /dev/null +++ b/src/orteach/paths.py @@ -0,0 +1,69 @@ +"""Where the instance tables are: one function, so every module finds data/raw the same way. + +Standard Part 4, "the table has to be reachable from wherever the notebook runs". +`pip install git+https://github.com/sear-labs/teaching-code` ships this package and NOT +`data/raw/`, which sits at the repository root and never enters the wheel. Until 2026-10-27 +every module found its tables by walking up from `__file__`, which is right in a clone and +an editable install and lands on site-packages' parent anywhere else, so the error read like +a corrupt download. + +The order, local copy first: + + 1. an explicit `data_dir=` a test, or a reader's own copy NAMED: honoured or refused + 2. $ORTEACH_DATA an override needing no code change NAMED: honoured or refused + 3. data/raw beside the code a clone, or `pip install -e .` + 4. data/raw under the cwd a script run from the repository root + 5. the published raw URL everything else, at the release TAG, cached locally + +A named location that lacks the file raises; it never falls through to the next candidate, +because handing someone who pointed at their own edited copy the published numbers instead +is the silent failure this ordering exists to prevent. Local must win over the URL for the +same reason: the notebooks tell the reader to edit a table and re-run, and the agreement +assertion stays green only if both halves read the edited file. + +The URL names a tag, not `main`: a notebook handed to students must not change its answer +when someone edits a table on the default branch. +""" +from __future__ import annotations + +import os +import urllib.request + +TAG = "v1.0.0" +REPO = "sear-labs/teaching-code" +RAW_URL = "https://raw.githubusercontent.com/%s/%s/data/raw/" % (REPO, TAG) +ENV = "ORTEACH_DATA" + +_HERE = os.path.dirname(os.path.abspath(__file__)) +SOURCE_DIR = os.path.normpath(os.path.join(_HERE, "..", "..", "data", "raw")) # in a clone + + +def _cache_dir() -> str: + base = os.environ.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache") + return os.path.join(base, "orteach", TAG) + + +def table(name: str, data_dir: str | None = None) -> str: + """Absolute path of instance table `name` (e.g. "diet_macros_foods.csv").""" + for label, where in (("data_dir argument", data_dir), ("$" + ENV, os.environ.get(ENV))): + if where: + path = os.path.join(where, name) + if not os.path.isfile(path): + raise FileNotFoundError("%s points at %s, which has no %s. A named location is " + "used or refused, never skipped." % (label, where, name)) + return path + for where in (SOURCE_DIR, os.path.join(os.getcwd(), "data", "raw")): + path = os.path.join(where, name) + if os.path.isfile(path): + return path + cached = os.path.join(_cache_dir(), name) + if not os.path.isfile(cached): + os.makedirs(os.path.dirname(cached), exist_ok=True) + url = RAW_URL + name + try: + urllib.request.urlretrieve(url, cached + ".part") + except OSError as e: + raise FileNotFoundError("%s is not in a local data/raw and could not be fetched from " + "%s (%s). Clone the repository, or set $%s." % (name, url, e, ENV)) from e + os.replace(cached + ".part", cached) + return cached diff --git a/src/orteach/sourcing.py b/src/orteach/sourcing.py index a3ba2d7..9100119 100644 --- a/src/orteach/sourcing.py +++ b/src/orteach/sourcing.py @@ -19,15 +19,13 @@ from __future__ import annotations import csv -import os from dataclasses import dataclass, field import gurobipy as gp from . import tolerance -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") +from . import paths @dataclass @@ -46,7 +44,7 @@ def total_demand(self): def load_sourcing() -> Instance: def rows(name): - with open(os.path.join(DATA_DIR, name), encoding="utf-8") as f: + with open(paths.table(name), encoding="utf-8") as f: return list(csv.DictReader(f)) routes = rows("sourcing_routes.csv") return Instance( diff --git a/src/orteach/transportation.py b/src/orteach/transportation.py index ef904be..b97f818 100644 --- a/src/orteach/transportation.py +++ b/src/orteach/transportation.py @@ -25,15 +25,13 @@ from __future__ import annotations import csv -import os from dataclasses import dataclass, field import gurobipy as gp from . import tolerance -DATA_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( - os.path.abspath(__file__)))), "data", "raw") +from . import paths @dataclass @@ -58,14 +56,14 @@ def load_instance(arcs_csv, nodes_csv, cost_col, qty_col, scale=1.0, name="") -> demands are given in units and converted here, in one place, by a named number.""" arcs = {} - with open(os.path.join(DATA_DIR, arcs_csv), encoding="utf-8") as f: + with open(paths.table(arcs_csv), encoding="utf-8") as f: rows = list(csv.DictReader(f)) cols = list(rows[0].keys()) o_col, d_col = cols[0], cols[1] # first two columns name the arc for r in rows: arcs[(r[o_col], r[d_col])] = float(r[cost_col]) supply, demand = {}, {} - with open(os.path.join(DATA_DIR, nodes_csv), encoding="utf-8") as f: + with open(paths.table(nodes_csv), encoding="utf-8") as f: for r in csv.DictReader(f): q = float(r[qty_col]) / scale (supply if r["kind"] == "supply" else demand)[r["node"]] = q diff --git a/tests/test_dependencies.py b/tests/test_dependencies.py new file mode 100644 index 0000000..ca5bd8b --- /dev/null +++ b/tests/test_dependencies.py @@ -0,0 +1,99 @@ +"""Every third-party import is declared in pyproject.toml (standard Part 6). + +An undeclared import is invisible on the authoring machine and on Colab, which ship most +of the scientific stack, and fatal on a clean install. So the imports are SCANNED (parsed, +never executed: importing may build a model) and compared with pyproject.toml, which is +READ rather than restated here, so this guard cannot drift from the file it guards. + + src/orteach the core dependencies, plus an extra for an import made inside a function + (orteach.energy reaches PyPSA only when a network is built) + notebooks/ the core dependencies and the extras; google.colab is Colab's own + tests/ all of the above plus dev + +A distribution whose import name differs from its project name needs an entry in MODULE_OF. +An unknown distribution FAILS rather than being guessed at: loosening the check to pass would +hide exactly the change it exists to catch. +""" +import ast +import json +import re +import sys +from pathlib import Path + +if sys.version_info >= (3, 11): + import tomllib +else: # declared in dev for 3.10; never skipped + import tomli as tomllib + +ROOT = Path(__file__).resolve().parents[1] +PYPROJECT = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))["project"] + +# project name on PyPI -> the module it installs. Every declared distribution must appear. +MODULE_OF = {"gurobipy": "gurobipy", "numpy": "numpy", "scipy": "scipy", "matplotlib": "matplotlib", + "pytest": "pytest", "statsmodels": "statsmodels", "ruff": None, "tomli": "tomli", + "pypsa": "pypsa", "pandas": "pandas", "ipywidgets": "ipywidgets"} +PLATFORM = {"google"} # google.colab: present only on Colab, guarded there + + +def _dists(specs): + return {re.split(r"[<>=!~;\[ ]", s, maxsplit=1)[0].strip().lower() for s in specs} + + +def _modules(dists): + unknown = sorted(d for d in dists if d not in MODULE_OF) + assert not unknown, ("pyproject.toml declares %s, which MODULE_OF does not map to a module. " + "Add the mapping; do not loosen this test." % unknown) + return {MODULE_OF[d] for d in dists if MODULE_OF[d]} + + +CORE = _modules(_dists(PYPROJECT["dependencies"])) +EXTRAS = {k: _modules(_dists(v)) for k, v in PYPROJECT["optional-dependencies"].items()} +STDLIB = set(sys.stdlib_module_names) + + +def _imports(source): + out = set() + for node in ast.walk(ast.parse(source)): + if isinstance(node, ast.Import): + out |= {a.name.split(".")[0] for a in node.names} + elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module: + out.add(node.module.split(".")[0]) + return out + + +def _undeclared(found, allowed): + return sorted(m for m in found if m not in STDLIB | allowed | {"orteach"}) + + +def _notebook_code(path): + cells = json.loads(path.read_text(encoding="utf-8"))["cells"] + code = "\n".join("".join(c["source"]) for c in cells if c["cell_type"] == "code") + return "\n".join(ln for ln in code.splitlines() if not ln.lstrip().startswith(("!", "%"))) + + +def test_the_package_imports_only_what_it_declares(): + files = sorted((ROOT / "src" / "orteach").glob("*.py")) + assert files, "no package modules found" + allowed = CORE | EXTRAS["energy"] + bad = {f.name: _undeclared(_imports(f.read_text(encoding="utf-8")), allowed) for f in files} + bad = {k: v for k, v in bad.items() if v} + assert not bad, "imported but not declared in pyproject.toml: %s" % bad + print("%d modules scanned" % len(files)) + + +def test_every_notebook_imports_only_what_is_declared(): + nbs = sorted((ROOT / "notebooks").rglob("*.ipynb")) + assert len(nbs) >= 17, "found only %d notebooks" % len(nbs) + allowed = CORE | EXTRAS["energy"] | PLATFORM + bad = {n.name: _undeclared(_imports(_notebook_code(n)), allowed) for n in nbs} + bad = {k: v for k, v in bad.items() if v} + assert not bad, "imported but not declared in pyproject.toml: %s" % bad + print("%d notebooks scanned" % len(nbs)) + + +def test_the_tests_import_only_what_is_declared(): + files = sorted((ROOT / "tests").glob("*.py")) + allowed = CORE | EXTRAS["energy"] | EXTRAS["dev"] + bad = {f.name: _undeclared(_imports(f.read_text(encoding="utf-8")), allowed) for f in files} + bad = {k: v for k, v in bad.items() if v} + assert not bad, "imported but not declared in pyproject.toml: %s" % bad diff --git a/tests/test_paths.py b/tests/test_paths.py new file mode 100644 index 0000000..fae782d --- /dev/null +++ b/tests/test_paths.py @@ -0,0 +1,73 @@ +"""orteach.paths.table(): the one place every module finds an instance table. + +Standard Part 4: local must win, a NAMED location is honoured or refused and never skipped, +and the URL fallback names a tag. Each of those is a test below, by name. No test here touches +the network: the URL case fakes the download. +""" +import os +import sys + +import pytest + +sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname( + os.path.abspath(__file__))), "src")) + +from orteach import assignment, paths # noqa: E402 + +NAME = "assignment_4x4.csv" + + +@pytest.fixture +def no_env(monkeypatch): + monkeypatch.delenv(paths.ENV, raising=False) + + +def test_in_a_clone_the_table_comes_from_the_repository(no_env): + assert paths.table(NAME) == os.path.join(paths.SOURCE_DIR, NAME) + assert os.path.isfile(paths.table(NAME)) + + +def test_a_readers_edited_copy_reaches_the_loader(tmp_path, no_env): + """The case the ordering exists for: a reader edits a table in their own folder and the + package must read THAT file, not the published one.""" + (tmp_path / NAME).write_text("machine,job,cost\n1,1,99\n", encoding="utf-8") + assert paths.table(NAME, data_dir=str(tmp_path)) == str(tmp_path / NAME) + assert assignment.load_costs(paths.table(NAME, data_dir=str(tmp_path))) == {("1", "1"): 99.0} + + +def test_a_named_directory_without_the_file_is_refused_not_skipped(tmp_path, no_env): + with pytest.raises(FileNotFoundError, match="never skipped"): + paths.table(NAME, data_dir=str(tmp_path)) + + +def test_the_environment_variable_is_honoured_and_refused_the_same_way(tmp_path, monkeypatch): + monkeypatch.setenv(paths.ENV, str(tmp_path)) + with pytest.raises(FileNotFoundError, match=paths.ENV): + paths.table(NAME) # set, but empty: refused, not the repo's copy + (tmp_path / NAME).write_text("machine,job,cost\n", encoding="utf-8") + assert paths.table(NAME) == str(tmp_path / NAME) + + +def test_without_a_local_copy_it_fetches_the_tagged_file_once(tmp_path, monkeypatch, no_env): + """The pip-installed case: no data/raw beside the code or under the cwd.""" + monkeypatch.setattr(paths, "SOURCE_DIR", str(tmp_path / "absent")) + monkeypatch.chdir(tmp_path) + monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "cache")) + fetched = [] + + def fake_retrieve(url, dest): + fetched.append(url) + with open(dest, "w", encoding="utf-8") as f: + f.write("machine,job,cost\n") + + monkeypatch.setattr(paths.urllib.request, "urlretrieve", fake_retrieve) + first = paths.table(NAME) + second = paths.table(NAME) + assert first == second and os.path.isfile(first) + assert fetched == [paths.RAW_URL + NAME], fetched # once, then from the cache + assert first.startswith(str(tmp_path / "cache")) + + +def test_the_url_names_the_release_tag_not_a_branch(): + assert "/%s/data/raw/" % paths.TAG in paths.RAW_URL + assert "/main/" not in paths.RAW_URL and paths.TAG.startswith("v") diff --git a/tools/check_notebooks.py b/tools/check_notebooks.py index 61b33fa..7bfb2b8 100644 --- a/tools/check_notebooks.py +++ b/tools/check_notebooks.py @@ -28,6 +28,11 @@ in the prose came from that run) setup cell the Colab setup cell names this notebook's own folder licence id no Gurobi licence banner in any output + figure text every cell that outputs an image also prints a line starting + "Figure:" saying what the image SHOWS - its text alternative, + written in the same cell as the plot (standard Part 3, accessible) + setup cell tag the setup cell clones orteach.paths.TAG, the same release the + package fetches tables from """ from __future__ import annotations @@ -55,6 +60,11 @@ CODE_SPAN_RE = re.compile(r"`[^`]*`|\$\$.*?\$\$|\$[^$\n]*\$", re.S) EXERCISES_RE = re.compile(r"^#+\s*where to take this next.*", re.I | re.M | re.S) LICENCE_RE = re.compile(r"LicenseID to value|Academic license|Restricted license") +# The release the package fetches tables from, read from source (not imported). The setup cell +# must clone the same one, or Colab runs this notebook against tables from another release. +_TAG_M = re.search(r'^TAG = "([^"]+)"', (ROOT / "src" / "orteach" / "paths.py").read_text(encoding="utf-8"), re.M) +assert _TAG_M, "no TAG = ... in src/orteach/paths.py" +PACKAGE_TAG = _TAG_M.group(1) def _numbers_in_prose(md_text: str) -> list[str]: @@ -101,6 +111,15 @@ def src(c): if LICENCE_RE.search(outputs): fails.append("a Gurobi licence banner is in the outputs") + # every image has a text alternative in its own cell (a requirement in prose has already failed) + def _cell_text(c): + return "".join("".join(o.get("text", "")) for o in c.get("outputs", [])) + no_alt = [i for i, c in enumerate(cells) if c.get("cell_type") == "code" + and any("image/png" in o.get("data", {}) for o in c.get("outputs", [])) + and not any(line.startswith("Figure: ") for line in _cell_text(c).splitlines())] + if no_alt: + fails.append("%d figure cell(s) print no 'Figure:' text alternative: cells %s" % (len(no_alt), no_alt[:6])) + # orphans orphans = [i for i, c in enumerate(cells) if c.get("cell_type") == "code" and (i == 0 or cells[i - 1].get("cell_type") != "markdown")] @@ -169,6 +188,10 @@ def src(c): fails.append("no Colab setup cell (REPO_URL)") elif ("notebooks/%s" % folder) not in src(setup[0]): fails.append("setup cell does not chdir to notebooks/%s" % folder) + if setup and ('REF = "%s"' % PACKAGE_TAG) not in src(setup[0]): + fails.append("setup cell does not clone REF = %r, the release orteach.paths.TAG names" % PACKAGE_TAG) + if setup and '"--branch", REF' not in src(setup[0]): + fails.append("setup cell clones without --branch REF, so Colab gets main, not the release") return fails diff --git a/tools/seeds/seed_curvefit.py b/tools/seeds/seed_curvefit.py index 6faff63..3d29696 100644 --- a/tools/seeds/seed_curvefit.py +++ b/tools/seeds/seed_curvefit.py @@ -46,6 +46,7 @@ def code(t): 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 @@ -55,7 +56,7 @@ def code(t): if ON_COLAB: if not os.path.isdir("/content/teaching-code"): - subprocess.run(["git", "clone", "--quiet", REPO_URL, "/content/teaching-code"], check=True) + subprocess.run(["git", "clone", "--quiet", "--depth", "1", "--branch", REF, REPO_URL, "/content/teaching-code"], check=True) os.chdir("/content/teaching-code/notebooks/06_nonlinear_and_convex") subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "gurobipy>=11,<14"], check=True) diff --git a/tools/seeds/seed_diet.py b/tools/seeds/seed_diet.py index e85409a..1e440a2 100644 --- a/tools/seeds/seed_diet.py +++ b/tools/seeds/seed_diet.py @@ -40,6 +40,7 @@ def code(t): 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 @@ -49,7 +50,7 @@ def code(t): if ON_COLAB: if not os.path.isdir("/content/teaching-code"): - subprocess.run(["git", "clone", "--quiet", REPO_URL, "/content/teaching-code"], check=True) + subprocess.run(["git", "clone", "--quiet", "--depth", "1", "--branch", REF, REPO_URL, "/content/teaching-code"], check=True) os.chdir("/content/teaching-code/notebooks/01_lp_formulation") subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "gurobipy>=11,<14"], check=True) diff --git a/tools/seeds/seed_distributions.py b/tools/seeds/seed_distributions.py index 85663e6..9fcf0b8 100644 --- a/tools/seeds/seed_distributions.py +++ b/tools/seeds/seed_distributions.py @@ -40,6 +40,7 @@ def code(t): 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 @@ -49,7 +50,7 @@ def code(t): if ON_COLAB: if not os.path.isdir("/content/teaching-code"): - subprocess.run(["git", "clone", "--quiet", REPO_URL, "/content/teaching-code"], check=True) + subprocess.run(["git", "clone", "--quiet", "--depth", "1", "--branch", REF, REPO_URL, "/content/teaching-code"], check=True) os.chdir("/content/teaching-code/notebooks/14_probability_and_stats") subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "gurobipy>=11,<14"], check=True) @@ -103,6 +104,8 @@ def code(t): f"sqrt(n p (1-p)) = {math.sqrt(N_BINOM * P_BINOM * (1 - P_BINOM)):.3f}") plt.hist(sample, bins=range(sample.min(), sample.max() + 2), color="lightblue", edgecolor="white") plt.axvline(sample.mean(), color="red"); plt.title("Binomial(100, 0.25): 10,000 draws"); plt.show() +print(f"Figure: a histogram of the {N_SAMPLE:,} binomial draws, mound-shaped from {sample.min()} to " + f"{sample.max()}, peaking near {sample.mean():.1f}, with a vertical line at the sample mean.") ''') md(r""" @@ -291,6 +294,8 @@ def code(t): plt.plot(sample, ecdf, ".", ms=2, label="empirical") plt.plot(grid, [0.5 * (1 + math.erf((g - 50) / (10 * math.sqrt(2)))) for g in grid], "k-", lw=1, label="formula") plt.legend(); plt.title("Normal(50, 10): empirical CDF of 10,000 draws"); plt.show() +print(f"Figure: the empirical CDF of the {N_SAMPLE:,} draws (dots) lies on the formula's S-shaped " + f"curve (solid line), rising from 0 near 20 to 1 near 80 and passing 0.5 at 50.") print(f"largest gap between the two: {np.max(np.abs(ecdf - stats.norm.cdf(sample, 50, 10))):.4f}") ''') @@ -338,6 +343,9 @@ def code(t): for ax, size in zip(axes[1:], SIZES): ax.hist(means[size], bins=30, color="lightgreen"); ax.set_title(f"means of samples of {size}") plt.tight_layout(); plt.show() +print(f"Figure: four histograms. The exponential population is skewed hard to the right; the " + f"means of samples of {SIZES[0]}, {SIZES[1]} and {SIZES[2]} are mound-shaped around 4, with spreads " + f"(standard deviation) {means[SIZES[0]].std():.3f}, {means[SIZES[1]].std():.3f} and {means[SIZES[2]].std():.3f}.") ''') md(r""" diff --git a/tools/seeds/seed_duality.py b/tools/seeds/seed_duality.py index 662608d..31662ea 100644 --- a/tools/seeds/seed_duality.py +++ b/tools/seeds/seed_duality.py @@ -41,6 +41,7 @@ def code(t): 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 @@ -50,7 +51,7 @@ def code(t): if ON_COLAB: if not os.path.isdir("/content/teaching-code"): - subprocess.run(["git", "clone", "--quiet", REPO_URL, "/content/teaching-code"], check=True) + subprocess.run(["git", "clone", "--quiet", "--depth", "1", "--branch", REF, REPO_URL, "/content/teaching-code"], check=True) os.chdir("/content/teaching-code/notebooks/03_duality_and_sensitivity") subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "gurobipy>=11,<14"], check=True) diff --git a/tools/seeds/seed_energy.py b/tools/seeds/seed_energy.py index f01221c..4e1e304 100644 --- a/tools/seeds/seed_energy.py +++ b/tools/seeds/seed_energy.py @@ -42,6 +42,7 @@ def code(t): 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 @@ -51,7 +52,7 @@ def code(t): if ON_COLAB: if not os.path.isdir("/content/teaching-code"): - subprocess.run(["git", "clone", "--quiet", REPO_URL, "/content/teaching-code"], check=True) + subprocess.run(["git", "clone", "--quiet", "--depth", "1", "--branch", REF, REPO_URL, "/content/teaching-code"], check=True) os.chdir("/content/teaching-code/notebooks/12_energy_systems_pypsa") subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "gurobipy>=11,<14", "pypsa", "highspy"], check=True) diff --git a/tools/seeds/seed_games.py b/tools/seeds/seed_games.py index 43b4df6..c71f5d6 100644 --- a/tools/seeds/seed_games.py +++ b/tools/seeds/seed_games.py @@ -41,6 +41,7 @@ def code(t): 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 @@ -50,7 +51,7 @@ def code(t): if ON_COLAB: if not os.path.isdir("/content/teaching-code"): - subprocess.run(["git", "clone", "--quiet", REPO_URL, "/content/teaching-code"], check=True) + subprocess.run(["git", "clone", "--quiet", "--depth", "1", "--branch", REF, REPO_URL, "/content/teaching-code"], check=True) os.chdir("/content/teaching-code/notebooks/10_game_theory") subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "gurobipy>=11,<14"], check=True) diff --git a/tools/seeds/seed_goal.py b/tools/seeds/seed_goal.py index f5fc541..85dc816 100644 --- a/tools/seeds/seed_goal.py +++ b/tools/seeds/seed_goal.py @@ -43,6 +43,7 @@ def code(t): 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 @@ -52,7 +53,7 @@ def code(t): if ON_COLAB: if not os.path.isdir("/content/teaching-code"): - subprocess.run(["git", "clone", "--quiet", REPO_URL, "/content/teaching-code"], check=True) + subprocess.run(["git", "clone", "--quiet", "--depth", "1", "--branch", REF, REPO_URL, "/content/teaching-code"], check=True) os.chdir("/content/teaching-code/notebooks/01_lp_formulation") subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "gurobipy>=11,<14"], check=True) diff --git a/tools/seeds/seed_inference.py b/tools/seeds/seed_inference.py index 457a151..2a95e08 100644 --- a/tools/seeds/seed_inference.py +++ b/tools/seeds/seed_inference.py @@ -40,6 +40,7 @@ def code(t): 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 @@ -49,7 +50,7 @@ def code(t): if ON_COLAB: if not os.path.isdir("/content/teaching-code"): - subprocess.run(["git", "clone", "--quiet", REPO_URL, "/content/teaching-code"], check=True) + subprocess.run(["git", "clone", "--quiet", "--depth", "1", "--branch", REF, REPO_URL, "/content/teaching-code"], check=True) os.chdir("/content/teaching-code/notebooks/14_probability_and_stats") subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "gurobipy>=11,<14"], check=True) diff --git a/tools/seeds/seed_markov.py b/tools/seeds/seed_markov.py index 858aac6..abcd065 100644 --- a/tools/seeds/seed_markov.py +++ b/tools/seeds/seed_markov.py @@ -42,6 +42,7 @@ def code(t): 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 @@ -51,7 +52,7 @@ def code(t): if ON_COLAB: if not os.path.isdir("/content/teaching-code"): - subprocess.run(["git", "clone", "--quiet", REPO_URL, "/content/teaching-code"], check=True) + subprocess.run(["git", "clone", "--quiet", "--depth", "1", "--branch", REF, REPO_URL, "/content/teaching-code"], check=True) os.chdir("/content/teaching-code/notebooks/09_queueing_and_markov") subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "gurobipy>=11,<14"], check=True) diff --git a/tools/seeds/seed_pooling.py b/tools/seeds/seed_pooling.py index ec902d6..31c8275 100644 --- a/tools/seeds/seed_pooling.py +++ b/tools/seeds/seed_pooling.py @@ -41,6 +41,7 @@ def code(t): 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 @@ -50,7 +51,7 @@ def code(t): if ON_COLAB: if not os.path.isdir("/content/teaching-code"): - subprocess.run(["git", "clone", "--quiet", REPO_URL, "/content/teaching-code"], check=True) + subprocess.run(["git", "clone", "--quiet", "--depth", "1", "--branch", REF, REPO_URL, "/content/teaching-code"], check=True) os.chdir("/content/teaching-code/notebooks/06_nonlinear_and_convex") subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "gurobipy>=11,<14"], check=True) diff --git a/tools/seeds/seed_sourcing.py b/tools/seeds/seed_sourcing.py index 1994e50..ce7ab63 100644 --- a/tools/seeds/seed_sourcing.py +++ b/tools/seeds/seed_sourcing.py @@ -41,6 +41,7 @@ def code(t): 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 @@ -50,7 +51,7 @@ def code(t): if ON_COLAB: if not os.path.isdir("/content/teaching-code"): - subprocess.run(["git", "clone", "--quiet", REPO_URL, "/content/teaching-code"], check=True) + subprocess.run(["git", "clone", "--quiet", "--depth", "1", "--branch", REF, REPO_URL, "/content/teaching-code"], check=True) os.chdir("/content/teaching-code/notebooks/13_supply_chain") subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "gurobipy>=11,<14"], check=True)