diff --git a/doc/manual.xml b/doc/manual.xml index 290d75982..8bf544c36 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -2,21 +2,17 @@ - DYNARE MANUAL - Version 4 - DYNARE - MichelJuillard -CEPREMAP and University Paris 8 -michel.juillard@ens.fr -
-48 bd Jourdan -75014ParisFrance -
- + Dynare Manual + Version 4.0.2 (draft) + + MichelJuillard + CEPREMAP and University Paris 8 + michel.juillard@ens.fr +
48 bd Jourdan75014ParisFrance
+ -1996-2008Dynare Team + 1996-2008Dynare Team - Permission is granted to copy, distribute and/or modify this document @@ -59,8 +55,11 @@ A copy of the license can be found at: forecast -Preface -Dynare is a pre-processor and a collection of Matlab® and GNU Octave routines which solve, simulate and estimate non-linear +Introduction + +What is Dynare ? + +Dynare is a pre-processor and a collection of Matlab and GNU Octave routines which solve, simulate and estimate non-linear models with forward looking variables. It is the result of research carried at CEPREMAP by several people (see Laffargue, 1990, Boucekkine, 1995, and Juillard, 1996, Collard and Juillard 2001a and 2001b). @@ -68,7 +67,7 @@ Juillard, 1996, Collard and Juillard 2001a and 2001b). When the framework is deterministic, Dynare can be used for models with the assumption of perfect foresight. Typically, the system is supposed to be in a state of -equilibrium before a period ``1'' when the news of a contemporaneous +equilibrium before a period 1 when the news of a contemporaneous or of a future shock is learned by the agents in the model. The purpose of the simulation is to describe the reaction in anticipation of, then in reaction to the shock, until the system returns to the old or @@ -95,99 +94,44 @@ Starting with version 3.0, it is possible to use Dynare to estimate model parame Currently the development team of Dynare is composed of S. Adjemian, M. Juillard, O. Kamenik, F. Mihoubi and S. Villemot. Several parts of Dynare use or have strongly benefited from publicly available programs by F. Collard, L. Ingber, P. Klein, M. Ratto, S. Sakata, F. Schorfheide, C. Sims, P. Soederlind and R. Wouters. + -
Changes -
Version 4 -December 26, 2006 - -added option mh_recover - -
-
Version 3 -December 30, 2005 - -added details about parameter transformation in and in -added conditional compilation commands and if_elseif_else_end -enhanced output section of command -added exogenous deterministic shocks in stochastic models. See , , , -added a forecast command for calibrated models. See . - -October 14, 2005 - -added syntax for computing optimal policy. See olr, olr_inst, , , . -added syntax for estimating correlation between two shocks or two measurment errors in , and - - -July 20, 2005 - -Expanded description of statement -changed the default for nonlinear solver in -added a mention of the possibility to write explicitly a steady state function in , , and -added a brief Ouput section in -corrected misleading description of option in -added variance decomposition among the statistics computed with option in -tex option in isn't yet implemented - -May 3, 2005 - -added option in -modified option in -modified option in - -March 6, 2005 - -corrected typos in equations for 1st and 2nd order approximation formulas in . -temporarily removed description of output variables in as old content was outdated and the new one isn't ready yet. -added cross-references - -
-
- +Changes since version 3 -Introduction + + + +Installation and configuration - -In order to give instructions to Dynare, the user has to write a model file whose file name must terminate by ".mod". This file contains the description of the model and the computing tasks required by the user. - - -In practice, the handling of your model file is done in two -steps: in the first one, the model and the processing instructions -written by the user in a model file are -interpreted and the proper Matlab® or GNU Octave instructions are generated; in the -second step, the program actually runs the computations. Both steps -are triggered by a single keyword: dynare. - Software requirements -Packaged versions of Dynare are available for Windows® 98/NT/2000/XP/Vista, Debian GNU/Linux and Ubuntu, on Intel/AMD x86 architectures. +Packaged versions of Dynare are available for Windows 98/NT/2000/XP/Vista, Debian GNU/Linux and Ubuntu, on Intel/AMD x86 architectures. Dynare should work on other systems and architectures, but some compilation steps are necessary in that case. - -The Matlab® version is written for Matlab® version 6.5 and above. - - -The Octave version is written for GNU Octave version 3.0.0 and above. +In order to run Dynare, you need at least one of the following: + +Matlab version 6.5 or above; note that no toolbox is needed by Dynare, +GNU Octave version 3.0.0 or above. + -Installation and configuration +Installation of GNU Octave + +You can skip this step if you are planning to use only Matlab with Dynare. + +Please refer to DynareOctave on Dynare Wiki for detailed instructions. + + + +Installation of Dynare After installation, Dynare can be used in any directory on your computer. It is best practive to keep your model files in directories different from the one containing the Dynare toolbox. That way you can upgrade Dynare and discard the previous version without having to worry about your own files. -Installation of GNU Octave - -You can skip this step if you are planning to use only Matlab® with Dynare. - -Please refer to DynareOctave on Dynare Wiki for detailed instructions. - - - -Installation of Dynare - -On Windows® +On <trademark class="registered">Windows</trademark> Execute the automated installer called dynare-4.x.y-win32.exe (where 4.x.y is the version number), and follow the instructions. The default installation directory is c:\dynare\4.x.y. @@ -197,33 +141,33 @@ After installation, Dynare can be used in any directory on your computer. It is You can have several versions of Dynare coexisting (for example in c:\dynare), as long as you correctly adjust your path settings (see ). -Note that no installer is currently avaible for Windows® on 64 bits platforms. For the time being, please follow the instructions given in if you have such a system. - +Note that no installer is currently avaible for Windows on 64 bits platforms. For the time being, please follow the instructions given in if you have such a system. + -On Debian GNU/Linux and Ubuntu +On Debian GNU/Linux and Ubuntu Please refer to InstallOnDebianOrUbuntu on Dynare Wiki for detailed instructions. Dynare will be installed under /usr/lib/dynare. Documentation will be under /usr/share/doc/dynare. - + -For other systems +For other systems You need to download Dynare source code from the Dynare website and unpack it somewhere. Then you will need to recompile the pre-processor and the dynamic loadable libraries. Please refer to BuildingPreprocessor and BuildingDlls on Dynare Wiki. - + -Configuration +Configuration -For Matlab® +For <trademark class="registered">Matlab</trademark> You need to add the matlab subdirectory of your Dynare -installation to Matlab® path. You have two options for doing that: +installation to Matlab path. You have two options for doing that: - Using the addpath command in the Matlab® command window: + Using the addpath command in the Matlab command window: - Under Windows®, assuming that you have installed Dynare at the standard location, and replacing "4.x.y" by correct version number, type: + Under Windows, assuming that you have installed Dynare at the standard location, and replacing "4.x.y" by correct version number, type: addpath c:\dynare\4.x.y\matlab @@ -233,24 +177,24 @@ installation to Matlab® path. You have two options for doing that: addpath /usr/lib/dynare/matlab - Matlab® will not remember this setting next time you run it, and you will have + Matlab will not remember this setting next time you run it, and you will have to do it again. Via the menu entries: Select the "Set Path" entry in the "File" menu, then click on "Add Folder...", and select the matlab subdirectory of your Dynare - installation. Note that you SHOULD NOT use "Add with Subfolders...". Apply + installation. Note that you should not use "Add with Subfolders...". Apply the settings by clicking on "Save". Note that Matlab will remember this setting next time you run it. - + -For GNU Octave +For GNU Octave You need to add the matlab subdirectory of your Dynare installation to Octave path, using the addpath at the Octave command prompt. -Under Windows®, assuming that you have installed Dynare at the standard location, and replacing "4.x.y" by correct version number, type: +Under Windows, assuming that you have installed Dynare at the standard location, and replacing "4.x.y" by correct version number, type: addpath c:\dynare\4.x.y\matlab @@ -266,25 +210,36 @@ installation to Octave path, using the addpath at the Octave If you don't want to type these two commands every time you run Octave, -you can put them in a file called .octaverc in your home directory (under Windows® this will generally by c:\Document and Settings\USERNAME\). This file is run by Octave at every startup. - +you can put them in a file called .octaverc in your home directory (under Windows this will generally by c:\Documents and Settings\USERNAME\). This file is run by Octave at every startup. + -Some words of warning +Some words of warning -You should be very careful about the content of you Matlab® or Octave path. You can display its content by simply typing path in the command window. +You should be very careful about the content of you Matlab or Octave path. You can display its content by simply typing path in the command window. -The path should normally contain system directories of Matlab® or Octave, and the matlab subdirectory of your Dynare installation. It should not contain any other Dynare-related directory, from another Dynare version of from the version you are using. However, note that Dynare will automatically add one (and only one) of the mex/2007a, mex/2007b, and mex/octave subdirectories, depending on your installation. +The path should normally contain system directories of Matlab or Octave, and the matlab subdirectory of your Dynare installation. It should not contain any other Dynare-related directory, from another Dynare version of from the version you are using. However, note that Dynare will automatically add one (and only one) of the mex/2007a, mex/2007b, and mex/octave subdirectories, depending on your installation. You have to be aware that adding other directories to your path can potentially create problems, if some of your M-files have the same names than Dynare files. Your files would then override Dynare files, and make Dynare unusable. - - + Dynare invocation -You invoke Dynare by using the dynare at the Matlab® or Octave prompt. + +In order to give instructions to Dynare, the user has to write a model file whose filename extension must be .mod. This file contains the description of the model and the computing tasks required by the user. Its contents is described in . + + +Once the model file is written, Dynare is invoked using the dynare command at the Matlab or Octave prompt (with the filename of the .mod given as argument). + + +In practice, the handling of the model file is done in two +steps: in the first one, the model and the processing instructions +written by the user in a model file are +interpreted and the proper Matlab or GNU Octave instructions are generated; in the +second step, the program actually runs the computations. Boths steps are triggered automatically by the dynare command. + @@ -310,14 +265,14 @@ you can put them in a file called .octaverc in your home di Description -dynare executes instruction included in FILENAME.mod. +dynare executes instruction included in FILENAME.mod. This user-supplied file contains the model and the processing instructions, as described in . Details -dynare begins by launching the preprocessor on the *.mod file. +dynare begins by launching the preprocessor on the .mod file. By default (unless any of , or options have been given to ), the preprocessor creates three intermediary files: @@ -333,16 +288,16 @@ These files may be looked at to understand errors reported at the simulation sta Options - : by default, dynare will issue a clear all command to Matlab® or Octave, thereby deleting all workspace variables; this options instructs dynare not to clear the workspace + : by default, dynare will issue a clear all command to Matlab or Octave, thereby deleting all workspace variables; this options instructs dynare not to clear the workspace : instructs dynare to save the intermediary file which is obtained after macro-processing (see ); the saved output will go in FILENAME-macroexp.mod - : instructs the preprocessor to write some debugging information about the scanning and parsing of the *.mod file + : instructs the preprocessor to write some debugging information about the scanning and parsing of the .mod file Output -Depending on the computing tasks requested in the *.mod file, executing command dynare will leave in the workspace variables containing results available for further processing. More details are given under the relevant computing tasks. +Depending on the computing tasks requested in the .mod file, executing command dynare will leave in the workspace variables containing results available for further processing. More details are given under the relevant computing tasks. @@ -379,7 +334,7 @@ In the description of Dynare commands, the following conventions are observed: MODEL_EXPRESSION indicates a mathematical expression valid in the model description (see and ) VARIABLE_NAME indicates a variable name starting with an alphabetical character and can't contain ()+-*/^=!;:@#. or accentuated characters PARAMETER_NAME indicates a parameter name starting with an alphabetical character and can't contain ()+-*/^=!;:@#. or accentuated characters -FILENAME indicates a file name valid in the underlying operating system (Windows®, GNU/Linux, ...) +FILENAME indicates a file name valid in the underlying operating system (Windows, GNU/Linux, ...) @@ -532,125 +487,78 @@ varexo_det tau; Description -This optional command declares parameters used in the model, in variable initialization or in shock declarations. See for the syntax of PARAMETER_NAME. +This optional command declares parameters used in the model, in variable initialization or in shocks declarations. See for the syntax of PARAMETER_NAME. -The parameters must then be assigned values, see . +The parameters must subsequently be assigned values, see . Example parameters alpha, bet; - -alpha = 0.3; -bet = sqrt(2); -Other general declarations - - - - (deprecated) - - - - - - - dsample - - - - dsample - reduces the number of periods considered in subsequent output commands - - - - - - periods - - - - periods - specifies the number of simulation periods - - - - - periods - INTEGER; - - - - -Description - -This command is now deprecated (but will still work for older model files). It is not necessary when no simulation is performed and is replaced by an option in and . - - -Sets the number of periods in the simulation. The periods are numbered from 1 to INTEGER. In perfect foresight simulations, it is assumed that all future events are perfectly known at the beginning of period 1. - - - -Example - -periods 100; - - - - - - - cutoff - - - - cutoff - declares the cutoff for fast deterministic simulations - - - - - - markowitz - - - - markowitz - declares the markowitz criterion for fast deterministic simulations - - - - - Expressions -You can specify mathematical expression at two kinds of places in the *.mod file: inside some commands and inside the model description. These expressions are respectively represented by EXPRESSION and MODEL_EXPRESSION in this manual. + Dynare distinguishes between two types of mathematical expressions: those that are used to describe the model, and those that are used outside the model block (e.g. for initializing parameters or variables, or as command options). In this manual, those two types of expressions are respectively denoted by MODEL_EXPRESSION and EXPRESSION. -Unlike Matlab® or Octave expressions, these expressions are necessarily scalar ones, and cannot construct or contain matricesNote that you can also put arbitrary Matlab® or Octave expressions in your *.mod file, but those expressions have to be on separate lines, generally at the end of the file for post-processing purposes. These constructions are not addresses in these section.. + Unlike Matlab or Octave expressions, Dynare expressions are necessarily scalar ones: they cannot contain matrices or evaluate to matricesNote that arbitrary Matlab or Octave expressions can be put in a .mod file, but those expressions have to be on separate lines, generally at the end of the file for post-processing purposes. They are not interpreted by Dynare, and are simply passed on unmodified to Matlab or Octave. Those constructions are not addresses in this section.. -You can construct these expressions using integers (INTEGER), floating point numbers (DOUBLE), parameters, variables, operators and functions. + Expressions can be constructed using integers (INTEGER), floating point numbers (DOUBLE), parameter names, variable names, operators and functions. -Parameters and variables -Lead and lags allowed only in model expressions. + + Parameters and variables -Describe the semantic difference for endogenous/exogenous between the two kinds of expressions. - + Parameters and variables can be introduced in expressions by simply typing their names. The semantics of parameters and variables is quite different whether they are used inside or outside the model block. -Operators - + + Inside the model -Functions -Unknown functions allowed (under some conditions) in expressions outside model block. + Parameters used inside the model either refer to the value given through parameter initialization (and possiblity ) when doing a simulation, or are the estimated variables when doing an estimation. + + Variables used in a MODEL_EXPRESSION denote current period values when neither a lead or a lag is given. A lead or a lag can be given by enclosing an integer between parenthesis just after the variable name: a positive integer means a lead, a negative one means a lag. For example, if c is an endogenous variable, then c(+1) is the variable one period ahead, and c(-2) is the variable two periods before. + + Leads and lags are primarily used for endogenous variables. They can be used for exogenous variables under some conditions (TO BE EXPLICITED). They are forbidden for parameters and for local model variables (see ). + + + + + Outside the model + When used in an expression outside the model block, a parameter or a variable simply refers to the last value given to that variable. More precisely, for a parameter it refers to the value given in the corresponding parameter initialization; for an endogenous or exogenous variable, it refers to the value given in the most recent or block. + + + + + Operators + The following operators are allowed in both MODEL_EXPRESSION and EXPRESSION: + + binary arithmetic operators: +, -, *, /, ^ + unary arithmetic operators: +, - + binary comparison operators (which evaluate to either 0 or 1): <, >, <=, >=, ==, != + + + + + Functions + The following standard functions are allowed in both MODEL_EXPRESSION and EXPRESSION: + + exponential: exp() + natural logarithm: log() (aliased as ln()) + base 10 logarithm: log10() + square root: sqrt() + trigonometric functions: sin(), cos(), tan(), asin(), acos(), atan() + TO BE COMPLETED + + + Unknown functions allowed (under some conditions) in expressions outside model block. -Initializing parameters +Parameter initialization The syntax is the following: @@ -1238,7 +1146,7 @@ forecast; The matrix of variance-covariance of the shocks can be directly specified as a upper (or lower) triangular matrix. Dynare builds the corresponding symmetrix matrix. Each row of the triangular matrix, except the last one, must be terminated by a semi-colon ';'. For a given element, an EXPRESSION using predefined parameters is allowed but must be placed between parentheses. THE ORDER OF THE COVARIANCES IN THE MATRIX IS THE SAME AS THE ONE USED IN THE VAREXO DECLARATION. -In previous versions, it was possible to directly set Dynare's internal covariance matrix Sigma_e_. This is still possible for compatibility with older .mod files, but STRONGLY DISCOURAGED as too prone to error. When setting Sigma_e_ directly, the order of the exogenous shocks is the ALPHABETICAL order of their names. +In previous versions, it was possible to directly set Dynare's internal covariance matrix Sigma_e_. This is still possible for compatibility with older .mod files, but STRONGLY DISCOURAGED as too prone to error. When setting Sigma_e_ directly, the order of the exogenous shocks is the ALPHABETICAL order of their names. @@ -1256,6 +1164,60 @@ where the variance of u is 0.81, the variance of e +Other general declarations + + + + (deprecated) + + + + + dsample + + + + dsample + reduces the number of periods considered in subsequent output commands + + + + + + periods + + + + periods + specifies the number of simulation periods + + + + + periods + INTEGER; + + + + +Description + +This command is now deprecated (but will still work for older model files). It is not necessary when no simulation is performed and is replaced by an option in and . + + +Sets the number of periods in the simulation. The periods are numbered from 1 to INTEGER. In perfect foresight simulations, it is assumed that all future events are perfectly known at the beginning of period 1. + + + +Example + +periods 100; + + + + + + Solving and simulating Dynare has special commands for the computation of the static equilibrium of the model (, of the eigenvalues of the linearized model () for dynamics local analysis, of a deterministic simulation () and for solving and/or simulating a stochastic model (). @@ -1315,7 +1277,7 @@ Computes the equilibrium value of the endogenous variables for the value of the For complicated models, finding good numerical initial values for the endogenous variables is the trickiest part of finding the equilibrium of that model. Often, it is better to start with a smaller model and add new variables one by one. -If you know how to compute the steady state for your model, you can provide a Matlab function doing the computation instead of using steady. The function should be called with the name of the .mod file followed by _steadystate. See fs2000a_steadystate.m in examples/fs2000 directory. +If you know how to compute the steady state for your model, you can provide a Matlab function doing the computation instead of using steady. The function should be called with the name of the .mod file followed by _steadystate. See fs2000a_steadystate.m in examples/fs2000 directory. @@ -1567,7 +1529,7 @@ When a list of VARIABLE_NAMEs is specified, results are displayed only for these stoch_simul computes a Taylor approximation of the decision and transition functions for the model, impulse response functions and various descriptive statistics (moments, variance decomposition, correlation and autocorrelation coefficients). For correlated shocks, the variance decomposition is computed as in the VAR literature through a Cholesky decomposition of the covariance matrix of the exogenous variables. When the shocks are correlated, the variance decomposition depends upon the order of the variables in the command. -The Taylor approximation is computed around the steady state (except whith option dr_algo=1). If you know how to compute the steady state for your model, you can provide a Matlab function doing the computation instead of using the nonlinear solver. The function should be called with the name of the .mod file followed by _steadystate. See fs2000a_steadystate.m in examples/fs2000 directory. +The Taylor approximation is computed around the steady state (except whith option dr_algo=1). If you know how to compute the steady state for your model, you can provide a Matlab function doing the computation instead of using the nonlinear solver. The function should be called with the name of the .mod file followed by _steadystate. See fs2000a_steadystate.m in examples/fs2000 directory. @@ -2235,7 +2197,7 @@ oo_.posterior_hpdsup.measurement_errors_corr.gdp_conso Note on steady state computation -If you know how to compute the steady state for your model, you can provide a Matlab function doing the computation instead of using steady. The function should be called with the name of the .mod file followed by _steadystate. See fs2000a_steadystate.m in examples/fs2000 directory. +If you know how to compute the steady state for your model, you can provide a Matlab function doing the computation instead of using steady. The function should be called with the name of the .mod file followed by _steadystate. See fs2000a_steadystate.m in examples/fs2000 directory. @@ -2593,9 +2555,9 @@ In Matlab, variables saved with the dynasave command can be r Macro-processing language -It is possible to use "macro" commands in the *.mod file for doing the following tasks: source file inclusion, replicating blocks of equations through loops, conditional inclusion of code... +It is possible to use "macro" commands in the .mod file for doing the following tasks: source file inclusion, replicating blocks of equations through loops, conditional inclusion of code... -Technically, this macro language is totally independent of the basic Dynare language, and is processed by a separate component of the Dynare pre-processor. The macro processor transforms a *.mod file with macros into a *.mod file without macros (doing expansions/inclusions), and then feeds it to the Dynare parser. +Technically, this macro language is totally independent of the basic Dynare language, and is processed by a separate component of the Dynare pre-processor. The macro processor transforms a .mod file with macros into a .mod file without macros (doing expansions/inclusions), and then feeds it to the Dynare parser. @@ -2635,7 +2597,7 @@ In Matlab, variables saved with the dynasave command can be r @#if ... @#else ... @#endif - conditional inclusion of some part of the *.mod file + conditional inclusion of some part of the .mod file @@ -2646,7 +2608,7 @@ In Matlab, variables saved with the dynasave command can be r @#for ... @#endfor - loop for replications of portions of the *.mod file + loop for replications of portions of the .mod file