# README
This repository contains code to replicate the results in Auclert, Bardóczy, Rognlie, Straub (2021):
"Using the Sequence-Space Jacobian to Solve and Estimate Heterogeneous-Agent Models".

We will post any updates to this replication archive, such as streamlined implementations of the same models
and tasks, at https://github.com/shade-econ/ssj-replication. Please visit there if you are interested in
the most up-to-date version of the code.

A separate, general-purpose toolkit to solve and estimate models in sequence space is available at 
https://github.com/shade-econ/sequence-jacobian. This toolkit implements many of the techniques in the paper,
but does not itself replicate the results of the paper. One version of the toolkit is contained within this archive,
described below.

Overview
---------
- Jupyter notebooks that generate all figures and tables in the paper.  
  -`results.ipynb`: performs all computations and saves the results  
  -`figures_tables.ipynb`: creates figures and tables from saved results 
- **toolkit**: A copy of the `sequence-jacobian` toolkit that is used to compute many of our results.
- **models**: The particular models we use as illustrations.
- **import_export**: External data and supplementary results; comes with precomputed results. 
  - *autodiff*: notebooks that implement the Reiter method and compute Jacobians with automatic differentiation;
    the results of these computations  are also stored here  
  - *data*: datasets for estimation
  - *dynare*: Dynare code for representative agent models; results from Dynare are also stored here
  - *results*: stores the results from `results.ipynb`

Detailed Instructions
---------------------------
The primary language of the repository is Python.
Some supplementary results are obtained by MATLAB and Dynare, or by the automatic differentiation
package JAX.
All data are publicly available and included.

MATLAB is proprietary software and JAX is a Python package under active development that currently only
supports Linux (Ubuntu 16.04 or later) and macOS (10.12 or later) but not Windows. 
To make the replication material as accessible as possible, we provide two ways to run the code. 

### I. Using pre-computed supplementary materials
This approach requires only Python 3.8 or newer with standard packages listed in `requirements.txt`. Results of
supplementary MATLAB/Dynare and JAX-dependent Python code are loaded as data. 

1. Run `results.ipynb` in the parent folder to solve and estimate all models.
   - If you want to overwrite the pre-computed results in `import_export/results/`, set `save_data = True` 
     in the first cell.
   - Running the whole notebook can take up to 6-10 hours on a laptop. Almost all of this time is taken by 
     the Metropolis-Hastings algorithm applied to the two-asset HANK model (section 5).
   - The sections (numbered 1-7) are self-contained, any of them may be commented out.

2. Run `figures_tables.ipynb` in the parent folder to display all graphs and tables from the paper and appendices.
   - Loads data from `import_export/results/`: Figs 1-2, 5-7, F1-F10; Tables 1-3, C1-C3, F1-F4.
   - Loads data from `import_export/autodiff/`: Figs 4, D1-D2.
   - Loads data from `import_export/dynare/`: Figs E1-E2; Table F1.
   - The first cell uses LaTeX with `mathpazo` package to format the figures. If you don't have LaTeX installed, comment out the lines starting with `plt.rc`.   


### II. Computing supplementary materials
Generating supplementary materials from scratch requires MATLAB (~R2020a), Dynare (~4.6.4), and JAX (0.2.11).
The implementation of the Reiter method also uses `SolveQZ.py` written by Alisdair McKay, which we downloaded from
https://alisdairmckay.com/Notes/HetAgents/index.html and included in this replication archive.

1. Dynare results for Figs E1-E2 and Table F1.
    - Go to folder `import_export/dynare/`.
    - Run `sw_maincode.m` in folder `smets_wouters/`.
    - Run `hs_maincode.m` in folder `herbst-schorfheide/`.
    - In both cases, edit the addpath command in the first line to point to the location of Dynare on your computer.
    
2. Reiter method & computing Jacobians with automatic differentiation for figure 4 and tables D1-D2. 
    - Go to folder `import_export/autodiff/`.
    - Run `reiter.ks` to obtain impulse responses for the Krusell-Smith model from the Reiter method.
    - Run `reiter.hank1` to obtain impulse responses for the one-asset HANK model from the Reiter method.
    - Run `jax_accuracy_ks` to obtain the Jacobians of the heterogeneous household block in the Krusell-Smith model
      with three different differentiation methods.
    - Run `jax_accuracy_hank` to obtain the Jacobians of the heterogeneous household block in the one-asset HANK
      model with three different differentiation methods.
