Minimax — Control Systems/Optimization
Control_Systems/Optimization/Minimax · 1 input / 4 output port(s) at insert · exports to Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog, PLC Structured Text
Description#
The block's own DESCRIPTION_HTML, rendered verbatim — the same text the config dialog's info panel and the library navigator show. Fix a wrong sentence in the block's .cpp (R-D9), never here.
Minimax
Control Systems / Optimization
Finds the x that makes the largest of m polynomials as small as
possible, their coefficients arriving on a port – MATLAB's
fminimax, solved again on every sample:
minimize over x maxi Fi(x), Fi(x) = Σt ci,t · x1e(t,1) · … · xne(t,n), i = 1 … m
The exponents e are configuration – the problem's shape, which fixes the loop bounds every export unrolls. The m objectives share that ONE term dictionary, and their coefficients c are the signal: one column per objective, stacked into a single port. So the surfaces being balanced can change on every sample while their form does not.
The search is fminimax's own: an artificial variable γ joins
x, every objective becomes the constraint Fi(x) − γ ≤ 0,
and a sequential quadratic programming method minimizes γ – a BFGS
Hessian approximation, an active-set QP with its own feasibility phase, and a merit
line search. Gradients are exact, because a polynomial's gradient is another
polynomial.
The factory setting is fminimax's documented example: five
objectives in two variables over the terms [2 0; 0 2; 1 0; 0 1; 0 0]
(x₁², x₂², x₁, x₂, 1) – 2x₁² +
x₂² − 48x₁ − 40x₂ + 304, −x₁²
− 3x₂², x₁ + 3x₂ − 18, −x₁ −
x₂ and x₁ + x₂ − 8 – from [0.1; 0.1]. Its
answer is x = (4, 4) with a largest objective of 0.
Ports
- c – the coefficients, a column [m·T,1]: rows 1..T are objective 1's, one per ROW of Term Exponents in the same order, rows T+1..2T objective 2's, and so on. A row vector is refused.
- x – the minimizer, [n,1] (n = the columns of Term Exponents).
- F(x) – every objective at x, [m,1].
- max F – the largest of them, a scalar [1,1]
(
fminimax'smaxfval). - exitflag – a scalar [1,1],
fminimax's own: 4 the search direction became smaller than twice Step Tolerance; 5 the predicted change in γ became smaller than Function Tolerance (both with the constraints met); 0 a limit below stopped the search; −2 no point was found where the constraints hold.fminimaxhas no flag 1: its first-order test is switched off for this problem.
Parameters
- Options – empty (default), or the path of a Solver Options block (
Home/Solver Options), MATLAB’s options argument: for the run, every option it sets replaces this block’s parameter of the same name; one it leaves atdefault, or one this block does not have, changes nothing. - Term Exponents – a [T,n] matrix of whole numbers from 0 to 4: row t, column i is the power of xi in term t. T is 1 to 8, n is 1 to 4, and no term may total more than degree 4. The caps are the export's, not the search's – see Code export.
- Number of Objectives – m, from 1 to 6. With m = 1 the block minimizes a single polynomial.
- Start Point – x0, n entries. The search is LOCAL, so on a problem with several local minimax points this chooses which one is found.
- Step Tolerance – StepTolerance, positive; default 1e-6. The search stops with flag 4 once the largest entry of the QP step is below twice this.
- Function Tolerance – FunctionTolerance, positive; default 1e-6. The search stops with flag 5 once the step's predicted change in γ is below this.
- Constraint Tolerance – ConstraintTolerance, positive; default 1e-6: how far Fi(x) − γ may exceed 0 and still count as met.
- Maximum Iterations – MaxIterations, 1 to 2000, default 400, MATLAB's own.
- Maximum Function Evaluations –
MaxFunctionEvaluations, 0 to 2000. 0 (the default) means MATLAB's
own, 100·(n+1) – the +1 is γ, which
fminimaxcounts as a variable. - Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period.
Code export
All ten targets: Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog and PLC Structured Text. Each prints the same description of the iteration that the simulation itself runs, so every target does the same arithmetic in the same order as the simulation.
The exponent pattern is unrolled once: each term's monomial and its n partial derivatives, shared by every objective. The iteration is emitted with fixed trip counts and flags that stop the arithmetic once the answer is found, because none of the ten has an unbounded loop a hardware target could also carry.
⚠ The three HDL targets run the search in simulation-only real arithmetic, quantizing only at the port boundaries: a QP divides and compares across many orders of magnitude, which a Q16.16 datapath does not carry.
Simulink bridge
None (Support::None). The Optimization Toolbox ships no
Simulink library at all and fminimax is a MATLAB function, so there is
no block to map onto; the bridge reports this block rather than dropping it
silently, and it has no parity testbench. Code export verification still covers it
across all ten languages.
Notes
- Stateless: the search restarts from Start Point on every sample, so the answer depends only on the coefficients present at that step.
- ⚠ LOCAL. The method finds a point where no small step lowers the largest objective; on a non-convex problem that can depend on Start Point.
- ⚠ If the largest objective is unbounded below – every objective can be driven down together, which an odd-degree term with a coefficient that can change sign allows – there is no answer, and the point reported is wherever the evaluation limit stopped the search (flag 0) or where the line search gave up. Keep at least one objective bounded below if every sample is to have a minimax point.
- eps has no spelling in nine of the ten targets, so MATLAB's
epsand the constants built from it are the exact binary values here.
Code facts#
| Fact | Value |
|---|---|
| registered type | Control_Systems/Optimization/Minimax |
| family | Control_Systems/Optimization |
| solver environment class | ICoreBlock_0_Control_Systems_1_Optimization_2_Minimax |
| source | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Optimization/Minimax/ICoreBlock_0_Control_Systems_1_Optimization_2_Minimax.cpp |
| header | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Optimization/Minimax/ICoreBlock_0_Control_Systems_1_Optimization_2_Minimax.h |
| default size on canvas | 170 × 110 px |
| ports at insert | 1 in, 4 out |
| code generators implemented | Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog, PLC Structured Text |
Ports#
| # | Direction | Signal type | Description label |
|---|---|---|---|
| 1 | in | ICoreDouble | c |
| 2 | out | ICoreDouble | x |
| 3 | out | ICoreDouble | F(x) |
| 4 | out | ICoreDouble | max F |
| 5 | out | ICoreDouble | exitflag |
Ports the constructor creates. A block whose port list changes with its configuration adds or removes ports at load time; the count above is the one a freshly inserted block has.
Configuration variables#
| Config variable | Default | Simulink parameter |
|---|---|---|
Term Exponents | [2 0; 0 2; 1 0; 0 1; 0 0] | — |
Number of Objectives | 5 | — |
Start Point | [0.1; 0.1] | — |
Step Tolerance | 1e-6 | — |
Function Tolerance | 1e-6 | — |
Constraint Tolerance | 1e-6 | — |
Maximum Iterations | 400 | — |
Maximum Function Evaluations | 0 | — |
Options | — | — |
Every block also carries Sampling Time (s) from ICoreBlockSolverEnvironment: zero or less inherits the solver's rate, a positive value runs the block at that period.
Simulink bridge#
| support | Support::None |
| Simulink path | — |
| port-count rule | PortsParam::None |
SampleTime parameter | yes |
Caveat (shown to the user): the Optimization Toolbox ships no Simulink library at all, so there is no block to map onto and no library path a diagram could name; fminimax is a MATLAB function. The block is reported rather than dropped when a model crosses
Catalog contract: src/ICoreBlocks/ICoreCoder/ICoreCommandSystem/SimulinkBridge/ICoreSimulinkBlockCatalog.h
Description vs code#
The checker has a blind spot here — it could not resolve something (a grouped port bullet, a computed config name), which is reported and never counted as a pass. A reader has to settle it:
B0no sample under docs/generated/samples/ — nothing to cross-check (P8.1)
The verdict above is
tools/docs/check_block_descriptions.py(P7.1), which compares LISTS. It cannot read a sentence: "stateless" on a block with a state, an initial-value semantic the recursion does not implement, a "not synthesizable" caveat the HDL banner contradicts. That is the agent audit (P7.3) on BLOCK_DESCRIPTION_AUDIT.md, and this tool's green is not a substitute for one.
File banner (developer view)#
The top comment of the block's .cpp — the maths, the realization and the export strategy, addressed to whoever changes it. It must not contradict the description above (P7.5).
Minimax -- fminimax over m polynomials whose coefficients are a wire F_i(x) = sum over terms of c(i,t) * x1^e(t,1) * ... * xn^e(t,n), i = 1 .. m [x, fval, maxfval, exitflag] = fminimax(F, x0)
THE OBJECTIVE SEAM IS THE FAMILY'S. The exponent pattern is configuration -- the problem's SHAPE, which fixes every loop bound the ten exports unroll -- and the coefficients are the signal. The m objectives share one term dictionary, exactly as Nonlinear System Solve's equations do, so the port is m coefficient columns stacked into one: rows (i-1)*T+1 .. i*T are objective i's. One unrolled evaluation then serves every objective and every gradient.
THE SOLVER IS fminimax's OWN, TRANSCRIBED, and it is shared with Goal Attainment: fminimax adds gamma to x, turns each objective into F_i(x) - gamma <= 0 and hands the lot to nlconst.m's SQP, whose QP is qpsub.m -- fgoalattain does the same with a goal and a weight in each row. So the whole solver lives in ICoreGoalAttainmentSupport, and this block is that solver at goal 0, weight 1, reporting max F where Goal Attainment reports gamma.
⚠ MEASURED AGAINST R2026a, with the analytic gradient supplied to fminimax as this block computes it (SpecifyObjectiveGradient = true), over 1300 random problems -- n = 1..4 variables, m = 1..4 objectives, up to 8 terms of degree <= 4 -- the PROGRAM THIS BLOCK RUNS, compiled standalone and fed the same corpus:
exit flag identical 1299 / 1300 iteration count identical 1298 / 1300 evaluation count identical 1298 / 1300 converged answers (flag 4/5, 1276 of them): x within 1e-12 relative on 1273, bit-identical on 149
The single flag that differs (4 here, 5 in MATLAB) is a problem whose Hessian approximation grows to 1e29 and sends qpsub down its singular branch; x still agrees there to 2.4e-9. The two converged rows that differ by more than that are UNBOUNDED problems -- an odd-degree term running off to -1e11 and -1e14 -- where the point reported is an artefact of the path in both.
At the factory setting, fminimax's own documented example (five objectives in two variables, from [0.1; 0.1]), this block answers x = [3.99999986409303; 4.00000013590545] in 7 iterations and 13 evaluations, flag 4 -- fminimax's figures to every digit MATLAB prints.
The three HDL targets carry the iteration in
real: SIMULATION-ONLY, quantized at the ports.
Sample results#
No sample run is committed for this block. Samples come from the headless harness (DOCS_PLAN.md P8.1) into docs/generated/samples/; until one exists this block's behaviour is witnessed by the parity and export-verification suites, not by a plot here.