ICC Decision Suite VS11 - EvoOpt pilot

BUILD AND LOAD
Close Excel, extract to its own folder and run BUILD_SUITE.cmd. If Excel blocks
project access, temporarily enable Trust access to the VBA project object model.
Unload the older suite XLAM, then load dist\ICC_Decision_Suite_VS11.xlam through
Excel Options > Add-ins. Keep suite_assets next to the XLAM and keep your existing
RiskSim XLL. EvoOpt needs no Solver add-in, XLL, Python or network connection.
This is source plus a Windows builder; native Excel/VBA acceptance is required.

EXAMPLES
Open ICC_EvoOpt_VS11_Product_Mix.xlsx in examples. Read Start, then choose
EvoOpt > Run EvoOpt. Expected optimum: A=20, B=40; contribution ZAR 2,000.
The bounded integer grid is completely evaluated with the supplied 3,000 budget.
Open ICC_EvoOpt_VS11_Formulation.xlsx separately. This continuous example has an
analytical optimum A=0.3, B=0.2, C=0.5; minimum cost ZAR 14/kg. Search results
may be approximate. C is a formula, not an adjustable cell, so fractions total 1.
The supplied _ICC_EvoOpt table is ready to run in each workbook. Setup opens an
existing compatible table without overwriting it. Run one example at a time.

CONFIGURATION
_ICC_EvoOpt A1:G1: Role, Label, Worksheet, Cell, Lower / Relation, Upper / RHS,
Type / Tolerance. H1: ICC EvoOpt VS11.
Each contiguous row contains one local scalar reference in columns C and D.
OBJECTIVE: exactly one row, E=MAX or MIN.
VARIABLE: up to 20 numeric constant cells, E=lower, F=upper,
G=CONTINUOUS or INTEGER. Bounds must lie within +/-1 billion. Fractional integer
bounds are tightened inward. Starting values must be within bounds and integral
for INTEGER variables. Formula, spill, array, merged or protected cells cannot be
variables. Use a dependent formula for a balancing formulation fraction.
CONSTRAINT: up to 50 numeric cells, E=<=, >= or =, F=fixed numeric RHS,
G=nonnegative absolute feasibility tolerance in that cell's own units.
K2: candidate budget, integer 1 to 50,000. K3: integer seed 1 to 2,147,483,646.
Cell references stay within the model workbook. Use explicit cell addresses.
Use variable bounds for constraints on the variable cells themselves.

SEARCH AND FEASIBILITY
A fully enumerable integer/fixed grid fitting the budget (including the starting
candidate) is checked exhaustively. Otherwise seeded differential evolution
(DE/rand/1/bin; mutation 0.7; crossover 0.8; population 20-80) is followed by
coordinate refinement. The candidate budget is a ceiling, not a required count.
Continuous searches and incomplete grids do not prove global optimality.
Feasible candidates always beat infeasible ones. Among feasible candidates the
objective decides. Otherwise normalized constraint violation decides, then the
objective. Violation is the sum of max(0, relation gap minus absolute tolerance)
divided by max(1, abs(RHS)) for each constraint. Equalities use abs(LHS-RHS).
Tolerance directly affects admissible solutions; choose it in the model's units.
No automatic equality repair, gradients, constraint inference or optimality-gap
certificate is included. Narrow feasible regions can require more search.
Each candidate uses two full recalculations, comparing objective and constraints
to detect observed nondeterminism (relative tolerance 1e-10). Remove random
sampling and live/external updates first. This is not stochastic optimization.
A numeric error at any evaluated point aborts the run; restrict bounds to the
valid model domain. No workbook formulas are rewritten.

PROGRESS, STOP AND RECOVERY
Status bar and EO11_..._Log show best value and feasibility, updated every ten
candidates. EvoOpt > Stop Search stops at the next update; Ctrl+Break interrupts
and triggers restoration. Do not edit or close the workbook while searching.
Calculation mode, events, screen state and status bar are restored afterwards.
Starting inputs are restored before results are shown. A Yes/No prompt lets you
apply the best feasible solution; No leaves the starting model unchanged.
A saved best solution is rechecked before it can remain applied.
No feasible solution means no apply prompt; the report shows the least-violating
candidate found. Stopping does not imply infeasibility or optimality.
_ICC_EvoRecovery records the latest starting values and applied values. Restore
Inputs restores a pending run or the most recently applied solution. It refuses
to overwrite applied inputs that have subsequently changed. A new run replaces
this snapshot; it is not an unlimited undo history. Save the workbook to persist
recovery. The add-in does not automatically save user workbooks. A process crash
before saving cannot be guaranteed recoverable. Pending recovery blocks a new run.

RESULTS
EO11_..._Result contains the starting and best objectives, variable values and
constraint gaps. Results/logs are static snapshots. Reports distinguish complete
integer enumeration from heuristic search. All existing analysis pilots remain.
See PREVIOUS_VS10_README.txt and PREVIOUS_VS9_README.txt for earlier workflows.

STATUS
Working pilots: RiskSim, DecisionTree, Sensitivity, StatLab, EvoOpt.
Planned: RiskOpt, NeuralLab, AI Assist. Project management remains deferred.
