environment.yml

# Environment for CBE/ACMS 40499 & 60499 — Optimization for Decision Science
#
# One environment for both jobs:
#   1. running the course notebooks locally
#   2. building and contributing to the course website
#
#   conda env create -f environment.yml
#   conda activate optimization_fall2026
#   idaes get-extensions        # solvers -> ~/.idaes/bin; skip if already present
#
# Then add ~/.idaes/bin to PATH so Pyomo can find Ipopt, k_aug, and dot_sens.
#
# No separate `npm install -g mystmd` is needed: the jupyter-book 2.x pip
# package ships the MyST CLI (`jupyter-book build --html`) and manages its own
# Node toolchain. `nodejs` is kept below for building the custom site theme.
#
# Verified 2026-08-17 on osx-arm64: Python 3.13.15, Pyomo 6.10.1,
# jupyter-book 2.1.6, Ipopt 3.13.2. Re-verified 2026-08-18 with glpk 5.0 and
# casadi 3.7.2 added.
#
# NOTE ON PATH. Pyomo locates solvers as executables on PATH, so running the
# notebooks needs BOTH directories visible, and 🔴 ~/.idaes/bin must come FIRST:
#     export PATH="$HOME/.idaes/bin:$CONDA_PREFIX/bin:$PATH"
# Activating the environment covers the second; the first is never automatic.
# Calling the interpreter by absolute path covers NEITHER -- SolverFactory
# ('glpk').available() returns False even though glpsol is installed.
#
# ⚠ THE ORDER MATTERS AND USED TO BE WRONG HERE (corrected 2026-09-07). With
# $CONDA_PREFIX/bin first, conda-forge's ipopt 3.14.19 -- pulled in as a
# transitive dependency of idaes-pse, never requested below -- SHADOWS the IDAES
# one, and it has NO HSL: linear_solver=ma27/ma57/ma97 all die with
# "dlopen(libhsl.dylib): no such file". The IDAES binaries (extensions v3.4.2,
# Ipopt 3.13.2) are statically linked against HSL, and are also what students get
# on Colab via `idaes get-extensions` -- so this order is what makes local runs
# reproduce the student environment. It is also what the "Ipopt 3.13.2" in the
# verification note above actually refers to.
#
# Blast radius of putting IDAES first is exactly TWO binaries: `ipopt` and
# `ipopt_sens` are the only names present in both directories. glpsol stays
# conda's; cbc, bonmin, couenne, clp, k_aug and dot_sens exist only in
# ~/.idaes/bin either way.
#
# To make it automatic for a local dev environment, drop a script in
# $CONDA_PREFIX/etc/conda/activate.d/ that prepends ~/.idaes/bin, with a matching
# deactivate.d that strips that one entry back off. Do NOT save and restore the
# whole PATH in the deactivate hook -- the saved copy is captured after conda has
# already added the env bin, so restoring it leaks the env bin into the
# deactivated shell.

name: optimization_fall2026

channels:
  - conda-forge

dependencies:
  - python=3.13

  # Optimization stack. idaes-pse pulls in Pyomo (>=6.10.1) and provides both
  # the diagnostics toolbox (degeneracy hunter) and the solver binaries
  # (ipopt, k_aug, dot_sens, cbc, bonmin, couenne) into ~/.idaes/bin.
  - idaes-pse

  # glpk supplies the `glpsol` MILP solver. Added 2026-08-18: it was never in
  # this file, and the notebooks only ever installed it on Colab via
  # helper.install_glpk() -- so a LOCAL run had never had it. That single
  # omission accounted for four of the W1 audit's failures (Pyomo1, Pyomo2,
  # Pyomo-Mini-Project, Sudoku_Solver).
  - glpk

  # highspy supplies the HiGHS solver via pyomo's appsi_highs interface, used by
  # notebooks/contrib/semiconductor_manufacturing.ipynb. Added 2026-08-18: it was
  # in the "not included, unmaintained upstream" list below, but that rationale
  # was wrong -- HiGHS is actively maintained and ships a cp313 arm64 wheel.
  - highspy

  # casadi is imported by notebooks/3-dev/DAE_background.ipynb, a core chapter.
  # Added 2026-08-18: it was neither a dependency nor in the "install ad hoc"
  # list below -- a genuine oversight, not a deliberate exclusion.
  - casadi

  # Scientific Python used across the notebooks
  - numpy
  - scipy
  - pandas
  - matplotlib
  - scikit-learn
  - networkx
  - sympy
  - openpyxl        # reads knapsack_data.xlsx
  - tabulate
  - tqdm
  - seaborn

  # Notebooks
  - jupyterlab
  - ipykernel
  - ipywidgets
  - nbformat        # required by scripts/process_notebooks.py

  # Website toolchain (JupyterBook 2 / MyST). The `myst` CLI itself comes from
  # npm; nodejs is here so `npm install -g mystmd` works inside the environment.
  - nodejs

  # poppler supplies `pdftotext`, which four of the course-pack checkers in
  # ../optimization-private/lecture-notes/ shell out to (check_leaks,
  # check_pagination, check_clipping, and the fixnote verification). Added
  # 2026-08-22: it was never declared, and on the machine where this was found
  # it happened to be satisfied by an unrelated Homebrew install -- so the
  # checkers passed for a reason that had nothing to do with this file.
  - poppler

  # Development
  - pytest
  - pip
  - pip:
      - jupyter-book
      - black[jupyter]
      # pypdf is imported by lecture-notes/check_citations.py, the gate that
      # verifies every textbook page citation in the course pack. Added
      # 2026-08-22: it was missing, so that checker was the ONE of ten that
      # could not run in this environment at all. Worse, its own error message
      # said "pypdf required: conda activate optimization_fall2026" -- naming
      # the environment that lacked it, so following the instruction did not
      # help. Anyone who ran it and got a result was silently using a different
      # interpreter.
      - pypdf

# Not included — needed only by a few student-contributed notebooks, several of
# which are unmaintained upstream. Install ad hoc if you are working on those:
#   GPy, GPyOpt, scikit-optimize, xgboost, nltk, Tasmanian, okabeito
#
# Of these, GPyOpt is genuinely dead -- archived repo, sdist only, last released
# 2020 -- which is why notebooks/contrib/Bayesian_Optimization1.ipynb is being
# retired rather than repaired. GPy itself is NOT dead (1.14.2, cp313 wheels);
# it is simply only needed by that one notebook.