NewFeatures.md

@@ -5,60 +5,97 @@ the [DynareWiki](http://www.dynare.org/DynareWiki/NewFeatures).
 Dynare 6
 --------
 
- - Different versions of Dynare are now available as [Docker Containers](https://hub.docker.com/r/dynare/dynare).
+ - Implementation of the Sequential Monte-Carlo sampler (new value `hssmc` for option `posterior_sampling_method`) as described by Herbst and Schorfheide (JAE, 2014).
 
  - New perfect foresight simulation with expectation errors. In such a scenario, agents make expectation errors, in the sense that the path they had anticipated in period 1 does not realize exactly. More precisely, in some simulation periods, they may receive new information that makes them revise their anticipation for the path of future shocks. Also, under this scenario, it is assumed that agents behave as under perfect foresight, *i.e.* they take their decisions as if there was no uncertainty and they knew exactly the path of future shocks; the new information that they may receive comes as a total surprise to them. Implemented by new `perfect_foresight_with_expectation_errors_setup` and `perfect_foresight_with_expectation_errors_solver` commands, and `shocks(learnt_in=…)`, `mshocks(learnt_in=…)` and `endval(learnt_in=…)` blocks.
 
- - Pruning à la Andreasen et al. (2018) is now available at an arbitrary approximation order when performing stochastic simulations with `stoch_simul` (!2147)
+ - IRF matching with stochastic simulations:
+   - Dynare supports both Frequentist (as in Christiano, Eichenbaum, and Evans (2005, JPE)) as well as Bayesian IRF matching approaches (as in Christiano, Trabandt, and Walentin (2010, Handbook)). The core idea of IRF matching is to treat empirical impulse responses (e.g. given from a SVAR or local projection estimation) as data and select model parameters that align the model's IRFs closely with their empirical counterparts. (!2191)
+   - New options to `method_of_moments` command. (preprocessor!85)
+   - New blocks `matched_irfs` and `matched_irfs_weights` to specify the values and weights of the empirical impulse response functions. (preprocessor#124)
+
+ - Pruning à la Andreasen et al. (2018) is now available at an arbitrary approximation order when performing stochastic simulations with `stoch_simul` (!2147), and at 3rd order when performing particle filtering (!2071, particles!16, !2045)
+
+ - New `log` option to the `var` statement. In addition to the endogenous variable(s) thus declared, this option also triggers the creation of auxiliary variable(s) equal to the log of the corresponding endogenous variable(s). For example, given a ``var(log) y`` statement, two endogenous will be created (``y`` and ``LOG_y``), and an auxiliary equation linking the two will also be added (equal to ``y = exp(LOG_y)``). Moreover, every occurrence of ``y`` in the model will be replaced by ``exp(LOG_y)``. This option is for example useful when one wants to perform a loglinear approximation of some variable(s) in the context of a first-order stochastic approximation; or when one wants to ensure the variable(s) stay(s) in the definition domain of the function defining the steady state or the dynamic residuals when the nonlinear solver is used. (#349)
+
+ - New model editing features (21a8a5794a83b5098cad0fe7beab93dcbe5ef6bf and 4db28998687b8845568e8750d99a1b45f0d6a94f)
+
+   - multiple `model` blocks are now supported (this was already working but not explicitly documented)
+
+   - :warning: multiple `estimated_params` blocks now concatenate their contents, instead of overwriting previous ones; an `overwrite` option has been implemented to provide the old (undocumented) behaviour (preprocessor@60ef6bbdbd2f95b7f8d52b1c10cf6bb9aa7773cc, preprocessor@ea44aa19d6dd2bf4c508ee081b2b6cae2a647250)
+
+   - new `model_options` statement to set model options in a global fashion (preprocessor#19)
+
+   - new `model_remove` command to remove equations (preprocessor@1f004584e9c8b2ea5fbda6dd5413b516ce956679)
+
+   - new `model_replace` block to replace equations (preprocessor@1f004584e9c8b2ea5fbda6dd5413b516ce956679)
+
+   - new `var_remove` command to remove variables (or parameters) (preprocessor@342c4faf8d95169b7391507e703c88d76b38a243)
+
+   - new `estimated_params_remove` block to remove estimated parameters (preprocessor@5ffbc5bad31c306f561d673cde36d460cb5906c1)
+
+ - Stochastic simulations
+
+   - Performance improvements for k-order perturbation simulation and particle filtering at higher order (⩾ 3). (#1802, !2071, particles!16, !2045)
+
+   - Performance improvement for the first order perturbation solution using either cycle reduction (`dr=cycle_reduction` option) or logarithmic reduction (`dr=logarithmic_reduction`) (!2085, !2089)
+
+   - New option `nomodelsummary` to the `stoch_simul` command, to suppress the printing of the model summary and the covariance of the exogenous shocks (a00eb5e1ded61d2e0086f841203a5eec96e77931)
+
+ - Estimation
 
    - New `conditional_likelihood` option to the `estimation` command. When the option is set, instead of using the Kalman filter to evaluate the likelihood, Dynare will evaluate the conditional likelihood based on the first order reduced form of the model, by assuming that the initial state vector is 0 for all the endogenous variables. (b7693c32, f7694208)
 
    - The `estimation` command now accepts the `additional_optimizer_steps` option, to sequentially execute several optimizers when looking for the posterior mode (!2178)
 
- - The `generate_trace_plots`-command now allows comparing multiple chains. (baf8243f)
+   - The `generate_trace_plots` command now allows comparing multiple chains. (baf8243f)
 
    - The Geweke and Raftery-Lewis convergence diagnostics will now also be displayed in case of `mh_nblocks>1`. (d0e99daf9ae84cf3a605fa4cf49d506d36b2bd95)
 
- - Steady state computation now allows accounting for `MCP`-tags (https://git.dynare.org/Dynare/dynare/-/merge_requests/1877)
+   - New optimizer options `robust`, `TolGstep`, and `TolGstepRel` to optimizer 5 `newrat` (!2231)
 
- - New option `tolx` of `steady` that governs the termination based on the step tolerance (https://git.dynare.org/Dynare/preprocessor/-/merge_requests/60)
- - New option `fsolve_options` to `steady` for setting options to `fsolve` when `solve_algo=0` (#1856)
+   - Possibility of specifying a truncated normal distribution as a prior, using the 3rd and 4th parameters of the `estimated_params` block as the bounds (!2161)
 
- - New optimizer options `robust`, `TolGstep`, and `TolGstepRel` to optimizer 5 `newrat` (!2231)
+   - New `brooks_gelman_plotrows` option to the `estimation` command for controlling the number of parameters to depict along the rows of the figures depicting the Brooks and Gelman (1998) convergence diagnostics (!2146)
+
+   - :warning: the default value of the `mode_compute` option of the `estimation` command has been changed to `5` (it was previously `4`)
 
    - :warning: New `estimation`-option `mh_init_scale_factor` replacing the deprecated `mh_init_scale` to govern the overdispersion of the starting draws when initializing several Monte Carlo Markov Chains (!2041).
 
- - :warning: Dynare will not duplicate information stored in `oo_.endo_simul, oo_.exo_simul`, and `oo_.irfs` in the base workspace. New helper functions `send_endogenous_variables_to_workspace`, `send_exogenous_variables_to_workspace`, and `send_irfs_to_workspace` can be used to explicitly request these outputs and to mimic the old behavior (!2229). 
+   - :warning: `mode_compute` will recursively update the covariance matrix across the `NumberOfMh` Metropolis-Hastings runs, starting with the `InitialCovarianceMatrix` in the first run, instead of computing it from scratch in every Metropolis-Hastings run (e5102eee)
 
- - OccBin:
-   - new `reset_check_ahead_periods_in_new_period`-option that allows resetting `check_ahead_periods` in each simulation period (3765ef77)
-   - new `simul_max_check_ahead_periods`, `likelihood_max_check_ahead_periods`, and `smoother_max_check_ahead_periods`-options to truncate the number of periods for which agents check ahead which regime is present (2f236048 and preprocessor@ed95a2ca )
+ - Steady state computation
 
- - New `log` option to the `var` statement. In addition to the endogenous variable(s) thus declared, this option also triggers the creation of auxiliary variable(s) equal to the log of the corresponding endogenous variable(s). For example, given a ``var(log) y`` statement, two endogenous will be created (``y`` and ``LOG_y``), and an auxiliary equation linking the two will also be added (equal to ``y = exp(LOG_y)``). Moreover, every occurrence of ``y`` in the model will be replaced by ``exp(LOG_y)``. This option is for example useful when one wants to perform a loglinear approximation of some variable(s) in the context of a first-order stochastic approximation; or when one wants to ensure the variable(s) stay(s) in the definition domain of the function defining the 
-steady state or the dynamic residuals when the nonlinear solver is used. (#349)
+   - Steady state computation now allows accounting for `mcp` tags (!1877)
 
- - The `osr` command now accepts the `analytical_derivation` and `analytical_derivation_mode` options (!2171)
+   - New option `tolx` of `steady` that governs the termination based on the step tolerance (preprocessor!60)
 
- - Possibility of specifying a truncated normal distribution as a prior, using the 3rd and 4th parameters of the `estimated_params` block as the bounds (!2161)
+   - New option `fsolve_options` to `steady` for setting options to `fsolve` when `solve_algo=0` (#1856)
 
- - New `display_parameter_values` command to print the parameter values to the command window (!2268).
+   - Homotopy: new option `from_initval_to_endval` option to the `homotopy_setup` block, for easily computing homotopy from initial to terminal steady state (when the former is already computed) (2e3fbfc0408a360dd169c927a5ea38c89f6ff95c)
 
- - New `collapse_figures_in_tabgroup` command to dock all figure (!2263)
+   - New `non_zero` option to `resid` command to restrict display to non-zero residuals (preprocessor@9db21a231c5ab8f8aa26680ffecf3abfcf45bfab, 3d7299c1e490a6813de2b2cb450b738b4c7acdf9); :warning: the old syntax `resid(1)` is not supported anymore
 
- - New option `kind` in the `pac_model` command.  This option allows the user to select the formula used to compute the weights on the VAR companion matrix variables that are used to form PAC expectations. See b297353b06c9c35223500439c0bc63321675768b.
 
- - Allows decomposition of the PAC target into an arbitrary number of components. (b297353b06c9c35223500439c0bc63321675768b)
+ - OccBin
 
- - Perfect foresight: significant performance improvement of `stack_solve_algo=1` (LBJ algorithm) when used in conjuction with options `block` and/or `bytecode` of the `model` block (17b016d983be260aa09926809d1f3465307c58e2, be648d350b162152e999b8ffad830dce6b373190, 77a7d5c3dec67b6d9943fc23c11afbb1d0cfd431)
+   - new `reset_check_ahead_periods_in_new_period`-option that allows resetting `check_ahead_periods` in each simulation period (3765ef77)
 
- - Performance improvements for k-order perturbation simulation and particle
-   filtering at higher order (⩾ 3). (#1802, !2071, particles!16, !2045)
+   - new `simul_max_check_ahead_periods`, `likelihood_max_check_ahead_periods`, and `smoother_max_check_ahead_periods`-options to truncate the number of periods for which agents check ahead which regime is present (2f236048 and preprocessor@ed95a2ca )
 
- - Pruning now available for 3rd order particle filtering (!2071, particles!16, !2045)
+ - Optimal policy
+
+   - The `osr` command now accepts the `analytical_derivation` and `analytical_derivation_mode` options (!2171)
 
    - `evaluate_planner_objective` can now compute the unconditional welfare for order ⩾ 3. (!1962)
 
- - Performance improvement for the first order perturbation solution using either cycle reduction (`dr=cycle_reduction` option) or logarithmic reduction (`dr=logarithmic_reduction`) (!2085, !2089)
+   - New options `periods` and `drop` to `evaluate_planner_objective` (!1967)
+
+
+
+ - Perfect foresight
+
+   - Significant performance improvement of `stack_solve_algo=1` (LBJ algorithm) when used in conjuction with options `block` and/or `bytecode` of the `model` block (17b016d983be260aa09926809d1f3465307c58e2, be648d350b162152e999b8ffad830dce6b373190, 77a7d5c3dec67b6d9943fc23c11afbb1d0cfd431)
 
    - When using block decomposition (with the `block` option of the `model` block), the option `mfs` now defaults to `1`. This setting should deliver better performance on most models, so it is a better default value.
 
@@ -66,35 +103,41 @@ steady state or the dynamic residuals when the nonlinear solver is used. (#349)
 
    - New option `static_mfs` to the `model` block (and the `model_options` command). Controls the minimum feedback set computation for the static model. Defaults to `0` (corresponding to the behaviour in Dynare 5.x)
 
- - Perfect foresight homotopy:
+   - Homotopy
+
      - New `endval_steady` option to `perfect_foresight_setup` command to compute terminal steady state as the same time as the transitory dynamics (and new options `steady_solve_algo`, `steady_tolf`, `steady_tolx`, `steady_maxit` and `steady_markowitz` to control the steady state nonlinear solver) (d5a3a8e16af56af23c8eb27a693b2e67579bfde0)
+
      - New `homotopy_linearization_fallback` and `homotopy_marginal_linearization_fallback` options to `perfect_foresight_solver` command to get an approximate solution when homotopy fails to go to 100% (d5a3a8e16af56af23c8eb27a693b2e67579bfde0)
+
      - New `homotopy_initial_step_size`, `homotopy_min_step_size`, `homotopy_step_size_increase_success_count` and `homotopy_max_completion_share` to `perfect_foresight_solver` command to fine tune the homotopy behaviour (d5a3a8e16af56af23c8eb27a693b2e67579bfde0)
+
      - Purely backward/forward/static models are now supported (fe142b663ef34d26969191d2a096b08aecc1eb10)
 
- - Steady state homotopy: new option `from_initval_to_endval` option to the `homotopy_setup` block, for easily computing homotopy from initial to terminal steady state (when the former is already computed) (2e3fbfc0408a360dd169c927a5ea38c89f6ff95c)
+   - The `stack_solve_algo=1` and `stack_solve_algo=6` options were merged. Both are now synonymous, and provide the LBJ algorithm. They work both with and without the `block` and `bytecode` options. Using `stack_solve_algo=1` is now recommended, but `stack_solve_algo=6` is kept for backward compatibility reasons (06f665e231c1a66863612eb75802ff4f0b698c57)
 
- - New model editing features (21a8a5794a83b5098cad0fe7beab93dcbe5ef6bf and 4db28998687b8845568e8750d99a1b45f0d6a94f)
 
-   - multiple `model` blocks are now supported (this was already working but not explicitly documented)
+ - Semi-structural models
 
-   - :warning: multiple `estimated_params` blocks now concatenate their contents, instead of overwriting previous ones; an `overwrite` option has been implemented to provide the old (undocumented) behaviour (preprocessor@60ef6bbdbd2f95b7f8d52b1c10cf6bb9aa7773cc, preprocessor@ea44aa19d6dd2bf4c508ee081b2b6cae2a647250)
+   - Allows decomposition of the PAC target into an arbitrary number of components. (b297353b06c9c35223500439c0bc63321675768b)
 
-   - new `model_options` statement to set model options in a global fashion (preprocessor#19)
+   - New option `kind` in the `pac_model` command.  This option allows the user to select the formula used to compute the weights on the VAR companion matrix variables that are used to form PAC expectations. See b297353b06c9c35223500439c0bc63321675768b.
 
-   - new `model_remove` command to remove equations (preprocessor@1f004584e9c8b2ea5fbda6dd5413b516ce956679)
+   - Performance improvement to `solve_algo=12` and `solve_algo=14` (which can significantly accelerate the simulation of purely backward/static/forward models)
 
-   - new `model_replace` block to replace equations (preprocessor@1f004584e9c8b2ea5fbda6dd5413b516ce956679)
 
-   - new `var_remove` command to remove variables (or parameters) (preprocessor@342c4faf8d95169b7391507e703c88d76b38a243)
+ - dseries:
 
-   - new `estimated_params_remove` block to remove estimated parameters (preprocessor@5ffbc5bad31c306f561d673cde36d460cb5906c1)
+   - The `remove` and `remove_` methods now accept a list of variables (it would previously accept only a single variable) (dseries@b7ca9c3e, c02e5505)
+   - new `--with-legend` option to the `dplot` command (dseries@44c36549)
 
- - When `use_dll` option of the `model` block is set, the preprocessor now takes advantage of parallelization when compiling the MEX files (preprocessor@f6053df7545174885486a457a2253897a1ed4e27, preprocessor@5cf4729ab0790084af0b0a9e9a1062ddefff3401, preprocessor@dd66459e5f2e5c57ea25cb4a0e8709b22ff3195b, preprocessor@3dd40c6c42d82997972e90899da8632a747f5c90)
 
- - New options `periods` and `drop` to `evaluate_planner_objective` (!1967)
+ - Misc
 
- - New option `nomodelsummary` to the `stoch_simul` command, to suppress the printing of the model summary and the covariance of the exogenous shocks (a00eb5e1ded61d2e0086f841203a5eec96e77931)
+   - New `display_parameter_values` command to print the parameter values to the command window (!2268).
+
+   - New `collapse_figures_in_tabgroup` command to dock all figure (!2263)
+
+   - When `use_dll` option of the `model` block is set, the preprocessor now takes advantage of parallelization when compiling the MEX files (preprocessor@f6053df7545174885486a457a2253897a1ed4e27, preprocessor@5cf4729ab0790084af0b0a9e9a1062ddefff3401, preprocessor@dd66459e5f2e5c57ea25cb4a0e8709b22ff3195b, preprocessor@3dd40c6c42d82997972e90899da8632a747f5c90)
 
    - Support for new mathematical primitives: complementary error function (`erfc`), hyperbolic functions (`cosh`, `sinh`, `tanh`, `acosh`, `asinh`, `atanh`) (preprocessor#85, preprocessor@c0ea8d72038cd6c57e48aca26d2d29866848ae0a)
 
@@ -102,29 +145,16 @@ steady state or the dynamic residuals when the nonlinear solver is used. (#349)
 
    - The `calib_smoother` command now accepts options `nobs` and `heteroskedastic_filter` (see !2110)
 
- - New `brooks_gelman_plotrows` option to the `estimation` command for controlling the number of parameters to depict along the rows of the figures depicting the Brooks and Gelman (1998) convergence diagnostics (!2146)
-
- - dseries:
-   - The `remove` and `remove_` methods now accept a list of variables (it would previously accept only a single variable) (dseries@b7ca9c3e, c02e5505)
-   - new `--with-legend` option to the `dplot` command (dseries@44c36549)
-
    - Under the MATLAB Desktop, autocompletion is now available for the `dynare` command and other CLI commands (thanks to Eduard Benet Cerda from MathWorks) (36a2a41e357780d468582c78c4cbb738c5bb4b26)
 
- - Performance improvement to `solve_algo=12` and `solve_algo=14` (which can significantly accelerate the simulation of purely backward/static/forward models)
-
- - :warning: New `non_zero` option to `resid` command to restrict display to non-zero residuals (preprocessor@9db21a231c5ab8f8aa26680ffecf3abfcf45bfab, 3d7299c1e490a6813de2b2cb450b738b4c7acdf9); the old syntax `resid(1)` is not supported anymore
-
- - The `stack_solve_algo=1` and `stack_solve_algo=6` options were merged. Both are now synonymous, and provide the LBJ algorithm. They work both with and without the `block` and `bytecode` options. Using `stack_solve_algo=1` is now recommended, but `stack_solve_algo=6` is kept for backward compatibility reasons (06f665e231c1a66863612eb75802ff4f0b698c57)
-
    - Model debugging: the preprocessor now creates files for evaluating separately the left- and right-hand sides of model equations. For a model file called `ramst.mod`, you can call `[lhs,rhs]=ramst.debug.static_resid(y,x,params);` (for the static model) and `[lhs,rhs]=ramst.debug.dynamic_resid(y,x,params,steady_state);` (for the dynamic model), where `y` are the endogenous, `x` the exogenous, `params` the parameters, and `steady_state` is self-explanatory. NB: In the dynamic case, the vector `y` of endogenous must have $3n$ elements where $n$ is the number of endogenous (including auxiliary ones); the first $n$ elements correspond to the lagged values, the middle $n$ elements to the contemporaneous values, and the last $n$ elements to the lead values.
 
    - New `search` interactive command for listing the equations in which given variable(s) appear (#1886)
-
- - :warning: the default value of the `mode_compute` option of the `estimation` command has been changed to `5` (it was previously `4`)
+   - :warning: Dynare will not duplicate information stored in `oo_.endo_simul, oo_.exo_simul`, and `oo_.irfs` in the base workspace. New helper functions `send_endogenous_variables_to_workspace`, `send_exogenous_variables_to_workspace`, and `send_irfs_to_workspace` can be used to explicitly request these outputs and to mimic the old behavior (!2229). 
 
    - :warning: The `dynare_sensitivity` command has been renamed `sensitivity`. The old name is still accepted, but will trigger a warning (66bc9fd9c2707c787efae797e1976b7052159dc4)
 
- - :warning: The `model_info`-command allows to print the block decomposition even if the `block`-option of the `model` has not been used by specifying the new options `block_static` and `block_dynamic`. The old `static`-option of the command is superseded by the `block_static`-option. (45450651 and preprocessor@2fd06811)
+   - :warning: The `model_info` command allows to print the block decomposition even if the `block`-option of the `model` has not been used by specifying the new options `block_static` and `block_dynamic`. The old `static`-option of the command is superseded by the `block_static`-option. (45450651 and preprocessor@2fd06811)
 
    - :warning: The default location for the configuration file has changed. On Linux and macOS, the configuration file is searched by default under `dynare/dynare.ini` in the configuration directories defined by the XDG specification (typically `$HOME/.config/dynare/dynare.ini` for the user-specific configuration and `/etc/xdg/dynare/dynare.ini` for the system-wide configuration, the former having precedence over the latter). Under Windows, the configuration file is searched by default in `%APPDATA%\dynare\dynare.ini` (typically `c:\Users\USERNAME\AppData\Roaming\dynare\dynare.ini`) (43b24facb)
 
@@ -142,14 +172,7 @@ steady state or the dynamic residuals when the nonlinear solver is used. (#349)
 
    - :warning: The `parallel_slave_open_mode` option of the `dynare` command has been renamed `parallel_follower_open_mode` (preprocessor#86, !1976)
 
- - :warning: `mode_compute` will recursively update the covariance matrix across the `NumberOfMh` Metropolis-Hastings runs, starting with the `InitialCovarianceMatrix` in the first run, instead of computing it from scratch in every Metropolis-Hastings run (e5102eee)
 
- - Implementation of the Sequential Monte-Carlo sampler (new value `hssmc` for option `posterior_sampling_method`) as described by Herbst and Schorfheide (JAE, 2014).
-
-- IRF matching with stochastic simulations:
-   - Dynare supports both Frequentist (as in Christiano, Eichenbaum, and Evans (2005, JPE)) as well as Bayesian IRF matching approaches (as in Christiano, Trabandt, and Walentin (2010, Handbook)). The core idea of IRF matching is to treat empirical impulse responses (e.g. given from a SVAR or local projection estimation) as data and select model parameters that align the model's IRFs closely with their empirical counterparts. (!2191)
-   - New options to `method_of_moments` command. (preprocessor!85)
-   - New blocks `matched_irfs` and `matched_irfs_weights` to specify the values and weights of the empirical impulse response functions. (preprocessor#124)
 
 Dynare 5
 --------