diff --git a/doc/source/modeling-expressions.rst b/doc/source/modeling-expressions.rst index eb1f15f89..ed07830f7 100644 --- a/doc/source/modeling-expressions.rst +++ b/doc/source/modeling-expressions.rst @@ -632,18 +632,21 @@ Handling in Gurobi ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For Gurobi, the following univariate nonlinear functions are instead handled natively: -**exp**, **log**, **^**, **sin**, **cos**, **tan**. -After suitable transformations, the MP interface sends Gurobi the expressions that use +**exp**, **log**, **^**, **sin**, **cos**, **tan**, +as part of Gurobi's new MINLP capability --- +`global nonlinear solving `_ via spatial branching. +After suitable transformations, MP interface sends Gurobi +:ref:`expressions trees ` that use these functions. -Gurobi 11 defaults to piecewise-linear approximation of these functions -as part of its preprocessing. However, Gurobi :ref:`option ` ``alg:global`` -(``pre:funcnonlinear``) sets the default to the new MINLP capability --- -`global nonlinear solving `_ via spatial branching: +Gurobi 12 defaults to proper nonlinear handling of these functions. +Alternatively it allows their piecewise-linear approximation +as part of preprocessing. Gurobi :ref:`option ` ``alg:global`` +(``pre:funcnonlinear``) can be used to apply piecewise-linear approximation: .. code-block:: ampl - ampl: option gurobi_options 'global=1'; solve; + ampl: option gurobi_options 'global=-1'; solve; For individual constraints and objectives, the choice of global solving vs piecewise-linear approximation can be performed via the ``.global`` suffix: diff --git a/doc/source/modeling-tools.rst b/doc/source/modeling-tools.rst index 97669b79f..b6a08fd5a 100644 --- a/doc/source/modeling-tools.rst +++ b/doc/source/modeling-tools.rst @@ -16,6 +16,8 @@ This sections gives a technical list of accepted constraints and expressions, as well as control options for their reformulations. +.. _flat-vs-expressions + Flat constraints vs expression trees ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -24,16 +26,18 @@ to be submitted as a *flat constraint* with an introduced auxiliary variable for the expression result: -```ampl +.. code-block:: ampl + aux_var = max(x, y); -``` + Same or different solvers allow an alternative way, namely *expression trees* or *complete formulas*: -```ampl - s.t. NLConstraint1: 2*x + 4*exp(16 - 2*sin(x + y^2)) <= 19; -``` +.. code-block:: ampl + + s.t. NLConstraint1: 2*x + 4*exp(16 - 2*sin(x + y^2)) <= 19; + In the latter case, expression ``exp(16 - 2*sin(x + y^2))`` is passed to the solver as a single formula using @@ -53,17 +57,21 @@ Reformulation options Sometimes it is handy to disable all automatic reformulations, for example, to test manual modeling of high-level constructs. For that, declare all contraints as natively accepted by the solver: -set :ref:`MP solver option ` ``acc:_all=2`` +set :ref:`MP solver option ` ``acc:_all=2``. Vice versa, to force full linearization, set ``acc:_all=0``. Alternatively, to disable specific reformulations, declare them as natively accepted individually: -e.g., ``acc:alldiff=2``. In detail, a constraint's or expression's +e.g., ``acc:alldiff=2``. Or, to apply MP reformulation, +despite the solver natively accepting the construct, +set the option to 0: ``acc:or=0``. +In detail, a constraint's or expression's individual acceptance option can have some or all of the following values: -``` -acc:sin +.. code-block:: bash + + acc:sin Solver acceptance level for 'SinConstraint' as either constraint or expression, default 4: @@ -74,24 +82,30 @@ acc:sin 3 - Accepted as expression but automatic redefinition will be used where possible 4 - Accepted as expression natively and preferred -``` + To uniformly control all expressions, use option `acc:_expr`: -``` -acc:_expr +.. code-block:: bash + + acc:_expr Solver acceptance level for all expressions, default 1: 0 - Not accepted, all expressions will be treated as flat constraints, or redefined 1 - Accepted. See the individual acc:... options -``` + + Value 1 passes expression trees to the solver (if natively supported; corresponds to value 4 in the individual options), value 0 uses flat constraints (again, those which are natively supported; corresponds to value 2 or 0 in the individual options.) +Finally, the kinds of reformulations which are applied when needed, +along with corresponding configuration settings, +are described in :ref:`expressions_supported`. + To find out which constraints or expressions are natively supported by the solver, or, more generally, understood by MP,