fminimax — Minimize the largest of a set of constrained objective values.
fminimax solves a smooth goal-attainment epigraph for a vector objective, retaining every original constraint. The solver uses genuine constrained SQP, not a fixed penalty or a nonsmooth max callback.
Syntax
[x,fval,maxfval,exitflag,output,lambda] = fminimax(fun,x0)
[x,fval,maxfval,exitflag,output,lambda] = fminimax(fun,x0,A,b)
[x,fval,maxfval,exitflag,output,lambda] = fminimax(fun,x0,A,b,Aeq,beq)
[x,fval,maxfval,exitflag,output,lambda] = fminimax(fun,x0,A,b,Aeq,beq,lb,ub)
[x,fval,maxfval,exitflag,output,lambda] = fminimax(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon)
[x,fval,maxfval,exitflag,output,lambda] = fminimax(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options)
[...] = fminimax(problem)Inputs
fun- Type
Any- Required
- Yes
- Default
- —
- Description
- Vector/array objective and optional n-by-m Jacobian.
x0- Type
Any- Required
- Yes
- Default
- —
- Description
- Finite starting array; original shape is preserved.
A- Type
Any- Required
- Yes
- Default
- —
- Description
- Linear inequality matrix or [].
b- Type
Any- Required
- Yes
- Default
- —
- Description
- Linear inequality RHS or [].
Aeq- Type
Any- Required
- Yes
- Default
- —
- Description
- Equality matrix or [].
beq- Type
Any- Required
- Yes
- Default
- —
- Description
- Equality RHS or [].
lb- Type
Any- Required
- Yes
- Default
- —
- Description
- Lower bounds or [].
ub- Type
Any- Required
- Yes
- Default
- —
- Description
- Upper bounds or [].
nonlcon- Type
Any- Required
- Yes
- Default
- —
- Description
- Nonlinear callback [c,ceq] with optional Jacobians, or [].
options- Type
Any- Required
- Yes
- Default
- —
- Description
- Supported scalar options structure, or [].
problem- Type
Any- Required
- Yes
- Default
- —
- Description
- Scalar problem with objective,x0,solver,options and optional constraints/bounds.
Returns
x- Type
Any- Description
- Original-shaped last accepted point.
fval- Type
Any- Description
- Original objective array at x, or [] if unavailable.
maxfval- Type
Any- Description
- Maximum of the original F(:), including with absolute-objective mode.
exitflag- Type
Any- Description
- 1 original KKT; 4 feasible small step; 5 feasible small objective change; 0 limit; -1 observer; -2 local restoration failure; -4 numerical difficulty.
output- Type
Any- Description
- Actual iteration/callback accounting, residuals and goal-attainment algorithm.
lambda- Type
Any- Description
- Six original constraint/bound multiplier fields, excluding generated objective rows, or [] if unavailable.
Returned values from fminimax depend on how many outputs the caller requests.
Errors
RunMat:fminimax:InvalidArgument- When
- Invalid input or unsupported option.
- Message
fminimax: invalid argument
Public inputs and original shapes
FiniteDifferenceStepSize (legacy FinDiffRelStep) accepts a finite strictly positive real floating scalar or vector; a scalar factor expands to every variable. TypicalX must be a finite strictly positive real floating vector with one element per original variable (a scalar for a scalar problem).
Omitted or empty controls resolve to sqrt(eps) for forward differences, eps^(1/3) for existing central-difference routes, and unit TypicalX. Forward offsets use sign(x), with sign(0)=1, times the factor and max(abs(x),TypicalX); central offsets omit that sign. Actual representable bound-feasible offsets own the denominators. Nominal underflow uses adjacent representable feasible points; unusable actual offsets or an overflowing central span refuse before probe callbacks. These controls do not add objective calls or bypass existing evaluation budgets. Fully supplied derivative paths leave these operands dormant, without validating or gathering them.
fminimax accepts fun,x0, optionally followed by complete A/b, Aeq/beq and lb/ub pairs, nonlcon and options. fgoalattain requires fun,x0,goal,weight before the same optional constraints. Empty pairs mean absent constraints; empty bounds leave components unbounded. Scalar problem structures require objective,x0,solver,options, and additionally goal,weight for fgoalattain; optional fields are Aineq,bineq,Aeq,beq,lb,ub,nonlcon.
Every original objective and constraint callback receives x with the original x0 shape. Linear matrices refer to column-major x(:). Returned x preserves x0 shape, and fval preserves the original objective array shape. Goals and weights are finite vectors with one entry per objective. Objective extent and nonlinear constraint extents cannot change. Bounds can contain signed infinity but not NaN; shorter nonempty bounds constrain leading entries and warn. Contradictory bounds return x0, empty fval and exitflag -2 without an objective evaluation.
Attainment model
The solver owns a smooth extra variable gamma and minimizes gamma together with every original constraint. Positive fgoalattain weights seek F_i<=goal_i, using F_i-goal_i-|weight_i|*gamma<=0. Negative weights seek F_i>=goal_i, using goal_i-F_i-|weight_i|*gamma<=0. The original signed weight remains unchanged; its magnitude scales underachievement and overachievement in the selected direction. A negative gamma represents directional overachievement. Minimax uses goals zero and weights one. Zero-weight rows are hard F_i<=goal_i constraints and are never divided by zero.
AbsoluteMaxObjectiveCount for fminimax treats the first k objectives by absolute value, adding both signed rows. EqualityGoalCount for fgoalattain similarly minimizes the first k absolute deviations |F_i-goal_i| using |weight_i|, independently of the original weight sign, rather than rewarding one-sided overachievement. A zero-weight equality goal imposes F_i=goal_i. The remaining goals keep their selected one-sided directions. Counts are nonnegative and cannot exceed the objective extent. At least one nonzero weight is necessary, but not sufficient, for a bounded attainment objective; an all-zero-weight model does not produce a claimed finite optimum.
The goal-attainment SQP model uses the existing cooperative sparse convex quadratic kernel with independent original subproblem KKT checks, local feasibility restoration and a Powell-damped Lagrangian BFGS model. The attainment coordinate has exactly zero model curvature. Default MeritFunction='multiobj' globalizes the worst normalized objective and original hard constraints; 'singleobj' uses the ordinary scalar attainment merit. Proposed gamma is retained independently, not reset after line search. When worst-objective merit is flat, a separate correction filter requires sufficient original epigraph-feasibility improvement without worsening the true worst objective. A gamma-only trial reuses the same original evaluated values/Jacobians and changes only exact affine gamma contributions. It invokes no objective or constraint callback and consumes no evaluated-point budget.
Gradients, budgets and callbacks
Without gradients, bound-feasible forward differences are used; FiniteDifferenceType='central' selects centered differences using actual feasible representable steps. The extra attainment column is exact and never generates finite-difference callbacks. SpecifyObjectiveGradient=true requests [F,G], where G has numel(x0) rows and numel(F) columns. With nonlinear constraints, analytic derivatives are effective only when both SpecifyObjectiveGradient and SpecifyConstraintGradient are true; then nonlcon returns [c,ceq,GC,GCeq], with one gradient column per corresponding constraint. Otherwise the folded objective/constraint rows are differenced. Dormant constraint-gradient controls are not gathered or invoked.
MaxFunctionEvaluations counts actual original-x evaluation points, not the number of synthetic epigraph rows. At a point, objective and nonlinear constraint callbacks share one point charge; output separately records their actual call counts. A trial and its complete derivative sweep cannot overrun the hard limit. Original callback exceptions and cancellation retain their cause and do not become line-search retries. Only genuine nonfinite/complex numerical results or original-model arithmetic overflow can reject a numerical trial.
OutputFcn accepts the original-context init/iter/done observer contract, including handle lists. It receives original-shaped x, original-shaped objective fval, attainfactor, original-x search direction, counts, step and residual metadata. Gradient metadata is the public n-by-m objective Jacobian when available, retained sparsely; it is empty when full derivatives are unavailable. Observers do not replay the objective.
Controls and supported scope
Supported controls are MaxIterations/MaxIter (default 400), MaxFunctionEvaluations/MaxFunEvals (default 100*numel(x0)), ConstraintTolerance/TolCon, OptimalityTolerance, FunctionTolerance, StepTolerance/TolX (all default 1e-6), FiniteDifferenceType/FinDiffType, SpecifyObjectiveGradient, SpecifyConstraintGradient, Display, OutputFcn, MeritFunction and the corresponding first-objective count. Limits and tolerances can be zero. Legacy TolFun applies to function and optimality tolerances; contradictory manual legacy/modern bindings are rejected. Constructor merge precedence uses only the ordinary transient explicit/imported/default origins.
Display supports off, none, iter and final. There is no accepted Algorithm alias: output.algorithm reports the actual goal-attainment-sqp mechanism. Scaling beyond derivative probe scaling, MaxSQPIter, TolConSQP, relative line-search bounds, plotting and parallel differences are not implemented; unsupported fields are rejected rather than ignored. These additional controls remain outside the supported API.
Outputs and guarantees
Up to six outputs are x,fval,maxfval-or-attainfactor,exitflag,output,lambda. fminimax maxfval is max(fval(:)), including when the optimization treats a first subset by absolute value. fgoalattain returns the actual accepted attainment factor. Outputs come from retained evaluated data, with no extra callbacks to fill outputs. Unavailable objective values and multiplier estimates are empty.
Flag 1 requires original augmented feasibility, Lagrangian stationarity, multiplier-sign and complementarity checks. Flag 4 is a feasible small original-x step; flag 5 is a feasible small objective change, neither promising first-order stationarity. Flag 0 is a hard iteration/point limit; -1 is an observer stop; -2 is contradictory bounds or failed local restoration, not a general global nonlinear infeasibility certificate; -4 is numerical difficulty without a minimum claim.
Lambda fields lower,upper,ineqlin,eqlin,ineqnonlin,eqnonlin preserve original variable and supplied constraint identities. Generated objective rows participate in KKT but are not appended to user ineqnonlin. Fixed-coordinate finite differences do not invent full derivatives: complete first-order success and multiplier publication are withheld when required full derivatives are unavailable. Output includes iterations, funcCount, objectiveCallCount, constraintCallCount, lssteplength, stepsize, constrviolation, firstorderopt, algorithm and message. Optional residuals and line-search length are empty if unavailable.
Execution and compatibility
This is a cooperative host numerical solver on native and WebAssembly targets. Callback dispatch, provider transfer, cancellation and publication use the original invocation context. Transparent Automatic arrays follow ordinary host materialization; Explicit gpuArray data requires the named host-gather extension, and unproven resident intent is refused. This is not a GPU or distributed optimizer.
Sparse matrices/Jacobians, Single data, exact native-integer/logical data/results, and native-integer controls have separate named RunMat extensions. Ordinary floating controls do not need the Single-data extension. Integers must preserve exact binary64 conversion, and counts must fit host indices. Strict gates precede transfers for affected roles. Finite host-memory execution is refused before callback and solver workspace; no complete finite-memory bound is claimed.
Examples
Minimize the larger quadratic
fun=@(x)[(x-1)^2 (x+1)^2];
[x,F,m,flag]=fminimax(fun,2)Minimize an absolute objective while reporting original F
options=optimoptions('fminimax','AbsoluteMaxObjectiveCount',1,'Display','off');
[x,F,m,flag]=fminimax(@(x)[x;-5],-1.5,[],[],[],[],-2,-1,[],options)Using fminimax with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how fminimax changes the result.
Run a small fminimax example, explain the result, then change one input and compare the output.
Related Math functions
Optim
acceptancesa · annealingboltz · annealingfast · coneprog · crossoverarithmetic · crossoverheuristic · crossoverintermediate · crossoverlaplace · crossoverscattered · crossoversinglepoint · crossovertwopoint · eqnproblem · EquationProblem.solve · EquationProblem.subsasgn · EquationProblem.subsref · evaluate · fgoalattain · fitscalingprop · fitscalingrank · fitscalingshiftlinear · fitscalingtop · fminbnd · fmincon · fminsearch · fminunc · fseminf · fsolve · fzero · ga · gacreationlinearfeasible · gacreationnonlinearfeasible · gacreationsobol · gacreationuniform · gacreationuniformint · gaplotbestf · gaplotbestindiv · gaplotdistance · gaplotexpectation · gaplotgenealogy · gaplotmaxconstr · gaplotrange · gaplotscorediversity · gaplotscores · gaplotselection · gaplotstopping · integerConstraint · integral · intlinprog · linprog · lsqcurvefit · lsqlin · LsqlinWarmStart.subsasgn · LsqlinWarmStart.subsref · lsqnonlin · lsqnonneg · mutationadaptfeasible · mutationgaussian · mutationpositivebasis · mutationpower · mutationuniform · optimexpr · optimget · OptimizationConstraint.evaluate · OptimizationConstraint.subsasgn · OptimizationConstraint.subsref · OptimizationExitflag.double · OptimizationExitflag.eq · OptimizationExitflag.ne · OptimizationExitflag.string · OptimizationExpression.acos · OptimizationExpression.acosh · OptimizationExpression.acot · OptimizationExpression.acoth · OptimizationExpression.acsc · OptimizationExpression.acsch · OptimizationExpression.asec · OptimizationExpression.asech · OptimizationExpression.asin · OptimizationExpression.asinh · OptimizationExpression.atan · OptimizationExpression.atanh · OptimizationExpression.cat · OptimizationExpression.cos · OptimizationExpression.cosh · OptimizationExpression.cot · OptimizationExpression.coth · OptimizationExpression.csc · OptimizationExpression.csch · OptimizationExpression.ctranspose · OptimizationExpression.cumprod · OptimizationExpression.cumsum · OptimizationExpression.diag · OptimizationExpression.diff · OptimizationExpression.dot · OptimizationExpression.eq · OptimizationExpression.evaluate · OptimizationExpression.exp · OptimizationExpression.ge · OptimizationExpression.horzcat · OptimizationExpression.ldivide · OptimizationExpression.le · OptimizationExpression.log · OptimizationExpression.mean · OptimizationExpression.minus · OptimizationExpression.mldivide · OptimizationExpression.mpower · OptimizationExpression.mrdivide · OptimizationExpression.mtimes · OptimizationExpression.norm · OptimizationExpression.plus · OptimizationExpression.power · OptimizationExpression.prod · OptimizationExpression.rdivide · OptimizationExpression.reshape · OptimizationExpression.sec · OptimizationExpression.sech · OptimizationExpression.sin · OptimizationExpression.sinh · OptimizationExpression.sqrt · OptimizationExpression.subsasgn · OptimizationExpression.subsref · OptimizationExpression.sum · OptimizationExpression.tan · OptimizationExpression.tanh · OptimizationExpression.times · OptimizationExpression.trace · OptimizationExpression.transpose · OptimizationExpression.uminus · OptimizationExpression.uplus · OptimizationExpression.vertcat · OptimizationExpression.zeros · OptimizationExpression.zerosLike · OptimizationProblem.solve · OptimizationProblem.subsasgn · OptimizationProblem.subsref · OptimizationVariable.subsasgn · OptimizationVariable.subsref · optimoptions · optimplotconstrviolation · optimplotfirstorderopt · optimplotfunccount · optimplotfval · optimplotfvalconstr · optimplotmilp · optimplotstepsize · optimplotx · optimproblem · optimset · optimvar · optimwarmstart · particleswarm · patternsearch · psplotbestf · psplotbestx · psplotfuncount · psplotmaxconstr · psplotmeshsize · pswcreationuniform · pswplotbestf · quad · quadprog · QuadprogWarmStart.subsasgn · QuadprogWarmStart.subsref · saplotbestf · saplotbestx · saplotf · saplotstopping · saplottemperature · saplotx · savemilpsolutions · secondordercone · selectionremainder · selectionroulette · selectionstochunif · selectiontournament · selectionuniform · simulannealbnd · solve · surrogateopt · surrogateoptplot · temperatureboltz · temperatureexp · temperaturefast
Elementwise
abs · angle · besselj · bsxfun · complex · conj · double · eps · erf · erfcinv · exp · expm1 · flintmax · gamma · gammaln · heaviside · hypot · imag · int16 · int32 · int64 · int8 · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · times · typecast · uint16 · uint32 · uint64 · uint8
Trigonometry
acos · acosd · acosh · acotd · acscd · asecd · asin · asind · asinh · atan · atan2 · atan2d · atand · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Reduction
all · any · bounds · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · maxk · mean · median · min · mink · movmax · movmean · movmedian · movmin · movprod · movstd · movsum · movvar · nnz · prod · rms · std · sum · trapz · var
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Signal
blackman · butter · buttord · cheb2ord · conv · conv2 · deconv · downsample · envelope · filter · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · periodogram · pulstran · pwelch · rectpuls · resample · sawtooth · sinc · spectrogram · square · tripuls · unwrap · upsample · zplane
Factor
chol · decomposition · decomposition.ctranspose · decomposition.mldivide · decomposition.mrdivide · decomposition.mtimes · decomposition.rdivide · decomposition.subsref · decomposition.times · decomposition.uminus · decomposition.uplus · eig · eigs · gmres · ichol · ilu · lu · ordeig · ordqz · ordschur · pcg · qr · qz · rsf2csf · schur · svd
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Interpolation
griddedInterpolant · griddedInterpolant.subsref · interp1 · interp1q · interp2 · pchip · ppval · spline
Integer Division
Source you can read
Every RunMat function's source is public. Read exactly how fminimax is executed, line by line, in Rust.
- View the source for fminimax in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.