@ohtaman/washi 0.6.0 → 0.7.0

package/docs/guide/decomposition.md

@@ -1,162 +1,163 @@
-# Advanced Decomposition Methods & Best Practices
+# Decomposition Methods (`solveColumnGeneration` & `solveBenders`)
 
-Mixed-Integer Programming (MIP) formulations can become slow when symmetry or coupling constraints cause branch-and-bound trees to grow large.
-WaSHI provides decomposition orchestrators (`master.solveColumnGeneration` and `master.solveBenders`) along with lower-level modeling primitives for dual inspection and dynamic model modification.
+When monolithic Mixed-Integer Programming (MIP) models have exponentially many candidate patterns or large multi-stage subproblems, WaSHI provides two high-level decomposition orchestrators—`master.solveColumnGeneration()` and `master.solveBenders()`—along with low-level primitives for dual inspection and dynamic model updates.
 
----
-
-## Why Decomposition? (When Monolithic MIP Stalls)
-
-There are two common problem structures where monolithic MIP formulations struggle:
-
-| Problem Structure | Monolithic MIP Bottleneck | Technique | WaSHI API |
-| :--- | :--- | :--- | :--- |
-| **Symmetry & Loose Continuous Bounds**<br>*(Cutting Stock, Vehicle Routing/VRP, Crew Rostering)* | Symmetric permutations and a weak continuous relaxation enlarge the branch-and-bound tree. | **Column Generation**<br>*(Dantzig-Wolfe Decomposition)* | [`master.solveColumnGeneration()`](#column-generation-solvecolumngeneration) |
-| **Complicating Decisions & Multi-Stage Structure**<br>*(Traveling Salesperson/TSP, Facility Location with Routing, Two-Stage Stochastic Planning)* | Coupling master decisions with large scenario or operational subproblems increases the matrix size. | **Benders Decomposition** | [`master.solveBenders()`](#benders-decomposition-solvebenders) |
+| Decomposition Method | WaSHI Orchestrator | Typical Use Case |
+| :--- | :--- | :--- |
+| **Column Generation** *(Dantzig-Wolfe)* | [`master.solveColumnGeneration()`](#column-generation-solvecolumngeneration) | Models with exponentially many patterns, routes, or schedules (e.g., Cutting Stock, Vehicle Routing, Crew Rostering). |
+| **Benders Decomposition** *(and Lazy Cuts)* | [`master.solveBenders()`](#benders-decomposition-solvebenders) | Two-stage or complicating-variable problems (e.g., Facility Location + Dispatch, Stochastic Planning, TSP Subtour Elimination). |
 
 ---
 
 ## Foundational Primitives
 
-WaSHI provides fine-grained modeling primitives to inspect dual information and dynamically modify models:
+WaSHI exposes four lower-level primitives used internally by the decomposition orchestrators and available directly for custom algorithms:
 
-### 1. Constraint Duals (`dual`)
-Access the dual values (marginal impact on the objective per unit change in RHS) after an LP solve:
+### 1. Constraint Duals (`c.dual`)
+After solving a continuous linear program (LP), read the shadow price (marginal impact on the objective per unit change in RHS) of each constraint:
 
 ```typescript
-m.constraint(expr`${x} + ${y} <= 10`, "capacity");
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0 });
+const y = m.continuous("y", { lb: 0 });
+
+m.objective(maximize(expr`3 * ${x} + 2 * ${y}`));
+const c = m.constraint(expr`${x} + ${y} <= 10`, "capacity");
 await m.solve();
 
-const c = m.getConstraintByName("capacity")!;
-console.log(c.dual); // Dual value / shadow price
-console.log(m.solution?.duals.capacity);
+console.log(c.dual);                    // Dual value / shadow price
+console.log(m.solution?.duals.capacity); // Lookup by constraint name
 ```
 
-### 2. Continuous LP Relaxation (`model.relax()`)
-Decomposition algorithms require solving the continuous LP relaxation to extract dual values. `model.relax()` temporarily relaxes all `Integer` and `Binary` variables to continuous variables within their bounds:
+### 2. Continuous LP Relaxation (`m.relax()`)
+`m.relax()` temporarily relaxes all `Integer` and `Binary` variables to continuous variables within their `[lb, ub]` bounds and solves the LP relaxation so constraint duals are populated:
 
 ```typescript
-// Solves LP relaxation and populates shadow prices in m.solution.duals
+// Solves the continuous LP relaxation and populates m.solution.duals
 const status = await m.relax();
-console.log("Theoretical dual bound:", m.objectiveValue);
+console.log("LP relaxation bound:", m.objectiveValue);
 ```
 
-### 3. Dynamic Column Injection (`model.addColumn()`)
-Inject a new decision variable along with its objective coefficient and constraint contributions in a single call:
+### 3. Dynamic Column Injection (`m.addColumn()`)
+Create a new decision variable, set its objective coefficient, and attach its non-zero coefficients to existing named constraints in a single call:
 
 ```typescript
 const col = m.addColumn({
   name: "pattern_1",
-  type: "Integer", // or "Continuous"
+  type: "Integer", // or "Continuous" / "Binary"
   lb: 0,
-  cost: 1, // objective coefficient
+  cost: 1, // Objective coefficient
   coefficients: {
-    demand_itemA: 2,
-    demand_itemB: 1,
+    capacity: 2,
   },
 });
 ```
 
-### 4. Dynamic Constraint Modification (`addTerm` / `setTerm`)
-Update the coefficients of individual variables in an existing constraint:
+### 4. Dynamic Constraint Term Updates (`c.addTerm()` / `c.setTerm()`)
+Increment or overwrite the coefficient of a variable inside an existing linear constraint:
 
 ```typescript
-const c = m.getConstraintByName("budget")!;
-c.addTerm(newVar, 5); // Increments newVar's coefficient by 5
-c.setTerm(newVar, 0); // Setting to 0 cleanly removes the term
+const extra = m.continuous("extra", { lb: 0 });
+const budget = m.constraint(expr`${x} + ${y} <= 20`, "budget");
+
+budget.addTerm(extra, 5); // Adds +5 * extra to the LHS
+budget.setTerm(extra, 0); // Setting 0 removes extra from the constraint
 ```
 
 ---
 
 ## Column Generation (`solveColumnGeneration`)
 
-Column Generation starts with a **Restricted Master Problem (RMP)** with a small subset of columns. In each iteration:
-1. It solves the RMP's LP relaxation via `master.relax()`.
-2. Evaluates a pricing subproblem using constraint shadow prices.
-3. Finds candidate columns with negative reduced costs ($\bar{c} = \text{cost} - \sum \pi_i a_i < 0$) and dynamically injects them into the master problem.
-4. Repeats until no improving columns exist.
-5. Finally solves the full master model as a Mixed-Integer Program (`finalizeAsMIP`, default: `true`) to obtain optimal integer solutions.
+`master.solveColumnGeneration(options)` starts from a **Restricted Master Problem (RMP)** containing an initial feasible subset of columns and executes the column generation loop:
+1. Solves the continuous LP relaxation of the master problem via `master.relax()`.
+2. Invokes your `pricing` callback with the current dual shadow prices (`duals`, `getDual`).
+3. Evaluates candidate columns (`ColumnProposal` or `ColumnProposal[]`), dynamically injecting those with improving reduced costs ($\bar{c} = \text{cost} - \sum_i \pi_i a_i < 0$ when minimizing).
+4. Repeats until `pricing` returns `null` / `[]` or no column improves the objective beyond `reducedCostTolerance`.
+5. Optionally solves the final master model as a MIP (`finalizeAsMIP: true`, the default) to obtain an integer solution over all generated columns.
 
-### Column Generation with the `pricing` Callback
-
-Provide a `pricing` callback that receives constraint shadow prices (duals), solves the subproblem (using a WaSHI model or any custom algorithm), and returns new column proposals. WaSHI automatically evaluates reduced costs and injects improving columns:
+### Pricing with a WaSHI Subproblem Model
 
 ```typescript
 import { Model, expr, minimize, maximize } from "@ohtaman/washi";
 
 const rollWidth = 100;
-const items = [
-  { id: "A", width: 45, demand: 10 },
-  { id: "B", width: 36, demand: 14 },
-  { id: "C", width: 16, demand: 20 },
-];
 
-// 1. Define Restricted Master Problem (RMP) with naive initial single-cut patterns
+// 1. Restricted Master Problem (RMP) with simple single-item initial patterns
 const master = new Model("CuttingStockMaster");
-
-const pA = master.integer("init_A", { lb: 0 }); // 2 of A per roll (45*2 = 90 <= 100)
-const pB = master.integer("init_B", { lb: 0 }); // 2 of B per roll (36*2 = 72 <= 100)
-const pC = master.integer("init_C", { lb: 0 }); // 6 of C per roll (16*6 = 96 <= 100)
+const pA = master.integer("init_A", { lb: 0 }); // 2 of A (width 45) per roll
+const pB = master.integer("init_B", { lb: 0 }); // 2 of B (width 36) per roll
+const pC = master.integer("init_C", { lb: 0 }); // 6 of C (width 16) per roll
 
 master.objective(minimize(expr`${pA} + ${pB} + ${pC}`));
-master.constraint(expr`2 * ${pA} >= 10`, "demand_A");
-master.constraint(expr`2 * ${pB} >= 14`, "demand_B");
-master.constraint(expr`6 * ${pC} >= 20`, "demand_C");
-const [demandA, demandB, demandC] = master.constraints;
+const demandA = master.constraint(expr`2 * ${pA} >= 10`, "demand_A");
+const demandB = master.constraint(expr`2 * ${pB} >= 14`, "demand_B");
+const demandC = master.constraint(expr`6 * ${pC} >= 20`, "demand_C");
 
-// 2. Solve with master.solveColumnGeneration()
+// 2. Run Column Generation
 const result = await master.solveColumnGeneration({
   finalizeAsMIP: true,
   pricing: async () => {
-    // Pricing subproblem: Bounded Knapsack
+    // Knapsack pricing subproblem: find a pattern maximizing total dual value
     const sub = new Model("KnapsackPricing");
-    const a_A = sub.integer("a_A", { lb: 0, ub: 2 });
-    const a_B = sub.integer("a_B", { lb: 0, ub: 2 });
-    const a_C = sub.integer("a_C", { lb: 0, ub: 6 });
+    const aA = sub.integer("a_A", { lb: 0, ub: 2 });
+    const aB = sub.integer("a_B", { lb: 0, ub: 2 });
+    const aC = sub.integer("a_C", { lb: 0, ub: 6 });
 
-    // Maximize shadow price collection
     const dualA = demandA.dual ?? 0;
     const dualB = demandB.dual ?? 0;
     const dualC = demandC.dual ?? 0;
-    sub.objective(maximize(expr`${dualA} * ${a_A} + ${dualB} * ${a_B} + ${dualC} * ${a_C}`));
-    sub.constraint(expr`45 * ${a_A} + 36 * ${a_B} + 16 * ${a_C} <= ${rollWidth}`);
+    sub.objective(maximize(expr`${dualA} * ${aA} + ${dualB} * ${aB} + ${dualC} * ${aC}`));
+    sub.constraint(expr`45 * ${aA} + 36 * ${aB} + 16 * ${aC} <= ${rollWidth}`);
 
     await sub.solve();
 
-    // Return the generated cutting pattern
     return {
       cost: 1,
       type: "Integer",
       coefficients: {
-        demand_A: Math.round(a_A.value ?? 0),
-        demand_B: Math.round(a_B.value ?? 0),
-        demand_C: Math.round(a_C.value ?? 0),
+        demand_A: Math.round(aA.value ?? 0),
+        demand_B: Math.round(aB.value ?? 0),
+        demand_C: Math.round(aC.value ?? 0),
       },
     };
   },
 });
 
-console.log("Optimal rolls needed:", result.objectiveValue); // 14
-console.log("Iterations executed:", result.iterations);
-console.log("Dynamic columns added:", result.columnsAdded);
+console.log("Optimal rolls:", result.objectiveValue); // 14
+console.log("Iterations:", result.iterations);
+console.log("Columns added:", result.columnsAdded);
 ```
 
-### Custom Pricing Algorithms (Graph / Dynamic Programming)
+### Pricing with a Custom Algorithm (`getDual`)
 
-Because `pricing` is a standard callback returning column definitions, you can solve the subproblem using any algorithm (e.g. Dijkstra, Bellman-Ford, or custom heuristics):
+Because `pricing` is a standard callback receiving `PricingContext`, you can also solve the pricing problem directly in TypeScript (e.g., via combinatorial search, dynamic programming, or shortest-path routines) instead of constructing a subproblem `Model`:
 
 ```typescript
-const result = await master.solveColumnGeneration({
-  pricing: async ({ getDual }) => {
-    // Solve subproblem with specialized custom graph algorithm
-    const route = solveSpecializedShortestPath(getDual);
-    if (!route) return null;
-
-    return {
-      cost: route.distance,
-      type: "Integer",
-      coefficients: route.visitedCustomers,
-    };
+const customResult = await master.solveColumnGeneration({
+  maxIterations: 100,
+  reducedCostTolerance: 1e-6,
+  pricing: ({ getDual }) => {
+    const dA = getDual("demand_A");
+    const dB = getDual("demand_B");
+    const dC = getDual("demand_C");
+
+    // Search feasible patterns (45*aA + 36*aB + 16*aC <= rollWidth) for negative reduced cost (1 - dualSum < -1e-6)
+    let bestDualSum = 1 + 1e-6;
+    let best: { demand_A: number; demand_B: number; demand_C: number } | null = null;
+    for (let aA = 0; 45 * aA <= rollWidth; aA++) {
+      for (let aB = 0; 45 * aA + 36 * aB <= rollWidth; aB++) {
+        for (let aC = 0; 45 * aA + 36 * aB + 16 * aC <= rollWidth; aC++) {
+          const dualSum = dA * aA + dB * aB + dC * aC;
+          if (dualSum > bestDualSum) {
+            bestDualSum = dualSum;
+            best = { demand_A: aA, demand_B: aB, demand_C: aC };
+          }
+        }
+      }
+    }
+    return best ? { cost: 1, type: "Integer", coefficients: best } : null;
   },
 });
 ```
@@ -165,33 +166,29 @@ const result = await master.solveColumnGeneration({
 
 ## Benders Decomposition (`solveBenders`)
 
-Benders Decomposition partitions the problem into:
-- **Master Problem**: Contains complicating variables (e.g., 0-1 facility opening decisions $y$) and an auxiliary variable $\theta \ge 0$ representing estimated subproblem costs.
-- **Subproblem**: Solves operational decisions given fixed master values $y^*$, feeding back **Optimality Cuts** to the master.
+`master.solveBenders(options)` partitions a problem into a **Master Problem** (holding first-stage or complicating variables) and a **Subproblem** evaluated at each master candidate solution to generate **Optimality Cuts** or **Feasibility Cuts**.
 
-### Recommended: Automated Cut Generation with `sub.link()`
+### Automatic Cut Generation (`sub.link()`)
 
-Return the subproblem `Model` from your callback and register linking constraints with `sub.link(...)`. WaSHI automatically manages $\theta$, evaluates master candidate values, extracts duals, and injects Benders optimality cuts:
+Return a continuous LP subproblem `Model` from `subproblem` and declare cross-model constraints via `sub.link(...)`. WaSHI automatically manages the auxiliary cost estimator variable $\theta$, substitutes master candidate values, extracts subproblem duals, and adds Benders cuts until convergence:
 
 ```typescript
 import { Model, expr, minimize } from "@ohtaman/washi";
 
-// 1. Master problem: Facility location decisions
+// 1. Master problem: binary facility opening decisions
 const master = new Model("FacilityMaster");
 const y1 = master.binary("open_F1");
 const y2 = master.binary("open_F2");
 
-// Objective: Fixed facility costs (theta is managed automatically)
+// Fixed opening costs (theta for operational subproblem cost is managed automatically)
 master.objective(minimize(expr`100 * ${y1} + 120 * ${y2}`));
-// Minimal aggregate capacity requirement
-master.constraint(expr`50 * ${y1} + 60 * ${y2} >= 75`, "capacity_check");
+master.constraint(expr`50 * ${y1} + 60 * ${y2} >= 75`, "total_capacity_floor");
 
-// 2. Solve automatically with master.solveBenders()
+// 2. Solve with automatic Benders cut generation
 const result = await master.solveBenders({
   gapTolerance: 1e-4,
   subproblem: () => {
-    // Operational dispatch subproblem
-    const sub = new Model("TransportSubproblem");
+    const sub = new Model("DispatchSubproblem");
     const x11 = sub.continuous("x_11", { lb: 0 });
     const x12 = sub.continuous("x_12", { lb: 0 });
     const x13 = sub.continuous("x_13", { lb: 0 });
@@ -205,195 +202,66 @@ const result = await master.solveBenders({
       )
     );
 
-    // Customer demand constraints
     sub.constraint(expr`${x11} + ${x21} >= 20`, "demand_C1");
     sub.constraint(expr`${x12} + ${x22} >= 25`, "demand_C2");
     sub.constraint(expr`${x13} + ${x23} >= 30`, "demand_C3");
 
-    // Link subproblem flows with master decisions y1, y2 via linking constraints
+    // Link subproblem dispatch flows to master binary variables y1, y2
     sub.link(expr`${x11} + ${x12} + ${x13} <= 50 * ${y1}`);
     sub.link(expr`${x21} + ${x22} + ${x23} <= 60 * ${y2}`);
 
-    return sub; // Returning the model automatically generates cuts and manages theta
+    return sub;
   },
 });
 
 console.log("Optimal total cost:", result.objectiveValue); // 390
-console.log("Iterations:", result.iterations);
 console.log("Cuts added:", result.cutsAdded);
-console.log("Facility decisions:", {
-  F1: result.values.open_F1,
-  F2: result.values.open_F2,
-});
+console.log("Open facilities:", result.values);
 ```
 
-### Low-Level Control: Custom `BendersCut` Callback
+> [!NOTE]
+> **`theta` Lower Bound for Negative Subproblem Objectives**: When `sub.link(...)` is used without an explicit `theta` variable, WaSHI injects `__benders_theta` with default `lb: 0` (assuming non-negative subproblem costs). If your subproblem objective can take negative values (e.g., rebate or profit terms), declare `const theta = master.continuous("theta", { lb: -1e6 })`, include `+ ${theta}` in `master.objective(...)`, and pass `{ theta }` in `solveBenders(options)`.
+
+### Manual Cut Generation (`BendersCut` / Lazy Constraints)
 
-You can also construct Benders cuts manually by returning `BendersCut` objects:
+For combinatorial separation (such as lazy subtour elimination) or custom analytical cuts, return one `BendersCut` object, an array `BendersCut[]`, or `null` when converged:
 
 ```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+const master = new Model("ManualBenders");
+const y = master.binary("y");
+const theta = master.continuous("theta", { lb: 0 });
+master.objective(minimize(expr`40 * ${y} + ${theta}`));
+
 const result = await master.solveBenders({
+  theta,
   gapTolerance: 1e-4,
-  subproblem: async () => {
-    const open1 = y1.value ?? 0;
-    const open2 = y2.value ?? 0;
-    const estTheta = theta.value ?? 0;
-
-    const sub = new Model("TransportSubproblem");
-    // ...
-    await sub.solve();
+  subproblem: ({ getMasterValue }) => {
+    const yVal = getMasterValue(y);
+    const estTheta = getMasterValue(theta);
 
-    const actualCost = sub.objectiveValue!;
-    if (estTheta < actualCost - 1e-4) {
+    // Operational cost is 100 when y = 0, or 30 when y = 1
+    const actualSubCost = 100 - 70 * yVal;
+    if (estTheta < actualSubCost - 1e-4) {
       return {
-        kind: "optimality",
-        constraint: expr`${theta} - 50 * ${sub.solution!.duals.cap1} * ${y1} - 60 * ${sub.solution!.duals.cap2} * ${y2} >= ${rhs}`,
-        subproblemObjective: 100 * open1 + 120 * open2 + actualCost,
+        kind: "optimality", // or "feasibility" for lazy combinatorial cuts
+        constraint: expr`${theta} >= 100 - 70 * ${y}`,
+        subproblemObjective: 40 * yVal + actualSubCost,
       };
     }
     return null; // Converged
   },
 });
-```
 
----
-
-## Application Examples
-
-Two common applications of decomposition methods:
-
-### 1. Vehicle Routing Problem (CVRP) $\times$ Column Generation
-*(Full executable source: [`examples/node/13-vehicle-routing-column-generation.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/13-vehicle-routing-column-generation.ts))*
-
-* **Problem Structure**: Enumerating every feasible customer tour upfront produces a large number of variables.
-* **Column Generation Formulation**:
-  * **Master Problem**: Set covering model that selects the minimum number of vehicle routes such that each customer is served.
-  * **Pricing Subproblem**: Knapsack model that dynamically generates a capacity-feasible route (column) with negative reduced cost based on customer dual shadow prices.
-
-```typescript
-import { Model, expr, minimize, LinExpr, type Var } from "@ohtaman/washi";
-
-const vehicleCapacity = 8;
-const customers = [
-  { id: "C1", demand: 4 },
-  { id: "C2", demand: 3 },
-  { id: "C3", demand: 5 },
-  { id: "C4", demand: 2 },
-  { id: "C5", demand: 4 },
-];
-
-// 1. Master Problem: Customer coverage
-const master = new Model("CVRP_Master");
-const initialRoutes: Var[] = [];
-for (const cust of customers) {
-  initialRoutes.push(master.integer(`init_${cust.id}`, { lb: 0, ub: 1 }));
-}
-master.objective(minimize(initialRoutes.reduce((acc, r) => acc.add(r), new LinExpr())));
-
-for (let i = 0; i < customers.length; i++) {
-  master.constraint(expr`${initialRoutes[i]} >= 1`, `visit_${customers[i].id}`);
-}
-const visitConstrs = master.constraints;
-
-// 2. Solve via Column Generation
-const result = await master.solveColumnGeneration({
-  finalizeAsMIP: true,
-  pricing: async () => {
-    const sub = new Model("RoutePricing");
-    const a: Record<string, Var> = {};
-    const obj = new LinExpr();
-
-    for (let i = 0; i < customers.length; i++) {
-      const cust = customers[i];
-      a[cust.id] = sub.binary(`v_${cust.id}`);
-      obj.addTerm(a[cust.id], visitConstrs[i].dual ?? 0);
-    }
-
-    sub.objective(maximize(obj));
-
-    // Capacity limit: sum(demand_i * a_i) <= vehicleCapacity
-    const load = customers.reduce((acc, c) => acc.add(a[c.id].mul(c.demand)), new LinExpr());
-    sub.constraint(expr`${load} <= ${vehicleCapacity}`);
-
-    await sub.solve();
-
-    const coefficients: Record<string, number> = {};
-    for (const cust of customers) {
-      coefficients[`visit_${cust.id}`] = Math.round(a[cust.id].value ?? 0);
-    }
-
-    return {
-      cost: 1,
-      type: "Integer",
-      coefficients,
-    };
-  },
-});
-
-console.log("Optimal fleet size:", result.objectiveValue); // 3 vehicles
+console.log(result.objectiveValue); // 70 (y = 1, theta = 30)
 ```
 
-### 2. Traveling Salesperson Problem (TSP) $\times$ Benders Decomposition (Lazy Subtour Elimination)
-*(Full executable source: [`examples/node/14-traveling-salesperson-benders.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/14-traveling-salesperson-benders.ts))*
-
-* **Problem Structure**: Preventing isolated sub-loops (subtours) requires Subtour Elimination Constraints (SECs), which grow as $O(2^n)$ constraints for $n$ cities.
-* **Benders Decomposition Formulation**:
-  * **Master Problem**: Solves the relaxed assignment problem (each city has 1 incoming and 1 outgoing edge).
-  * **Subproblem**: Evaluates the candidate tour graph for disconnected components. If isolated subtours exist, it lazily injects a Benders feasibility cut ($\sum_{i,j \in S} x_{ij} \le |S| - 1$) cutting off that cycle.
-
-```typescript
-import { Model, expr, minimize, LinExpr, type Var } from "@ohtaman/washi";
-
-const n = cities.length;
-const master = new Model("TSP_Master");
-const x: Record<string, Var> = {};
-const objExpr = new LinExpr();
-
-for (let i = 0; i < n; i++) {
-  for (let j = 0; j < n; j++) {
-    if (i !== j) {
-      const v = master.binary(`x_${i}_${j}`);
-      x[`${i}_${j}`] = v;
-      objExpr.addTerm(v, dist(i, j));
-    }
-  }
-}
-master.objective(minimize(objExpr));
-
-// Degree constraints
-for (let i = 0; i < n; i++) {
-  const outE = new LinExpr();
-  const inE = new LinExpr();
-  for (let j = 0; j < n; j++) {
-    if (i !== j) {
-      outE.addTerm(x[`${i}_${j}`], 1);
-      inE.addTerm(x[`${j}_${i}`], 1);
-    }
-  }
-  master.constraint(expr`${outE} == 1`, `out_${i}`);
-  master.constraint(expr`${inE} == 1`, `in_${i}`);
-}
+---
 
-// Solve with Benders lazy subtour elimination
-const result = await master.solveBenders({
-  subproblem: () => {
-    const cycles = findCycles(n, (i, j) => (x[`${i}_${j}`].value ?? 0) > 0.5);
-    if (cycles.length === 1 && cycles[0].length === n) {
-      return null; // Single tour covers all cities
-    }
+## Related Examples & Formulation Tips
 
-    // Subtour detected: inject Benders feasibility cut for smallest cycle
-    const S = cycles.reduce((min, c) => (c.length < min.length ? c : min), cycles[0]);
-    const secExpr = new LinExpr();
-    for (const i of S) {
-      for (const j of S) {
-        if (i !== j) secExpr.addTerm(x[`${i}_${j}`], 1);
-      }
-    }
-    return {
-      kind: "feasibility",
-      constraint: expr`${secExpr} <= ${S.length - 1}`,
-    };
-  },
-});
-```
+- **Full Decomposition Walkthroughs**:
+  - [Vehicle Routing Problem (`solveColumnGeneration`)](../examples/vehicle-routing.md)
+  - [Traveling Salesperson Problem (`solveBenders` lazy subtour elimination)](../examples/traveling-salesperson.md)
+- **Formulation Tips**: See [Formulation Patterns & Optimization Tips](./formulation-tips.md#_5-decomposition-formulation-tips) for Set Covering (`>= 1`) vs. Set Partitioning (`== 1`), Price-and-Branch (`finalizeAsMIP`), and multi-cut separation.