Dev doc #237

doc/source/components.rst

@@ -417,6 +417,8 @@ tools can be adapted to convert the instance for a particular solver.
 Flat model converters
 ~~~~~~~~~~~~~~~~~~~~~
 
+New: expression trees added. See Gurobi and SCIP drivers.
+
 `mp::FlatConverter` and `mp::MIPFlatConverter` represent and
 convert flat models (i.e., models :ref:`without expression trees <flat-solvers>`).
 Typically, a flat model

doc/source/drivers.rst

@@ -6,8 +6,8 @@ Solver drivers
 
 .. _flat-solvers:
 
-'Flat API' solvers
-------------------
+'Flat API' and new expression-based solvers
+-----------------------------------------------
 
 For solvers with traditional 'flat' (no expression trees) APIs,
 non-linear AMPL expressions need to be reformulated.
@@ -19,20 +19,24 @@ For example, ``max(a, b)`` is translated into a constraint
 
 which is in turn reformulated for
 MIP or passed to the solver natively (e.g., Gurobi: `GRBaddgenconstrMax`).
-See the :ref:`modeling-guide`.
+
+A recent extension to MP allows passing expression trees
+to solvers, see :ref:`supported-constraints`.
 
 There are several implementations, see :ref:`modeling-overview`.
+See also the :ref:`modeling-guide`.
 
 
 .. _expression-solvers:
 
-Expression-based solvers
-------------------------
+Old-API expression-based solvers
+--------------------------------------
 
-Expression-based solver APIs can efficiently map
-NL forests.
+Some older drivers map directly from NL file's model, without
+exploiting the automatic reformulation capabilites of MP.
 For example, AMPL expression
-``exp()`` maps to IBM ILOG Concert's ``IloExponent``. The library
+``exp()`` maps to IBM ILOG Concert's ``IloExponent``.
+The MP library
 has the following C++ drivers of this kind, all of which support
 `AMPL extensions for logic and constraint programming`__:
 

doc/source/howto.rst

@@ -36,7 +36,7 @@ Recommended setup
 ~~~~~~~~~~~~~~~~~~~~~
 
 The recommended driver structure is to use the
-:ref:`Backend class hierarchy with FlatModelAPI <recommended-driver-logic>`.
+:ref:`Backend class hierarchy with FlatModelAPI or ExprModelAPI <recommended-driver-logic>`.
 Examples: :ref:`flat-solvers`.
 
 
@@ -204,6 +204,89 @@ the following:
    ACCEPT_CONSTRAINT(LinConGE, Recommended, CG_Linear)
    void AddConstraint(const LinConGE& lc);
 
+   /// NEW: expression trees
+   //////////////////////////// EXPRESSION TREES ////////////////////////////
+   /// Handle expression trees: inherit basic API
+   USE_BASE_EXPRESSION_HANDLERS(BaseModelAPI)
+
+   /// Overall switch
+   ACCEPT_EXPRESSION_INTERFACE(Recommended);
+
+   /// GetVarExpression(\a i): expression representing variable 0<=i<n_var.
+   /// Only called for 'nonlinear' variables.
+   Expr GetVarExpression(int i) { return MakeVarExpr(i); }
+
+   /// GetZeroExpr(): constant 0.0 expression.
+   /// Can be used to represent empty expression in an NLConstraint.
+   Expr GetZeroExpression() { return MakeEmptyExpr(); }
+
+   /// Gurobi 12 has no classical NL range constraint
+   ACCEPT_CONSTRAINT(NLConstraint, NotAccepted, CG_Algebraic)
+
+   /// NLAssignEQ: algebraic expression expicifier.
+   /// Meaning: var == expr.
+   /// @note Accessors: GetName(), GetExpression(nle), GetVariable(nle).
+   ACCEPT_CONSTRAINT(NLAssignEQ, Recommended, CG_General)
+   void AddConstraint(const NLAssignEQ& nle);
+   /// NLAssignLE: algebraic expression expicifier in positive context.
+   /// Meaning: var <= expr.
+   /// @note Accessors: GetName(), GetExpression(nle), GetVariable(nle).
+   ACCEPT_CONSTRAINT(NLAssignLE, Recommended, CG_General)
+   void AddConstraint(const NLAssignLE& nle);
+   /// NLAssignGE: algebraic expression expicifier in negative context.
+   /// Meaning: var >= expr.
+   /// @note Accessors: GetName(), GetExpression(nle), GetVariable(nle).
+   ACCEPT_CONSTRAINT(NLAssignGE, Recommended, CG_General)
+   void AddConstraint(const NLAssignGE& nle);
+
+   /// @brief Accept NLAffineExpr.
+   /// @note Use accessors, not methods;
+   /// - GetLinSize(le), GetLinCoef(le, i), GetLinTerm(le, i);
+   ///   GetConstTerm(le).
+   ACCEPT_EXPRESSION(NLAffineExpression, Recommended);
+   Expr AddExpression(const NLAffineExpression& le);
+
+   /// Accept NLQuadExpr.
+   /// @note Use accessors, not methods;
+   /// - GetLinSize(le), GetLinCoef(le, i), GetLinTerm(le, i);
+   ///   GetQuadSize(le), GetQuadCoef(le, i),
+   ///   GetQuadTerm1(le, i), GetQuadTerm2(le, i);
+   ///   GetConstTerm(le).
+   ACCEPT_EXPRESSION(NLQuadExpression, Recommended);
+   Expr AddExpression(const NLQuadExpression& le);
+
+   /// Each expression can be accepted as a proper expression,
+   /// or as a flat functional constraint var <=/==/>= expr
+   /// (in this case, with variables as arguments).
+   /// The uequality/inqeuality type of the flat constraint is
+   /// determied by GetContext().
+   ///
+   /// @note Use accessor: GetArgExpression(ee, 0)
+   /// - don't AbsExpression's methods.
+   ///
+   /// Similar for other expression types.
+
+
+   ACCEPT_EXPRESSION(ExpExpression, Recommended)
+   Expr AddExpression(const ExpExpression& );
+   ACCEPT_EXPRESSION(ExpAExpression, Recommended)
+   Expr AddExpression(const ExpAExpression& );
+   ACCEPT_EXPRESSION(LogExpression, Recommended)
+   Expr AddExpression(const LogExpression& );
+   ACCEPT_EXPRESSION(LogAExpression, Recommended)
+   Expr AddExpression(const LogAExpression& );
+   /// @note Use accessor: GetParameter(pe, 0)
+   ///   - don't use PowExpression's methods.
+   ACCEPT_EXPRESSION(PowExpression, Recommended)
+   Expr AddExpression(const PowExpression& );
+   ACCEPT_EXPRESSION(SinExpression, Recommended)
+   Expr AddExpression(const SinExpression& );
+   ACCEPT_EXPRESSION(CosExpression, Recommended)
+   Expr AddExpression(const CosExpression& );
+
+   ACCEPT_EXPRESSION(DivExpression, Recommended)
+   Expr AddExpression(const DivExpression& );
+
 
 Note that after `InitProblemModificationPhase()` has been called,
 you can access the `mp::FlatModelInfo` object with the inherited method

solvers/gurobi/gurobimodelapi.h

@@ -224,11 +224,11 @@ class GurobiModelAPI :
   /// Each expression can be accepted as a proper expression,
   /// or as a flat functional constraint var <=/==/>= expr
   /// (in this case, with variables as arguments).
-  /// The uequality/inqeuality type of the flat constraint is
+  /// The equality/inequality type of the flat constraint is
   /// determied by GetContext().
   ///
   /// @note Use accessor: GetArgExpression(ee, 0)
-  /// - don't AbsExpression's methods.
+  /// - don't use ...Expression's methods.
   ///
   /// Similar for other expression types.