Merge branch 'doc_mcp' of git.dynare.org:JohannesPfeifer/dynare

Ref. !2077

doc/manual/source/the-model-file.rst

@@ -2993,7 +2993,9 @@ Finding the steady state with Dynare nonlinear solver
            ``10``
 
                 Levenberg-Marquardt mixed complementarity problem
-                (LMMCP) solver (*Kanzow and Petra (2004)*).
+                (LMMCP) solver (*Kanzow and Petra (2004)*). The complementarity 
+                conditions are specified with an ``mcp`` equation tag, see
+                :opt:`lmmcp`. 
 
            ``11``
 
@@ -3764,16 +3766,27 @@ speed-up on large models.
        the endogenous variables (such as a ZLB on the nominal interest
        rate or a model with irreversible investment). This option is
        equivalent to ``stack_solve_algo=7`` **and**
-       ``solve_algo=10``. Using the LMMCP solver requires a particular
+       ``solve_algo=10``. Using the LMMCP solver avoids the need for min/max 
-       model setup as the goal is to get rid of any min/max operators
+       operators and explicit complementary slackness conditions in the model
-       and complementary slackness conditions that might introduce a
+       as they will typically introduce a singularity into the Jacobian. This is 
-       singularity into the Jacobian. This is done by attaching an
+       done by setting the problem up as a mixed complementarity problem (MCP) of the form:
-       equation tag (see :ref:`model-decl`) with the ``mcp`` keyword
+
-       to affected equations. This tag states that the equation to
+       .. math::
-       which the tag is attached has to hold unless the expression
+             LB = X   &\Rightarrow   F(X)>0\\
-       within the tag is binding. For instance, a ZLB on the nominal
+ 
-       interest rate would be specified as follows in the model
+             LB\leq X \leq UB &\Rightarrow   F(X)=0\\
-       block::
+
+             X =UB &\Rightarrow   F(X)<0.
+ 
+       where :math:`X` denotes the vector of endogenous variables, :math:`F(X)` the equations
+       of the model, :math:`LB` denotes a lower bound, and :math:`UB` an upper bound. Such a setup
+       is implemented by attaching an equation tag (see :ref:`model-decl`) 
+       with the ``mcp`` keyword to the affected equations. This tag states that 
+       the equation to which the tag is attached has to hold unless the inequality
+       constraint within the tag is binding. 
+
+       For instance, a ZLB on the nominal interest rate would be specified 
+       as follows in the model block::
 
             model;
                ...
@@ -3791,20 +3804,27 @@ speed-up on large models.
        slackness condition). By restricting the value of ``r`` coming
        out of this equation, the ``mcp`` tag also avoids using
        ``max(r,-1.94478)`` for other occurrences of ``r`` in the rest
-       of the model. It is important to keep in mind that, because the
+       of the model. Two things are important to keep in mind. First, because the
        ``mcp`` tag effectively replaces a complementary slackness
        condition, it cannot be simply attached to any
        equation. Rather, it must be attached to the correct affected
        equation as otherwise the solver will solve a different problem
-       than originally intended. Also, since the problem to be solved
+       than originally intended. Second, the sign of the residual of the dynamic 
-       is nonlinear, the sign of the residuals of the dynamic equation
+       equation must conform to the MCP setup outlined above. In case of the ZLB,
-       matters. In the previous example, for the nominal interest rate
+       we are dealing with a lower bound. Consequently, the dynamic equation 
-       rule, if the LHS and RHS are reversed the sign of the residuals
+       needs to return a positive residual. Dynare by default computes the residual 
-       (the difference between the LHS and the RHS) will change and it
+       of an equation ``LHS=RHS`` as ``residual=LHS-RHS``, while an implicit equation 
-       may happen that solver fails to identify the solution path. More
+       ``LHS`` is interpreted as ``LHS=0``. For the above equation this implies
-       generally, convergence of the nonlinear solver is not guaranteed
+ 
-       when using mathematically equivalent representations of the same
+           ``residual= r - (rho*r(-1) + (1-rho)*(gpi*Infl+gy*YGap) + e);`` 
-       equation.
+ 
+       which is correct, since it will be positive if the implied interest rate 
+       ``rho*r(-1) + (1-rho)*(gpi*Infl+gy*YGap) + e`` is  
+       below ``r=-1.94478``. In contrast, specifying the equation as 
+
+            ``rho*r(-1) + (1-rho)*(gpi*Infl+gy*YGap) + e = r;```
+
+       would be wrong.
 
        Note that in the current implementation, the content of the
        ``mcp`` equation tag is not parsed by the preprocessor. The