BASEforHANK.jl Documentation

Introduction

This manual documents the Julia package BASEforHANK, which provides a toolbox for the Bayesian Solution and Estimation (BASE) of a heterogeneous-agent New-Keynesian (HANK) model.

It comes with examples that showcase how to use the package. Originally, the code accompanied the paper Bayer, Born, and Luetticke (2024, AER). Note that the toolbox is not a 1-for-1 replication package for the linked paper. In particular, the preset resolution is smaller.

First steps

Installation

We recommend to use Julia for VSCode IDE as a front-end to Julia. To get started with the toolbox, simply download or clone the folder, e.g. via git clone and set your cd to the project directory. Then start the Julia REPL and type ] so that you can call

(v1.12) pkg> activate .

(BASEtoolbox) pkg> instantiate

This will install all needed packages. For more on Julia environments, see Pkg.jl.

We have tested the module on Julia Version 1.12.2 (macOS: arm64-apple-darwin22.4.0, Windows: x86_64-w64-mingw32, Linux: x86_64-linux-gnu). You can find out which version you are using by calling versioninfo() in the Julia REPL.

If you use a different editor, make sure that the environment is correctly set, as otherwise the instantiated packages might not be found.

Toolbox folder structure

In the following, we call the root directory of the repository BASEtoolbox.jl (which is the directory containing, for instance, Project.toml). The folder structure is as follows:

src/: Contains the source code of the toolbox, that is:

• the main module file BASEforHANK.jl,
• the submodules in the folder SubModules/,
• and the pre-processing functions in the folder Preprocessor/.

examples/: Contains the examples that showcase the toolbox. For each example, there is a subfolder in examples/ that contains the main file to run the example as well as all relevant files for the example. The baseline example that showcases most functions of the toolbox is given by examples/baseline/main.jl. This is strictly required as it serves as the baseline for testing and documentation.

bld/: Contains the generated files (after generating them). The folder is not part of the repository, but is created when running (certain parts of) the toolbox. That is, the folder contains:

• the generated files from the examples as subfolders of bld/.

docs/: Contains the documentation of the toolbox, that is:

• the source code in src/,
• and the generated documentation in build/.

test/: Contains the tests for the toolbox.

Building the documentation

You can build the documentation locally by starting a new Julia REPL in the root directory of the repository, activating the environment, and running the following command: include("docs/make.jl"). You can access the documentation, once it is built locally, via running python3 -m http.server --directory docs/build/. If you then open your browser at http://localhost:8000, the documentation should render properly. Beyond that, the documentation is hosted via GitHub Pages and can be accessed here.

Getting started with your model

The backbone of the toolbox is a computation algorithm to efficiently solve one- or two-asset heterogeneous agent models. The household problem, including all notation, is described in detail in Household Problem. The algorithm is described in Computational Notes.

If you want to add a new model, the recommended way is to start by copying one of the provided examples into a new folder in examples/. This way, you can make sure that all necessary files are present and that the toolbox can be run without any issues.

We provide a detailed description of the user inputs in a typical example in General example structure. To decide which example is best suited as a starting point for your needs, you can look at the list of the provided examples in Examples.

Methods

The following gives an overview on the methods provided by the toolbox. They naturally build on each other. For a more detailed documentation of each method, including its main functions, see the respective section.

Preprocessing, parsing, and incomes

Preprocessing stitches the user-provided .mod files together with the template functions in src/Preprocessor/, checks that every declared variable has a matching equation, and creates the generated functions consumed by the solver. Parsing (see Example Structure) loads input_aggregate_names.jl, builds the type-safe index structs, and exposes convenience macros such as @make_struct, @writeXSS, and the household-problem argument helpers. The household inputs (input_compute_args_hh_prob_ss.jl) are turned into executable functions via IncomesETC so that the steady-state solver and perturbation code can always reconstruct wages, taxes, and transfers consistent with the aggregate model.

Steady state and preparing linearization

With model objects in place, compute_steadystate first solves the household problem (via EGM) to obtain the stationary distribution, marginal value functions, and aggregate quantities. It then calls prepare_linearization to build the state/control vectors, apply the first-stage DCT reduction, and assemble all bookkeeping structs (SteadyResults) required for perturbation, estimation, and model reduction. If you need to calibrate parameters before solving, run_calibration provides an automated moment-matching loop that repeatedly invokes the steady-state solver under user-specified targets.

Linearization and model reduction

linearize_full_model differentiates the implicit equilibrium system F(X_t, X_{t+1}) = 0, fills Jacobian blocks with known derivatives, and solves the generalized Schur system to deliver gx/hx along with the compressed LinearResults. Subsequent calls to model_reduction construct factor representations for copula/value-function coefficients, if needed, and update_model reuses the existing Jacobians to re-linearize after parameter updates without recomputing the entire household problem. The model reduction routines build on Bayer, Born, and Luetticke (2024). Models with one asset can also be solved up to second-order—the second-order solution and generalized impulse response functions are described in PerturbationSolution and PostEstimation—which builds on Bayer, Luetticke, Weiss, and Winkelmann (2025).

Estimation

The Estimation module wraps the linear solution in a state-space model, builds the observation selector H_sel, and runs the Kalman filter/smoother to evaluate the likelihood. find_mode locates the posterior mode under the supplied priors, and sample_posterior performs random-walk Metropolis–Hastings to explore the posterior. Alternative workflows, such as IRF Matching, reuse the same infrastructure but swap the objective from likelihood to IRF distance.

Plots and statistics

Post-estimation utilities (see Post Estimation) compute and visualize impulse responses, variance/historical decompositions, distributional IRFs, GIRFs, and unconditional moments. The plotting helpers (plot_irfs, plot_vardecomp, plot_hist_decomp, …) operate on the LinearResults/SteadyResults objects and can ingest posterior draws to attach credible intervals.

For hands-on examples of the full pipeline, consult the walkthroughs in docs/src/examples/ (baseline, simplified HANK, and two-sector variants), which mirror the corresponding folders under examples/ in the repository.