Implements solution methods for models with rich heterogeneity.

Normann Rionrequested to merge
normann/dynare:ha into master

This merge request introduces a comprehensive framework for solving, simulating, and documenting heterogeneous-agent models in Dynare. It implements a solution method and establishes a modular structure for heterogeneity support in both MATLAB and Fortran MEX components. It also replaces earlier ad hoc prototypes under hank/ with a unified, production-ready design under heterogeneity/. HANK models feature the type of heterogeneity we want to handle, but it's a bit too specific. What we really want to manage is heterogeneity, in the sense of a continuum of agents whose distribution matter to their individual choices with a dynamic interaction between both. Hence the choice of the keyword heterogeneity for all the related routines and folders.

Repository and Submodule

  • Updated .gitmodules to point the preprocessor submodule to normann/preprocessor.git, branch ha (heterogeneity-aware preprocessor), which contains 2 fixes:
    • Fix the writeSetAuxiliaryVariablesFile routine for mod files with an heterogeneous model block
    • Fix Jacobian column calculation for aggregate exogenous variables in the heterogeneous model block

I'll revert this change once a MR on the preprocessor has been merged. The latter will include the syntax changes discussed with the Dynare team.

Documentation

  • Expanded doc/manual/source/the-model-file.rst with a new dedicated section: “Heterogeneity” (.. _heterogeneity:). This section:

    • Introduces the conceptual framework and the syntax novelties.

    • Documents user-facing commands:

      • heterogeneity_initialize
      • heterogeneity_solve
      • heterogeneity_simulate

    • Explains their workflow and the connection to the steady-state distribution.

    • Describes current limitations.

New MATLAB Modules

A full suite of heterogeneous-agent routines was added under matlab/+heterogeneity/ and matlab/+heterogeneity/+internal/.

Top-level public functions:

  • initialize_steady_state.m – loads and validates steady-state .mat files.
  • solve.m – computes the linearized system.
  • simulate.m – performs IRF, stochastic, or deterministic-sequence simulations.
  • plot_simulation.m – optional visualization utility.
  • check_steady_state_input.m – input validation.

Internal helper functions (+internal/):

  • Numerical linear algebra utilities (pagemtimes, pagemldivide) to keep the code copmatible with OCTAVE, which does not feature those commands.
  • Jacobian builders (compute_state_jacobian, compute_shock_jacobian, compute_heterogeneous_jacobian).
  • Impulse-response computations (compute_impulse_responses).
  • Data preprocessing routines (build_Phi_tilde_e, compute_input, etc.).
  • Structural helpers for dr filling.
  • Low-level block processing (process_jacobian_block).

This provides a self-contained computational layer for the HANK module. I used the +internal namespace because OCTAVE does not handle well the private subfolders within a namespace (See the bug here).

Fortran MEX Layer

Added new MEX sources under mex/sources/heterogeneity/:

  • Core computational primitives for expectations, Markov transitions, and discretization:
    • utils/markov.f08, utils/gray_code.f08, utils/curlyDs.f08, utils/expectations.f08.
  • Specialized routines:
    • compute_transition_matrices/mexFunction.F08
    • compute_expected_y/mexFunction.F08
    • compute_expected_dx/mexFunction.F08
    • compute_curlyDs/mexFunction.F08
    • rouwenhorst/mexFunction.F08
  • Shared interpolation and bracket search utilities (hank/utils/interpolation.f08, etc.).
  • Updated MEX interface layer (matlab_mex.F08).

These provide the numerical backbone for the MATLAB layer, improving performance in high-dimensional settings. It shall be expanded further in later MRs.

Test Suite

Added an extensive set of tests under tests/heterogeneity/:

  • Functional and consistency tests:

    • test_initialize_steady_state.m
    • test_check_steady_state.m
    • test_field_validation.m
    • test_file_loading.m

  • Solver and simulation validation:

    • test_solve_functionality.m
    • test_solve_with_custom_impulse_responses.m
    • test_simulate_stochastic.m
    • test_simulate_deterministic.m
    • test_shock_methods.m

  • Utilities:

    • print_test_summary.m, run_test.m, and small .mod and .mat fixtures (Krusell–Smith, two-agent benchmarks).

All tests ensure compatibility of the new solver with Dynare’s structures (oo_, M_, options_). All standard Dynare tests pass on MATLAB R2024a and Octave 10.2 (with patched optim package). Confirmed IRF and stochastic modes produce consistent results with the SSJ suite.

Build System

  • Updated meson.build to integrate the new Fortran MEX targets under mex/sources/heterogeneity/ and mex/sources/hank/.
  • Amended the build system to handle environment variables with the -D option.

Default Options

  • Modified matlab/default_option_values.m to add default settings for heterogeneity-related options.

Design and Rationale

The architecture mirrors Dynare’s established workflow:

heterogeneity_initialize → heterogeneity_solve → heterogeneity_simulate
  • Internal MEX routines provide computational efficiency without modifying core solver routines.
  • Future extensions (nonlinear transitions, handling of initial state values, estimation) are already anticipated in design.
Edited by Normann Rion

Merge request reports