105 lines
4.2 KiB
Markdown
105 lines
4.2 KiB
Markdown
# Configurable Maximize Criteria for `solve()`
|
||
|
||
**Date:** 2026-06-11
|
||
**Status:** Approved
|
||
|
||
## Problem
|
||
|
||
The objective in `solve.py` is hardcoded at the bottom of `solve()` (the
|
||
"OBJECTIVE IS SET HERE" block): it maximizes the monomial
|
||
`finalE² · finalB¹ · finalS²` via hand-chained `AddMultiplicationEquality`
|
||
calls, with intermediate bounds derived from the Phase-1 per-resource
|
||
ceilings. Changing the criteria means editing solver internals. The actual
|
||
usage pattern (per git history) is varying the per-resource powers, so the
|
||
criteria should be a parameter of `solve()`.
|
||
|
||
## API
|
||
|
||
Two new keyword-only arguments on `solve()`, with module-level defaults in
|
||
the PARAMETERS section (matching the existing `INITIAL` / `FIXED_CHOICES`
|
||
pattern):
|
||
|
||
```python
|
||
OBJECTIVE_FACTORS = {"E": 2, "B": 1, "S": 2} # missing keys = 0 (excluded)
|
||
OBJECTIVE_MODE = "product" # "product" or "sum"
|
||
|
||
def solve(*, ..., objective_factors=None, objective_mode=None):
|
||
```
|
||
|
||
- `None` for either argument falls back to the module-level default, the
|
||
same convention `resource_constraints` already uses.
|
||
- Defaults reproduce the current hardcoded objective (`E²·B·S²`) exactly.
|
||
- Valid factor keys: `"E"`, `"B"`, `"S"`, `"C"` (Capital becomes
|
||
targetable). Values are integers.
|
||
|
||
### Validation (fail fast with `ValueError`)
|
||
|
||
- Unknown key in `objective_factors`.
|
||
- All factors zero (or empty dict) — degenerate objective.
|
||
- `objective_mode` not in `{"product", "sum"}`.
|
||
- Non-integer factor values.
|
||
- Negative factor values **in product mode only**: a negative exponent
|
||
means division, which integer CP-SAT cannot express. Sum mode accepts
|
||
negative weights — CP-SAT handles negative coefficients in linear
|
||
objectives natively.
|
||
|
||
## Semantics
|
||
|
||
The factor means **exponent** in product mode and **weight** in sum mode.
|
||
|
||
- **`product`**: maximize `Πₖ finalₖ^factorₖ`. Built generically: expand the
|
||
factors to a flat list of final-resource vars (e.g.
|
||
`[finalE, finalE, finalB, finalS, finalS]`), then fold pairwise with
|
||
`AddMultiplicationEquality`, carrying a running upper bound multiplied
|
||
from the Phase-1 caps. This replaces the hand-chained `prodEE`/`prodSS`/
|
||
`prodBB`/`prodEB`/`obj` block and the `Eprod`/`Bprod`/`Sprod` bound
|
||
helpers.
|
||
- **`sum`**: maximize `Σₖ factorₖ · finalₖ` — a single `m.Maximize(...)` on
|
||
a linear expression; no auxiliary variables. May be negative when
|
||
negative weights are used.
|
||
|
||
A factor of 0 drops the resource from the objective (exponent 0 → factor
|
||
of 1 in product mode), matching current behavior where Capital simply
|
||
isn't in the objective. It does not force the resource to zero.
|
||
|
||
## Phase-1 ceilings
|
||
|
||
Ceilings (`_ceiling`) are computed only for resources with a nonzero
|
||
factor. Rationale:
|
||
|
||
- Each ceiling solve costs up to 20 s; skipping unused resources is a real
|
||
win.
|
||
- `C` gets a ceiling only when it appears in a product objective, where the
|
||
bound is required for the intermediate product variables.
|
||
- Sum mode does not need caps for bounds, but the redundant
|
||
`final ≤ cap` constraints are still added for computed ceilings since
|
||
they prune the search.
|
||
|
||
## Reporting
|
||
|
||
`_report` receives the resolved objective spec (factors + mode) and prints
|
||
the expression that was actually maximized along with its value, replacing
|
||
the hardcoded `product(scaled) = E·B·S` line. Examples:
|
||
|
||
- product mode: `objective E^2*B*S^2 = <value>` with the value descaled by
|
||
`10^(sum of exponents)`.
|
||
- sum mode: `objective 2E + B - S = <value>` descaled by 10.
|
||
|
||
`finalC` (`C[NUM_STEPS + 1]`) participates in the printout when `"C"` has a
|
||
nonzero factor; `_report` already receives the `C` pool dict. The
|
||
per-resource FINAL line and the intermediate solution printer (E/B/S)
|
||
remain unchanged.
|
||
|
||
## Unchanged
|
||
|
||
- The intermediate solution printer still tracks E/B/S.
|
||
- `web_solve.py` keeps working unmodified — both new arguments are
|
||
optional with behavior-preserving defaults.
|
||
|
||
## Bounds note
|
||
|
||
With `MAX_RES = 2000`, the default product bound is
|
||
`2000⁵ = 3.2 × 10¹⁶`, comfortably inside CP-SAT's int64 objective range.
|
||
Extreme factor values could overflow; the fold computes the running bound
|
||
explicitly, so an overflow would surface as a CP-SAT model error rather
|
||
than silent wraparound. No additional guard is included (YAGNI).
|