Multi-obj documentation #239

doc/CMakeLists.txt

@@ -30,6 +30,7 @@ add_prefix(mp_docs ${DOC_BASEDIR}/
     model-guide.rst
     modeling-overview.rst
     modeling-expressions.rst
+    modeling-mo.rst
     modeling-efficiency.rst
     modeling-numerics.rst
     modeling-tools.rst

doc/source/features-guide.rst

@@ -883,9 +883,10 @@ Multiple objectives
 Many real world problems have multiple objectives; often this scenario is tackled by blending all the objectives
 by linear combination when formulating the model, or by minimizing each unwanted objective deviations from a pre-specified
 goal.
-Many solvers can facilitate the formulation; the available functionalities are solver-specific; at MP level
-they accessible via the main option ``obj:multi``. Consult the solver documentation for the functionalities available
-on your solver.
+Many solvers can facilitate the formulation; the available functionalities are solver-specific. For other solvers,
+MP :ref:`emulates the multi-objective capability <multiple-objectives>`. Consult the ``obj:multi``
+:ref:`option <solver-options>` documentation
+for the functionalities available on your solver.
 
 .. list-table::
    :header-rows: 0

doc/source/model-guide.rst

@@ -13,8 +13,9 @@ Ever wondered how to model logical and non-linear constraints? For example:
 
 - Piecewise-linear approximation of *y = sin(x)*.
 
-MP automates many of such modeling tasks by reformulating AMPL nonlinear
-constraints suitably for the given solver.
+Moreover, MP supports :ref:`multiple-objectives`.
+MP automates many of such modeling tasks by reformulating AMPL models
+suitably for the given solver.
 A series of small modeling tasks like these are handled in the
 `MP Modeling Series <https://ampl.com/streamlit/Modeling_Tips>`_,
 while below follows a comprehensive guide.
@@ -25,6 +26,7 @@ while below follows a comprehensive guide.
    self
    modeling-overview
    modeling-expressions
+   modeling-mo
    modeling-efficiency
    modeling-numerics
    modeling-tools

doc/source/modeling-mo.rst

@@ -0,0 +1,46 @@
+.. _multiple-objectives:
+
+
+Multiple objectives
+----------------------------------
+
+To consider multiple objectives in an AMPL model, use
+:ref:`solver option <solver-options>` ``obj:multi``.
+Otherwise, only the 1st objective is considered
+(or any objective specified by ``obj:no``.)
+
+.. code-block:: ampl
+
+    minimize total_cost {s in STORE}:
+       sum {j in FOOD} cost[s,j] * Buy[j];
+
+    minimize total_number:  sum {j in FOOD} Buy[j];
+
+
+See the
+:ref:`Multi-objective AMPL Colab notebooks <https://colab.ampl.com/tags/multiple-objectives.html>`
+for examples.
+
+
+Blended objectives
+************************************************
+
+By default, all objectives are blended together
+(summed up with the corresponding signs.)
+Suffixes ``.objweight`` can be used to change the individual weights
+and objective senses, according to the option ``obj:multi:weight``.
+
+
+Lexicographical objectives
+********************************************************
+
+To apply hierarchical optimization, use suffix ``.objpriority``,
+as described in the ``obj:multi`` option description.
+
+.. code-block:: ampl
+
+    maximize ReverseSeniority {e in 1..2, i in I: E[i]==e}:
+      sum {t in V[i]: Pr[i, t]==0}
+        S[i] * x[i, t]
+      suffix objpriority (2-e)*S_range + 1 + S[i] - min {j in I} S[j];
+

doc/source/modeling-overview.rst

@@ -13,6 +13,9 @@ Currently available MP-based solvers include:
 - `gurobi <https://github.com/ampl/mp/tree/develop/solvers/gurobi>`_,
   an enhanced interface to the `Gurobi solver <https://ampl.com/products/solvers/solvers-we-sell/gurobi/>`_
 
+- `cplexmp <https://github.com/ampl/mp/tree/develop/solvers/cplexmp>`_,
+  an enhanced interface to the `Gurobi solver <https://ampl.com/products/solvers/solvers-we-sell/cplex/>`_
+
 - `copt <https://github.com/ampl/mp/tree/develop/solvers/copt>`_,
   an interface to `Cardinal Optimizer <https://ampl.com/products/solvers/solvers-we-sell/copt/>`_