@ohtaman/washi 0.5.0 → 0.7.0

package/docs/guide/constraints.md

@@ -1,17 +1,17 @@
 # Constraints (`m.constraint` & `m.indicator`)
 
 Constraints restrict the feasible solution space of your mathematical or logical model.
-In WaSHI, both linear arithmetic constraints and propositional SMT formulas are registered using **`m.constraint()`**:
+In WaSHI, both linear arithmetic constraints and propositional logic formulas are registered using **`m.constraint()`**:
 
 ```typescript
-m.constraint(expr`${desks} + 2 * ${chairs} <= 40`, "wood_limit");
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
 ```
 
 ---
 
-## ✍️ Algebraic Linear Constraints (`expr`)
+## Algebraic Linear Constraints (`expr`)
 
-The `expr` tagged template literal syntax allows writing equations and inequalities with natural mathematical notation:
+The `expr` tagged template literal allows writing equations and inequalities with standard mathematical notation:
 
 ```typescript
 import { Model, expr } from "@ohtaman/washi";
@@ -30,13 +30,15 @@ m.constraint(expr`3 * ${x} + ${y} >= 20`, "min_demand");
 m.constraint(expr`${x} + ${y} == 30`, "exact_quota");
 ```
 
+`m.constraint()` returns the registered `Constraint` (or `BoolExpr` for logical formulas), or an array when passed a batch array.
+
 ### Supported Comparison Operators
 - `<=`: Upper bound constraint
 - `>=`: Lower bound constraint
 - `==` or `=`: Exact equality constraint
 
 ### Batch Registration
-You can pass an array of constraints to `m.constraint([...])` to register them transactionally in a single call:
+Pass an array of constraints to `m.constraint([...])` to register them transactionally in a single call:
 
 ```typescript
 m.constraint([expr`${x} <= 10`, expr`${y} <= 20`]);
@@ -44,50 +46,51 @@ m.constraint([expr`${x} <= 10`, expr`${y} <= 20`]);
 
 ---
 
-## 🏷️ Naming Constraints
+## Naming Constraints
 
-Every constraint can be given a unique, descriptive name as the second argument of `m.constraint(c, name)`:
+Pass a unique, descriptive name as the second argument of `m.constraint(c, name)`:
 
 ```typescript
 m.constraint(expr`${x} + ${y} <= 100`, "budget_cap");
 ```
 
 ### Why Name Constraints?
-1. **Model Inspection (`m.toLpString()`)**: Exported CPLEX LP strings retain these descriptive names (sanitized if needed) so you can inspect the exact generated formulation.
-2. **Conflict Diagnosis (`conflicts` / `unsatCore`)**: When constraints contradict each other, Z3 `m.check()` returns the exact constraint names forming the conflicting subset.
+1. **Model Inspection (`m.toLpString()`)**: Exported CPLEX LP strings retain these descriptive names (sanitized if needed) so you can inspect the generated formulation.
+2. **Conflict Diagnosis (`conflicts` / `unsatCore`)**: When constraints contradict each other, `m.check()` returns the conflicting constraint names (via built-in HiGHS elastic relaxation or Z3 `unsatCore`).
 3. **Direct Lookup (`m.getConstraintByName()`)**: Retrieve a constraint by name after solving to inspect its `dual` or `slack` value.
 
 ---
 
-## 🔁 Adding Constraints over Iterables & Sums
+## Aggregated Constraints (`sum` & `dot`)
 
-Use `sum()` or `dot()` inside `expr` to express linear aggregations cleanly:
+Use `sum(...)` and `dot(..., ...)` directly inside `expr` to express linear aggregations over arrays and dictionaries cleanly:
 
 ```typescript
-import { Model, sum, expr } from "@ohtaman/washi";
+import { Model, expr } from "@ohtaman/washi";
 
-const items = ["A", "B", "C"];
+const m = new Model();
+const items = ["A", "B", "C"] as const;
 const weights = { A: 5, B: 10, C: 15 };
 const selected = m.binary(items);
 
+// Select at most 2 items
+m.constraint(expr`sum(${selected}) <= 2`, "max_items");
+
 // Total weight cannot exceed capacity 25
-m.constraint(
-  expr`${sum(items, (i) => selected[i].mul(weights[i]))} <= 25`,
-  "capacity_limit"
-);
+m.constraint(expr`dot(${weights}, ${selected}) <= 25`, "capacity_limit");
 ```
 
 ---
 
-## 🎯 Conditional / Indicator Constraints (`m.indicator`)
+## Conditional / Indicator Constraints (`m.indicator`)
 
-When a linear constraint should only take effect when a binary decision variable is active (`1` or `0`), use `m.indicator()`:
+When a linear constraint should only take effect when a binary decision variable (`m.binary()`) equals `1` (or `0`), use `m.indicator()`:
 
 ```typescript
 const useDiscount = m.binary("use_discount");
 const cartTotal = m.continuous("cart_total", { lb: 0, ub: 10_000 });
 
-// If useDiscount == 1, then cartTotal >= 100
+// If useDiscount == 1, enforce cartTotal >= 100
 // WaSHI automatically derives a safe, tight Big-M from the variable bounds
 m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
   activeValue: 1,
@@ -97,16 +100,16 @@ m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
 
 ### Safe Automatic Big-M Derivation & Bounds
 
-When `options.M` is omitted, WaSHI automatically derives a safe, minimal Big-M value from the finite variable bounds:
+When `options.M` is omitted, WaSHI automatically derives a minimal valid Big-M value from finite variable bounds (`lb` and `ub`):
 - For `<=` constraints, variables with positive coefficients require finite upper bounds (`ub`), and negative coefficients require finite lower bounds (`lb`).
 - For `>=` constraints, variables with positive coefficients require finite lower bounds (`lb`), and negative coefficients require finite upper bounds (`ub`).
-- For `==` constraints, safe bounds are derived separately for both the `<=` and `>=` directions (generating `name_le` and `name_ge`).
+- For `==` constraints, bounds are derived separately for both the `<=` and `>=` directions (generating `name_le` and `name_ge`).
 
-If any referenced variable lacks the required finite bounds, `m.indicator()` throws an actionable error prompting for finite bounds or an explicit `options.M`.
+If any referenced variable lacks the required finite bound, `m.indicator()` throws an error prompting for finite bounds or an explicit `options.M`.
 
-### Explicit Override & Numerical Stability
+### Explicit `M` Override
 
-You can override the derived Big-M by providing `{ M: number }`:
+You can override the derived Big-M by passing `{ M: number }`:
 
 ```typescript
 m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
@@ -116,15 +119,13 @@ m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
 ```
 
 > [!TIP]
-> **Numerical Stability vs. Correctness**:
-> An $M$ value that is too small can inadvertently cut off valid solutions. Conversely, an excessively large $M$ (e.g., $10^9$) causes poor matrix conditioning and numerical instability in MIP solvers.
-> By setting explicit, realistic variable bounds (`lb` and `ub`), WaSHI derives the tightest possible safe Big-M automatically.
+> **Prefer Finite Variable Bounds Over Arbitrary Large `M`**: An $M$ value that is too small can cut off valid feasible solutions, whereas an excessively large $M$ (e.g., $10^9$) degrades numerical conditioning in MIP solvers. Setting realistic `lb` and `ub` bounds on variables lets WaSHI compute the tightest safe Big-M automatically.
 
 ---
 
-## 🧠 Propositional Logic & SMT Constraints (`BoolVar`, `and`, `or`, `not`, `implies`, `xor`)
+## Propositional Logic & SMT Constraints (`BoolVar`, `and`, `or`, `not`, `implies`, `xor`)
 
-When solving with the **Z3** SMT engine (`@ohtaman/washi/solvers/z3`), you can combine propositional boolean variables (`m.bool()`) and linear constraints (`Constraint`) using first-class logical operators:
+WaSHI provides first-class logical operators to combine propositional boolean variables (`m.bool()`) and linear constraints (`Constraint`). Logical formulas are solved natively by the **Z3** SMT adapter (`@ohtaman/washi/solvers/z3`) and automatically linearized to 0-1 MIP constraints on **HiGHS** and **GLPK**:
 
 ```typescript
 import { Model, expr, and, or, not, implies, xor } from "@ohtaman/washi";
@@ -133,14 +134,14 @@ import "@ohtaman/washi/solvers/z3";
 const m = new Model({ solver: "z3" });
 const isAdmin = m.bool("isAdmin");
 const hasMfa = m.bool("hasMfa");
-const Clearance = m.integer("clearance", { lb: 0, ub: 5 });
+const clearance = m.integer("clearance", { lb: 0, ub: 5 });
 
 // Method syntax on BoolVar / BoolOp:
 m.constraint(isAdmin.implies(hasMfa), "admin_requires_mfa");
 
 // Mixing boolean propositions with linear arithmetic comparisons:
 m.constraint(
-  implies(isAdmin, expr`${Clearance} >= 4`),
+  implies(isAdmin, expr`${clearance} >= 4`),
   "admin_clearance_level"
 );
 
@@ -154,24 +155,29 @@ m.constraint(and(or(isAdmin, hasMfa), not(xor(isAdmin, hasMfa))), "policy");
 | :--- | :--- | :--- |
 | **Trigger variable** | Numeric `Binary` variable (`m.binary()`) | `BoolVar` (`m.bool()`), `BoolOp`, or `Constraint` |
 | **Consequent** | Linear `Constraint` (`<=`, `>=`, `==`) | `BoolVar`, `BoolOp`, or linear `Constraint` |
-| **Target Solvers** | **All MIP/LP solvers** (HiGHS, GLPK, Z3) via Big-M linearization | **Z3 SMT solver** (`capabilities.supportsSMT: true`) |
-| **Best For** | Operations research & MIP optimization with an objective (`m.solve()`) | Rule engines, policy verification, and SMT feasibility (`m.check()`) |
+| **Target Solvers** | **All MIP/LP solvers** (HiGHS, GLPK, Z3) via Big-M linearization | **All solvers** (HiGHS and GLPK via automatic 0-1 MIP linearization, Z3 natively) |
+| **Primary Use Case** | MIP optimization models with arithmetic binary variables (`m.solve()`) | Logical rule systems and SMT feasibility (`m.check()`) |
+
+> [!NOTE]
+> **General Inequality Antecedents in `implies()`**: On **Z3** (`solver: "z3"`), the antecedent `a` in `implies(a, b)` can be any linear inequality—for example, ``implies(expr`${clearance} >= 4`, hasMfa)`` using `clearance` and `hasMfa` above. On MIP solvers (**HiGHS** / **GLPK**), conditional constraints should use a `BoolVar` (`m.bool()`) antecedent or `m.indicator(binVar, constraint)` with a `Binary` trigger variable.
 
 ---
 
-## 📐 Dual Values, Shadow Prices & Lookups
+## Dual Values, Shadow Prices & Lookups
 
-For continuous Linear Programming (LP) problems, query the economic shadow price (`dual`) and surplus (`slack`) on each constraint:
+For continuous Linear Programming (LP) problems, query the shadow price (`dual`) and surplus (`slack`) on each constraint (returned by `m.constraint()` or looked up via `m.getConstraintByName()`):
 
 ```typescript
-m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood");
+const woodConstraint = m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood");
 
 await m.solve();
 
-const woodConstraint = m.getConstraintByName("wood");
-console.log("Shadow price (dual):", woodConstraint?.dual);
-console.log("Slack surplus:", woodConstraint?.slack);
+console.log("Shadow price (dual):", woodConstraint.dual);
+console.log("Slack surplus:", woodConstraint.slack);
 console.log("Total linear constraints:", m.numConstrs);
 ```
 
-For logical constraints registered with a name, use `m.getLogicalConstraintByName(name)` to look up the registered `LogicalConstraintItem`.
+For named logical constraints, use `m.getLogicalConstraintByName(name)` to look up the registered `LogicalConstraintItem`.
+
+> [!TIP]
+> For modeling techniques such as **soft constraints with slack variables** and **symmetry breaking**, see [Formulation Patterns & Optimization Tips](./formulation-tips.md#_3-constraint-design-numerical-conditioning).

package/docs/guide/decomposition.md

@@ -0,0 +1,267 @@
+# Decomposition Methods (`solveColumnGeneration` & `solveBenders`)
+
+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.
+
+| 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 exposes four lower-level primitives used internally by the decomposition orchestrators and available directly for custom algorithms:
+
+### 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
+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();
+
+console.log(c.dual);                    // Dual value / shadow price
+console.log(m.solution?.duals.capacity); // Lookup by constraint name
+```
+
+### 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 the continuous LP relaxation and populates m.solution.duals
+const status = await m.relax();
+console.log("LP relaxation bound:", m.objectiveValue);
+```
+
+### 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" / "Binary"
+  lb: 0,
+  cost: 1, // Objective coefficient
+  coefficients: {
+    capacity: 2,
+  },
+});
+```
+
+### 4. Dynamic Constraint Term Updates (`c.addTerm()` / `c.setTerm()`)
+Increment or overwrite the coefficient of a variable inside an existing linear constraint:
+
+```typescript
+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`)
+
+`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.
+
+### Pricing with a WaSHI Subproblem Model
+
+```typescript
+import { Model, expr, minimize, maximize } from "@ohtaman/washi";
+
+const rollWidth = 100;
+
+// 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 (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}`));
+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. Run Column Generation
+const result = await master.solveColumnGeneration({
+  finalizeAsMIP: true,
+  pricing: async () => {
+    // Knapsack pricing subproblem: find a pattern maximizing total dual value
+    const sub = new Model("KnapsackPricing");
+    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 });
+
+    const dualA = demandA.dual ?? 0;
+    const dualB = demandB.dual ?? 0;
+    const dualC = demandC.dual ?? 0;
+    sub.objective(maximize(expr`${dualA} * ${aA} + ${dualB} * ${aB} + ${dualC} * ${aC}`));
+    sub.constraint(expr`45 * ${aA} + 36 * ${aB} + 16 * ${aC} <= ${rollWidth}`);
+
+    await sub.solve();
+
+    return {
+      cost: 1,
+      type: "Integer",
+      coefficients: {
+        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:", result.objectiveValue); // 14
+console.log("Iterations:", result.iterations);
+console.log("Columns added:", result.columnsAdded);
+```
+
+### Pricing with a Custom Algorithm (`getDual`)
+
+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 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;
+  },
+});
+```
+
+---
+
+## Benders Decomposition (`solveBenders`)
+
+`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**.
+
+### Automatic Cut Generation (`sub.link()`)
+
+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: binary facility opening decisions
+const master = new Model("FacilityMaster");
+const y1 = master.binary("open_F1");
+const y2 = master.binary("open_F2");
+
+// Fixed opening costs (theta for operational subproblem cost is managed automatically)
+master.objective(minimize(expr`100 * ${y1} + 120 * ${y2}`));
+master.constraint(expr`50 * ${y1} + 60 * ${y2} >= 75`, "total_capacity_floor");
+
+// 2. Solve with automatic Benders cut generation
+const result = await master.solveBenders({
+  gapTolerance: 1e-4,
+  subproblem: () => {
+    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 });
+    const x21 = sub.continuous("x_21", { lb: 0 });
+    const x22 = sub.continuous("x_22", { lb: 0 });
+    const x23 = sub.continuous("x_23", { lb: 0 });
+
+    sub.objective(
+      minimize(
+        expr`3 * ${x11} + 4 * ${x12} + 2 * ${x13} + 4 * ${x21} + 2 * ${x22} + 3 * ${x23}`
+      )
+    );
+
+    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 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;
+  },
+});
+
+console.log("Optimal total cost:", result.objectiveValue); // 390
+console.log("Cuts added:", result.cutsAdded);
+console.log("Open facilities:", result.values);
+```
+
+> [!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)
+
+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: ({ getMasterValue }) => {
+    const yVal = getMasterValue(y);
+    const estTheta = getMasterValue(theta);
+
+    // 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", // or "feasibility" for lazy combinatorial cuts
+        constraint: expr`${theta} >= 100 - 70 * ${y}`,
+        subproblemObjective: 40 * yVal + actualSubCost,
+      };
+    }
+    return null; // Converged
+  },
+});
+
+console.log(result.objectiveValue); // 70 (y = 1, theta = 30)
+```
+
+---
+
+## Related Examples & Formulation Tips
+
+- **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.