diff --git a/doc/manual.xml b/doc/manual.xml index 488d76a6a..ec8f339ec 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -2171,7 +2171,7 @@ steady; 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. 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. If you know how to compute the steady state for your model, you can provide a MATLAB/Octave 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 IRFs are computed as the difference between the trajectory of a variable following a shock at the beginning of period 1 and its steady state value. @@ -2194,58 +2194,332 @@ steady; - + Auxiliary variables for leads and lags For a stochastic model, Dynare will perform a transformation of the model so that there is only one lead and one lag on endogenous, and no lead/lag on exogenous. This transformation is achieved by the creation of auxiliary variables, and corresponding equations. For example, if x(+2) exists in the model, Dynare will create one auxiliary variable AUX_ENDO_LEAD = x(+1), and replace x(+2) by AUX_ENDO_LEAD(+1). A similar transformation is done for lags greater than 2 on endogenous (auxiliary variables will have a name beginning with AUX_ENDO_LAG), and for exogenous with leads and lags (auxiliary variables will have a name beginning with AUX_EXO_LEAG or AUX_EXO_LAG respectively). Once created, all auxiliary variables are included in the set of endogenous variables. The output of decision rules (see below) is such that auxiliary variable names are replaced by the original variables they refer to. + The number of endogenous variables before the creation of auxiliary variables is stored in M_.orig_endo_nbr, and the number of endogenous variables after the creation of auxiliary variables is stored in M_.endo_nbr. Decision rules - The approximated solution of a model takes the form of a set of decision rules or transition equations expressing the current value of the endogenous variables of the model as function of the previous state of the model and shocks oberved at the beginning of the period. + The approximated solution of a model takes the form of a set of decision + rules or transition equations expressing the current value of the endogenous + variables of the model as function of the previous state of the model and + shocks oberved at the beginning of the period. The decision rules are stored + in the structure oo_.dr which is described below. + +Typology and ordering of variables + + Dynare distinguishes four types of endogenous variables: + + + + Purely backward (or purely predetermined) variables + + + Those that appear only at current and past period in the model, but not + at future period (i.e. at + t and t-1 but not + t+1). The number of such variables is equal to + oo_.dr.npred - oo_.dr.nboth. + + + + + Purely forward variables + + + Those that appear only at current and future period in the model, but + not at past period (i.e. at + t and t+1 but not + t-1). The number of such variables is stored in + oo_.dr.nfwrd. + + + + + Mixed variables + + + Those that appear at current, past and future period in the model + (i.e. at t, + t+1 and t-1). The number of such + variables is stored in oo_.dr.nboth. + + + + + Static variables + + + Those that appear only at current, not past and future period in the + model (i.e. only at + t, not at t+1 or + t-1). The number of such variables is stored in + oo_.dr.nstatic. + + + + + + + Note that all endogenous variables fall into one of these four categories, + since after the creation of auxiliary + variables, all endogenous have at most one lead and one lag. We + therefore have the following identity: oo_.dr.npred + oo_.dr.nfwrd + + oo_.dr.nstatic = M_.endo_nbr. + + + + Internally, Dynare uses two orderings of the endogenous variables: the order + of declaration (which is reflected in M_.endo_names), and + an order based on the four types described above, which we will call the + DR-order ("DR" stands for decision rules). Most of the time, the declaration + order is used, but for elements of the decision rules, the DR-order is used. + + + The DR-order is the following: static variables appear first, then purely + backward variables, then mixed variables, and finally purely forward + variables. Inside each category, variables are arranged according to the + declaration order. + + + Variable oo_.dr.order_var maps DR-order to declaration + order, and variable oo_.dr.inv_order_var contains the + inverse map. In other words, the k-th variable in the DR-order corresponds + to the endogenous variable numbered oo_.dr_order_var(k) in + declaration order. Conversely, k-th declared variable is numbered + oo_.dr.inv_order_var(k) in DR-order. + + + Finally, the state variables of the model are the purely backward variables + and the mixed variables. They are orderer in DR-order when they appear in + decision rules elements. There are oo_.dr.npred such + variables. + + + + First order approximation -
- yt = ys + A yht-1 + B ut - + - where ys is the steady state value of y and yht=yt-ys. + The approximation has the form: +
+ + yt = ys + A yht-1 + B + ut +
+ + where ys is the steady state value of y and + yht=yt-ys. + + + + The coefficients of the decision rules are stored as follows: + + + + ys is stored in oo_.dr.ys. The vector rows + correspond to all endogenous in the declaration order. + + + + + A is stored in oo_.dr.ghx. The matrix rows + correspond to all endogenous in DR-order. The matrix columns correspond + to state variables in DR-order. + + + + + B is stored oo_.dr.ghu. The matrix rows correspond + to all endogenous in DR-order. The matrix columns correspond to + exogenous variables in declaration order. + + + + + + Second order approximation -
- yt = ys + 0.5Δ2 + A yht-1 + B ut + 0.5C(yht-1⊗yht-1) + 0.5D(ut⊗ut) + E(yht-1⊗ut) - + - where ys is the steady state value of y, yht=yt-ys, and Δ2 is the shift effect of the variance of future shocks. + The approximation has the form: +
+ + yt = ys + 0.5 Δ2 + + A yht-1 + B ut + 0.5 C + (yht-1⊗yht-1) + 0.5 D + (ut⊗ut) + E + (yht-1⊗ut) +
+ + where ys is the steady state value of y, + yht=yt-ys, and + Δ2 is the shift effect of the variance of + future shocks. + + + + The coefficients of the decision rules are stored in the variables described + for first order approximation, plus the following variables: + + + + Δ2 is stored in + oo_.dr.ghs2. The vector rows correspond to all + endogenous in DR-order. + + + + + C is stored in oo_.dr.ghxx. The matrix rows + correspond to all endogenous in DR-order. The matrix columns correspond + to the Kronecker product of the vector of state variables in DR-order. + + + + + D is stored in oo_.dr.ghuu. The matrix rows + correspond to all endogenous in DR-order. The matrix columns correspond + to the Kronecker product of exogenous variables in declaration order. + + + + + E is stored in oo_.dr.ghxu. The matrix rows + correspond to all endogenous in DR-order. The matrix columns correspond + to the Kronecker product of the vector of state variables (in DR-order) + by the vector of exogenous variables (in declaration order). + + + + + + +Third order approximation + + + The approximation has the form: + +
+ + yt = ys + G0 + + G1 zt + + G2 (zt⊗ + zt) + G3 + (zt⊗ zt ⊗ + zt) + +
+ + where ys is the steady state value of y, and zt is a + vector consisting of the deviation from the steady state of the state + variables (in DR-order) at date t-1 followed by the exogenous variables at + date t (in declaration order). The vector zt is + therefore of size nz = oo_.dr.npred + + M_.exo_nbr. + + + + The coefficients of the decision rules are stored as follows: + + + + ys is stored in oo_.dr.ys. The vector rows + correspond to all endogenous in the declaration order. + + + + + G0 is stored in oo_.dr.g_0. The + vector rows correspond to all endogenous in DR-order. + + + + + G1 is stored in oo_.dr.g_1. The + matrix rows correspond to all endogenous in DR-order. The matrix + columns correspond to state variables in DR-order, followed by + exogenous in declaration order. + + + + + G2 is stored in + oo_.dr.g_2. The matrix rows correspond to all + endogenous in DR-order. The matrix columns correspond to the Kronecker + product of state variables (in DR-order), followed by exogenous (in + declaration order). Note that the Kronecker product is stored in a + folded way, i.e. symmetric elements are + stored only once, which implies that the matrix has + nz(nz+1)/2 columns. More + precisely, each column of this matrix corresponds to a pair + (i1, i2) where each index + represents an element of zt and is therefore + between 1 and nz. Only non-decreasing pairs are + stored, i.e. those for which + i1 ≤ i2. The columns + are arranged in the lexicographical order of non-decreasing pairs. Also + note that for those pairs where i1 ≠ + i2, since the element is stored only once but + appears two times in the unfolded G2 matrix, it + must be multiplied by 2 when computing the decision rules. + + + + + G3 is stored in + oo_.dr.g_3. The matrix rows correspond to all + endogenous in DR-order. The matrix columns correspond to the third + Kronecker power of state variables (in DR-order), followed by exogenous + (in declaration order). Note that the third Kronecker power is stored + in a folded way, i.e. symmetric elements + are stored only once, which implies that the matrix has + nz(nz+1)(nz+2)/6 + columns. More precisely, each column of this matrix corresponds to a + tuple (i1, i2, + i3) where each index represents an element of + zt and is therefore between 1 and + nz. Only non-decreasing tuples are stored, + i.e. those for which + i1 ≤ i2 ≤ + i3. The columns are arranged in the + lexicographical order of non-decreasing tuples. Also note that for + tuples that have three distinct indices + (i.e. i1 ≠ + i2 and i1 ≠ + i3 and i2 ≠ + i3), since these elements are stored only once + but appears six times in the unfolded G3 matrix, + they must be multiplied by 6 when computing the decision + rules. Similarly, for those tuples that have two equal indices + (i.e. of the form (a,a,b) or (a,b,a) or + (b,a,a)), since these elements are stored only once but appears three + times in the unfolded G3 matrix, they must be + multiplied by 3 when computing the decision rules. + + + + + + -Output variables +Other output variables - stoch_simul sets several fields in global variable oo_. The descriptive statistics are theoretical moments when no simulation is requested and otherwise represent the moments of the simulated variables. + stoch_simul sets other fields in global variable oo_. The descriptive statistics are theoretical moments when no simulation is requested and otherwise represent the moments of the simulated variables. - the coefficients of the decision rules are stored in global structure oo_.dr. Here is the correspondance with the symbols used in the above description of the decision rules: - Decision rule coefficients - - ys: oo_.dr.ys. The vector rows correspond to variables in the declaration order of the variable names. - Δ2: oo_.dr.ghs2. The vector rows correspond to re-ordered variables (see below). - A: oo_.dr.ghx. The matrix rows correspond to re-ordered variables (see below). The matrix columns correspond to state variables (see below). - B: oo_.dr.ghu. The matrix rows correspond to re-ordered variables (see below). The matrix columns correspond to exogenous variables in declaration order. - C: oo_.dr.ghxx. The matrix rows correspond to re-ordered variables (see below). The matrix columns correspond to the Kronecker product of the vector of state variables (see below). - D: oo_.dr.ghuu. The matrix rows correspond to re-ordered variables (see below). The matrix columns correspond to the Kronecker product of exogenous variables in declaration order. - E: oo_.dr.ghxu. The matrix rows correspond to re-ordered variables (see below). The matrix columns correspond to the Kronecker product of the vector of state variables (see below) by the vector of exogenous variables in declaration order. - - When reordered, the variables are stored in the following order: static variables, purely predetermined variables (variables that appear only at the current and lagged periods in the model), variables that are both predetermined and forward-looking (variables that appear at the current, future and lagged periods in the model), purely forward-looking variables (variables that appear only at the current and future periods in the model). In each category, the variables are arranged in declaration order. Variable oo_.dr.order_var maps reordered variables to declaration order, and variable oo_.dr.inv_order_var contains the inverse map. In other words, the first row in transition matrices corresponds to the endogenous declared at position oo_.dr_order_var(1); conversely, first declared variable has row oo_.dr.inv_order_var(1) in transition matrices. - - The state variables of the model are purely predetermined variables and variables that are both predetermined and forward-looking. They are ordered in that order. When there are lags on more than one period, the state variables are ordered first according to their lag: first variables from the previous period, then variables from two periods before and so on. Note also that when a variable appears in the model at a lag larger than one period, it is automatically included at all inferior lags. - - The mean of the endogenous variables is available in the vector oo_.mean. The variables are arranged in declaration order. The matrix of variance-covariance of the endogenous variables in the matrix oo_.var. The variables are arranged in declaration order. @@ -2253,14 +2527,21 @@ steady; - Simulated variables, when they have been computed, are available in MATLAB - vectors with the same name as the endogenous variables. They are also available in the oo_.endo_simul matrix. The series are arranged by row, in declaration order of the variable names + Simulated variables, when they have been computed, are available in + MATLAB/Octave vectors in the + global workspace with the same name as the endogenous variables. They + are also available in the oo_.endo_simul matrix. The + series are arranged by row, in declaration order of the variable + names Impulse responses, when they have been computed, are available in oo_.irfs, with the following naming convention: VARIABLE_NAME_SHOCK_NAME. - (DEPRECATED) They are currently also available in MATLAB vectors in the global workspace, however they will disappear there in a future version. + + (DEPRECATED) They are currently also available in MATLAB/Octave vectors in the global + workspace, however they will disappear there in a future version. Example: