@ohtaman/washi 0.4.0 → 0.6.0

package/docs/guide/decomposition.md

@@ -0,0 +1,399 @@
+# Advanced Decomposition Methods & Best Practices
+
+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.
+
+---
+
+## 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) |
+
+---
+
+## Foundational Primitives
+
+WaSHI provides fine-grained modeling primitives to inspect dual information and dynamically modify models:
+
+### 1. Constraint Duals (`dual`)
+Access the dual values (marginal impact on the objective per unit change in RHS) after an LP solve:
+
+```typescript
+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);
+```
+
+### 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:
+
+```typescript
+// Solves LP relaxation and populates shadow prices in m.solution.duals
+const status = await m.relax();
+console.log("Theoretical dual 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:
+
+```typescript
+const col = m.addColumn({
+  name: "pattern_1",
+  type: "Integer", // or "Continuous"
+  lb: 0,
+  cost: 1, // objective coefficient
+  coefficients: {
+    demand_itemA: 2,
+    demand_itemB: 1,
+  },
+});
+```
+
+### 4. Dynamic Constraint Modification (`addTerm` / `setTerm`)
+Update the coefficients of individual variables in an existing 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
+```
+
+---
+
+## 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.
+
+### 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:
+
+```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
+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)
+
+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;
+
+// 2. Solve with master.solveColumnGeneration()
+const result = await master.solveColumnGeneration({
+  finalizeAsMIP: true,
+  pricing: async () => {
+    // Pricing subproblem: Bounded Knapsack
+    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 });
+
+    // 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}`);
+
+    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),
+      },
+    };
+  },
+});
+
+console.log("Optimal rolls needed:", result.objectiveValue); // 14
+console.log("Iterations executed:", result.iterations);
+console.log("Dynamic columns added:", result.columnsAdded);
+```
+
+### Custom Pricing Algorithms (Graph / Dynamic Programming)
+
+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):
+
+```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,
+    };
+  },
+});
+```
+
+---
+
+## 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.
+
+### Recommended: Automated Cut Generation with `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:
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+// 1. Master problem: Facility location 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)
+master.objective(minimize(expr`100 * ${y1} + 120 * ${y2}`));
+// Minimal aggregate capacity requirement
+master.constraint(expr`50 * ${y1} + 60 * ${y2} >= 75`, "capacity_check");
+
+// 2. Solve automatically with master.solveBenders()
+const result = await master.solveBenders({
+  gapTolerance: 1e-4,
+  subproblem: () => {
+    // Operational dispatch subproblem
+    const sub = new Model("TransportSubproblem");
+    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}`
+      )
+    );
+
+    // 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
+    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
+  },
+});
+
+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,
+});
+```
+
+### Low-Level Control: Custom `BendersCut` Callback
+
+You can also construct Benders cuts manually by returning `BendersCut` objects:
+
+```typescript
+const result = await master.solveBenders({
+  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();
+
+    const actualCost = sub.objectiveValue!;
+    if (estTheta < actualCost - 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,
+      };
+    }
+    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
+```
+
+### 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
+    }
+
+    // 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}`,
+    };
+  },
+});
+```

package/docs/guide/expressions.md

@@ -0,0 +1,204 @@
+# Expressions (`expr`, `sum`, `dot`)
+
+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.
+
+| Approach | Example | Infix readability | Type safety & IDE rename | Indexed variables (`flow[i][j]`) |
+| :--- | :--- | :--- | :--- | :--- |
+| Method chaining | `x.mul(30).add(y.mul(50)).le(40)` | Low | Yes | Yes |
+| Raw string parsing | `parseConstraint("30 * x + 50 * y <= 40", resolver)` | High | No (runtime string lookup) | Fragile (string concatenation) |
+| **Tagged template (`expr`)** | `` expr`30 * ${x} + 50 * ${y} <= 40` `` | **High** | **Yes (actual TS references)** | **Yes (bound by object reference)** |
+
+---
+
+## ✍️ 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.
+
+Use `expr` for both arithmetic expressions (`LinExpr | QuadExpr`) and relational constraints (`Constraint`):
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0 });
+const y = m.continuous("y", { lb: 0 });
+
+// 1. Linear combination: 3*x + 5*y - 10
+const linearExpr = expr`3 * ${x} + 5 * ${y} - 10`;
+
+// 2. Quadratic expression: x * y + 2 * x^2
+const quadExpr = expr`${x} * ${y} + 2 * ${x} * ${x}`;
+
+// 3. Relational constraint:
+const balanceConstraint = expr`${x} + 2 * ${y} <= 40`;
+```
+
+### Supported Syntax in `expr`
+- **Addition & Subtraction**: `${x} + ${y} - 5`
+- **Scalar Multiplication**: `4 * ${x}`, `${x} * 4`
+- **Variable Multiplication (Quadratic terms)**: `${x} * ${y}`, `2 * ${x} * ${x}`
+- **Powers & Exponentiation**: `${x}^2`, `${x}**2`
+- **Unary Negation**: `-${x} + 10`
+- **Parentheses**: `2 * (${x} + ${y})`
+- **Nested Expressions**: `expr` seamlessly interpolates variables, numbers, `sum()` results, and nested expressions.
+
+> [!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.
+
+---
+
+## ⚡ High-Performance Summation (`sum`)
+
+For iterating over large collections of variables or indices:
+
+```typescript
+import { sum } from "@ohtaman/washi";
+
+const items = ["A", "B", "C"];
+const weights = { A: 10, B: 20, C: 30 };
+const x = m.binary(items);
+
+// 1. Transform elements with a mapping callback:
+const totalWeight = sum(items, (item) => x[item].mul(weights[item]));
+
+// 2. Direct array summation:
+const count = sum(Object.values(x));
+```
+
+`sum()` runs in $O(N)$ linear time without AST overhead.
+
+---
+
+## 🎯 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)`).
+
+Supported 1D and 2D container shapes:
+- **1D Arrays**: `number[]` $\times$ `(Var | LinExpr)[]`
+- **1D Records**: `Record<K, number>` $\times$ `Record<K, Var | LinExpr>`
+- **2D Arrays**: `number[][]` $\times$ `(Var | LinExpr)[][]`
+- **2D Records**: `Record<R, Record<C, number>>` $\times$ `Record<R, Record<C, Var | LinExpr>>`
+- **2D Mixed**: `Array<Record<C, ...>>` or `Record<R, Array<...>>`
+
+Mismatched array lengths, missing dictionary keys, or non-finite/non-linear leaves throw an explicit error indicating the offending path (e.g., `at '[0].StoreB'`).
+
+### 1D Vector Dot Product
+```typescript
+import { dot } from "@ohtaman/washi";
+
+const profits = { desk: 30, chair: 50 };
+const vars = m.integer(["desk", "chair"]);
+
+// Computes 30 * vars.desk + 50 * vars.chair
+const totalProfit = dot(profits, vars);
+```
+
+### 2D Matrix Dot 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 costs = {
+  Tokyo: { StoreA: 4, StoreB: 7 },
+  Osaka: { StoreA: 8, StoreB: 3 },
+};
+
+const ship = m.continuous(factories, stores);
+
+// Total shipping cost in one line:
+m.objective(minimize(dot(costs, ship)));
+```
+
+---
+
+## 🧮 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()`:
+
+### 1. Using `expr` (Recommended)
+You can write quadratic formulas naturally with `*`, `^2`, or `**2`:
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0 });
+const y = m.continuous("y", { lb: 0 });
+
+// Quadratic objective using expr:
+m.objective(minimize(expr`3 * ${x} + ${x}^2 + ${y}^2`));
+
+// Linear constraint using expr:
+m.constraint(expr`${x} + ${y} >= 4`);
+```
+
+### 2. Method Chaining with `.mul()` or `QuadExpr`
+Alternatively, you can construct quadratic expressions programmatically:
+
+```typescript
+import { Model, QuadExpr, minimize } from "@ohtaman/washi";
+
+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
+const quad = x.mul(y).add(x.mul(x).mul(2));
+
+// 2. Build portfolio risk objective: w^T * Sigma * w
+const assets = ["Tech", "Bonds"];
+const w = m.continuous(assets, { lb: 0, ub: 1 });
+
+let risk = new QuadExpr();
+risk = risk.add(w.Tech.mul(w.Tech).mul(0.04));
+risk = risk.add(w.Tech.mul(w.Bonds).mul(0.005));
+risk = risk.add(w.Bonds.mul(w.Bonds).mul(0.01));
+
+m.objective(minimize(risk));
+```
+
+---
+
+## 📊 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:
+
+```typescript
+const revenue = expr`30 * ${x} + 50 * ${y}`;
+const laborUsed = expr`2 * ${x} + ${y}`;
+
+m.objective(maximize(revenue));
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_cap");
+m.constraint(expr`${laborUsed} <= 50`, "labor_cap");
+
+await m.solve();
+
+console.log("Total Revenue:", revenue.value);   // 1100 (x = 20, y = 10)
+console.log("Labor Used:", laborUsed.value);    // 50
+```
+
+If the model has not been solved (or any variable in the expression has `value === null`), `.value` returns `null`.
+
+---
+
+## 🔗 Fluent Arithmetic & Relational Methods
+
+In addition to `expr`, `Var`, `LinExpr`, and `QuadExpr` provide immutable fluent methods for programmatic expression building:
+
+| Method | Supported On | Return Type | Description |
+| :--- | :--- | :--- | :--- |
+| `.add(other)` | `Var`, `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Adds a number, `Var`, `LinExpr`, or `QuadExpr`. |
+| `.sub(other)` | `Var`, `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Subtracts a number, `Var`, `LinExpr`, or `QuadExpr`. |
+| `.mul(other)` | `Var`, `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Multiplies by a scalar `number`, or multiplies two linear terms into a `QuadExpr`. |
+| `.div(divisor)` | `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Divides by a non-zero finite scalar `number`. |
+| `.neg()` | `Var`, `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Negates all terms ($-e$). |
+| `.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`). |
+