@ohtaman/washi 0.4.0 → 0.6.0

package/docs/examples/traveling-salesperson.md

@@ -0,0 +1,173 @@
+# Traveling Salesperson Problem (TSP via Benders Decomposition)
+
+| Problem Class | Solver | Key APIs | Links |
+| :--- | :--- | :--- | :--- |
+| Combinatorial OR / Benders | HiGHS (default) | `m.solveBenders()`, `subproblem`, `m.binary()`, `m.constraint()`, `expr` | <ul><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/14-traveling-salesperson-benders.ts">Source Code</a></li><li><a href="../guide/decomposition.md">Decomposition Guide</a></li></ul> |
+
+The **Traveling Salesperson Problem (TSP)** seeks the shortest closed tour that visits every city in a given set once and returns to the starting city.
+
+In the **Dantzig-Fulkerson-Johnson (DFJ)** formulation, preventing disconnected cycles (**subtours**) requires subtour elimination constraints for every non-empty proper subset of cities $S \subset V$:
+
+$$\sum_{i \in S, j \notin S} x_{ij} \ge 1 \quad \forall S \subset V, \; 2 \le |S| \le |V| - 1$$
+
+Because there are $2^n - 2$ subsets, enumerating all subtour constraints upfront is impractical as $n$ grows. With **Benders Decomposition (Lazy Constraint Separation)**, constraints are added only when violated:
+1. **Master Problem**: Solves the degree-assignment relaxation (each city has 1 incoming and 1 outgoing edge).
+2. **Separation Subproblem**: Inspects the candidate solution graph. If disconnected cycles exist, it adds a **Benders Feasibility Cut** eliminating the smallest cycle and resolves until a single connected tour is obtained.
+
+## Problem Inputs
+
+We consider **5 cities** on a 2D Euclidean coordinate grid:
+
+| City | Coordinates $(x, y)$ |
+| :--- | :---: |
+| **City A (0)** | $(0, 0)$ |
+| **City B (1)** | $(1, 0)$ |
+| **City C (2)** | $(1, 2)$ |
+| **City D (3)** | $(0, 2)$ |
+| **City E (4)** | $(0.5, 3)$ |
+
+## Implementation in WaSHI
+
+<CodeRunner>
+
+```typescript
+import { Model, expr, minimize, LinExpr } from "@ohtaman/washi";
+
+async function runTSP() {
+  const cities = [
+    { name: "A", x: 0, y: 0 },
+    { name: "B", x: 1, y: 0 },
+    { name: "C", x: 1, y: 2 },
+    { name: "D", x: 0, y: 2 },
+    { name: "E", x: 0.5, y: 3 },
+  ];
+  const n = cities.length;
+
+  function dist(i, j) {
+    const dx = cities[i].x - cities[j].x;
+    const dy = cities[i].y - cities[j].y;
+    return Math.hypot(dx, dy);
+  }
+
+  // 1. Master Problem: Degree assignment relaxation
+  const master = new Model("TSP_BendersMaster");
+  const x = {};
+
+  for (let i = 0; i < n; i++) {
+    x[i] = {};
+    for (let j = 0; j < n; j++) {
+      if (i !== j) {
+        x[i][j] = master.binary(`x_${i}_${j}`);
+      }
+    }
+  }
+
+  // Objective: Minimize total tour distance
+  let totalDistance = new LinExpr();
+  for (let i = 0; i < n; i++) {
+    for (let j = 0; j < n; j++) {
+      if (i !== j) {
+        totalDistance = totalDistance.add(x[i][j].mul(dist(i, j)));
+      }
+    }
+  }
+  master.objective(minimize(totalDistance));
+
+  // Each city must have 1 outgoing and 1 incoming edge
+  for (let i = 0; i < n; i++) {
+    let outExpr = new LinExpr();
+    let inExpr = new LinExpr();
+    for (let j = 0; j < n; j++) {
+      if (i !== j) {
+        outExpr = outExpr.add(x[i][j]);
+        inExpr = inExpr.add(x[j][i]);
+      }
+    }
+    master.constraint(expr`${outExpr} == 1`, `out_${i}`);
+    master.constraint(expr`${inExpr} == 1`, `in_${i}`);
+  }
+
+  console.log("Solving TSP with Benders lazy subtour elimination...");
+
+  // 2. Solve via Benders Decomposition
+  let cutCounter = 0;
+  const result = await master.solveBenders({
+    subproblem: () => {
+      // Find active directed edges in the master solution
+      const succ = {};
+      for (let i = 0; i < n; i++) {
+        for (let j = 0; j < n; j++) {
+          if (i !== j && Math.round(x[i][j].value ?? 0) === 1) {
+            succ[i] = j;
+          }
+        }
+      }
+
+      // Trace connected cycles
+      const visited = new Set();
+      const cycles = [];
+      for (let i = 0; i < n; i++) {
+        if (!visited.has(i)) {
+          const cycle = [];
+          let curr = i;
+          while (!visited.has(curr)) {
+            visited.add(curr);
+            cycle.push(curr);
+            curr = succ[curr];
+          }
+          cycles.push(cycle);
+        }
+      }
+
+      // If more than 1 cycle, subtours exist: inject Benders feasibility cut
+      if (cycles.length > 1) {
+        const smallestCycle = cycles.reduce((min, c) => (c.length < min.length ? c : min));
+        const S = new Set(smallestCycle);
+        cutCounter++;
+        console.log(`Subtour detected: [${smallestCycle.map(k => cities[k].name).join(" -> ")}]. Adding Benders cut #${cutCounter}.`);
+
+        let cutLhs = new LinExpr();
+        for (const i of S) {
+          for (let j = 0; j < n; j++) {
+            if (!S.has(j)) {
+              cutLhs = cutLhs.add(x[i][j]);
+            }
+          }
+        }
+
+        return {
+          kind: "feasibility",
+          constraint: expr`${cutLhs} >= 1`,
+          name: `subtour_cut_${cutCounter}`,
+        };
+      }
+
+      return null; // Single connected tour found
+    },
+  });
+
+  console.log(`\nStatus: ${result.status}`);
+  console.log(`Optimal Tour Distance: ${result.objectiveValue?.toFixed(3)}`);
+  console.log(`Total Benders Cuts Added: ${result.cutsAdded}`);
+  console.log(`Iterations: ${result.iterations}`);
+
+  console.log("\nOptimal tour edges:");
+  for (let i = 0; i < n; i++) {
+    for (let j = 0; j < n; j++) {
+      if (i !== j && (result.values[`x_${i}_${j}`] ?? 0) > 0.5) {
+        console.log(`  ${cities[i].name} -> ${cities[j].name} (distance: ${dist(i, j).toFixed(3)})`);
+      }
+    }
+  }
+}
+
+runTSP();
+```
+
+</CodeRunner>
+
+## Notes
+
+- **Lazy Subtour Elimination**: The master problem starts with only the $2n$ degree constraints, and subtour elimination cuts are added on demand when disconnected cycles appear in the master solution.
+- **Separation Callback**: The `subproblem` callback reads candidate edge values via `x[i][j].value`, traces connected components in $O(n)$, and returns `{ kind: "feasibility", constraint: ... }` when multiple cycles are present.
+- **Termination Condition**: Returning `null` from `subproblem` indicates that no violated subtour constraints remain.

package/docs/examples/unsat-core.md

@@ -0,0 +1,64 @@
+# Conflict Diagnosis (Unsat Core)
+
+| Problem Class | Solver | Key APIs | Links |
+| :--- | :--- | :--- | :--- |
+| Infeasibility Diagnosis / Unsat Core | Z3 (`@ohtaman/washi/solvers/z3`) | `m.integer()`, `m.continuous()`, `m.constraint()`, `expr`, `m.check()`, `m.conflicts` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=conflict_diagnosis_unsat">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts">Source Code</a></li></ul> |
+
+When business rules, budgets, and operational policies grow complex, constraints inevitably conflict. Traditional solvers simply report "Infeasible", leaving engineers to guess which of hundreds of rules caused the contradiction.
+
+This example shows how to isolate the conflicting constraint subset using Z3 Unsat Core extraction.
+
+## The Conflicting Scenario
+
+A tech team is staffing a customer project:
+1. Each engineer costs $8,000 against the project budget (`budget_limit`).
+2. The customer requires rush delivery (`rush_required`).
+3. Rush delivery mandates at least 8 engineers (`rush_staffing_rule`).
+4. The board has imposed a strict budget cap of $50,000 (`strict_board_budget_cap`).
+5. Labor law requires at least 1 employee on staff (`minimum_one_employee`).
+
+Notice that:
+
+$$8 \text{ engineers} \times \$8,000 = \$64,000 > \$50,000 \text{ budget!}$$
+
+## Implementation in WaSHI
+
+<CodeRunner preset="conflict_diagnosis_unsat">
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
+
+async function diagnoseConflicts() {
+  const m = new Model({ name: "ConflictDiagnosis", solver: "z3" });
+
+  const engineers = m.integer("engineers", { lb: 0, ub: 20 });
+  const budget = m.continuous("budget", { lb: 0, ub: 100000 });
+  const rushDelivery = m.bool("rushDelivery");
+
+  // Rule 1: Each engineer costs $8,000
+  m.constraint(expr`8000 * ${engineers} <= ${budget}`, "budget_limit");
+
+  // Rule 2: Customer requires rush delivery
+  m.constraint(rushDelivery, "rush_required");
+
+  // Rule 3: Rush delivery requires at least 8 engineers
+  m.constraint(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
+
+  // Rule 4: Board budget cap of $50,000 (Conflict!)
+  m.constraint(expr`${budget} <= 50000`, "strict_board_budget_cap");
+
+  // Rule 5: Innocent bystander rule
+  m.constraint(expr`${engineers} >= 1`, "minimum_one_employee");
+
+  // Run diagnosis
+  const res = await m.check({ solver: "z3" });
+
+  console.log(`Status: ${res.status}`);
+  console.log("Conflicting Constraints (conflicts):", m.conflicts);
+}
+
+diagnoseConflicts();
+```
+
+</CodeRunner>

package/docs/examples/vehicle-routing.md

@@ -0,0 +1,206 @@
+# Capacitated Vehicle Routing Problem (CVRP, 50 Customers via Column Generation)
+
+| Problem Class | Solver | Key APIs | Links |
+| :--- | :--- | :--- | :--- |
+| Combinatorial OR / Dantzig-Wolfe | HiGHS (default) | `m.solveColumnGeneration()`, `pricing`, `sum()`, `m.binary()`, `m.constraint()`, `expr` | <ul><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/13-vehicle-routing-column-generation.ts">Source Code</a></li><li><a href="../guide/decomposition.md">Decomposition Guide</a></li></ul> |
+
+The **Capacitated Vehicle Routing Problem (CVRP)** determines the minimum number of delivery vehicles needed to visit a set of customers, subject to vehicle cargo capacity, maximum customer stops per shift, and route duration limits.
+
+In a monolithic MIP formulation, enumerating all possible customer combinations and visit sequences leads to $O(2^n)$ binary variables. With **Column Generation (Dantzig-Wolfe Decomposition)**, routes are generated on demand:
+1. **Restricted Master Problem (RMP)**: Solves a set partitioning problem that selects a subset of candidate routes so that every customer is visited once.
+2. **Pricing Subproblem**: Uses the dual values (shadow prices) from the master LP relaxation to construct improving routes with negative reduced cost ($\bar{c} = 1 - \sum \pi_i < 0$) via cheapest insertion and 2-opt local search.
+
+## Problem Inputs
+
+We consider a distribution network with a central depot at $(0, 0)$ and **50 customer locations**:
+
+- **Vehicle Cargo Capacity**: At most **10 units** per vehicle.
+- **Maximum Stops**: At most **4 customers** per route.
+- **Maximum Shift Duration**: At most **200 minutes** (transit time + service time) per route.
+- **Transit & Service Times**: Euclidean distances between nodes (1 unit = 1 minute) plus **10 minutes** of unloading service time per customer.
+
+## Implementation in WaSHI
+
+<CodeRunner>
+
+```typescript
+import { Model, expr, minimize, sum } from "@ohtaman/washi";
+
+// --- Extracted Routing Helpers ---
+
+// 2-opt local search to eliminate crossing paths in a tour
+function optimize2Opt(tour, dist) {
+  let best = [...tour];
+  let improved = true;
+
+  while (improved) {
+    improved = false;
+    for (let i = 1; i < best.length - 2; i++) {
+      for (let j = i + 1; j < best.length - 1; j++) {
+        const dCurrent = dist(best[i - 1], best[i]) + dist(best[j], best[j + 1]);
+        const dSwap = dist(best[i - 1], best[j]) + dist(best[i], best[j + 1]);
+        if (dSwap < dCurrent) {
+          best = [...best.slice(0, i), ...best.slice(i, j + 1).reverse(), ...best.slice(j + 1)];
+          improved = true;
+        }
+      }
+    }
+  }
+  return best;
+}
+
+// Inserts a customer into the tour at the position that minimizes detour distance
+function insertCheapest(tour, id, dist) {
+  let bestPos = 1;
+  let minCost = Infinity;
+
+  for (let p = 1; p < tour.length; p++) {
+    const cost = dist(tour[p - 1], id) + dist(id, tour[p]) - dist(tour[p - 1], tour[p]);
+    if (cost < minCost) {
+      minCost = cost;
+      bestPos = p;
+    }
+  }
+  return [...tour.slice(0, bestPos), id, ...tour.slice(bestPos)];
+}
+
+// Calculates transit time and total duration (transit + service) for a tour
+function calcRouteTime(tour, dist, serviceTimes) {
+  let travelTime = 0;
+  for (let i = 0; i < tour.length - 1; i++) {
+    travelTime += dist(tour[i], tour[i + 1]);
+  }
+  const serviceTime = tour.slice(1, -1).reduce((acc, id) => acc + (serviceTimes[id] ?? 0), 0);
+  return { travelTime, totalTime: travelTime + serviceTime };
+}
+
+// Pricing subproblem: Finds an improving route with negative reduced cost (1 - dualSum < 0)
+function findImprovingRoute(candidates, config) {
+  let bestRoute = null;
+  let minReducedCost = -1e-4;
+
+  for (const seed of candidates.slice(0, 15)) {
+    let tour = ["Depot", seed.id, "Depot"];
+    let load = seed.demand;
+    let dualSum = seed.dual;
+
+    for (const next of candidates) {
+      if (tour.includes(next.id)) continue;
+      if (load + next.demand > config.vehicleCapacity) continue;
+      if (tour.length - 2 >= config.maxStops) continue;
+
+      const candidateTour = optimize2Opt(insertCheapest(tour, next.id, config.dist), config.dist);
+      const { totalTime } = calcRouteTime(candidateTour, config.dist, config.serviceTimes);
+
+      if (totalTime <= config.maxRouteTime) {
+        tour = candidateTour;
+        load += next.demand;
+        dualSum += next.dual;
+      }
+    }
+
+    const reducedCost = 1 - dualSum;
+    if (reducedCost < minReducedCost) {
+      minReducedCost = reducedCost;
+      bestRoute = tour;
+    }
+  }
+  return bestRoute;
+}
+
+// --- Main CVRP via Column Generation ---
+
+async function runCVRP() {
+  const vehicleCapacity = 10;
+  const maxStops = 4;
+  const maxRouteTime = 200; // minutes
+
+  // Central depot and 50 customer locations
+  const depot = { id: "Depot", x: 0, y: 0 };
+  const customers = Array.from({ length: 50 }, (_, i) => {
+    const angle = i * 2.4;
+    const radius = 15 + (i % 5) * 8;
+    return {
+      id: `C${i + 1}`,
+      x: Math.round(Math.cos(angle) * radius),
+      y: Math.round(Math.sin(angle) * radius),
+      demand: 1 + (i % 4),
+      serviceTime: 10,
+    };
+  });
+
+  const nodes = Object.fromEntries([depot, ...customers].map((n) => [n.id, n]));
+  const dist = (a, b) =>
+    Math.round(Math.hypot(nodes[a].x - nodes[b].x, nodes[a].y - nodes[b].y));
+  const serviceTimes = Object.fromEntries(customers.map((c) => [c.id, c.serviceTime]));
+
+  const routeConfig = { dist, serviceTimes, vehicleCapacity, maxStops, maxRouteTime };
+
+  // 1. Build Restricted Master Problem (RMP)
+  const master = new Model("CVRP_FleetMaster");
+
+  // Initial naive routes: 1 dedicated vehicle per customer
+  const initialRoutes = customers.map((c) => master.binary(`route_init_${c.id}`));
+  master.objective(minimize(sum(initialRoutes)));
+
+  // Each customer must be visited by exactly 1 vehicle
+  for (let i = 0; i < customers.length; i++) {
+    master.constraint(expr`${initialRoutes[i]} == 1`, `visit_${customers[i].id}`);
+  }
+  const visitConstrs = master.constraints;
+
+  console.log(`Initial state: 50 naive single-customer routes (50 vehicles).`);
+  console.log("Solving via Column Generation with dual-directed heuristic pricing...");
+
+  // 2. Solve via Column Generation
+  const result = await master.solveColumnGeneration({
+    finalizeAsMIP: true,
+    pricing: async () => {
+      // 1. Sort customers by shadow price (dual profit) descending
+      const candidates = customers
+        .map((c, i) => ({ id: c.id, demand: c.demand, dual: visitConstrs[i].dual ?? 0 }))
+        .filter((c) => c.dual > 0)
+        .sort((a, b) => b.dual - a.dual);
+
+      // 2. Solve pricing subproblem: find route with negative reduced cost (dualSum > 1)
+      const bestRoute = findImprovingRoute(candidates, routeConfig);
+      if (!bestRoute) return null; // No improving column found
+
+      // 3. Propose new column to Restricted Master Problem
+      const { travelTime, totalTime } = calcRouteTime(bestRoute, dist, serviceTimes);
+      const coefficients = {};
+      for (const id of bestRoute.slice(1, -1)) {
+        coefficients[`visit_${id}`] = 1;
+      }
+
+      return {
+        cost: 1,
+        type: "Binary",
+        coefficients,
+        meta: { tour: bestRoute, travelTime, totalTime },
+      };
+    },
+  });
+
+  console.log(`\nStatus: ${result.status}`);
+  console.log(`Fleet Size: ${Math.round(result.objectiveValue ?? 0)} vehicles (heuristic column generation)`);
+  console.log(`Total Columns Generated: ${result.columnsAdded}`);
+
+  console.log("\nSample routes selected in fleet:");
+  const activeRoutes = result.generatedColumns.filter((c) => (c.variable.value ?? 0) > 0.5);
+  for (const r of activeRoutes.slice(0, 5)) {
+    const meta = r.proposal.meta;
+    console.log(`  ${meta?.tour.join(" -> ")} (Transit: ${meta?.travelTime}m, Total: ${meta?.totalTime}m)`);
+  }
+}
+
+runCVRP();
+```
+
+</CodeRunner>
+
+## Notes
+
+- **Master Problem and Pricing Separation**: The master problem solves the LP relaxation and final set-partitioning MIP, while the `pricing` callback searches for negative-reduced-cost routes using cheapest insertion and 2-opt local search.
+- **Dual Value Access**: Dual values from the master LP relaxation are read from `visitConstrs[i].dual` to prioritize customers with higher shadow prices during route construction.
+- **Route Metadata**: Each proposed column attaches `{ tour, travelTime, totalTime }` under `meta`, allowing the ordered stop sequence to be inspected from `result.generatedColumns` after the solve completes.