Nash-Ramsey Toolbox
==================

This toolbox computes Nash and Ramsey equilibria for DSGE models using
Dynare.  It supports Dynare 6.5 and Dynare 7.0.  It accompanies the JME
paper; the replication scripts and worked examples are included alongside
the core programs.

Instructions are available at http://www.lguerrieri.com/Nash_ramsey_website/

If using this toolbox please cite

@article{BGL2019,
  author  = {Bodenstein, Martin and Guerrieri, Luca and LaBriola, Joe},
  title   = {{Macroeconomic Policy Games}},
  journal = {Journal of Monetary Economics},
  year    = {2019},
  volume  = {101},
  pages   = {64--81},
  doi     = {10.1016/j.jmoneco.2018.07.015},
}


FIRST-TIME SETUP
----------------
Before using the toolbox for the first time, or after moving it to a new
location, run the following from the MATLAB command window:

    run setup_toolbox

This detects Dynare 6.5 and Dynare 7.0 in their standard installation
locations and embeds absolute paths into setpathdynare6_5.m and
setpathdynare7_0.m.  It only needs to be run once per location.  A
warning (not an error) is issued if only one Dynare version is found.


DIRECTORY STRUCTURE
-------------------

nash_ramsey_toolbox_051626/          <- toolbox root
|
|-- setup_toolbox.m                  <- run once after installation (see above)
|-- setpathdynare6_5.m               <- path-setup for Dynare 6.5; call at session start
|-- setpathdynare7_0.m               <- path-setup for Dynare 7.0; call at session start
|-- run_tests.m                      <- verify toolbox compatibility with installed Dynare
|-- call_cleanup.m                   <- remove Dynare output from all example directories
|
|-- toolbox_programs/                <- core toolbox (83 .m files)
|       create_ramsey.m              solve Ramsey optimal policy problem
|       get_nash.m                   solve Nash equilibrium
|       get_ramsey.m                 solve Ramsey equilibrium
|       convertmodfiles.m            convert .mod files for toolbox use
|       dynparse.m                   Dynare .mod file parser
|       cleanup_dynare_dir.m         remove Dynare output from a directory
|       ... (and more)
|
|-- utilities/                       <- plotting and helper functions (47 .m files)
|       makeirf.m                    impulse response function charts
|       makechart*.m                 chart-generation helpers
|       printpref*.m                 print/export helpers
|       hpfast.m, bpass.m            filtering utilities
|       anneal.m                     simulated annealing optimizer
|       ... (and more)
|
|-- JME_paper/
|       main.pdf                     the published paper
|
|-- JME_paper_replication_and_examples/
|       readme.txt                   describes each example in detail
|       BBCDL_model_excl2ndorder/    figures 1, 2, 4 and table 1
|       BBCDL_model_2ndorder/        figure 3
|       GK_model/                    figures 5-6
|       GK_model_with_altruism/      figure 7
|       LQ_BBCDL_model/              LQ verification
|
|-- tests/
|       test_convertmodfiles/        source files for the convertmodfiles test
|       test_results/                timestamped .mat files from run_tests


STARTING A SESSION
------------------
At the top of any script that uses the toolbox, add one of:

    run setpathdynare6_5      % if using Dynare 6.5
    run setpathdynare7_0      % if using Dynare 7.0

Each setpath file adds Dynare, toolbox_programs, and utilities to the
MATLAB path.  Because they contain absolute paths (written by
setup_toolbox), they work correctly regardless of which subdirectory you
run them from.

Both setpathdynare6_5.m and setpathdynare7_0.m are present in every
example subdirectory so you can run examples directly from that folder.


TESTING
-------
To verify that the toolbox works with the installed Dynare version, call
the appropriate setpath script first, then run:

    run_tests          % auto-detects Dynare version
    run_tests('6.5')   % label results as Dynare 6.5
    run_tests('7.0')   % label results as Dynare 7.0

Results are saved to tests/test_results/ as timestamped .mat files.


CLEANING UP
-----------
Dynare writes output files (.log, .eps, package directories, etc.) into
each model directory.  To remove all generated output from every example
subdirectory while preserving source files, run from the toolbox root:

    run call_cleanup


HOW setup_toolbox WORKS
------------------------
MATLAB scripts typically set paths with relative references such as
'../../utilities', which break as soon as the calling script is moved to
a different folder depth.

setup_toolbox.m solves this by:

  1. Using mfilename('fullpath') to locate itself, which always returns
     the correct absolute path regardless of MATLAB's current working
     directory or operating system.

  2. Building absolute paths to utilities/ and toolbox_programs/ with
     fullfile(), which uses the correct separator (/ on Mac/Linux, \ on
     Windows) automatically.

  3. Reading each setpathdynare*.m file and replacing the dir2, dir3, and
     dynare_path assignments in-place with the absolute paths computed
     for the detected Dynare version.

After setup_toolbox has been run, any setpathdynare*.m file can be copied
into any subfolder of the project and will still point to the right
directories.


DYNARE VERSION
--------------
The toolbox supports Dynare 6.5 and Dynare 7.0.  setup_toolbox looks for
each version in the standard installation locations:

  Mac (Apple Silicon)   /Applications/Dynare/<version>-arm64/matlab
  Mac (Intel)           /Applications/Dynare/<version>/matlab
  Windows               C:\dynare\<version>\matlab
  Linux                 /usr/lib/dynare/<version>/matlab

If a version is installed elsewhere, set the dynare_path variable at the
top of the relevant setpathdynare*.m file to the full path of its matlab
subdirectory.
