@ohtaman/washi 0.5.0 → 0.7.0

package/docs/guide/expressions.md

@@ -2,7 +2,7 @@
 
 Mathematical expressions are linear or quadratic combinations of decision variables and numeric coefficients.
 
-In JavaScript and TypeScript—which do not support operator overloading—WaSHI provides the **unified tagged template literal (`expr`)**, **`sum()`**, and matrix/vector **`dot()`** to construct algebraic expressions without losing static type safety.
+In JavaScript and TypeScript—which do not support operator overloading—WaSHI provides the **unified tagged template literal (`expr`)**, **`sum()`**, and matrix/vector **`dot()`** to construct algebraic expressions with full static type safety.
 
 | Approach | Example | Infix readability | Type safety & IDE rename | Indexed variables (`flow[i][j]`) |
 | :--- | :--- | :--- | :--- | :--- |
@@ -12,9 +12,9 @@ In JavaScript and TypeScript—which do not support operator overloading—WaSHI
 
 ---
 
-## ✍️ Tagged Template Literal (`expr`)
+## Tagged Template Literal (`expr`)
 
-Similar to parameterized `sql` tagged templates, `expr` receives the static operator text (`+`, `-`, `*`, `^2`, `<=`, `>=`, `==`) separately from the interpolated `${...}` values (`Var`, `LinExpr`, `QuadExpr`, or finite `number`). Variables are bound by object reference rather than resolved by string name, avoiding naming collisions and preserving TypeScript type checking and IDE refactoring.
+Similar to parameterized `sql` tagged templates, `expr` receives static operator text (`+`, `-`, `*`, `^2`, `<=`, `>=`, `==`) separately from interpolated `${...}` values (`Var`, `LinExpr`, `QuadExpr`, or finite `number`). Variables are bound by object reference rather than resolved by string name, avoiding naming collisions and preserving TypeScript type checking and IDE refactoring.
 
 Use `expr` for both arithmetic expressions (`LinExpr | QuadExpr`) and relational constraints (`Constraint`):
 
@@ -37,44 +37,55 @@ const balanceConstraint = expr`${x} + 2 * ${y} <= 40`;
 
 ### Supported Syntax in `expr`
 - **Addition & Subtraction**: `${x} + ${y} - 5`
-- **Scalar Multiplication**: `4 * ${x}`, `${x} * 4`
+- **Scalar Multiplication & Division**: `4 * ${x}`, `${x} / 2`
 - **Variable Multiplication (Quadratic terms)**: `${x} * ${y}`, `2 * ${x} * ${x}`
 - **Powers & Exponentiation**: `${x}^2`, `${x}**2`
-- **Unary Negation**: `-${x} + 10`
+- **Unary Plus & Negation**: `-${x} + 10`, `+${x}`
 - **Parentheses**: `2 * (${x} + ${y})`
-- **Nested Expressions**: `expr` seamlessly interpolates variables, numbers, `sum()` results, and nested expressions.
+- **Aggregations (`sum` & `dot`)**: `sum(${xVec}) <= 100`, `dot(${costs}, ${xVec})`, `sum(${rows}, ${(r) => grid[r][col]})`
+- **Element-Wise Container Arithmetic**: `sum((${price} - ${cost}) * ${qty})`, `sum((${xVec} - ${target})^2)`, `dot(${price} - ${cost}, ${qty})`
+- **Nested Expressions**: `expr` interpolates variables, numbers, `Array` / `Record` containers (inside `sum` or `dot`), and nested `LinExpr` / `QuadExpr` objects.
 
 > [!NOTE]
 > For relational comparisons (`<=`, `>=`, `==`), `expr` (e.g., ``expr`${x} + 2 * ${y} <= 40` ``) returns a first-class `Constraint`.
-> For arithmetic expressions without comparison operators, `expr` uniformly handles linear and quadratic expressions (up to degree 2): if quadratic terms are present, `expr` returns a `QuadExpr`; otherwise, it returns a `LinExpr`. Polynomial terms of degree $> 2$ (e.g. ``${x} * ${y} * ${z}``, ``${x}^3``) and non-linear constraints (e.g. ``${x} * ${y} <= 10``) are rejected because standard MILP/LP/QP formulations only support linear constraints and quadratic objectives.
+> For arithmetic expressions without comparison operators, `expr` uniformly handles linear and quadratic expressions (up to degree 2): if quadratic terms are present, `expr` returns a `QuadExpr`; otherwise, it returns a `LinExpr`. Interpolated `Array` or `Record` containers must be reduced to a scalar via `sum(...)` or `dot(..., ...)`. Polynomial terms of degree $> 2$ (e.g., ``${x} * ${y} * ${z}``, ``${x}^3``) and non-linear constraints (e.g., ``${x} * ${y} <= 10``) throw an error because LP/MIP/QP formulations require linear constraints and at most quadratic objectives.
 
 ---
 
-## ⚡ High-Performance Summation (`sum`)
+## High-Performance Summation (`sum`)
 
-For iterating over large collections of variables or indices:
+Sum 1D or 2D `Array`, `Iterable`, or `Record` containers directly inside `` expr`sum(...)` `` or via the standalone `sum()` helper:
 
 ```typescript
-import { sum } from "@ohtaman/washi";
+import { expr, sum } from "@ohtaman/washi";
 
-const items = ["A", "B", "C"];
+const items = ["A", "B", "C"] as const;
 const weights = { A: 10, B: 20, C: 30 };
 const x = m.binary(items);
 
-// 1. Transform elements with a mapping callback:
+// 1. Direct Record or Array summation inside expr (no Object.values() needed):
+m.constraint(expr`sum(${x}) <= 2`, "max_selected");
+
+// 2. Element-wise arithmetic inside expr`sum(...)`:
+const weightedExpr = expr`sum(${weights} * ${x})`;
+
+// 3. Transform elements with a mapping callback (standalone or inside expr):
 const totalWeight = sum(items, (item) => x[item].mul(weights[item]));
 
-// 2. Direct array summation:
-const count = sum(Object.values(x));
+// 4. Standalone 1D/2D Record or Array summation:
+const count = sum(x);
 ```
 
-`sum()` runs in $O(N)$ linear time without AST overhead.
+`sum()` runs in $O(N)$ linear time without AST parsing overhead.
+
+> [!TIP]
+> **Avoid $O(N^2)$ `expr` Re-Assignment Inside Loops**: Because `LinExpr` and `expr` results are immutable, accumulating terms one by one via ``total = expr`${total} + ${x[i]}` `` inside a loop copies all previously accumulated terms on every iteration ($O(N^2)$ time and memory). Pass arrays or records to `sum(x)` or `dot(coeffs, x)` for $O(N)$ construction.
 
 ---
 
-## 🎯 Dot Product (`dot`)
+## Dot Product (`dot`)
 
-The `dot(a, b)` helper computes linear combinations of numeric coefficients (`number`) and variables or linear expressions (`Var | LinExpr`) in either operand order (`dot(coeffs, vars)` or `dot(vars, coeffs)`).
+The `dot(a, b)` helper (usable both inside `` expr`dot(${a}, ${b})` `` and as a standalone function `dot(a, b)`) computes linear combinations of numeric coefficients (`number`) and variables or linear expressions (`Var | LinExpr`) in either operand order (`dot(coeffs, vars)` or `dot(vars, coeffs)`).
 
 Supported 1D and 2D container shapes:
 - **1D Arrays**: `number[]` $\times$ `(Var | LinExpr)[]`
@@ -87,41 +98,74 @@ Mismatched array lengths, missing dictionary keys, or non-finite/non-linear leav
 
 ### 1D Vector Dot Product
 ```typescript
-import { dot } from "@ohtaman/washi";
+import { expr, dot } from "@ohtaman/washi";
 
 const profits = { desk: 30, chair: 50 };
-const vars = m.integer(["desk", "chair"]);
+const vars = m.integer(["desk", "chair"] as const);
 
-// Computes 30 * vars.desk + 50 * vars.chair
-const totalProfit = dot(profits, vars);
+// Computes 30 * vars.desk + 50 * vars.chair inside expr (or via standalone dot(profits, vars))
+const totalProfit = expr`dot(${profits}, ${vars})`;
 ```
 
-### 2D Matrix Dot Product
+### 2D Matrix Inner Product (Frobenius Inner Product)
 Works directly with 2D arrays (`m.continuous(rows, cols)`), nested dictionaries (`m.continuous(rowKeys, colKeys)`), or mixed 2D containers:
 
 ```typescript
-const factories = ["Tokyo", "Osaka"];
-const stores = ["StoreA", "StoreB"];
+const factories = ["Tokyo", "Osaka"] as const;
+const stores = ["StoreA", "StoreB"] as const;
 
 const costs = {
   Tokyo: { StoreA: 4, StoreB: 7 },
   Osaka: { StoreA: 8, StoreB: 3 },
 };
 
-const ship = m.continuous(factories, stores);
+const ship = m.continuous(factories, stores, { lb: 0 });
+
+// Total shipping cost across all routes (equivalent to expr`sum(${costs} * ${ship})`):
+const totalShippingCost = expr`dot(${costs}, ${ship})`;
+```
+
+> [!NOTE]
+> **2D `dot(A, B)` is the Frobenius Inner Product**: For 2D matrices or nested records, `dot(A, B)` computes the scalar **Frobenius inner product** $\langle A, B \rangle_F = \sum_{i,j} A_{i,j} B_{i,j}$ (the sum of element-wise products across all rows and columns, equivalent to `` expr`sum(${A} * ${B})` ``), **not** the matrix-matrix product $(AB)_{i,k} = \sum_j A_{i,j} B_{j,k}$.
+
+---
+
+## Composing Aggregations in `expr`
+
+### Separating Operators and Data
 
-// Total shipping cost in one line:
-m.objective(minimize(dot(costs, ship)));
+Write mathematical operators, `sum(...)`, `dot(..., ...)`, and comparison symbols (`<=`, `>=`, `==`) in the template string, and pass variables, scalars, and containers (`Array` / `Record`) via `${...}`:
+
+```typescript
+// Nested template calls and Object.values() (verbose)
+const totalProfit1 = expr`${dot(profits, vars)}`;
+const cap1 = expr`${sum(Object.values(vars))} <= 100`;
+
+// Direct sum() and dot() inside expr (recommended)
+const totalProfit2 = expr`dot(${profits}, ${vars})`;
+const cap2 = expr`sum(${vars}) <= 100`;
 ```
 
+### Common `expr` Aggregation Syntax
+
+| Operation | Mathematical Formula | WaSHI Expression |
+| :--- | :--- | :--- |
+| **Total sum** (1D/2D `Array` or `Record`) | $\sum_i x_i \le C$ | `` m.constraint(expr`sum(${x}) <= ${C}`) `` |
+| **Inner product** (1D vector or 2D Frobenius) | $\sum_i c_i x_i \le B$ | `` m.constraint(expr`dot(${c}, ${x}) <= ${B}`) `` |
+| **Element-wise difference & product** | $\sum_i (p_i - c_i) \cdot x_i$ | `` expr`sum((${price} - ${cost}) * ${x})` `` |
+| **Sum of squared deviations (QP)** | $\sum_i (x_i - t_i)^2$ | `` expr`sum((${x} - ${target})^2)` `` |
+| **Element-wise constraints** ($\forall i \in I$) | $a_i x_i \le b_i \quad (\forall i)$ | `` m.constraint(items.map((i) => expr`${a[i]} * ${x[i]} <= ${b[i]}`)) `` |
+| **2D row sums** (for each row $f$) | $\sum_s X_{f,s} \le S_f \quad (\forall f)$ | `` m.constraint(factories.map((f) => expr`sum(${ship[f]}) <= ${supply[f]}`)) `` |
+| **2D column sums** (for each column $s$) | $\sum_f X_{f,s} \ge D_s \quad (\forall s)$ | `` m.constraint(stores.map((s) => expr`sum(${factories}, ${(f) => ship[f][s]}) >= ${demand[s]}`)) `` |
+
 ---
 
-## 🧮 Quadratic Expressions (`QuadExpr` & `expr`)
+## Quadratic Expressions (`QuadExpr` & `expr`)
 
-WaSHI natively supports Convex Quadratic Programming (QP) with the HiGHS solver. Quadratic objectives can be written uniformly using the `expr` template literal, or algebraically using `QuadExpr` and `.mul()`:
+WaSHI supports Convex Quadratic Programming (QP) objectives via the HiGHS solver. Quadratic expressions can be written using the `expr` template literal or constructed programmatically with `QuadExpr` and `.mul()`.
 
 ### 1. Using `expr` (Recommended)
-You can write quadratic formulas naturally with `*`, `^2`, or `**2`:
+Write quadratic terms with `*`, `^2`, or `**2`:
 
 ```typescript
 import { Model, expr, minimize } from "@ohtaman/washi";
@@ -138,7 +182,7 @@ m.constraint(expr`${x} + ${y} >= 4`);
 ```
 
 ### 2. Method Chaining with `.mul()` or `QuadExpr`
-Alternatively, you can construct quadratic expressions programmatically:
+You can also construct quadratic expressions programmatically:
 
 ```typescript
 import { Model, QuadExpr, minimize } from "@ohtaman/washi";
@@ -147,12 +191,11 @@ const m = new Model();
 const x = m.continuous("x", { lb: 0 });
 const y = m.continuous("y", { lb: 0 });
 
-// 1. Construct quadratic terms with .mul()
-// Represents x * y + 2 * x^2
+// 1. Construct quadratic terms with .mul() (x * y + 2 * x^2)
 const quad = x.mul(y).add(x.mul(x).mul(2));
 
-// 2. Build portfolio risk objective: w^T * Sigma * w
-const assets = ["Tech", "Bonds"];
+// 2. Build portfolio variance objective: w^T * Sigma * w
+const assets = ["Tech", "Bonds"] as const;
 const w = m.continuous(assets, { lb: 0, ub: 1 });
 
 let risk = new QuadExpr();
@@ -163,13 +206,22 @@ risk = risk.add(w.Bonds.mul(w.Bonds).mul(0.01));
 m.objective(minimize(risk));
 ```
 
+> [!NOTE]
+> **Convexity Requirement ($\mathbf{Q} \succeq 0$)**: QP solvers (including HiGHS) require the quadratic objective matrix $\mathbf{Q}$ to be **positive semi-definite (PSD)** when minimizing (or negative semi-definite when maximizing). Sum-of-squares terms ($\sum_i (x_i - t_i)^2$) and covariance matrices ($\mathbf{w}^\top \boldsymbol{\Sigma} \mathbf{w}$) are guaranteed PSD, whereas indefinite products over continuous variables (such as minimizing $x \cdot y$) are non-convex and rejected by the solver. *(To linearize the product of two binary variables $x_A \cdot x_B$ in MILP, see [Formulation Patterns & Tips](./formulation-tips.md#product-of-two-binary-variables).)*
+
 ---
 
-## 📊 Evaluating Expressions After Solving (`.value`)
+## Evaluating Expressions After Solving (`.value`)
 
-Both `LinExpr` and `QuadExpr` expose a `.value` getter (`number | null`). Once a model has been solved and all referenced variables have finite primal values, you can evaluate any sub-expression—such as total department cost, portfolio return, or resource utilization—directly without manual arithmetic:
+Both `LinExpr` and `QuadExpr` expose a `.value` getter (`number | null`). Once a model has been solved and all referenced variables have finite primal values, you can evaluate any sub-expression directly:
 
 ```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+const m = new Model();
+const x = m.integer("x", { lb: 0 });
+const y = m.integer("y", { lb: 0 });
+
 const revenue = expr`30 * ${x} + 50 * ${y}`;
 const laborUsed = expr`2 * ${x} + ${y}`;
 
@@ -187,7 +239,7 @@ If the model has not been solved (or any variable in the expression has `value =
 
 ---
 
-## 🔗 Fluent Arithmetic & Relational Methods
+## Fluent Arithmetic & Relational Methods
 
 In addition to `expr`, `Var`, `LinExpr`, and `QuadExpr` provide immutable fluent methods for programmatic expression building:
 
@@ -201,4 +253,3 @@ In addition to `expr`, `Var`, `LinExpr`, and `QuadExpr` provide immutable fluent
 | `.le(rhs)` | `Var`, `LinExpr` | `Constraint` | Builds a $\le$ constraint (`lhs <= rhs`). |
 | `.ge(rhs)` | `Var`, `LinExpr` | `Constraint` | Builds a $\ge$ constraint (`lhs >= rhs`). |
 | `.eq(rhs)` | `Var`, `LinExpr` | `Constraint` | Builds an $==$ equality constraint (`lhs == rhs`). |
-

package/docs/guide/formulation-tips.md

@@ -0,0 +1,212 @@
+# Formulation Patterns & Optimization Tips
+
+While the preceding Modeling Guide pages cover WaSHI's APIs (`Model`, `expr`, `m.constraint`, `m.solve`, etc.), this page collects standard mathematical optimization formulation patterns and solver tuning techniques frequently used in linear and mixed-integer programming (LP/MIP).
+
+---
+
+## 1. Variables & Domain Modeling
+
+### Semi-Continuous Decisions ($\{0\} \cup [L, U]$)
+
+A semi-continuous quantity must be either `0` (inactive) or within a positive interval `[L, U]` (e.g., a production batch with a minimum run size $L = 10$ and capacity $U = 100$).
+
+Combine a continuous variable `x` with a binary activation variable `isActive` and linking constraints $L \cdot b \le x \le U \cdot b$:
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+
+const m = new Model("SemiContinuousBatch");
+const batch = m.continuous("batch", { lb: 0, ub: 100 });
+const isActive = m.binary("is_active");
+
+// If isActive === 0, batch is forced to 0; if isActive === 1, batch lies in [10, 100]
+m.constraint(expr`${batch} >= 10 * ${isActive}`, "min_batch_run");
+m.constraint(expr`${batch} <= 100 * ${isActive}`, "max_batch_run");
+```
+
+### Minimal-Perturbation Rescheduling vs. Warm Starting
+
+When re-optimizing an existing schedule after a disruption, passing yesterday's assignment via [`initialValue`](./variables.md#primal-initial-values-warm-start-hints) only gives the MIP solver a starting search point—it does **not** prevent the solver from changing every assignment for a tiny objective gain.
+
+To keep a revised binary plan $x_i \in \{0, 1\}$ close to a baseline assignment $x_i^{\text{prev}} \in \{0, 1\}$, penalize the **Hamming distance** (number of flipped decisions) in the objective:
+
+$$\text{Changes} = \sum_{i:\, x_i^{\text{prev}} = 0} x_i + \sum_{i:\, x_i^{\text{prev}} = 1} (1 - x_i)$$
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+const m = new Model("StableReschedule");
+const prevPlan = [1, 0, 1, 0];
+const x = prevPlan.map((prev, i) =>
+  m.binary(`slot_${i}`, { initialValue: prev })
+);
+
+// Linear terms counting how many 0/1 decisions differ from prevPlan
+const flipTerms = x.map((v, i) => (prevPlan[i] === 1 ? expr`1 - ${v}` : v));
+
+// Require at least 3 active slots while penalizing changes from prevPlan
+m.constraint(expr`sum(${x}) >= 3`, "min_active_slots");
+m.objective(minimize(expr`5 * sum(${flipTerms})`));
+```
+
+---
+
+## 2. Linearizing Non-Linear Expressions
+
+### Product of Two Binary Variables ($x_A \cdot x_B$)
+
+In integer programming, if an interaction cost or synergy bonus applies only when two binary decisions $x_A, x_B \in \{0, 1\}$ are **both** equal to `1`, avoid introducing a quadratic term. Instead, introduce an auxiliary variable $z_{AB} \in [0, 1]$ and add the three standard McCormick / Fortet linear inequalities so the model remains a pure MILP:
+
+$$z_{AB} \le x_A, \quad z_{AB} \le x_B, \quad z_{AB} \ge x_A + x_B - 1$$
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+const m = new Model("BinaryProductLinearization");
+const xA = m.binary("xA");
+const xB = m.binary("xB");
+// When xA and xB are binary, continuous [0, 1] bounds suffice to force bothAB into {0, 1}
+const bothAB = m.continuous("both_AB", { lb: 0, ub: 1 });
+
+m.constraint(expr`${bothAB} <= ${xA}`, "and_upper_A");
+m.constraint(expr`${bothAB} <= ${xB}`, "and_upper_B");
+m.constraint(expr`${bothAB} >= ${xA} + ${xB} - 1`, "and_lower_AB");
+
+m.objective(maximize(expr`10 * ${xA} + 10 * ${xB} + 5 * ${bothAB}`));
+```
+
+### Min-Max & Max-Min Objectives (Load Balancing)
+
+Linear and quadratic objectives cannot call `Math.max(...)` directly. To minimize a bottleneck or peak workload $\min \max_i (\text{load}_i)$, introduce an auxiliary ceiling variable $z$, constrain every individual load by $\text{load}_i \le z$, and minimize $z$:
+
+$$\min z \quad \text{subject to} \quad \text{load}_i \le z \quad \forall i$$
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+const m = new Model("MinMaxLoadBalancing");
+const workers = ["Alice", "Bob", "Carol"] as const;
+const hours = m.continuous(workers, { lb: 0, ub: 40 });
+const maxHours = m.continuous("max_hours", { lb: 0, ub: 40 });
+
+// Bound every worker's hours by the shared ceiling maxHours
+m.constraint(workers.map((w) => expr`${hours[w]} <= ${maxHours}`));
+m.constraint(expr`sum(${hours}) >= 60`, "total_required_work");
+
+// Minimizing maxHours distributes the 60 hours evenly (20 hours each)
+m.objective(minimize(maxHours));
+```
+
+*(Symmetrically, to **maximize the minimum** level $\max \min_i u_i$, impose $u_i \ge z$ for all $i$ and set `m.objective(maximize(z))`.)*
+
+---
+
+## 3. Constraint Design & Numerical Conditioning
+
+### Hard vs. Soft Constraints (Elastic Slack Variables)
+
+Treating every business target as a strict **hard constraint** makes a model `"Infeasible"` as soon as demand exceeds capacity. Keep physical and legal invariants as hard constraints, and model non-rigid targets as **soft constraints** by adding non-negative slack variables ($s \ge 0$) with penalty weights $W$ in the objective:
+
+| Target Type | Hard Constraint | Soft Constraint ($s \ge 0$) | Objective Penalty Term (Minimize) |
+| :--- | :--- | :--- | :--- |
+| **Lower bound** | $\text{lhs} \ge b$ | $\text{lhs} + s_{\text{short}} \ge b$ | $+ W \cdot s_{\text{short}}$ |
+| **Upper bound** | $\text{lhs} \le b$ | $\text{lhs} - s_{\text{excess}} \le b$ | $+ W \cdot s_{\text{excess}}$ |
+| **Target equality** | $\text{lhs} = b$ | $\text{lhs} + s_{\text{short}} - s_{\text{excess}} = b$ | $+ W_1 \cdot s_{\text{short}} + W_2 \cdot s_{\text{excess}}$ |
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+const m = new Model("SoftConstraintCoverage");
+const assignedStaff = m.integer("assigned_staff", { lb: 0, ub: 4 }); // Max 4 staff available
+const shortage = m.continuous("shortage", { lb: 0 });                // Non-negative slack (s >= 0)
+
+// Soft target: aim for 5 staff, allowing shortage > 0 if unavailable
+m.constraint(expr`${assignedStaff} + ${shortage} >= 5`, "target_5_staff");
+
+// Penalize unmet shortage ($1,000) above regular wage ($100)
+m.objective(minimize(expr`100 * ${assignedStaff} + 1000 * ${shortage}`));
+
+await m.solve();
+// assignedStaff.value === 4, shortage.value === 1 (returns best compromise instead of Infeasible)
+```
+
+> [!TIP]
+> **Scaling Penalty Weights ($W$)**: Choose $W$ larger than normal operational marginal costs (typically $10\times$ to $1{,}000\times$ unit cost), and avoid extreme constants such as $10^{12}$. Keeping the ratio between the largest and smallest coefficients within $10^5\text{–}10^6$ preserves floating-point numerical stability in LP/MIP solvers.
+
+### Symmetry Breaking for Identical Resources
+
+When a model contains $K$ interchangeable resources—such as identical trucks, bins, or parallel machines—any feasible assignment has up to $K!$ equivalent permutations with the exact same objective value. Without symmetry breaking, a MIP solver explores redundant mirror-image subtrees before proving optimality.
+
+Impose a canonical ordering ($u_0 \ge u_1 \ge \dots \ge u_{K-1}$) so identical resources are activated in index order:
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+
+const m = new Model("SymmetryBreaking");
+const numTrucks = 4;
+const truckUsed = m.binary(numTrucks, { prefix: "truck_used" });
+
+// Only allow activating truck k+1 when truck k is also active
+for (let k = 0; k < numTrucks - 1; k++) {
+  m.constraint(
+    expr`${truckUsed[k]} >= ${truckUsed[k + 1]}`,
+    `order_truck_${k}`
+  );
+}
+```
+
+---
+
+## 4. Multi-Objective & MIP Stopping Design
+
+### Weighted Sum vs. Lexicographic Two-Stage Optimization
+
+When balancing competing goals—such as minimizing total cost ($f_1$) while also minimizing peak workload ($f_2$)—two approaches are standard:
+
+- **Weighted Sum (Single Solve)**: Combine normalized terms into one objective, e.g., ``minimize(expr`${totalCost} + 50 * ${maxHours}`)``.
+- **Lexicographic (Hierarchical) Two-Stage Solve**: When the primary objective has strict priority, solve for $f_1$ first, add a constraint locking $f_1$ within an acceptable tolerance of its optimum $f_1^*$, and re-solve for $f_2$:
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+const m = new Model("LexicographicTwoStage");
+const workers = ["Alice", "Bob"] as const;
+const wage = { Alice: 20, Bob: 20 };
+const hours = m.continuous(workers, { lb: 0, ub: 40 });
+const maxHours = m.continuous("max_hours", { lb: 0, ub: 40 });
+
+const totalCost = expr`dot(${wage}, ${hours})`;
+m.constraint(expr`sum(${hours}) >= 40`, "required_hours");
+m.constraint(workers.map((w) => expr`${hours[w]} <= ${maxHours}`));
+
+// Stage 1: Minimize primary objective (total wage cost)
+m.objective(minimize(totalCost));
+await m.solve();
+const minCost = m.objectiveValue!;
+
+// Stage 2: Keep cost within 1% of minCost and balance workload (minimize maxHours)
+m.constraint(expr`${totalCost} <= ${minCost * 1.01}`, "near_optimal_cost");
+m.objective(minimize(maxHours));
+await m.solve();
+```
+
+### MIP Tail-Off & Optimality Gap Tolerances
+
+In combinatorial MIP problems, solvers often find a near-optimal feasible solution within seconds, then spend most of the remaining runtime closing the final fraction of a percent in the branch-and-bound tree (**tail-off**).
+
+In interactive UIs and batch pipelines, combine `timeLimit` with business-meaningful tolerances in [`m.solve(options)`](./objectives.md#solve-options-solveoptions):
+- **`relGap: 0.01`**: Stop immediately once the incumbent is proven within **1%** of the theoretical dual bound.
+- **`absGap: 100`**: Stop immediately once `|objectiveValue - objectiveBound| <= 100` in the objective's native units.
+
+---
+
+## 5. Decomposition Formulation Tips
+
+When using [`solveColumnGeneration` or `solveBenders`](./decomposition.md):
+
+1. **Set Covering (`>= 1`) vs. Set Partitioning (`== 1`) in Column Generation**:
+   Formulating coverage constraints as inequalities (`>= 1`) rather than equalities (`== 1`) restricts dual shadow prices to $\pi_i \ge 0$, reducing dual oscillations and accelerating convergence whenever over-coverage can be pruned at no extra cost (e.g., Euclidean routing under the triangle inequality).
+2. **Price-and-Branch (`finalizeAsMIP: true`) vs. Exact Branch-and-Price**:
+   Solving the final Restricted Master Problem as a MIP over columns generated at the root LP relaxation (`finalizeAsMIP: true`) implements the **Price-and-Branch** heuristic—avoiding complex branching inside the pricing subproblem while producing high-quality integer solutions in practice.
+3. **Multi-Cut Separation in Benders / Lazy Constraints**:
+   When a separation callback detects multiple disconnected subtours or violated components in a candidate solution, returning cuts for **all** violated components in one batch reduces the number of master MIP re-solves (see [Traveling Salesperson (`examples/traveling-salesperson`)](../examples/traveling-salesperson.md)).

package/docs/guide/objectives.md

@@ -25,9 +25,12 @@ m.constraint(expr`2 * ${x} + 3 * ${y} <= 100`, "resource_limit");
 
 Calling `m.objective()` with no arguments returns the current objective expression (`LinExpr | QuadExpr`). If you omit setting an objective, the model defaults to minimizing `0`.
 
+> [!TIP]
+> For objective formulation patterns—such as **Min-Max / Max-Min load balancing**, **weighted-sum vs. lexicographic multi-objective optimization**, and **MIP stopping tolerances (`relGap` / `absGap`)**—see [Formulation Patterns & Optimization Tips](./formulation-tips.md#_4-multi-objective-mip-stopping-design).
+
 ---
 
-## 🚀 Solving the Model (`m.solve()` vs. `m.check()`)
+## Solving the Model (`m.solve()` vs. `m.check()`)
 
 WaSHI provides two asynchronous execution entrypoints:
 
@@ -63,7 +66,7 @@ You can also pass a solver name directly as the first argument: `await m.solve("
 
 ---
 
-## ⏱️ Real-Time Progress (`onProgress`) & Cancellation (`AbortSignal`)
+## Real-Time Progress (`onProgress`) & Cancellation (`AbortSignal`)
 
 For long-running MIP optimizations in interactive UIs, you can stream live branch-and-bound progress (`SolveProgressEvent`) and allow users to cancel the solve cleanly with `AbortController`:
 
@@ -109,7 +112,7 @@ console.log("Has incumbent:", m.hasPrimalSolution); // true if an incumbent was
 
 ---
 
-## 📊 Reading Results, Bounds & Solver Status
+## Reading Results, Bounds & Solver Status
 
 After solving, query the status, optimal values, and MIP optimality bounds on the `Model`:
 
@@ -157,7 +160,7 @@ If an integer-feasible incumbent was found before hitting `timeLimit` or `signal
 
 ---
 
-## 🔄 Model Mutations & Execution Validity
+## Model Mutations & Execution Validity
 
 A `Model` instance keeps its solution state synchronized across mutations made through `Model` methods and `Model` / `Var` / `Constraint` property setters:
 

package/docs/guide/unsat-core.md

@@ -4,13 +4,13 @@ When building real-world optimization and configuration systems, two verificatio
 1. **Why is my model infeasible?** Which specific business rules contradict each other?
 2. **Does the solver's solution genuinely satisfy every constraint?** How do I verify tolerances, integrality, and formulations?
 
-WaSHI provides built-in tools for both: **Unsat Core conflict diagnosis** via Z3 (`m.check()`), **independent solution validation** (`m.validateSolution()`), **LP formulation export** (`m.toLpString()`), and **fast unit testing** (`MockSolver`).
+WaSHI provides built-in tools for both: **conflict diagnosis** via built-in HiGHS elastic relaxation or Z3 Unsat Core (`m.check()`), **independent solution validation** (`m.validateSolution()`), **LP formulation export** (`m.toLpString()`), and **fast unit testing** (`MockSolver`).
 
 ---
 
-## 🔍 Conflict Diagnosis (`unsatCore` / `conflicts`)
+## Conflict Diagnosis (`unsatCore` / `conflicts`)
 
-When a model is **Infeasible**, traditional MIP solvers simply report that no solution exists without indicating *which* constraints are contradictory.
+When an optimization run (`m.solve()`) returns **`"Infeasible"`**, the status alone tells you that no solution satisfies every constraint—not *which* rules conflict with each other.
 By calling **`await m.check({ solver: "z3" })`**, WaSHI uses Z3's `assertAndTrack` mechanism to compute an **Unsatisfiable Core (`unsatCore`)**—a conflicting subset of named constraints that cannot be satisfied simultaneously:
 
 ```typescript
@@ -42,22 +42,41 @@ Notice that `routine_operating_cost` is **not** in the core, because only `minim
 > - **Use `m.check({ solver: "z3" })` for Unsat Core extraction**: `m.solve()` runs optimization (`Z3.Optimize`), whereas `m.check()` runs tracked satisfiability checking (`Z3.Solver.assertAndTrack`) and populates `result.conflicts` / `m.conflicts` (and alias `m.unsatCore`).
 > - **Name your constraints**: Variable bounds (`lb`, `ub`) act as background domain declarations. To include a bound or business rule in the reported `unsatCore` list, register it as a named constraint via `m.constraint(expr`...`, "rule_name")`.
 
-### Workflow: Optimize with HiGHS, Diagnose with Z3
+### Workflow: Infeasibility Diagnosis with HiGHS or Z3
 
-Because WaSHI models are solver-independent, you can solve your optimization model with **HiGHS** first and automatically fall back to **Z3** `m.check()` if HiGHS reports `"Infeasible"`:
+Because WaSHI models are solver-independent, you can diagnose infeasibilities using either solver:
+1. **Built-in HiGHS & GLPK (default)**: `await m.check()` uses a single-solve elastic slack formulation ($\min \sum s_i$) to identify which constraints required relaxation (`diag.conflicts`), requiring no extra dependencies.
+2. **Z3 SMT Solver**: `await m.check({ solver: "z3" })` uses SMT tracking to extract an exact unsatisfiable core (`diag.unsatCore` / `diag.conflicts`).
 
 ```typescript
 const status = await m.solve(); // Fast MIP solve with default HiGHS
 
 if (status === "Infeasible") {
-  const diag = await m.check({ solver: "z3" });
+  // Option 1: Built-in single-solve elastic diagnosis with HiGHS
+  const diag = await m.check();
   console.error("Model is infeasible due to conflicting rules:", diag.conflicts);
+
+  // Option 2: Exact SMT unsat core diagnosis with Z3 (requires import "@ohtaman/washi/solvers/z3")
+  // const z3Diag = await m.check({ solver: "z3" });
+  // console.error("Z3 Unsat Core:", z3Diag.unsatCore);
 }
 ```
 
+### Comparing Z3 `unsatCore` vs. HiGHS Elastic Slack `conflicts`
+
+| Property | Z3 (`m.check({ solver: "z3" })`) | HiGHS / GLPK (`m.check()`) |
+| :--- | :--- | :--- |
+| **Algorithm** | SMT assumption tracking (`assertAndTrack`) | Single-solve $L_1$ elastic slack relaxation ($\min \sum s_i$) |
+| **Populated Fields** | Both `result.unsatCore` and `result.conflicts` | `result.conflicts` (`unsatCore` is `undefined`) |
+| **Semantic Meaning** | A **contradictory subset** of rules that cannot all hold together | A **minimum-violation repair set** of constraints whose relaxation restores feasibility |
+| **Unit-Scaling Sensitivity** | **Scale-invariant** (pure logical/algebraic contradiction) | **Scale-sensitive** (minimizing unweighted $\sum s_i$ prefers relaxing a headcount constraint by `2` units over a budget constraint by `10,000` dollars) |
+
+> [!TIP]
+> When diagnosing models that mix constraints of vastly different magnitudes (e.g., headcount $\le 8$ alongside budget $\le 50{,}000$), use **`m.check({ solver: "z3" })`** if you want the complete scale-invariant set of mutually contradictory rules, or normalize constraint scales when relying on unweighted $L_1$ slack relaxation.
+
 ---
 
-## ✅ Independent Solution Validation (`m.validateSolution()`)
+## Independent Solution Validation (`m.validateSolution()`)
 
 After solving a model (or supplying a custom candidate map via `values`), you can independently verify that all variable bounds, integer/binary domains, linear constraints, and logical SMT formulas hold against the original model definitions:
 
@@ -97,7 +116,7 @@ if (m.hasPrimalSolution) {
 
 ---
 
-## 📄 Inspecting the LP Formulation (`m.toLpString()`)
+## Inspecting the LP Formulation (`m.toLpString()`)
 
 When debugging coefficients, signs, or Big-M indicator expansions, call `m.toLpString()` to export the model in standard CPLEX/HiGHS `.lp` format:
 
@@ -123,7 +142,7 @@ End
 
 ---
 
-## 🧪 Unit Testing Application Logic with `MockSolver`
+## Unit Testing Application Logic with `MockSolver`
 
 When running unit tests for application code that builds or consumes a WaSHI `Model`, you can use the built-in `MockSolver` (`solver: "mock"`) to return deterministic results instantaneously without loading WebAssembly: