Optimization Toolbox: Reference

Exact controls, worksheet columns, publication schemas, status definitions, limits, diagnostics, and troubleshooting for the Optimization Toolbox.

← Optimization Toolbox overview · Getting started · Modeling guide · Solver guide · Examples

Control reference

Control Default Valid range/values Used by
Active model product_mix Model ID in Start catalog All workflows
Objective direction Auto Auto / Minimize / Maximize Auto preserves worksheet Sense; explicit override is single-objective only
Scenario Baseline Baseline or enabled scenario name All workflows
Solver mode Recommended Recommended / Local / MultiStart / Global Solve-strategy dispatch; class/strategy compatibility is validated
Random seed 42 Integer MultiStart / Differential Evolution
Global budget 120 30–2000 Differential Evolution / SHGO sampling
Pareto points 9 3–31 Multiobjective epsilon sweep

The notebook also exposes an Analysis view control with Auto and Solver comparison.

Input range reference

The beta reads fixed authored bands from the workbook. The last row below is the current notebook input boundary, not a theoretical solver limit.

Input Range Approx. data-row capacity
Solve controls Start!A5:B12 7 controls
Model catalog Start!D5:H14 9 model rows in current beta
Variables Variables!A5:J40 35 data rows
Parameters Variables!L5:P25 20 data rows
Objective definitions Linear Model!A5:F30 25 data rows
Linear objective terms Linear Model!H5:L40 35 data rows
Constraint definitions Linear Model!N5:T40 35 data rows
Constraint terms Linear Model!V5:Z80 75 data rows
Quadratic terms Quadratic & Conic!A5:F20 15 data rows
Expressions Expressions!A5:I30 25 data rows
Scenarios Scenarios!A5:G20 15 data rows

If an authored model needs to exceed an input band, extend the workbook and corresponding bf.ref(...) boundary together and rerun the template validation gate. Do not assume rows outside the documented range are read automatically.

Input table columns

Model catalog

Model, Label, Expected class, Preferred strategy, Description

Expected class is compared with the compiler’s structural classification and produces a diagnostic on mismatch; it never forces a class. Preferred strategy accepts Recommended, Local, MultiStart, or Global and is consulted only when Start → Solver mode is Recommended.

Closed-enumeration input columns use workbook data validation, and the long model-definition sheets freeze their header rows. Authors should preserve those controls when extending the input bands.

Variables

Model, Variable, Label, Type, LowerBound, UpperBound, InitialValue, Scale, Group, Enabled

Parameters

Model, Parameter, Value, Units, Description

Objective definitions

Model, Objective, Label, Sense, Enabled, Description

Sense must be Minimize or Maximize. Every linear, quadratic, or nonlinear objective term must reference an enabled definition.

Linear objective terms

Model, Objective, Variable, Coefficient, Enabled

Constraint definitions

Model, Constraint, Label, LowerBound, UpperBound, Group, Enabled

Constraint terms

Model, Constraint, Variable, Coefficient, Enabled

Quadratic terms

Model, Objective, Variable1, Variable2, Coefficient, Enabled

Expressions

Model, ExpressionId, Role, Objective, Expression, LowerBound, UpperBound, Weight, Enabled

Scenarios

Model, Scenario, TargetType, Target, Field, Value, Enabled

See Modeling guide for field semantics.

Published output reference

summary

Two columns: Metric, Value.

Published metrics:

  1. Model
  2. Problem class
  3. Scenario
  4. Solver
  5. Status
  6. Objective value
  7. Max violation
  8. Runtime (s)
  9. Evaluations / nodes
  10. Random seed
  11. Termination

The summary keeps the termination text concise for the worksheet surface; messages longer than 60 characters are abbreviated. The full solver termination message is also published as a Solver termination row in Diagnostics.

Workbook spill: Results!A5:B16.

variables

Columns:

Column Meaning
Variable Machine variable name
Value Returned decision value
Lower Active lower bound after scenario
Upper Active upper bound after scenario
Bound status At lower / At upper / Interior / n/a
Marginal Reserved for solver-specific variable marginal; current beta generally publishes n/a

Workbook spill: Results!D5:I28.

constraints

Columns:

Column Meaning
Constraint Constraint ID
Activity \(A_i x\) at the returned decision
Lower Active lower activity bound
Upper Active upper activity bound
Slack Minimum distance to an active finite side
Binding Yes when absolute slack <= 1e-6
Marginal LP constraint marginal when available; otherwise n/a
Marginal side equality, lower, or upper for the active LP side; otherwise n/a

Workbook spill: Results!K5:R32.

analysis

The columns depend on analysis type.

Pareto analysis

Point, objective 1, objective 2, objective-2 limit, Status, Solver, Max violation, Method.

Solver comparison

Solver, Status, Objective, Feasible, Max violation, Runtime (s), Evaluations, Seed.

Standard model analysis

Analysis, Scenario, Status, Objective, Max violation, Solver, Primary delta, Notes.

For LP, additional rows report constraint marginals.

Workbook spill: Analysis!A5:H34.

diagnostics

Columns:

  • Severity
  • Check
  • Detail

Typical checks include:

  • problem classification;
  • discrete variable count;
  • scaling warning;
  • global-result semantics;
  • QP backend limitation;
  • independent feasibility check;
  • runtime architecture;
  • MATLAB relationship/capability disclaimer.

Workbook spill: Diagnostics!A5:C28.

Status glossary

Status Meaning Typical families
OPTIMAL Backend supports an optimality claim and terminated successfully LP, MILP
LOCAL_OPTIMUM Local numerical method succeeded and independent feasibility passed QP, NLP, least squares
FEASIBLE_SOLUTION Acceptance criteria passed without a stronger optimum claim Equations; some fallback cases
BEST_FOUND Best independently feasible candidate among repeated/bounded search methods NLP with MultiStart / Global strategy
PARETO_SET Nondominated tradeoff table generated Multiobjective
INFEASIBLE Mathematical-programming backend reports infeasibility LP, MILP
UNBOUNDED Mathematical-programming backend reports unbounded objective LP, MILP
FAILED Solve or independent acceptance does not justify another status Any

Feasibility tolerance

The shared acceptance threshold is 1e-6 maximum modeled violation.

Violation includes:

  • lower-bound shortfall;
  • upper-bound exceedance;
  • integrality distance to nearest integer;
  • linear ranged-constraint violation;
  • supported nonlinear ranged-constraint violation.

A candidate can therefore have a favorable objective and still be rejected.

Expression reference

Operators

+, -, *, /, **, unary +, unary -

Functions

exp, log, sqrt, sin, cos, tanh, abs, minimum, maximum

Disallowed examples

np.log(x)          # attribute access
x[0]               # indexing
__import__('os')    # arbitrary function/name
foo(x)             # unknown function
sin(x, dtype=...)  # keyword argument

Domain responsibility

The parser validates syntax and names; it cannot make an invalid mathematical domain meaningful. For example, log(x) still requires positive x during evaluation. Use variable bounds and model design to keep expressions in valid domains.

Scenario target reference

TargetType Target syntax Field
Parameter parameter name ignored by current assignment logic
VariableBound variable name LowerBound / UpperBound
ObjectiveCoefficient Objective|Variable conventionally Coefficient
ConstraintBound constraint ID LowerBound / UpperBound

Unsupported target types or fields raise an error.

Solver-specific limits

LP

  • Uses HiGHS.
  • Constraint marginals available for optimal results.
  • Full allowable-range sensitivity not published.

MILP

  • Continuous/integer/binary only.
  • Backend time limit: 10 seconds.
  • Node count published when available.

QP/NLP

  • SLSQP local solver.
  • Max iterations: 600.
  • ftol: 1e-9 for SLSQP.
  • No automatic convexity certificate.

Least squares/equations

  • Maximum function evaluations: 1000.
  • xtol, ftol, gtol: 1e-11.
  • Variable bounds supported.

Global strategy

  • The mathematical class remains NLP; Global is a solve strategy.
  • Finite bounds required on every variable.
  • Differential Evolution population size fixed at 6.
  • Differential Evolution iteration count derived from budget and dimension, clipped to a small browser-safe range.
  • Differential Evolution tolerance: 1e-7.
  • Differential Evolution polishing enabled.
  • Single worker.
  • SHGO sample count capped at 120 in the current implementation.
  • MultiStart/global comparison uses seven local starts.
  • The current Global adapter rejects general linear or nonlinear constraints; validate constrained NLPs with Local or MultiStart instead.

Pareto

  • Exactly two named objectives.
  • Current method assumes linear objectives/constraints suitable for HiGHS LP.
  • Pareto point control: 3–31.

Troubleshooting

Unknown active model

Message: Unknown active model ...

Check that Start → Active model exactly matches the Model value in the Start catalog.

No enabled variables

Message: model has no enabled variables.

Confirm Variables rows use the active Model ID and Enabled is truthy.

Unsupported variable type

Use exactly Continuous, Integer, or Binary. Typos fail intentionally.

Invalid variable or parameter name

Use letters/digits/underscores and do not start with a digit.

Lower bound exceeds upper bound

Fix the base bound or selected scenario override.

Scenario not enabled

Scenario names are model-specific. Confirm the Scenarios table has enabled rows for the active Model and exact Scenario name.

Objective/constraint term references undefined name

Check spelling and Model ID on both the term row and definition row.

Unsafe/unsupported expression element

Rewrite the expression using the supported operators/functions. The parser intentionally blocks general Python.

Unknown expression name

Declare the name as a decision variable or parameter, or fix the spelling.

Global search requires finite bounds

Add defensible finite LowerBound and UpperBound values to every active variable or use Local/Recommended mode instead.

Local nonlinear result is FAILED

Inspect:

  • termination message;
  • InitialValue;
  • scaling warning;
  • expression domain;
  • constraint feasibility;
  • maximum violation.

BEST_FOUND instead of OPTIMAL

This is intentional for heuristic/bounded global search. It prevents the workbook from claiming proof it does not have.

LP marginal is n/a

Marginals are only published for supported optimal LP constraint rows. They are not generalized to MILP/NLP/global models.

Model is infeasible

Treat this first as a modeling/business-rule result, not a software bug. Compare lower/upper bounds, conflicting constraints, and scenario overrides. The supplied infeasible fixture demonstrates expected behavior.

Validation reference

The template’s offline_test.py defines one baseline plus eight model-switch scenarios so every major problem class is exercised.

The full offline generation gate validates:

  • workbook regeneration;
  • package/notebook parity;
  • publication/spill contract;
  • notebook structure;
  • native execution;
  • browser/Pyodide execution;
  • poster generation;
  • Univer edit/restore behavior;
  • runtime formatting/presentation checks.

These tests validate the generic fixture library, not the correctness of an author’s future domain model. Operational workbooks should add domain-specific acceptance expectations.

Version and parity policy

This Toolbox is capability-inspired by MATLAB Optimization Toolbox and Global Optimization Toolbox. It is not a MATLAB API compatibility layer.

When the Python method differs, documentation should state:

  1. the Excel problem the capability addresses;
  2. the actual backend used;
  3. the strength of the result claim;
  4. what MATLAB capability it most closely corresponds to;
  5. what remains unavailable.

That policy is more useful than a raw function-count parity claim.