diff --git a/docs/superpowers/plans/2026-06-11-configurable-objective.md b/docs/superpowers/plans/2026-06-11-configurable-objective.md new file mode 100644 index 0000000..e1005b3 --- /dev/null +++ b/docs/superpowers/plans/2026-06-11-configurable-objective.md @@ -0,0 +1,311 @@ +# Configurable Maximize Criteria Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Make the maximize criteria a parameter of `solve()`: a factors dict (E/B/S/C) plus a "product"/"sum" mode, defaulting to the current hardcoded `E²·B·S²` product. + +**Architecture:** All changes live in `solve.py`. Module-level defaults (`OBJECTIVE_FACTORS`, `OBJECTIVE_MODE`) follow the existing `INITIAL`/`FIXED_CHOICES` pattern; `solve()` resolves `None` args to them (same convention as `resource_constraints`). The hand-chained `AddMultiplicationEquality` objective block is replaced by a generic fold (product mode) or a single linear `Maximize` (sum mode). Phase-1 ceilings are computed only for resources with a nonzero factor. `_report` prints the expression that was actually maximized. + +**Tech Stack:** Python 3.13, Google OR-Tools CP-SAT (`cp_model`). + +**Spec:** `docs/superpowers/specs/2026-06-11-configurable-objective-design.md` + +**Testing:** Per user instruction, no automated tests — the user validates manually. + +--- + +### Task 1: Module-level defaults and validation helper + +**Files:** +- Modify: `solve.py` (PARAMETERS section, after `RESOURCE_CONSTRAINTS` at ~line 68) + +- [ ] **Step 1: Add the defaults and `_validate_objective`** + +Insert after the `RESOURCE_CONSTRAINTS = []` line: + +```python +# Maximize criteria for solve(). Factor = exponent in "product" mode, +# weight in "sum" mode. Keys: E, B, S, C; missing keys = 0 (resource +# excluded from the objective — it is NOT forced to zero). Negative +# factors are allowed only in "sum" mode (a negative exponent would mean +# division, which integer CP-SAT cannot express). +OBJECTIVE_FACTORS = {"E": 2, "B": 1, "S": 2} +OBJECTIVE_MODE = "product" # "product" or "sum" + + +def _validate_objective(factors, mode): + if mode not in ("product", "sum"): + raise ValueError(f"objective_mode must be 'product' or 'sum', got {mode!r}") + unknown = set(factors) - {"E", "B", "S", "C"} + if unknown: + raise ValueError(f"unknown objective_factors keys: {sorted(unknown)}") + for k, v in factors.items(): + if not isinstance(v, int) or isinstance(v, bool): + raise ValueError(f"objective factor {k}={v!r} must be an int") + if mode == "product" and v < 0: + raise ValueError( + f"objective factor {k}={v} is negative; negative exponents " + "are not expressible in product mode" + ) + if not any(factors.values()): + raise ValueError("objective_factors needs at least one nonzero factor") +``` + +(The `isinstance(v, bool)` check exists because `bool` is a subclass of `int` in Python; `True` as a factor is almost certainly a caller bug.) + +- [ ] **Step 2: Commit** + +```bash +git add solve.py +git commit -m "feat: add objective factors/mode defaults and validation" +``` + +--- + +### Task 2: Accept and resolve the new `solve()` arguments + +**Files:** +- Modify: `solve.py` — `solve()` signature (~line 981) and top of the function body + +- [ ] **Step 1: Extend the signature** + +Add two keyword args to `solve()` (after `resource_constraints=None`): + +```python +def solve( + *, + initial=INITIAL, + arrivals=ARRIVALS, + max_res=MAX_RES, + max_vat=MAX_VAT, + time_limit=60.0, + num_workers=8, + verbose=True, + fixed_choices=FIXED_CHOICES, + resource_constraints=None, + objective_factors=None, + objective_mode=None, +): +``` + +- [ ] **Step 2: Resolve defaults and validate, first thing in the body** + +Insert at the very top of the function body, before the `# ---- build the city list` block, so bad input fails before any model construction: + +```python + if objective_factors is None: + objective_factors = OBJECTIVE_FACTORS + if objective_mode is None: + objective_mode = OBJECTIVE_MODE + _validate_objective(objective_factors, objective_mode) + # Normalized copy: every key present, missing keys = 0. + obj_factors = {k: objective_factors.get(k, 0) for k in "EBSC"} +``` + +- [ ] **Step 3: Commit** + +```bash +git add solve.py +git commit -m "feat: solve() accepts objective_factors and objective_mode" +``` + +--- + +### Task 3: Compute Phase-1 ceilings only for resources in the objective + +**Files:** +- Modify: `solve.py` — Phase-1 block (~lines 1536-1554, `def _ceiling` through the three `m.Add(final* <= cap*)` lines) and the verbose ceilings print (~line 1596) + +- [ ] **Step 1: Replace the fixed capE/capB/capS computation with a caps dict** + +The existing line `finalE, finalB, finalS = E[NUM_STEPS + 1], ...` stays. Just below it, replace this block: + +```python + capE = _ceiling(finalE) + capB = _ceiling(finalB) + capS = _ceiling(finalS) + m.Add(finalE <= capE) + m.Add(finalB <= capB) + m.Add(finalS <= capS) +``` + +with (keeping `def _ceiling(var):` as is, above it): + +```python + finals = {"E": finalE, "B": finalB, "S": finalS, "C": C[NUM_STEPS + 1]} + + # Ceilings only for resources that appear in the objective: each + # ceiling solve costs up to 20s, and only objective resources need + # bounds (product mode) / benefit from the redundant cap constraint. + caps = {} + for k, var in finals.items(): + if obj_factors[k] != 0: + caps[k] = _ceiling(var) + m.Add(var <= caps[k]) +``` + +- [ ] **Step 2: Update the verbose ceilings print** + +Replace: + +```python + print(f"(resource ceilings used: E<={capE} B<={capB} S<={capS})") +``` + +with: + +```python + caps_str = " ".join(f"{k}<={v}" for k, v in caps.items()) + print(f"(resource ceilings used: {caps_str})") +``` + +- [ ] **Step 3: Commit** + +```bash +git add solve.py +git commit -m "feat: compute resource ceilings only for objective resources" +``` + +--- + +### Task 4: Generic objective builder (product fold / linear sum) + +**Files:** +- Modify: `solve.py` — the "OBJECTIVE IS SET HERE" block (~lines 1556-1578) + +- [ ] **Step 1: Replace the hardcoded objective block** + +Delete the whole block from `def Eprod(v):` through `m.Maximize(obj)` (including `Eprod`/`Bprod`/`Sprod` and the `prodEE`/`prodSS`/`prodBB`/`prodEB`/`obj` variables) and replace with: + +```python + # ====================================================================== + # OBJECTIVE IS SET HERE + # ====================================================================== + if objective_mode == "sum": + # Linear: CP-SAT takes weighted sums (negative weights included) + # directly, no auxiliary variables needed. + m.Maximize(sum(f * finals[k] for k, f in obj_factors.items() if f)) + else: + # Product: maximize prod(finals[k] ** obj_factors[k]). Expand the + # exponents into a flat factor list and fold pairwise, carrying a + # running upper bound from the Phase-1 caps. + factor_keys = [k for k, f in obj_factors.items() for _ in range(f)] + obj = finals[factor_keys[0]] + bound = caps[factor_keys[0]] + for k in factor_keys[1:]: + bound *= caps[k] + nxt = m.NewIntVar(0, bound, "") + m.AddMultiplicationEquality(nxt, [obj, finals[k]]) + obj = nxt + m.Maximize(obj) +``` + +Notes for the implementer: +- `factor_keys` for the default `{"E": 2, "B": 1, "S": 2}` is `["E", "E", "B", "S", "S"]`, reproducing the old `E²·B·S²` objective. +- A single-factor product (e.g. `{"E": 1}`) skips the loop entirely and maximizes `finalE` directly — that's correct. +- Every key in `factor_keys` has a nonzero factor, so `caps[k]` always exists (Task 3 computed caps for exactly those keys). + +- [ ] **Step 2: Commit** + +```bash +git add solve.py +git commit -m "feat: build objective from factors dict in product or sum mode" +``` + +--- + +### Task 5: Report the actually-maximized objective + +**Files:** +- Modify: `solve.py` — `_report()` signature (~line 1651) and its FINAL print (~lines 1854-1858); the `_report(...)` call inside `solve()` (~line 1597) + +- [ ] **Step 1: Add objective params to `_report`'s signature** + +Append two keyword params after `baron_deposits=None`: + +```python + baron_deposits=None, + obj_factors=None, + obj_mode=None, +): +``` + +- [ ] **Step 2: Replace the FINAL print** + +Replace: + +```python + fe, fb, fs = solver.Value(finalE), solver.Value(finalB), solver.Value(finalS) + print( + f"\nFINAL E={fe / 10:.1f} B={fb / 10:.1f} S={fs / 10:.1f} " + f"product(scaled) = {fe * fb * fs / 1000} sum = {(fe + fb + fs) / 10:.1f}" + ) +``` + +with: + +```python + fe, fb, fs = solver.Value(finalE), solver.Value(finalB), solver.Value(finalS) + vals = {"E": fe, "B": fb, "S": fs, "C": solver.Value(C[NUM_STEPS + 1])} + if obj_factors is None: + # Legacy fallback: old hardcoded E*B*S display. + obj_str = f"product(scaled) = {fe * fb * fs / 1000}" + elif obj_mode == "sum": + terms = [ + f"{f}{k}" if abs(f) != 1 else (k if f > 0 else f"-{k}") + for k, f in obj_factors.items() + if f + ] + expr = " + ".join(terms).replace("+ -", "- ") + raw = sum(f * vals[k] for k, f in obj_factors.items()) + obj_str = f"objective {expr} = {raw / 10:.1f}" + else: + expr = "*".join( + k if f == 1 else f"{k}^{f}" for k, f in obj_factors.items() if f + ) + raw, n = 1, 0 + for k, f in obj_factors.items(): + raw *= vals[k] ** f + n += f + # Resource values are x10-scaled, so descale by 10^(sum of exponents). + obj_str = f"objective {expr} = {raw / 10**n}" + print( + f"\nFINAL E={fe / 10:.1f} B={fb / 10:.1f} S={fs / 10:.1f} " + f"{obj_str} sum = {(fe + fb + fs) / 10:.1f}" + ) +``` + +Display examples: product `{"E": 2, "B": 1, "S": 2}` → `objective E^2*B*S^2 = ...` descaled by `10^5`; sum `{"E": 2, "B": 1, "S": -1}` → `objective 2E + B - S = ...` descaled by 10. + +- [ ] **Step 3: Pass the objective through from `solve()`** + +At the `_report(...)` call inside `solve()`, append two keyword arguments after `baron_deposits,`: + +```python + baron_deposits, + obj_factors=obj_factors, + obj_mode=objective_mode, + ) +``` + +- [ ] **Step 4: Commit** + +```bash +git add solve.py +git commit -m "feat: report prints the actually maximized objective" +``` + +--- + +### Task 6: Smoke check (user validation) + +Per user instruction there are no automated tests. A quick way to confirm the default path is byte-for-byte behavior-compatible: + +- [ ] **Step 1: Syntax check** + +Run: `uv run python -c "import solve"` +Expected: no output, exit 0. + +- [ ] **Step 2: Hand off to user** + +The user validates solver behavior themselves (e.g. `uv run python solve.py` should produce the same plan/objective as before the change, now printing `objective E^2*B*S^2 = ...`).