From 8eeddf996a99c987d2621537d868c61c086220aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Adjemia=20=28Scylla=29?= Date: Sat, 1 Dec 2018 22:56:11 +0100 Subject: [PATCH] Fixed indentation and removed tabs. --- src/source/running-dynare.rst | 582 +++++++++++++++++----------------- 1 file changed, 290 insertions(+), 292 deletions(-) diff --git a/src/source/running-dynare.rst b/src/source/running-dynare.rst index 12ecfdaff..656fd97c4 100644 --- a/src/source/running-dynare.rst +++ b/src/source/running-dynare.rst @@ -26,385 +26,383 @@ GNU Octave instructions are generated; in the second step, the program actually runs the computations. Both steps are triggered automatically by the ``dynare`` command. -.. matcomm :: dynare FILENAME[.mod] [OPTIONS…] - - This command launches Dynare and executes the instructions - included in ``FILENAME.mod``. This user-supplied file contains the - model and the processing instructions, as described in - :ref:`model-file`. The options, listed below, can be passed on the - command line, following the name of the ``.mod`` file or in the - first line of the ``.mod`` file itself (see below). - - dynare begins by launching the preprocessor on the ``.mod - file``. By default (unless ``use_dll`` option has been given to - ``model``), the preprocessor creates three intermediary files: - - - - ``filename.m`` - - Contains variable declarations, and computing tasks. - - - - ``FILENAME_dynamic.m`` - - Contains the dynamic model equations. Note that Dynare might - introduce auxiliary equations and variables (see - :ref:`aux-variables`). Outputs are the residuals of the - dynamic model equations in the order the equations were - declared and the Jacobian of the dynamic model equations. For - higher order approximations also the Hessian and the - third-order derivatives are provided. When computing the - Jacobian of the dynamic model, the order of the endogenous - variables in the columns is stored in - ``M_.lead_lag_incidence``. The rows of this matrix represent - time periods: the first row denotes a lagged (time t-1) - variable, the second row a contemporaneous (time t) variable, - and the third row a leaded (time t+1) variable. The columns of - the matrix represent the endogenous variables in their order - of declaration. A zero in the matrix means that this - endogenous does not appear in the model in this time - period. The value in the ``M_.lead_lag_incidence`` matrix - corresponds to the column of that variable in the Jacobian of - the dynamic model. Example: Let the second declared variable - be ``c`` and the ``(3,2)`` entry of ``M_.lead_lag_incidence`` - be 15. Then the 15th column of the Jacobian is the derivative - with respect to ``c(+1)``. - - - ``FILENAME_static.m`` + .. matcomm:: dynare FILENAME[.mod] [OPTIONS…] + + This command launches Dynare and executes the instructions + included in ``FILENAME.mod``. This user-supplied file contains the + model and the processing instructions, as described in + :ref:`model-file`. The options, listed below, can be passed on the + command line, following the name of the ``.mod`` file or in the + first line of the ``.mod`` file itself (see below). + + dynare begins by launching the preprocessor on the ``.mod + file``. By default (unless ``use_dll`` option has been given to + ``model``), the preprocessor creates three intermediary files: + + - ``filename.m`` + + Contains variable declarations, and computing tasks. + + - ``FILENAME_dynamic.m`` + + Contains the dynamic model equations. Note that Dynare might + introduce auxiliary equations and variables (see + :ref:`aux-variables`). Outputs are the residuals of the + dynamic model equations in the order the equations were + declared and the Jacobian of the dynamic model equations. For + higher order approximations also the Hessian and the + third-order derivatives are provided. When computing the + Jacobian of the dynamic model, the order of the endogenous + variables in the columns is stored in + ``M_.lead_lag_incidence``. The rows of this matrix represent + time periods: the first row denotes a lagged (time t-1) + variable, the second row a contemporaneous (time t) variable, + and the third row a leaded (time t+1) variable. The columns of + the matrix represent the endogenous variables in their order + of declaration. A zero in the matrix means that this + endogenous does not appear in the model in this time + period. The value in the ``M_.lead_lag_incidence`` matrix + corresponds to the column of that variable in the Jacobian of + the dynamic model. Example: Let the second declared variable + be ``c`` and the ``(3,2)`` entry of ``M_.lead_lag_incidence`` + be 15. Then the 15th column of the Jacobian is the derivative + with respect to ``c(+1)``. + + - ``FILENAME_static.m`` + + Contains the long run static model equations. Note that Dynare + might introduce auxiliary equations and variables (see + :ref:`aux-variables`). Outputs are the residuals of the static + model equations in the order the equations were declared and + the Jacobian of the static equations. Entry ``(i,j)`` of the + Jacobian represents the derivative of the ith static model + equation with respect to the jth model variable in declaration + order. + + + These files may be looked at to understand errors reported at the + simulation stage. + + ``dynare`` will then run the computing tasks by executing ``FILENAME.m``. + + A few words of warning are warranted here: the filename of the + ``.mod`` file should be chosen in such a way that the generated + ``.m`` files described above do not conflict with ``.m`` files + provided by MATLAB/Octave or by Dynare. Not respecting this rule + could cause crashes or unexpected behaviour. In particular, it + means that the ``.mod`` file cannot be given the name of a + MATLAB/Octave or Dynare command. Under Octave, it also means that + the ``.mod`` file cannot be named ``test.mod``. + + *Options* + + .. option:: noclearall + + By default, ``dynare`` will issue a ``clear all`` command to + MATLAB (` are + present, this option is used to limit the order of the + derivatives with respect to the parameters that are calculated + by the preprocessor. 0 means no derivatives, 1 means first + derivatives, and 2 means second derivatives. Default: 2 - .. option:: onlymacro + .. option:: nowarn - Instructs the preprocessor to only perform the - macro-processing step, and stop just after. Mainly useful for - debugging purposes or for using the macro-processor - independently of the rest of Dynare toolbox. + Suppresses all warnings. - .. option:: nolinemacro + .. option:: json = parse|transform|compute - Instructs the macro-preprocessor to omit line numbering - information in the intermediary ``.mod`` file created after - the macro-processing step. Useful in conjunction with - ``savemacro`` when one wants that to reuse the intermediary - ``.mod`` file, without having it cluttered by line numbering - directives. + Causes the preprocessor to output a version of the ``.mod`` + file in JSON format. - .. option:: nolog + If ``parse`` is passed, the output will be written after the + parsing of the ``.mod`` file to a file called + ``FILENAME.json``. - Instructs Dynare to no create a logfile of this run in - ``FILENAME.log.`` The default is to create the logfile. + If ``transform`` is passed, the JSON output of the transformed + model (maximum lead of 1, minimum lag of -1, expectation + operators substituted, etc.) will be written to a file called + ``FILENAME.json`` and the original, untransformed model will + be written in ``FILENAME_original.json``. - .. option:: params_derivs_order=0|1|2 + And if ``compute`` is passed, the output is written after the + computing pass. In this case, the transformed model is written + to ``FILENAME.json``, the original model is written to + ``FILENAME_original.json``, and the dynamic and static files + are written to ``FILENAME_dynamic.json`` and + ``FILENAME_static.json``. - When :comm:`identification`, :comm:`dynare_sensitivity` (with - identification), or :ref:`estimation_cmd ` are - present, this option is used to limit the order of the - derivatives with respect to the parameters that are calculated - by the preprocessor. 0 means no derivatives, 1 means first - derivatives, and 2 means second derivatives. Default: 2 + .. option:: jsonstdout - .. option:: nowarn + Instead of writing output requested by ``json`` to files, + write to standard out. - Suppresses all warnings. + .. option:: onlyjson - .. option:: json = parse|transform|compute + Quit processing once the output requested by ``json`` has been + written. - Causes the preprocessor to output a version of the ``.mod`` - file in JSON format. + .. option:: jsonderivsimple - If ``parse`` is passed, the output will be written after the - parsing of the ``.mod`` file to a file called - ``FILENAME.json``. + Print a simplified version (excluding variable name(s) and lag + information) of the static and dynamic files in + ``FILENAME_static.json`` and ``FILENAME_dynamic.``. - If ``transform`` is passed, the JSON output of the transformed - model (maximum lead of 1, minimum lag of -1, expectation - operators substituted, etc.) will be written to a file called - ``FILENAME.json`` and the original, untransformed model will - be written in ``FILENAME_original.json``. + .. option:: warn_uninit - And if ``compute`` is passed, the output is written after the - computing pass. In this case, the transformed model is written - to ``FILENAME.json``, the original model is written to - ``FILENAME_original.json``, and the dynamic and static files - are written to ``FILENAME_dynamic.json`` and - ``FILENAME_static.json``. + Display a warning for each variable or parameter which is not + initialized. See :ref:`param-init`, or + :comm:`load_params_and_steady_state + ` for initialization of + parameters. See :ref:`init-term-cond`, or + :comm:`load_params_and_steady_state + ` for initialization of + endogenous and exogenous variables. - .. option:: jsonstdout + .. option:: console - Instead of writing output requested by ``json`` to files, - write to standard out. + Activate console mode. In addition to the behavior of + ``nodisplay``, Dynare will not use graphical waitbars for long + computations. - .. option:: onlyjson + .. option:: nograph - Quit processing once the output requested by ``json`` has been - written. + Activate the ``nograph`` option (see :opt:`nograph`), so that + Dynare will not produce any graph. - .. option:: jsonderivsimple + .. option:: nointeractive - Print a simplified version (excluding variable name(s) and lag - information) of the static and dynamic files in - ``FILENAME_static.json`` and ``FILENAME_dynamic.``. + Instructs Dynare to not request user input. - .. option:: warn_uninit + .. option:: nopathchange - Display a warning for each variable or parameter which is not - initialized. See :ref:`param-init`, or - :comm:`load_params_and_steady_state - ` for initialization of - parameters. See :ref:`init-term-cond`, or - :comm:`load_params_and_steady_state - ` for initialization of - endogenous and exogenous variables. + By default Dynare will change Matlab/Octave’s path if + ``dynare/matlab`` directory is not on top and if Dynare’s + routines are overriden by routines provided in other + toolboxes. If one wishes to override Dynare’s routines, the + ``nopathchange`` options can be used. Alternatively, the path + can be temporarly modified by the user at the top of the + ``.mod`` file (using Matlab/Octave’s ``addpath`` command). - .. option:: console + .. option:: mingw - Activate console mode. In addition to the behavior of - ``nodisplay``, Dynare will not use graphical waitbars for long - computations. + Tells Dynare that your MATLAB is configured for compiling MEX + files with the MinGW compiler from TDM-GCC (see + :ref:`compil-install`). This option is only available under + Windows, and is used in conjunction with ``use_dll``. - .. option:: nograph + .. option:: msvc - Activate the ``nograph`` option (see :opt:`nograph`), so that - Dynare will not produce any graph. + Tells Dynare that your MATLAB is configured for compiling MEX + files with Microsoft Visual C++ (see + :ref:`compil-install`). This option is only available under + Windows, and is used in conjunction with ``use_dll``. - .. option:: nointeractive + .. option:: cygwin - Instructs Dynare to not request user input. + Tells Dynare that your MATLAB is configured for compiling MEX + files with Cygwin (see :ref:`compil-install`). This option is + only available under Windows, and is used in conjunction with + ``use_dll``. - .. option:: nopathchange + .. option:: parallel[=CLUSTER_NAME] - By default Dynare will change Matlab/Octave’s path if - ``dynare/matlab`` directory is not on top and if Dynare’s - routines are overriden by routines provided in other - toolboxes. If one wishes to override Dynare’s routines, the - ``nopathchange`` options can be used. Alternatively, the path - can be temporarly modified by the user at the top of the - ``.mod`` file (using Matlab/Octave’s ``addpath`` command). + Tells Dynare to perform computations in parallel. If + CLUSTER_NAME is passed, Dynare will use the specified cluster + to perform parallel computations. Otherwise, Dynare will use + the first cluster specified in the configuration file. See + :ref:`conf-file`, for more information about the configuration + file. - .. option:: mingw + .. option:: conffile=FILENAME - Tells Dynare that your MATLAB is configured for compiling MEX - files with the MinGW compiler from TDM-GCC (see - :ref:`compil-install`). This option is only available under - Windows, and is used in conjunction with ``use_dll``. + Specifies the location of the configuration file if it differs + from the default. See :ref:`conf-file`, for more information + about the configuration file and its default location. - .. option:: msvc + .. option:: parallel_slave_open_mode - Tells Dynare that your MATLAB is configured for compiling MEX - files with Microsoft Visual C++ (see - :ref:`compil-install`). This option is only available under - Windows, and is used in conjunction with ``use_dll``. + Instructs Dynare to leave the connection to the slave node + open after computation is complete, closing this connection + only when Dynare finishes processing. - .. option:: cygwin + .. option:: parallel_test - Tells Dynare that your MATLAB is configured for compiling MEX - files with Cygwin (see :ref:`compil-install`). This option is - only available under Windows, and is used in conjunction with - ``use_dll``. + Tests the parallel setup specified in the configuration file + without executing the ``.mod`` file. See :ref:`conf-file`, for + more information about the configuration file. - .. option:: parallel[=CLUSTER_NAME] + .. option:: -DMACRO_VARIABLE=MACRO_EXPRESSION - Tells Dynare to perform computations in parallel. If - CLUSTER_NAME is passed, Dynare will use the specified cluster - to perform parallel computations. Otherwise, Dynare will use - the first cluster specified in the configuration file. See - :ref:`conf-file`, for more information about the configuration - file. + Defines a macro-variable from the command line (the same + effect as using the Macro directive ``@#define`` in a model + file, see :ref:`macro-proc-lang`). - .. option:: conffile=FILENAME + .. option:: -I<> - Specifies the location of the configuration file if it differs - from the default. See :ref:`conf-file`, for more information - about the configuration file and its default location. + Defines a path to search for files to be included by the + macroprocessor (using the ``@#include`` command). Multiple + ``-I`` flags can be passed on the command line. The paths will + be searched in the order that the ``-I`` flags are passed and + the first matching file will be used. The flags passed here + take priority over those passed to ``@#includepath``. - .. option:: parallel_slave_open_mode + .. option:: nostrict - Instructs Dynare to leave the connection to the slave node - open after computation is complete, closing this connection - only when Dynare finishes processing. + Allows Dynare to issue a warning and continue processing when - .. option:: parallel_test + 1. there are more endogenous variables than equations. + 2. an undeclared symbol is assigned in ``initval`` or ``endval``. + 3. exogenous variables were declared but not used in the + ``model`` block. - Tests the parallel setup specified in the configuration file - without executing the ``.mod`` file. See :ref:`conf-file`, for - more information about the configuration file. + .. option:: fast - .. option:: -DMACRO_VARIABLE=MACRO_EXPRESSION + Only useful with model option ``use_dll``. Don’t recompile the + MEX files when running again the same model file and the lists + of variables and the equations haven’t changed. We use a 32 + bit checksum, stored in ``/checksum``. There + is a very small probability that the preprocessor misses a + change in the model. In case of doubt, re-run without the fast + option. - Defines a macro-variable from the command line (the same - effect as using the Macro directive ``@#define`` in a model - file, see :ref:`macro-proc-lang`). + .. option:: minimal_workspace - .. option:: -I<> + Instructs Dynare not to write parameter assignments to + parameter names in the .m file produced by the + preprocessor. This is potentially useful when running + ``dynare`` on a large ``.mod`` file that runs into workspace + size limitations imposed by MATLAB. - Defines a path to search for files to be included by the - macroprocessor (using the ``@#include`` command). Multiple - ``-I`` flags can be passed on the command line. The paths will - be searched in the order that the ``-I`` flags are passed and - the first matching file will be used. The flags passed here - take priority over those passed to ``@#includepath``. + .. option:: compute_xrefs - .. option:: nostrict + Tells Dynare to compute the equation cross references, writing + them to the output ``.m`` file. - Allows Dynare to issue a warning and continue processing when + These options can be passed to the preprocessor by listing them + after the name of the ``.mod`` file. They can alternatively be + defined in the first line of the ``.mod`` file, this avoids typing + them on the command line each time a ``.mod`` file is to be + run. This line must be a Dynare comment (ie must begin with //) + and the options must be comma separated between ``--+`` options: + and ``+--``. As in the command line, if an option admits a value + the equal symbol must not be surrounded by spaces. For instance + ``json = compute`` is not correct, and should be written + ``json=compute``. - 1. there are more endogenous variables than equations. - 2. an undeclared symbol is assigned in ``initval`` or ``endval``. - 3. exogenous variables were declared but not used in the ``model`` block. + *Output* - .. option:: fast + Depending on the computing tasks requested in the ``.mod`` file, + executing the ``dynare`` command will leave variables containing + results in the workspace available for further processing. More + details are given under the relevant computing tasks. The + ``M_``,``oo_``, and ``options_`` structures are saved in a file + called ``FILENAME_results.mat``. If they exist, ``estim_params_``, + ``bayestopt_``, ``dataset_``, ``oo_recursive_`` and + ``estimation_info`` are saved in the same file. - Only useful with model option ``use_dll``. Don’t recompile the - MEX files when running again the same model file and the lists - of variables and the equations haven’t changed. We use a 32 - bit checksum, stored in ``/checksum``. There - is a very small probability that the preprocessor misses a - change in the model. In case of doubt, re-run without the fast - option. + .. matvar:: M_ - .. option:: minimal_workspace + Structure containing various information about the model. - Instructs Dynare not to write parameter assignments to - parameter names in the .m file produced by the - preprocessor. This is potentially useful when running - ``dynare`` on a large ``.mod`` file that runs into workspace - size limitations imposed by MATLAB. + .. matvar:: options_ - .. option:: compute_xrefs + Structure contains the values of the various options used by + Dynare during the computation. - Tells Dynare to compute the equation cross references, writing - them to the output ``.m`` file. + .. matvar:: oo_ - These options can be passed to the preprocessor by listing them - after the name of the ``.mod`` file. They can alternatively be - defined in the first line of the ``.mod`` file, this avoids typing - them on the command line each time a ``.mod`` file is to be - run. This line must be a Dynare comment (ie must begin with //) - and the options must be comma separated between ``--+`` options: - and ``+--``. As in the command line, if an option admits a value - the equal symbol must not be surrounded by spaces. For instance - ``json = compute`` is not correct, and should be written - ``json=compute``. + Structure containing the various results of the computations. - *Output* + .. matvar:: dataset_ - Depending on the computing tasks requested in the ``.mod`` file, - executing the ``dynare`` command will leave variables containing - results in the workspace available for further processing. More - details are given under the relevant computing tasks. The ``M_, - oo_``, and ``options_`` structures are saved in a file called - ``FILENAME_results.mat``. If they exist, ``estim_params_, - bayestopt_, dataset_, oo_recursive_`` and ``estimation_info`` are - saved in the same file. + A ``dseries`` object containing the data used for estimation. + .. matvar:: oo_recursive_ - .. matvar:: M_ + Cell array containing the ``oo_`` structures obtained when + estimating the model for the different samples when performing + recursive estimation and forecasting. The ``oo_`` structure + obtained for the sample ranging to the `i` -th observation is + saved in the `i` -th field. The fields for non-estimated + endpoints are empty. - Structure containing various information about the model. + *Example* - .. matvar:: options_ - - Structure contains the values of the various options used by - Dynare during the computation. - - .. matvar:: oo_ - - Structure containing the various results of the computations. - - .. matvar:: dataset_ - - A ``dseries`` object containing the data used for estimation. - - .. matvar:: oo_recursive_ - - Cell array containing the ``oo_`` structures obtained when - estimating the model for the different samples when performing - recursive estimation and forecasting. The ``oo_`` structure - obtained for the sample ranging to the `i` -th observation is - saved in the `i` -th field. The fields for non-estimated - endpoints are empty. - - - :ex: - - Call dynare from the MATLAB or Octave prompt, without or with options: + Call dynare from the MATLAB or Octave prompt, without or with options: .. code-block:: matlab >> dynare ramst >> dynare ramst.mod savemacro - Alternatively the options can be passed in the first line - of ``ramst.mod``: + Alternatively the options can be passed in the first line of + ``ramst.mod``: .. code-block:: dynare // --+ options: savemacro, json=compute +-- - and then dynare called without passing options on the command - line: + and then dynare called without passing options on the command line: .. code-block:: matlab @@ -452,8 +450,8 @@ parser works, this is not the case. The most common example of misleading line and column numbers (and error message for that matter) is the case of a missing semicolon, as seen in the following example:: - varexo a, b - parameters c, ...; + varexo a, b + parameters c, ...; In this case, the parser doesn’t know a semicolon is missing at the end of the ``varexo`` command until it begins parsing the second line