Skip to content

Latest commit

 

History

History
48 lines (35 loc) · 6.24 KB

AGENTS.md

File metadata and controls

48 lines (35 loc) · 6.24 KB

WARNING: Do not modify this file.

  • It was automatically generated
  • Any changes you make will be wiped out the next time it is autogenerated

Project Context: Econ-ARK

This repository, HARK, is a component of the Econ-ARK project, an open-source platform for building and solving computational economic models. Understanding its role within the broader ecosystem is crucial for effective analysis.

Please consult these resources to understand the relationships between the different parts of the project.

1. Repository Purpose

HARK (Heterogeneous Agents Resources and toolKit) is the core library of the Econ-ARK project. Its primary purpose is to provide a powerful, open-source Python toolkit for economists and computational social scientists to build, solve, and simulate complex structural models of economic behavior. It specifically focuses on models with "heterogeneous agents"—individuals or firms that differ in characteristics like wealth, income, or preferences. The intended audience includes academic researchers, graduate students, and policy analysts who need to move beyond representative agent models to study economic questions related to inequality, risk, and aggregate dynamics.

2. Key Concepts and Abstractions

  1. AgentType and the Model Class Hierarchy: The central abstraction in HARK is the AgentType class (HARK/core.py), which represents a type of economic agent. These agents are endowed with a model that defines their economic problem. The model.py file defines a base Model class, and specific economic models (like those in HARK/ConsumptionSaving/) inherit from it. This object-oriented structure allows for modularity and extensibility, where complex models can be built by inheriting and modifying simpler ones.
  2. Consumption-Saving Problems: A core focus of HARK is solving life-cycle consumption-saving models. Classes like ConsIndShockModel (in HARK/ConsumptionSaving/ConsIndShockModel.py) implement the canonical model where agents face idiosyncratic income shocks and make optimal consumption choices. The framework provides tools to solve for the agent's decision rules (the "consumption function") and simulate their behavior over time.
  3. Discrete-Continuous Choice Modeling (DCEGM): For models involving both discrete choices (e.g., whether to work or retire) and continuous choices (e.g., how much to consume), HARK implements the Discrete-Continuous Endogenous Grid Method (DCEGM). The file HARK/dcegm.py contains the implementation of this advanced solution method, which is crucial for a class of modern economic models that are otherwise difficult to solve.
  4. Just-In-Time (JIT) Compilation for Performance: Many economic simulations are computationally intensive. HARK leverages the numba library to apply Just-In-Time (JIT) compilation to performance-critical functions, especially within solution and simulation loops. This allows for Python's high-level syntax while achieving speeds comparable to compiled languages like C or Fortran, which is essential for large-scale simulations.

3. Core Functionality & Key Files

  • HARK/core.py: This is the absolute core of the toolkit. It defines the AgentType class, which is the fundamental object for representing and simulating populations of economic agents. Understanding this class is the first step to understanding HARK's architecture.
  • HARK/model.py: This file contains the base Model class, which defines the structure of an economic problem that an AgentType will solve. It establishes the interface for how models are defined and solved.
  • HARK/ConsumptionSaving/: This directory contains the implementations of HARK's most well-developed economic models. Files like ConsIndShockModel.py (the canonical incomplete markets model) are essential starting points for understanding how specific economic theories are translated into code.
  • HARK/dcegm.py: Contains the implementation of the Discrete-Continuous Endogenous Grid Method (DCEGM), a powerful but complex solution method for models with both discrete and continuous choices. This is key for understanding how HARK handles more advanced problems.
  • examples/: This directory is the best entry point for new users. It contains a wealth of Jupyter notebooks that provide practical, step-by-step demonstrations of how to set up, solve, and analyze various models using the HARK toolkit.

4. AI Search and Analysis Strategy

  • Most Effective Entry Point: The most effective way to understand the repository is to start with the examples/ directory. Pick a fundamental notebook like examples/ConsIndShockModel/IndShockConsumerType.ipynb and trace the code from there. The notebooks provide context and demonstrate the intended use of the library's classes and functions, which is hard to grasp from the source code alone.
  • Common Pitfalls:
    • HARK vs. DemARK/REMARK: Be aware that HARK is the core library. Many extended examples and replications live in the separate DemARK and REMARK repositories. Users' questions might relate to code in those repositories, not just HARK.
    • Deep Inheritance Chains: The code makes extensive use of class inheritance. A method being called on an AgentType instance might be defined in a parent or grandparent class. It is crucial to trace the full Method Resolution Order (MRO) to find the source of a specific behavior.
    • Parameter Dictionaries: Models are configured using large Python dictionaries of parameters. It can be difficult to know which parameters are available or what they do without carefully inspecting the class's __init__ method and its parents.
  • Effective Search Terms:
    • To understand agent setup: "AgentType", "parameter_class", "self.parameters".
    • To understand model solutions: "solve", "solution", "vFunc", "cFunc".
    • To understand simulations: "simulate", "track_vars", "MonteCarlo".
    • For specific models: "ConsIndShockModel", "TractableBufferStockModel", "dcegm".