diff --git a/doc/source/modeling-expressions.rst b/doc/source/modeling-expressions.rst index a953f14b5..eb1f15f89 100644 --- a/doc/source/modeling-expressions.rst +++ b/doc/source/modeling-expressions.rst @@ -40,7 +40,8 @@ of various kinds; for example, max((x+1)*x*z, y, y-z)<=3 and exp(y)<=12); AMPL represents these combinations as expression trees, -which are sent to MP-based solver interfaces to be processed as solvers require. +which are sent to MP-based solver interfaces to be processed as solvers require, +or user desires. Indexing over sets is a common feature of AMPL expressions. The examples below use two kinds of indexing expressions, @@ -88,9 +89,13 @@ Thus where necessary, the MP interface constructs an approximate closed region b use of a small tolerance. For example, if x is minimized subject to x > 5, then any x value greater than 5 is not minimal, and any x value less than or equal to 5 is not feasible. Thus, to insure that a minimum is well defined, the constraint must -be changed to x >= 5 + eps for some small constant eps. Each solver has its own -default value of the eps constant, which can be adjusted through -an :ref:`option setting `. +be changed to x >= 5 + eps for some small constant eps. The value of the +eps constant can be adjusted through the :ref:`MP option setting ` +``cvt:mip:eps``. + +The reformulations performed by MP can be configured, as described +in :ref:`supported-constraints`. Those performed by AMPL itself, +can be configured by `AMPL options `_. Conditional operators diff --git a/doc/source/modeling-tools.rst b/doc/source/modeling-tools.rst index 4bca6afcf..97669b79f 100644 --- a/doc/source/modeling-tools.rst +++ b/doc/source/modeling-tools.rst @@ -9,24 +9,99 @@ This section highlights some tools aiding modeling and solving. .. _supported-constraints: -Supported constraints and reformulations -************************************************ +Supported constructs and configuring the reformulations +*************************************************************** -Sometimes it is handy to disable all automatic reformulations. +This sections gives a technical list of accepted constraints +and expressions, as well as control options for their +reformulations. + +Flat constraints vs expression trees +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some solvers require each individual expression +to be submitted as a *flat constraint* +with an introduced auxiliary variable for the expression +result: + +```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; +``` + +In the latter case, expression ``exp(16 - 2*sin(x + y^2))`` +is passed to the solver as a single formula using +an expression tree mechanism. This representation allows +more general treatment of nonlinearities in the solver, +usually resulting in better performance and numerical precision. +Examples of MP solvers supporting expression trees are +SCIP 9.1.1 and Gurobi 12. + +Next subsection explains how a user can switch between +flat constraints and formulas, if available, +or force reformulation. + +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: -``acc:_all=2`` (alternatively, disable specific -reformulations, e.g., ``acc:alldiff=2``.) +set :ref:`MP solver option ` ``acc:_all=2`` Vice versa, to force full linearization, set ``acc:_all=0``. -To find out which constraints are natively supported by the solver, +Alternatively, to disable specific +reformulations, declare them as natively accepted individually: +e.g., ``acc:alldiff=2``. In detail, a constraint's or expression's +individual +acceptance option can have some or all of the following values: + +``` +acc:sin + Solver acceptance level for 'SinConstraint' as either constraint or + expression, default 4: + + 0 - Not accepted natively, automatic redefinition will be attempted + 1 - Accepted as constraint but automatic redefinition will be used + where possible + 2 - Accepted as constraint natively and preferred + 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 + 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.) + +To find out which constraints or expressions +are natively supported by the solver, or, more generally, understood by MP, and to control which are reformulated, there are two ways. -Method 1: acceptance options +Querying acceptance options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -List the solver's natively supported constraints, +List the solver's natively supported constraints and expressions, by running the solver executable with the ``-=acc`` command-line switch which lists all solver options starting with the ``acc:`` prefix: @@ -40,7 +115,7 @@ at `AMPL Development `_. .. _full-cons-list: -Method 2: full constraint list +Full constraint list ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ List all constraints known by the MP model converter, including some diff --git a/doc/source/modeling-troublesh.rst b/doc/source/modeling-troublesh.rst index 253dfe49e..0d6eeed67 100644 --- a/doc/source/modeling-troublesh.rst +++ b/doc/source/modeling-troublesh.rst @@ -16,9 +16,10 @@ See sections :ref:`efficiency` and :ref:`numerical_accuracy`. Play with `AMPL options `_ and :ref:`solver-options`. Prominent ones are AMPL presolve -(switch off: ``ampl: option presolve 0;``) and solver's presolve +(switch off: ``ampl: option presolve 0;``), solver's presolve (``ampl: option gurobi_options 'presolve=0';``) and others -(tolerances, *numfocus*, *intfocus*, etc.) +(tolerances, *numfocus*, *intfocus*, etc.), as well as +MP reformulation options, see :ref:`supported-constraints`. To see what MP and/or the solver do with your model, export the solver's received model, and, if possible, the solver's presolved model: diff --git a/test/end2end/cases/categorized/fast/multi_obj/modellist.json b/test/end2end/cases/categorized/fast/multi_obj/modellist.json index 6c5d43c5c..ad3ad4c57 100644 --- a/test/end2end/cases/categorized/fast/multi_obj/modellist.json +++ b/test/end2end/cases/categorized/fast/multi_obj/modellist.json @@ -37,6 +37,7 @@ "tags" : ["linear", "continuous", "multiobj"], "files" : ["dietobj_1000.mod", "dietobj.dat"], "options": { "ANYSOLVER_options": "multiobj=1" }, + "comment": "Combined objective delivers the same values", "values": { "total_cost[\"A&P\"]": 865.55053686471, "total_cost[\"JEWEL\"]": 870.917122405154,