Implement IRA Consumer Model with early withdrawal penalties and dual savings accounts by Copilot · Pull Request #1588 · econ-ark/HARK

Copilot · 2025-07-30T22:35:28Z

This PR implements a comprehensive IRA Consumer Model that extends HARK's consumption-saving framework to handle retirement accounts with early withdrawal penalties. The implementation addresses all three requirements from the original issue:

New Features

Two Savings Accounts Model

Liquid Account: Traditional savings with full liquidity but lower returns
IRA Account: Higher returns but subject to early withdrawal penalties before retirement age
Agents optimally allocate savings between accounts based on effective returns

Kinked Interest Rates

Each account supports different borrowing vs saving rates:

Rfree_liquid_save / Rfree_liquid_boro: Liquid account rates for positive/negative balances
Rfree_IRA_save / Rfree_IRA_boro: IRA account rates (borrowing typically prohibited)

Early Withdrawal Penalties

Configurable penalty rate (e.g., 10%) for IRA withdrawals before retirement age
Age-dependent effective rates: effective_IRA_rate = base_rate * (1 - penalty) when young
Penalty automatically removed at retirement age (e.g., 65)

Implementation Details

Core Components

IRAConsumerType: Extends IndShockConsumerType with dual-account functionality
IRASolution: Extends ConsumerSolution with IRA-specific consumption functions
solve_ConsIRA(): Solver function implementing penalty-adjusted optimization
init_ira_accounts: Default parameter dictionary for easy setup

Economic Behavior

The model produces realistic life-cycle behavior:

# Young agents prefer liquid assets due to penalty costs
agent_young = IRAConsumerType(current_age=25, IRA_penalty_rate=0.10)

# Older agents shift toward IRA for higher returns
agent_older = IRAConsumerType(current_age=60, IRA_penalty_rate=0.10)

# Retired agents face no penalties
agent_retired = IRAConsumerType(current_age=70, retirement_age=65)

Usage Example

from HARK.ConsumptionSaving.ConsIRAModel import IRAConsumerType

# Create agent with IRA accounts
agent = IRAConsumerType(
    Rfree_liquid_save=1.03,    # 3% liquid savings rate
    Rfree_IRA_save=1.07,       # 7% IRA savings rate  
    IRA_penalty_rate=0.10,     # 10% early withdrawal penalty
    retirement_age=65,         # Penalty-free age
    AgentCount=10000
)

# Solve and simulate
agent.solve()
agent.initialize_sim()
agent.simulate()

# Analyze retirement savings behavior
consumption = agent.history['cNrm']
assets = agent.history['aNrm']

Testing and Validation

The implementation includes comprehensive testing:

Unit tests for all major components
Edge case validation (no penalty, same rates, retirement age scenarios)
Parameter bounds checking
Integration tests with existing HARK framework

All tests validate that the model:

Prefers higher-return accounts when penalties are low
Correctly applies age-based penalty logic
Handles kinked interest rate structures
Reduces to standard consumption models in limiting cases

Documentation

Complete documentation includes:

Mathematical framework description
Usage examples and tutorials
Parameter reference guide
Integration instructions with existing HARK models

The implementation follows established HARK patterns and integrates seamlessly with existing consumption-saving models while providing powerful new capabilities for retirement savings research.

Recent Updates

Synced with main branch and resolved merge conflict in HARK/ConsumptionSaving/__init__.py
Updated IRAConsumerType export to use main's new explicit __all__ export style
Fixed test compatibility with updated interpolation behavior (accepting np.ndarray return types)

Fixes #136.

Tests for new functionality/models or Tests to reproduce the bug-fix in code.
Updated documentation of features that add new functionality.
Update CHANGELOG.md with major/minor changes.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

…penalties Co-authored-by: alanlujan91 <5382704+alanlujan91@users.noreply.github.com>

Co-authored-by: alanlujan91 <5382704+alanlujan91@users.noreply.github.com>

mnwhite · 2025-07-30T23:14:57Z

I have a draft model for this that is mostly working. I just need to fix some behavior near the lower bound that's probably due to numeric error / clipping over the boundary.

alanlujan91 · 2025-12-02T03:05:42Z

@copilot sync with main and review your work

Co-authored-by: alanlujan91 <5382704+alanlujan91@users.noreply.github.com>

Copilot · 2025-12-02T03:14:00Z

@copilot sync with main and review your work

Synced with main in commit 7f93fbd. Resolved merge conflict in HARK/ConsumptionSaving/__init__.py by adopting main's new export style and adding IRAConsumerType. Fixed test compatibility with updated interpolation behavior. All 6 IRA model tests pass.

Copilot

Pull request overview

This PR aims to add an IRA dual-account consumer model (liquid + IRA) with kinked rates and early-withdrawal penalties, and it also includes a broad set of refactors/expansions across testing, distributions, estimation utilities, documentation, and CI workflows.

Changes:

Adds IRA model documentation/examples and introduces additional validation/testing scaffolding.
Expands and modernizes test coverage across multiple consumption-saving and distributions components.
Updates docs/CI tooling (coverage workflow, docs config, API reference indexing) and refactors several core utilities (distributions, estimation, simulator).

Reviewed changes

Copilot reviewed 82 out of 176 changed files in this pull request and generated 32 comments.

Show a summary per file

File	Description
tests/test_simulate.py	Adds simulator/SSJ/Markov test coverage (currently contains test-breaking typos).
HARK/Calibration/Income/IncomeTools.py	Changes `parse_income_spec` outputs (introduces a breaking key rename that likely disrupts downstream parameter wiring).
HARK/estimation.py	Refactors parallel Nelder-Mead behavior and I/O; contains an invalid clamp for `P` that can break optimization.
examples/SequenceSpaceJacobians/estimation/routines.py	Adds estimation utilities; `log_prior` has an incorrect Gamma case and a repeated-work loop.
HARK/distributions/multivariate.py	Refactors multivariate lognormal internals; current `_cdf` shape checks and `_pdf` computation are incorrect.
HARK/ConsumptionSaving/ConsLaborModel.py	Solver/plotting updates; introduces import-time matplotlib side effects.
docs/guides/quick_start.md	Adds `install_examples()` guidance; contains an incorrect example notebook path.
docs/conf.py	Updates docs theme/config and adds thumbnails; references missing static assets and lacks proper static-path configuration.
examples/ConsumptionSaving/example_ConsIRAModel.py	Adds an IRA usage example; currently hardcodes CI-only `sys.path`.
tests/ConsumptionSaving/validate_ConsIRAModel.py	Adds IRA edge-case validation script; currently hardcodes CI-only `sys.path` and isn’t structured as a test.

Comments suppressed due to low confidence (2)

docs/conf.py:116

html_css_files references override-nbsphinx-gallery.css, but there is no such file in the docs tree, and icon_links references _static/econ-ark-logo.png while the logo is currently under docs/images/. Add/restore html_static_path and ensure the referenced static assets are present under a configured static path (or update the paths to match the repository layout).
HARK/ConsumptionSaving/ConsPrefShockModel.py:1126
Base classes have conflicting values for attribute 'calc_bounding_values': Function calc_bounding_values and Function calc_bounding_values.
Base classes have conflicting values for attribute 'make_euler_error_func': Function make_euler_error_func and Function make_euler_error_func.

class KinkyPrefConsumerType(PrefShockConsumerType, KinkedRconsumerType):

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-28T19:23:08Z

tests/test_simulate.py

+        self.agent.track_vars = ["aNrm", "cNrm", "Mrkv"]
+        self.agent.initialize_sym()
+        self.agent.symulate()
+


AgentType appears to use simulate(), but this test calls symulate(), which will raise AttributeError and fail the test. Rename the call to simulate() (or the correct method name in the API).

Copilot · 2026-01-28T19:23:08Z

tests/test_simulate.py

+        self.agent.symulate()
+
+        Mrkv_hist = self.agent.hystory["Mrkv"]
+        for t in range(self.agent.T_sim):
+            self.assertTrue(np.all(Mrkv_hist[t, :] == Mrkv_hist[t, 0]))


This test references self.agent.hystory, but the simulation history attribute is typically history. As written, this will raise AttributeError and fail the test; update to the correct attribute name.

Copilot · 2026-01-28T19:23:09Z

HARK/Calibration/Income/IncomeTools.py

@@ -673,7 +674,8 @@ def parse_income_spec(

    P0 = P0 * defl
    income_params["P0"] = P0


parse_income_spec now writes pLogInitMean, but the rest of the codebase (and tests) uses pLvlInitMean for the mean of log initial permanent income. This will silently stop overriding pLvlInitMean in downstream parameter dicts. Preserve backward compatibility by continuing to set income_params["pLvlInitMean"] (and optionally also set/alias pLogInitMean).

Suggested change

income_params["P0"] = P0

income_params["P0"] = P0

income_params["pLvlInitMean"] = np.log(P0)

Copilot · 2026-01-28T19:23:09Z

tests/ConsumptionSaving/validate_ConsIRAModel.py

+import sys
+sys.path.insert(0, '/home/runner/work/HARK/HARK')
+


Avoid hardcoding CI-specific paths like /home/runner/work/HARK/HARK inside the test tree. If this is intended as a validation script, place it under examples/ or scripts/ and remove the sys.path.insert; if it is intended as a test, convert it into a real pytest/unittest test module and use standard imports.

Copilot · 2026-01-28T19:23:10Z

HARK/estimation.py

    # Make sure degree of parallelization is not illegal
    if P > N - 1:
-        print(
+        warnings.warn(
            "Requested degree of simplex parallelization is "
            + str(P)
            + ", but dimension of optimization problem is only "
            + str(N - 1)
            + ".",
        )
-        print("Degree of parallelization has been reduced to " + str(N - 1) + ".")
-        P = N - 1
+        warnings.warn(
+            "Degree of parallelization has been reduced to " + str(N - 1) + "."
+        )
+        P = N - 2



When P > N-1, this reduces P to N-2, which contradicts the warning message and can make P==0 for 1D problems (breaking the update loop). Set P to N-1 (or at least clamp to max(1, N-1)) and keep the warning text consistent with the actual value.

Copilot · 2026-01-28T19:23:16Z

HARK/rewards.py

-            return CRRAutility(c, self.CRRA)
+            try:
+                return CRRAutility(c, self.CRRA)
+            except:


Except block directly handles BaseException.

Copilot · 2026-01-28T19:23:16Z

HARK/rewards.py

-            return CRRAutilityP(c, self.CRRA)
+            try:
+                return CRRAutilityP(c, self.CRRA)
+            except:


Except block directly handles BaseException.

Copilot · 2026-01-28T19:23:17Z

HARK/rewards.py

-            return CRRAutilityPP(c, self.CRRA)
+            try:
+                return CRRAutilityPP(c, self.CRRA)
+            except:


Except block directly handles BaseException.

Copilot · 2026-01-28T19:23:17Z

HARK/ConsumptionSaving/ConsIRAModel.py

+        pass
+
+


Unnecessary 'pass' statement.

Suggested change

pass

Copilot · 2026-01-28T19:23:17Z

HARK/ConsumptionSaving/ConsRiskyContribModel.py

+        WithdrawTax = WithdrawTax[-1]
    else:
-        tau = tau
+        WithdrawTax = WithdrawTax


This assignment assigns a variable to itself.

Initial plan

544cec6

Copilot AI assigned Copilot and alanlujan91 Jul 30, 2025

Copilot started work on behalf of alanlujan91 July 30, 2025 22:35 View session

Copilot AI and others added 2 commits July 30, 2025 22:45

Implement IRA Consumer Model with dual accounts and early withdrawal …

bcd6c5b

…penalties Co-authored-by: alanlujan91 <5382704+alanlujan91@users.noreply.github.com>

Complete IRA Consumer Model with validation tests and documentation

abd68e5

Co-authored-by: alanlujan91 <5382704+alanlujan91@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] IRA accounts with early withdrawal penalties~~ Implement IRA Consumer Model with early withdrawal penalties and dual savings accounts Jul 30, 2025

Copilot AI requested a review from alanlujan91 July 30, 2025 22:49

Copilot finished work on behalf of alanlujan91 July 30, 2025 22:49

Copilot started work on behalf of alanlujan91 December 2, 2025 03:06 View session

Sync with main branch and fix IRA model tests for compatibility

7f93fbd

Co-authored-by: alanlujan91 <5382704+alanlujan91@users.noreply.github.com>

Copilot finished work on behalf of alanlujan91 December 2, 2025 03:15

mnwhite added this to Issues & PRs Jan 3, 2026

mnwhite moved this to In progress in Issues & PRs Jan 3, 2026

alanlujan91 requested a review from Copilot January 28, 2026 19:15

Copilot started reviewing on behalf of alanlujan91 January 28, 2026 19:15 View session

Copilot AI reviewed Jan 28, 2026

View reviewed changes

alanlujan91 mentioned this pull request Feb 27, 2026

Tax-Differentiated Account Model (401k/IRA/Roth/Taxable) #1731

Open

		@@ -673,7 +674,8 @@ def parse_income_spec(

		P0 = P0 * defl
		income_params["P0"] = P0

	income_params["P0"] = P0
	income_params["P0"] = P0
	income_params["pLvlInitMean"] = np.log(P0)

Uh oh!

Conversation

Copilot AI commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New Features

Two Savings Accounts Model

Kinked Interest Rates

Early Withdrawal Penalties

Implementation Details

Core Components

Economic Behavior

Usage Example

Testing and Validation

Documentation

Recent Updates

Uh oh!

mnwhite commented Jul 30, 2025

Uh oh!

alanlujan91 commented Dec 2, 2025

Uh oh!

Copilot AI commented Dec 2, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Jul 30, 2025 •

edited

Loading