diff --git a/doc/manual/source/the-model-file.rst b/doc/manual/source/the-model-file.rst index df6541547..1bc92ac45 100644 --- a/doc/manual/source/the-model-file.rst +++ b/doc/manual/source/the-model-file.rst @@ -8137,6 +8137,234 @@ commitment with ``ramsey_policy``, for optimal policy under discretion with ``discretionary_policy`` or for optimal simple rule with ``osr`` (also implying commitment). +.. command:: planner_objective MODEL_EXPRESSION ; + + |br| This command declares the policy maker objective, for use + with ``ramsey_policy`` or ``discretionary_policy``. + + You need to give the one-period objective, not the discounted + lifetime objective. The discount factor is given by the + ``planner_discount`` option of ``ramsey_policy`` and + ``discretionary_policy``. The objective function can only contain + current endogenous variables and no exogenous ones. This + limitation is easily circumvented by defining an appropriate + auxiliary variable in the model. + + With ``ramsey_policy``, you are not limited to quadratic + objectives: you can give any arbitrary nonlinear expression. + + With ``discretionary_policy``, the objective function must be quadratic. + +Optimal policy under commitment (Ramsey) +---------------------------------------- + +.. command:: ramsey_model (OPTIONS...); + + |br| This command computes the First Order Conditions for maximizing + the policy maker objective function subject to the constraints + provided by the equilibrium path of the private economy. + + The planner objective must be declared with the :comm:`planner_objective` command. + + This command only creates the expanded model, it doesn’t perform + any computations. It needs to be followed by other instructions to + actually perform desired computations. Examples are calls to ``steady`` + to compute the steady state of the Ramsey economy, to ``stoch_simul`` + with various approximation orders to conduct stochastic simulations based on + perturbation solutions, to ``estimation`` in order to estimate models + under optimal policy with commitment, and to perfect foresight simulation + routines. + + See :ref:`aux-variables`, for an explanation of how Lagrange + multipliers are automatically created. + + *Options* + + This command accepts the following options: + + .. option:: planner_discount = EXPRESSION + + Declares or reassigns the discount factor of the central + planner ``optimal_policy_discount_factor``. Default: ``1.0``. + + .. option:: planner_discount_latex_name = LATEX_NAME + + Sets the LaTeX name of the ``optimal_policy_discount_factor`` + parameter. + + .. option:: instruments = (VARIABLE_NAME,...) + + Declares instrument variables for the computation of the + steady state under optimal policy. Requires a + ``steady_state_model`` block or a ``_steadystate.m`` file. See + below. + + *Steady state* + + Dynare takes advantage of the fact that the Lagrange multipliers + appear linearly in the equations of the steady state of the model + under optimal policy. Nevertheless, it is in general very + difficult to compute the steady state with simply a numerical + guess in ``initval`` for the endogenous variables. + + It greatly facilitates the computation, if the user provides an + analytical solution for the steady state (in + ``steady_state_model`` block or in a ``_steadystate.m`` file). In + this case, it is necessary to provide a steady state solution + CONDITIONAL on the value of the instruments in the optimal policy + problem and declared with the option ``instruments``. The initial value + of the instrument for steady state finding in this case is set with + ``initval``. Note that computing and displaying steady state values + using the ``steady``-command or calls to ``resid`` must come after + the ``ramsey_model`` statement and the ``initval``-block. + + Note that choosing the instruments is partly a matter of interpretation and + you can choose instruments that are handy from a mathematical + point of view but different from the instruments you would refer + to in the analysis of the paper. A typical example is choosing + inflation or nominal interest rate as an instrument. + + +.. block:: ramsey_constraints ; + + |br| This block lets you define constraints on the variables in + the Ramsey problem. The constraints take the form of a variable, + an inequality operator (> or <) and a constant. + + *Example* + + :: + + ramsey_constraints; + i > 0; + end; + +.. command:: evaluate_planner_objective ; + + This command computes, displays, and stores the value of the + planner objective function + under Ramsey policy in ``oo_.planner_objective_value``, given the + initial values of the endogenous state variables. If not specified + with ``histval``, they are taken to be at their steady state + values. The result is a 1 by 2 vector, where the first entry + stores the value of the planner objective when the initial + Lagrange multipliers associated with the planner’s problem are set + to their steady state values (see :comm:`ramsey_policy`). + + In contrast, the second entry stores the value of the planner + objective with initial Lagrange multipliers of the planner’s + problem set to 0, i.e. it is assumed that the planner exploits its + ability to surprise private agents in the first period of + implementing Ramsey policy. This is the value of implementating + optimal policy for the first time and committing not to + re-optimize in the future. + + Because it entails computing at least a second order approximation, the + computation of the planner objective value is skipped with a message when + the model is too large (more than 180 state variables, including lagged + Lagrange multipliers). + +.. command:: ramsey_policy [VARIABLE_NAME...]; + ramsey_policy (OPTIONS...) [VARIABLE_NAME...]; + + |br| This command is formally equivalent to the calling sequence + + :: + + ramsey_model; + stoch_simul(order=1); + evaluate_planner_objective; + + It computes the first order approximation of the + policy that maximizes the policy maker’s objective function + subject to the constraints provided by the equilibrium path of the + private economy and under commitment to this optimal policy. The + Ramsey policy is computed by approximating the equilibrium system + around the perturbation point where the Lagrange multipliers are + at their steady state, i.e. where the Ramsey planner acts as if + the initial multipliers had been set to 0 in the distant past, + giving them time to converge to their steady state + value. Consequently, the optimal decision rules are computed + around this steady state of the endogenous variables and the + Lagrange multipliers. + + This first order approximation to the optimal policy conducted by + Dynare is not to be confused with a naive linear quadratic + approach to optimal policy that can lead to spurious welfare + rankings (see *Kim and Kim (2003)*). In the latter, the optimal + policy would be computed subject to the first order approximated + FOCs of the private economy. In contrast, Dynare first computes + the FOCs of the Ramsey planner’s problem subject to the nonlinear + constraints that are the FOCs of the private economy and only then + approximates these FOCs of planner’s problem to first + order. Thereby, the second order terms that are required for a + second-order correct welfare evaluation are preserved. + + Note that the variables in the list after the ``ramsey_policy`` + command can also contain multiplier names. In that case, Dynare + will for example display the IRFs of the respective multipliers + when ``irf>0``. + + The planner objective must be declared with the :comm:`planner_objective` command. + + *Options* + + This command accepts all options of ``stoch_simul``, plus: + + .. option:: planner_discount = EXPRESSION + + See :opt:`planner_discount `. + + .. option:: instruments = (VARIABLE_NAME,...) + + Declares instrument variables for the computation of the + steady state under optimal policy. Requires a + ``steady_state_model`` block or a ``_steadystate.m`` file. See + below. + + Note that only a first order approximation of the optimal Ramsey + policy is available, leading to a second-order accurate welfare + ranking (i.e. ``order=1`` must be specified). + + *Output* + + This command generates all the output variables of + ``stoch_simul``. For specifying the initial values for the + endogenous state variables (except for the Lagrange multipliers), + see :bck:`histval`. + + + *Steady state* + + See :comm:`Ramsey steady state `. + +Optimal policy under discretion +------------------------------- + +.. command:: discretionary_policy [VARIABLE_NAME...]; + discretionary_policy (OPTIONS...) [VARIABLE_NAME...]; + + |br| This command computes an approximation of the optimal policy + under discretion. The algorithm implemented is essentially an LQ + solver, and is described by *Dennis (2007)*. + + You should ensure that your model is linear and your objective is + quadratic. Also, you should set the ``linear`` option of the + ``model`` block. + + *Options* + + This command accepts the same options than ``ramsey_policy``, plus: + + .. option:: discretionary_tol = NON-NEGATIVE DOUBLE + + Sets the tolerance level used to assess convergence of the + solution algorithm. Default: ``1e-7``. + + .. option:: maxit = INTEGER + + Maximum number of iterations. Default: ``3000``. + Optimal Simple Rules (OSR) -------------------------- @@ -8390,236 +8618,6 @@ Optimal Simple Rules (OSR) ``M_.endo_names``. -Optimal policy under commitment (Ramsey) ----------------------------------------- - -.. command:: ramsey_model (OPTIONS...); - - |br| This command computes the First Order Conditions for maximizing - the policy maker objective function subject to the constraints - provided by the equilibrium path of the private economy. - - The planner objective must be declared with the :comm:`planner_objective` command. - - This command only creates the expanded model, it doesn’t perform - any computations. It needs to be followed by other instructions to - actually perform desired computations. Examples are calls to ``steady`` - to compute the steady state of the Ramsey economy, to ``stoch_simul`` - with various approximation orders to conduct stochastic simulations based on - perturbation solutions, to ``estimation`` in order to estimate models - under optimal policy with commitment, and to perfect foresight simulation - routines. - - See :ref:`aux-variables`, for an explanation of how Lagrange - multipliers are automatically created. - - *Options* - - This command accepts the following options: - - .. option:: planner_discount = EXPRESSION - - Declares or reassigns the discount factor of the central - planner ``optimal_policy_discount_factor``. Default: ``1.0``. - - .. option:: planner_discount_latex_name = LATEX_NAME - - Sets the LaTeX name of the ``optimal_policy_discount_factor`` - parameter. - - .. option:: instruments = (VARIABLE_NAME,...) - - Declares instrument variables for the computation of the - steady state under optimal policy. Requires a - ``steady_state_model`` block or a ``_steadystate.m`` file. See - below. - - *Steady state* - - Dynare takes advantage of the fact that the Lagrange multipliers - appear linearly in the equations of the steady state of the model - under optimal policy. Nevertheless, it is in general very - difficult to compute the steady state with simply a numerical - guess in ``initval`` for the endogenous variables. - - It greatly facilitates the computation, if the user provides an - analytical solution for the steady state (in - ``steady_state_model`` block or in a ``_steadystate.m`` file). In - this case, it is necessary to provide a steady state solution - CONDITIONAL on the value of the instruments in the optimal policy - problem and declared with the option ``instruments``. The initial value - of the instrument for steady state finding in this case is set with - ``initval``. Note that computing and displaying steady state values - using the ``steady``-command or calls to ``resid`` must come after - the ``ramsey_model`` statement and the ``initval``-block. - - Note that choosing the instruments is partly a matter of interpretation and - you can choose instruments that are handy from a mathematical - point of view but different from the instruments you would refer - to in the analysis of the paper. A typical example is choosing - inflation or nominal interest rate as an instrument. - - -.. block:: ramsey_constraints ; - - |br| This block lets you define constraints on the variables in - the Ramsey problem. The constraints take the form of a variable, - an inequality operator (> or <) and a constant. - - *Example* - - :: - - ramsey_constraints; - i > 0; - end; - -.. command:: evaluate_planner_objective ; - - This command computes, displays, and stores the value of the - planner objective function - under Ramsey policy in ``oo_.planner_objective_value``, given the - initial values of the endogenous state variables. If not specified - with ``histval``, they are taken to be at their steady state - values. The result is a 1 by 2 vector, where the first entry - stores the value of the planner objective when the initial - Lagrange multipliers associated with the planner’s problem are set - to their steady state values (see :comm:`ramsey_policy`). - - In contrast, the second entry stores the value of the planner - objective with initial Lagrange multipliers of the planner’s - problem set to 0, i.e. it is assumed that the planner exploits its - ability to surprise private agents in the first period of - implementing Ramsey policy. This is the value of implementating - optimal policy for the first time and committing not to - re-optimize in the future. - - Because it entails computing at least a second order approximation, the - computation of the planner objective value is skipped with a message when - the model is too large (more than 180 state variables, including lagged - Lagrange multipliers). - -.. command:: ramsey_policy [VARIABLE_NAME...]; - ramsey_policy (OPTIONS...) [VARIABLE_NAME...]; - - |br| This command is formally equivalent to the calling sequence - - :: - - ramsey_model; - stoch_simul(order=1); - evaluate_planner_objective; - - It computes the first order approximation of the - policy that maximizes the policy maker’s objective function - subject to the constraints provided by the equilibrium path of the - private economy and under commitment to this optimal policy. The - Ramsey policy is computed by approximating the equilibrium system - around the perturbation point where the Lagrange multipliers are - at their steady state, i.e. where the Ramsey planner acts as if - the initial multipliers had been set to 0 in the distant past, - giving them time to converge to their steady state - value. Consequently, the optimal decision rules are computed - around this steady state of the endogenous variables and the - Lagrange multipliers. - - This first order approximation to the optimal policy conducted by - Dynare is not to be confused with a naive linear quadratic - approach to optimal policy that can lead to spurious welfare - rankings (see *Kim and Kim (2003)*). In the latter, the optimal - policy would be computed subject to the first order approximated - FOCs of the private economy. In contrast, Dynare first computes - the FOCs of the Ramsey planner’s problem subject to the nonlinear - constraints that are the FOCs of the private economy and only then - approximates these FOCs of planner’s problem to first - order. Thereby, the second order terms that are required for a - second-order correct welfare evaluation are preserved. - - Note that the variables in the list after the ``ramsey_policy`` - command can also contain multiplier names. In that case, Dynare - will for example display the IRFs of the respective multipliers - when ``irf>0``. - - The planner objective must be declared with the :comm:`planner_objective` command. - - *Options* - - This command accepts all options of ``stoch_simul``, plus: - - .. option:: planner_discount = EXPRESSION - - See :opt:`planner_discount `. - - .. option:: instruments = (VARIABLE_NAME,...) - - Declares instrument variables for the computation of the - steady state under optimal policy. Requires a - ``steady_state_model`` block or a ``_steadystate.m`` file. See - below. - - Note that only a first order approximation of the optimal Ramsey - policy is available, leading to a second-order accurate welfare - ranking (i.e. ``order=1`` must be specified). - - *Output* - - This command generates all the output variables of - ``stoch_simul``. For specifying the initial values for the - endogenous state variables (except for the Lagrange multipliers), - see :bck:`histval`. - - - *Steady state* - - See :comm:`Ramsey steady state `. - -Optimal policy under discretion -------------------------------- - -.. command:: discretionary_policy [VARIABLE_NAME...]; - discretionary_policy (OPTIONS...) [VARIABLE_NAME...]; - - |br| This command computes an approximation of the optimal policy - under discretion. The algorithm implemented is essentially an LQ - solver, and is described by *Dennis (2007)*. - - You should ensure that your model is linear and your objective is - quadratic. Also, you should set the ``linear`` option of the - ``model`` block. - - *Options* - - This command accepts the same options than ``ramsey_policy``, plus: - - .. option:: discretionary_tol = NON-NEGATIVE DOUBLE - - Sets the tolerance level used to assess convergence of the - solution algorithm. Default: ``1e-7``. - - .. option:: maxit = INTEGER - - Maximum number of iterations. Default: ``3000``. - - -.. command:: planner_objective MODEL_EXPRESSION ; - - |br| This command declares the policy maker objective, for use - with ``ramsey_policy`` or ``discretionary_policy``. - - You need to give the one-period objective, not the discounted - lifetime objective. The discount factor is given by the - ``planner_discount`` option of ``ramsey_policy`` and - ``discretionary_policy``. The objective function can only contain - current endogenous variables and no exogenous ones. This - limitation is easily circumvented by defining an appropriate - auxiliary variable in the model. - - With ``ramsey_policy``, you are not limited to quadratic - objectives: you can give any arbitrary nonlinear expression. - - With ``discretionary_policy``, the objective function must be quadratic. - - Sensitivity and identification analysis =======================================